hanzio 2.2.0 → 3.1.0

package/src/testing/module-mocker.ts

@@ -0,0 +1,50 @@
+type ModuleExports = Record<string, unknown>
+
+/**
+ * `mock.module` that can be undone. Bun replaces a mocked module for the whole
+ * process and `mock.restore()` does not bring it back
+ * (https://github.com/oven-sh/bun/issues/7823), so one suite's stub silently
+ * leaks into every later suite.
+ *
+ * Mocks spread the module's real exports first, so exports you don't override
+ * keep working, and `clear()` re-registers the originals. Call it in
+ * `afterEach` or `afterAll`.
+ *
+ * Bun resolves specifiers relative to the file that registers the mock, so
+ * pass absolute paths or package names. A `resolve` function maps your own
+ * shorthand (an `@/` alias, a source-root-relative path) to absolute paths.
+ *
+ * @example
+ * const moduleMocker = new ModuleMocker((specifier) =>
+ *   specifier.startsWith('@/') ? path.resolve(srcDir, specifier.slice(2)) : specifier
+ * )
+ * await moduleMocker.mock('@/lib/posthog', () => ({ captureException: mock() }))
+ * afterAll(() => moduleMocker.clear())
+ */
+export class ModuleMocker {
+	private restorers: (() => void)[] = []
+
+	constructor(
+		private readonly resolve: (specifier: string) => string = (specifier) =>
+			specifier
+	) {}
+
+	async mock(
+		specifier: string,
+		renderMocks: () => ModuleExports
+	): Promise<void> {
+		const { mock } = await import('bun:test')
+		const resolved = this.resolve(specifier)
+		const original = { ...(await import(resolved)) } as ModuleExports
+		const merged = { ...original, ...renderMocks() }
+		mock.module(resolved, () => merged)
+		this.restorers.push(() => {
+			mock.module(resolved, () => original)
+		})
+	}
+
+	clear(): void {
+		for (const restore of this.restorers) restore()
+		this.restorers = []
+	}
+}

package/src/testing/prisma.ts

@@ -0,0 +1,78 @@
+import type { Mock, mock } from 'bun:test'
+
+export type PrismaMethodMock = Mock<(...args: unknown[]) => Promise<unknown>>
+
+/**
+ * A Prisma client where every model delegate and every method is a Bun mock,
+ * created on first access, like `jest-mock-extended`'s `mockDeep()`.
+ * `$`-prefixed client methods (`$transaction`, `$queryRaw`) are mocks too.
+ */
+export type DeepMockedPrisma<Client> = {
+	[K in keyof Client]: Client[K] extends (...args: never[]) => unknown
+		? PrismaMethodMock
+		: { [Method in keyof Client[K]]: PrismaMethodMock }
+} & {
+	/** Resets every mock created so far. Call it in `beforeEach`. */
+	$reset: () => void
+}
+
+/**
+ * Builds a deep auto-mock of a Prisma client from Bun's `mock`. Register it
+ * with `mock.module` in place of the module that exports your client.
+ *
+ * @example
+ * import { mock } from 'bun:test'
+ * import type { prisma } from '../lib/prisma'
+ *
+ * export const prismaMock = createPrismaMock<typeof prisma>(mock)
+ * mock.module(prismaModulePath, () => ({ ...prismaExports, prisma: prismaMock }))
+ *
+ * prismaMock.user.findUnique.mockResolvedValue({ id: 'u1' })
+ * expect(prismaMock.user.findUnique).toHaveBeenCalledWith({ where: { id: 'u1' } })
+ */
+export function createPrismaMock<Client>(
+	createMock: typeof mock
+): DeepMockedPrisma<Client> {
+	const created: PrismaMethodMock[] = []
+	const reset = () => {
+		for (const method of created) method.mockReset()
+	}
+
+	const methodsOf = (methods: Map<string, PrismaMethodMock>, key: string) => {
+		let method = methods.get(key)
+		if (!method) {
+			method = createMock() as unknown as PrismaMethodMock
+			created.push(method)
+			methods.set(key, method)
+		}
+		return method
+	}
+
+	const delegates = new Map<string, object>()
+	const rootMethods = new Map<string, PrismaMethodMock>()
+
+	const delegateFor = (model: string) => {
+		let delegate = delegates.get(model)
+		if (!delegate) {
+			const methods = new Map<string, PrismaMethodMock>()
+			delegate = new Proxy(
+				{},
+				{
+					get: (_target, method) =>
+						typeof method === 'symbol' ? undefined : methodsOf(methods, method)
+				}
+			)
+			delegates.set(model, delegate)
+		}
+		return delegate
+	}
+
+	return new Proxy({} as DeepMockedPrisma<Client>, {
+		get(_target, property) {
+			if (property === '$reset') return reset
+			if (typeof property === 'symbol') return undefined
+			if (property.startsWith('$')) return methodsOf(rootMethods, property)
+			return delegateFor(property)
+		}
+	})
+}

