hanzio 2.1.0 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristoffer Hansen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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':
@@ -1156,9 +1171,8 @@ bun run build
 
 ## Releasing
 
-Releases are cut by [Release Please](https://github.com/googleapis/release-please)
-from squash-merged PR titles written as conventional commits. `feat:` bumps the
-minor version, `fix:` the patch, `feat!:` or a `BREAKING CHANGE:` footer the
-major. `chore:`, `ci:`, `docs:`, `refactor:` and `test:` do not release. Each
-merge to main updates a release PR; merging that PR tags the version and
-publishes to npm. Nobody runs `npm publish` locally.
+Squash PRs with conventional titles (`fix:`, `feat:`, or `feat!:`). Release Please keeps the version and changelog in a release PR; merge that PR to publish with release notes and npm provenance. See [release and recovery instructions](docs/releasing.md).
+
+## License
+
+[MIT](LICENSE).

package/dist/api-wrapper/endpoint.d.ts

@@ -1,10 +1,11 @@
 import type { z } from 'zod';
-import type { ApiEndpoint } from './types';
+import type { ApiEndpoint, CheckResponseContext } from './types';
 /**
  * Defines an endpoint with full inference, as an alternative to
  * `satisfies ApiEndpoint`: `resFormatter` must return what `resSchema`
- * accepts, and a literal `path` types its `:params` (making `reqParams`
- * required when there's no `reqParamsSchema`).
+ * accepts, `checkResponse` receives the parsed `resSchema` output, and a
+ * literal `path` types its `:params` (making `reqParams` required when
+ * there's no `reqParamsSchema`).
  *
  * @example
  * export const usersGet = defineEndpoint({
@@ -13,6 +14,8 @@ import type { ApiEndpoint } from './types';
  *   resSchema: User
  * })
  */
-export declare function defineEndpoint<const TEndpoint extends ApiEndpoint>(endpoint: TEndpoint & {
-    resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TEndpoint['resSchema']>;
+export declare function defineEndpoint<const TEndpoint extends Omit<ApiEndpoint, 'checkResponse'>, TRes extends z.ZodType = TEndpoint['resSchema']>(endpoint: TEndpoint & {
+    resSchema: TRes;
+    resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TRes>;
+    checkResponse?: ((data: z.output<TRes>, context: CheckResponseContext) => void | Promise<void>) | false;
 }): TEndpoint;

package/dist/api-wrapper/transport.d.ts

@@ -49,6 +49,7 @@ export declare function makeRequestWithRetry<TValidated>(args: MakeRequestArgs<T
 export declare function validateAndTransformResponse<T extends z.ZodType>(endpoint: ApiEndpoint<z.ZodType | undefined, z.ZodType | undefined, z.ZodType | undefined, z.ZodType | undefined, T>, response: Response, ctx: (over?: Partial<ApiErrorContext>) => ApiErrorContext): Promise<{
     data: z.infer<T>;
     responseSizeBytes: number;
+    headers: Record<string, string>;
 }>;
 export declare function defaultShouldRetry(ctx: RetryContext): boolean;
 export {};

package/dist/api-wrapper/types.d.ts

@@ -17,6 +17,11 @@ export interface ApiEndpoint<TReqBody extends z.ZodType | undefined = z.ZodType
     resFormatter?: (data: unknown, headers: Record<string, string>) => z.input<TResponse>;
     reqDefaultQueryParams?: QueryParams;
     doNotEncodeQueryParams?: boolean;
+    /**
+     * Replaces the client's `checkResponse` for this endpoint; `false` skips it.
+     * `defineEndpoint` types `data` as the parsed `resSchema` output.
+     */
+    checkResponse?: ((data: any, context: CheckResponseContext) => void | Promise<void>) | false;
 }
 export interface ApiWrapperResponse<T> {
     data: T;
@@ -25,6 +30,8 @@ export interface ApiWrapperResponse<T> {
     responseTimeMs: number;
     httpStatus: number;
     retryCount: number;
+    /** Response headers of the final attempt, keyed by lowercase name. */
+    headers: Record<string, string>;
 }
 export type RetryContext = {
     error?: unknown;

package/dist/{index-j1ybktbr.js → index-zbj9s3s3.js}

@@ -1006,7 +1006,7 @@ async function validateAndTransformResponse(endpoint, response, ctx) {
   }
   const transformedData = endpoint.resFormatter ? endpoint.resFormatter(responseData, responseHeaders) : responseData;
   const data = await validateResponse(endpoint.resSchema, transformedData, ctx);
-  return { data, responseSizeBytes };
+  return { data, responseSizeBytes, headers: responseHeaders };
 }
 function defaultShouldRetry2(ctx) {
   if (ctx.error)
@@ -1170,14 +1170,16 @@ function createApiClientImpl(apiConfig) {
         responseSizeMb: result.validatedData.responseSizeBytes / (1024 * 1024),
         responseTimeMs: elapsed(),
         httpStatus: result.httpStatus,
-        retryCount: result.retryCount
+        retryCount: result.retryCount,
+        headers: result.validatedData.headers
       };
     };
     const runCheckResponse = async (data, httpStatus, attempt) => {
-      if (!apiConfig.checkResponse)
+      const checkResponse = endpoint.checkResponse === undefined ? apiConfig.checkResponse : endpoint.checkResponse;
+      if (!checkResponse)
         return;
       try {
-        await apiConfig.checkResponse(data, {
+        await checkResponse(data, {
           endpoint: endpointName,
           method: endpoint.method,
           url: fullUrl,

package/dist/src/api-wrapper/index.js

@@ -28,7 +28,7 @@ import {
   paginate2,
   otelMiddleware2,
   defineEndpoint2
-} from "../../index-j1ybktbr.js";
+} from "../../index-zbj9s3s3.js";
 export {
   ActionError2 as ActionError,
   ApiError2 as ApiError,

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/src/secrets/index.js

@@ -1,7 +1,7 @@
 import {
   HttpResponseError2,
   createApiClient2
-} from "../../index-j1ybktbr.js";
+} from "../../index-zbj9s3s3.js";
 import {
   getViteDefine2,
   viteSecretSetPlugin2

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.1.0",
+  "version": "3.0.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -25,6 +25,8 @@
   },
   "files": [
     "src/**/*.ts",
+    "src/**/README.md",
+    "src/api-wrapper/SKILL.md",
     "dist",
     "!src/**/*.test.ts"
   ],
@@ -132,7 +134,8 @@
     "typecheck": "tsgo --noEmit",
     "prepare": "husky",
     "test:secrets:runtime": "bun run build && node scripts/verify-secrets.mjs",
-    "test:exports": "bun run build && node scripts/verify-exports.mjs"
+    "test:exports": "bun run build && node scripts/verify-exports.mjs",
+    "verify:package": "node scripts/verify-package.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
@@ -152,5 +155,10 @@
     "zod": {
       "optional": true
     }
-  }
+  },
+  "homepage": "https://github.com/HansKristoffer/hanzio#readme",
+  "bugs": {
+    "url": "https://github.com/HansKristoffer/hanzio/issues"
+  },
+  "packageManager": "bun@1.4.2"
 }