hanzio 1.1.0 → 2.0.0

package/src/url/index.ts

@@ -1,5 +1,150 @@
-export function getDomainFaviconUrl(domain: string, size = 128): string {
+export type UrlQueryValue = string | number | boolean | null | undefined
+export type UrlQueryParams = Record<
+	string,
+	UrlQueryValue | readonly UrlQueryValue[]
+>
+
+/**
+ * Serializes query params. Arrays repeat the key (`a=1&a=2`); `null` and
+ * `undefined` are skipped. Returns the string without a leading `?`.
+ */
+export function buildQueryString(
+	params: UrlQueryParams,
+	options: { encode?: boolean } = {}
+): string {
+	const pairs: [string, string][] = []
+	for (const [key, value] of Object.entries(params)) {
+		const values = Array.isArray(value) ? value : [value]
+		for (const item of values) {
+			if (item != null) pairs.push([key, String(item)])
+		}
+	}
+
+	if (options.encode === false) {
+		return pairs.map(([key, value]) => `${key}=${value}`).join('&')
+	}
+	return new URLSearchParams(pairs).toString()
+}
+
+/**
+ * Replaces `:name` placeholders with encoded values. Throws when a placeholder
+ * has no value. Only `:` followed by a letter or `_` counts, so ports like
+ * `:8080` are left alone.
+ */
+export function replacePathParams(
+	path: string,
+	params: Record<string, string | number | boolean | undefined> = {}
+): string {
+	return path.replace(/:([A-Za-z_]\w*)/g, (_, key: string) => {
+		const value = params[key]
+		if (value === undefined) {
+			throw new Error(`Missing required path parameter: ${key}`)
+		}
+		return encodeURIComponent(String(value))
+	})
+}
+
+/** Joins base and path with exactly one `/`, fills `:params`, appends query. */
+export function buildUrl(
+	base: string,
+	path = '',
+	options: {
+		params?: Record<string, string | number | boolean | undefined>
+		query?: UrlQueryParams
+	} = {}
+): string {
+	const joined = path
+		? `${trimTrailingSlash(base)}/${path.replace(/^\/+/, '')}`
+		: base
+	const url = replacePathParams(joined, options.params)
+	const query = options.query ? buildQueryString(options.query) : ''
+	if (!query) return url
+	return `${url}${url.includes('?') ? '&' : '?'}${query}`
+}
+
+/**
+ * Normalizes a domain or URL to its origin: adds `https://` when no scheme is
+ * given and strips any path, query or trailing slash.
+ */
+export function normalizeDomain(input: string): string {
+	const trimmed = input.trim()
+	const withScheme = /^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)
+		? trimmed
+		: `https://${trimmed}`
+	return new URL(withScheme).origin
+}
+
+/** Accepts a bare domain (`example.com`) or a full URL. */
+export function getDomainFaviconUrl(domainOrUrl: string, size = 128): string {
+	let domain = domainOrUrl
+	try {
+		if (/^[a-z][a-z\d+.-]*:\/\//i.test(domainOrUrl)) {
+			domain = new URL(domainOrUrl).hostname
+		}
+	} catch {
+		// Not a URL; use the input as-is.
+	}
 	return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(
 		domain
 	)}&sz=${size}`
 }
+
+/** Removes trailing slashes: `'https://x.com/a/'` → `'https://x.com/a'`. */
+export function trimTrailingSlash(url: string): string {
+	return url.replace(/\/+$/, '')
+}
+
+/** Prefixes `/` unless the path already starts with one. */
+export function ensureLeadingSlash(path: string): string {
+	return path.startsWith('/') ? path : `/${path}`
+}
+
+type MailtoRecipients = string | readonly string[]
+
+/**
+ * Builds a `mailto:` link. Spaces become `%20` (not `+`, which mail clients
+ * show literally) and body line breaks become `%0D%0A`.
+ */
+export function buildMailto(options: {
+	to?: MailtoRecipients
+	cc?: MailtoRecipients
+	bcc?: MailtoRecipients
+	subject?: string
+	body?: string
+}): string {
+	const { to, cc, bcc, subject, body } = options
+	const headers = Object.entries({
+		cc: cc && recipients(cc),
+		bcc: bcc && recipients(bcc),
+		subject: subject && encodeURIComponent(subject),
+		body: body && encodeURIComponent(body.replace(/\r?\n/g, '\r\n'))
+	})
+		.filter(([, value]) => value)
+		.map(([key, value]) => `${key}=${value}`)
+		.join('&')
+	return `mailto:${to ? recipients(to) : ''}${headers ? `?${headers}` : ''}`
+}
+
+function recipients(value: MailtoRecipients): string {
+	return (typeof value === 'string' ? [value] : value)
+		.map((address) => encodeURIComponent(address.trim()).replace(/%40/g, '@'))
+		.join(',')
+}
+
+/**
+ * Milliseconds to wait from a `Retry-After` header: delta-seconds (fractions
+ * allowed) or an HTTP date relative to `now`. Past dates and negative values
+ * give `0`; a missing or invalid value gives `undefined`.
+ */
+export function parseRetryAfter(
+	value: string | null | undefined,
+	now = Date.now()
+): number | undefined {
+	const trimmed = value?.trim()
+	if (!trimmed) return undefined
+	if (/^-?\d*\.?\d+$/.test(trimmed)) {
+		return Math.max(0, Number(trimmed) * 1000)
+	}
+	const date = Date.parse(trimmed)
+	return Number.isNaN(date) ? undefined : Math.max(0, date - now)
+}

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')
+}