@fougere/schema 0.2.0-alpha.0 → 0.2.0-alpha.2

package/dist/schema/view.d.ts

@@ -0,0 +1,26 @@
+import type { Field, Fields } from "../field/index.js";
+import type { Hints } from "../hints.js";
+import type { CompositeUnique } from "../unique.js";
+import type { ValidationResult, ValidateOptions } from '../validation/index.js';
+/** The row an entity carries — its fields' value types, all present. */
+export type Row<TFields extends Fields> = {
+    [K in keyof TFields]: TFields[K] extends Field<infer T> ? T : never;
+};
+/** A row as handed to the constructor — every key omissible. */
+export type PartialRow<TFields extends Fields> = Partial<Row<TFields>>;
+/**
+ * What a schema ANSWERS. No construct signature, so a class carrying a body satisfies it —
+ * and `Fields` by default, for a reader that does not care which map it holds.
+ */
+export interface SchemaView<TFields extends Fields = Fields> {
+    readonly name: string;
+    getFields(): TFields;
+    /** Per-consumer hints from the 2nd arg of `entity()`. Derivations carry them. */
+    getHints(): Hints<TFields> | undefined;
+    /** Field groups unique together, from the 2nd arg of `entity()`. */
+    getUnique(): CompositeUnique<TFields> | undefined;
+    /** This view's validation mode — `patch` is set by `partial()`. */
+    getOpts(): ValidateOptions;
+    validate(input: unknown): ValidationResult<Row<TFields>>;
+}
+//# sourceMappingURL=view.d.ts.map

package/dist/schema/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/schema/view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGhF,wEAAwE;AACxE,MAAM,MAAM,GAAG,CAAC,OAAO,SAAS,MAAM,IAAI;KACvC,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACpE,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAEvE;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,SAAS,IAAI,OAAO,CAAC;IACrB,iFAAiF;IACjF,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IACvC,oEAAoE;IACpE,SAAS,IAAI,eAAe,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IAClD,mEAAmE;IACnE,OAAO,IAAI,eAAe,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;CAC1D"}

package/dist/schema/view.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=view.js.map

package/dist/schema/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/schema/view.ts"],"names":[],"mappings":""}

package/dist/unique.d.ts

