@workerstack/database 0.21.0 → 0.22.0

package/src/codegen/format-constraints.ts

@@ -0,0 +1,114 @@
+/**
+ * A column's `format` checked against its helper and its other keys: a format sets a text's
+ * pattern, case, trim and length and an integer's range, so a transform or a bound it already
+ * holds beside it is a second rule a reader of the tables file believes; an enum's values are
+ * checked against it here, at codegen, since the DTO is the enum itself.
+ */
+import {
+	FORMATS,
+	formatTakes,
+	INTEGER_FORMATS,
+	INTEGER_SPECS,
+	type IntegerFormat,
+	TEXT_FORMATS,
+	type TextFormat,
+} from "../formats/catalog.ts"
+import type { CombColumnKind } from "../meta/column.ts"
+import type { ConstantValue } from "./analyzer-types.ts"
+
+/* the transforms a text declares, each of which a format sets itself */
+const TRANSFORMS = ["lowercase", "trim", "uppercase"] as const
+
+/** A bound's side, as a format's range names it in an error */
+type Side = "max" | "min"
+
+/** Whether `value` is one of `ids` */
+const isOneOf = <F extends string>(ids: readonly F[], value: ConstantValue): value is F =>
+	(ids as readonly ConstantValue[]).includes(value)
+
+/** A format's id as an error names it, with the article it is read with: "an iso4217", "a bcp47" */
+const anId = (format: TextFormat): string => `${/^(?:[aeio]|rfc|srgb)/.test(format) ? "an" : "a"} ${format}`
+
+/** A text format's length on one side, as an error names it: its fixed length, else that side's */
+function lengthOf(format: TextFormat, side: Side): string {
+	const { max, min } = FORMATS[format]
+	return min === max ? `length ${min}` : `${side} length ${side === "max" ? max : min}`
+}
+
+/**
+ * Refuses a declared bound the format's range already holds, or one that leaves no value in it;
+ * `named` is the range's side as an error reads it
+ */
+function refuseBounds(
+	constraints: Readonly<Record<string, ConstantValue>>,
+	{ least, most, named, place }: { least: number; most: number | null; named: (side: Side) => string; place: string },
+): void {
+	const { max, min } = constraints
+	if (typeof max === "number" && most !== null && max > most)
+		throw new Error(`${place}: max ${max} is past ${named("max")}: the format holds it`)
+	if (typeof max === "number" && max < least)
+		throw new Error(`${place}: max ${max} is below ${named("min")}: no value is both`)
+	if (typeof min === "number" && most !== null && min > most)
+		throw new Error(`${place}: min ${min} is past ${named("max")}: no value is both`)
+	if (typeof min === "number" && min < least)
+		throw new Error(`${place}: min ${min} is below ${named("min")}: the format holds it`)
+}
+
+/** Refuses the first of an enum's values its format does not take as written, naming the standard's form where the format's transforms reach it */
+function refuseEnumValues(format: TextFormat, { place, values }: { place: string; values: readonly string[] }): void {
+	const { transform } = FORMATS[format]
+	const value = values.find((each) => !formatTakes(format, each))
+	if (value === undefined) return
+	const written = transform.reduce(
+		(each, step) => (step === "trim" ? each.trim() : step === "lowercase" ? each.toLowerCase() : each.toUpperCase()),
+		value,
+	)
+	const hint = formatTakes(format, written) ? `; write the standard's form, ${JSON.stringify(written)}` : ""
+	throw new Error(`${place}: ${JSON.stringify(value)} is no ${format} value${hint}`)
+}
+
+/** Refuses what a text format already sets: a declared transform, or a length bound outside its range */
+function refuseTextKeys(format: TextFormat, constraints: Readonly<Record<string, ConstantValue>>, place: string): void {
+	const transform = TRANSFORMS.find((each) => constraints[each] === true)
+	if (transform !== undefined)
+		throw new Error(`${place}: ${anId(format)} text takes no ${transform}: the format sets its case and trim`)
+	const { max, min } = FORMATS[format]
+	refuseBounds(constraints, { least: min, most: max, named: (side) => `${format}'s ${lengthOf(format, side)}`, place })
+}
+
+/**
+ * The format a column declares, checked against its helper: an id the helper's kind knows (an
+ * integer format on c.integer, a text format on c.text and c.enum), no transform or bound the
+ * format already sets or that leaves it no value, and every c.enum value one the format takes as
+ * written. Null when none is declared; an error at `place` otherwise. The helper key check refuses a
+ * format on any other helper first, and a text's kind check one beside a kind
+ */
+export function formatOf(
+	constraints: Readonly<Record<string, ConstantValue>>,
+	{ helper, place, values }: { helper: CombColumnKind | null; place: string; values: readonly string[] | null },
+): IntegerFormat | TextFormat | null {
+	const format = constraints["format"]
+	if (format === undefined) return null
+	const integer = helper === "integer"
+	if (integer ? !isOneOf(INTEGER_FORMATS, format) : !isOneOf(TEXT_FORMATS, format)) {
+		const known = isOneOf(TEXT_FORMATS, format) || isOneOf(INTEGER_FORMATS, format)
+		const ids = integer ? `integer formats: ${INTEGER_FORMATS.join(", ")}` : `text formats: ${TEXT_FORMATS.join(", ")}`
+		throw new Error(
+			`${place}: ${known ? `c.${helper} takes no format` : "comb knows no format"} ${JSON.stringify(format)}; ${ids}`,
+		)
+	}
+	if (isOneOf(INTEGER_FORMATS, format)) {
+		const { max, min } = INTEGER_SPECS[format]
+		refuseBounds(constraints, {
+			least: min,
+			most: max,
+			named: (side) => `${format}'s ${side === "max" ? max : min}`,
+			place,
+		})
+		return format
+	}
+	const text = format as TextFormat
+	if (helper === "enum") refuseEnumValues(text, { place, values: values ?? [] })
+	else refuseTextKeys(text, constraints, place)
+	return text
+}

