hanzio 1.2.0 → 2.0.0

package/src/zod/index.ts

@@ -1,8 +1,21 @@
 import { z } from 'zod'
+import { toArray } from '../array'
+import { err, ok, type Result } from '../promise'
+import type { JsonObject, JsonValue } from '../string'
+
+export {
+	getEnumValues,
+	getObjectShape,
+	unwrapSchema,
+	zodDefaults
+} from './introspect'
 
 export { jsonToZodSchemaMapper } from './jsonToZodSchemaMapper'
 export {
+	createMinMaxFilter,
+	type MinMaxFilter,
 	toGteLteFilter,
+	toGtLtFilter,
 	type ZodMinMaxFilter,
 	zodMinMaxFilter
 } from './zodMinMaxFilter'
@@ -10,8 +23,96 @@ 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 createZId<TypeName extends string>(
+	typeName: TypeName,
+	{ prefix = '' }: { prefix?: string } = {}
+) {
+	return z
+		.string()
+		.min(1, `${typeName} ID is required`)
+		.startsWith(prefix, `${typeName} ID must start with "${prefix}"`)
+		.brand<TypeName>()
+}
+
+/** Branded string id: `Id<'User'>` is not assignable to `Id<'Organization'>`. */
+export type Id<TypeName extends string> = GenericId<TypeName>
+
+/** Brands a string without checking it (fixtures, trusted sources). */
+export function asId<TypeName extends string>(value: string): Id<TypeName> {
+	return value as Id<TypeName>
+}
+
+/** Validates a non-empty string and brands it; throws a `ZodError` otherwise. */
+export function parseId<TypeName extends string>(
+	typeName: TypeName,
+	value: unknown
+): Id<TypeName> {
+	return createZId(typeName).parse(value) as Id<TypeName>
+}
+
+export function safeParseId<TypeName extends string>(
+	typeName: TypeName,
+	value: unknown
+): Result<Id<TypeName>, z.ZodError> {
+	// `.brand()` output stays deferred for a generic TypeName
+	return toResult(createZId(typeName).safeParse(value)) as Result<
+		Id<TypeName>,
+		z.ZodError
+	>
+}
+
+/**
+ * Binds the id helpers to a project's union of entity names once:
+ * `export const { zId, asId, parseId, safeParseId } = createIdHelpers<'User' | 'Organization'>()`
+ */
+export function createIdHelpers<TypeNames extends string>() {
+	return {
+		zId: <T extends TypeNames>(typeName: T) => createZId(typeName),
+		asId: asId as <T extends TypeNames>(value: string) => Id<T>,
+		parseId: parseId as <T extends TypeNames>(
+			typeName: T,
+			value: unknown
+		) => Id<T>,
+		safeParseId: safeParseId as <T extends TypeNames>(
+			typeName: T,
+			value: unknown
+		) => Result<Id<T>, z.ZodError>
+	}
+}
+
+/** Any JSON value (no `undefined`, `NaN` or `Infinity`). */
+export const zJsonValue: z.ZodType<JsonValue> = z.lazy(() =>
+	z.union([
+		z.string(),
+		z.number(),
+		z.boolean(),
+		z.null(),
+		z.array(zJsonValue),
+		zJsonObject
+	])
+)
+
+export const zJsonObject: z.ZodType<JsonObject> = z.record(
+	z.string(),
+	zJsonValue
+)
+
+/** `JSON.parse` + `schema.safeParse` without throwing. */
+export function parseJson<S extends z.ZodType>(
+	text: string,
+	schema: S
+): Result<z.output<S>, SyntaxError | z.ZodError> {
+	let value: unknown
+	try {
+		value = JSON.parse(text)
+	} catch (error) {
+		return { ok: false, data: null, error: error as SyntaxError }
+	}
+	return toResult(schema.safeParse(value))
+}
+
+function toResult<T>(result: z.ZodSafeParseResult<T>): Result<T, z.ZodError> {
+	return result.success ? ok(result.data) : err(result.error)
 }
 
 export function zSingleOrArray<T extends z.ZodType>(
@@ -20,10 +121,5 @@ export function zSingleOrArray<T extends z.ZodType>(
 	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]
-}
+/** @deprecated Use `toArray` from `hanzio`. */
+export const normalizeSingleOrArray = toArray

