hanzio 2.2.0 → 3.0.0

package/README.md

@@ -52,6 +52,15 @@ subpath export:
 `scripts/verify-exports.mjs` imports every entry above from the packed tarball
 in CI, so this table and `package.json#exports` can't drift apart.
 
+## Migrating to 3.0
+
+- `typedSwitch<Constraint>(…)` is removed. The explicit type argument switched
+  off inference, so those calls checked neither exhaustiveness nor, in object
+  mode, the return type. Annotate the result instead:
+  `const result: HasId = typedSwitch(status, { … })`.
+- `typedSwitch` rejects case keys that aren't values of the switched union. A
+  typo used to compile and fall through to the default handler.
+
 ## Migrating to 2.0
 
 - Subpath-only modules are no longer re-exported from `hanzio`. Change
@@ -479,12 +488,13 @@ Validators run in order: `globalValidator`, `validators[toState]`, then
 
 ### typedSwitch
 
-`typedSwitch` is an exhaustive switch helper for string unions and discriminated
-unions (string, number or boolean discriminants). `assertNever` covers regular
-`switch` statements. See the [typedSwitch docs](src/typedswitch/README.md).
+`typedSwitch` is an exhaustive switch helper for string, number and boolean
+values and for discriminated unions. `typedSwitchGroup` lets several cases share
+one handler. `assertNever` covers regular `switch` statements. See the
+[typedSwitch docs](src/typedswitch/README.md).
 
 ```ts
-import { assertNever, typedSwitch } from 'hanzio'
+import { assertNever, typedSwitch, typedSwitchGroup } from 'hanzio'
 
 type Event =
 	| { type: 'click'; x: number; y: number }
@@ -501,6 +511,11 @@ const text = typedSwitch(response as Response, 'code', {
 	404: () => 'Not found'
 })
 
+const event = { type: 'scroll', offset: 4 } as Event
+typedSwitch(event, 'type', {
+	...typedSwitchGroup(event, 'type', ['click', 'scroll'], (e) => e.type)
+})
+
 function area(shape: Shape) {
 	switch (shape.kind) {
 		case 'circle':

package/dist/src/index.js

@@ -90,8 +90,8 @@ function typedSwitch(value, keyOrCases, casesOrDefault, defaultCase) {
   let cases;
   let defaultHandler;
   let discriminantKey;
-  if (typeof value === "string") {
-    key = value;
+  if (typeof value !== "object") {
+    key = String(value);
     cases = keyOrCases;
     defaultHandler = casesOrDefault;
   } else {
@@ -119,6 +119,11 @@ function typedSwitch(value, keyOrCases, casesOrDefault, defaultCase) {
   const contextSuffix = discriminantKey ? ` (discriminant key: "${discriminantKey}")` : "";
   throw new Error(`Unhandled case: ${key}${contextSuffix}.${availableCasesSuffix}`);
 }
+function typedSwitchGroup(_value, keyOrKeys, keysOrHandler, handler) {
+  const keys = handler ? keysOrHandler : keyOrKeys;
+  const shared = handler ?? keysOrHandler;
+  return Object.fromEntries(keys.map((key) => [String(key), shared]));
+}
 function assertNever(value, message) {
   throw new Error(message ?? `Unexpected value: ${String(value)}`);
 }
@@ -1093,6 +1098,7 @@ export {
   typedFromEntries,
   typedKeys,
   typedSwitch,
+  typedSwitchGroup,
   unwrapResult2 as unwrapResult,
   withAlpha,
   withTimeout2 as withTimeout

package/dist/typedswitch/index.d.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' }),
  *    })
  */
@@ -95,30 +106,40 @@ type PartialObjectCases<T, K extends keyof T, R> = {
 export type ObjectSwitchCases<T, K extends keyof T, R> = T[K] extends Discriminant ? ObjectCases<T, K, R | Promise<R>> : never;
 /** Partial cases for object input with custom key (when default is provided) */
 export type PartialObjectSwitchCases<T, K extends keyof T, R> = T[K] extends Discriminant ? PartialObjectCases<T, K, R | Promise<R>> : never;
-export declare function typedSwitch<T extends string, Cases extends {
-    [K in T]: (value: K) => unknown;
-}>(value: T, cases: Cases): RawCasesReturnType<Cases>;
-export declare function typedSwitch<T extends string, Cases extends {
-    [K in T]?: (value: K) => unknown;
-}, DefaultCase extends (value: Exclude<T, HandledCaseKeys<Cases>>) => unknown>(value: T, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
-export declare function typedSwitch<T extends object, K extends keyof T, Cases extends ObjectCases<T, K, unknown>>(value: T, key: K, cases: Cases): RawCasesReturnType<Cases>;
-export declare function typedSwitch<T extends object, K extends keyof T, Cases extends PartialObjectCases<T, K, unknown>, DefaultCase extends (value: Exclude<T, Record<K, ValuesForKeys<T[K], HandledCaseKeys<Cases>>>>) => unknown>(value: T, key: K, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
-export declare function typedSwitch<Constraint, T extends string = string>(value: T, cases: {
-    [K in T]: (value: K) => Constraint;
-}): Constraint;
-export declare function typedSwitch<Constraint, T extends string = string>(value: T, cases: {
-    [K in T]: (value: K) => Constraint | Promise<Constraint>;
-}): Constraint | Promise<Constraint>;
-export declare function typedSwitch<Constraint, T extends string = string>(value: T, cases: {
-    [K in T]?: (value: K) => Constraint;
-}, defaultCase: (value: T) => Constraint): Constraint;
-export declare 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>;
-export declare 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 declare 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>;
-export declare 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 declare 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>;
+/**
+ * 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;
+};
+export declare function typedSwitch<T extends Discriminant, Cases extends {
+    [V in T as `${V}`]: (value: V) => unknown;
+} & NoUnknownCases<Cases, `${T}`>>(value: T, cases: Cases): RawCasesReturnType<Cases>;
+export declare function typedSwitch<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, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
+export declare function typedSwitch<T extends object, K extends keyof T, Cases extends ObjectCases<T, K, unknown> & NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>>(value: T, key: K, cases: Cases): RawCasesReturnType<Cases>;
+export declare function typedSwitch<T extends object, K extends keyof T, 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>(value: T, key: K, cases: Cases, defaultCase: DefaultCase): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>;
+/**
+ * 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 declare 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 declare 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;
+};
 /**
  * Exhaustiveness helper for regular `switch` statements. Place it in the
  * `default` branch: it only type-checks when every case has been handled, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzio",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -26,6 +26,7 @@
   "files": [
     "src/**/*.ts",
     "src/**/README.md",
+    "src/api-wrapper/SKILL.md",
     "dist",
     "!src/**/*.test.ts"
   ],

package/src/api-wrapper/README.md

@@ -3,8 +3,11 @@
 Typed HTTP clients from Zod schemas: `createApiClient` validates requests and
 responses, retries with exponential backoff, and throws structured errors.
 
-Building a new wrapper with an AI agent? See [AGENTS.md](./AGENTS.md) for the
-step-by-step workflow and folder conventions.
+Building a new wrapper with an AI agent? [SKILL.md](./SKILL.md) has the
+step-by-step workflow and folder conventions. It ships with the package: copy
+`node_modules/hanzio/src/api-wrapper/SKILL.md` to
+`.claude/skills/hanzio-api-wrapper/SKILL.md` (or `.agents/skills/…`), or point
+your agent at it.
 
 ## Quick Start
 

package/src/api-wrapper/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: hanzio-api-wrapper
+description: Building typed HTTP API wrappers with createApiClient and Zod in hanzio/api-wrapper. Covers folder layout, index factory, endpoint files with defineEndpoint, shared types, pagination with paginate, and common REST API integration patterns.
+---
+
+# AI Agent Guide: Building API Wrappers
+
+This guide is for AI assistants to follow when building API wrappers using the
+`createApiClient` utility from `hanzio/api-wrapper`. The API reference
+(configuration, errors, actions, retries, pagination) lives in
+[README.md](./README.md).
+
+## Folder Structure
+
+When creating a new API wrapper, follow this structure:
+
+```txt
+src/api-wrapper/{api-name}/
+├── index.ts
+├── types.ts
+├── {endpointName}.ts
+├── {anotherEndpoint}.ts
+└── utils/
+    ├── {utilName}.ts
+    └── ...
+```
+
+### Naming Conventions
+
+- Folder name: lowercase, kebab-case, for example `github-api`, `stripe`, `template-persona`.
+- Endpoint files: camelCase and action-oriented, for example `topicsGet.ts`, `usersCreate.ts`, `ordersUpdate.ts`.
+- Utility files: camelCase and descriptive, for example `paginateResults.ts`, `templateGetAll.ts`.
+
+## Step-By-Step Process
+
+### Step 1: Gather Information
+
+The user will typically provide one or more of:
+
+1. cURL command: extract method, URL, headers, and body.
+2. Request/response examples: use them to build Zod schemas.
+3. Chrome DevTools Network logs: extract request and response details.
+4. API documentation: reference schemas, auth, pagination, and endpoints.
+
+### Step 2: Create The Folder
+
+```bash
+mkdir -p src/api-wrapper/{api-name}/utils
+```
+
+### Step 3: Create The Index File
+
+The index file creates and exports the API client. When the token comes from
+a secret store, create the client at module level and resolve the header
+lazily with a `defaultHeaders` function; take the token as a parameter only
+when callers supply it per instance.
+
+```ts
+import { createApiClient } from 'hanzio/api-wrapper'
+import { endpointOne } from './endpointOne'
+import { endpointTwo } from './endpointTwo'
+
+export const exampleApi = createApiClient({
+	name: 'exampleApi',
+	baseApiUrls: {
+		default: 'https://api.example.com'
+	},
+	defaultHeaders: () => ({
+		Authorization: `Bearer ${getSecret('EXAMPLE_API_TOKEN')}`
+	}),
+	endpoints: {
+		endpointOne,
+		endpointTwo
+	}
+})
+```
+
+If the project uses OpenTelemetry, add
+`use: [otelMiddleware(trace.getTracer('app'))]`; for other shared middleware
+(metrics), pass it with `use: [...]` instead of wrapping `fetch`. Pass a
+`logger` so failures are logged with their category (server, input or output
+validation). If the API returns HTTP 200 with an
+error envelope (e.g. `{ success: false, errors }`), add a `checkResponse` that
+throws on failure rather than checking after every call. Endpoints without the
+envelope set `checkResponse: false` (or their own check). When the result is in
+response headers (e.g. a `Location`), read them in `resFormatter(body, headers)`.
+
+### Step 4: Create Shared Types
+
+If multiple endpoints share schemas, create a `types.ts` file.
+
+```ts
+import { z } from 'zod'
+
+export const ListQueryInput = z.object({
+	page: z.number().optional(),
+	page_size: z.number().optional()
+})
+export type ListQueryInput = z.infer<typeof ListQueryInput>
+
+export const ListQueryOutput = <T extends z.ZodType>(itemSchema: T) =>
+	z.object({
+		data: z.array(itemSchema),
+		current_page: z.number(),
+		last_page: z.number(),
+		per_page: z.number(),
+		total: z.number()
+	})
+
+export type ListQueryOutput<T> = {
+	data: T[]
+	current_page: number
+	last_page: number
+	per_page: number
+	total: number
+}
+```
+
+### Step 5: Create Endpoint Files
+
+Each endpoint gets its own file with request/response schemas and endpoint
+configuration.
+
+```ts
+import { defineEndpoint } from 'hanzio/api-wrapper'
+import { z } from 'zod'
+
+export const UserResponse = z.object({
+	id: z.number(),
+	name: z.string(),
+	email: z.string()
+})
+
+export const usersGet = defineEndpoint({
+	method: 'GET',
+	path: '/users/:userId',
+	reqQuerySchema: z.object({ includeInactive: z.boolean().optional() }),
+	resSchema: UserResponse
+})
+```
+
+`defineEndpoint` types `reqParams` from the `:params` in `path`, so add a
+`reqParamsSchema` only when params need validation or coercion.
+
+### Step 6: Create Utility Functions
+
+Place reusable helpers in `utils/`, e.g. response normalization or rate-limit
+handling. For pagination, use the built-in `paginate` instead of a hand-written
+loop:
+
+```ts
+import { paginate } from 'hanzio/api-wrapper'
+import type { GetExampleApi } from '../index'
+
+export const usersGetAll = (api: GetExampleApi) =>
+	Array.fromAsync(
+		paginate(
+			(page: number = 1) => api.usersList({ reqQuery: { page } }),
+			(res) =>
+				res.data.current_page < res.data.last_page
+					? res.data.current_page + 1
+					: null
+		)
+	)
+```
+
+## Extracting Information From User Input
+
+### From cURL Commands
+
+```bash
+curl -X POST 'https://api.example.com/users' \
+  -H 'Authorization: Bearer token123' \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "John", "email": "john@example.com"}'
+```
+
+Extract:
+
+- Method: `POST`
+- Base URL: `https://api.example.com`
+- Path: `/users`
+- Headers: `Authorization`, `Content-Type`
+- Body schema: `{ name: string, email: string }`
+
+### From Chrome DevTools
+
+Look for:
+
+1. Request URL: base URL plus path.
+2. Request method: HTTP method.
+3. Request headers: auth and custom headers.
+4. Request payload: body schema.
+5. Response body: response schema.
+6. Query string parameters: query schema.
+
+### Building Zod Schemas From JSON
+
+Given this response:
+
+```json
+{
+	"id": 123,
+	"name": "John Doe",
+	"email": "john@example.com",
+	"created_at": "2024-01-15T10:30:00Z",
+	"roles": ["admin", "user"],
+	"profile": {
+		"avatar_url": "https://example.com/avatar.png",
+		"bio": "Developer"
+	},
+	"is_active": true
+}
+```
+
+Create this schema:
+
+```ts
+const UserResponse = z.object({
+	id: z.number(),
+	name: z.string(),
+	email: z.string(),
+	created_at: z.string(),
+	roles: z.array(z.string()),
+	profile: z.object({
+		avatar_url: z.string(),
+		bio: z.string()
+	}),
+	is_active: z.boolean()
+})
+```
+
+## Checklist
+
+- [ ] Create folder with API name in kebab-case.
+- [ ] Create `index.ts` with a `createApiClient` call.
+- [ ] Set `baseApiUrls` and `defaultHeaders` (a function when the token comes from a secret store).
+- [ ] Add `checkResponse` if the API returns errors inside 200 responses.
+- [ ] Create `types.ts` for shared schemas when needed.
+- [ ] Create one file per endpoint.
+- [ ] Define Zod schemas for all request and response data.
+- [ ] Use `defineEndpoint` for endpoint definitions.
+- [ ] Create helpers in `utils/` when needed.
+- [ ] Export the API type, for example `export type ExampleApi = typeof exampleApi`.
+- [ ] Test with `createMockFetch` from `hanzio/api-wrapper/testing` passed as `fetch`; don't replace `globalThis.fetch`.
+
+## Tips
+
+1. Always use `defineEndpoint` for endpoint definitions (it checks `resFormatter` and types path params).
+2. Import Zod from `zod`.
+3. Be strict with schemas and mark unstable fields as `.optional()` or `.nullish()`.
+4. Use descriptive endpoint names like `usersGet`, `usersCreate`, and `ordersListByStatus`.
+5. Keep files small by using one endpoint per file.
+6. Extract schemas to `types.ts` when used by two or more endpoints.
+7. Use `paginate` when APIs use pagination.
+8. Ask for sample responses if the user only provides cURL commands.

