@workerstack/database 0.21.0 → 0.22.1

package/docs/meta-contract.md

@@ -166,6 +166,55 @@ no `anyOf` walk. A nullable trimmed text with a `max` of 9, as codegen publishes
 - `x-comb-rectangular`: `true` on a multidimensional array: every sub-array of one level, across the
   whole level, has the same length, as Postgres stores an array: `[[1, 2], [3, 4]]` is one,
   `[[1, 2], [3]]` is not.
+- `x-comb-format`: the standard a written value is held to, by its id, on a text, an enum or an
+  integer. On a text, the value after its `x-comb-transform` matches the published `pattern` and
+  length bounds; where the id below names a registry, it is also a member of that pinned registry,
+  which no pattern states, so a reader must check it, with the predicate named, which
+  `@workerstack/database` exports, or with the release named (`HRK` matches `^[A-Z]{3}$` and is no
+  `iso4217` value: withdrawn in 2023). A text failing it gets zod's `invalid_format` issue with the
+  id as its `format` and no message of comb's, so a zod locale or error map words it. On an enum the
+  listed values are the rule, each one the format takes, and the id is what they mean; every DTO of
+  an enum publishes it, as each holds the values. On an integer the published `minimum` and
+  `maximum` are the standard's range, or a declared one inside it. A read of a text or an integer
+  publishes none. The ids, each with its standard and release:
+  - `base64url`: RFC 4648 §5 base64url, unpadded.
+  - `bcp47`: BCP 47 language tag, RFC 5646 §2.1 well-formed.
+  - `e164`: ITU-T E.164 phone number, + and up to 15 digits.
+  - `iana-time-zone`: IANA time zone name, tzdata 2026f. Registry: `isIanaTimeZone`.
+  - `ip`: IPv4 dotted quad or IPv6 address, RFC 4291 §2.2.
+  - `ipv4`: IPv4 address, dotted quad without leading zeros.
+  - `ipv6`: IPv6 address, RFC 4291 §2.2.
+  - `iso3166-1-alpha-2`: ISO 3166-1 alpha-2 country code, Debian iso-codes v4.20.1. Registry: `isIso3166Alpha2`.
+  - `iso3166-1-alpha-3`: ISO 3166-1 alpha-3 country code, Debian iso-codes v4.20.1. Registry: `isIso3166Alpha3`.
+  - `iso4217`: ISO 4217 alphabetic currency code, SIX list 2026-09-17. Registry: `isIso4217`.
+  - `iso639-1`: ISO 639-1 language code, Debian iso-codes v4.20.1. Registry: `isIso639Alpha2`.
+  - `kebab-slug`: kebab-case slug, lowercase letters and digits joined by single hyphens.
+  - `pkce-s256-challenge`: RFC 7636 §4.2 PKCE SHA-256 code challenge.
+  - `rfc1123-hostname`: RFC 1123 §2.1 host name.
+  - `semver`: Semantic Versioning 2.0.0 version.
+  - `sha256-hex`: SHA-256 digest, FIPS 180-4, lowercase hex.
+  - `sha512-hex`: SHA-512 digest, FIPS 180-4, lowercase hex.
+  - `srgb-hex`: sRGB color as #rrggbb, CSS Color 4.
+  - `srgb-hex-alpha`: sRGB color with alpha as #rrggbbaa, CSS Color 4.
+  - `ulid`: ULID, Crockford base32 in lowercase.
+  - `uts35-ca`: UTS #35 calendar (ca) key value, CLDR 49.
+  - `uts35-fw`: UTS #35 first day of the week (fw) key value, CLDR 49.
+  - `uts35-hc`: UTS #35 hour cycle (hc) key value, CLDR 49.
+  - `uts35-ms`: UTS #35 measurement system (ms) key value, CLDR 49.
+  - `uts35-mu`: UTS #35 measurement unit (mu) key value, CLDR 49.
+  - `uts35-nu`: UTS #35 numbering system (nu) key value, CLDR 49.
+  - `uuid`: RFC 9562 UUID, lowercase hex.
+  - `uuid-v4`: RFC 9562 UUID version 4, lowercase hex.
+  - `uuid-v7`: RFC 9562 UUID version 7, lowercase hex.
+  - `iso8601-month`: ISO 8601 month number, 1 January to 12 December.
+  - `iso8601-weekday`: ISO 8601 §3.2.2 weekday number, 1 Monday to 7 Sunday.
+- `x-comb-schema`: the export name of the zod schema a written text or number is piped into after
+  every other rule, on the value as rewritten; its issues reach the caller as the schema yields
+  them. The `allOf` beside it is the schema's published part: its input JSON Schema, last, after
+  the patterns of the field's own chain when that has two or more. A refine in the schema publishes
+  nothing, so a rule it states only as a refine is one the producer alone runs: a reader may take a
+  value the producer then refuses. On a nullable field the `allOf` sits on the non-null member
+  alone, as its `type` would refuse the null the field takes. A read publishes none.
 - `x-comb-minLength`, `x-comb-maxLength`, `x-comb-minimum`, `x-comb-maximum`: on a read, the
   declared bounds it states without enforcing them, so a stored row past one still reads.
 
