@workerstack/database 0.21.0 → 0.22.0

package/src/codegen/runtime/read-comb.ts

@@ -1,5 +1,7 @@
-/** What the runtime reader reads of a c helper's own record: its constraints and an enum's state machine, as JSON */
-import type { SnapshotComb } from "./snapshot-types.ts"
+/** What the runtime reader reads of a c helper's own record: its constraints, a column schema and an enum's state machine, as JSON */
+import * as z from "zod"
+import type { CombColumnMeta } from "../../meta/column.ts"
+import type { ModuleExport, SnapshotComb } from "./snapshot-types.ts"
 
 const STRING_LIST = (value: unknown): value is string[] =>
 	Array.isArray(value) && value.every((item) => typeof item === "string")
@@ -21,6 +23,72 @@ function constraintsOf(raw: unknown, at: string): Record<string, boolean | numbe
 	return constraints
 }
 
+/** The packages a schema found nowhere might have been in, as its error names them; empty when every module loaded */
+const skipped = (unloaded: readonly string[]): string =>
+	unloaded.length === 0 ? "" : ` (${unloaded.join(", ")} would not load on their own)`
+
+/* the helpers whose `schema` key names a zod schema the generated DTOs pipe the value into; on any other the key stays a constraint, which the constraint check refuses by name */
+// lookup-table: the c helpers that take a column schema
+const SCHEMA_KINDS: ReadonlySet<string> = /* @__PURE__ */ new Set(["integer", "real", "text"])
+
+const DEFS = "#/$defs/"
+
+/**
+ * `node` with each `$ref` replaced by the entry of `defs` it points at, its sibling keywords kept:
+ * zod files a schema carrying an `id` under the root's `$defs`, a pointer that would dangle once the
+ * literal sits in another document's `allOf`. Every `$ref` zod writes points into `$defs`, as
+ * `cycles: "throw"` leaves no reference back to the root
+ */
+function inlined(node: unknown, defs: Readonly<Record<string, unknown>>): unknown {
+	if (Array.isArray(node)) return node.map((each) => inlined(each, defs))
+	if (typeof node !== "object" || node === null) return node
+	const { $ref, ...rest } = node as Record<string, unknown>
+	const own = Object.fromEntries(Object.entries(rest).map(([key, value]) => [key, inlined(value, defs)]))
+	if ($ref === undefined) return own
+	const name = ($ref as string).slice(DEFS.length).replaceAll("~1", "/").replaceAll("~0", "~")
+	return { ...(inlined(defs[name], defs) as object), ...own }
+}
+
+/** The input JSON Schema of a zod schema as a self-contained literal, `$schema` dropped; an error naming the column when zod has none */
+function inputJsonOf(schema: z.ZodType, at: string): Readonly<Record<string, unknown>> {
+	let json: Record<string, unknown>
+	try {
+		json = z.toJSONSchema(schema, { cycles: "throw", io: "input" }) as Record<string, unknown>
+	} catch (error) {
+		throw new Error(
+			`${at}: the schema its schema key is given has no JSON Schema form (zod: ${(error as Error).message}); comb publishes every DTO rule`,
+			{ cause: error },
+		)
+	}
+	const { $defs, $schema: _dropped, ...root } = json
+	return inlined(root, ($defs ?? {}) as Record<string, unknown>) as Record<string, unknown>
+}
+
+/**
+ * A helper's constraints with its `schema` key read: on a text or number column, taken out for the
+ * export that holds it and its input JSON Schema; on any other helper, kept as `true` for the
+ * constraint check to refuse. An error naming the column for a value that is no zod schema, and
+ * for one no module exports, naming the modules that would not load (`unloaded`)
+ */
+function columnSchemaOf(
+	meta: CombColumnMeta,
+	at: string,
+	{ locate, unloaded }: { locate: (value: unknown) => ModuleExport | null; unloaded: readonly string[] },
+): Pick<SnapshotComb, "schema" | "schemaJson"> & { constraints: Record<string, unknown> } {
+	const { schema: declared, ...constraints } = (meta.constraints ?? {}) as Record<string, unknown>
+	if (declared === undefined) return { constraints, schema: null, schemaJson: null }
+	if (!SCHEMA_KINDS.has(meta.kind))
+		return { constraints: { ...constraints, schema: true }, schema: null, schemaJson: null }
+	if (typeof declared !== "object" || declared === null || !("_zod" in declared))
+		throw new Error(`${at}: the constraint schema is no zod schema; comb's DTOs are zod 4, so the schema must be one`)
+	const schema = locate(declared)
+	if (schema === null)
+		throw new Error(
+			`${at}: no module of the project exports the schema its schema key is given${skipped(unloaded)}; export it, above the table that names it, so the generated DTOs can import it`,
+		)
+	return { constraints, schema, schemaJson: inputJsonOf(declared as z.ZodType, at) }
+}
+
 /* the keys a c.enum's state machine has; values, which docs/state-machines.md §4 holds in the same const, read from c.enum's second argument */
 const STATE_KEYS = ["initial", "terminal", "transitions", "values"]
 
@@ -141,4 +209,4 @@ function refuseJsonDocument(
 		)
 }
 