package/src/zod/introspect.ts

@@ -0,0 +1,103 @@
+import type { z } from 'zod'
+import { type Def, defOf, type Schema, walk } from './zodToTypeString'
+
+// Pipes are read from their input side, except preprocess (`in` is a transform)
+function pipeInput(def: z.core.$ZodPipeDef): Schema {
+	return defOf(def.in).type === 'transform' ? def.out : def.in
+}
+
+function unwrapOnce(def: Def): Schema | undefined {
+	switch (def.type) {
+		case 'optional':
+		case 'nullable':
+		case 'default':
+		case 'prefault':
+		case 'nonoptional':
+		case 'catch':
+		case 'readonly':
+			return def.innerType
+		case 'lazy':
+			return def.getter()
+		case 'pipe':
+			return pipeInput(def)
+		default:
+			return undefined
+	}
+}
+
+/**
+ * Strips optional/nullable/default/prefault/nonoptional/catch/readonly/lazy
+ * wrappers and pipes (input side) until the schema that carries the shape.
+ */
+export function unwrapSchema(schema: Schema): Schema {
+	const inner = unwrapOnce(defOf(schema))
+	return inner ? unwrapSchema(inner) : schema
+}
+
+/** Values of a (possibly wrapped) `z.enum`, stringified; `undefined` for other schemas. */
+export function getEnumValues(schema: Schema): string[] | undefined {
+	const def = defOf(unwrapSchema(schema))
+	return def.type === 'enum'
+		? Object.values(def.entries).map(String)
+		: undefined
+}
+
+/** Shape of a (possibly wrapped) `z.object`; `undefined` for other schemas. */
+export function getObjectShape(
+	schema: Schema
+): Readonly<Record<string, Schema>> | undefined {
+	const def = defOf(unwrapSchema(schema))
+	return def.type === 'object' ? def.shape : undefined
+}
+
+/**
+ * Initial form state for a schema: `.default()` values, `undefined` for
+ * optional, `null` for nullable, first enum/literal/union option, `''`, `0`,
+ * `false`, `[]`, and objects filled per key. Other types give `undefined`.
+ * The result is typed as the schema output but is NOT validated (`''` fails
+ * `.min(1)`, dates stay `undefined`).
+ */
+export function zodDefaults<S extends Schema>(schema: S): z.output<S> {
+	return defaultFor(schema) as z.output<S>
+}
+
+function defaultFor(schema: Schema): unknown {
+	return walk(schema, undefined, (def): unknown => {
+		switch (def.type) {
+			case 'default':
+			case 'prefault':
+				return def.defaultValue
+			case 'optional':
+				return undefined
+			case 'nullable':
+				return null
+			case 'object': {
+				const result: Record<string, unknown> = {}
+				for (const [key, child] of Object.entries(def.shape)) {
+					result[key] = defaultFor(child)
+				}
+				return result
+			}
+			case 'array':
+				return []
+			case 'string':
+				return ''
+			case 'number':
+				return 0
+			case 'bigint':
+				return 0n
+			case 'boolean':
+				return false
+			case 'enum':
+				return Object.values(def.entries)[0]
+			case 'literal':
+				return def.values[0]
+			case 'union':
+				return def.options[0] && defaultFor(def.options[0])
+			default: {
+				const inner = unwrapOnce(def)
+				return inner && defaultFor(inner)
+			}
+		}
+	})
+}

package/src/zod/jsonToZodSchemaMapper.ts

@@ -1,7 +1,18 @@
 import { z } from 'zod'
+import { isRecord } from '../guard'
+
+type ObjectConfig<V> =
+	V extends Record<string, unknown>
+		? PropertyConfig<V, Record<string, any>>
+		: never
+
+// Nested objects (and arrays of objects) take a config for the nested JSON value
+type NestedConfig<V> = V extends readonly (infer E)[]
+	? ObjectConfig<E>
+	: ObjectConfig<V>
 
 type PropertyConfig<T, U> = {
-	[K in keyof T]?: (jsonObject: U) => T[K]
+	[K in keyof T]?: ((jsonObject: U) => T[K]) | NestedConfig<NonNullable<T[K]>>
 }
 
 export function jsonToZodSchemaMapper<