package/src/typedswitch/README.md

@@ -22,15 +22,16 @@ bun add typedswitch
 - **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
-- **Return type constraints** — Enforce that all handlers return a specific type
+- **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
 
-### String/Enum Input
+### Plain Value Input
 
-Switch on a string literal or enum value directly:
+Switch on a string, number, boolean or enum value directly:
 
 ```typescript
 import { typedSwitch } from 'typedswitch'
@@ -58,6 +59,21 @@ const result = typedSwitch(status, {
 })
 ```
 
+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.):
@@ -116,6 +132,32 @@ typedSwitch(result, 'ok', {
 })
 ```
 
+### 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:
@@ -202,45 +244,23 @@ const result = typedSwitch(status, {
 // result: { ok: true; data: string } | { ok: false; code: number } | null
 ```
 
-### Return Type Constraints
+### Enforcing a Return Type
 
-Enforce that all handlers return a type extending a constraint with `typedSwitch<Constraint>(...)`. The `<Constraint>` is optional; omit it when you want TypeScript to infer the return types freely.
+Annotate the result. Every handler's return type must fit, and exhaustiveness
+checking still applies:
 
 ```typescript
 interface HasId {
   id: string
 }
 
-// All handlers must return something with { id: string }
-const result = typedSwitch<HasId>(status, {
-  success: () => ({ id: '123', name: 'John' }),     // ✓ OK
-  error: () => ({ id: '456', code: 500 }),          // ✓ OK
-  pending: () => ({ id: '789' }),                   // ✓ OK
-})
-// result: HasId
-
-// This would be a compile error:
-typedSwitch<HasId>(status, {
-  success: () => ({ name: 'John' }),  // ✗ Error: missing 'id'
-  error: () => ({ id: '456' }),
+const result: HasId = typedSwitch(status, {
+  success: () => ({ id: '123', name: 'John' }),
+  error: () => ({ id: '456', code: 500 }),
   pending: () => ({ id: '789' }),
 })
 ```
 
