Merge pull request #3 from J0m1ty/dev-next

Simplify types, address bugs, and improve type safety

Author: J0m1ty

README.md

@@ -4,7 +4,7 @@
 [![Build Status](https://github.com/J0m1ty/ts-safe-union/workflows/CI/badge.svg)](https://github.com/J0m1ty/ts-safe-union/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A TypeScript utility for destructuring discriminated unions while maintaining type safety. This package is tiny (no dependencies) and is niche but simple to use and solves a common problem in Typescript. Broadly, this package helps with:
+A TypeScript utility for destructuring discriminated unions while maintaining type safety. This package is tiny (no dependencies) and solves a common problem in Typescript. Broadly, this package helps with:
 - Safely destructuring discriminated unions
 - Making switch/case statements exhaustive
 - Improving state management patterns
@@ -67,17 +67,9 @@ type RequestState = DiscriminatedUnion<
   }
 >;
 
-// Optional: Define common properties
-type RequestStateWithCommon = RequestState & {
-  id: string;
-  timestamp: number;
-};
-
-// Example implementation
+// Example request consumer
 const handleRequest = (request: RequestStateWithCommon) => {
-  const { status, id, timestamp, progress, data, error } = request;
-
-  console.log(`Processing request ${id} from ${timestamp}`);
+  const { status, progress, data, error } = request;
 
   if (status === "loading") {
     console.log(`Loading: ${progress}%`);
@@ -89,6 +81,23 @@ const handleRequest = (request: RequestStateWithCommon) => {
 };
 ```
 
+If you want to define your keys elsewhere, you can provide them to the Discriminated Union and the TS complier will give you errors if some variant are not supplied in the list. For example, the following example will have a type error because the error variant is not specified.
+
+```typescript
+import { DiscriminatedUnion } from "ts-safe-union";
+
+const statusKeys = ["loading", "success", "error"] as const;
+
+type RequestState = DiscriminatedUnion<
+  "status",
+  {
+    loading: { progress: number };
+    success: { data: unknown };
+  },
+  typeof statusKeys[number] // << error here
+>;
+```
+
 ### MergedUnion
 
 Use `MergedUnion` when you want to merge two existing object types into a single union while maintaining safe property access.
@@ -123,12 +132,11 @@ Check out the [examples directory](./examples) for simple but practical use case
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a PR. Make sure to:
+Contributions are welcome! Please feel free to submit a PR. If you feel comfortable, also:
 
 1. Add tests for any new features
 2. Update documentation if needed
-3. Follow the existing code style
-4. Ensure all tests pass by running `npm test`
+3. Ensure all tests pass by running `npm test`
 
 ## License
 

src/index.ts

@@ -4,97 +4,82 @@
  * @packageDocumentation
  */
 
-///////////// DISCRIMINATED UNION //////////////
-
 /**
- * Utility type that converts a union type to an intersection type.
- * @internal
+ * Extract all property keys that appear in any member of a union.
  */
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
-    k: infer I
-) => void
-    ? I
-    : never;
+type UnionKeys<U> = U extends any ? keyof U : never;
 
 /**
- * Utility type that tags a single state with a discriminator value.
- * @internal
+ * Build one member of the discriminated union.  The construction does three things:
+ *   1. Includes the original `Member` properties
+ *   2. Injects `{ [Discriminator]: TagName }` so the member is uniquely tagged
+ *   3. Adds any missing keys from `AllKeys` as optional   `?: undefined`
+ * 
+ * 
+ * @template TagName        literal tag that identifies this member (e.g. "circle")
+ * @template Member         object type supplied for this tag (e.g. { radius: number })
+ * @template Discriminator  key that stores the tag (e.g. "kind")
+ * @template AllKeys        union of keys across all members
  */
-type TaggedState<TDiscriminator extends string, K extends string, State> = {
-    [P in TDiscriminator]: K;
-} & State;
+type BuildMember<
+    TagName extends PropertyKey,
+    Member extends object,
+    Discriminator extends PropertyKey,
+    AllKeys extends PropertyKey
+> =
+    Member &
+    { [P in Discriminator]: TagName } &
+    { [P in Exclude<AllKeys, keyof Member>]?: undefined };
 
 /**
- * Utility type that produces a union of all tagged states from the given record.
- * @internal
- */
-type AllTaggedStates<
-    TDiscriminator extends string,
-    TStates extends Record<string, any>
+* Transform a map of variants into a clean discriminated union.
+* 
+* @example
+* ```ts
+* type RequestState = DiscriminatedUnion<
+*   "status",
+*   {
+*     loading: { progress: number };
+*     success: { data: unknown };
+*     error: { error: Error };
+*   }
+* >;
+* ```
+*/
+export type DiscriminatedUnion<
+    Discriminator extends PropertyKey,
+    Variants extends Record<PropertyKey, object>,
+    Tags extends keyof Variants = keyof Variants
 > = {
-    [K in keyof TStates]: TaggedState<TDiscriminator, K & string, TStates[K]>;
-}[keyof TStates];
+    [Tag in Tags]:
+    BuildMember<
+        Tag & string,
+        Variants[Tag],
+        Discriminator,
+        UnionKeys<Variants[Tags]>
+    >
+}[Tags];
 
 /**
- * Utility type that extracts common property keys from all states.
- * @internal
+ * Cleanly expands union types into a single object type.
  */
-type SharedProperties<TStates extends Record<string, any>> = {
-    [K in keyof UnionToIntersection<TStates[keyof TStates]>]?: unknown;
-};
+type Expand<T> = { [K in keyof T]: T[K]; }
 
 /**
- * Creates a safely destructurable discriminated union type that maintains type safety.
- *
- * @template TDiscriminator - The string literal type that will be used as the discriminator property name
- * @template TStates - An object type mapping discriminator values to their respective property types
+ * Merge two object types so that properties present in both objects become a union of their types and properties exclusive to one side are kept optional.
  *
  * @example
- * type RequestState = SafeUnion<"status", {
- *   loading: { progress: number };     // Will have status: "loading"
- *   success: { data: unknown };        // Will have status: "success"
- *   error: { error: Error };          // Will have status: "error"
- * }>;
- */
-export type DiscriminatedUnion<
-    TDiscriminator extends string,
-    TStates extends Record<string, any>
-> = AllTaggedStates<TDiscriminator, TStates> & SharedProperties<TStates>;
-
-///////////// MERGE UNION //////////////
-
-/**
- * Utility type to merge the value for a single property key from T and U.
- * @internal
- */
-type MergePropertyValue<
-    T extends object,
-    U extends object,
-    K extends PropertyKey
-> = K extends keyof T
-    ? K extends keyof U
-        ? T[K] | U[K] // if both T and U have the key K, merge their values
-        : T[K] | unknown // if only T has the key K, make it possibly unknown
-    : K extends keyof U
-    ? U[K] | unknown // if only U has the key K, make it possibly unknown
-    : never;
-
-/**
- * Constructs an object type that includes all keys from T and U,
- * merging the property types using MergePropertyValue.
- * @internal
- */
-type MergedProperties<T extends object, U extends object> = {
-    [K in keyof T | keyof U]?: MergePropertyValue<T, U, K>;
-};
-
-/**
- * Merges two object types T and U into a single type that includes all properties from both,
- * with overlapping properties merged into a union type.
- * @internal
+ * ```ts
+ * type A = { id: string; name: string };
+ * type B = { id: number; age: number };
+ *
+ * type AB = MergedUnion<A, B>;
  */
-export type MergedUnion<T extends object, U extends object> = MergedProperties<
-    T,
-    U
-> &
-    (T | U);
+export type MergedUnion<
+    First extends object,
+    Second extends object
+> = Expand<
+    { [K in Extract<keyof First, keyof Second>]: First[K] | Second[K] } &
+    { [K in Exclude<keyof First, keyof Second>]?: First[K] } &
+    { [K in Exclude<keyof Second, keyof First>]?: Second[K] }
+>;