package/src/codegen/generators/dtos/entity-file.ts

@@ -193,7 +193,8 @@ function importLines(
 	const lines = [`import * as z from "zod"`]
 	if (table.combMeta) lines.push(`import { combMeta } from "${options.metaImportFrom ?? "@workerstack/database/meta"}"`)
 	/* a local schema kept beside a c.json import may name a comb predicate */
-	if (body.some((line) => COMB_NAMESPACE.test(line))) lines.push(combImport(options.combFrom ?? "@workerstack/database"))
+	if (body.some((line) => COMB_NAMESPACE.test(line)))
+		lines.push(combImport(options.combFrom ?? "@workerstack/database"))
 	lines.push(...schemaImportLines(options.schemaImports, options.entityDir, options.importStyle))
 	const shared = sharedImports(table, spread, options.sharedSchemas)
 	if (shared.length > 0) {

package/src/codegen/generators/dtos/example-meta.ts

@@ -3,6 +3,9 @@
  * objects over inline ones.
  */
 import type { FieldMeta } from "../../analyzer-types.ts"
+import { declaredBounds } from "./number-range.ts"
+import { textFormatOf } from "./text-format.ts"
+import { textRules } from "./text-schema.ts"
 
 const EXAMPLE_ULID = "01h5a3g8k9m2n4p6q8r0t2v4x6"
 const ALPHANUMERIC_CYCLE = "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
@@ -66,10 +69,12 @@ const NO_EXAMPLE_KINDS: ReadonlySet<string> = /* @__PURE__ */ new Set([
 ])
 
 /* sensitive or structured values get no example: the schema says enough, the value would leak */
-function hasNoExample({ combKind, constraints, dataType, dimensions, foreignKey }: FieldMeta): boolean {
+function hasNoExample({ combKind, constraints, dataType, dimensions, foreignKey, schemaJson }: FieldMeta): boolean {
 	/* a pattern decides what the value looks like, which no generic example can know; an array's
 	 * example would be its element's, of the wrong shape */
 	if (constraints.private || constraints.password || constraints.pattern !== null || foreignKey !== null) return true
+	/* a schema's rule may be a refine its published JSON Schema does not state, so comb knows no value it takes */
+	if (schemaJson !== null) return true
 	if ((dimensions ?? 0) > 0) return true
 	if (combKind === null) return dataType === "object json"
 	return NO_EXAMPLE_KINDS.has(combKind)
@@ -83,7 +88,8 @@ const SHARED_NUMBER = { integer: 42, real: 0.5, timestamp: 1_711_468_800_000 }
  * or the one bound it misses
  */
 function midpoint(field: FieldMeta, key: keyof typeof SHARED_NUMBER): ExampleResult {
-	const { max, min } = field.constraints
+	/* an integer format's range is a declared bound, as the DTO checks it */
+	const { max, min } = declaredBounds(field.constraints)
 	const fits = (value: number) => (min === null || value >= min) && (max === null || value <= max)
 	if (fits(SHARED_NUMBER[key])) return shared(key)
 	/* an integer's example is an integer within its bounds, a fractional bound rounded inward */
@@ -120,6 +126,19 @@ function textExample({ constraints: { max, min } }: FieldMeta): ExampleResult {
 	return inline(JSON.stringify(cycleOf(max !== null && max < word ? max : (min as number))))
 }
 
+/**
+ * A text format's example, the catalog's value of its standard as written, which its DTO takes;
+ * none where the column's own range, its declared bounds and length, leaves it out
+ */
+function formatExample(field: FieldMeta): ExampleResult | null | undefined {
+	const format = textFormatOf(field.constraints)
+	if (format === null) return undefined
+	const { max, min } = textRules(field.constraints, field)
+	const { length } = format.spec.example
+	if ((max !== null && length > max) || (min !== null && length < min)) return null
+	return inline(JSON.stringify(format.spec.example))
+}
+
 /** A rule's answer: an example, `null` for none at all, `undefined` when the field is not its kind */
 type Rule = (field: FieldMeta) => ExampleResult | null | undefined
 
@@ -146,6 +165,7 @@ const RULES: Rule[] = [
 	/* a state column's example is the value a row starts at, which its create alone takes */
 	({ enumValues, states }) =>
 		enumValues !== null && enumValues.length > 0 ? inline(JSON.stringify(states?.initial ?? enumValues[0])) : undefined,
+	formatExample,
 	(field) =>
 		field.combKind === "integer" || field.combKind === "real" || field.combKind === "timestamp"
 			? midpoint(field, field.combKind)

package/src/codegen/generators/dtos/field-schema.ts

@@ -13,6 +13,7 @@ import { STORABLE_TEXT_RULE } from "../../../storable-text.ts"
 import {
 	boundCode,
 	clamp,
+	declaredBounds,
 	integerRange,
 	isInteger,
 	isNumeric,
@@ -21,7 +22,7 @@ import {
 	type Range,
 	SAFE,
 } from "./number-range.ts"
-import { stated, textBase, textRules } from "./text-schema.ts"
+import { chainAllOf, stated, textBase, textRules } from "./text-schema.ts"
 
 /** A builder's answer: its base, or `undefined` when the column is not its kind */
 type Built = Base | undefined
@@ -30,12 +31,14 @@ type Built = Base | undefined
  * A c.enum, a pgEnum or an enum text column, its values read at runtime and written out; a state
  * column's create takes its machine's `initial` alone, the value a row starts at
  */
-function enumBase({ element, field, schemaType }: Build): Built {
+function enumBase({ annotations, element, field, schemaType }: Build): Built {
 	if (field.enumValues === null) return undefined
+	/* the values are the rule, each one codegen checked against the format; the format is what they mean */
+	const keys = annotations.format === null ? {} : { "x-comb-format": annotations.format }
 	const initial = field.states?.initial ?? null
 	if (schemaType === "create" && initial !== null && element !== true)
-		return plain(`z.literal(${JSON.stringify(initial)})`)
-	return plain(`z.enum(${JSON.stringify(field.enumValues)})`)
+		return plain(`z.literal(${JSON.stringify(initial)})`, keys)
+	return plain(`z.enum(${JSON.stringify(field.enumValues)})`, keys)
 }
 
 /* no engine stores U+0000 or a lone UTF-16 surrogate as sent: jsonb refuses both, Postgres text
@@ -101,8 +104,11 @@ function integerOf(annotations: FieldConstraints, range: Range, schemaType: Sche
 			`z.number().int().min(${boundCode(range.min)}).max(${boundCode(range.max)})`,
 			stated({ maximum: annotations.max, minimum: annotations.min }),
 		)
+	/* an integer format's range is a declared bound, and its id what the number means */
+	const { max, min } = declaredBounds(annotations)
 	return plain(
-		`z.number().int().min(${boundCode(clamp(annotations.min, range.min, Math.max))}).max(${boundCode(clamp(annotations.max, range.max, Math.min))})`,
+		`z.number().int().min(${boundCode(clamp(min, range.min, Math.max))}).max(${boundCode(clamp(max, range.max, Math.min))})`,
+		annotations.format === null ? {} : { "x-comb-format": annotations.format },
 	)
 }
 
@@ -217,13 +223,30 @@ export const generateFieldSchema = (
 	options: FieldSchemaOptions,
 ): string | null => fieldSchemaOf(field, schemaType, options)?.code ?? null
 
-/** The Zod base of a column of one value: the first builder's that takes it, else text */
+/** The Zod base of a column of one value: the first builder's that takes it, else text, piped into its schema */
 function baseOf(build: Build): Base {
 	for (const builder of BUILDERS) {
 		const base = builder(build)
-		if (base !== undefined) return base
+		if (base !== undefined) return piped(build, base, [])
 	}
-	return textBase(build)
+	return piped(build, textBase(build), chainAllOf(build))
+}
+
+/**
+ * `base` piped into the schema a text or number column declares, after every rule of comb's, so
+ * the schema reads the rewritten value and its issues reach the caller as it yields them; a read
+ * never refuses a stored row, so it takes none. zod publishes a pipe's input side, the base, so the
+ * schema's own input JSON Schema is published in an `allOf` after the chain's (`own`), which that
+ * `allOf` is written over, and its export's name is a key. The `allOf` is on the code, not the
+ * keys: a nullable's keys also sit beside its `anyOf`, where the schema's `type` would refuse the
+ * null the field takes
+ */
+function piped(build: Build, base: Base, own: readonly unknown[]): Base {
+	const { field, schemaType } = build
+	const [ref] = field.schemaImports
+	if (!isMutative(schemaType) || field.schemaJson === null || ref === undefined) return base
+	const code = `${base.code}.pipe(${ref.name})${metaOf({ allOf: [...own, field.schemaJson] })}`
+	return { ...base, code, keys: { ...base.keys, "x-comb-schema": ref.imported } }
 }
 
 /** What a written value of a column is held to: its bounds and the regexes it must match */

package/src/codegen/generators/dtos/ip-patterns.ts

@@ -10,22 +10,27 @@
  */
 const GROUP = "[0-9A-Fa-f]{1,4}"
 const OCTET = "(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])"
+/** Postgres's IPv4 tail: two groups, or two to four octets */
 const TAIL = `(?:${GROUP}:${GROUP}|${OCTET}(?:\\.${OCTET}){1,3})`
+/** A dotted quad: four decimal octets, none with a leading zero */
+const QUAD = `${OCTET}(?:\\.${OCTET}){3}`
+/** RFC 4291's IPv4 tail: two groups, or a dotted quad */
+const STRICT_TAIL = `(?:${GROUP}:${GROUP}|${QUAD})`
 const PREFIX = "(?:12[0-8]|1[01][0-9]|[1-9]?[0-9])"
 
 /** At most `most` + 1 groups split by `:`, or none: what stands before a `::` */
 const before = (most: number): string => `(?:(?:${GROUP}:){0,${most}}${GROUP})?`
 
-/** An IPv6 address's source: eight groups, or a `::` with up to seven around it, the last two a tail */
-function address(): string {
+/** An IPv6 address's source: eight groups, or a `::` with up to seven around it, the last two `tail` */
+function address(tail: string): string {
 	return [
-		`(?:${GROUP}:){6}${TAIL}`,
-		`::(?:${GROUP}:){5}${TAIL}`,
-		`${before(0)}::(?:${GROUP}:){4}${TAIL}`,
-		`${before(1)}::(?:${GROUP}:){3}${TAIL}`,
-		`${before(2)}::(?:${GROUP}:){2}${TAIL}`,
-		`${before(3)}::${GROUP}:${TAIL}`,
-		`${before(4)}::${TAIL}`,
+		`(?:${GROUP}:){6}${tail}`,
+		`::(?:${GROUP}:){5}${tail}`,
+		`${before(0)}::(?:${GROUP}:){4}${tail}`,
+		`${before(1)}::(?:${GROUP}:){3}${tail}`,
+		`${before(2)}::(?:${GROUP}:){2}${tail}`,
+		`${before(3)}::${GROUP}:${tail}`,
+		`${before(4)}::${tail}`,
 		`${before(5)}::${GROUP}`,
 		`${before(6)}::`,
 	].join("|")
@@ -39,11 +44,20 @@ function address(): string {
 const unformatted = (rule: string): string => `${rule}.meta({ format: void 0 })`
 
 /** An IPv6 address, as Postgres's inet reads one */
-export const ipv6Rule = (): string => unformatted(`z.stringFormat("ipv6", /^(?:${address()})$/u)`)
+export const ipv6Rule = (): string => unformatted(`z.stringFormat("ipv6", /^(?:${address(TAIL)})$/u)`)
 
 /** An IPv6 network, an address and its prefix length, as Postgres's inet and cidr read one */
-export const cidrv6Rule = (): string => unformatted(`z.stringFormat("cidrv6", /^(?:${address()})\\/${PREFIX}$/u)`)
+export const cidrv6Rule = (): string => unformatted(`z.stringFormat("cidrv6", /^(?:${address(TAIL)})\\/${PREFIX}$/u)`)
 
 /** A plain inet's rule: a host address, its netmask optional */
 export const inetRule = (): string =>
 	`z.union([${unformatted("z.ipv4()")}, ${ipv6Rule()}, ${unformatted("z.cidrv4()")}, ${cidrv6Rule()}])`
+
+/**
+ * An IPv6 address as RFC 4291 §2.2 writes one, unanchored: Postgres's rule but an IPv4 tail of four
+ * octets, never two or three, so `::ffff:1.2` is refused. The `ipv6` and `ip` text formats' source
+ */
+export const strictIpv6Source = (): string => address(STRICT_TAIL)
+
+/** An IPv4 address as a dotted quad, unanchored: the `ipv4` and `ip` text formats' source */
+export const ipv4Source = (): string => QUAD

package/src/codegen/generators/dtos/number-range.ts

@@ -1,6 +1,7 @@
 /** The range a number column holds and the bounds a written one takes, which the DTO checks and the manifest states. */
 import type { FieldMeta } from "../../analyzer-types.ts"
 import type { FieldConstraints } from "../../annotations.ts"
+import { INTEGER_SPECS, type IntegerFormat } from "../../../formats/catalog.ts"
 import type { Build } from "./build-types.ts"
 
 /* Postgres stores c.integer in int4 */
@@ -49,14 +50,32 @@ export function integerRange(field: FieldMeta, dialect: Build["dialect"]): Range
 	return field.dataType === "number int16" ? INT2 : SAFE
 }
 
+/** Whether `format` is an integer format's id, which an integer column's format always is: codegen refused any other */
+const isIntegerFormat = (format: FieldConstraints["format"]): format is IntegerFormat =>
+	format !== null && Object.hasOwn(INTEGER_SPECS, format)
+
+/**
+ * The bounds a written number is declared to: its own, joined with its integer format's range, the
+ * tighter of each pair winning
+ */
+export function declaredBounds({ format, max, min }: FieldConstraints): { max: number | null; min: number | null } {
+	if (!isIntegerFormat(format)) return { max, min }
+	const spec = INTEGER_SPECS[format]
+	return {
+		max: max === null ? spec.max : Math.min(max, spec.max),
+		min: min === null ? spec.min : Math.max(min, spec.min),
+	}
+}
+
 /** A declared bound clamped to the column's, the column's where none is declared */
 export const clamp = (declared: number | null, bound: number, pick: (a: number, b: number) => number): number =>
 	declared === null ? bound : pick(declared, bound)
 
 /** Refuses an integer's bounds, clamped to what the column holds, that leave no integer: every write would be refused */
 export function refuseNoInteger(name: string, annotations: FieldConstraints, range: Range): void {
-	const min = clamp(annotations.min, range.min, Math.max)
-	const max = clamp(annotations.max, range.max, Math.min)
+	const declared = declaredBounds(annotations)
+	const min = clamp(declared.min, range.min, Math.max)
+	const max = clamp(declared.max, range.max, Math.min)
 	if (Math.ceil(min) > Math.floor(max))
 		throw new Error(`${name}: its bounds min ${min} and max ${max} leave no integer the column holds; widen them`)
 }
@@ -67,7 +86,7 @@ export function refuseNoInteger(name: string, annotations: FieldConstraints, ran
  * none on a boolean or a timestamp comb fills
  */
 export function numberRules(field: FieldMeta, dialect: Build["dialect"]): { max: number | null; min: number | null } {
-	const { max, min } = field.constraints
+	const { max, min } = declaredBounds(field.constraints)
 	const kind = field.combKind
 	if (kind === "boolean" || kind === "createdAt" || kind === "updatedAt" || kind === "deletedAt")
 		return { max: null, min: null }

package/src/codegen/generators/dtos/schema-aliases.ts

@@ -1,5 +1,6 @@
 /**
- * The local names an entity file imports its c.json schemas under. A
+ * The local names an entity file imports its column schemas under, a c.json column's and a text or
+ * number column's alike. A
  * schema is its module's export, so two modules' `profile` are two imports: an export name more than
  * one module gives, or one a generated file declares itself, is imported under an alias that names
  * its module, `profileFromWorkSchemas`, numbered on if that is taken too. Which names keep their own
@@ -37,7 +38,7 @@ function moduleWord(ref: ImportRef, root: string): string {
 }
 
 /**
- * The analysis with each c.json schema import under a local name of its own in every file it is
+ * The analysis with each column schema import under a local name of its own in every file it is
  * imported into; `root` the project's, which a module's path is taken from
  */
 function aliasSchemaImports(analysis: AnalysisResult, root: string): AnalysisResult {
@@ -83,7 +84,8 @@ function aliasSchemaImports(analysis: AnalysisResult, root: string): AnalysisRes
 			if (ref === undefined) return field
 			return {
 				...field,
-				jsonSchemaName: names.get(keyed(ref)) as string,
+				/* a text or number column's schema is piped into, never a c.json column's type */
+				jsonSchemaName: field.jsonSchemaName === null ? null : (names.get(keyed(ref)) as string),
 				schemaImports: field.schemaImports.map(named),
 			}
 		}),

package/src/codegen/generators/dtos/text-format.ts

@@ -0,0 +1,63 @@
+/**
+ * A text column's standard format in its DTO: one check that pushes zod's `invalid_format` issue
+ * with the format's id and no message, so zod's locale or the consumer's error map words it, and
+ * the source and length bounds it holds the value to, published as the format's own. Every format
+ * is read from the catalog's spec map alone.
+ */
+import type { FieldConstraints } from "../../annotations.ts"
+import { FORMATS, type FormatSpec, type TextFormat } from "../../../formats/catalog.ts"
+import { regexExpression } from "../../utils/pattern.ts"
+import { metaOf } from "./build-types.ts"
+
+/** A declared text format: its id beside its spec */
+export type DeclaredFormat = { id: TextFormat; spec: FormatSpec }
+
+/** Whether `format` is a text format's id, which a text column's format always is: codegen refused any other */
+const isTextFormat = (format: FieldConstraints["format"]): format is TextFormat =>
+	format !== null && Object.hasOwn(FORMATS, format)
+
+/** The format a text declares; null when it declares none */
+export function textFormatOf({ format }: FieldConstraints): DeclaredFormat | null {
+	return isTextFormat(format) ? { id: format, spec: FORMATS[format] } : null
+}
+
+/** A format's source as the regex literal comb builds from it under u, as the manifest states a pattern */
+export const sourceLiteral = (source: string): string => `/${new RegExp(source, "u").source}/u`
+
+/** The test a value meets to be of `spec`'s format, as written after its transforms: its length, its source, its registry */
+function formatTest(spec: FormatSpec): string {
+	const length =
+		spec.min === spec.max
+			? [`ctx.value.length === ${spec.min}`]
+			: [
+					...(spec.min > 0 ? [`ctx.value.length >= ${spec.min}`] : []),
+					...(spec.max === null ? [] : [`ctx.value.length <= ${spec.max}`]),
+				]
+	const member = spec.member === null ? [] : [`comb.${spec.member}(ctx.value)`]
+	return [...length, `${regexExpression(sourceLiteral(spec.source))}.test(ctx.value)`, ...member].join(" && ")
+}
+
+/** A format's own length bounds as JSON Schema states them; none at a floor of 0 or no cap */
+const lengths = ({ max, min }: FormatSpec): Record<string, number> => ({
+	...(min > 0 ? { minLength: min } : {}),
+	...(max === null ? {} : { maxLength: max }),
+})
+
+/**
+ * The format's check and what it publishes: its source as `pattern`, or, beside a declared pattern
+ * zod publishes as `pattern` itself (`declaresPattern`), in an `allOf`, and its length bounds
+ */
+export function formatCheck({ id, spec }: DeclaredFormat, declaresPattern: boolean): string {
+	const issue = `{ code: "invalid_format", format: ${JSON.stringify(id)}, input: ctx.value, origin: "string" }`
+	const source = declaresPattern ? { allOf: [{ pattern: spec.source }] } : { pattern: spec.source }
+	return `.check((ctx) => { if (!(${formatTest(spec)})) ctx.issues.push(${issue}) })${metaOf({ ...source, ...lengths(spec) })}`
+}
+
+/** The bounds of `range` the format's own leave to a check of zod's: those tighter than its */
+export const tighterBounds = (
+	{ max, min }: { max: number | null; min: number | null },
+	spec: FormatSpec,
+): { max: number | null; min: number | null } => ({
+	max: max !== null && (spec.max === null || max < spec.max) ? max : null,
+	min: min !== null && min > spec.min ? min : null,
+})

package/src/codegen/generators/dtos/text-schema.ts

@@ -1,7 +1,9 @@
 /** The Zod expression of a text column: its kind, transforms and bounds, by schema type. */
+import { regexes } from "zod"
 import type { FieldConstraints } from "../../annotations.ts"
 import type { FieldMeta } from "../../analyzer-types.ts"
 import { type Base, type Build, plain } from "./build-types.ts"
+import { formatCheck, sourceLiteral, textFormatOf, tighterBounds } from "./text-format.ts"
 import { STORABLE_TEXT_RULE } from "../../../storable-text.ts"
 import { isMutative } from "./schema-type.ts"
 import { regexExpression } from "../../utils/pattern.ts"
@@ -44,10 +46,18 @@ const ID_LENGTH = { maxLength: 48, minLength: 1 }
  */
 function isIdText(annotations: FieldConstraints, field: FieldMeta): boolean {
 	const untargetedRef = field.combKind === "ref" && field.foreignKey === null
-	const declares = field.length !== null || annotations.min !== null || annotations.max !== null
+	const declares =
+		field.length !== null ||
+		annotations.min !== null ||
+		annotations.max !== null ||
+		annotations.format !== null ||
+		field.schemaJson !== null
 	return (field.combKind === "id" || field.foreignKey?.toId === true || untargetedRef) && !declares
 }
 
+/** The lesser of two upper bounds, either of which may be none */
+const lesser = (a: number | null, b: number | null): number | null => (a === null ? b : b === null ? a : Math.min(a, b))
+
 /* the shortest value each format admits, measured from its check in a test: an address
    such as a@b.cc, and https:// with one character after it, or alone as an imageUri's prefix */
 export const TEXT_FLOORS: { email: number; imageUri: number; url: number } = { email: 6, imageUri: 8, url: 9 }
@@ -65,6 +75,12 @@ const floorOf = ({ email, imageUri, url }: FieldConstraints): number =>
 function textRange(annotations: FieldConstraints, field: FieldMeta): TextRange {
 	if (isIdText(annotations, field)) return { max: ID_LENGTH.maxLength, min: ID_LENGTH.minLength }
 	const max = annotations.max ?? field.length
+	/* a format's range is its values': the tighter of it and the declared one, no floor of a required text's 1 */
+	const format = textFormatOf(annotations)
+	if (format !== null) {
+		const min = Math.max(annotations.min ?? 0, format.spec.min)
+		return { max: lesser(max, format.spec.max), min: min === 0 ? null : min }
+	}
 	const floor = floorOf(annotations)
 	if (floor > 0) return { max, min: Math.max(annotations.min ?? 0, floor) }
 	return { max, min: annotations.min ?? (field.isNotNull ? 1 : null) }
@@ -97,6 +113,9 @@ const CHAIN: Record<Transform, string> = {
  */
 export function transformsOf(annotations: FieldConstraints, mutative: boolean): Transform[] {
 	if (!mutative) return []
+	/* a format sets its own trim and case: codegen refused a declared one beside it */
+	const format = textFormatOf(annotations)
+	if (format !== null) return [...format.spec.transform]
 	if (annotations.url) return ["trim", "strip-tab-newline"]
 	if (annotations.email) return ["trim", "lowercase"]
 	const casing: Transform[] = annotations.lowercase ? ["lowercase"] : annotations.uppercase ? ["uppercase"] : []
@@ -155,6 +174,8 @@ function textKeys(build: Build): Record<string, unknown> {
 	const transform = transformKey(annotations, mutative)
 	if (isIdText(annotations, field)) return mutative ? { ...transform, ...GUARD_KEY } : stated(ID_LENGTH)
 	if (!mutative) return readKeys(build)
+	/* a format's source admits no U+0000 or surrogate, so it takes no text guard */
+	if (annotations.format !== null) return { ...transform, "x-comb-format": annotations.format }
 	if (annotations.email) return transform
 	return annotations.url ? { ...transform, ...URL_KEY, ...GUARD_KEY } : { ...transform, ...GUARD_KEY }
 }
@@ -179,7 +200,11 @@ function textBounds(build: Build, range: TextRange): string {
 		return held === null ? "" : `.max(${held})`
 	}
 	if (annotations.email) return emailBounds(annotations, range)
-	return rangeChecks(range) + writeChecks(annotations)
+	const format = textFormatOf(annotations)
+	if (format === null) return rangeChecks(range) + writeChecks(annotations)
+	/* the format's check first, then a declared bound tighter than its, as zod's own check, and a declared pattern */
+	const pattern = annotations.pattern === null ? "" : `.regex(${regexExpression(annotations.pattern)})`
+	return formatCheck(format, annotations.pattern !== null) + rangeChecks(tighterBounds(range, format.spec)) + pattern
 }
 
 /**
@@ -229,6 +254,28 @@ export function textRules(annotations: FieldConstraints, field: FieldMeta): Text
 	const range = textRange(annotations, field)
 	const declared = annotations.pattern === null ? [] : [annotations.pattern]
 	if (isIdText(annotations, field)) return { ...range, patterns: [ID_PATTERN] }
+	const format = textFormatOf(annotations)
+	/* the format's source first, as its check runs before the declared pattern's */
+	if (format !== null) return { ...range, patterns: [sourceLiteral(format.spec.source), ...declared] }
 	const kind = [annotations.url ? HTTPS : null, annotations.name ? NAME : null, annotations.imageUri ? IMAGE : null]
 	return { ...range, patterns: [...declared, ...kind.filter((each) => each !== null)] }
 }
+
+/** A regex literal's source, as zod publishes it */
+const sourceOf = (literal: string): string => literal.slice(1, literal.lastIndexOf("/"))
+
+/**
+ * The `allOf` a written text's own chain publishes: the pattern of each of two or more regexes, as
+ * zod writes them in the order they are checked, z.email()'s first, or a format's source beside a
+ * declared pattern. A schema's `allOf`, written over the chain's, carries these first
+ */
+export function chainAllOf(build: Build): Array<{ pattern: string }> {
+	const { annotations, field } = build
+	if (!isMutative(build.schemaType) || isIdText(annotations, field)) return []
+	/* a format's source as its check publishes it beside a declared pattern: the catalog's */
+	const format = textFormatOf(annotations)
+	if (format !== null) return annotations.pattern === null ? [] : [{ pattern: format.spec.source }]
+	const { patterns } = textRules(annotations, field)
+	const chain = [...(annotations.email ? [regexes.email.source] : []), ...patterns.map(sourceOf)]
+	return chain.length > 1 ? chain.map((pattern) => ({ pattern })) : []
+}

package/src/codegen/generators/manifest.ts

@@ -7,7 +7,8 @@
  */
 import path from "node:path"
 import { deriveEntityMeta, publishedPartialUniqueIndexes, publishedUniqueIndexes, writesOf } from "../entity-meta.ts"
-import type { FieldMeta, TableMeta } from "../analyzer-types.ts"
+import type { FieldMeta, ImportRef, TableMeta } from "../analyzer-types.ts"
+import type { IntegerFormat, TextFormat } from "../../formats/catalog.ts"
 import { writeGenJsonFile } from "../utils/fs.ts"
 import type { GeneratorContext } from "./context-types.ts"
 import { qualifiedName } from "../utils/table-name.ts"
@@ -57,6 +58,10 @@ type ManifestColumn = {
 	min: number | null
 	/** Every regex a written text must match, its kind's and the declared one, as JavaScript regex literals; a plain Postgres type's rule is its `kind` and `sqlType`'s */
 	patterns: string[]
+	/** The standard format a written value is checked against (`iso4217`, `iso8601-weekday`), by its id; null when the column declares none */
+	format: TextFormat | IntegerFormat | null
+	/** The export name of the zod schema a text or number column declares, which a write runs after the column's own rules; null when none, and on a c.json column, whose schema is its value's shape rather than a rule beside it */
+	schema: string | null
 	/** A text column's format, null for any other */
 	textKind: "email" | "imageUri" | "name" | "password" | "url" | null
 	/** The rewrites a written value takes before `min`, `max` and `patterns` bind it, in order: the DTO's own list (meta-contract §2.1) */
@@ -177,6 +182,7 @@ function toColumn(field: FieldMeta, dialect: GeneratorContext["dialect"]): Manif
 	const { max, maxBytes, min, patterns } = writeRules(field, dialect)
 	return {
 		enumValues: field.enumValues,
+		format: constraints.format,
 		/* what the write bodies do, read off the rule the DTOs and the stamp read, a private column's too */
 		generated: !writesOf(field).create,
 		immutable: !writesOf(field).update,
@@ -188,6 +194,8 @@ function toColumn(field: FieldMeta, dialect: GeneratorContext["dialect"]): Manif
 		notNull: field.isNotNull,
 		patterns,
 		primaryKey: field.isPrimaryKey,
+		/* a text or number column's schema is the field's one import; a c.json column's import is its value's shape, with no schemaJson */
+		schema: field.schemaJson === null ? null : (field.schemaImports[0] as ImportRef).imported,
 		textKind: textKindOf(constraints),
 		transform: transformsOf(constraints, true),
 		private: constraints.private,