@@ -12,33 +23,45 @@ export function jsonToZodSchemaMapper<
 	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 : {}
+	return zodSchema.parse(mapObject(jsonObject, zodSchema, config))
+}
 
-	for (const key of Object.keys(shape)) {
-		const fieldConfig = config[key as keyof z.infer<T>]
-		let value: any = jsonObject[key as keyof U]
+function mapObject(
+	jsonObject: Record<string, any>,
+	schema: z.core.$ZodType,
+	config: Record<string, unknown>
+): Record<string, unknown> {
+	const shape = schema instanceof z.ZodObject ? schema.shape : {}
+	const result: Record<string, unknown> = {}
 
-		if (fieldConfig) {
-			value = fieldConfig(jsonObject)
+	for (const [key, fieldSchema] of Object.entries(shape)) {
+		const fieldConfig = config[key]
+		if (typeof fieldConfig === 'function') {
+			result[key] = fieldConfig(jsonObject)
+			continue
 		}
 
-		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>
+		const nested = (fieldConfig ?? {}) as Record<string, unknown>
+		const value = jsonObject[key]
+		const inner = unwrap(fieldSchema)
+		const element = inner instanceof z.ZodArray && unwrap(inner.element)
+
+		if (inner instanceof z.ZodObject && isRecord(value)) {
+			result[key] = mapObject(value, inner, nested)
+		} else if (element instanceof z.ZodObject && Array.isArray(value)) {
+			result[key] = value.map((item) =>
+				isRecord(item) ? mapObject(item, element, nested) : item
 			)
 		} else {
-			result[key as keyof z.infer<T>] = value
+			result[key] = value
 		}
 	}
 
-	return zodSchema.parse(result)
+	return result
+}
+
+function unwrap(schema: z.core.$ZodType): z.core.$ZodType {
+	return schema instanceof z.ZodOptional || schema instanceof z.ZodNullable
+		? unwrap(schema.unwrap())
+		: schema
 }

package/src/zod/zodMinMaxFilter.ts

@@ -1,19 +1,24 @@
 import { z } from 'zod'
 
-export const zodMinMaxFilter = z.object({
-	min: z.number().optional(),
-	max: z.number().optional()
-})
+/**
+ * Creates a `{ min?, max? }` filter schema for any comparable value schema,
+ * e.g. `createMinMaxFilter(z.coerce.date())`.
+ */
+export function createMinMaxFilter<T extends z.ZodType>(schema: T) {
+	return z.object({ min: schema.optional(), max: schema.optional() })
+}
+
+export const zodMinMaxFilter = createMinMaxFilter(z.number())
 
 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 {
+export type MinMaxFilter<T> = { min?: T; max?: T }
+
+function toRange<T>(
+	filter: MinMaxFilter<T> | undefined,
+	lower: string,
+	upper: string
+): Record<string, T> | undefined {
 	if (!filter) return undefined
 
 	const hasMin = filter.min !== undefined
@@ -22,7 +27,26 @@ export function toGteLteFilter(
 	if (!hasMin && !hasMax) return undefined
 
 	return {
-		...(hasMin && { gte: filter.min }),
-		...(hasMax && { lte: filter.max })
+		...(hasMin && { [lower]: filter.min as T }),
+		...(hasMax && { [upper]: filter.max as T })
 	}
 }
+
+/**
+ * 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<T>(
+	filter: MinMaxFilter<T> | undefined
+): { gte?: T; lte?: T } | undefined {
+	return toRange(filter, 'gte', 'lte')
+}
+
+/**
+ * Exclusive variant of `toGteLteFilter`, mapping min/max to `gt`/`lt`.
+ */
+export function toGtLtFilter<T>(
+	filter: MinMaxFilter<T> | undefined
+): { gt?: T; lt?: T } | undefined {
+	return toRange(filter, 'gt', 'lt')
+}