@drzl/validation-core 3.20.0 → 3.22.1

package/README.md

@@ -25,7 +25,8 @@ Shared interfaces and helpers used by validation generators.
 
 - Every dollar speeds up CI hardware and offsets long test runs on my aging laptop.
 - Sponsors get roadmap input and priority responses in GitHub Issues.
-- Prefer a quick overview? Check `docs/sponsor.md` for the current goals and thank-yous.
+- Prefer a quick overview? The current goals and thank-yous are at
+  https://use-drzl.github.io/drzl/sponsor.
 
 ## Exports (essentials)
 
@@ -53,20 +54,45 @@ Shared interfaces and helpers used by validation generators.
 - CHECK constraints (shared by every generator that reads them)
   - `parseCheck(expression, name)` -> the parts of a `CHECK` that can be stated with certainty:
     column comparisons, `BETWEEN`, `IN (...)`, top-level `AND`, `length()`/`char_length()`,
-    `cardinality()`/`array_length(col, 1)`, and comparisons between two columns. A disjunction, a
-    negation, `octet_length`, an unrecognised function call and a regex match are all refused
-    whole rather than half-applied.
-  - `COLUMN_FORMATS` -> patterns for the column formats that are expressible. Only `numeric` is:
-    Postgres accepts `today`, `January 8, 1999` and `allballs`, so a date or time pattern would
-    reject rows the database takes.
+    `octet_length()`, `cardinality()`/`array_length(col, 1)`, and comparisons between two columns.
+    A negation, an unrecognised function call and a regex match are all refused whole rather than
+    half-applied, and a disjunction is read only where the whole of it pins one column to a set.
+  - `lengthMeasure(column, check)` -> how to answer a count on a given column, as one of
+    `'codePoints'`, `'utf8Bytes'` or `'byteLength'`, or nothing where no expression answers it.
+    The unit is on the check and the answer needs the column too: measured on PostgreSQL 17.5,
+    `length()` is the character count on a `text` and the byte count on a `bytea`, and
+    `char_length(bytea)` is not a function that exists. `measureExpression(measure, variable)`
+    renders it and `lengthCheckLabel(check)` renders the message the ledger keys on.
+  - `COLUMN_FORMATS` -> patterns for the column formats that are expressible, which is a short
+    list: Postgres accepts `today`, `January 8, 1999` and `allballs`, so a date or time pattern
+    would reject rows the database takes. `numeric` is Postgres's numeric input grammar, and
+    `pgBigint`/`mysqlBigint` are the two answers a `bigint({ mode: 'string' })` column has, since
+    Postgres parses that text as an integer literal (`0x1f` and `1_000` included) and MySQL parses
+    it as a decimal number it then rounds (`12.5` becomes 13). Each was measured against its own
+    server; neither states the magnitude, and the entry says why.
   - `CODEPOINT_LENGTH` -> `[...v].length`, since `varchar(n)` counts characters and JavaScript's
     `.length` counts UTF-16 units. All four generators use it.
   - `isIntegerColumn(c)`
+- Constraints as data (shared by the generators that emit a ledger)
+  - `tableConstraints(table)` -> every CHECK, unique constraint, primary key and foreign key on a
+    table, each with a stable `id`, the columns it names, the rule as a sentence, whether a
+    generated schema enforces it, and, where it does, the exact message it attaches. A folded
+    numeric CHECK carries its `bounds` and a folded `IN` list its `values`, because those are what
+    is left to match on once the library writes the failure message itself.
+  - `classifyTableChecks(table)` -> the one reading of `parseCheck` plus the column-shape guards,
+    shared with `meta`, so "the database also checks this and no schema does" is one answer rather
+    than two.
+  - `renderConstraintsModule(tables, opts)` -> the source of `constraints.ts`: the data above plus,
+    unless `errorMap` is false, `constraintForIssue(table, issue)`. Plain objects with no import of
+    any kind, and the matcher reads zod's path items and valibot's alike.
+  - `resolveConstraints(option)` expands the `true` shorthand; `CONSTRAINTS_MODULE` is the file
+    name every generator writes it to.
 - Uniqueness
   - `renderDuplicateFinder(table, fnName, rowType)` -> the source of a function returning the rows
-    in a batch that collide with an earlier row on a unique constraint. Plain TypeScript with no
-    reference to any validation library, so all four generators emit the same one. Null and absent
-    columns skip a constraint, matching SQL.
+    in a batch that collide with an earlier row on the primary key or a unique constraint. Plain
+    TypeScript with no reference to any validation library, so every validator generator emits the
+    same one. Null and absent columns skip a constraint, matching SQL, so rows that leave a
+    generated key to the database report nothing on it.
 - Naming (shared by every generator that emits a schema name)
   - `resolveAffix({ affix, schemaSuffix })` -> `ResolvedAffix`
   - `schemaName(mode, tsName, resolved)`, `typeName(mode, tsName, resolved)`