-export { constraintsOf, refuseJsonDocument, statesOf, STRING_LIST }
+export { columnSchemaOf, constraintsOf, refuseJsonDocument, skipped, statesOf, STRING_LIST }

package/src/codegen/runtime/read-tables.ts

@@ -1,16 +1,16 @@
 /**
  * The runtime reader: load the tables module, find every drizzle table it exports, and read each
  * as drizzle built it (getTableConfig) and as comb's `c` helpers recorded it (combColumnMeta).
- * Objects a generated file must import, a c.json schema or a c.enum values array, are located by
- * identity among the exports of the project modules the tables module loads.
+ * Objects a generated file must import, a c.json schema or a text or number column's schema, are
+ * located by identity among the exports of the project modules the tables module loads.
  */
 import { Column, getTableColumns, is, type SQL, type Table } from "drizzle-orm"
 import { ExtraConfigColumn, getTableConfig as pgConfig, IndexedColumn, PgDialect, PgTable } from "drizzle-orm/pg-core"
 import { getTableConfig as sqliteConfig, SQLiteDialect, SQLiteTable } from "drizzle-orm/sqlite-core"
 import { byCodeUnit } from "../utils/order.ts"
-import { combColumnMeta } from "../../meta/column.ts"
+import { combColumnMeta, type CombColumnMeta } from "../../meta/column.ts"
 import { dimensionsOf, filledByDefault, type ReadColumn, unnamedUnique } from "./read-column.ts"