@@ -652,7 +701,12 @@ reader joins through the manifest alone. A composite foreign key is one relation
 per column, each carrying the whole key as `key: { columns, refColumns }`, paired by position, so
 a reader joins on every column together rather than on independent pairs. Per column it carries the helper that
 declared it, its `sqlType`, the column's SQL type with its modifier as drizzle writes it (`timestamp(3) with time zone`, `interval day`, `numeric(3, -2)`), an array's that of its element, beside its `dimensions` (0 for a column of one value, 2 for `integer[][]`) and `nullElements`, whether a written element may be null, as the column's drizzle type declares it (false for a column of one value), the bounds a write takes and enum values, `textKind` (`"email"`, `"url"`, `"imageUri"`,
-`"password"`, `"name"`, or null), `transform`, the list the DTO publishes as `x-comb-transform`
+`"password"`, `"name"`, or null), `format`, the id of the standard format a write checks the
+value against (`"iso4217"`, `"iso8601-weekday"`), as `x-comb-format` publishes it (§2.1), or null
+when the column declares none, `schema`, the export name of the zod schema a text or number column
+declares, which a write runs after the column's own rules and whose published part is
+`x-comb-schema`'s (§2.1), or null when none and on a `c.json` column, whose schema is its value's
+shape rather than a rule beside it, `transform`, the list the DTO publishes as `x-comb-transform`
 (§2.1), and `generated`, `immutable` and `private` flags. `min`, `max`, `patterns` and `maxBytes`
 are what the create DTO enforces, not what the column declares, from `writeRules`, which reads
 the rules the DTO's builders read: a text's declared bounds with comb's own (a required text's 1, a

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@workerstack/database",
-	"version": "0.21.0",
+	"version": "0.22.1",
 	"description": "Database framework for Cloudflare D1, PostgreSQL, and SQLite. Schema builders, error handling, D1 sessions, sharding, codegen, migrations.",
 	"keywords": [
 		"cloudflare-d1",
@@ -124,11 +124,6 @@
 			"types": "./types/typescript-floor-types.d.ts",
 			"default": "./src/sqlite/d1/sharding/index.ts"
 		},