package/src/testing/window.ts

@@ -0,0 +1,119 @@
+/** A complete in-memory `Storage` (`localStorage` / `sessionStorage`). */
+export function createTestStorage(): Storage {
+	const store = new Map<string, string>()
+	return {
+		get length() {
+			return store.size
+		},
+		clear: () => store.clear(),
+		getItem: (key) => store.get(key) ?? null,
+		key: (index) => [...store.keys()][index] ?? null,
+		removeItem: (key) => {
+			store.delete(key)
+		},
+		setItem: (key, value) => {
+			store.set(key, String(value))
+		}
+	}
+}
+
+type ShimLocation = Pick<
+	URL,
+	| 'href'
+	| 'origin'
+	| 'protocol'
+	| 'host'
+	| 'hostname'
+	| 'port'
+	| 'pathname'
+	| 'search'
+	| 'hash'
+>
+
+type ShimWindow = {
+	location: ShimLocation
+	addEventListener: (...args: unknown[]) => void
+	removeEventListener: (...args: unknown[]) => void
+	localStorage: Storage
+}
+
+const noop = () => {}
+
+function locationOf(href: string): ShimLocation {
+	const { origin, protocol, host, hostname, port, pathname, search, hash } =
+		new URL(href)
+	return {
+		href,
+		origin,
+		protocol,
+		host,
+		hostname,
+		port,
+		pathname,
+		search,
+		hash
+	}
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null
+}
+
+/**
+ * Installs a minimal `globalThis.window` for unit tests of browser-facing code
+ * that only probes `window` (`location`, `localStorage`, event listeners), and
+ * returns a `reset` to call in `afterEach`.
+ *
+ * Tests may assign a partial `window`. The shim keeps its own shape and copies
+ * `location`, `localStorage` and the listener functions from the assigned
+ * object, because libraries such as axios and PostHog read those at import
+ * time. It installs no `document`: Vue and PrismJS treat one as a full DOM.
+ *
+ * @example
+ * // test-setup.ts, preloaded through bunfig.toml
+ * const resetWindow = installWindowShim()
+ * afterEach(resetWindow)
+ */
+export function installWindowShim(href = 'http://localhost/'): () => void {
+	const shim: ShimWindow = {
+		location: locationOf(href),
+		addEventListener: noop,
+		removeEventListener: noop,
+		localStorage: createTestStorage()
+	}
+
+	const assign = (value: unknown) => {
+		if (!isObject(value)) return
+		if (value.localStorage) shim.localStorage = value.localStorage as Storage
+		shim.location =
+			isObject(value.location) && typeof value.location.href === 'string'
+				? (value.location as ShimLocation)
+				: locationOf(href)
+		shim.addEventListener =
+			typeof value.addEventListener === 'function'
+				? (value.addEventListener as ShimWindow['addEventListener'])
+				: noop
+		shim.removeEventListener =
+			typeof value.removeEventListener === 'function'
+				? (value.removeEventListener as ShimWindow['removeEventListener'])
+				: noop
+	}
+
+	const install = () => {
+		Object.defineProperty(globalThis, 'window', {
+			configurable: true,
+			enumerable: true,
+			get: () => shim,
+			set: assign
+		})
+	}
+
+	install()
+	return () => {
+		shim.location = locationOf(href)
+		shim.addEventListener = noop
+		shim.removeEventListener = noop
+		shim.localStorage = createTestStorage()
+		install()
+	}
+}

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

package/src/zod/index.ts

@@ -97,6 +97,26 @@ export const zJsonObject: z.ZodType<JsonObject> = z.record(
 	zJsonValue
 )
 
+/** An E.164 phone number: `+`, then 7 to 15 digits with no leading zero. */
+export const E164_REGEX = /^\+[1-9]\d{6,14}$/
+
+/**
+ * An optional E.164 phone number for forms: a cleared input submits `''`,
+ * which means "no number", so `''` and `null` both parse to `null`.
+ *
+ * Deliberately not `union([regex, literal('')])`: that serializes the empty
+ * literal as `enum: [""]`, which Gemini function declarations reject.
+ */
+export const zOptionalE164 = z
+	.string()
+	.refine(
+		(value) => value === '' || E164_REGEX.test(value),
+		'Phone number must be in E.164 format (e.g. +14155551234)'
+	)
+	.describe('E.164 phone number (e.g. +14155551234); empty string clears it')
+	.nullable()
+	.transform((value) => value || null)
+
 /** `JSON.parse` + `schema.safeParse` without throwing. */
 export function parseJson<S extends z.ZodType>(
 	text: string,