-import { constraintsOf, refuseJsonDocument, statesOf, STRING_LIST } from "./read-comb.ts"
+import { columnSchemaOf, constraintsOf, refuseJsonDocument, skipped, statesOf, STRING_LIST } from "./read-comb.ts"
 import type { ElementNulls } from "./element-types.ts"
 import type {
 	ModuleExport,
@@ -52,29 +52,41 @@ type Context = {
 	unloaded: readonly string[]
 }
 
+/** Where `value` is exported, the first of `exportsHolding`; null when nowhere, or when nothing was given */
+const locate = (value: unknown, context: Context): ModuleExport | null =>
+	value === undefined ? null : (exportsHolding(value, context.loaded, context.tablesPath)[0] ?? null)
+
+/** Where a c.json column's schema is exported; an error naming the column when nowhere, or for a schema that is no stored document */
+function jsonSchemaOf(
+	meta: CombColumnMeta,
+	column: ReadColumn,
+	{ at, context }: { at: string; context: Context },
+): ModuleExport | null {
+	if (meta.kind !== "json") return null
+	const schema = locate(meta.schema, context)
+	if (schema === null)
+		throw new Error(
+			`${at}: no module of the project exports the schema its c.json is given${skipped(context.unloaded)}; export it, so the generated DTOs can import it`,
+		)
+	refuseJsonDocument(meta.schema, at, {
+		filled: filledByDefault(column),
+		notNull: column.notNull && !column.dimensions,
+	})
+	return schema
+}
+
 function combOf(column: ReadColumn, at: string, context: Context): SnapshotComb | null {
 	const meta = combColumnMeta(column)
 	if (meta === undefined) return null
-	const located = (value: unknown) =>
-		value === undefined ? null : (exportsHolding(value, context.loaded, context.tablesPath)[0] ?? null)
 	if (meta.values !== undefined && !STRING_LIST(meta.values)) throw new Error(`${at}: c.enum takes an array of strings`)
-	const schema = located(meta.schema)
-	if (meta.kind === "json" && schema === null) {
-		const skipped = context.unloaded.length === 0 ? "" : ` (${context.unloaded.join(", ")} would not load on their own)`
-		throw new Error(
-			`${at}: no module of the project exports the schema its c.json is given${skipped}; export it, so the generated DTOs can import it`,
-		)
-	}
-	if (meta.kind === "json")
-		refuseJsonDocument(meta.schema, at, {
-			filled: filledByDefault(column),
-			notNull: column.notNull && !column.dimensions,
-		})
+	const own = columnSchemaOf(meta, at, { locate: (value) => locate(value, context), unloaded: context.unloaded })
+	const schema = own.schema ?? jsonSchemaOf(meta, column, { at, context })
 	return {
-		constraints: constraintsOf(meta.constraints, at),
+		constraints: constraintsOf(own.constraints, at),
 		kind: meta.kind,
 		prefix: meta.prefix ?? null,
 		schema,
+		schemaJson: own.schemaJson,
 		states: statesOf(meta.states, at, column),
 		values: meta.values === undefined ? null : [...meta.values],
 	}

package/src/codegen/runtime/snapshot-types.ts

@@ -14,8 +14,10 @@ type SnapshotComb = {
 	constraints: Record<string, boolean | number | string>
 	kind: string
 	prefix: string | null
-	/** where the exact zod schema a c.json column was given is exported; null when nowhere */
+	/** where the exact zod schema a c.json column, or a text or number column's `schema` key, was given is exported; null when none was given */
 	schema: ModuleExport | null
+	/** a text or number column's schema as its input JSON Schema, self-contained (each `$defs` entry inlined) and `$schema` dropped; null on c.json and when undeclared */
+	schemaJson: Readonly<Record<string, unknown>> | null
 	states: { initial: string | null; terminal: string[] | null; transitions: Record<string, string[]> | null } | null
 	values: string[] | null
 }

package/src/codegen/runtime/to-meta.ts

@@ -141,14 +141,15 @@ const TYPED_COLUMNS = {
 /** What a column's `c` helper recorded, as FieldMeta names it; a plain drizzle column's own enum values */
 function combFactsOf(
 	column: SnapshotColumn,
-): Pick<FieldMeta, "enumValues" | "jsonSchemaName" | "prefix" | "schemaImports" | "states"> {
+): Pick<FieldMeta, "enumValues" | "jsonSchemaName" | "prefix" | "schemaImports" | "schemaJson" | "states"> {
 	const comb = column.comb
 	const schema = comb?.schema ?? null
 	return {
 		enumValues: comb?.values ?? column.enumValues,
-		jsonSchemaName: schema?.name ?? null,
+		jsonSchemaName: comb?.kind === "json" ? (schema as ModuleExport).name : null,
 		prefix: comb?.prefix ?? null,
 		schemaImports: schema === null ? [] : [importOf(schema)],
+		schemaJson: comb?.schemaJson ?? null,
 		states: comb?.states ?? null,
 	}
 }
@@ -172,19 +173,21 @@ function fieldOf(column: SnapshotColumn, { file, table, tables }: Build): FieldM
 			`${place}: comb has no rule for a ${column.columnType} column (${column.dataType}); build it with a c helper, or as drizzle ${TYPED_COLUMNS[table.dialect]}`,
 		)
 	const filled = isFilled(column, kind)
+	const facts = combFactsOf(column)
 	const constraints = fieldConstraintsOf(column.comb?.constraints ?? {}, {
 		fieldName: column.key,
 		filled,
 		helper: kind,
 		measure: measuredBy(column, kind),
 		place,
+		values: facts.enumValues,
 	})
 	if (constraints.mutable && column.foreignKey === null && kind !== "ref")
 		throw new Error(`${place}: mutable lets a reference move on update, and ${column.key} references nothing`)
 	if (constraints.relation !== null && column.foreignKey === null)
 		throw new Error(`${place}: relation names the relation of a key, and ${column.key} references nothing`)
 	return {
-		...combFactsOf(column),
+		...facts,
 		autoIncrement: column.autoIncrement,
 		columnType: column.columnType,
 		combKind: kind,

package/src/formats/catalog.ts

@@ -0,0 +1,255 @@
+/*
+ * The standard formats a column declares with `format`: each id's standard, the source its DTO checks,
+ * its length bounds, the transforms that run before the check, and the pinned registry a value must
+ * also belong to. The DTO's failure is zod's `invalid_format` issue with the id and no message, so a
+ * zod locale or error map translates it; the catalog carries no text a person reads but `standard`.
+ */
+import { ipv4Source, strictIpv6Source } from "../codegen/generators/dtos/ip-patterns.ts"
+import { isIanaTimeZone } from "./iana-time-zone.ts"
+import { isIso3166Alpha2, isIso3166Alpha3 } from "./iso3166-1.ts"
+import { isIso4217 } from "./iso4217.ts"
+import { isIso639Alpha2 } from "./iso639-1.ts"
+import {
+	CALENDARS,
+	FIRST_DAYS,
+	HOUR_CYCLES,
+	MEASUREMENT_SYSTEMS,
+	MEASUREMENT_UNITS,
+	NUMBERING_SYSTEMS,
+} from "./uts35.ts"
+
+/** The ids `c.text` and `c.enum` take as `format`, sorted by code unit */
+export const TEXT_FORMATS = [
+	"base64url",
+	"bcp47",
+	"e164",
+	"iana-time-zone",
+	"ip",
+	"ipv4",
+	"ipv6",
+	"iso3166-1-alpha-2",
+	"iso3166-1-alpha-3",
+	"iso4217",
+	"iso639-1",
+	"kebab-slug",
+	"pkce-s256-challenge",
+	"rfc1123-hostname",
+	"semver",
+	"sha256-hex",
+	"sha512-hex",
+	"srgb-hex",
+	"srgb-hex-alpha",
+	"ulid",
+	"uts35-ca",
+	"uts35-fw",
+	"uts35-hc",
+	"uts35-ms",
+	"uts35-mu",
+	"uts35-nu",
+	"uuid",
+	"uuid-v4",
+	"uuid-v7",
+] as const
+
+/** The ids `c.integer` takes as `format`, sorted by code unit */
+export const INTEGER_FORMATS = ["iso8601-month", "iso8601-weekday"] as const
+
+/** A text format's id */
+export type TextFormat = (typeof TEXT_FORMATS)[number]
+
+/** An integer format's id */
+export type IntegerFormat = (typeof INTEGER_FORMATS)[number]
+
+/** The registry predicate a text format's value must also satisfy */
+type Member = "isIanaTimeZone" | "isIso3166Alpha2" | "isIso3166Alpha3" | "isIso4217" | "isIso639Alpha2"
+
+/** What a text format checks, after its transforms, on the value its DTO is given */
+export type FormatSpec = {
+	/** The standard and the release it follows, as a person reads it */
+	readonly standard: string
+	/** The anchored pattern the value matches, portable to RE2 and JavaScript's `u` flag */
+	readonly source: string
+	/** The fewest characters a value has */
+	readonly min: number
+	/** The most characters a value has, or null when the format sets no cap and a column declares one */
+	readonly max: number | null
+	/** The transforms that run, in order, before the check */
+	readonly transform: readonly ("lowercase" | "trim" | "uppercase")[]
+	/** The pinned registry the value must belong to, by its predicate's name, or null when the source is the whole rule */
+	readonly member: Member | null
+	/** A value of the format as written, which the format takes and a generated DTO publishes as its example */
+	readonly example: string
+}
+
+/** The range an integer format's value lies in */
+export type IntegerSpec = {
+	/** The standard that numbers the values, as a person reads it */
+	readonly standard: string
+	/** The least value */
+	readonly min: number
+	/** The greatest value */
+	readonly max: number
+}
+
+/** The transforms a format runs before its check: trim on all, then the one case its values are written in */
+type Transforms = FormatSpec["transform"]
+const TRIM: Transforms = ["trim"]
+const LOWERCASE: Transforms = ["trim", "lowercase"]
+const UPPERCASE: Transforms = ["trim", "uppercase"]
+
+/*
+ * RFC 5646 §2.1's langtag: language (with up to three extlangs), script, region, variants, extensions
+ * and private use, each class case-insensitive; a grandfathered tag is no langtag
+ */
+const LANGUAGE = "(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,3}|[A-Za-z]{4,8})"
+const VARIANTS = "(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*"
+const EXTENSIONS = "(?:-[0-9A-WYZa-wyz](?:-[A-Za-z0-9]{2,8})+)*"
+const LANGTAG = `${LANGUAGE}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?${VARIANTS}${EXTENSIONS}(?:-[Xx](?:-[A-Za-z0-9]{1,8})+)?`
+
+/* semver.org 2.0.0's version pattern, its groups non-capturing */
+const NUMBER = "(?:0|[1-9][0-9]*)"
+const IDENTIFIER = "(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)"
+const BUILD = "(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?"
+const SEMVER = `${NUMBER}\\.${NUMBER}\\.${NUMBER}(?:-${IDENTIFIER}(?:\\.${IDENTIFIER})*)?${BUILD}`
+
+const HOST_LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?"
+const HOSTNAME = `^${HOST_LABEL}(?:\\.${HOST_LABEL})*$`
+const ZONE_NAME = "^[A-Za-z0-9_+-]+(?:/[A-Za-z0-9_+-]+){0,2}$"
+const HEX = "[0-9a-f]"
+const BASE64URL = "[A-Za-z0-9_-]"
+/* whole quads, then two or three characters: a length of 1 mod 4 encodes no byte string */
+const UNPADDED = `^(?:${BASE64URL}{4})*(?:${BASE64URL}{2,3})?$`
+
+/* the examples too long for their format's row, the digests of no bytes among them */
+const PHONE = "+385911234567"
+const ZONE = "Europe/Zagreb"
+const IPV6 = "2001:db8::1"
+const PKCE_CHALLENGE = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
+const RGBA = "#1e90ff80"
+const ULID = "01hzy3k8q2m4n5p6r7s8t9v0wx"
+const UUID_V7 = "01890a5d-ac96-774b-bcce-b302099a8057"
+const SHA256_EMPTY = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+const SHA512_EMPTY =
+	"cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e"
+const UUID_V4 = "0f8fad5b-d9cb-469f-a165-70867728950e"
+
+/* the standards whose names would widen a row past the line */
+const COUNTRY_2 = "ISO 3166-1 alpha-2 country code, Debian iso-codes v4.20.1"
+const COUNTRY_3 = "ISO 3166-1 alpha-3 country code, Debian iso-codes v4.20.1"
+const CURRENCY = "ISO 4217 alphabetic currency code, SIX list 2026-09-17"
+const LANGUAGE_CODE = "ISO 639-1 language code, Debian iso-codes v4.20.1"
+const CHALLENGE = "RFC 7636 §4.2 PKCE SHA-256 code challenge"
+const SLUG = "kebab-case slug, lowercase letters and digits joined by single hyphens"
+const ADDRESS = "IPv4 dotted quad or IPv6 address, RFC 4291 §2.2"
+const DIGEST_256 = "SHA-256 digest, FIPS 180-4, lowercase hex"
+const DIGEST_512 = "SHA-512 digest, FIPS 180-4, lowercase hex"
+const COLOR_ALPHA = "sRGB color with alpha as #rrggbbaa, CSS Color 4"
+
+/** One row of the table: a spec's fields in the order a reader scans them */
+type Row = readonly [
+	standard: string,
+	source: string,
+	min: number,
+	max: number | null,
+	transform: Transforms,
+	member: Member | null,
+	example: string,
+]
+
+/** The spec a row states */
+const spec = ([standard, source, min, max, transform, member, example]: Row): FormatSpec => ({
+	example,
+	max,
+	member,
+	min,
+	source,
+	standard,
+	transform,
+})
+
+/** RFC 9562's 8-4-4-4-12 layout in lowercase hex, its version digit and variant digit given */
+const uuid = (standard: string, [version, variant]: [string, string], example: string): FormatSpec =>
+	spec([
+		standard,
+		`^${HEX}{8}-${HEX}{4}-${version}${HEX}{3}-${variant}${HEX}{3}-${HEX}{12}$`,
+		36,
+		36,
+		LOWERCASE,
+		null,
+		example,
+	])
+
+/** A UTS #35 key's spec: an alternation of CLDR's values, the whole rule, bounded by the shortest and longest */
+function uts35(key: string, values: readonly string[], example: string): FormatSpec {
+	const lengths = values.map((value) => value.length)
+	const standard = `UTS #35 ${key} key value, CLDR 49`
+	const [min, max] = [Math.min(...lengths), Math.max(...lengths)]
+	return spec([standard, `^(?:${values.join("|")})$`, min, max, LOWERCASE, null, example])
+}
+
+/** Every text format's spec, built in a function so importing the module runs nothing */
+function specs(): { readonly [F in TextFormat]: FormatSpec } {
+	const ipv4 = ipv4Source()
+	const ipv6 = strictIpv6Source()
+	return {
+		base64url: spec(["RFC 4648 §5 base64url, unpadded", UNPADDED, 0, null, TRIM, null, "dGVzdA"]),
+		/* RFC 5646 §4.4.1's 35 is the buffer an implementation must hold, not a cap on a tag */
+		bcp47: spec(["BCP 47 language tag, RFC 5646 §2.1 well-formed", `^${LANGTAG}$`, 2, null, TRIM, null, "zh-Hant-TW"]),
+		e164: spec(["ITU-T E.164 phone number, + and up to 15 digits", "^\\+[1-9][0-9]{1,14}$", 3, 16, TRIM, null, PHONE]),
+		"iana-time-zone": spec(["IANA time zone name, tzdata 2026f", ZONE_NAME, 1, 64, TRIM, "isIanaTimeZone", ZONE]),
+		ip: spec([ADDRESS, `^(?:${ipv4}|${ipv6})$`, 2, 45, LOWERCASE, null, IPV6]),
+		ipv4: spec(["IPv4 address, dotted quad without leading zeros", `^${ipv4}$`, 7, 15, TRIM, null, "192.0.2.1"]),
+		ipv6: spec(["IPv6 address, RFC 4291 §2.2", `^(?:${ipv6})$`, 2, 45, LOWERCASE, null, IPV6]),
+		"iso3166-1-alpha-2": spec([COUNTRY_2, "^[A-Z]{2}$", 2, 2, UPPERCASE, "isIso3166Alpha2", "HR"]),
+		"iso3166-1-alpha-3": spec([COUNTRY_3, "^[A-Z]{3}$", 3, 3, UPPERCASE, "isIso3166Alpha3", "HRV"]),
+		iso4217: spec([CURRENCY, "^[A-Z]{3}$", 3, 3, UPPERCASE, "isIso4217", "EUR"]),
+		"iso639-1": spec([LANGUAGE_CODE, "^[a-z]{2}$", 2, 2, LOWERCASE, "isIso639Alpha2", "hr"]),
+		"kebab-slug": spec([SLUG, "^[a-z0-9]+(?:-[a-z0-9]+)*$", 1, 128, TRIM, null, "spring-sale-2026"]),
+		"pkce-s256-challenge": spec([CHALLENGE, `^${BASE64URL}{43}$`, 43, 43, TRIM, null, PKCE_CHALLENGE]),
+		"rfc1123-hostname": spec(["RFC 1123 §2.1 host name", HOSTNAME, 1, 253, LOWERCASE, null, "api.example.com"]),
+		semver: spec(["Semantic Versioning 2.0.0 version", `^${SEMVER}$`, 5, 256, TRIM, null, "1.4.0-rc.1"]),
+		"sha256-hex": spec([DIGEST_256, `^${HEX}{64}$`, 64, 64, LOWERCASE, null, SHA256_EMPTY]),
+		"sha512-hex": spec([DIGEST_512, `^${HEX}{128}$`, 128, 128, LOWERCASE, null, SHA512_EMPTY]),
+		"srgb-hex": spec(["sRGB color as #rrggbb, CSS Color 4", `^#${HEX}{6}$`, 7, 7, LOWERCASE, null, "#1e90ff"]),
+		"srgb-hex-alpha": spec([COLOR_ALPHA, `^#${HEX}{8}$`, 9, 9, LOWERCASE, null, RGBA]),
+		/* Crockford's base32 in lowercase, as generateUlid writes it; the first character holds 3 bits */
+		ulid: spec(["ULID, Crockford base32 in lowercase", "^[0-7][0-9a-hjkmnp-tv-z]{25}$", 26, 26, LOWERCASE, null, ULID]),
+		"uts35-ca": uts35("calendar (ca)", CALENDARS, "gregory"),
+		"uts35-fw": uts35("first day of the week (fw)", FIRST_DAYS, "mon"),
+		"uts35-hc": uts35("hour cycle (hc)", HOUR_CYCLES, "h23"),
+		"uts35-ms": uts35("measurement system (ms)", MEASUREMENT_SYSTEMS, "metric"),
+		"uts35-mu": uts35("measurement unit (mu)", MEASUREMENT_UNITS, "celsius"),
+		"uts35-nu": uts35("numbering system (nu)", NUMBERING_SYSTEMS, "latn"),
+		uuid: uuid("RFC 9562 UUID, lowercase hex", [HEX, HEX], UUID_V4),
+		"uuid-v4": uuid("RFC 9562 UUID version 4, lowercase hex", ["4", "[89ab]"], UUID_V4),
+		"uuid-v7": uuid("RFC 9562 UUID version 7, lowercase hex", ["7", "[89ab]"], UUID_V7),
+	}
+}
+
+/** Every text format's spec, by id */
+export const FORMATS: { readonly [F in TextFormat]: FormatSpec } = /* @__PURE__ */ specs()
+
+/** Every integer format's range, by id */
+export const INTEGER_SPECS: { readonly [F in IntegerFormat]: IntegerSpec } = {
+	"iso8601-month": { max: 12, min: 1, standard: "ISO 8601 month number, 1 January to 12 December" },
+	"iso8601-weekday": { max: 7, min: 1, standard: "ISO 8601 §3.2.2 weekday number, 1 Monday to 7 Sunday" },
+}
+
+const MEMBERS: { readonly [M in Member]: (value: string) => boolean } = {
+	isIanaTimeZone,
+	isIso3166Alpha2,
+	isIso3166Alpha3,
+	isIso4217,
+	isIso639Alpha2,
+}
+
+/**
+ * Whether `format` takes `value` exactly as written, its transforms not run: within the format's
+ * length bounds, matching its source, and a member of its registry when it names one. Never throws.
+ */
+export function formatTakes(format: TextFormat, value: string): boolean {
+	const { max, member, min, source } = FORMATS[format]
+	if (value.length < min || (max !== null && value.length > max)) return false
+	if (!new RegExp(source, "u").test(value)) return false
+	return member === null || MEMBERS[member](value)
+}

package/src/formats/iana-time-zone.ts

@@ -0,0 +1,117 @@
+// Written by `bun scripts/registries.ts` from the pinned release below: edit the script, not this file.
+// IANA tzdata 2026f: https://data.iana.org/time-zones/releases/tzdata2026f.tar.gz
+// every Zone and Link name of africa, antarctica, asia, australasia, europe, northamerica, southamerica, etcetera, backward; Factory dropped
+
+// lookup-table: the 597 time zone names of tzdata 2026f, one line per area, read by isIanaTimeZone
+const NAMES: ReadonlySet<string> = /* @__PURE__ */ new Set(
+	/* @__PURE__ */ `Africa/Abidjan Africa/Accra Africa/Addis_Ababa Africa/Algiers Africa/Asmara Africa/Asmera Africa/Bamako
+Africa/Bangui Africa/Banjul Africa/Bissau Africa/Blantyre Africa/Brazzaville Africa/Bujumbura Africa/Cairo
+Africa/Casablanca Africa/Ceuta Africa/Conakry Africa/Dakar Africa/Dar_es_Salaam Africa/Djibouti Africa/Douala
+Africa/El_Aaiun Africa/Freetown Africa/Gaborone Africa/Harare Africa/Johannesburg Africa/Juba Africa/Kampala
+Africa/Khartoum Africa/Kigali Africa/Kinshasa Africa/Lagos Africa/Libreville Africa/Lome Africa/Luanda
+Africa/Lubumbashi Africa/Lusaka Africa/Malabo Africa/Maputo Africa/Maseru Africa/Mbabane Africa/Mogadishu
+Africa/Monrovia Africa/Nairobi Africa/Ndjamena Africa/Niamey Africa/Nouakchott Africa/Ouagadougou
+Africa/Porto-Novo Africa/Sao_Tome Africa/Timbuktu Africa/Tripoli Africa/Tunis Africa/Windhoek
+America/Adak America/Anchorage America/Anguilla America/Antigua America/Araguaina
+America/Argentina/Buenos_Aires America/Argentina/Catamarca America/Argentina/ComodRivadavia
+America/Argentina/Cordoba America/Argentina/Jujuy America/Argentina/La_Rioja America/Argentina/Mendoza
+America/Argentina/Rio_Gallegos America/Argentina/Salta America/Argentina/San_Juan America/Argentina/San_Luis
+America/Argentina/Tucuman America/Argentina/Ushuaia America/Aruba America/Asuncion America/Atikokan
+America/Atka America/Bahia America/Bahia_Banderas America/Barbados America/Belem America/Belize
+America/Blanc-Sablon America/Boa_Vista America/Bogota America/Boise America/Buenos_Aires America/Cambridge_Bay
+America/Campo_Grande America/Cancun America/Caracas America/Catamarca America/Cayenne America/Cayman
+America/Chicago America/Chihuahua America/Ciudad_Juarez America/Coral_Harbour America/Cordoba
+America/Costa_Rica America/Coyhaique America/Creston America/Cuiaba America/Curacao America/Danmarkshavn
+America/Dawson America/Dawson_Creek America/Denver America/Detroit America/Dominica America/Edmonton
+America/Eirunepe America/El_Salvador America/Ensenada America/Fort_Nelson America/Fort_Wayne America/Fortaleza
+America/Glace_Bay America/Godthab America/Goose_Bay America/Grand_Turk America/Grenada America/Guadeloupe
+America/Guatemala America/Guayaquil America/Guyana America/Halifax America/Havana America/Hermosillo
+America/Indiana/Indianapolis America/Indiana/Knox America/Indiana/Marengo America/Indiana/Petersburg
+America/Indiana/Tell_City America/Indiana/Vevay America/Indiana/Vincennes America/Indiana/Winamac
+America/Indianapolis America/Inuvik America/Iqaluit America/Jamaica America/Jujuy America/Juneau
+America/Kentucky/Louisville America/Kentucky/Monticello America/Knox_IN America/Kralendijk America/La_Paz
+America/Lima America/Los_Angeles America/Louisville America/Lower_Princes America/Maceio America/Managua
+America/Manaus America/Marigot America/Martinique America/Matamoros America/Mazatlan America/Mendoza
+America/Menominee America/Merida America/Metlakatla America/Mexico_City America/Miquelon America/Moncton
+America/Monterrey America/Montevideo America/Montreal America/Montserrat America/Nassau America/New_York
+America/Nipigon America/Nome America/Noronha America/North_Dakota/Beulah America/North_Dakota/Center
+America/North_Dakota/New_Salem America/Nuuk America/Ojinaga America/Panama America/Pangnirtung
+America/Paramaribo America/Phoenix America/Port-au-Prince America/Port_of_Spain America/Porto_Acre
+America/Porto_Velho America/Puerto_Rico America/Punta_Arenas America/Rainy_River America/Rankin_Inlet
+America/Recife America/Regina America/Resolute America/Rio_Branco America/Rosario America/Santa_Isabel
+America/Santarem America/Santiago America/Santo_Domingo America/Sao_Paulo America/Scoresbysund
+America/Shiprock America/Sitka America/St_Barthelemy America/St_Johns America/St_Kitts America/St_Lucia
+America/St_Thomas America/St_Vincent America/Swift_Current America/Tegucigalpa America/Thule
+America/Thunder_Bay America/Tijuana America/Toronto America/Tortola America/Vancouver America/Virgin
+America/Whitehorse America/Winnipeg America/Yakutat America/Yellowknife
+Antarctica/Casey Antarctica/Davis Antarctica/DumontDUrville Antarctica/Macquarie Antarctica/Mawson
+Antarctica/McMurdo Antarctica/Palmer Antarctica/Rothera Antarctica/South_Pole Antarctica/Syowa
+Antarctica/Troll Antarctica/Vostok
+Arctic/Longyearbyen
+Asia/Aden Asia/Almaty Asia/Amman Asia/Anadyr Asia/Aqtau Asia/Aqtobe Asia/Ashgabat Asia/Ashkhabad Asia/Atyrau
+Asia/Baghdad Asia/Bahrain Asia/Baku Asia/Bangkok Asia/Barnaul Asia/Beirut Asia/Bishkek Asia/Brunei
+Asia/Calcutta Asia/Chita Asia/Choibalsan Asia/Chongqing Asia/Chungking Asia/Colombo Asia/Dacca Asia/Damascus
+Asia/Dhaka Asia/Dili Asia/Dubai Asia/Dushanbe Asia/Famagusta Asia/Gaza Asia/Harbin Asia/Hebron
+Asia/Ho_Chi_Minh Asia/Hong_Kong Asia/Hovd Asia/Irkutsk Asia/Istanbul Asia/Jakarta Asia/Jayapura Asia/Jerusalem
+Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Kashgar Asia/Kathmandu Asia/Katmandu Asia/Khandyga Asia/Kolkata
+Asia/Krasnoyarsk Asia/Kuala_Lumpur Asia/Kuching Asia/Kuwait Asia/Macao Asia/Macau Asia/Magadan Asia/Makassar
+Asia/Manila Asia/Muscat Asia/Nicosia Asia/Novokuznetsk Asia/Novosibirsk Asia/Omsk Asia/Oral Asia/Phnom_Penh
+Asia/Pontianak Asia/Pyongyang Asia/Qatar Asia/Qostanay Asia/Qyzylorda Asia/Rangoon Asia/Riyadh Asia/Saigon
+Asia/Sakhalin Asia/Samarkand Asia/Seoul Asia/Shanghai Asia/Singapore Asia/Srednekolymsk Asia/Taipei
+Asia/Tashkent Asia/Tbilisi Asia/Tehran Asia/Tel_Aviv Asia/Thimbu Asia/Thimphu Asia/Tokyo Asia/Tomsk
+Asia/Ujung_Pandang Asia/Ulaanbaatar Asia/Ulan_Bator Asia/Urumqi Asia/Ust-Nera Asia/Vientiane Asia/Vladivostok
+Asia/Yakutsk Asia/Yangon Asia/Yekaterinburg Asia/Yerevan
+Atlantic/Azores Atlantic/Bermuda Atlantic/Canary Atlantic/Cape_Verde Atlantic/Faeroe Atlantic/Faroe
+Atlantic/Jan_Mayen Atlantic/Madeira Atlantic/Reykjavik Atlantic/South_Georgia Atlantic/St_Helena
+Atlantic/Stanley
+Australia/ACT Australia/Adelaide Australia/Brisbane Australia/Broken_Hill Australia/Canberra Australia/Currie
+Australia/Darwin Australia/Eucla Australia/Hobart Australia/LHI Australia/Lindeman Australia/Lord_Howe
+Australia/Melbourne Australia/NSW Australia/North Australia/Perth Australia/Queensland Australia/South
+Australia/Sydney Australia/Tasmania Australia/Victoria Australia/West Australia/Yancowinna
+Brazil/Acre Brazil/DeNoronha Brazil/East Brazil/West
+CET CST6CDT
+Canada/Atlantic Canada/Central Canada/Eastern Canada/Mountain Canada/Newfoundland Canada/Pacific
+Canada/Saskatchewan Canada/Yukon
+Chile/Continental Chile/EasterIsland
+Cuba EET EST EST5EDT Egypt Eire
+Etc/GMT Etc/GMT+0 Etc/GMT+1 Etc/GMT+10 Etc/GMT+11 Etc/GMT+12 Etc/GMT+2 Etc/GMT+3 Etc/GMT+4 Etc/GMT+5 Etc/GMT+6
+Etc/GMT+7 Etc/GMT+8 Etc/GMT+9 Etc/GMT-0 Etc/GMT-1 Etc/GMT-10 Etc/GMT-11 Etc/GMT-12 Etc/GMT-13 Etc/GMT-14
+Etc/GMT-2 Etc/GMT-3 Etc/GMT-4 Etc/GMT-5 Etc/GMT-6 Etc/GMT-7 Etc/GMT-8 Etc/GMT-9 Etc/GMT0 Etc/Greenwich Etc/UCT
+Etc/UTC Etc/Universal Etc/Zulu
+Europe/Amsterdam Europe/Andorra Europe/Astrakhan Europe/Athens Europe/Belfast Europe/Belgrade Europe/Berlin
+Europe/Bratislava Europe/Brussels Europe/Bucharest Europe/Budapest Europe/Busingen Europe/Chisinau
+Europe/Copenhagen Europe/Dublin Europe/Gibraltar Europe/Guernsey Europe/Helsinki Europe/Isle_of_Man
+Europe/Istanbul Europe/Jersey Europe/Kaliningrad Europe/Kiev Europe/Kirov Europe/Kyiv Europe/Lisbon
+Europe/Ljubljana Europe/London Europe/Luxembourg Europe/Madrid Europe/Malta Europe/Mariehamn Europe/Minsk
+Europe/Monaco Europe/Moscow Europe/Nicosia Europe/Oslo Europe/Paris Europe/Podgorica Europe/Prague Europe/Riga
+Europe/Rome Europe/Samara Europe/San_Marino Europe/Sarajevo Europe/Saratov Europe/Simferopol Europe/Skopje
+Europe/Sofia Europe/Stockholm Europe/Tallinn Europe/Tirane Europe/Tiraspol Europe/Ulyanovsk Europe/Uzhgorod
+Europe/Vaduz Europe/Vatican Europe/Vienna Europe/Vilnius Europe/Volgograd Europe/Warsaw Europe/Zagreb
+Europe/Zaporozhye Europe/Zurich
+GB GB-Eire GMT GMT+0 GMT-0 GMT0 Greenwich HST Hongkong Iceland
+Indian/Antananarivo Indian/Chagos Indian/Christmas Indian/Cocos Indian/Comoro Indian/Kerguelen Indian/Mahe
+Indian/Maldives Indian/Mauritius Indian/Mayotte Indian/Reunion
+Iran Israel Jamaica Japan Kwajalein Libya MET MST MST7MDT
+Mexico/BajaNorte Mexico/BajaSur Mexico/General
+NZ NZ-CHAT Navajo PRC PST8PDT
+Pacific/Apia Pacific/Auckland Pacific/Bougainville Pacific/Chatham Pacific/Chuuk Pacific/Easter Pacific/Efate
+Pacific/Enderbury Pacific/Fakaofo Pacific/Fiji Pacific/Funafuti Pacific/Galapagos Pacific/Gambier
+Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Johnston Pacific/Kanton Pacific/Kiritimati
+Pacific/Kosrae Pacific/Kwajalein Pacific/Majuro Pacific/Marquesas Pacific/Midway Pacific/Nauru Pacific/Niue
+Pacific/Norfolk Pacific/Noumea Pacific/Pago_Pago Pacific/Palau Pacific/Pitcairn Pacific/Pohnpei Pacific/Ponape
+Pacific/Port_Moresby Pacific/Rarotonga Pacific/Saipan Pacific/Samoa Pacific/Tahiti Pacific/Tarawa
+Pacific/Tongatapu Pacific/Truk Pacific/Wake Pacific/Wallis Pacific/Yap
+Poland Portugal ROC ROK Singapore Turkey UCT
+US/Alaska US/Aleutian US/Arizona US/Central US/East-Indiana US/Eastern US/Hawaii US/Indiana-Starke US/Michigan
+US/Mountain US/Pacific US/Samoa
+UTC Universal W-SU WET Zulu`.split(/\s/u),
+)
+
+/**
+ * Whether `value` names a time zone of IANA tzdata 2026f, exactly as written: a zone or a link to one, such as
+ * Europe/Zagreb, America/Argentina/Buenos_Aires, Etc/GMT+5, UTC or US/Pacific. Case counts, and Factory, a
+ * placeholder, is no zone. Any string is taken; this never throws.
+ */
+export function isIanaTimeZone(value: string): boolean {
+	return NAMES.has(value)
+}