@fougere/schema 0.8.2-alpha.0 → 0.8.4-alpha.0

package/dist/vocabulary/rule/unique.js.map

@@ -1 +1 @@
-{"version":3,"file":"unique.js","sourceRoot":"","sources":["../../../src/vocabulary/rule/unique.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAqC,UAAU,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IAClF,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;CACvB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"unique.js","sourceRoot":"","sources":["../../../src/vocabulary/rule/unique.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,MAAM,CAAC,MAAM,MAAM,GAAqC,UAAU,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;IAClF,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE;CACvB,CAAC,CAAC,CAAC"}

package/dist/vocabulary/rule/writeOnly.d.ts

@@ -1,7 +1,7 @@
 import { Field } from '../../field/Field.js';
 /**
- * So a secret leaves no response, the dual of `readOnly` on the same axis.
- * FR : pour qu'un secret ne reparte dans aucune réponse, dual de `readOnly`.
+ * Closes the way out, the dual of `readOnly`: the value is written and never sent back.
+ * FR : ferme la sortie, dual de `readOnly` : la valeur s'écrit et ne repart jamais.
  * `writeOnly(text())` → `boundary.out` is `'closed'`
  */
 export declare const writeOnly: <T>(field: Field<T>) => Field<T>;

package/dist/vocabulary/rule/writeOnly.js

@@ -1,11 +1,11 @@
 import { vocabulary } from '../vocabulary.js';
 import { Boundary } from '../../axis/boundary/Boundary.js';
 /**
- * So a secret leaves no response, the dual of `readOnly` on the same axis.
- * FR : pour qu'un secret ne reparte dans aucune réponse, dual de `readOnly`.
+ * Closes the way out, the dual of `readOnly`: the value is written and never sent back.
+ * FR : ferme la sortie, dual de `readOnly` : la valeur s'écrit et ne repart jamais.
  * `writeOnly(text())` → `boundary.out` is `'closed'`
  */
 export const writeOnly = vocabulary('writeOnly', (field) => ({
-    boundary: Boundary.declared(field).with({ out: 'closed' }),
+    boundary: Boundary.declared(field).declaring({ out: 'closed' }),
 }));
 //# sourceMappingURL=writeOnly.js.map

package/dist/vocabulary/rule/writeOnly.js.map

@@ -1 +1 @@
-{"version":3,"file":"writeOnly.js","sourceRoot":"","sources":["../../../src/vocabulary/rule/writeOnly.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAG3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAqC,UAAU,CACnE,WAAW,EACX,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;CAC3D,CAAC,CACH,CAAC"}
+{"version":3,"file":"writeOnly.js","sourceRoot":"","sources":["../../../src/vocabulary/rule/writeOnly.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAG3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAqC,UAAU,CACnE,WAAW,EACX,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;CAChE,CAAC,CACH,CAAC"}

package/dist/vocabulary/vocabulary.d.ts

@@ -1,7 +1,7 @@
 import { Field } from '../field/Field.js';
 /**
- * So a word is one statement about a field, not a rebuilt field.
- * FR : pour qu'un mot soit une affirmation sur un champ, pas un champ reconstruit.
+ * Builds a `rule/` word, which states members on the field it receives.
+ * FR : fabrique un mot de `rule/`, qui énonce des membres sur le champ reçu.
  * `vocabulary('indexed', () => ({ role: { index: true } }))`
  */
 export declare function vocabulary(name: string, states: (field: Field) => Partial<Field>): FieldWord;

package/dist/vocabulary/vocabulary.js

@@ -2,17 +2,17 @@ import { EXTENSION_SLOTS } from '../axis/Axis.js';
 import { dequal } from 'dequal';
 const MEMBER_SLOTS = [...EXTENSION_SLOTS, 'meta'];
 /**
- * So a word is one statement about a field, not a rebuilt field.
- * FR : pour qu'un mot soit une affirmation sur un champ, pas un champ reconstruit.
+ * Builds a `rule/` word, which states members on the field it receives.
+ * FR : fabrique un mot de `rule/`, qui énonce des membres sur le champ reçu.
  * `vocabulary('indexed', () => ({ role: { index: true } }))`
  */
 export function vocabulary(name, states) {
     return (field) => field.with(merge(name, field, states(field)));
 }
 /**
- * So two words that state the same member differently refuse instead of one winning.
- * FR : pour que deux mots contredisant un même membre refusent, plutôt qu'un l'emporte.
- * `readOnly(writeOnly(text()))` → both close a different side, so both apply
+ * Refuses two words stating one member differently, rather than letting the outer win.
+ * FR : refuse deux mots qui énoncent un même membre différemment.
+ * `readOnly(writeOnly(text()))` → both apply; `immutable(created())` → throws
  */
 function merge(name, field, given) {
     const merged = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/schema",
-  "version": "0.8.2-alpha.0",
+  "version": "0.8.4-alpha.0",
   "description": "The entity and its 4 axes — shape, role, lifecycle, boundary. Subject-owned judgments, edge-safe.",
   "keywords": [
     "fougere",

package/src/Schema.ts

@@ -42,16 +42,6 @@ export class Schema {
   /** The one place a schema holds what it is. The readings below are its projections. */
   static definition: SchemaDefinition = SchemaDefinition.of({ fields: {} });
 
-  static get fields(): Fields {
-    return this.definition.fields;
-  }
-  /** An entry survives every derivation that kept its field: `Post.pick('body').adapters`. */
-  static get adapters(): EntityAdapters<Fields> {
-    return this.definition.adapterSet.adapters;
-  }
-  static get opts(): ValidateOptions {
-    return this.definition.opts;
-  }
   static get derivation(): SchemaDerivation | undefined {
     return this.definition.derivation;
   }
@@ -75,26 +65,29 @@ export class Schema {
     }
   }
 
-  static getFields() {
-    return this.fields;
+  static getFields(): Fields {
+    return this.definition.fields;
   }
-  static getAdapters() {
-    return this.adapters;
+  /** An entry survives every derivation that kept its field: `Post.pick('body').getAdapters()`. */
+  static getAdapters(): EntityAdapters<Fields> {
+    return this.definition.adapterSet.adapters;
   }
   static getUnique(): CompositeUnique<Fields> | undefined {
     return this.definition.constraints.unique;
   }
-  static getOpts() {
-    return this.opts;
+  static getOpts(): ValidateOptions {
+    return this.definition.opts;
   }
 
   static validate(input: unknown) {
-    return InputValidator.of(this.fields, this.opts).validate(input);
+    const { fields, opts } = this.definition;
+
+    return InputValidator.of(fields, opts).validate(input);
   }
 
   static from(data: Record<string, unknown>) {
     const row: Record<string, unknown> = {};
-    for (const [key, field] of Object.entries(this.fields)) {
+    for (const [key, field] of Object.entries(this.definition.fields)) {
       if (!Object.hasOwn(data, key)) continue;
       const value = data[key];
       if (value === null || value === undefined) {
@@ -108,7 +101,8 @@ export class Schema {
   }
 
   static get ['~standard'](): StandardSchemaV1.Props<Record<string, unknown>> {
-    const { fields, opts } = this;
+    const { fields, opts } = this.definition;
+
     return {
       version: 1,
       vendor: 'fougere',
@@ -118,7 +112,7 @@ export class Schema {
         return {
           issues: verdict.errors.map((e) => ({
             message: e.message,
-            path: e.path && e.path !== '.' ? [{ key: e.path }] : undefined,
+            path: e.path.length > 0 ? e.path.map((key) => ({ key })) : undefined,
           })),
         };
       },

package/src/SchemaDefinition.ts

@@ -1,5 +1,5 @@
-import { type Fields } from './field/Field.js';
-import { FieldSet, deduplicated } from './field/FieldSet.js';
+import { type FieldName, type Fields } from './field/Field.js';
+import { FieldSet } from './field/FieldSet.js';
 import {
   type CompositeUnique,
   type EntityDeclarations,
@@ -18,8 +18,40 @@ import type { SchemaView } from './SchemaView.js';
  * and `opts` because the next rule spanning two fields — a check, an exclusion — is a
  * member here, not an eighth positional argument in a list that has already lost one.
  */
-export interface SchemaConstraints<TFields extends Fields = Fields> {
+export class SchemaConstraints<TFields extends Fields = Fields> {
   readonly unique?: CompositeUnique<TFields>;
+
+  private constructor(unique?: CompositeUnique<TFields>) {
+    if (unique) this.unique = unique;
+  }
+
+  static readonly none = new SchemaConstraints();
+
+  /**
+   * The order is part of a group, so `['a','b']` and `['b','a']` are two constraints.
+   * FR : l'ordre fait partie du groupe : `['a','b']` et `['b','a']` sont deux contraintes.
+   * `SchemaConstraints.of([['a','b'], ['a','b']])` → `unique` holds one group
+   */
+  static of<TFields extends Fields>(
+    groups: readonly (readonly FieldName<TFields>[])[],
+  ): SchemaConstraints<TFields> {
+    const seen = new Map<string, readonly FieldName<TFields>[]>();
+    for (const group of groups) seen.set(JSON.stringify(group), group);
+
+    return new SchemaConstraints(seen.size ? [...seen.values()] : undefined);
+  }
+
+  /** One member gone and the group is gone: it constrained a pair that no longer exists. */
+  renamed(transform: (key: string) => string | undefined): SchemaConstraints {
+    if (!this.unique) return SchemaConstraints.none;
+    const kept: string[][] = [];
+    for (const group of this.unique) {
+      const renamed = group.map(transform);
+      if (renamed.every((key): key is string => key !== undefined)) kept.push(renamed);
+    }
+
+    return SchemaConstraints.of(kept);
+  }
 }
 
 /**
@@ -72,6 +104,31 @@ export class SchemaDefinition {
     this.constraints = state.constraints;
   }
 
+  /**
+   * A schema cut from another one: it carries no previous names and holds no rows of its
+   * own, whatever else it keeps. `pick`, `partial`, `extend` and `compose` all land here.
+   */
+  private static derived(state: Omit<SchemaState, 'previous' | 'anchored'>): SchemaDefinition {
+    return new SchemaDefinition({ ...state, previous: undefined, anchored: false });
+  }
+
+  /**
+   * The same schema, one member restated — `declares` and `anchor`, which cut nothing.
+   * What they do not name is kept, and that is the whole difference with `derived`.
+   */
+  private restated(state: Partial<SchemaState>): SchemaDefinition {
+    return new SchemaDefinition({
+      fields: this.fields,
+      adapterSet: this.adapterSet,
+      opts: this.opts,
+      previous: this.previous,
+      derivation: this.derivation,
+      anchored: this.anchored,
+      constraints: this.constraints,
+      ...state,
+    });
+  }
+
   /** Built complete or not at all — no static assigned on the side. */
   static of(declaration: {
     fields: Fields;
@@ -89,7 +146,7 @@ export class SchemaDefinition {
       previous: declaration.previous,
       derivation: declaration.derivation,
       anchored: declaration.anchored ?? false,
-      constraints: declaration.constraints ?? {},
+      constraints: declaration.constraints ?? SchemaConstraints.none,
     });
   }
 
@@ -101,31 +158,22 @@ export class SchemaDefinition {
     ]);
     const declared = FieldSet.declaring(this.fields, declarations.unique);
 
-    return new SchemaDefinition({
+    return this.restated({
       fields: declared.fields,
       adapterSet: EntityAdapterSet.merged([
         this.adapterSet,
         EntityAdapterSet.of(declarations.adapters),
       ]),
-      opts: this.opts,
       previous: declarations.previous ?? this.previous,
-      derivation: this.derivation,
-      anchored: this.anchored,
       constraints:
-        declarations.unique === undefined ? this.constraints : { unique: declared.unique },
+        declarations.unique === undefined
+          ? this.constraints
+          : SchemaConstraints.of(declared.groups),
     });
   }
 
   anchoring(): SchemaDefinition {
-    return new SchemaDefinition({
-      fields: this.fields,
-      adapterSet: this.adapterSet,
-      opts: this.opts,
-      previous: this.previous,
-      derivation: this.derivation,
-      anchored: true,
-      constraints: this.constraints,
-    });
+    return this.restated({ anchored: true });
   }
 
   pick(keys: readonly string[], root: SchemaView): SchemaDefinition {
@@ -160,52 +208,32 @@ export class SchemaDefinition {
     }
     const nameOf = (key: string) => kept.get(key);
 
-    return new SchemaDefinition({
+    return SchemaDefinition.derived({
       fields,
       adapterSet: this.adapterSet.rename(nameOf),
       opts: this.opts,
-      previous: undefined,
       derivation: this.origin(root).rename(nameOf),
-      anchored: false,
-      constraints: this.constraintsRenamed(nameOf),
+      constraints: this.constraints.renamed(nameOf),
     });
   }
 
-  /** One member gone and the group is gone: it constrained a pair that no longer exists. */
-  private constraintsRenamed(
-    transform: (key: string) => string | undefined,
-  ): SchemaConstraints {
-    if (!this.constraints.unique) return this.constraints;
-    const kept: string[][] = [];
-    for (const group of this.constraints.unique) {
-      const renamed = group.map(transform);
-      if (renamed.every((key): key is string => key !== undefined)) kept.push(renamed);
-    }
-
-    return { unique: deduplicated(kept) as CompositeUnique<Fields> | undefined };
-  }
-
   patched(root: SchemaView): SchemaDefinition {
-    return new SchemaDefinition({
+    return SchemaDefinition.derived({
       fields: { ...this.fields },
       adapterSet: this.adapterSet,
       opts: { ...this.opts, patch: true },
-      previous: undefined,
       derivation: this.origin(root),
-      anchored: false,
       constraints: this.constraints,
     });
   }
 
   /** An added field does not pretend to come from the root, which never declared it. */
   extended(extra: Fields, root: SchemaView): SchemaDefinition {
-    return new SchemaDefinition({
+    return SchemaDefinition.derived({
       fields: { ...this.fields, ...extra },
       adapterSet: this.adapterSet,
       opts: this.opts,
-      previous: undefined,
       derivation: this.origin(root),
-      anchored: false,
       constraints: this.constraints,
     });
   }
@@ -221,22 +249,20 @@ export class SchemaDefinition {
       groups.push(...(view.getUnique() ?? []));
     }
 
-    return new SchemaDefinition({
+    return SchemaDefinition.derived({
       fields,
       adapterSet: EntityAdapterSet.merged(
         views.map((view) => EntityAdapterSet.of(view.getAdapters())),
       ),
       opts,
-      previous: undefined,
       derivation: undefined,
-      anchored: false,
-      constraints: { unique: deduplicated(groups) as CompositeUnique<Fields> | undefined },
+      constraints: SchemaConstraints.of(groups),
     });
   }
 
   /**
-   * So a gesture naming a field that does not exist says so, and lists what there is.
-   * FR : pour qu'un geste nommant un champ inexistant le dise, et énumère ce qui existe.
+   * Refuses a gesture naming a field the schema does not carry, and lists what it does.
+   * FR : refuse un geste nommant un champ absent, et énumère ceux qui existent.
    * `pick('titel')` → `pick(): unknown field \`titel\`. This schema carries id, title, body.`
    */
   private assertKnown(operation: string, keys: readonly string[]): void {

package/src/SchemaView.ts

@@ -1,7 +1,7 @@
 import type { Field, Fields } from './field/Field.js';
 import type { CompositeUnique, PreviousNames } from './entity/EntityDeclarations.js';
 import type { EntityAdapters } from './entity/EntityAdapters.js';
-import type { ValidationResult } from './validation.js';
+import type { ValidationResult } from './lib/validation.js';
 import type { ValidateOptions } from './validator/InputValidator.js';
 import type { SchemaDerivation } from './SchemaDerivation.js';
 

package/src/axis/Axis.ts

@@ -1,7 +1,7 @@
 import { roleAxis } from './role/RoleAxis.js';
 import { lifecycleAxis } from './lifecycle/LifecycleAxis.js';
 import { boundaryAxis } from './boundary/BoundaryAxis.js';
-import type { ValidationError } from '../validation.js';
+import type { ValidationError } from '../lib/validation.js';
 
 export interface Axis<Declared = unknown, Wire = unknown> {
   readonly slot: 'role' | 'lifecycle' | 'boundary';

package/src/axis/boundary/Boundaries.ts

@@ -1,6 +1,11 @@
 import type { BoundaryRules } from './Boundary.js';
 import { Registry } from '../../lib/Registry.js';
 
+/**
+ * Wire to domain, and it must ANSWER a value it already produced: two doors decode — the
+ * client one on what arrives, `StorageGuard` on what a handler writes — so a decoder that
+ * halves cents halves them twice and stores a hundredth.
+ */
 export type Decoder = (value: unknown) => { value: unknown } | { error: string };
 export type Encoder = (value: unknown) => unknown;
 

package/src/axis/boundary/Boundary.ts

@@ -13,9 +13,9 @@ export type BoundaryRef = 'isoDate' | (string & {}) | BoundaryRules;
 const identityDecoder: Decoder = (value) => ({ value });
 const identityEncoder: Encoder = (value) => value;
 
-export class Boundary implements BoundaryRules {
-  readonly in?: BoundaryRules['in'];
-  readonly out?: BoundaryRules['out'];
+export class Boundary {
+  private readonly in?: BoundaryRules['in'];
+  private readonly out?: BoundaryRules['out'];
   readonly decode: Decoder;
   readonly encode: Encoder;
 
@@ -61,15 +61,13 @@ export class Boundary implements BoundaryRules {
 
   /** `date-time` means a `Date` on both sides, without a word in the entity. */
   static forShape(shape: Shape | undefined): Boundary {
-    const base = Shapes.of(shape).base;
-    if (base?.type === 'string' && base.format === 'date-time') {
-      return new Boundary(Boundaries.aliases.find('isoDate')!);
-    }
+    if (Shapes.typeOf(shape) === 'date') return new Boundary(Boundaries.aliases.find('isoDate')!);
     return new Boundary();
   }
 
-  with(overrides: BoundaryRules): Boundary {
-    return new Boundary({ in: overrides.in ?? this.in, out: overrides.out ?? this.out });
+  /** The dual of `declared`: what `readOnly()` writes back on the field, not a judge. */
+  declaring(overrides: BoundaryRules): BoundaryRules {
+    return { in: overrides.in ?? this.in, out: overrides.out ?? this.out };
   }
 
   get readOnly(): boolean {

package/src/axis/boundary/BoundaryAxis.ts

@@ -10,7 +10,7 @@ export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
     if (typeof value === 'string') return; 
     if (!isObject(value)) {
       errors.push({
-        path: 'boundary',
+        path: ['boundary'],
         message: `Expected an alias name or { in, out } — got ${shown(value)}`,
       });
       return;
@@ -19,7 +19,7 @@ export const boundaryAxis: Axis<BoundaryRef, BoundaryRef> = {
       const rule = value[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> }` });
+        errors.push({ path: ['boundary', side], message: `Expected 'closed' or { ${verb}: <name> }` });
       }
     }
   },

package/src/axis/lifecycle/Lifecycle.ts

@@ -8,9 +8,9 @@ export interface LifecycleRules {
   update?: (typeof UPDATE_TOKENS)[number];
 }
 
-export class Lifecycle implements LifecycleRules {
-  readonly create?: LifecycleRules['create'];
-  readonly update?: LifecycleRules['update'];
+export class Lifecycle {
+  private readonly create?: LifecycleRules['create'];
+  private readonly update?: LifecycleRules['update'];
 
   private constructor(rules: LifecycleRules = {}) {
     this.create = rules.create;
@@ -25,8 +25,13 @@ export class Lifecycle implements LifecycleRules {
     return this.create === undefined;
   }
 
+  /** The server fills it at create, so a client form never carries it. */
+  get stampedAtCreate(): boolean {
+    return this.create === 'now';
+  }
+
   get stampedOnce(): boolean {
-    return this.create === 'now' && this.update !== 'now';
+    return this.stampedAtCreate && !this.stampedOnUpdate;
   }
 
   get immutable(): boolean {

package/src/axis/lifecycle/LifecycleAxis.ts

@@ -1,5 +1,5 @@
 import type { Axis } from '../Axis.js';
-import type { ValidationError } from '../../validation.js';
+import type { ValidationError } from '../../lib/validation.js';
 import { admitWire, oneOfTokens } from '../../projection/card/admission.js';
 import { isObject, shown } from '../../lib/utils.js';
 import { CREATE_TOKENS, UPDATE_TOKENS, type LifecycleRules } from './Lifecycle.js';
@@ -9,13 +9,13 @@ export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
 
   validator(value, errors) {
     if (!isObject(value)) {
-      errors.push({ path: 'lifecycle', message: `Expected an object — got ${shown(value)}` });
+      errors.push({ path: ['lifecycle'], message: `Expected an object — got ${shown(value)}` });
       return;
     }
     if (value.create !== undefined) validateCreate(value.create, errors);
     if (value.update !== undefined && !oneOfTokens(value.update, UPDATE_TOKENS)) {
       errors.push({
-        path: 'lifecycle.update',
+        path: ['lifecycle', 'update'],
         message: `Expected 'now' or 'forbidden' — got ${shown(value.update)}`,
       });
     }
@@ -29,8 +29,8 @@ export const lifecycleAxis: Axis<LifecycleRules, LifecycleRules> = {
 };
 
 /**
- * So the four legal ways to declare a creation are stated once, and anything else names them.
- * FR : pour que les quatre façons de déclarer une création soient dites une fois.
+ * Judges the create rule, whose four legal forms are stated here and nowhere else.
+ * FR : juge la règle de création, dont les quatre formes légales sont énoncées ici seulement.
  * `create: 3` → `Expected 'now', 'optional', { value } or { generate } — got 3`
  */
 function validateCreate(rule: unknown, errors: ValidationError[]): void {
@@ -40,7 +40,7 @@ function validateCreate(rule: unknown, errors: ValidationError[]): void {
     if ('generate' in rule) {
       if (typeof rule.generate !== 'string') {
         errors.push({
-          path: 'lifecycle.create.generate',
+          path: ['lifecycle', 'create', 'generate'],
           message: `Expected a generator name — got ${shown(rule.generate)}`,
         });
       }
@@ -48,7 +48,7 @@ function validateCreate(rule: unknown, errors: ValidationError[]): void {
     }
   }
   errors.push({
-    path: 'lifecycle.create',
+    path: ['lifecycle', 'create'],
     message: `Expected 'now', 'optional', { value } or { generate } — got ${shown(rule)}`,
   });
 }

package/src/axis/lifecycle/apply.ts

@@ -4,10 +4,9 @@ import { Clock } from './Clock.js';
 import { type Field, type Fields } from '../../field/Field.js';
 
 /**
- * So every storage realizes a create the same way.
- * FR : pour que chaque storage réalise une création de la même façon.
- * `applyCreate({ id: primary(), createdAt: created() }, { title: 'a' })`
- * → `id` generated, `createdAt` stamped, `title` untouched
+ * Fills what the declaration leaves to the storage, so no handler stamps a date itself.
+ * FR : remplit ce que la déclaration laisse au storage : aucun handler n'estampe lui-même.
+ * `applyCreate({ id: primary(), createdAt: created() }, { title: 'a' })` → `id`, `createdAt`
  */
 export function applyCreate(fields: Fields, input: Record<string, unknown>): Record<string, unknown> {
   const values: Record<string, unknown> = { ...input };
@@ -17,7 +16,7 @@ export function applyCreate(fields: Fields, input: Record<string, unknown>): Rec
     if (name in values) continue;
     const rule = Lifecycle.of(field);
 
-    if (rule.create === 'now') values[name] = new Date(instant);
+    if (rule.stampedAtCreate) values[name] = new Date(instant);
     else if (rule.literal) values[name] = freshValue(rule.literal.value);
     else if (rule.generator) values[name] = Generators.resolve(rule.generator)();
   }
@@ -26,8 +25,9 @@ export function applyCreate(fields: Fields, input: Record<string, unknown>): Rec
 }
 
 /**
- * So two rows created from one declared default never end up sharing the same object.
- * FR : pour que deux lignes nées d'un même défaut ne partagent pas l'objet.
+ * Clones a declared default, so two rows born of `create: { value: [] }` hold two arrays.
+ * FR : clone un défaut déclaré, pour que deux lignes nées de `create: { value: [] }`
+ * tiennent deux tableaux.
  * `create: { value: [] }` → each instance gets its own array
  */
 function freshValue(value: unknown): unknown {
@@ -36,8 +36,9 @@ function freshValue(value: unknown): unknown {
 }
 
 /**
- * So `updated()` is stamped by the storage, and no handler has to remember it.
- * FR : pour qu'`updated()` soit estampé par le storage, pas par le handler.
+ * The dual of `applyCreate` on a patch: only `update: 'now'` fields are touched.
+ * FR : le dual d'`applyCreate` sur une modification : seuls les champs `update: 'now'`
+ * sont touchés.
  * `applyUpdate(fields, { title: 'b' })` → `updatedAt` added, nothing else
  */
 export function applyUpdate(fields: Fields, patch: Record<string, unknown>): Record<string, unknown> {

package/src/axis/role/Role.ts

@@ -7,11 +7,11 @@ export interface RoleRules {
   relation?: Relation;
 }
 
-export class Role implements RoleRules {
-  readonly primary?: boolean;
-  readonly index?: boolean;
-  readonly unique?: boolean;
-  readonly relation?: Relation;
+export class Role {
+  private readonly primary?: boolean;
+  private readonly index?: boolean;
+  private readonly unique?: boolean;
+  private readonly relation?: Relation;
 
   private constructor(rules: RoleRules = {}) {
     this.primary = rules.primary;
@@ -45,8 +45,17 @@ export class Role implements RoleRules {
     return this.relation?.kind === 'one';
   }
 
+  /** Either kind — what a CLI flag and a GraphQL selection both leave out. */
+  get isRelation(): boolean {
+    return this.relation !== undefined;
+  }
+
   /** Calls `() => Post` so no caller has to. */
   get target(): EntityConstructor | undefined {
     return this.relation?.to();
   }
+
+  get onDelete(): Relation['onDelete'] {
+    return this.relation?.onDelete;
+  }
 }