@fougere/schema 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/{judge/ValueJudge.ts → validator/FieldValueValidator.ts}

@@ -1,8 +1,8 @@
 import { Validator, format as engineFormats } from '@cfworker/json-schema';
 import { Formats, type FormatPredicate } from '../axis/shape/Formats.js';
-import { Anatomy, type Shape } from '../axis/shape/Shape.js';
-import type { Field } from '../fields/Field.js';
-import type { Checked } from './result.js';
+import { Shapes, type Shape } from '../axis/shape/Shape.js';
+import type { Field } from '../field/Field.js';
+import type { Checked } from '../validation.js';
 
 interface ShapePlan {
   validator: Validator;
@@ -10,21 +10,26 @@ interface ShapePlan {
   formatName?: string;
 }
 
-export class ValueJudge {
+export class FieldValueValidator {
   private static readonly plans = new WeakMap<object, ShapePlan>();
 
   private constructor(private readonly field: Field) {}
 
-  static of(field: Field): ValueJudge {
-    return new ValueJudge(field);
+  /** The shape is compiled once and reused, not rebuilt per value. */
+  static of(field: Field): FieldValueValidator {
+    return new FieldValueValidator(field);
   }
 
-  check(value: unknown): Checked {
+  validate(value: unknown): Checked {
     const shape = this.field.shape;
-    const base = Anatomy.of(shape).base;
+    const base = Shapes.of(shape).base;
     if (value !== null) {
       if (base?.type === 'object' && !base.properties) return { value };
-      if (base?.type === 'string' && base.format === 'date-time' && value instanceof Date) {
+      if (
+        base?.type === 'string' &&
+        base.format === 'date-time' &&
+        value instanceof Date
+      ) {
         return Number.isNaN(value.getTime()) ? { error: 'Invalid date' } : { value };
       }
       if (
@@ -35,7 +40,7 @@ export class ValueJudge {
         return { error: 'Expected a number' };
       }
     }
-    const plan = ValueJudge.planFor(shape);
+    const plan = FieldValueValidator.planFor(shape);
     const result = plan.validator.validate(value);
     if (!result.valid) return { error: result.errors[0]?.error ?? 'Invalid value' };
     if (plan.custom && typeof value === 'string' && !plan.custom(value)) {
@@ -47,7 +52,7 @@ export class ValueJudge {
   private static planFor(shape: Shape): ShapePlan {
     let plan = this.plans.get(shape);
     if (!plan) {
-      const base = Anatomy.of(shape).base;
+      const base = Shapes.of(shape).base;
       const formatName = base?.type === 'string' ? base.format : undefined;
       plan = {
         validator: new Validator(shape as object, '2020-12', true),
@@ -60,11 +65,11 @@ export class ValueJudge {
   }
 
   private static customFormatOf(name: string): FormatPredicate | undefined {
-    const custom = Formats.resolve(name);
+    const custom = Formats.find(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.`,
+          `the engine validates ${Object.keys(engineFormats).length} formats natively and this is not one of them.`,
       );
     }
     return custom;

package/src/{judge/RowRefusal.ts → validator/InputRefusal.ts}

@@ -3,15 +3,13 @@
  *
  * A value refused by its own shape carries the engine's message and a decoder refused by
  * user code carries that code's; neither is structural and neither belongs here. These
- * five are `RowJudge`'s own, and a table of cases enumerates them instead of reading the
+ * five are `InputValidator`'s own, and a table of cases enumerates them instead of reading the
  * text of a function — which a minifier rewrites without a word.
  */
-export const RowRefusal = {
+export const InputRefusal = {
   notAnObject: 'Expected an object',
   unknownField: 'Unknown field',
   required: 'Required',
   readOnly: 'Read-only',
   immutable: 'Immutable',
 } as const;
-
-export type RowRefusal = (typeof RowRefusal)[keyof typeof RowRefusal];

package/src/{judge/RowJudge.ts → validator/InputValidator.ts}

@@ -1,20 +1,23 @@
 import { Boundary } from '../axis/boundary/Boundary.js';
 import { Lifecycle } from '../axis/lifecycle/Lifecycle.js';
 import { Role } from '../axis/role/Role.js';
-import type { Field, Fields } from '../fields/Field.js';
-import type { ValidateOptions } from './options.js';
-import type { ValidationError, ValidationResult } from './result.js';
-import { ValueJudge } from './ValueJudge.js';
-import { RowRefusal } from './RowRefusal.js';
+import type { Field, Fields } from '../field/Field.js';
+import type { ValidationError, ValidationResult } from '../validation.js';
+import { FieldValueValidator } from './FieldValueValidator.js';
+import { InputRefusal } from './InputRefusal.js';
 
-export class RowJudge {
+export interface ValidateOptions {
+  patch?: boolean;
+}
+
+export class InputValidator {
   private constructor(
     private readonly fields: Fields,
     private readonly options: ValidateOptions,
   ) {}
 
-  static of(fields: Fields, options: ValidateOptions = {}): RowJudge {
-    return new RowJudge(fields, options);
+  static of(fields: Fields, options: ValidateOptions = {}): InputValidator {
+    return new InputValidator(fields, options);
   }
 
   onAbsent(field: Field): 'skip' | 'empty-list' | null {
@@ -24,18 +27,22 @@ export class RowJudge {
     return null;
   }
 
-  check(input: unknown): ValidationResult<Record<string, unknown>> {
+  /** Hands on the value it PARSED, so a handler never re-checks a row. */
+  validate(input: unknown): ValidationResult<Record<string, unknown>> {
     if (typeof input !== 'object' || input === null) {
-      return { success: false, errors: [{ path: '.', message: RowRefusal.notAnObject }] };
+      return {
+        success: false,
+        errors: [{ path: '.', message: InputRefusal.notAnObject }],
+      };
     }
 
     const data = input as Record<string, unknown>;
     const errors: ValidationError[] = [];
-    const out: Record<string, unknown> = {};
+    const row: Record<string, unknown> = {};
 
     for (const key of Object.keys(data)) {
       if (!(key in this.fields)) {
-        errors.push({ path: key, message: RowRefusal.unknownField });
+        errors.push({ path: key, message: InputRefusal.unknownField });
       }
     }
 
@@ -47,38 +54,38 @@ export class RowJudge {
         if (this.options.patch) continue;
         const absence = this.onAbsent(field);
         if (absence === null) {
-          errors.push({ path, message: RowRefusal.required });
+          errors.push({ path, message: InputRefusal.required });
           continue;
         }
-        if (absence === 'empty-list') out[key] = [];
+        if (absence === 'empty-list') row[key] = [];
         continue;
       }
 
       const boundary = Boundary.of(field);
       if (boundary.readOnly) {
-        errors.push({ path, message: RowRefusal.readOnly });
+        errors.push({ path, message: InputRefusal.readOnly });
         continue;
       }
       if (this.options.patch && Lifecycle.of(field).immutable) {
-        errors.push({ path, message: RowRefusal.immutable });
+        errors.push({ path, message: InputRefusal.immutable });
         continue;
       }
 
-      const checked = ValueJudge.of(field).check(value);
+      const checked = FieldValueValidator.of(field).validate(value);
       if ('error' in checked) {
         errors.push({ path, message: checked.error });
         continue;
       }
       if (checked.value === null) {
-        out[key] = null;
+        row[key] = null;
         continue;
       }
       const decoded = boundary.decode(checked.value);
       if ('error' in decoded) errors.push({ path, message: decoded.error });
-      else out[key] = decoded.value;
+      else row[key] = decoded.value;
     }
 
     if (errors.length > 0) return { success: false, errors };
-    return { success: true, data: out };
+    return { success: true, data: row };
   }
 }

package/src/vocabulary/bool.ts

@@ -1,9 +1,15 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
+/**
+ * So a default is a lifecycle rule, not a value the handler remembers to set.
+ * FR : pour qu'un défaut soit une règle de cycle de vie, pas un oubli possible du handler.
+ * `bool({ default: false })`
+ */
 export function bool(opts?: { default?: boolean; description?: string }): Field<boolean> {
   return new Field<boolean>({
     shape: { type: 'boolean' },
-    lifecycle: opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
+    lifecycle:
+      opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
     meta: opts?.description !== undefined ? { description: opts.description } : undefined,
   });
 }

package/src/vocabulary/created.ts

@@ -1,8 +1,13 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 import { date } from './date.js';
 
+/**
+ * So a creation stamp is written by the storage and refused from a client.
+ * FR : pour qu'un horodatage de création soit écrit par le storage et refusé au client.
+ * `created()` → `create: 'now'`, `update: 'forbidden'`
+ */
 export function created(): Field<Date> {
   return date().with({
-    lifecycle: { create: "now", update: "forbidden" },
+    lifecycle: { create: 'now', update: 'forbidden' },
   });
 }

package/src/vocabulary/date.ts

@@ -1,5 +1,10 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
+/**
+ * So a date is a string on the wire and a `Date` in a handler, with no word said.
+ * FR : pour qu'une date soit une chaîne sur le fil et une `Date` dans un handler.
+ * `date()` → `{ type: 'string', format: 'date-time' }`, decoded by the `isoDate` boundary
+ */
 export function date(): Field<Date> {
   return new Field<Date>({ shape: { type: 'string', format: 'date-time' } });
 }

package/src/vocabulary/email.ts

@@ -1,6 +1,11 @@
 import { text, type TextOptions } from './text.js';
-import type { Field } from '../fields/Field.js';
+import type { Field } from '../field/Field.js';
 
+/**
+ * So the format is stated once, where everyone would otherwise write the same regex.
+ * FR : pour que le format soit énoncé une fois, là où chacun réécrirait la même regex.
+ * `email({ max: 254 })`
+ */
 export function email(opts?: Omit<TextOptions, 'format'>): Field<string> {
   return text({ ...opts, format: 'email' });
 }

package/src/vocabulary/immutable.ts

@@ -1,6 +1,14 @@
 import { vocabulary } from './vocabulary.js';
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
-export const immutable: <T>(field: Field<T>) => Field<T> = vocabulary('immutable', () => ({
-  lifecycle: { update: 'forbidden' },
-}));
+/**
+ * So a write-once field is refused on a patch by the validator, not by the table.
+ * FR : pour qu'un champ écrit une fois soit refusé par le juge sur une modification.
+ * `immutable(text())` → `update: 'forbidden'`
+ */
+export const immutable: <T>(field: Field<T>) => Field<T> = vocabulary(
+  'immutable',
+  () => ({
+    lifecycle: { update: 'forbidden' },
+  }),
+);

package/src/vocabulary/indexed.ts

@@ -1,4 +1,11 @@
 import { vocabulary } from './vocabulary.js';
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
-export const indexed: <T>(field: Field<T>) => Field<T> = vocabulary('indexed', () => ({ role: { index: true } }));
+/**
+ * So the entity states the index, and the DDL is the one that emits it.
+ * FR : pour que l'entité énonce l'index, le DDL étant celui qui l'émet.
+ * `indexed(text())` → `role.index` is `true`
+ */
+export const indexed: <T>(field: Field<T>) => Field<T> = vocabulary('indexed', () => ({
+  role: { index: true },
+}));

package/src/vocabulary/json.ts

@@ -1,20 +1,27 @@
-import { Field } from '../fields/Field.js';
-import type { SchemaView } from '../schema/SchemaView.js';
-import { RowJudge } from '../judge/RowJudge.js';
+import { Field } from '../field/Field.js';
+import type { SchemaView } from '../SchemaView.js';
+import { InputValidator } from '../validator/InputValidator.js';
 
 export function json<T = unknown>(): Field<T>;
-export function json<E extends SchemaView & (new (...args: any[]) => any)>(of: E): Field<InstanceType<E>>;
+export function json<E extends SchemaView & (new (...args: any[]) => any)>(
+  of: E,
+): Field<InstanceType<E>>;
+/**
+ * So a stored object can carry a schema, instead of admitting any shape forever.
+ * FR : pour qu'un objet stocké porte un schéma, au lieu d'admettre toute forme à jamais.
+ * `json(Address)` → the object's properties and its required keys
+ */
 export function json(of?: SchemaView): Field<unknown> {
   if (!of) return new Field({ shape: { type: 'object' } });
   const fields = of.getFields();
-  const judge = RowJudge.of(fields);
+  const validator = InputValidator.of(fields);
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
   for (const [key, field] of Object.entries(fields)) {
     properties[key] = field.meta?.description
       ? { ...field.shape, description: field.meta.description }
       : field.shape;
-    if (judge.onAbsent(field) === null) required.push(key);
+    if (validator.onAbsent(field) === null) required.push(key);
   }
   return new Field({
     shape: { type: 'object', properties, ...(required.length ? { required } : {}) },

package/src/vocabulary/list.ts

@@ -1,12 +1,20 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
 export interface ListOptions {
   min?: number;
   max?: number;
 }
 
+/**
+ * So a list of values is told apart from a relation, which `many()` declares.
+ * FR : pour qu'une liste de valeurs se distingue d'une relation, que `many()` déclare.
+ * `list(text(), { max: 5 })`; `list(ref(User))` → throws
+ */
 export function list<T>(item: Field<T>, opts?: ListOptions): Field<T[]> {
-  if (item.role?.relation) throw new Error('list() takes a value field (text(), number()…) — a relation has no value shape');
+  if (item.role?.relation)
+    throw new Error(
+      'list() takes a value field (text(), number()…) — a relation has no value shape',
+    );
   return new Field<T[]>({
     shape: { type: 'array', items: item.shape, minItems: opts?.min, maxItems: opts?.max },
   });

package/src/vocabulary/many.ts

@@ -1,7 +1,14 @@
 import { Relation, type EntityConstructor } from '../axis/role/Relation.js';
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
-export function many<E extends EntityConstructor>(target: E | (() => E)): Field<InstanceType<E>[]> {
+/**
+ * So the other side of a reference is declared, and holds no column.
+ * FR : pour que l'autre côté d'une référence soit déclaré, sans porter de colonne.
+ * `many(() => Post)` → a collection, absent from the row a client sends
+ */
+export function many<E extends EntityConstructor>(
+  target: E | (() => E),
+): Field<InstanceType<E>[]> {
   return new Field<InstanceType<E>[]>({
     shape: { type: 'array' },
     role: { relation: Relation.many(target) },

package/src/vocabulary/nullable.ts

@@ -1,7 +1,15 @@
 import { vocabulary } from './vocabulary.js';
-import { Anatomy } from '../axis/shape/Shape.js';
-import { type Field } from '../fields/Field.js';
+import { Shapes } from '../axis/shape/Shape.js';
+import { type Field } from '../field/Field.js';
 
-export const nullable: <T>(field: Field<T>) => Field<T | null> = vocabulary('nullable', (field) => ({
-  shape: Anatomy.nullable(field.shape),
-}));
+/**
+ * So `null` becomes a legal value, without touching whether the field is required.
+ * FR : pour que `null` devienne légal, sans toucher au caractère obligatoire du champ.
+ * `nullable(text())` → `{ type: ['string', 'null'] }`, still required at create
+ */
+export const nullable: <T>(field: Field<T>) => Field<T | null> = vocabulary(
+  'nullable',
+  (field) => ({
+    shape: Shapes.nullable(field.shape),
+  }),
+);

package/src/vocabulary/number.ts

@@ -1,4 +1,4 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
 export interface NumberOptions {
   min?: number;
@@ -8,10 +8,20 @@ export interface NumberOptions {
   description?: string;
 }
 
+/**
+ * So `integer` is a shape, not a second word to remember.
+ * FR : pour qu'`integer` soit une forme, pas un second mot à retenir.
+ * `number({ integer: true, min: 0 })` → `{ type: 'integer', minimum: 0 }`
+ */
 export function number(opts?: NumberOptions): Field<number> {
   return new Field<number>({
-    shape: { type: opts?.integer ? 'integer' : 'number', minimum: opts?.min, maximum: opts?.max },
-    lifecycle: opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
+    shape: {
+      type: opts?.integer ? 'integer' : 'number',
+      minimum: opts?.min,
+      maximum: opts?.max,
+    },
+    lifecycle:
+      opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
     meta: opts?.description !== undefined ? { description: opts.description } : undefined,
   });
 }

package/src/vocabulary/oneOf.ts

@@ -1,14 +1,21 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
 interface OneOfOptions<V extends string = string> {
   description?: string;
   default?: V;
 }
 
-export function oneOf<const T extends readonly string[]>(...values: [...T]): Field<T[number]>;
+export function oneOf<const T extends readonly string[]>(
+  ...values: [...T]
+): Field<T[number]>;
 export function oneOf<const T extends readonly string[]>(
   ...args: [...T, OneOfOptions<T[number]>]
 ): Field<T[number]>;
+/**
+ * So the set is in the type and in the CHECK constraint, from one declaration.
+ * FR : pour que l'ensemble soit dans le type et dans la contrainte CHECK, d'une déclaration.
+ * `oneOf('draft', 'published', { default: 'draft' })`
+ */
 export function oneOf<const T extends readonly string[]>(
   ...args: [...T] | [...T, OneOfOptions<T[number]>]
 ): Field<T[number]> {
@@ -18,7 +25,8 @@ export function oneOf<const T extends readonly string[]>(
   const opts = hasOpts ? (last as OneOfOptions) : {};
   return new Field<T[number]>({
     shape: { type: 'string', enum: values },
-    lifecycle: opts.default !== undefined ? { create: { value: opts.default } } : undefined,
+    lifecycle:
+      opts.default !== undefined ? { create: { value: opts.default } } : undefined,
     meta: opts.description !== undefined ? { description: opts.description } : undefined,
   });
 }

package/src/vocabulary/optional.ts

@@ -1,8 +1,18 @@
 import { vocabulary } from './vocabulary.js';
-import { Anatomy } from '../axis/shape/Shape.js';
-import { type Field } from '../fields/Field.js';
+import { Shapes } from '../axis/shape/Shape.js';
+import { type Field } from '../field/Field.js';
 
-export const optional: <T>(field: Field<T>) => Field<T | null> = vocabulary('optional', (field) => ({
-  shape: Anatomy.nullable(field.shape),
-  ...(field.lifecycle?.create === undefined ? { lifecycle: { create: 'optional' as const } } : {}),
-}));
+/**
+ * So the two questions are settled at once: `null` is legal, and absence is too.
+ * FR : pour que les deux questions soient réglées d'un coup : `null` légal, absence permise.
+ * `optional(text())` → nullable shape and `create: 'optional'`
+ */
+export const optional: <T>(field: Field<T>) => Field<T | null> = vocabulary(
+  'optional',
+  (field) => ({
+    shape: Shapes.nullable(field.shape),
+    ...(field.lifecycle?.create === undefined
+      ? { lifecycle: { create: 'optional' as const } }
+      : {}),
+  }),
+);

package/src/vocabulary/primary.ts

@@ -1,4 +1,4 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 import { Generators, type GeneratorRef } from '../axis/lifecycle/Generators.js';
 
 interface PrimaryOptions {
@@ -7,12 +7,17 @@ interface PrimaryOptions {
 
 export function primary(opts?: PrimaryOptions): Field<string>;
 export function primary<T>(field: Field<T>): Field<T>;
+/**
+ * So an id is generated and write-once by declaring nothing else.
+ * FR : pour qu'un identifiant soit généré et écrit une fois sans rien déclarer d'autre.
+ * `primary()` → cuid2, `update: 'forbidden'`; `primary(number())` → the same on a number
+ */
 export function primary(fieldOrOptions?: Field | PrimaryOptions): Field {
   if (Field.is(fieldOrOptions)) {
     const field = fieldOrOptions;
     return field.with({
       role: { ...field.role, primary: true },
-      lifecycle: { ...field.lifecycle, update: "forbidden" },
+      lifecycle: { ...field.lifecycle, update: 'forbidden' },
     });
   }
 
@@ -23,11 +28,11 @@ export function primary(fieldOrOptions?: Field | PrimaryOptions): Field {
     Generators.register(name, fn);
     generate = name;
   } else {
-    generate = opts.generate ?? "cuid2";
+    generate = opts.generate ?? 'cuid2';
   }
   return new Field<string>({
-    shape: { type: "string" },
+    shape: { type: 'string' },
     role: { primary: true },
-    lifecycle: { create: { generate }, update: "forbidden" },
+    lifecycle: { create: { generate }, update: 'forbidden' },
   });
 }

package/src/vocabulary/readOnly.ts

@@ -1,7 +1,15 @@
 import { vocabulary } from './vocabulary.js';
 import { Boundary } from '../axis/boundary/Boundary.js';
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
-export const readOnly: <T>(field: Field<T>) => Field<T> = vocabulary('readOnly', (field) => ({
-  boundary: Boundary.declared(field).with({ in: 'closed' }),
-}));
+/**
+ * So a field a client may read but never write says so once, on the field.
+ * FR : pour qu'un champ lisible mais non écrivable le dise une fois, sur le champ.
+ * `readOnly(text())` → `boundary.in` is `'closed'`, absent from every form
+ */
+export const readOnly: <T>(field: Field<T>) => Field<T> = vocabulary(
+  'readOnly',
+  (field) => ({
+    boundary: Boundary.declared(field).with({ in: 'closed' }),
+  }),
+);

package/src/vocabulary/ref.ts

@@ -1,11 +1,19 @@
 import { Relation, type EntityConstructor } from '../axis/role/Relation.js';
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
 export interface RefOptions {
   cascade?: boolean;
 }
 
-export function ref<E extends EntityConstructor>(target: E | (() => E), opts?: RefOptions): Field<string> {
+/**
+ * So a reference names the target entity, and the column type follows from it.
+ * FR : pour qu'une référence nomme l'entité cible, la colonne en découlant.
+ * `ref(() => User, { cascade: true })`
+ */
+export function ref<E extends EntityConstructor>(
+  target: E | (() => E),
+  opts?: RefOptions,
+): Field<string> {
   return new Field<string>({
     shape: { type: 'string' },
     role: { relation: Relation.one(target, opts?.cascade) },

package/src/vocabulary/text.ts

@@ -1,4 +1,4 @@
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 import { type StringFormat } from '../axis/shape/Formats.js';
 
 export interface TextOptions {
@@ -10,10 +10,22 @@ export interface TextOptions {
   description?: string;
 }
 
+/**
+ * So a string field states its bounds where the DDL and the validator both read them.
+ * FR : pour qu'un champ texte énonce ses bornes là où le DDL et le juge les lisent.
+ * `text({ max: 200, format: 'email' })`
+ */
 export function text(opts?: TextOptions): Field<string> {
   return new Field<string>({
-    shape: { type: 'string', minLength: opts?.min, maxLength: opts?.max, pattern: opts?.pattern, format: opts?.format },
-    lifecycle: opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
+    shape: {
+      type: 'string',
+      minLength: opts?.min,
+      maxLength: opts?.max,
+      pattern: opts?.pattern,
+      format: opts?.format,
+    },
+    lifecycle:
+      opts?.default !== undefined ? { create: { value: opts.default } } : undefined,
     meta: opts?.description !== undefined ? { description: opts.description } : undefined,
   });
 }

package/src/vocabulary/unique.ts

@@ -1,10 +1,11 @@
-import { vocabulary } from "./vocabulary.js";
-import { Field } from "../fields/Field.js";
-import { Unique } from "../constraint/Unique.js";
+import { vocabulary } from './vocabulary.js';
+import { Field } from '../field/Field.js';
 
-export const unique: <T>(field: Field<T>) => Field<T> = vocabulary(
-  "unique",
-  (field) => ({
-    role: { rules: [...(field.role?.rules ?? []), new Unique([])] },
-  }),
-);
+/**
+ * So a field is unique on its own, whatever key it ends up under.
+ * FR : pour qu'un champ soit unique à lui seul, quelle que soit sa clé.
+ * `unique(email)` → `role.unique` is true
+ */
+export const unique: <T>(field: Field<T>) => Field<T> = vocabulary('unique', () => ({
+  role: { unique: true },
+}));

package/src/vocabulary/updated.ts

@@ -1,6 +1,11 @@
 import { created } from './created.js';
-import { Field } from '../fields/Field.js';
+import { Field } from '../field/Field.js';
 
+/**
+ * So the dual of `created()` is re-stamped at every write, by the same hand.
+ * FR : pour que le dual de `created()` soit ré-estampé à chaque écriture, par la même main.
+ * `updated()` → `create: 'now'`, `update: 'now'`
+ */
 export function updated(): Field<Date> {
   const base = created();
   return base.with({ lifecycle: { ...base.lifecycle, update: 'now' } });