hanzio 2.1.0 → 3.0.0

package/src/typedswitch/README.md

@@ -0,0 +1,335 @@
+# typedswitch
+
+A type-safe, exhaustive switch expression for TypeScript. Handle discriminated unions and string literals with full type inference, compile-time exhaustiveness checking, and async support.
+
+## Installation
+
+```bash
+npm install typedswitch
+```
+
+```bash
+pnpm add typedswitch
+```
+
+```bash
+bun add typedswitch
+```
+
+## Features
+
+- **Full type inference** — Return types are automatically inferred from your handlers
+- **Exhaustiveness checking** — TypeScript ensures all cases are handled at compile time
+- **Discriminated union support** — Works with any discriminant key, not just `type`
+- **Async-aware** — Async handlers preserve their `Promise` return type
+- **Grouped cases** — Share one handler between several values, fully typed
+- **Default handlers** — Handle remaining cases with a fallback
+- **Typo-proof cases** — A case key that isn't a value of the union is a compile error
+- **`assertNever`** — Exhaustiveness checking for regular `switch` statements
+
+## Usage
+
+### Plain Value Input
+
+Switch on a string, number, boolean or enum value directly:
+
+```typescript
+import { typedSwitch } from 'typedswitch'
+
+type Status = 'success' | 'error' | 'pending'
+
+const status: Status = 'success'
+
+// All cases required — TypeScript enforces exhaustiveness
+const message = typedSwitch(status, {
+  success: () => 'Operation completed!',
+  error: () => 'Something went wrong',
+  pending: () => 'Please wait...',
+})
+// message: string
+```
+
+Each handler receives the narrowed value:
+
+```typescript
+const result = typedSwitch(status, {
+  success: (val) => val.toUpperCase(), // val: 'success'
+  error: (val) => val.toUpperCase(),   // val: 'error'
+  pending: (val) => val.toUpperCase(), // val: 'pending'
+})
+```
+
+Numbers and booleans are keyed by `String(value)`, and each handler still
+receives the typed value:
+
+```typescript
+typedSwitch(code, {
+  200: (c) => 'ok',            // c: 200
+  404: (c) => `missing ${c}`,  // c: 404
+})
+
+typedSwitch(enabled, {
+  true: () => 'on',
+  false: () => 'off',
+})
+```
+
+### Discriminated Union Input
+
+Switch on objects with a string, number, or boolean discriminant property (like `type`, `kind`, `status`, etc.):
+
+```typescript
+type Event =
+  | { type: 'click'; x: number; y: number }
+  | { type: 'scroll'; offset: number }
+  | { type: 'keypress'; key: string }
+
+const event: Event = { type: 'click', x: 100, y: 200 }
+
+// Specify the discriminant key as the second argument
+const description = typedSwitch(event, 'type', {
+  click: (e) => `Clicked at (${e.x}, ${e.y})`,   // e: { type: 'click'; x: number; y: number }
+  scroll: (e) => `Scrolled ${e.offset}px`,       // e: { type: 'scroll'; offset: number }
+  keypress: (e) => `Pressed ${e.key}`,           // e: { type: 'keypress'; key: string }
+})
+// description: string
+```
+
+Works with any discriminant key:
+
+```typescript
+type Order =
+  | { status: 'pending'; createdAt: Date }
+  | { status: 'completed'; completedAt: Date }
+  | { status: 'cancelled'; reason: string }
+
+const order: Order = { status: 'completed', completedAt: new Date() }
+
+const info = typedSwitch(order, 'status', {
+  pending: (o) => `Created: ${o.createdAt}`,
+  completed: (o) => `Done: ${o.completedAt}`,
+  cancelled: (o) => `Cancelled: ${o.reason}`,
+})
+```
+
+Number and boolean discriminants work too. Cases are keyed by `String(value)`:
+
+```typescript
+type Response =
+  | { code: 200; body: string }
+  | { code: 404; path: string }
+
+typedSwitch(response, 'code', {
+  200: (r) => r.body,              // r: { code: 200; body: string }
+  404: (r) => `Missing ${r.path}`, // r: { code: 404; path: string }
+})
+
+type Result = { ok: true; value: number } | { ok: false; error: string }
+
+typedSwitch(result, 'ok', {
+  true: (r) => r.value,
+  false: (r) => r.error,
+})
+```
+
+### Grouped Cases
+
+Spread `typedSwitchGroup` into the cases to share one handler between several
+values. Pass the switched value (and key) so the types are inferred. The
+handler receives the union of the grouped members, and exhaustiveness checking,
+default handlers and return type inference keep working:
+
+```typescript
+import { typedSwitch, typedSwitchGroup } from 'typedswitch'
+
+const description = typedSwitch(event, 'type', {
+  ...typedSwitchGroup(event, 'type', ['click', 'scroll'], (e) => e.type), // e: click or scroll event
+  keypress: (e) => `Pressed ${e.key}`,
+})
+
+const message = typedSwitch(status, {
+  ...typedSwitchGroup(status, ['error', 'cancelled'], (s) => `Stopped: ${s}`), // s: 'error' | 'cancelled'
+  success: () => 'Done!',
+  pending: () => 'Please wait...',
+})
+```
+
+Group keys must be values of the discriminant. A case written after the spread
+replaces the grouped handler for that key; writing it before the spread is a
+type error. If two groups list the same key, the later group wins.
+
+### Default Handler
+
+Handle a subset of cases and catch the rest with a default handler:
+
+```typescript
+type Status = 'success' | 'error' | 'pending' | 'cancelled'
+
+const status: Status = 'cancelled'
+
+// Only handle specific cases, default handles the rest
+const message = typedSwitch(
+  status,
+  {
+    success: () => 'Done!',
+    error: () => 'Failed!',
+  },
+  (val) => `Unhandled status: ${val}`  // val: 'pending' | 'cancelled' (unhandled cases only)
+)
+// message: string
+```
+
+Only required, defined handlers narrow the default handler's input. Optional
+handlers (including reusable `PartialStringSwitchCases` and
+`PartialObjectSwitchCases` maps) can be absent, so their cases remain in the
+default handler's input type.
+
+Works with discriminated unions too:
+
+```typescript
+const description = typedSwitch(
+  event,
+  'type',
+  {
+    click: (e) => `Clicked at (${e.x}, ${e.y})`,
+  },
+  (e) => `Unhandled event: ${e.type}`  // e: scroll or keypress event (unhandled members only)
+)
+```
+
+### Async Handlers
+
+Mix sync and async handlers freely. `typedSwitch` returns the selected handler's value directly, so async branches preserve their `Promise` return type while sync branches remain sync:
+
+```typescript
+// All sync — returns string
+const syncResult = typedSwitch(status, {
+  success: () => 'ok',
+  error: () => 'err',
+  pending: () => 'wait',
+})
+// syncResult: string
+
+// All async — returns Promise<string>
+const asyncResult = typedSwitch(status, {
+  success: async () => {
+    const data = await fetchData()
+    return data.message
+  },
+  error: async () => 'err',
+  pending: async () => 'wait',
+})
+// asyncResult: Promise<string>
+
+const message = await asyncResult
+
+// Mixed sync/async — returns string | Promise<string>
+const mixedResult = typedSwitch(status, {
+  success: () => 'ok',
+  error: async () => 'err',
+  pending: () => 'wait',
+})
+```
+
+### Return Type Inference
+
+Return types are inferred from all handlers as a union:
+
+```typescript
+const result = typedSwitch(status, {
+  success: () => ({ ok: true, data: 'hello' }),
+  error: () => ({ ok: false, code: 500 }),
+  pending: () => null,
+})
+// result: { ok: true; data: string } | { ok: false; code: number } | null
+```
+
+### Enforcing a Return Type
+
+Annotate the result. Every handler's return type must fit, and exhaustiveness
+checking still applies:
+
+```typescript
+interface HasId {
+  id: string
+}
+
+const result: HasId = typedSwitch(status, {
+  success: () => ({ id: '123', name: 'John' }),
+  error: () => ({ id: '456', code: 500 }),
+  pending: () => ({ id: '789' }),
+})
+```
+
+## Error Handling
+
+When a case is unhandled at runtime (e.g., due to unsafe casts), `typedSwitch` throws a descriptive error:
+
+```typescript
+const status = 'unknown' as Status
+
+typedSwitch(status, {
+  success: () => 'ok',
+  error: () => 'err',
+})
+// Throws: "Unhandled case: unknown. Available cases: success, error"
+```
+
+For discriminated unions:
+
+```typescript
+// Throws: "Unhandled case: unknown (discriminant key: "type"). Available cases: click, scroll, keypress"
+```
+
+Object discriminants must be strings, numbers, or booleans. Missing or other discriminant values throw a runtime error if they reach `typedSwitch`.
+
+## `assertNever`
+
+For regular `switch` statements, put `assertNever` in the `default` branch. It fails to compile if a case is missing, and throws at runtime if an unexpected value gets through:
+
+```typescript
+import { assertNever } from 'typedswitch'
+
+function label(status: Status) {
+  switch (status) {
+    case 'success': return 'Done'
+    case 'error': return 'Failed'
+    case 'pending': return 'Waiting'
+    default: return assertNever(status) // compile error if a case is missing
+  }
+}
+```
+
+## API Reference
+
+### `typedSwitch(value, cases)`
+
+Switch on a string, number or boolean value with exhaustive case handling.
+
+### `typedSwitch(value, cases, defaultHandler)`
+
+Switch on a string, number or boolean value with partial cases and a default fallback.
+
+### `typedSwitch(object, key, cases)`
+
+Switch on a discriminated union using the specified discriminant key (string, number, or boolean values).
+
+### `typedSwitch(object, key, cases, defaultHandler)`
+
+Switch on a discriminated union with partial cases and a default fallback.
+
+### `typedSwitchGroup(value, keys, handler)` / `typedSwitchGroup(object, key, keys, handler)`
+
+Returns cases that all call `handler`, for spreading into `typedSwitch` cases.
+
+### `assertNever(value, message?)`
+
+Takes a `never` value and always throws (`Unexpected value: ${value}` or `message`). Use it for exhaustive `switch` statements.
+
+### Exported Helper Types
+
+`StringSwitchCases`, `PartialStringSwitchCases`, `ObjectSwitchCases`, and `PartialObjectSwitchCases` are exported for users who want to annotate reusable case maps.
+
+## License
+
+MIT

