hanzio 1.0.0

package/src/typedswitch/index.ts

@@ -0,0 +1,309 @@
+/**
+ * typedSwitch - A type-safe switch statement for discriminated unions
+ *
+ * Supports two input modes:
+ *
+ * 1. STRING INPUT - switch on a string/enum value directly:
+ *
+ *    @example
+ *    const status: 'success' | 'error' = 'success'
+ *
+ *    // All cases required (no default)
+ *    typedSwitch(status, {
+ *      success: (val) => 'handled success',
+ *      error: (val) => 'handled error',
+ *    })
+ *
+ *    // Partial cases with default handler
+ *    typedSwitch(status, {
+ *      success: (val) => 'handled success',
+ *    }, (val) => 'default handler')
+ *
+ *
+ * 2. OBJECT INPUT - switch on a discriminated union with custom key:
+ *
+ *    @example
+ *    type Event =
+ *      | { type: 'click'; x: number; y: number }
+ *      | { type: 'scroll'; offset: number }
+ *
+ *    // All cases required (no default)
+ *    typedSwitch(event, 'type', {
+ *      click: (e) => `Clicked at ${e.x}, ${e.y}`,
+ *      scroll: (e) => `Scrolled ${e.offset}px`,
+ *    })
+ *
+ *    // Partial cases with default handler
+ *    typedSwitch(event, 'type', {
+ *      click: (e) => `Clicked at ${e.x}, ${e.y}`,
+ *    }, (e) => 'unhandled event')
+ *
+ *    // Works with any discriminant key (not just 'type')
+ *    type Order = { status: 'pending' } | { status: 'completed' }
+ *    typedSwitch(order, 'status', {
+ *      pending: (o) => 'waiting...',
+ *      completed: (o) => 'done!',
+ *    })
+ *
+ *
+ * 3. WITH CONSTRAINT - use `typedSwitch<T>` to enforce return type:
+ *
+ *    @example
+ *    interface HasId { id: string }
+ *
+ *    // All handlers must return something with { id: string }
+ *    typedSwitch<HasId>(status, {
+ *      success: () => ({ id: '123', name: 'John' }), // ✓ OK
+ *      error: () => ({ id: '456' }), // ✓ OK
+ *    })
+ *
+ *    // Type error - missing 'id' property
+ *    typedSwitch<HasId>(status, {
+ *      success: () => ({ name: 'John' }), // ✗ Error!
+ *      error: () => ({ id: '456' }),
+ *    })
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Helper types for return type inference
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Extract raw return type from a handler function (preserves Promise) */
+// biome-ignore lint/suspicious/noExplicitAny: Required for type extraction from functions
+type RawHandlerReturnType<T> = T extends (...args: any[]) => infer R ? R : never
+
+/** Get union of all raw return types from a cases object's values */
+type RawCasesReturnType<Cases> = {
+	[K in keyof Cases]: Cases[K] extends undefined
+		? never
+		: RawHandlerReturnType<Cases[K]>
+}[keyof Cases]
+
+// ═══════════════════════════════════════════════════════════════════════════
+// String input mode types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Cases for string input - all cases required */
+export type StringSwitchCases<T extends string, R> = {
+	[K in T]: (value: K) => R | Promise<R>
+}
+
+/** Partial cases for string input (when default is provided) */
+export type PartialStringSwitchCases<T extends string, R> = {
+	[K in T]?: (value: K) => R | Promise<R>
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Object input mode types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Cases for object input with custom key - all cases required */
+export type ObjectSwitchCases<T, K extends keyof T, R> = T[K] extends string
+	? {
+			[V in T[K]]: (value: Extract<T, Record<K, V>>) => 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 string
+	? {
+			[V in T[K]]?: (value: Extract<T, Record<K, V>>) => R | Promise<R>
+		}
+	: never
+
+type Handler = (value: unknown) => unknown
+type CasesRecord = Record<string, Handler | undefined>
+
+function runSwitch(
+	value: string | Record<string, unknown>,
+	keyOrCases: string | CasesRecord,
+	casesOrDefault?: CasesRecord | Handler,
+	defaultCase?: Handler
+): unknown {
+	let key: string
+	let cases: CasesRecord
+	let defaultHandler: Handler | undefined
+	let discriminantKey: string | undefined
+
+	if (typeof value === 'string') {
+		// String input: typedSwitch(string, cases, default?)
+		key = value
+		cases = keyOrCases as CasesRecord
+		defaultHandler = casesOrDefault as Handler | undefined
+	} else {
+		// Object input: typedSwitch(obj, key, cases, default?)
+		if (typeof keyOrCases !== 'string') {
+			throw new Error(
+				'Invalid typedSwitch call: object mode requires a string discriminant key'
+			)
+		}
+
+		discriminantKey = keyOrCases
+		const discriminantValue = value[discriminantKey]
+		if (typeof discriminantValue !== 'string') {
+			throw new Error(
+				`Invalid discriminant value for key "${discriminantKey}": expected string, received ${typeof discriminantValue}`
+			)
+		}
+
+		key = discriminantValue
+		cases = casesOrDefault as CasesRecord
+		defaultHandler = defaultCase
+	}
+
+	const handler = cases[key]
+
+	if (handler) {
+		return handler(value)
+	}
+
+	if (defaultHandler) {
+		return defaultHandler(value)
+	}
+
+	const availableCases = Object.keys(cases).join(', ')
+	const availableCasesSuffix =
+		availableCases.length > 0
+			? ` Available cases: ${availableCases}`
+			: ' Available cases: (none)'
+	const contextSuffix = discriminantKey
+		? ` (discriminant key: "${discriminantKey}")`
+		: ''
+
+	throw new Error(
+		`Unhandled case: ${key}${contextSuffix}.${availableCasesSuffix}`
+	)
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Function overloads
+// ═══════════════════════════════════════════════════════════════════════════
+
+// String input - all cases required (no default)
+export function typedSwitch<
+	T extends string,
+	Cases extends { [K in T]: (value: K) => unknown }
+>(value: T, cases: Cases): RawCasesReturnType<Cases>
+
+// String input - partial cases allowed (with default)
+export function typedSwitch<
+	T extends string,
+	Cases extends { [K in T]?: (value: K) => unknown },
+	DefaultCase extends (value: T) => unknown
+>(
+	value: T,
+	cases: Cases,
+	defaultCase: DefaultCase
+): RawCasesReturnType<Cases> | RawHandlerReturnType<DefaultCase>
+
+// Object input with key - all cases required (no default)
+export function typedSwitch<
+	T extends Record<string, unknown>,
+	K extends keyof T,
+	TKey extends T[K] & string,
+	Cases extends { [V in TKey]: (value: Extract<T, Record<K, V>>) => unknown }
+>(value: T, key: K, cases: Cases): RawCasesReturnType<Cases>
+
+// Object input with key - partial cases allowed (with default)
+export function typedSwitch<
+	T extends Record<string, unknown>,
+	K extends keyof T,
+	TKey extends T[K] & string,
+	Cases extends { [V in TKey]?: (value: Extract<T, Record<K, V>>) => unknown },
+	DefaultCase extends (value: T) => unknown
+>(
+	value: T,
+	key: K,
+	cases: Cases,
+	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: {
+		[V in T[K] & string]: (value: Extract<T, Record<K, V>>) => 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: {
+		[V in T[K] & string]: (
+			value: Extract<T, Record<K, V>>
+		) => 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: {
+		[V in T[K] & string]?: (value: Extract<T, Record<K, V>>) => 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: {
+		[V in T[K] & string]?: (
+			value: Extract<T, Record<K, V>>
+		) => Constraint | Promise<Constraint>
+	},
+	defaultCase: (value: T) => Constraint | Promise<Constraint>
+): Constraint | Promise<Constraint>
+
+// Implementation
+export function typedSwitch(
+	value: string | Record<string, unknown>,
+	keyOrCases: string | CasesRecord,
+	casesOrDefault?: CasesRecord | Handler,
+	defaultCase?: Handler
+): unknown {
+	return runSwitch(value, keyOrCases, casesOrDefault, defaultCase)
+}

package/src/url/index.ts

@@ -0,0 +1,5 @@
+export function getDomainFaviconUrl(domain: string, size = 128): string {
+	return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(
+		domain
+	)}&sz=${size}`
+}

package/src/zod/index.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+
+export { jsonToZodSchemaMapper } from './jsonToZodSchemaMapper'
+export {
+	toGteLteFilter,
+	type ZodMinMaxFilter,
+	zodMinMaxFilter
+} from './zodMinMaxFilter'
+export { zodToExample, zodToTypeString } from './zodToTypeString'
+
+export type GenericId<TypeName extends string> = string & z.$brand<TypeName>
+
+export function createZId<TypeName extends string>(typeName: TypeName) {
+	return z.string().min(1, `${typeName} ID is required`).brand<TypeName>()
+}
+
+export function zSingleOrArray<T extends z.ZodType>(
+	schema: T
+): z.ZodUnion<readonly [z.ZodArray<T>, T]> {
+	return z.union([z.array(schema), schema])
+}
+
+export function normalizeSingleOrArray<T>(
+	value: T | readonly T[] | null | undefined
+): T[] {
+	if (value == null) return []
+	if (Array.isArray(value)) return [...(value as readonly T[])]
+	return [value as T]
+}

package/src/zod/jsonToZodSchemaMapper.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+
+type PropertyConfig<T, U> = {
+	[K in keyof T]?: (jsonObject: U) => T[K]
+}
+
+export function jsonToZodSchemaMapper<
+	T extends z.ZodType,
+	U extends Record<string, any>
+>(
+	jsonObject: U,
+	zodSchema: T,
+	config: PropertyConfig<z.infer<T>, U>
+): z.infer<T> {
+	const result: Partial<z.infer<T>> = {}
+
+	const shape = zodSchema instanceof z.ZodObject ? zodSchema.shape : {}
+
+	for (const key of Object.keys(shape)) {
+		const fieldConfig = config[key as keyof z.infer<T>]
+		let value: any = jsonObject[key as keyof U]
+
+		if (fieldConfig) {
+			value = fieldConfig(jsonObject)
+		}
+
+		if (
+			shape[key] instanceof z.ZodObject &&
+			value &&
+			typeof value === 'object'
+		) {
+			// @ts-expect-error recursive mapper narrows key by shape iteration
+			result[key] = jsonToZodSchemaMapper(
+				value,
+				shape[key] as z.ZodObject,
+				(config[key as keyof z.infer<T>] || {}) as PropertyConfig<any, any>
+			)
+		} else {
+			result[key as keyof z.infer<T>] = value
+		}
+	}
+
+	return zodSchema.parse(result)
+}

package/src/zod/zodMinMaxFilter.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+
+export const zodMinMaxFilter = z.object({
+	min: z.number().optional(),
+	max: z.number().optional()
+})
+
+export type ZodMinMaxFilter = z.infer<typeof zodMinMaxFilter>
+
+/**
+ * Maps a min/max filter to a generic `gte`/`lte` range object (e.g. ORM-friendly).
+ * Returns `undefined` if both bounds are undefined.
+ */
+export function toGteLteFilter(
+	filter: ZodMinMaxFilter | undefined
+): { gte?: number; lte?: number } | undefined {
+	if (!filter) return undefined
+
+	const hasMin = filter.min !== undefined
+	const hasMax = filter.max !== undefined
+
+	if (!hasMin && !hasMax) return undefined
+
+	return {
+		...(hasMin && { gte: filter.min }),
+		...(hasMax && { lte: filter.max })
+	}
+}

package/src/zod/zodToTypeString.ts

@@ -0,0 +1,222 @@
+import type { z } from 'zod'
+
+// Helper to safely get a property from an unknown def object
+function getDefProp<T>(def: unknown, prop: string): T | undefined {
+	return (def as Record<string, unknown>)?.[prop] as T | undefined
+}
+
+/**
+ * Convert a Zod schema to a human-readable TypeScript-like interface string
+ */
+export function zodToTypeString(schema: z.ZodType, indent = 0): string {
+	const pad = '  '.repeat(indent)
+	const innerPad = '  '.repeat(indent + 1)
+
+	// Get the schema definition - try both Zod 4 and Zod 3 patterns
+	const def =
+		(schema as unknown as { _zod?: { def: unknown } })._zod?.def ??
+		(schema as unknown as { _def: unknown })._def
+
+	if (!def) return 'unknown'
+
+	// Zod 4 uses 'type' property with lowercase values (e.g., 'object', 'string')
+	// Zod 3 uses 'typeName' with 'Zod' prefix (e.g., 'ZodObject', 'ZodString')
+	const schemaType =
+		getDefProp<string>(def, 'type') ?? getDefProp<string>(def, 'typeName')
+
+	switch (schemaType) {
+		// Zod 4 lowercase types
+		case 'object': {
+			const shape = getDefProp<Record<string, z.ZodType>>(def, 'shape')
+			if (!shape || Object.keys(shape).length === 0) return '{}'
+
+			const fields = Object.entries(shape).map(([key, value]) => {
+				// Zod 4: check value.type === 'optional', Zod 3: check _def.typeName
+				const valueType = getDefProp<string>(
+					(value as unknown as { _zod?: { def: unknown } })._zod?.def ??
+						(value as unknown as { _def?: unknown })._def,
+					'type'
+				)
+				const isOptional = valueType === 'optional'
+				const innerSchema = isOptional
+					? (getDefProp<z.ZodType>(
+							(value as unknown as { _zod?: { def: unknown } })._zod?.def ??
+								(value as unknown as { _def?: unknown })._def,
+							'innerType'
+						) ?? value)
+					: value
+				const typeStr = zodToTypeString(innerSchema, indent + 1)
+				return `${innerPad}${key}${isOptional ? '?' : ''}: ${typeStr}`
+			})
+
+			return `{\n${fields.join('\n')}\n${pad}}`
+		}
+
+		case 'array': {
+			// Zod 4 uses 'element', Zod 3 uses 'type'
+			const itemType =
+				getDefProp<z.ZodType>(def, 'element') ??
+				getDefProp<z.ZodType>(def, 'type')
+			return itemType ? `${zodToTypeString(itemType, indent)}[]` : 'unknown[]'
+		}
+
+		case 'string':
+			return 'string'
+
+		case 'number':
+			return 'number'
+
+		case 'boolean':
+			return 'boolean'
+
+		case 'date':
+			return 'Date'
+
+		case 'null':
+			return 'null'
+
+		case 'undefined':
+			return 'undefined'
+
+		case 'any':
+			return 'any'
+
+		case 'unknown':
+			return 'unknown'
+
+		case 'record': {
+			const valueType = getDefProp<z.ZodType>(def, 'valueType')
+			return valueType
+				? `Record<string, ${zodToTypeString(valueType, indent)}>`
+				: 'Record<string, unknown>'
+		}
+
+		case 'enum': {
+			const values = getDefProp<string[]>(def, 'values')
+			return values ? values.map((v) => `"${v}"`).join(' | ') : 'string'
+		}
+
+		case 'literal': {
+			const value = getDefProp<unknown>(def, 'value')
+			return typeof value === 'string' ? `"${value}"` : String(value)
+		}
+
+		case 'union': {
+			const options = getDefProp<z.ZodType[]>(def, 'options')
+			return options
+				? options.map((o) => zodToTypeString(o, indent)).join(' | ')
+				: 'unknown'
+		}
+
+		case 'optional': {
+			const inner = getDefProp<z.ZodType>(def, 'innerType')
+			return inner ? `${zodToTypeString(inner, indent)} | undefined` : 'unknown'
+		}
+
+		case 'nullable': {
+			const inner = getDefProp<z.ZodType>(def, 'innerType')
+			return inner ? `${zodToTypeString(inner, indent)} | null` : 'unknown'
+		}
+
+		case 'default': {
+			const inner = getDefProp<z.ZodType>(def, 'innerType')
+			return inner ? zodToTypeString(inner, indent) : 'unknown'
+		}
+
+		// Zod 3 compatibility (with 'Zod' prefix)
+		case 'ZodObject':
+		case 'ZodArray':
+		case 'ZodString':
+		case 'ZodNumber':
+		case 'ZodBoolean':
+		case 'ZodDate':
+		case 'ZodNull':
+		case 'ZodUndefined':
+		case 'ZodAny':
+		case 'ZodUnknown':
+		case 'ZodRecord':
+		case 'ZodEnum':
+		case 'ZodLiteral':
+		case 'ZodUnion':
+		case 'ZodOptional':
+		case 'ZodNullable':
+		case 'ZodDefault':
+			// For Zod 3, recurse with the lowercase version
+			return zodToTypeString(schema, indent)
+
+		default:
+			return 'unknown'
+	}
+}
+
+/**
+ * Generate example JSON from a Zod schema
+ */
+export function zodToExample(schema: z.ZodType): unknown {
+	const def =
+		(schema as unknown as { _zod?: { def: unknown } })._zod?.def ??
+		(schema as unknown as { _def: unknown })._def
+	if (!def) return null
+
+	// Zod 4 uses 'type', Zod 3 uses 'typeName'
+	const schemaType =
+		getDefProp<string>(def, 'type') ?? getDefProp<string>(def, 'typeName')
+
+	switch (schemaType) {
+		case 'object': {
+			const shape = getDefProp<Record<string, z.ZodType>>(def, 'shape')
+			if (!shape) return {}
+			const result: Record<string, unknown> = {}
+			for (const [key, value] of Object.entries(shape)) {
+				const valueType = getDefProp<string>(
+					(value as unknown as { _zod?: { def: unknown } })._zod?.def ??
+						(value as unknown as { _def?: unknown })._def,
+					'type'
+				)
+				const isOptional = valueType === 'optional'
+				if (!isOptional) {
+					result[key] = zodToExample(value)
+				}
+			}
+			return result
+		}
+
+		case 'array': {
+			// Zod 4 uses 'element', Zod 3 uses 'type'
+			const itemType =
+				getDefProp<z.ZodType>(def, 'element') ??
+				getDefProp<z.ZodType>(def, 'type')
+			// Always return array with one item for better example
+			return itemType ? [zodToExample(itemType)] : []
+		}
+
+		case 'string':
+			return ''
+
+		case 'number':
+			return 0
+
+		case 'boolean':
+			return false
+
+		case 'enum': {
+			const values = getDefProp<string[]>(def, 'values')
+			return values?.[0] ?? ''
+		}
+
+		case 'literal':
+			return getDefProp<unknown>(def, 'value')
+
+		case 'optional':
+		case 'default': {
+			const inner = getDefProp<z.ZodType>(def, 'innerType')
+			return inner ? zodToExample(inner) : null
+		}
+
+		case 'record':
+			return {}
+
+		default:
+			return null
+	}
+}