-Constraints also work with discriminated unions and default handlers:
-
-```typescript
-const result = typedSwitch<HasId>(
-  event,
-  'type',
-  {
-    click: () => ({ id: 'click-1', x: 10, y: 20 }),
-    scroll: () => ({ id: 'scroll-1', offset: 100 }),
-    keypress: () => ({ id: 'key-1', key: 'Enter' }),
-  }
-)
-```
-
 ## Error Handling
 
 When a case is unhandled at runtime (e.g., due to unsafe casts), `typedSwitch` throws a descriptive error:
@@ -284,11 +304,11 @@ function label(status: Status) {
 
 ### `typedSwitch(value, cases)`
 
-Switch on a string literal with exhaustive case handling.
+Switch on a string, number or boolean value with exhaustive case handling.
 
 ### `typedSwitch(value, cases, defaultHandler)`
 
-Switch on a string literal with partial cases and a default fallback.
+Switch on a string, number or boolean value with partial cases and a default fallback.
 
 ### `typedSwitch(object, key, cases)`
 
@@ -298,13 +318,9 @@ Switch on a discriminated union using the specified discriminant key (string, nu
 
 Switch on a discriminated union with partial cases and a default fallback.
 
-### `typedSwitch<Constraint>(value, cases)`
-
-Switch on a string literal while enforcing that each handler returns `Constraint` or `Promise<Constraint>`.
-
-### `typedSwitch<Constraint>(object, key, cases)`
+### `typedSwitchGroup(value, keys, handler)` / `typedSwitchGroup(object, key, keys, handler)`
 
-Switch on a discriminated union while enforcing that each handler returns `Constraint` or `Promise<Constraint>`.
+Returns cases that all call `handler`, for spreading into `typedSwitch` cases.
 
 ### `assertNever(value, message?)`
 

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