package/src/typedswitch/index.ts

@@ -3,7 +3,8 @@
  *
  * Supports two input modes:
  *
- * 1. STRING INPUT - switch on a string/enum value directly:
+ * 1. PLAIN VALUE INPUT - switch on a string, number or boolean value directly.
+ *    Cases are keyed by `String(value)`:
  *
  *    @example
  *    const status: 'success' | 'error' = 'success'
@@ -19,6 +20,9 @@
  *      success: (val) => 'handled success',
  *    }, (val) => 'default handler')
  *
+ *    typedSwitch(code, { 200: (c) => 'ok', 404: (c) => 'missing' }) // c: 200, 404
+ *    typedSwitch(flag, { true: () => 'on', false: () => 'off' })
+ *
  *
  * 2. OBJECT INPUT - switch on a discriminated union with custom key:
  *
@@ -46,20 +50,27 @@
  *    })
  *
  *
- * 3. WITH CONSTRAINT - use `typedSwitch<T>` to enforce return type:
+ * 3. GROUPED CASES - share one handler between several values with
+ *    `typedSwitchGroup`. The handler receives the union of the grouped
+ *    members, and the spread keeps exhaustiveness and return type inference:
  *
  *    @example
- *    interface HasId { id: string }
+ *    typedSwitch(event, 'type', {
+ *      ...typedSwitchGroup(event, 'type', ['click', 'scroll'], (e) => e.type), // e: ClickEvent | ScrollEvent
+ *      key: (e) => e.key,
+ *    })
  *