-		"./sqlite/patterns": {
-			"types@>=5.7": "./types/sqlite/patterns.d.ts",
-			"types": "./types/typescript-floor-types.d.ts",
-			"default": "./src/sqlite/patterns.ts"
-		},
 		"./states": {
 			"types@>=5.7": "./types/states.d.ts",
 			"types": "./types/typescript-floor-types.d.ts",
@@ -147,7 +142,8 @@
 		"prepack": "rm -rf types && cp ../../README.md ../../LICENSE . && bun run types:emit",
 		"postpack": "rm -rf types README.md LICENSE",
 		"test": "vitest run",
-		"test:bun": "bun test tests/bun",
+		"test:bun": "bun test tests/bun --path-ignore-patterns=tests/bun/differential-lists.test.ts",
+		"test:differential": "vitest run --config vitest.differential.config.ts && bun test tests/bun/differential-lists.test.ts",
 		"test:coverage": "vitest run --coverage",
 		"test:consumers": "vitest run --config vitest.consumers.config.ts",
 		"test:e2e": "vitest run --config vitest.e2e.config.ts",

package/src/cli/args.ts

@@ -55,7 +55,8 @@ export const OPTIONS: readonly OptionSpec[] = [
 	},
 	{
 		commands: ["migrate diff"],
-		description: "Write nothing: exit 1 printing the migration a diff would write, 0 in sync",
+		description:
+			"Write nothing: exit 1 printing the migration a diff would write, 0 in sync, 2 when the check could not run",
 		long: "--dry-run",
 	},
 	{ commands: ["migrate apply"], description: "Apply this one migration file", long: "--file", value: "path" },
@@ -78,7 +79,8 @@ export const OPTIONS: readonly OptionSpec[] = [
 	},
 	{
 		commands: ["migrate apply", "migrate check", "migrate status"],
-		description: "Print one JSON object (database, applied, pending, refused, unknown) as the only stdout",
+		description:
+			"Print one JSON object (database, applied, pending, refused, unknown; stoppedBy when a signal stopped the run) as the only stdout",
 		long: "--json",
 	},
 ]

package/src/cli/codegen.ts

@@ -249,7 +249,7 @@ async function generate(
 /** The databases a codegen run covers: the one --tables names, or those comb.config.ts declares */
 async function databases(positionals: readonly string[], tables: string | undefined, io: CliIo): Promise<Database[]> {
 	if (tables !== undefined) {
-		const tablesPath = tablesFile(io.cwd, tables)
+		const tablesPath = tablesFile(io.cwd, tables, "--tables")
 		return [{ db: { tables }, direct: true, exportNamespace: undefined, generators: DIRECT, name: "", tablesPath }]
 	}
 	const config = await loadCombConfig(io.cwd)
@@ -263,7 +263,7 @@ async function databases(positionals: readonly string[], tables: string | undefi
 		exportNamespace: namespaces.get(name),
 		generators: db.generators ?? GENERATORS,
 		name,
-		tablesPath: tablesFile(io.cwd, db.tables),
+		tablesPath: tablesFile(io.cwd, db.tables, "tables"),
 	}))
 }
 

package/src/cli/comb-config.ts

@@ -6,6 +6,7 @@ import * as z from "zod"
 import type { CodegenConfig, DatabaseCodegen } from "../codegen/config.ts"
 import type { FtsTableConfig } from "../codegen/generators/fts-sql.ts"
 import { codegenConfigSchema } from "../codegen/config-schema.ts"
+import { refuseNotFile } from "./file-path.ts"
 import { CliError, type CliIo } from "./output.ts"
 
 export type { CodegenConfig, DatabaseCodegen }
@@ -58,10 +59,14 @@ export function databaseIn(config: CodegenConfig, name: string, hint?: string):
 	)
 }
 