@@ -1,16 +1,9 @@
 import type { Fields } from './field/index.js';
 import type { Hints } from './hints.js';
 /**
- * Field names that identify at most one row when taken together.
- *
- * `unique(field)` states a fact about one column; some facts are about a pair.
- * "A book appears once in a list" is true of `(listId, docId)` and of neither
- * alone, and there is no shape that can express it — judging one value never
- * sees the other rows. So it is declared on the entity and realized by storage.
- *
- * Held here rather than in a handler because a handler cannot hold it: a check
- * followed by a write is two round trips, and a concurrent request fits between
- * them. The database is the only place where the promise is keepable.
+ * Field names that identify at most one row when taken together. No shape can express it —
+ * judging one value never sees the other rows — and no handler either: a check then a write
+ * is two round trips with room for a concurrent one between them. Only the database keeps it.
  */
 export type CompositeUnique<TFields extends Fields> = ReadonlyArray<ReadonlyArray<Extract<keyof TFields, string>>>;
 /**
@@ -21,45 +14,27 @@ export type CompositeUnique<TFields extends Fields> = ReadonlyArray<ReadonlyArra
  * adds a key here, never a positional argument.
  */
 export interface EntityDeclarations<TFields extends Fields> {
-    /** Field groups that must be unique together. */
     unique?: CompositeUnique<TFields>;
     /** Per-consumer hints, keyed by registered adapter. See {@link Hints}. */
     hints?: Hints<TFields>;
 }
 /**
- * Carry composite groups across a field-key transform — the entity-level twin of
- * `deriveHints`.
- *
- * A group whose members did not all survive is dropped rather than narrowed: the
- * pair `(listId, docId)` says nothing about `listId` alone, and keeping the
- * remnant would silently state a stronger fact than the author ever wrote.
+ * Carry composite groups across a key transform. A group that lost a member is DROPPED,
+ * not narrowed: `(listId, docId)` says nothing about `listId` alone.
  */
 export declare function deriveUnique(groups: CompositeUnique<Fields> | undefined, mapKey: (key: string) => string | undefined): CompositeUnique<Fields> | undefined;
 /**
- * Carry the projected groups across the same key transform — the field-level twin of
- * {@link deriveUnique}, and it has to run with it: the group lives in TWO places once
- * projected (the declaration and each member's role), so remapping one alone left
- * `pick('id','listId')` with a role still claiming a pair whose other member was gone.
- *
- * Same rule as the declaration — a group that lost a member is dropped, not narrowed.
- * The empty self-reference needs no remapping: it names no key, which is exactly why it
- * survives a `rename()` for free.
+ * The same, on each member's role — it must run WITH {@link deriveUnique}: once projected
+ * the group lives in two places, so remapping one alone left a role claiming a pair whose
+ * other member was gone. The empty self-reference names no key, so it needs no remapping.
  */
 export declare function deriveUniqueRoles<TFields extends Fields>(fields: TFields, mapKey: (key: string) => string | undefined): TFields;
 /**
- * Project the entity's composite groups onto the role of every member — the single
- * place the two ways of stating uniqueness meet.
- *
- * The author writes each fact where it lives: `unique(slug)` on the field it is about,
- * `entity(fields, { unique: [['listId','docId']] })` on the entity, because a fact about
- * a pair is held by neither field alone. Both then read as ONE normal form on the role
- * axis, so every consumer — the DDL, the card, a foreign adapter — has a single shape to
- * handle, and a field belonging to two constraints simply carries two member lists.
+ * Project the entity's composite groups onto every member's role — the single place the
+ * two ways of stating uniqueness meet, so every consumer has one shape to handle.
  *
- * The entity declaration stays the source (`getUnique()` keeps answering it); this is a
- * projection of it, never a second place to edit. A named member group is spelled out
- * here, while a lone `unique()` keeps its `[]` self-reference — resolved by whoever reads
- * it, which is what makes `rename()` free.
+ * The entity declaration stays the source (`getUnique()` answers it); this is a projection,
+ * never a second place to edit.
  */
 export declare function projectUniqueOntoFields<TFields extends Fields>(fields: TFields, groups: CompositeUnique<TFields> | undefined): TFields;
 //# sourceMappingURL=unique.d.ts.map