- *    // All handlers must return something with { id: string }
- *    typedSwitch<HasId>(status, {
- *      success: () => ({ id: '123', name: 'John' }), // ✓ OK
- *      error: () => ({ id: '456' }), // ✓ OK
+ *    typedSwitch(status, {
+ *      ...typedSwitchGroup(status, ['success', 'pending'], (s) => 'fine'), // s: 'success' | 'pending'
+ *      error: () => 'failed',
  *    })
  *
- *    // Type error - missing 'id' property
- *    typedSwitch<HasId>(status, {
- *      success: () => ({ name: 'John' }), // ✗ Error!
+ *
+ * 4. ENFORCING A RETURN TYPE - annotate the result:
+ *
+ *    @example
+ *    const result: { id: string } = typedSwitch(status, {
+ *      success: () => ({ id: '123' }),
  *      error: () => ({ id: '456' }),
  *    })
  */
@@ -145,6 +156,16 @@ export type PartialObjectSwitchCases<
 	R
 > = T[K] extends Discriminant ? PartialObjectCases<T, K, R | Promise<R>> : never
 
+/**
+ * Rejects case keys that are not values of the switched union, so a typo
+ * fails to compile instead of silently falling through to the default.
+ */
+type NoUnknownCases<Cases, Allowed extends string> = {
+	[P in keyof Cases as `${P & (string | number)}` extends Allowed
+		? never
+		: P]: never
+}
+
 type Handler = (value: unknown) => unknown
 type CasesRecord = Record<string, Handler | undefined>
 
@@ -152,18 +173,25 @@ type CasesRecord = Record<string, Handler | undefined>
 // Function overloads
 // ═══════════════════════════════════════════════════════════════════════════
 
-// String input - all cases required (no default)
+// Plain value input - all cases required (no default)
 export function typedSwitch<
-	T extends string,
-	Cases extends { [K in T]: (value: K) => unknown }
+	T extends Discriminant,
+	Cases extends { [V in T as `${V}`]: (value: V) => unknown } & NoUnknownCases<
+		Cases,
+		`${T}`
+	>
 >(value: T, cases: Cases): RawCasesReturnType<Cases>
 
-// String input - partial cases allowed (with default)
+// Plain value input - partial cases allowed (with default)
 // The default handler only receives the cases not covered by `cases`.
 export function typedSwitch<
-	T extends string,
-	Cases extends { [K in T]?: (value: K) => unknown },
-	DefaultCase extends (value: Exclude<T, HandledCaseKeys<Cases>>) => unknown
+	T extends Discriminant,
+	Cases extends {
+		[V in T as `${V}`]?: (value: V) => unknown
+	} & NoUnknownCases<Cases, `${T}`>,
+	DefaultCase extends (
+		value: Exclude<T, ValuesForKeys<T, HandledCaseKeys<Cases>>>
+	) => unknown
 >(
 	value: T,
 	cases: Cases,
@@ -174,7 +202,8 @@ export function typedSwitch<
 export function typedSwitch<
 	T extends object,
 	K extends keyof T,
-	Cases extends ObjectCases<T, K, unknown>
+	Cases extends ObjectCases<T, K, unknown> &
+		NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>
 >(value: T, key: K, cases: Cases): RawCasesReturnType<Cases>
 
 // Object input with key - partial cases allowed (with default)
@@ -182,7 +211,8 @@ export function typedSwitch<
 export function typedSwitch<
 	T extends object,
 	K extends keyof T,
-	Cases extends PartialObjectCases<T, K, unknown>,
+	Cases extends PartialObjectCases<T, K, unknown> &
+		NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>,
 	DefaultCase extends (
 		value: Exclude<T, Record<K, ValuesForKeys<T[K], HandledCaseKeys<Cases>>>>
 	) => unknown
@@ -193,69 +223,9 @@ export function typedSwitch<
 	defaultCase: DefaultCase
 ): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>
 
-// String input - all cases required with return constraint (no default)
-export function typedSwitch<Constraint, T extends string = string>(
-	value: T,
-	cases: { [K in T]: (value: K) => Constraint }
-): Constraint
-export function typedSwitch<Constraint, T extends string = string>(
-	value: T,
-	cases: { [K in T]: (value: K) => Constraint | Promise<Constraint> }
-): Constraint | Promise<Constraint>
-
-// String input - partial cases allowed with return constraint (with default)
-export function typedSwitch<Constraint, T extends string = string>(
-	value: T,
-	cases: { [K in T]?: (value: K) => Constraint },
-	defaultCase: (value: T) => Constraint
-): Constraint
-export function typedSwitch<Constraint, T extends string = string>(
-	value: T,
-	cases: { [K in T]?: (value: K) => Constraint | Promise<Constraint> },
-	defaultCase: (value: T) => Constraint | Promise<Constraint>
-): Constraint | Promise<Constraint>
-
-// Object input with key - all cases required with return constraint (no default)
-export function typedSwitch<
-	Constraint,
-	T extends Record<string, unknown> = Record<string, unknown>,
-	K extends keyof T = keyof T
->(value: T, key: K, cases: ObjectCases<T, K, Constraint>): Constraint
-export function typedSwitch<
-	Constraint,
-	T extends Record<string, unknown> = Record<string, unknown>,
-	K extends keyof T = keyof T
->(
-	value: T,
-	key: K,
-	cases: ObjectCases<T, K, Constraint | Promise<Constraint>>
-): Constraint | Promise<Constraint>
-
-// Object input with key - partial cases allowed with return constraint (with default)
-export function typedSwitch<
-	Constraint,
-	T extends Record<string, unknown> = Record<string, unknown>,
-	K extends keyof T = keyof T
->(
-	value: T,
-	key: K,
-	cases: PartialObjectCases<T, K, Constraint>,
-	defaultCase: (value: T) => Constraint
-): Constraint
-export function typedSwitch<
-	Constraint,
-	T extends Record<string, unknown> = Record<string, unknown>,
-	K extends keyof T = keyof T
->(
-	value: T,
-	key: K,
-	cases: PartialObjectCases<T, K, Constraint | Promise<Constraint>>,
-	defaultCase: (value: T) => Constraint | Promise<Constraint>
-): Constraint | Promise<Constraint>
-
 // Implementation
 export function typedSwitch(
-	value: string | object,
+	value: Discriminant | object,
 	keyOrCases: string | CasesRecord,
 	casesOrDefault?: CasesRecord | Handler,
 	defaultCase?: Handler
@@ -265,9 +235,9 @@ export function typedSwitch(
 	let defaultHandler: Handler | undefined
 	let discriminantKey: string | undefined
 
-	if (typeof value === 'string') {
-		// String input: typedSwitch(string, cases, default?)
-		key = value
+	if (typeof value !== 'object') {
+		// Plain value input: typedSwitch(value, cases, default?)
+		key = String(value)
 		cases = keyOrCases as CasesRecord
 		defaultHandler = casesOrDefault as Handler | undefined
 	} else {
@@ -323,6 +293,50 @@ export function typedSwitch(
 	)
 }
 
+/**
+ * Builds cases that share one handler, for spreading into `typedSwitch` cases.
+ * Pass the switched value so its type is inferred; the handler receives the
+ * union of the grouped members. A case listed after the spread replaces the
+ * grouped handler for that key; listing it before the spread is a type error.
+ * If two groups list the same key, the later group wins.
+ *
+ * @example
+ * typedSwitch(event, 'type', {
+ *   ...typedSwitchGroup(event, 'type', ['click', 'scroll'], (e) => e.type),
+ *   key: (e) => e.key,
+ * })
+ */
+export function typedSwitchGroup<
+	T extends Discriminant,
+	const Keys extends readonly T[],
+	R
+>(
+	value: T,
+	keys: Keys,
+	handler: (value: Keys[number]) => R
+): { [V in Keys[number] as `${V}`]: (value: V) => R }
+export function typedSwitchGroup<
+	T extends object,
+	K extends keyof T,
+	const Keys extends readonly Extract<T[K], Discriminant>[],
+	R
+>(
+	value: T,
+	key: K,
+	keys: Keys,
+	handler: (value: Extract<T, Record<K, Keys[number]>>) => R
+): { [V in Keys[number] as `${V}`]: (value: Extract<T, Record<K, V>>) => R }
+export function typedSwitchGroup(
+	_value: unknown,
+	keyOrKeys: unknown,
+	keysOrHandler: unknown,
+	handler?: Handler
+): CasesRecord {
+	const keys = (handler ? keysOrHandler : keyOrKeys) as Discriminant[]
+	const shared = handler ?? (keysOrHandler as Handler)
+	return Object.fromEntries(keys.map((key) => [String(key), shared]))
+}
+
 /**
  * Exhaustiveness helper for regular `switch` statements. Place it in the
  * `default` branch: it only type-checks when every case has been handled, and