-/** The tables file `tables` names, resolved against `cwd`; a CliError when it is missing */
-export function tablesFile(cwd: string, tables: string): string {
+/**
+ * The tables file `tables` names, resolved against `cwd`, as `what` gave it (--tables, or
+ * comb.config.ts `tables`); a CliError when it is missing or not a file
+ */
+export function tablesFile(cwd: string, tables: string, what: "--tables" | "tables"): string {
 	const resolved = path.resolve(cwd, tables)
 	if (!fs.existsSync(resolved)) throw new CliError(`Tables file not found: ${resolved}`)
+	refuseNotFile(resolved, what, "point it at the module that exports the tables")
 	return resolved
 }
 
@@ -85,7 +90,7 @@ export async function declaredFts(
 
 /** The FTS5 DDL `declared` asks for, for the migration diff to keep apart from what Atlas sees */
 export async function ftsSql(cwd: string, declared: DeclaredFts, io: CliIo): Promise<string> {
-	const resolvedTables = tablesFile(cwd, declared.tables)
+	const resolvedTables = tablesFile(cwd, declared.tables, "tables")
 	const { analyze } = await import("../codegen/analyzer.ts")
 	const { generateFtsSql } = await import("../codegen/generators/fts-sql.ts")
 	return generateFtsSql((await analyze(resolvedTables, { cwd })).tables, declared.fts, io.err)

package/src/cli/file-path.ts

@@ -0,0 +1,25 @@
+/**
+ * The CLI's checks of a path or a name a command or a config gives before it reaches the
+ * filesystem, so a wrong kind is refused by name rather than as the error of whatever reads it.
+ */
+import fs from "node:fs"
+import { CliError } from "./output.ts"
+
+/**
+ * Refuse `file`, which `what` names (an option or a config field), when it exists as other than a
+ * file, saying what it is, then `fix`; a missing one is left to the caller, which refuses it its own way
+ */
+export function refuseNotFile(file: string, what: string, fix: string): void {
+	const stat = fs.statSync(file, { throwIfNoEntry: false })
+	if (stat === undefined || stat.isFile()) return
+	throw new CliError(`${what} ${file} ${stat.isDirectory() ? "is a directory, not a file" : "is not a file"}: ${fix}`)
+}
+
+/**
+ * Refuse a name a file is made from, `what` naming it, when it would name a path: one holding a
+ * separator, or `.` or `..` alone; then `usage`
+ */
+export function refusePathName(name: string, what: string, usage: string): void {
+	if (!/[/\\]/.test(name) && name !== "." && name !== "..") return
+	throw new CliError(`${what} "${name}" names a path: give a name alone, such as add_users\n${usage}`)
+}

package/src/cli/migrate-apply.ts

@@ -33,8 +33,8 @@ import type { Connection } from "../migrate/types.ts"
 import { parseArgs, type ParsedArgs } from "./args.ts"
 import { fileName, openSqliteTarget, type SqliteTarget } from "./migrate-sqlite-target.ts"
 import { resolveMigrateTarget } from "./migrate-target.ts"
-import { Refused } from "../migrate/core/refused.ts"
-import { checkPassed, CliError, type CliContext, type MigrateOutcome, Reported } from "./output.ts"
+import { asJson } from "./migrate-json.ts"
+import { checkPassed, CliError, type CliContext, type MigrateOutcome } from "./output.ts"
 
 type Mode = "apply" | "baseline" | "check" | "status"
 
@@ -220,11 +220,6 @@ async function migrateSqlite({ args, io, mode }: Request, target: Target): Promi
 	return { applied: pendingNames, pending: [] }
 }
 
-/**
- * `migrate apply|baseline|check|status`. With --json the human lines go to stderr and stdout is
- * one JSON object: the database, the files applied (or found applied) and pending, what was
- * refused, and the files whose answer was lost, which may have committed; a refusal still exits 1.
- */
 /** `mode`'s argv read: its database and options; refused by usage without one database */
 function readArgv(mode: Mode, argv: readonly string[]): { args: ParsedArgs; db: string } {
 	const args = parseArgs(argv, `migrate ${mode}`)
@@ -232,22 +227,11 @@ function readArgv(mode: Mode, argv: readonly string[]): { args: ParsedArgs; db:
 	return { args, db: args.positionals[0] as string }
 }
 
+/** `migrate apply|baseline|check|status`, with --json as one JSON object (migrate-json.ts) */
 export async function migrateApply(mode: Mode, argv: readonly string[], io: CliContext): Promise<void> {
 	const { args, db } = readArgv(mode, argv)
-	if (args.options["json"] !== true) {
-		await runMode({ args, db, io, mode })
-		return
-	}
-	const report = (outcome: MigrateOutcome, refused: string[], unknown: string[] = []) =>
-		io.out(JSON.stringify({ applied: outcome.applied, database: db, pending: outcome.pending, refused, unknown }))
-	try {
-		report(await runMode({ args, db, io: { ...io, out: io.err }, mode }), [])
-	} catch (error) {
-		/* a refusal or a failed command is an Error; a user's config can throw anything */
-		const { applied, pending, unknown } = error instanceof Refused ? error : { applied: [], pending: [], unknown: [] }
-		report({ applied, pending }, [error instanceof Error ? error.message : String(error)], unknown)
-		throw new Reported(error)
-	}
+	if (args.options["json"] === true) await asJson(db, io, (each) => runMode({ args, db, io: each, mode }))
+	else await runMode({ args, db, io, mode })
 }
 
 /**

package/src/cli/migrate-d1.ts

@@ -14,6 +14,7 @@ import { connectD1, wranglerFlags } from "../migrate/drivers/d1.ts"
 import type { D1ProviderConfig } from "../migrate/types.ts"
 import type { ParsedArgs } from "./args.ts"
 import { type MigrateTarget, refuseNoDir } from "./migrate-target.ts"
+import { refuseNotFile } from "./file-path.ts"
 import { checkPassed, CliError, type CliContext, type MigrateOutcome } from "./output.ts"
 
 type D1Mode = "apply" | "baseline" | "check" | "status"
@@ -27,7 +28,10 @@ function d1Config(request: D1Request, resolved: MigrateTarget | undefined): { co
 	if (resolved?.provider.type === "d1") {
 		if (args.options["local"] !== undefined)
 			throw new CliError("--local applies without comb.migrate.config.ts; set local: true on its d1 provider")
-		const wranglerConfig = resolved.provider.wranglerConfig ?? findWranglerConfig(resolved.configDir)
+		const configured = resolved.provider.wranglerConfig
+		const fix = `point ${db}'s d1 provider at its wrangler.json, wrangler.jsonc or wrangler.toml`
+		if (configured !== undefined) refuseNotFile(configured, "wranglerConfig", fix)
+		const wranglerConfig = configured ?? findWranglerConfig(resolved.configDir)
 		if (wranglerConfig === undefined)
 			throw new CliError(`no wrangler config next to comb.migrate.config.ts; set wranglerConfig on ${db}'s d1 provider`)
 		return { config: { ...resolved.provider, wranglerConfig }, dir: resolved.migrationsDir }

package/src/cli/migrate-json.ts

@@ -0,0 +1,48 @@
+/**
+ * `--json` for `migrate apply|baseline|check|status`: the human lines go to stderr and stdout is one
+ * JSON object, the database, the files applied (or found applied) and pending, what was refused, and
+ * the files whose answer was lost, which may have committed; a refusal still exits 1. A run a signal
+ * stopped (SIGHUP, SIGINT, SIGQUIT, SIGTERM) prints that object too, once the loop that applies files
+ * has said what committed (stopped.ts), with `stoppedBy` naming the signal, and then ends by the
+ * signal. A stop parks the run itself, so that object comes from the step held here.
+ */
+import { hold } from "../migrate/core/cleanup.ts"
+import { Refused } from "../migrate/core/refused.ts"
+import { Stopped } from "../migrate/core/stopped.ts"
+import { type CliContext, type MigrateOutcome, Reported } from "./output.ts"
+
+/** One end of a run, as the object prints it */
+type End = MigrateOutcome & { refused: string[]; stoppedBy?: NodeJS.Signals | undefined; unknown: string[] }
+
+/** `run` on `db`, its human lines on stderr and its one JSON object on `io.out` */
+export async function asJson(
+	db: string,
+	io: CliContext,
+	run: (io: CliContext) => Promise<MigrateOutcome>,
+): Promise<void> {
+	/* once: a run that fails as a signal stops it must not print a second object */
+	let printed = false
+	const report = ({ applied, pending, refused, stoppedBy, unknown }: End) => {
+		if (printed) return
+		printed = true
+		io.out(JSON.stringify({ applied, database: db, pending, refused, ...(stoppedBy && { stoppedBy }), unknown }))
+	}
+	/* held before the run, so it runs after every step the run holds: they have said what committed by then */
+	const release = hold((signal, earlier) => {
+		const found = earlier.find((each) => each instanceof Stopped)
+		/* a stop before any file applied: nothing committed, and no loop has a report to give */
+		const stopped = found ?? new Stopped(signal, `Stopped by ${signal}`, { pending: [] })
+		if (found === undefined) io.err(stopped.message)
+		report({ ...stopped, refused: [stopped.message], stoppedBy: signal, unknown: stopped.unknown })
+	})
+	try {
+		report({ ...(await run({ ...io, out: io.err })), refused: [], unknown: [] })
+	} catch (error) {
+		/* a refusal or a failed command is an Error; a user's config can throw anything */
+		const { applied, pending, unknown } = error instanceof Refused ? error : { applied: [], pending: [], unknown: [] }
+		report({ applied, pending, refused: [error instanceof Error ? error.message : String(error)], unknown })
+		throw new Reported(error)
+	} finally {
+		release()
+	}
+}

package/src/cli/migrate.ts

@@ -1,7 +1,7 @@
 /** `comb migrate`: init, diff, check, apply, baseline and status. */
 import fs from "node:fs"
 import path from "node:path"
-import { parseArgs, refuseFurther } from "./args.ts"
+import { parseArgs, refuseFurther, usageOf } from "./args.ts"
 import { binOf } from "../migrate/core/optional-peer.ts"
 import { declaredFts, ftsSql } from "./comb-config.ts"
 import {
@@ -14,7 +14,8 @@ import {
 } from "./drizzle-dialect.ts"
 import { migrateApply, needPeers } from "./migrate-apply.ts"
 import { type MigrateTarget, refuseBlank, refuseNoDir, resolveMigrateTarget } from "./migrate-target.ts"
-import { CliError, type CliContext } from "./output.ts"
+import { refusePathName } from "./file-path.ts"
+import { CliError, type CliContext, ShowHelp } from "./output.ts"
 import { scratchDir } from "../migrate/core/cleanup.ts"
 
 const DRIZZLE_CONFIG = `import { defineConfig } from "drizzle-kit"
@@ -100,10 +101,12 @@ function migrateInit(argv: readonly string[], io: CliContext): void {
  * database's dialect, directory and drizzle config come from it; without, it is SQLite in
  * ./atlas-migrations.
  */
-async function migrateDiff(argv: readonly string[], io: CliContext): Promise<void> {
+async function runDiff(argv: readonly string[], io: CliContext): Promise<void> {
 	const args = parseArgs(argv, "migrate diff")
 	/* parseArgs refuses a diff that names no database */
 	const [db, name] = args.positionals as [string, (string | undefined)?]
+	/* Atlas makes the file's name from it: a path would land outside the directory, or nowhere */
+	if (name !== undefined) refusePathName(name, "Migration name", usageOf("migrate diff"))
 	const env = args.options["env"] as string | undefined
 	const { d1, expected, exported, fts, migrationsDir, pg, provider, target } = await diffTarget(db, env, io)
 	/* a diff starts a missing directory, and refuses a file before anything runs */
@@ -229,7 +232,26 @@ function reportDrift(db: string, files: readonly string[], io: CliContext): neve
 		io.out(`-- ${path.basename(file)}`)
 		io.out(fs.readFileSync(file, "utf8"))
 	}
-	throw new CliError(`${db} has drifted from its migrations: comb migrate diff ${db} would write the SQL above`)
+	throw new Drifted(`${db} has drifted from its migrations: comb migrate diff ${db} would write the SQL above`)
+}
+
+/** A dry run's refusal for drift, which exits 1 */
+class Drifted extends CliError {}
+
+/**
+ * `migrate diff`. A dry run is a drift gate, so it exits 1 for drift alone, and 2 for every failure
+ * that kept it from checking, the argv's own refusal among them: --dry-run is read from argv, as
+ * the CLI reads --json, so that refusal knows it is a dry run's
+ */
+async function migrateDiff(argv: readonly string[], io: CliContext): Promise<void> {
+	if (!argv.includes("--dry-run")) return runDiff(argv, io)
+	try {
+		await runDiff(argv, io)
+	} catch (error) {
+		if (error instanceof Drifted || error instanceof ShowHelp) throw error
+		/* an Error: comb throws only Errors, and a config's load wraps whatever the config throws (migrate/config.ts) */
+		throw new CliError((error as Error).message, 2, { cause: error })
+	}
 }
 
 export async function cmdMigrate(argv: readonly string[], io: CliContext, help: string): Promise<void> {

package/src/codegen/analyzer-types.ts

@@ -1,3 +1,4 @@
+import type { IntegerFormat, TextFormat } from "../formats/catalog.ts"
 import type { CombColumnKind } from "../meta/column.ts"
 /**
  * TableMeta — serializable intermediate format produced by TableAnalyzer.
@@ -10,6 +11,8 @@ type FieldConstraintsMeta = {
 	autogenerate: boolean
 	/** the generated DTOs take only an email address */
 	email: boolean
+	/** the standard the value is held to: a text's or an enum's text format, an integer's integer format; null when none is declared */
+	format: TextFormat | IntegerFormat | null
 	/** an https URL or a data:image/ URI */
 	imageUri: boolean
 	/** the generated DTOs lowercase the text before they check it */
@@ -127,8 +130,10 @@ type FieldMeta = {
 	isPrimaryKey: boolean
 	/** the name the generated DTO imports a c.json column's schema under, null for any other column */
 	jsonSchemaName: string | null
-	/** the names the field's generated schema uses and must import (a c.json schema) */
+	/** the names the field's generated schema uses and must import: a c.json schema, or the zod schema a text or number column's `schema` key names */
 	schemaImports: ImportRef[]
+	/** the input JSON Schema of the zod schema a text or number column's `schema` key names, self-contained and without `$schema`, which the generated DTOs publish beside it; null for any other column. The schema's import is the field's one `schemaImports` entry */
+	schemaJson: Readonly<Record<string, unknown>> | null
 	/** a Postgres array's declared dimensions; 0 or absent for a column of one value */
 	dimensions?: number | undefined
 	/** whether a Postgres array's elements may be null, as its drizzle type declares; false or absent otherwise */

package/src/codegen/annotations.ts

@@ -5,12 +5,14 @@
  */
 import type { CombColumnKind } from "../meta/column.ts"
 import type { ConstantValue, FieldConstraintsMeta } from "./analyzer-types.ts"
+import { formatOf } from "./format-constraints.ts"
 import { patternLiteral } from "./utils/pattern.ts"
 
 /** Field constraints extracted from type arguments */
 export type FieldConstraints = FieldConstraintsMeta
 
 /* the keys of each constraint type in src/sqlite/constraints.ts, which tests/types/constraint-keys.typetest.ts holds them to */
+/* a timestamp's keys: its bounds and the flags every helper takes */
 export const NUMBER_KEYS = [
 	"autogenerate",
 	"max",
@@ -21,11 +23,57 @@ export const NUMBER_KEYS = [
 	"relation",
 	"tenant",
 ] as const
+/* a real's keys: a timestamp's, and the zod schema its value is piped into */
+export const REAL_KEYS = [
+	"autogenerate",
+	"max",
+	"min",
+	"mutable",
+	"nomutate",
+	"private",
+	"relation",
+	"schema",
+	"tenant",
+] as const
+/* an integer's keys: a real's, and the standard format that numbers its values */
+export const INTEGER_KEYS = [
+	"autogenerate",
+	"format",
+	"max",
+	"min",
+	"mutable",
+	"nomutate",
+	"private",
+	"relation",
+	"schema",
+	"tenant",
+] as const
 export const JSON_KEYS = ["autogenerate", "maxBytes", "mutable", "nomutate", "private", "relation", "tenant"] as const
-export const ENUM_KEYS = ["nomutate", "private", "tenant"] as const
+export const ENUM_KEYS = ["format", "nomutate", "private", "tenant"] as const
+/* a foreign key's keys: a text's but format and schema, as its value is another table's key */
+export const REF_KEYS = [
+	"autogenerate",
+	"email",
+	"imageUri",
+	"lowercase",
+	"max",
+	"min",
+	"mutable",
+	"name",
+	"nomutate",
+	"password",
+	"pattern",
+	"private",
+	"relation",
+	"tenant",
+	"trim",
+	"uppercase",
+	"url",
+] as const
 export const TEXT_KEYS = [
 	"autogenerate",
 	"email",
+	"format",
 	"imageUri",
 	"lowercase",
 	"max",
@@ -37,6 +85,7 @@ export const TEXT_KEYS = [
 	"pattern",
 	"private",
 	"relation",
+	"schema",
 	"tenant",
 	"trim",
 	"uppercase",
@@ -53,10 +102,10 @@ export type ConstraintKeys = {
 	readonly deletedAt: Keys
 	readonly enum: typeof ENUM_KEYS
 	readonly id: None
-	readonly integer: Keys
+	readonly integer: typeof INTEGER_KEYS
 	readonly json: typeof JSON_KEYS
-	readonly real: Keys
-	readonly ref: typeof TEXT_KEYS
+	readonly real: typeof REAL_KEYS
+	readonly ref: typeof REF_KEYS
 	readonly serialId: None
 	readonly text: typeof TEXT_KEYS
 	readonly timestamp: Keys
@@ -70,10 +119,10 @@ export const CONSTRAINT_KEYS: ConstraintKeys = {
 	deletedAt: NUMBER_KEYS,
 	enum: ENUM_KEYS,
 	id: [],
-	integer: NUMBER_KEYS,
+	integer: INTEGER_KEYS,
 	json: JSON_KEYS,
-	real: NUMBER_KEYS,
-	ref: TEXT_KEYS,
+	real: REAL_KEYS,
+	ref: REF_KEYS,
 	serialId: [],
 	text: TEXT_KEYS,
 	timestamp: NUMBER_KEYS,
@@ -115,10 +164,13 @@ const DROPPED: Readonly<Record<string, { keys: readonly string[]; said: string;
 	url: { keys: ["lowercase", "uppercase"], said: "it is kept as written, but for its trim", what: "a url" },
 }
 
-/** Refuses a second kind, or a key the one declared would drop, each of which a reader of the tables file believes holds */
+/** Refuses a second kind, a format beside a kind, or a key the one declared would drop, each of which a reader of the tables file believes holds */
 function refuseKinds(constraints: Readonly<Record<string, ConstantValue>>, place: string): void {
 	const [kind, second] = KINDS.filter((each) => constraints[each] === true)
 	if (second !== undefined) throw new Error(`${place}: ${kind} and ${second} contradict; declare one`)
+	/* a format is a text's whole rule, as a kind is */
+	if (kind !== undefined && constraints["format"] !== undefined)
+		throw new Error(`${place}: format and ${kind} contradict; declare one`)
 	const dropped = DROPPED[kind as string]
 	const key = dropped?.keys.find((each) => constraints[each] === true)
 	if (key !== undefined) throw new Error(`${place}: ${dropped?.what} takes no ${key}: ${dropped?.said}`)
@@ -180,7 +232,7 @@ function refuseMalformed(
 /**
  * A column's declared constraints, checked and with comb's defaults applied. Throws on a key the
  * helper does not take, a value of the wrong type, two keys that contradict, or bounds no value
- * meets, each message prefixed with `place`
+ * meets, or a format the helper cannot hold, each message prefixed with `place`
  */
 export function fieldConstraintsOf(
 	constraints: Readonly<Record<string, ConstantValue>>,
@@ -190,6 +242,7 @@ export function fieldConstraintsOf(
 		helper,
 		measure,
 		place,
+		values,
 	}: {
 		/** the column's property name; one starting with `_` is private */
 		fieldName: string
@@ -201,9 +254,12 @@ export function fieldConstraintsOf(
 		measure: "length" | "value"
 		/** where the column is declared, as each error message names it */
 		place: string
+		/** the column's enum values, each of which a c.enum's format must take; null when it has none */
+		values: readonly string[] | null
 	},
 ): FieldConstraints {
 	refuseMalformed(constraints, { helper, measure, place })
+	const format = formatOf(constraints, { helper, place, values })
 	const relation = constraints["relation"]
 
 	const autogenerate = filled ? constraints["autogenerate"] !== false : constraints["autogenerate"] === true
@@ -211,6 +267,7 @@ export function fieldConstraintsOf(
 	return {
 		autogenerate,
 		email: constraints["email"] === true,
+		format,
 		imageUri: constraints["imageUri"] === true,
 		lowercase: constraints["lowercase"] === true,
 		max: typeof constraints["max"] === "number" ? constraints["max"] : null,