hanzio 3.1.1 → 3.2.0

package/README.md

@@ -562,6 +562,12 @@ const text = typedSwitch(response as Response, 'code', {
 	404: () => 'Not found'
 })
 
+// Annotate the result to keep literal return types
+const tone: 'info' | 'danger' = typedSwitch(response as Response, 'code', {
+	200: () => 'info',
+	404: () => 'danger'
+})
+
 const event = { type: 'scroll', offset: 4 } as Event
 typedSwitch(event, 'type', {
 	...typedSwitchGroup(event, 'type', ['click', 'scroll'], (e) => e.type)

package/dist/format/index.d.ts

@@ -140,8 +140,11 @@ declare const DATE_PRESETS: {
  * follows the locale: `'D MMM'` is "5 Mar" in en-GB and "Mar 5" in en-US.
  */
 export type DatePreset = keyof typeof DATE_PRESETS;
-/** A date in one of the `DatePreset` layouts, in local time. */
-export declare function formatDate(date: DateInput, preset: DatePreset, locale: string): string;
+/**
+ * A date in one of the `DatePreset` layouts, or with any
+ * `Intl.DateTimeFormat` options, in local time unless they set `timeZone`.
+ */
+export declare function formatDate(date: DateInput, format: DatePreset | Intl.DateTimeFormatOptions, locale: string): string;
 /** Medium date and short time: "5 Mar 2026, 14:30" (en-GB). */
 export declare function formatDateTime(date: DateInput, locale: string): string;
 /**
@@ -182,7 +185,7 @@ export declare function pluralize(count: number, forms: Partial<Record<Intl.LDML
  * `export const fmt = withLocale(() => uiLocales.tag(appI18n.locale()))`.
  */
 export declare function withLocale(getLocale: () => string): {
-    formatDate: (date: DateInput, preset: "D MMM" | "D MMM YYYY" | "DD/MM/YYYY" | "DD/MM/YYYY HH:mm" | "HH:mm" | "MMMM YYYY" | "ddd" | "dddd, MMMM D") => string;
+    formatDate: (date: DateInput, format: "D MMM" | "D MMM YYYY" | "DD/MM/YYYY" | "DD/MM/YYYY HH:mm" | "HH:mm" | "MMMM YYYY" | "ddd" | "dddd, MMMM D" | Intl.DateTimeFormatOptions) => string;
     formatDateTime: (date: DateInput) => string;
     formatCompactTime: (date: DateInput) => string;
     formatDayDivider: (date: DateInput) => string;

package/dist/src/format/index.js

@@ -193,8 +193,9 @@ var DATE_PRESETS = {
   "dddd, MMMM D": { weekday: "long", day: "numeric", month: "long" },
   "MMMM YYYY": { month: "long", year: "numeric" }
 };
-function formatDate(date, preset, locale) {
-  return getDateTimeFormat(locale, DATE_PRESETS[preset]).format(toTime(date));
+function formatDate(date, format, locale) {
+  const options = typeof format === "string" ? DATE_PRESETS[format] : format;
+  return getDateTimeFormat(locale, options).format(toTime(date));
 }
 function formatDateTime(date, locale) {
   return getDateTimeFormat(locale, {
@@ -249,7 +250,7 @@ function pluralize(count, forms, locale) {
 }
 function withLocale(getLocale) {
   return {
-    formatDate: (date, preset) => formatDate(date, preset, getLocale()),
+    formatDate: (date, format) => formatDate(date, format, getLocale()),
     formatDateTime: (date) => formatDateTime(date, getLocale()),
     formatCompactTime: (date) => formatCompactTime(date, getLocale()),
     formatDayDivider: (date) => formatDayDivider(date, getLocale()),

package/dist/src/i18n/cli.js

@@ -12,6 +12,7 @@ import {
 
 // src/i18n/cli.ts
 import { existsSync } from "node:fs";
+import * as nodeModule from "node:module";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
@@ -21,10 +22,41 @@ var CONFIG_NAMES = [
   "i18n.config.js",
   "i18n.config.mjs"
 ];
+var BUNDLER_SUFFIXES = [
+  ".ts",
+  ".mts",
+  ".js",
+  ".mjs",
+  "/index.ts",
+  "/index.mts",
+  "/index.js",
+  "/index.mjs"
+];
+function resolveLikeBundlers() {
+  nodeModule.registerHooks?.({
+    resolve(specifier, context, nextResolve) {
+      try {
+        return nextResolve(specifier, context);
+      } catch (error) {
+        const code = error.code;
+        const retry = specifier.startsWith(".") && (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_UNSUPPORTED_DIR_IMPORT");
+        if (!retry)
+          throw error;
+        for (const suffix of BUNDLER_SUFFIXES) {
+          try {
+            return nextResolve(specifier + suffix, context);
+          } catch {}
+        }
+        throw error;
+      }
+    }
+  });
+}
 async function loadConfig(file) {
   const path = file ? resolve(file) : CONFIG_NAMES.map((name) => resolve(name)).find((path) => existsSync(path));
   if (!path || !existsSync(path))
     throw new CliError2(`No i18n config found: pass --config or add ${CONFIG_NAMES[0]}.`);
+  resolveLikeBundlers();
   const loaded = await import(pathToFileURL(path).href);
   if (!loaded.default?.catalogs)
     throw new CliError2(`${path} must default-export an i18n config`);

package/dist/typedswitch/index.d.ts

@@ -80,6 +80,23 @@ type RawHandlerReturnType<T> = T extends (...args: any[]) => infer R ? R : never
 type RawCasesReturnType<Cases> = {
     [K in keyof Cases]: RawHandlerReturnType<Cases[K]>;
 }[keyof Cases];
+/**
+ * `R` is only inferred from the call's contextual type. Without one it stays
+ * `unknown`, and the overload returns the handlers' own return types.
+ */
+type Annotated<R, Inferred> = unknown extends R ? Inferred : R;
+/**
+ * TypeScript fixes a handler's return type the first time it checks it, and
+ * an object-mode call (`value, key, cases`) is first tried against the
+ * plain-value overload with a default (`value, cases, defaultCase`). This type
+ * types those cases' handlers by the annotation there too, so they keep their
+ * literals. No value satisfies it: `default` would have to be `never`.
+ */
+type ObjectCasesContext<R> = {
+    [key: string]: (value: never) => R;
+} & {
+    default: never;
+};
 /** Only required, defined handlers guarantee that a case is handled. */
 type HandledCaseKeys<Cases> = {
     [K in keyof Cases]-?: {} extends Pick<Cases, K> ? never : undefined extends Cases[K] ? never : K;
@@ -113,13 +130,21 @@ export type PartialObjectSwitchCases<T, K extends keyof T, R> = T[K] extends Dis
 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, R, Cases extends {
+    [V in T as `${V}`]: (value: V) => R;
+} & NoUnknownCases<Cases, `${T}`>>(value: T, cases: Cases): Annotated<R, RawCasesReturnType<Cases>>;
+export declare function typedSwitch<T extends Discriminant, R, Cases extends {
+    [V in T as `${V}`]?: (value: V) => R;
+} & NoUnknownCases<Cases, `${T}`>, DefaultCase extends ((value: Exclude<T, ValuesForKeys<T, HandledCaseKeys<Cases>>>) => R) | ObjectCasesContext<R>>(value: T, cases: Cases, defaultCase: DefaultCase): Annotated<R, RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>>;
+export declare function typedSwitch<T extends object, K extends keyof T, R, Cases extends ObjectCases<T, K, R> & NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>>(value: T, key: K, cases: Cases): Annotated<R, RawCasesReturnType<Cases>>;
+export declare function typedSwitch<T extends object, K extends keyof T, R, Cases extends PartialObjectCases<T, K, R> & NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>, DefaultCase extends (value: Exclude<T, Record<K, ValuesForKeys<T[K], HandledCaseKeys<Cases>>>>) => R>(value: T, key: K, cases: Cases, defaultCase: DefaultCase): Annotated<R, RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>>;
 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 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 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzio",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",

package/src/format/README.md

@@ -87,6 +87,13 @@ formatDateTime(date, 'en-GB') // '5 Mar 2026, 07:04' (newer ICU: '5 Mar 2026 at
 Presets: `'DD/MM/YYYY'`, `'DD/MM/YYYY HH:mm'`, `'HH:mm'`, `'ddd'`, `'D MMM'`,
 `'D MMM YYYY'`, `'dddd, MMMM D'`, `'MMMM YYYY'`.
 
+For any other layout, pass `Intl.DateTimeFormat` options instead of a preset:
+
+```ts
+formatDate(date, { weekday: 'long', day: 'numeric', month: 'long' }, 'en-GB') // 'Thursday 5 March'
+formatDate(date, { dateStyle: 'short', timeZone: 'Europe/Copenhagen' }, 'da-DK') // '05.03.2026'
+```
+
 `formatCompactTime(date, locale, { now? })` is an activity timestamp for list
 rows: the time today, "yesterday", else the date (with the year when it is not
 this year). `formatDayDivider(date, locale, { now? })` labels a chat timeline:

package/src/format/index.ts

@@ -401,13 +401,17 @@ const DATE_PRESETS = {
  */
 export type DatePreset = keyof typeof DATE_PRESETS
 
-/** A date in one of the `DatePreset` layouts, in local time. */
+/**
+ * A date in one of the `DatePreset` layouts, or with any
+ * `Intl.DateTimeFormat` options, in local time unless they set `timeZone`.
+ */
 export function formatDate(
 	date: DateInput,
-	preset: DatePreset,
+	format: DatePreset | Intl.DateTimeFormatOptions,
 	locale: string
 ): string {
-	return getDateTimeFormat(locale, DATE_PRESETS[preset]).format(toTime(date))
+	const options = typeof format === 'string' ? DATE_PRESETS[format] : format
+	return getDateTimeFormat(locale, options).format(toTime(date))
 }
 
 /** Medium date and short time: "5 Mar 2026, 14:30" (en-GB). */
@@ -519,8 +523,10 @@ export function pluralize(
  */
 export function withLocale(getLocale: () => string) {
 	return {
-		formatDate: (date: DateInput, preset: DatePreset) =>
-			formatDate(date, preset, getLocale()),
+		formatDate: (
+			date: DateInput,
+			format: DatePreset | Intl.DateTimeFormatOptions
+		) => formatDate(date, format, getLocale()),
 		formatDateTime: (date: DateInput) => formatDateTime(date, getLocale()),
 		formatCompactTime: (date: DateInput) =>
 			formatCompactTime(date, getLocale()),

package/src/i18n/README.md

@@ -203,7 +203,9 @@ Both read `i18n.config.ts` (or `.mts`, `.js`, `.mjs`, or `--config <file>`)
 from the current directory; paths in it are relative to the config file.
 `defineI18nConfig` rejects a `baseLocale`, `disjointNamespaces` catalog or
 `identical.allowKeys` locale the config does not declare. A
-`.ts` config needs Bun, or a Node version that strips types. The bin is built
+`.ts` config needs Bun or Node 22.18+. Its relative imports may leave out the
+extension or `/index`, as TypeScript's bundler resolution allows, so
+`npx hanzio-i18n check` works without `bun --bun`. The bin is built
 on [`hanzio/cli`](../cli/README.md), so it needs `zod` installed; `--help`
 lists its options and it exits 1 on catalog problems, 2 on bad arguments.
 

package/src/i18n/cli.ts

@@ -5,6 +5,7 @@
 // a Node version that strips types.
 
 import { existsSync } from 'node:fs'
+import * as nodeModule from 'node:module'
 import { dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { z } from 'zod'
@@ -25,6 +26,44 @@ const CONFIG_NAMES = [
 
 type Loaded = { config: I18nConfig; root: string }
 
+// Node resolves a config's imports like a browser: `./src/locales` fails
+// because it names neither a file nor an extension. Bun resolves it like a
+// bundler. These are the suffixes TypeScript's bundler resolution tries.
+const BUNDLER_SUFFIXES = [
+	'.ts',
+	'.mts',
+	'.js',
+	'.mjs',
+	'/index.ts',
+	'/index.mts',
+	'/index.js',
+	'/index.mjs'
+]
+
+function resolveLikeBundlers() {
+	// Missing under Bun, which needs no help, and under Node before 22.15.
+	nodeModule.registerHooks?.({
+		resolve(specifier, context, nextResolve) {
+			try {
+				return nextResolve(specifier, context)
+			} catch (error) {
+				const code = (error as { code?: string }).code
+				const retry =
+					specifier.startsWith('.') &&
+					(code === 'ERR_MODULE_NOT_FOUND' ||
+						code === 'ERR_UNSUPPORTED_DIR_IMPORT')
+				if (!retry) throw error
+				for (const suffix of BUNDLER_SUFFIXES) {
+					try {
+						return nextResolve(specifier + suffix, context)
+					} catch {}
+				}
+				throw error
+			}
+		}
+	})
+}
+
 async function loadConfig(file: string | undefined): Promise<Loaded> {
 	const path = file
 		? resolve(file)
@@ -33,6 +72,7 @@ async function loadConfig(file: string | undefined): Promise<Loaded> {
 		throw new CliError(
 			`No i18n config found: pass --config or add ${CONFIG_NAMES[0]}.`
 		)
+	resolveLikeBundlers()
 	const loaded = (await import(pathToFileURL(path).href)) as {
 		default?: I18nConfig
 	}

package/src/typedswitch/README.md

@@ -246,21 +246,32 @@ const result = typedSwitch(status, {
 
 ### Enforcing a Return Type
 
-Annotate the result. Every handler's return type must fit, and exhaustiveness
-checking still applies:
+Annotate the result, or switch in a function with a declared return type.
+Every handler is checked against it, exhaustiveness checking still applies,
+and literals keep their types instead of widening to `string`:
 
 ```typescript
-interface HasId {
-  id: string
-}
+type Severity = 'success' | 'info' | 'warn' | 'danger'
 
-const result: HasId = typedSwitch(status, {
-  success: () => ({ id: '123', name: 'John' }),
-  error: () => ({ id: '456', code: 500 }),
-  pending: () => ({ id: '789' }),
+const severity: Severity = typedSwitch(quality, {
+  excellent: () => 'success',
+  good: () => 'info',
+  fair: () => 'warn',
+  poor: () => 'danger',
 })
+
+function orderBy(sort: Sort): Prisma.OrderOrderByWithRelationInput[] {
+  return typedSwitch(sort, {
+    name: () => [{ name: 'asc' }],
+    newest: () => [{ createdAt: 'desc' }],
+  })
+}
 ```
 
+Without an annotation, or inside a generic call such as `useState(typedSwitch(...))`,
+the result is the union of the handlers' widened return types. In Vue, annotate
+the getter: `computed((): Severity => typedSwitch(...))`.
+
 ## Error Handling
 
 When a case is unhandled at runtime (e.g., due to unsafe casts), `typedSwitch` throws a descriptive error:

package/src/typedswitch/index.ts

@@ -88,6 +88,23 @@ type RawCasesReturnType<Cases> = {
 	[K in keyof Cases]: RawHandlerReturnType<Cases[K]>
 }[keyof Cases]
 
+/**
+ * `R` is only inferred from the call's contextual type. Without one it stays
+ * `unknown`, and the overload returns the handlers' own return types.
+ */
+type Annotated<R, Inferred> = unknown extends R ? Inferred : R
+
+/**
+ * TypeScript fixes a handler's return type the first time it checks it, and
+ * an object-mode call (`value, key, cases`) is first tried against the
+ * plain-value overload with a default (`value, cases, defaultCase`). This type
+ * types those cases' handlers by the annotation there too, so they keep their
+ * literals. No value satisfies it: `default` would have to be `never`.
+ */
+type ObjectCasesContext<R> = { [key: string]: (value: never) => R } & {
+	default: never
+}
+
 /** Only required, defined handlers guarantee that a case is handled. */
 type HandledCaseKeys<Cases> = {
 	// biome-ignore lint/complexity/noBannedTypes: Empty-object assignability detects optional keys and index signatures.
@@ -173,6 +190,65 @@ type CasesRecord = Record<string, Handler | undefined>
 // Function overloads
 // ═══════════════════════════════════════════════════════════════════════════
 
+// Each mode has two overloads. The first four take the result type `R` from
+// the call's contextual type, such as an annotated variable or a declared
+// return type, so handlers that return literals ('info', [{ name: 'asc' }])
+// keep them. When that does not type-check, for example inside a generic call
+// like useState(typedSwitch(...)), the last four union the handlers' types.
+
+// Plain value input - all cases required, typed by the annotation
+export function typedSwitch<
+	T extends Discriminant,
+	R,
+	Cases extends { [V in T as `${V}`]: (value: V) => R } & NoUnknownCases<
+		Cases,
+		`${T}`
+	>
+>(value: T, cases: Cases): Annotated<R, RawCasesReturnType<Cases>>
+
+// Plain value input - partial cases with default, typed by the annotation.
+// It comes before the object overloads, which also take three arguments.
+export function typedSwitch<
+	T extends Discriminant,
+	R,
+	Cases extends {
+		[V in T as `${V}`]?: (value: V) => R
+	} & NoUnknownCases<Cases, `${T}`>,
+	DefaultCase extends
+		| ((value: Exclude<T, ValuesForKeys<T, HandledCaseKeys<Cases>>>) => R)
+		| ObjectCasesContext<R>
+>(
+	value: T,
+	cases: Cases,
+	defaultCase: DefaultCase
+): Annotated<R, RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>>
+
+// Object input with key - all cases required, typed by the annotation
+export function typedSwitch<
+	T extends object,
+	K extends keyof T,
+	R,
+	Cases extends ObjectCases<T, K, R> &
+		NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>
+>(value: T, key: K, cases: Cases): Annotated<R, RawCasesReturnType<Cases>>
+
+// Object input with key - partial cases with default, typed by the annotation
+export function typedSwitch<
+	T extends object,
+	K extends keyof T,
+	R,
+	Cases extends PartialObjectCases<T, K, R> &
+		NoUnknownCases<Cases, `${Extract<T[K], Discriminant>}`>,
+	DefaultCase extends (
+		value: Exclude<T, Record<K, ValuesForKeys<T[K], HandledCaseKeys<Cases>>>>
+	) => R
+>(
+	value: T,
+	key: K,
+	cases: Cases,
+	defaultCase: DefaultCase
+): Annotated<R, RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>>
+
 // Plain value input - all cases required (no default)
 export function typedSwitch<
 	T extends Discriminant,
@@ -182,6 +258,14 @@ export function typedSwitch<
 	>
 >(value: T, cases: Cases): RawCasesReturnType<Cases>
 
+// Object input with key - all cases required (no default)
+export 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>
+
 // Plain value input - partial cases allowed (with default)
 // The default handler only receives the cases not covered by `cases`.
 export function typedSwitch<
@@ -198,14 +282,6 @@ export function typedSwitch<
 	defaultCase: DefaultCase
 ): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>
 
-// Object input with key - all cases required (no default)
-export 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>
-
 // Object input with key - partial cases allowed (with default)
 // The default handler only receives the union members not covered by `cases`.
 export function typedSwitch<