@workerstack/database 0.21.0 → 0.22.0

package/README.md

@@ -4,6 +4,8 @@ Database framework for Cloudflare D1, PostgreSQL, and SQLite. Dialect-agnostic c
 
 This repo is the source of the [`@workerstack/database`](https://www.npmjs.com/package/@workerstack/database) npm package. The CLI binary is `comb`.
 
+Moved from `@lovrozagar/comb`: `@workerstack/database@0.21.0` is the same release as `@lovrozagar/comb@0.21.0` under the new name, and the old package is deprecated. To switch, follow step 3 of [Upgrading to 0.22](#upgrading-to-022).
+
 This README is the full usage manual. An agent that reads only this file should be able to define tables, generate artifacts, run migrations, and serve list queries without opening source.
 
 ## Table of contents
@@ -18,7 +20,8 @@ This README is the full usage manual. An agent that reads only this file should
   - [SQLite factories](#sqlite-factories)
   - [PostgreSQL factories](#postgresql-factories)
   - [Constraints](#constraints)
-  - [Patterns](#patterns)
+  - [Formats](#formats)
+  - [Column schemas](#column-schemas)
 - [Errors](#errors)
   - [`CombError`](#comberror)
   - [Constraint maps](#constraint-maps)
@@ -49,6 +52,7 @@ This README is the full usage manual. An agent that reads only this file should
 - [Package exports](#package-exports)
 - [Repository layout](#repository-layout)
 - [Develop](#develop)
+- [Upgrading to 0.22](#upgrading-to-022)
 - [Upgrading to 0.21](#upgrading-to-021)
 - [Upgrading to 0.20.1](#upgrading-to-0201)
 - [Upgrading to 0.20](#upgrading-to-020)
@@ -150,7 +154,6 @@ Define a table with Comb's column factories instead of Drizzle's raw ones.
 /* src/db/core.tables.ts */
 import { sqliteTable, index } from "drizzle-orm/sqlite-core"
 import { c } from "@workerstack/database/sqlite/columns"
-import { patterns } from "@workerstack/database/sqlite/patterns"
 import * as z from "zod"
 
 /* a c.json schema is exported, so the generated DTOs can import it, and is the stored document:
@@ -163,7 +166,7 @@ export const author = sqliteTable(
 		id: c.id("aut"),
 		email: c.text("email", { max: 254, email: true, lowercase: true, trim: true }),
 		display_name: c.text("display_name", { min: 2, max: 64, trim: true }),
-		locale: c.text("locale", { pattern: patterns.LOCALE }),
+		locale: c.text("locale", { format: "bcp47" }),
 		settings: c.json("settings", authorSettings),
 		created_at: c.createdAt("created_at"),
 		updated_at: c.updatedAt("updated_at"),
@@ -183,7 +186,7 @@ export const post = sqliteTable("post", {
 })
 ```
 
-The second argument to each factory is a **constraint object**. At runtime most of it is inert — `c.text("title", { max: 200 })` just becomes `text("title", { length: 200 })` — and the helper records it on the column for codegen, which turns `{ min: 2, max: 64, trim: true }` into a Zod schema, a CHECK constraint, and an OpenAPI description. Constraints live next to the column, once. Codegen loads the tables module, so a constraint value is whatever the module computes: a constant (`pattern: patterns.E164_PHONE`, `max: NAME_MAX`), an enum member, an object spread over another, a constraint object passed by name, or an enum list built by a call. Each value must be a boolean, a number or a string; `pattern` is a `/source/flags` string.
+The second argument to each factory is a **constraint object**. At runtime most of it is inert — `c.text("title", { max: 200 })` just becomes `text("title", { length: 200 })` — and the helper records it on the column for codegen, which turns `{ min: 2, max: 64, trim: true }` into a Zod schema, a CHECK constraint, and an OpenAPI description. Constraints live next to the column, once. Codegen loads the tables module, so a constraint value is whatever the module computes: a constant (`pattern: SKU_PATTERN`, `max: NAME_MAX`), an enum member, an object spread over another, a constraint object passed by name, or an enum list built by a call. Each value must be a boolean, a number or a string; `pattern` is a `/source/flags` string, and `schema`, the one value of another kind, an exported zod schema ([Column schemas](#column-schemas)).
 
 Point a config at the file:
 
@@ -322,6 +325,8 @@ The constraint object is shared by both dialects. `@workerstack/database/sqlite/
 | `min` / `max`                    | text, integer, real | length or numeric bounds                                                                                                                                                                                                     |
 | `maxBytes`                       | json                | UTF-8 byte bound on the serialized value, on writes                                                                                                                                                                          |
 | `pattern`                        | text                | regex, as a source-level string                                                                                                                                                                                              |
+| `format`                         | text, enum, integer | a standard by its id: a text's pattern, case, length and registry, an enum's values checked at codegen, an integer's range ([Formats](#formats))                                                                             |
+| `schema`                         | text, integer, real | an exported zod schema the write DTOs pipe the value into after comb's own rules ([Column schemas](#column-schemas))                                                                                                         |
 | `email` / `url`                  | text                | an email checked by zod's email pattern, which publishes; a url by the WHATWG URL parser, https only, its https pattern published; neither publishes a `format`                                                              |
 | `trim`, `lowercase`, `uppercase` | text                | transforms applied in generated schemas                                                                                                                                                                                      |
 | `password`                       | text                | a stored password hash: kept as written, held to its declared bounds and pattern alone; `passwordText()` holds the plaintext                                                                                                 |
@@ -350,19 +355,155 @@ const signIn = z.object({ email: z.email(), password: passwordText.typed() })
 
 `passwordText()` sets a password: any storable text of 15 to 128 characters, counted by code point, with no composition rule and nothing trimmed. A password used only beside a second factor may take `passwordText({ min: 8 })`, as rev 4 allows; `min` and `max` are yours to set. `passwordText.typed()` reads one typed to sign in and holds only the max, so a password set under an older or shorter minimum still signs in. Both normalize the value to NFC before they count it, and give the NFC string, so a password typed in another normalization hashes to the same value; an app that adopts it over hashes made from input it never normalized rehashes each one on its next successful sign-in. Under `{ hash: "bcrypt" }` both refuse past 72 UTF-8 bytes, which bcrypt reads no further than, and publish `x-comb-maxUtf8Bytes: 72`, the string's own bytes (`x-comb-maxBytes` is a JSON text's); `passwordText({ hash: "bcrypt", min })` with a `min` past 72 throws, as no password would pass it. The JSON Schema states the rewrite as `x-comb-transform: ["nfc"]` and the bounds as `minLength` and `maxLength`, which count the NFC form's code points, and a password out of bounds is zod's own `too_small` or `too_big` issue with its `minimum` or `maximum`, bcrypt's bytes included.
 
-### Patterns
+### Formats
+
+`format` holds a column to a published standard, named by its id: a `c.text` value's syntax, case and length, and its membership where the standard is a registry; a `c.enum`'s listed values, at codegen; a `c.integer`'s range. Like every constraint it shapes the generated DTOs alone, with no CHECK and no change to the column's type, the same on SQLite, D1 and Postgres, and a column stays nullable unless `.notNull()`: a null passes, a value is checked.
+
+```ts
+import { sqliteTable } from "drizzle-orm/sqlite-core"
+import { c } from "@workerstack/database/sqlite/columns"
+
+export const users = sqliteTable("users", {
+	id: c.id("usr"),
+	currency: c.text("currency", { format: "iso4217" }),
+	time_zone: c.text("time_zone", { format: "iana-time-zone" }),
+	locale: c.text("locale", { format: "bcp47" }),
+	country: c.text("country", { format: "iso3166-1-alpha-2" }),
+	pay_currency: c.enum("pay_currency", ["USD", "EUR", "GBP"], { format: "iso4217" }),
+	hour_cycle: c.enum("hour_cycle", ["h12", "h23"], { format: "uts35-hc" }),
+	week_start: c.integer("week_start", { format: "iso8601-weekday" }), // 1 Monday … 7 Sunday
+})
+```
+
+A text format trims the value, then writes it in its standard's case, before it checks it. The table names each text format's standard and release, the case a written value is put in, and the registry it must also belong to; an editor shows the same list on the `format` key.
+
+| Format                | Standard                                                               | Case       | Registry          |
+| --------------------- | ---------------------------------------------------------------------- | ---------- | ----------------- |
+| `base64url`           | RFC 4648 §5 base64url, unpadded                                        | kept       |                   |
+| `bcp47`               | BCP 47 language tag, RFC 5646 §2.1 well-formed                         | kept       |                   |
+| `e164`                | ITU-T E.164 phone number, + and up to 15 digits                        | kept       |                   |
+| `iana-time-zone`      | IANA time zone name, tzdata 2026f                                      | kept       | `isIanaTimeZone`  |
+| `ip`                  | IPv4 dotted quad or IPv6 address, RFC 4291 §2.2                        | lowercased |                   |
+| `ipv4`                | IPv4 address, dotted quad without leading zeros                        | kept       |                   |
+| `ipv6`                | IPv6 address, RFC 4291 §2.2                                            | lowercased |                   |
+| `iso3166-1-alpha-2`   | ISO 3166-1 alpha-2 country code, Debian iso-codes v4.20.1              | uppercased | `isIso3166Alpha2` |
+| `iso3166-1-alpha-3`   | ISO 3166-1 alpha-3 country code, Debian iso-codes v4.20.1              | uppercased | `isIso3166Alpha3` |
+| `iso4217`             | ISO 4217 alphabetic currency code, SIX list 2026-09-17                 | uppercased | `isIso4217`       |
+| `iso639-1`            | ISO 639-1 language code, Debian iso-codes v4.20.1                      | lowercased | `isIso639Alpha2`  |
+| `kebab-slug`          | kebab-case slug, lowercase letters and digits joined by single hyphens | kept       |                   |
+| `pkce-s256-challenge` | RFC 7636 §4.2 PKCE SHA-256 code challenge                              | kept       |                   |
+| `rfc1123-hostname`    | RFC 1123 §2.1 host name                                                | lowercased |                   |
+| `semver`              | Semantic Versioning 2.0.0 version                                      | kept       |                   |
+| `sha256-hex`          | SHA-256 digest, FIPS 180-4, lowercase hex                              | lowercased |                   |
+| `sha512-hex`          | SHA-512 digest, FIPS 180-4, lowercase hex                              | lowercased |                   |
+| `srgb-hex`            | sRGB color as #rrggbb, CSS Color 4                                     | lowercased |                   |
+| `srgb-hex-alpha`      | sRGB color with alpha as #rrggbbaa, CSS Color 4                        | lowercased |                   |
+| `ulid`                | ULID, Crockford base32 in lowercase                                    | lowercased |                   |
+| `uts35-ca`            | UTS #35 calendar (ca) key value, CLDR 49                               | lowercased |                   |
+| `uts35-fw`            | UTS #35 first day of the week (fw) key value, CLDR 49                  | lowercased |                   |
+| `uts35-hc`            | UTS #35 hour cycle (hc) key value, CLDR 49                             | lowercased |                   |
+| `uts35-ms`            | UTS #35 measurement system (ms) key value, CLDR 49                     | lowercased |                   |
+| `uts35-mu`            | UTS #35 measurement unit (mu) key value, CLDR 49                       | lowercased |                   |
+| `uts35-nu`            | UTS #35 numbering system (nu) key value, CLDR 49                       | lowercased |                   |
+| `uuid`                | RFC 9562 UUID, lowercase hex                                           | lowercased |                   |
+| `uuid-v4`             | RFC 9562 UUID version 4, lowercase hex                                 | lowercased |                   |
+| `uuid-v7`             | RFC 9562 UUID version 7, lowercase hex                                 | lowercased |                   |
+
+A text format's rule is its pattern, which Go's RE2, Rust's regex and JavaScript's `u` mode read alike, and its length bounds, published as `pattern`, `minLength` and `maxLength` beside `x-comb-format` and the `x-comb-transform` it runs (`["trim", "uppercase"]` on `iso4217`), and its OpenAPI example is a value of the standard as written (`EUR` on `iso4217`), none where the column's own bounds leave that value out. It takes no `x-comb-text`, as no format's pattern admits U+0000 or a surrogate. The format sets the column's trim, case and length, so codegen refuses a `trim`, `lowercase` or `uppercase` beside it (`users.currency: an iso4217 text takes no lowercase: the format sets its case and trim`), a `min` or `max` outside its range, which the format already holds or which leaves no value (`users.currency: max 4 is past iso4217's length 3: the format holds it`), and an `email`, `url`, `password`, `imageUri` or `name` beside it, each a rule of its own (`users.currency: format and email contradict; declare one`). A bound inside the range, or a `pattern`, beside a format narrows it. `bcp47` sets no maximum, as RFC 5646's 35 characters are the least an implementation must hold, not a cap on a tag, so a column declares its own `max`. An id comb does not know is refused with the list it does (`users.currency: comb knows no format "iso-4217"; text formats: base64url, bcp47, …`).
+
+Where the table names a predicate, a value must also be a member of the pinned registry it reads, which no pattern states: `HRK` matches `^[A-Z]{3}$` and is no `iso4217` value, withdrawn in 2023, and `Europe/Atlantis` matches the zone pattern and names no zone. Each registry is a snapshot of the release the table names, committed in comb's source: nothing fetches at build, test or run time, and a comb release moves to a newer one. The five predicates are root exports, each taking any string, exactly as written, and never throwing; a bundle that calls none of them carries none of their lists.
+
+```ts
+import { isIanaTimeZone, isIso3166Alpha2, isIso3166Alpha3, isIso4217, isIso639Alpha2 } from "@workerstack/database"
+
+isIso4217("EUR") // true
+isIso4217("HRK") // false: withdrawn in 2023
+isIso4217("eur") // false: the DTO uppercases a value first, the predicate does not
+isIso3166Alpha2("UK") // false: reserved, not assigned; GB is the code
+```
+
+A reader that validates from the JSON Schema alone checks such a value with the predicate, or with the release meta-contract §2.1 names beside the id. The `uts35-*` formats are the values of UTS #35's Unicode locale extension keys in CLDR 49, deprecated ones left out (`uts35-hc` is `h11`, `h12`, `h23`, `h24`, `c12` and `c24`); their pattern lists every value, so it is the whole rule, as on every format the table names no registry for.
+
+On a `c.enum` the listed values stay the rule, and `format` says what they mean: codegen refuses a value the format does not take as written (`users.pay_currency: "usd" is no iso4217 value; write the standard's form, "USD"`, `users.pay_currency: "HRK" is no iso4217 value`), and every DTO of the column publishes its `enum` with `x-comb-format`.
+
+`c.integer` takes the two integer formats: `iso8601-month`, 1 January to 12 December, and `iso8601-weekday`, 1 Monday to 7 Sunday (ISO 8601 §3.2.2), the numbering `Intl.Locale`'s `getWeekInfo().firstDay` returns. The write DTOs hold the value to the standard's range, or to a declared `min` or `max` inside it, published as `minimum` and `maximum` beside `x-comb-format`, and a value outside it gets zod's own `too_small` or `too_big`; codegen refuses a bound past the standard's (`users.week_start: max 8 is past iso8601-weekday's 7: the format holds it`) and a text format's id (`users.week_start: c.integer takes no format "iso4217"; integer formats: iso8601-month, iso8601-weekday`). `c.real`, `c.ref`, `c.json` and the timestamps take no format: TypeScript refuses one, and codegen refuses it from a tables module in JavaScript (`users.owner_id: c.ref takes no format`).
+
+A text its format refuses gets exactly one issue, zod's `invalid_format` with the id as its `format` and `origin: "string"`, and no message of comb's, so zod words it in the locale you configure, and an error map can key a message of your own on the id:
+
+```ts
+import * as z from "zod"
+
+// " eu " or "HRK" on an iso4217 field:
+// { code: "invalid_format", format: "iso4217", origin: "string", path: ["currency"], message: "Invalid iso4217" }
+
+z.config(z.locales.de()) // message: "Ungültig: iso4217"
+
+z.config({
+	customError: (issue) =>
+		issue.code === "invalid_format" && issue.format === "iso4217" ? "Unknown currency" : undefined,
+})
+```
+
+An error map that returns `undefined` leaves the issue to the locale, as that one does for every other issue.
+
+### Column schemas
+
+`schema` takes a rule comb has no key for: a zod schema the create and update DTOs pipe a `c.text`, `c.integer` or `c.real` value into after every rule of comb's, so it reads the value trimmed, cased and checked. Codegen imports it as it imports a `c.json` schema, so it must be exported, and it is best in a module of its own:
+
+```ts
+/* src/db/schemas.ts: a module of its own, so a DTO that imports a schema loads zod and this module alone */
+import * as z from "zod"
+
+export const dateOrder = z.enum(["iso", "dmy", "mdy"])
+export const evenMinutes = z.int().refine((value) => value % 2 === 0, { error: "Must be even" })
+```
+
+The tables module imports both, `import { dateOrder, evenMinutes } from "./schemas.ts"`, and names each on its column:
 
-`@workerstack/database/sqlite/patterns` ships regexes as source-level strings so the codegen parser can copy them verbatim into `.regex()` calls:
+<!-- ts-context
+declare const dateOrder: import("zod").ZodType<string, string>
+declare const evenMinutes: import("zod").ZodType<number, number>
+-->
 
 ```ts
-import { patterns } from "@workerstack/database/sqlite/patterns"
+import { sqliteTable } from "drizzle-orm/sqlite-core"
+import { c } from "@workerstack/database/sqlite/columns"
+
+export const users = sqliteTable("users", {
+	id: c.id("usr"),
+	date_order: c.text("date_order", { schema: dateOrder, trim: true }),
+	slot_minutes: c.integer("slot_minutes", { min: 0, schema: evenMinutes }),
+})
+```
 
-patterns.COUNTRY_ALPHA2 // "/^[A-Z]{2}$/"
-patterns.E164_PHONE // "/^\\+[1-9][0-9]{7,14}$/"
-patterns.IANA_TIMEZONE // "/^[A-Za-z_/]+$/"
-patterns.LOCALE // "/^[a-z]{2}(-[A-Z]{2})?$/"
+A schema exported from the tables module works too, but then every DTO that imports it loads the tables module and drizzle with it, a frontend form's bundle among them, and as a `const` it must sit above the table that names it: one below throws a `ReferenceError` as the module loads, which codegen reports in the module's own words. An inline schema type-checks, yet codegen refuses it, as it can only import an export: `users.date_order: no module of the project exports the schema its schema key is given; export it, above the table that names it, so the generated DTOs can import it`, with the note of packages that would not load on their own that a `c.json` schema's error carries.
+
+The text key takes a `z.ZodType<string, string>` and the number keys a `z.ZodType<number, number>`, so a `z.int()` on a text, or a transform to another type, fails to compile. The schema must come from the `zod` the generated DTOs import, one `zod` in the project's tree, as a `c.json` schema must. Codegen refuses a value that is no zod schema (`users.date_order: the constraint schema is no zod schema; comb's DTOs are zod 4, so the schema must be one`) and one with no JSON Schema form, such as a `z.custom()`, keeping zod's reason (`… has no JSON Schema form (zod: Custom types cannot be represented in JSON Schema); comb publishes every DTO rule`).
+
+Its issues reach the caller exactly as zod yields them, and comb adds no code or message: `"x"` on `date_order` is the enum's own `invalid_value` with its values, and `3` on `slot_minutes` is the refine's `custom` issue, `"Must be even"`. A value comb's own rules refuse never reaches the schema, so `-3` there gets the `too_small` of `min: 0` alone.
+
+The JSON Schema publishes the schema's export name as `x-comb-schema` and the schema's own input JSON Schema in an `allOf` beside it, which codegen computes with `z.toJSONSchema(schema, { io: "input" })` and writes as a literal; on a nullable field the `allOf` sits on the non-null member of its `anyOf`, as the schema's `type` would refuse the null the field takes. A nullable `date_order` publishes:
+
+```text
+{
+	"anyOf": [
+		{
+			"type": "string",
+			"allOf": [{ "type": "string", "enum": ["iso", "dmy", "mdy"] }],
+			"x-comb-schema": "dateOrder",
+			"x-comb-text": "no U+0000 or unpaired surrogate",
+			"x-comb-transform": ["trim"]
+		},
+		{ "type": "null" }
+	],
+	"x-comb-schema": "dateOrder",
+	"x-comb-text": "no U+0000 or unpaired surrogate",
+	"x-comb-transform": ["trim"]
+}
 ```
 
+A refine publishes nothing: `evenMinutes` publishes `{ "type": "integer" }` with a safe integer's range and no word of evenness. `x-comb-schema` is how a reader that runs no JavaScript learns the producer runs a rule it cannot see, and such a reader may take a value the server then refuses. A column with a `schema` carries no generated example, as a refine its JSON Schema does not state may refuse any value comb would pick. The read DTO runs no schema, as a read never refuses a stored row, and the manifest names the export as the column's `schema`. `c.enum`, `c.json`, `c.ref` and the timestamps take no `schema` (`users.status: c.enum takes no schema`): an enum's values and a `c.json` schema are rules of their own, and a reference's value is another table's key.
+
 ## Errors
 
 ### `CombError`
@@ -1057,28 +1198,27 @@ ULIDs use Crockford base32 with a 10-character timestamp and 16 characters of ra
 
 ## Package exports
 
-| Specifier                                    | Contents                                                                                           |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `@workerstack/database`                           | `CombError`, `createUlidFactory`, `generateId`, `generateUlid`, `LruCache`, error keys and types   |
-| `@workerstack/database/types`                     | `StatusKey`, `ConstraintMap`, `DatabaseErrorHandler`, …                                            |
-| `@workerstack/database/cli`                       | `runCli(argv, io)`: run the CLI in process and get its exit code                                   |
-| `@workerstack/database/codegen`                   | `analyze`, `validateTables`, `fieldConstraintsOf`, analysis types                                  |
-| `@workerstack/database/codegen/generators`        | every `generate*` function                                                                         |
-| `@workerstack/database/meta`                      | `combMeta`, `readCombMeta`, `readCombEntityMeta`, `readCombQueryMeta`, `carryCombMeta`, meta types |
-| `@workerstack/database/migrate`                   | config, providers, apply, parse, Atlas helpers                                                     |
-| `@workerstack/database/query`                     | filter, order, select, cursors, Zod builders                                                       |
-| `@workerstack/database/query/sqlite`              | SQL generation, FTS5, JSON helpers                                                                 |
-| `@workerstack/database/sqlite/columns`            | `c` for SQLite                                                                                     |
-| `@workerstack/database/sqlite/constraints`        | constraint types                                                                                   |
-| `@workerstack/database/sqlite/patterns`           | shared regex patterns                                                                              |
-| `@workerstack/database/sqlite/constraint-handler` | `sqliteErrorHandler`, `classifySqliteError`, `handleConstraintViolation`                           |
-| `@workerstack/database/sqlite/d1/session`         | `openD1Session`                                                                                    |
-| `@workerstack/database/sqlite/d1/bookmark`        | `BookmarkTracker`                                                                                  |
-| `@workerstack/database/sqlite/d1/error-handler`   | `d1ErrorHandler`, `classifyD1Error`                                                                |
-| `@workerstack/database/sqlite/d1/sharding`        | `ShardRouter`, `shardMap`                                                                          |
-| `@workerstack/database/states`                    | `defineStateMachine`, `canTransition`, `assertTransition`, `nextStates`, `isState`, `isTerminal`   |
-| `@workerstack/database/pg/columns`                | `c` for PostgreSQL                                                                                 |
-| `@workerstack/database/pg/error-handler`          | `pgErrorHandler`, `classifyPgError`                                                                |
+| Specifier                                         | Contents                                                                                                                         |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `@workerstack/database`                           | `CombError`, `createUlidFactory`, `generateId`, `generateUlid`, `LruCache`, the format registry predicates, error keys and types |
+| `@workerstack/database/types`                     | `StatusKey`, `ConstraintMap`, `DatabaseErrorHandler`, …                                                                          |
+| `@workerstack/database/cli`                       | `runCli(argv, io)`: run the CLI in process and get its exit code                                                                 |
+| `@workerstack/database/codegen`                   | `analyze`, `validateTables`, `fieldConstraintsOf`, analysis types                                                                |
+| `@workerstack/database/codegen/generators`        | every `generate*` function                                                                                                       |
+| `@workerstack/database/meta`                      | `combMeta`, `readCombMeta`, `readCombEntityMeta`, `readCombQueryMeta`, `carryCombMeta`, meta types                               |
+| `@workerstack/database/migrate`                   | config, providers, apply, parse, Atlas helpers                                                                                   |
+| `@workerstack/database/query`                     | filter, order, select, cursors, Zod builders                                                                                     |
+| `@workerstack/database/query/sqlite`              | SQL generation, FTS5, JSON helpers                                                                                               |
+| `@workerstack/database/sqlite/columns`            | `c` for SQLite                                                                                                                   |
+| `@workerstack/database/sqlite/constraints`        | constraint types                                                                                                                 |
+| `@workerstack/database/sqlite/constraint-handler` | `sqliteErrorHandler`, `classifySqliteError`, `handleConstraintViolation`                                                         |
+| `@workerstack/database/sqlite/d1/session`         | `openD1Session`                                                                                                                  |
+| `@workerstack/database/sqlite/d1/bookmark`        | `BookmarkTracker`                                                                                                                |
+| `@workerstack/database/sqlite/d1/error-handler`   | `d1ErrorHandler`, `classifyD1Error`                                                                                              |
+| `@workerstack/database/sqlite/d1/sharding`        | `ShardRouter`, `shardMap`                                                                                                        |
+| `@workerstack/database/states`                    | `defineStateMachine`, `canTransition`, `assertTransition`, `nextStates`, `isState`, `isTerminal`                                 |
+| `@workerstack/database/pg/columns`                | `c` for PostgreSQL                                                                                                               |
+| `@workerstack/database/pg/error-handler`          | `pgErrorHandler`, `classifyPgError`                                                                                              |
 
 ## Repository layout
 
@@ -1126,6 +1266,30 @@ bun run test:bun     # bun test — the bun:sqlite replay suite
 
 Commits follow [Conventional Commits](https://www.conventionalcommits.org). `bun install` points `core.hooksPath` at `.githooks`, so the `commit-msg` hook enforces it locally; CI re-checks every commit on a pull request.
 
+## Upgrading to 0.22
+
+What changes for a project on 0.21. Before deploying it:
+
+1. **Know what changed in the API.** A test holds these three lists to the exports themselves.
+
+   New exports: `IntegerFormat`, `RealConstraints`, `RefConstraints`, `TextFormat`, `isIanaTimeZone`, `isIso3166Alpha2`, `isIso3166Alpha3`, `isIso4217`, `isIso639Alpha2`.
+
+   Removed: `patterns`, with its entry point, @workerstack/database/sqlite/patterns. **Fix:** declare the format that holds the standard a pattern of it stood for, as item 2 maps each one.
+
+   Changed: `AnalysisResult`, `CodegenConfig`, `DatabaseCodegen`, `EnumOptions`, `FieldConstraints`, `FieldConstraintsMeta`, `FieldMeta`, `GeneratorContext`, `IntegerConstraints`, `Manifest`, `ManifestColumn`, `ManifestEntity`, `OrmConfig`, `PgColumns`, `ShardMapColumns`, `ShardMapTable`, `SqliteColumns`, `TableMeta`, `TextConstraints`, `analyze`, `buildManifest`, `c`, `defineCodegenConfig`, `deriveEntityMeta`, `fieldConstraintsOf`, `generateColumns`, `generateConstraints`, `generateDiagrams`, `generateDtos`, `generateEntities`, `generateEnumChecks`, `generateFieldNames`, `generateFts`, `generateFtsSql`, `generateManifest`, `generateOrm`, `generateRelations`, `generateRows`, `generateTranslations`, `isExcludedFromUpdate`, `shardMap`, `validateTables`.
+
+   `TextConstraints` gains `format` and `schema`, `IntegerConstraints` gains `format` and `schema`, and `EnumOptions` gains `format`, each optional ([Formats](#formats), [Column schemas](#column-schemas)), a `format` standing where a regex of the removed `patterns` did (step 2). `c.real` takes `RealConstraints`, a real's bounds and `schema` with no `format`, where 0.21 typed it with `IntegerConstraints`, and `c.ref` takes `RefConstraints`, a text's keys but `format` and `schema`. The `c` of @workerstack/database/sqlite/columns, @workerstack/database/pg/columns and @workerstack/database/sqlite/d1/sharding changes with them, as do `SqliteColumns`, `PgColumns`, `ShardMapColumns`, `ShardMapTable` and `shardMap`. **Fix:** none: a call that compiled on 0.21, one passing a value typed `IntegerConstraints` to `c.real` or `TextConstraints` to `c.ref` among them, compiles on 0.22.
+
+   `ManifestColumn` gains `format`, the id of the standard a write checks the value against, and `schema`, the export name of the zod schema a text or number column declares, each null when the column declares none and `schema` null on a `c.json` column, whose schema the manifest already describes. `FieldConstraintsMeta`, which the package root, @workerstack/database/codegen, @workerstack/database/meta and @workerstack/database/query reach, gains `format`, and `FieldMeta` gains `schemaJson`, the schema's input JSON Schema, which the DTOs publish. Each is required, as every field of these types is (`ManifestColumn.format`, `ManifestColumn.schema`, `FieldConstraintsMeta.format`, `FieldMeta.schemaJson`), so a `ManifestColumn` or `FieldConstraintsMeta` you build fails to compile (TS2741). The manifest stays `v` 3, and a manifest reader meets the two fields as nulls on every column that declares neither. **Fix:** a `ManifestColumn` you build sets `format: null` and `schema: null`, a `FieldConstraintsMeta` sets `format: null`, and a `FieldMeta` sets `schemaJson: null`.
+
+   `fieldConstraintsOf` takes `values`, the column's enum values, each of which a `c.enum`'s format must take, or `null` for a column with none. **Fix:** a direct caller of `fieldConstraintsOf` passes `values`.
+
+   The rest of the list changes only through those types: `FieldConstraints` is `FieldConstraintsMeta`; `AnalysisResult`, `TableMeta`, `Manifest` and `ManifestEntity` hold a `FieldMeta` or a `ManifestColumn`; and `analyze`, `buildManifest`, `validateTables`, `deriveEntityMeta`, `isExcludedFromUpdate`, `CodegenConfig`, `DatabaseCodegen`, `GeneratorContext`, `OrmConfig`, `defineCodegenConfig` and each `generate*` function take or return one. **Fix:** none.
+
+2. **Declare a `format` where a `patterns` regex stood.** Each of the four stood for a standard it held loosely: `COUNTRY_ALPHA2` took any two capitals, `UK` and `XX` among them; `E164_PHONE` refused a number of fewer than 8 digits; `IANA_TIMEZONE` took `a/b/c` and refused `Etc/GMT+5` and `America/Port-au-Prince`; `LOCALE` refused `zh-Hant-TW` and `es-419`. A format holds the standard itself, and a registry's format its pinned list: `iso3166-1-alpha-2` refuses `UK` and `XX`, `e164` takes 2 to 15 digits after the `+`, `iana-time-zone` takes the names of tzdata 2026f alone, and `bcp47` takes every well-formed tag. A format also trims the value and writes it in its standard's case before its check, so `" hr"` is stored as `HR` where the pattern refused it. A value it refuses gets zod's `invalid_format` with the id as its `format` and the locale's message, where a pattern's issue was `format: "regex"` with the pattern and an English message. **Fix:** replace `pattern: patterns.COUNTRY_ALPHA2` with `format: "iso3166-1-alpha-2"`, `pattern: patterns.E164_PHONE` with `format: "e164"`, `pattern: patterns.IANA_TIMEZONE` with `format: "iana-time-zone"` and `pattern: patterns.LOCALE` with `format: "bcp47"`; drop a `trim`, `lowercase` or `uppercase` beside it, and a `min` or `max` outside its range, which codegen refuses; a client that read a pattern's `format: "regex"` reads the id.
+
+3. **Install `@workerstack/database` in place of `@lovrozagar/comb`.** The package moved to the workerstack org and the old name gets no new releases; `@workerstack/database@0.21.0` is `@lovrozagar/comb@0.21.0` under the new name, so you can switch before taking 0.22. The `comb` CLI, `comb.config.ts`, `CombError` and the migration tables keep their names. Generated DTOs and entities import from the package by name, so files generated on the old name still import `@lovrozagar/comb`. **Fix:** run `bun remove @lovrozagar/comb && bun add @workerstack/database`, replace every `@lovrozagar/comb` import prefix with `@workerstack/database`, and rerun `comb codegen`.
+
 ## Upgrading to 0.21
 
 What changes for a project on 0.20. Before deploying it:

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.0",
 	"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",

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,