package/dist/unique.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../src/unique.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,MAAM,IAAI,aAAa,CACjE,aAAa,CAAC,OAAO,CAAC,MAAM,OAAO,EAAE,MAAM,CAAC,CAAC,CAC9C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,MAAM;IACxD,iDAAiD;IACjD,MAAM,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAClC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,SAAS,EAC3C,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAC1C,eAAe,CAAC,MAAM,CAAC,GAAG,SAAS,CAQrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,EACtD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAC1C,OAAO,CAkBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAS,MAAM,EAC5D,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,SAAS,GAC3C,OAAO,CAiBT"}
+{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../src/unique.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,MAAM,IAAI,aAAa,CACjE,aAAa,CAAC,OAAO,CAAC,MAAM,OAAO,EAAE,MAAM,CAAC,CAAC,CAC9C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,MAAM;IACxD,MAAM,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAClC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,SAAS,EAC3C,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAC1C,eAAe,CAAC,MAAM,CAAC,GAAG,SAAS,CAQrC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,SAAS,MAAM,EACtD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAC1C,OAAO,CAeT;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAS,MAAM,EAC5D,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,SAAS,GAC3C,OAAO,CAcT"}

package/dist/unique.js

@@ -1,10 +1,6 @@
 /**
- * Carry composite groups across a field-key transform — the entity-level twin of
- * `deriveHints`.
- *
- * A group whose members did not all survive is dropped rather than narrowed: the
- * pair `(listId, docId)` says nothing about `listId` alone, and keeping the
- * remnant would silently state a stronger fact than the author ever wrote.
+ * Carry composite groups across a key transform. A group that lost a member is DROPPED,
+ * not narrowed: `(listId, docId)` says nothing about `listId` alone.
  */
 export function deriveUnique(groups, mapKey) {
     if (!groups)
@@ -15,14 +11,9 @@ export function deriveUnique(groups, mapKey) {
     return carried.length > 0 ? carried : undefined;
 }
 /**
- * Carry the projected groups across the same key transform — the field-level twin of
- * {@link deriveUnique}, and it has to run with it: the group lives in TWO places once
- * projected (the declaration and each member's role), so remapping one alone left
- * `pick('id','listId')` with a role still claiming a pair whose other member was gone.
- *
- * Same rule as the declaration — a group that lost a member is dropped, not narrowed.
- * The empty self-reference needs no remapping: it names no key, which is exactly why it
- * survives a `rename()` for free.
+ * The same, on each member's role — it must run WITH {@link deriveUnique}: once projected
+ * the group lives in two places, so remapping one alone left a role claiming a pair whose
+ * other member was gone. The empty self-reference names no key, so it needs no remapping.
  */
 export function deriveUniqueRoles(fields, mapKey) {
     const out = { ...fields };
@@ -36,27 +27,16 @@ export function deriveUniqueRoles(fields, mapKey) {
         if (carried.length === groups.length)
             continue; // nothing lost, keep the field as is
         const { unique: _dropped, ...rest } = field.role;
-        out[key] = {
-            ...field,
-            role: carried.length ? { ...rest, unique: carried } : rest,
-        };
+        out[key] = field.with({ role: carried.length ? { ...rest, unique: carried } : rest });
     }
     return out;
 }
 /**
- * Project the entity's composite groups onto the role of every member — the single
- * place the two ways of stating uniqueness meet.
- *
- * The author writes each fact where it lives: `unique(slug)` on the field it is about,
- * `entity(fields, { unique: [['listId','docId']] })` on the entity, because a fact about
- * a pair is held by neither field alone. Both then read as ONE normal form on the role
- * axis, so every consumer — the DDL, the card, a foreign adapter — has a single shape to
- * handle, and a field belonging to two constraints simply carries two member lists.
+ * Project the entity's composite groups onto every member's role — the single place the
+ * two ways of stating uniqueness meet, so every consumer has one shape to handle.
  *
- * The entity declaration stays the source (`getUnique()` keeps answering it); this is a
- * projection of it, never a second place to edit. A named member group is spelled out
- * here, while a lone `unique()` keeps its `[]` self-reference — resolved by whoever reads
- * it, which is what makes `rename()` free.
+ * The entity declaration stays the source (`getUnique()` answers it); this is a projection,
+ * never a second place to edit.
  */
 export function projectUniqueOntoFields(fields, groups) {
     if (!groups || groups.length === 0)
@@ -69,10 +49,7 @@ export function projectUniqueOntoFields(fields, groups) {
             if (!field)
                 continue; // a group naming an absent field states nothing here
             const already = field.role?.unique ?? [];
-            projected[key] = {
-                ...field,
-                role: { ...field.role, unique: [...already, members] },
-            };
+            projected[key] = field.with({ role: { ...field.role, unique: [...already, members] } });
         }
     }
     return projected;

package/dist/unique.js.map

@@ -1 +1 @@
-{"version":3,"file":"unique.js","sourceRoot":"","sources":["../src/unique.ts"],"names":[],"mappings":"AAiCA;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA2C,EAC3C,MAA2C;IAE3C,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,OAAO,GAAG,MAAM;SACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;SACjC,MAAM,CAAC,CAAC,KAAK,EAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC;IAEjF,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAe,EACf,MAA2C;IAE3C,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAY,CAAC;IACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,MAAM;YAAE,SAAS;QAE9B,MAAM,OAAO,GAAG,MAAM;aACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;aAC7D,MAAM,CAAC,CAAC,KAAK,EAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC;QAEvF,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,SAAS,CAAG,qCAAqC;QACvF,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,IAAK,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,GAAG;YACT,GAAG,KAAK;YACR,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI;SAC3D,CAAC;IACJ,CAAC;IACD,OAAO,GAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAe,EACf,MAA4C;IAE5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAElD,MAAM,SAAS,GAAG,EAAE,GAAG,MAAM,EAAY,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QAC3B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK;gBAAE,SAAS,CAAG,qDAAqD;YAC7E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,GAAG;gBACf,GAAG,KAAK;gBACR,IAAI,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE;aACvD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,SAAoB,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"unique.js","sourceRoot":"","sources":["../src/unique.ts"],"names":[],"mappings":"AAyBA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA2C,EAC3C,MAA2C;IAE3C,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,OAAO,GAAG,MAAM;SACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;SACjC,MAAM,CAAC,CAAC,KAAK,EAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC;IAEjF,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAe,EACf,MAA2C;IAE3C,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAY,CAAC;IACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QAClC,IAAI,CAAC,MAAM,EAAE,MAAM;YAAE,SAAS;QAE9B,MAAM,OAAO,GAAG,MAAM;aACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;aAC7D,MAAM,CAAC,CAAC,KAAK,EAAqB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC;QAEvF,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,SAAS,CAAG,qCAAqC;QACvF,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,IAAK,CAAC;QAClD,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,GAAc,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAe,EACf,MAA4C;IAE5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAElD,MAAM,SAAS,GAAG,EAAE,GAAG,MAAM,EAAY,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QAC3B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK;gBAAE,SAAS,CAAG,qDAAqD;YAC7E,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IACD,OAAO,SAAoB,CAAC;AAC9B,CAAC"}

package/dist/validation/index.d.ts

@@ -0,0 +1,4 @@
+export type { ValidationError, ValidationResult, Checked } from "./result.js";
+export type { ValidateOptions } from "./options.js";
+export { Judge } from "./judge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC9E,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/validation/index.js

@@ -0,0 +1,2 @@
+export { Judge } from "./judge.js";
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/validation/judge.d.ts

@@ -0,0 +1,55 @@
+import type { Field, Fields } from '../field/index.js';
+import type { Checked, ValidationResult } from './result.js';
+import type { ValidateOptions } from './options.js';
+/**
+ * The one judge, at the three levels anything is judged: a field's DECLARATION, one VALUE
+ * against its shape, a ROW against a field map. Same answer shape at all three.
+ *
+ * A class and not three functions because it holds state: the per-shape plan cache. The
+ * closed vocabularies belong to the axes that close them — this file imports them.
+ */
+export declare class Judge {
+    /**
+     * One plan per shape — the shape object IS the source JSON Schema (the closed
+     * grammar the helpers emit), handed straight to the engine. Keyed by the shape
+     * reference (stable: derivations copy field refs, `partial()` spreads the field but
+     * keeps the same `shape`), built once and reused so the parse cost is amortised —
+     * and so an unresolvable format is refused once per shape, never per value.
+     */
+    private static readonly plans;
+    private static planFor;
+    /**
+     * Resolve a declared format, and REFUSE a name neither the engine nor the registry
+     * knows: the engine ignores an unknown format in silence, so a typo would let every
+     * value through while the card claims the field is constrained.
+     *
+     * SCOPE: the field's own shape — a format nested inside `json(Entity)` is not reached.
+     */
+    private static customFormatOf;
+    /**
+     * Validate a present value (null included) against its field — pure, never mutates.
+     *
+     * Reads `shape` and nothing else, so it answers "is this a legal value?" without ever
+     * asking who is speaking. That is what makes it usable on the way OUT of the domain,
+     * where the client-only axes (`boundary`, `lifecycle`) do not apply.
+     */
+    static value(field: Field, value: unknown): Checked;
+    /** `'now' | 'optional' | { value } | { generate: <name> }` — the four ways absence is answered. */
+    private static checkCreate;
+    private static checkLifecycle;
+    private static checkRelation;
+    private static checkRole;
+    /**
+     * The registry is OPEN, so a name cannot be checked here — `declaredBoundary` resolves it
+     * and throws `Unknown boundary alias` at the one place that can know. Only the FORM is
+     * judged: a name, or a pair of directional rules.
+     */
+    private static checkBoundary;
+    /** Judge a field's declaration — the five axes against their closed vocabularies. */
+    static field(value: unknown): ValidationResult<Field>;
+    /** Judge an input object against a field map — membership, absence, and who may speak. */
+    static row(fields: Fields, input: unknown, opts?: ValidateOptions): ValidationResult<Record<string, unknown>>;
+    /** The same judgment, as a boolean. */
+    static isField(value: unknown): value is Field;
+}
+//# sourceMappingURL=judge.d.ts.map

package/dist/validation/judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/validation/judge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAA0B,MAAM,mBAAmB,CAAC;AAK/E,OAAO,KAAK,EAAE,OAAO,EAAmB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAgBpD;;;;;;GAMG;AACH,qBAAa,KAAK;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAEjE,OAAO,CAAC,MAAM,CAAC,OAAO;IAetB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAW7B;;;;;;OAMG;IAEH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAiClD;IAED,mGAAmG;IACnG,OAAO,CAAC,MAAM,CAAC,WAAW;IAoB1B,OAAO,CAAC,MAAM,CAAC,cAAc;IAoB7B,OAAO,CAAC,MAAM,CAAC,aAAa;IAgC5B,OAAO,CAAC,MAAM,CAAC,SAAS;IAiCxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAwB5B,qFAAqF;IAErF,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAsCpD;IAED,0FAA0F;IAC1F,MAAM,CAAC,GAAG,CACR,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,eAAoB,GACvB,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA8E7C;IAED,uCAAuC;IACvC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAE7C;CACF"}

package/dist/validation/judge.js

@@ -0,0 +1,351 @@
+import { CREATE_TOKENS, UPDATE_TOKENS } from '../field/lifecycle.js';
+import { ON_DELETE, RELATION_KINDS } from '../field/role.js';
+import { Anatomy, Formats, boundaryOf, isShape, resolveBoundary, } from '../field/index.js';
+import { Validator, format as engineFormats } from '@cfworker/json-schema';
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const oneOfTokens = (v, tokens) => typeof v === 'string' && tokens.includes(v);
+/**
+ * The one judge, at the three levels anything is judged: a field's DECLARATION, one VALUE
+ * against its shape, a ROW against a field map. Same answer shape at all three.
+ *
+ * A class and not three functions because it holds state: the per-shape plan cache. The
+ * closed vocabularies belong to the axes that close them — this file imports them.
+ */
+export class Judge {
+    /**
+     * One plan per shape — the shape object IS the source JSON Schema (the closed
+     * grammar the helpers emit), handed straight to the engine. Keyed by the shape
+     * reference (stable: derivations copy field refs, `partial()` spreads the field but
+     * keeps the same `shape`), built once and reused so the parse cost is amortised —
+     * and so an unresolvable format is refused once per shape, never per value.
+     */
+    static plans = new WeakMap();
+    static planFor(shape) {
+        let p = this.plans.get(shape);
+        if (!p) {
+            const base = Anatomy.of(shape).base;
+            const formatName = base?.type === 'string' ? base.format : undefined;
+            p = {
+                validator: new Validator(shape, '2020-12', true),
+                custom: formatName === undefined ? undefined : this.customFormatOf(formatName),
+                formatName,
+            };
+            this.plans.set(shape, p);
+        }
+        return p;
+    }
+    /**
+     * Resolve a declared format, and REFUSE a name neither the engine nor the registry
+     * knows: the engine ignores an unknown format in silence, so a typo would let every
+     * value through while the card claims the field is constrained.
+     *
+     * SCOPE: the field's own shape — a format nested inside `json(Entity)` is not reached.
+     */
+    static customFormatOf(name) {
+        const custom = Formats.resolve(name);
+        if (!custom && !(name in engineFormats)) {
+            throw new Error(`Unknown format: '${name}'. Register it with Formats.register('${name}', …) — ` +
+                `the engine judges ${Object.keys(engineFormats).length} formats natively and this is not one of them.`);
+        }
+        return custom;
+    }
+    /**
+     * Validate a present value (null included) against its field — pure, never mutates.
+     *
+     * Reads `shape` and nothing else, so it answers "is this a legal value?" without ever
+     * asking who is speaking. That is what makes it usable on the way OUT of the domain,
+     * where the client-only axes (`boundary`, `lifecycle`) do not apply.
+     */
+    static value(field, value) {
+        const shape = field.shape;
+        // The pre-engine guards dispatch on the BASE type — `shape.type` itself may be
+        // the nullable union. They only short-circuit NON-null values: null always goes
+        // to the engine, whose union judges it (that is the whole nullability model).
+        const base = Anatomy.of(shape).base;
+        if (value !== null) {
+            // Opaque JSON (`json()`): no nested shape → passes through unchecked.
+            // `json(Entity)` carries `properties` and falls through to the engine,
+            // which validates the nesting natively (it's plain JSON Schema).
+            if (base?.type === 'object' && !base.properties)
+                return { value };
+            // A date-time field also accepts a live Date — the domain value, not its JSON wire
+            // string — which the boundary then passes through. The engine validates JSON, so a
+            // Date (a non-JSON value) skips the schema check here; a date STRING is validated below.
+            if (base?.type === 'string' && base.format === 'date-time' && value instanceof Date) {
+                return Number.isNaN(value.getTime()) ? { error: 'Invalid date' } : { value };
+            }
+            // NaN is `typeof number` yet has no JSON form, so the JSON-centric engine accepts it —
+            // guard it here (same nature as the Date case: a JS value JSON can't represent).
+            if ((base?.type === 'number' || base?.type === 'integer') && typeof value === 'number' && Number.isNaN(value)) {
+                return { error: 'Expected a number' };
+            }
+        }
+        const plan = this.planFor(shape);
+        const result = plan.validator.validate(value);
+        if (!result.valid)
+            return { error: result.errors[0]?.error ?? 'Invalid value' };
+        // A registered format judges AFTER the engine passed — so a custom rule composes
+        // with the built-ins instead of replacing them, and the message is the engine's
+        // own wording: from the outside, `siret` fails exactly like `email` does.
+        if (plan.custom && typeof value === 'string' && !plan.custom(value)) {
+            return { error: `String does not match format "${plan.formatName}".` };
+        }
+        return { value };
+    }
+    /** `'now' | 'optional' | { value } | { generate: <name> }` — the four ways absence is answered. */
+    static checkCreate(rule, errors) {
+        if (oneOfTokens(rule, CREATE_TOKENS))
+            return;
+        if (isObject(rule)) {
+            if ("value" in rule)
+                return; // any value — the shape judges it (`assertDefaultsAreValid`)
+            if ("generate" in rule) {
+                if (typeof rule.generate !== "string") {
+                    errors.push({
+                        path: "lifecycle.create.generate",
+                        message: "Expected a generator name",
+                    });
+                }
+                return;
+            }
+        }
+        errors.push({
+            path: "lifecycle.create",
+            message: `Expected 'now', 'optional', { value } or { generate } — got ${JSON.stringify(rule)}`,
+        });
+    }
+    static checkLifecycle(lifecycle, errors) {
+        if (!isObject(lifecycle)) {
+            errors.push({
+                path: "lifecycle",
+                message: `Expected an object — got ${JSON.stringify(lifecycle)}`,
+            });
+            return;
+        }
+        if (lifecycle.create !== undefined)
+            this.checkCreate(lifecycle.create, errors);
+        if (lifecycle.update !== undefined &&
+            !oneOfTokens(lifecycle.update, UPDATE_TOKENS)) {
+            errors.push({
+                path: "lifecycle.update",
+                message: `Expected 'now' or 'forbidden' — got ${JSON.stringify(lifecycle.update)}`,
+            });
+        }
+    }
+    static checkRelation(relation, errors) {
+        if (!isObject(relation)) {
+            errors.push({
+                path: "role.relation",
+                message: `Expected an object — got ${JSON.stringify(relation)}`,
+            });
+            return;
+        }
+        if (!oneOfTokens(relation.kind, RELATION_KINDS)) {
+            errors.push({
+                path: "role.relation.kind",
+                message: `Expected 'one' or 'many' — got ${JSON.stringify(relation.kind)}`,
+            });
+        }
+        // A thunk, never the class: it is what lets a circular relation resolve lazily.
+        if (typeof relation.to !== "function") {
+            errors.push({
+                path: "role.relation.to",
+                message: "Expected a thunk returning the target entity",
+            });
+        }
+        if (relation.onDelete !== undefined &&
+            !oneOfTokens(relation.onDelete, ON_DELETE)) {
+            errors.push({
+                path: "role.relation.onDelete",
+                message: `Expected 'cascade', 'restrict' or 'set null' — got ${JSON.stringify(relation.onDelete)}`,
+            });
+        }
+    }
+    static checkRole(role, errors) {
+        if (!isObject(role)) {
+            errors.push({
+                path: "role",
+                message: `Expected an object — got ${JSON.stringify(role)}`,
+            });
+            return;
+        }
+        for (const flag of ["primary", "index"]) {
+            if (role[flag] !== undefined && typeof role[flag] !== "boolean") {
+                errors.push({
+                    path: `role.${flag}`,
+                    message: `Expected a boolean — got ${JSON.stringify(role[flag])}`,
+                });
+            }
+        }
+        if (role.unique !== undefined) {
+            const groups = role.unique;
+            const legal = Array.isArray(groups) &&
+                groups.every((g) => Array.isArray(g) && g.every((m) => typeof m === "string"));
+            if (!legal) {
+                errors.push({
+                    path: "role.unique",
+                    message: "Expected groups of field names — string[][]",
+                });
+            }
+        }
+        if (role.relation !== undefined)
+            this.checkRelation(role.relation, errors);
+    }
+    /**
+     * The registry is OPEN, so a name cannot be checked here — `declaredBoundary` resolves it
+     * and throws `Unknown boundary alias` at the one place that can know. Only the FORM is
+     * judged: a name, or a pair of directional rules.
+     */
+    static checkBoundary(boundary, errors) {
+        if (typeof boundary === "string")
+            return;
+        if (!isObject(boundary)) {
+            errors.push({
+                path: "boundary",
+                message: `Expected an alias name or { in, out } — got ${JSON.stringify(boundary)}`,
+            });
+            return;
+        }
+        for (const [side, verb] of [
+            ["in", "decode"],
+            ["out", "encode"],
+        ]) {
+            const rule = boundary[side];
+            if (rule === undefined || rule === "closed")
+                continue;
+            if (!isObject(rule) || typeof rule[verb] !== "string") {
+                errors.push({
+                    path: `boundary.${side}`,
+                    message: `Expected 'closed' or { ${verb}: <name> }`,
+                });
+            }
+        }
+    }
+    /** Judge a field's declaration — the five axes against their closed vocabularies. */
+    static field(value) {
+        if (!isObject(value)) {
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: ".",
+                        message: `Expected an object — got ${JSON.stringify(value)}`,
+                    },
+                ],
+            };
+        }
+        const errors = [];
+        if (!isShape(value.shape)) {
+            errors.push({
+                path: "shape",
+                message: `Every field states a shape — got ${JSON.stringify(value.shape)}`,
+            });
+        }
+        if (value.lifecycle !== undefined)
+            this.checkLifecycle(value.lifecycle, errors);
+        if (value.role !== undefined)
+            this.checkRole(value.role, errors);
+        if (value.boundary !== undefined)
+            this.checkBoundary(value.boundary, errors);
+        if (value.meta !== undefined) {
+            if (!isObject(value.meta)) {
+                errors.push({
+                    path: "meta",
+                    message: `Expected an object — got ${JSON.stringify(value.meta)}`,
+                });
+            }
+            else if (value.meta.description !== undefined &&
+                typeof value.meta.description !== "string") {
+                errors.push({ path: "meta.description", message: "Expected a string" });
+            }
+        }
+        return errors.length ? { success: false, errors } : { success: true, data: value };
+    }
+    /** Judge an input object against a field map — membership, absence, and who may speak. */
+    static row(fields, input, opts = {}) {
+        if (typeof input !== 'object' || input === null) {
+            return { success: false, errors: [{ path: '.', message: 'Expected an object' }] };
+        }
+        const data = input;
+        const errors = [];
+        const out = {};
+        // Refuse, never strip: a key outside the contract is an error, not a silent
+        // drop. The client derives from the same contract (a form cannot emit a
+        // foreign key), so a stranger is a bug or an attack — both deserve the 400.
+        // Stripping would also let the envelope diverge from GraphQL, which refuses
+        // unknown input keys by construction.
+        //
+        // A FACT is judged by this same rule, deliberately — the one place it was tempting to
+        // relax it. A subscriber's copy of a fact can be older than the sender's, so tolerating
+        // a stranger key would let a rolling deployment through; it would also mean a reader
+        // silently ignoring a field it was supposed to handle. If the judge refuses, that is
+        // the end of it: the sender re-syncs its readers before it ships.
+        for (const key of Object.keys(data)) {
+            if (!(key in fields)) {
+                errors.push({ path: key, message: 'Unknown field' });
+            }
+        }
+        for (const [key, field] of Object.entries(fields)) {
+            const path = key;
+            const value = data[key];
+            if (value === undefined) {
+                if (opts.patch)
+                    continue; // patch: an unsent field is left untouched
+                // A read-only field is server-owned: its absence from a client input is
+                // never "Required" (same stance as OpenAPI readOnly+required).
+                if (boundaryOf(field).in === 'closed')
+                    continue;
+                // Absence is answered by `lifecycle.create` — a key access on the normal
+                // form. The judge only asks "is there a rule?": any rule ('now',
+                // 'optional', { value }, { generate }) makes absence legal, and the field
+                // is omitted from the result. Realisation is the storage adapter's role.
+                if (field.lifecycle?.create !== undefined)
+                    continue;
+                // No create rule: a `many` relation defaults to the empty collection
+                // (graph semantics, read on `role` — never a shared `{ value: [] }`).
+                if (field.role?.relation?.kind === 'many') {
+                    out[key] = [];
+                    continue;
+                }
+                errors.push({ path, message: 'Required' });
+                continue;
+            }
+            // A PRESENT value can be illegal by an axis other than shape:
+            // boundary `in: 'closed'` — a read-only field never crosses inbound;
+            // lifecycle `update: 'forbidden'` — re-supplying an immutable field in a patch.
+            if (boundaryOf(field).in === 'closed') {
+                errors.push({ path, message: 'Read-only' });
+                continue;
+            }
+            if (opts.patch && field.lifecycle?.update === 'forbidden') {
+                errors.push({ path, message: 'Immutable' });
+                continue;
+            }
+            // The shape predicate judges the value — null included, via the `[T,'null']`
+            // union. Then the boundary's decode converts wire→domain; null skips decode
+            // (a legal null is already the domain value, there is nothing to convert).
+            const checked = this.value(field, value);
+            if ('error' in checked) {
+                errors.push({ path, message: checked.error });
+                continue;
+            }
+            if (checked.value === null) {
+                out[key] = null;
+                continue;
+            }
+            const decoded = resolveBoundary(field).decode(checked.value);
+            if ('error' in decoded)
+                errors.push({ path, message: decoded.error });
+            else
+                out[key] = decoded.value;
+        }
+        if (errors.length > 0)
+            return { success: false, errors };
+        return { success: true, data: out };
+    }
+    /** The same judgment, as a boolean. */
+    static isField(value) {
+        return this.field(value).success;
+    }
+}
+//# sourceMappingURL=judge.js.map