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

package/src/axis/role/RoleAxis.ts

@@ -1,7 +1,7 @@
 import type { Axis, Resolver } from '../Axis.js';
 import { refuse, oneOfTokens } from '../../projection/card/admission.js';
 import { isObject, lowerFirst, shown } from '../../lib/utils.js';
-import type { ValidationError } from '../../validation.js';
+import type { ValidationError } from '../../lib/validation.js';
 import { ON_DELETE, RELATION_KINDS, type EntityConstructor, type Relation } from './Relation.js';
 import { type RoleRules } from './Role.js';
 import type { RoleDescriptor } from '../../projection/card/Descriptor.js';
@@ -11,13 +11,13 @@ export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
 
   validator(value, errors) {
     if (!isObject(value)) {
-      errors.push({ path: 'role', message: `Expected an object — got ${shown(value)}` });
+      errors.push({ path: ['role'], message: `Expected an object — got ${shown(value)}` });
       return;
     }
     for (const flag of ['primary', 'index', 'unique'] as const) {
       if (value[flag] !== undefined && typeof value[flag] !== 'boolean') {
         errors.push({
-          path: `role.${flag}`,
+          path: ['role', flag],
           message: `Expected a boolean — got ${shown(value[flag])}`,
         });
       }
@@ -73,27 +73,27 @@ export const roleAxis: Axis<RoleRules, RoleDescriptor> = {
 };
 
 /**
- * So a relation is validated where `() => Post` is required — a card carries a name.
- * FR : pour qu'une relation soit jugée là où `() => Post` est exigé, contrairement à une carte.
- * `{ to: User, kind: 'one' }` → error `Expected a function returning the target entity, such as () => Post`
+ * Judges a relation where `to` is a thunk; a card states a NAME, resolved by `toSchema` first.
+ * FR : juge une relation dont `to` est une fonction ; une carte y met un NOM, résolu avant.
+ * `{ to: User, kind: 'one' }` → `Expected a function returning the target entity, … () => Post`
  */
 function validateRelation(relation: unknown, errors: ValidationError[]): void {
   if (!isObject(relation)) {
-    errors.push({ path: 'role.relation', message: `Expected an object — got ${shown(relation)}` });
+    errors.push({ path: ['role', 'relation'], message: `Expected an object — got ${shown(relation)}` });
     return;
   }
   if (!oneOfTokens(relation.kind, RELATION_KINDS)) {
     errors.push({
-      path: 'role.relation.kind',
+      path: ['role', 'relation', 'kind'],
       message: `Expected 'one' or 'many' — got ${shown(relation.kind)}`,
     });
   }
   if (typeof relation.to !== 'function') {
-    errors.push({ path: 'role.relation.to', message: 'Expected a function returning the target entity, such as () => Post' });
+    errors.push({ path: ['role', 'relation', 'to'], message: 'Expected a function returning the target entity, such as () => Post' });
   }
   if (relation.onDelete !== undefined && !oneOfTokens(relation.onDelete, ON_DELETE)) {
     errors.push({
-      path: 'role.relation.onDelete',
+      path: ['role', 'relation', 'onDelete'],
       message: `Expected 'cascade', 'restrict' or 'set null' — got ${shown(relation.onDelete)}`,
     });
   }

package/src/axis/shape/Shape.ts

@@ -1,6 +1,17 @@
-import type { JSONSchema7 } from 'json-schema';
+import type { JSONSchema7, JSONSchema7TypeName } from 'json-schema';
 import type { StringFormat } from './Formats.js';
 
+/**
+ * The standard's own list, less `null` — a shape states that as the `[T,'null']` union —
+ * and with `string` in the three forms every projection here tells apart: a `date()`, a
+ * bounded set, and everything else. Those three are the whole of what this package adds.
+ */
+export type ShapeType =
+  | Exclude<JSONSchema7TypeName, 'null' | 'string'>
+  | 'text'
+  | 'date'
+  | 'choice';
+
 type Nullably<T extends string> = T | readonly [T, 'null'];
 
 interface StringConstraints { minLength?: number; maxLength?: number; pattern?: string; enum?: readonly (string | null)[]; format?: StringFormat }
@@ -17,16 +28,6 @@ export type Shape =
 
 const SHAPE_TYPES = ['string', 'number', 'integer', 'boolean', 'array', 'object'] as const;
 
-function isShapeImpl(value: unknown): value is Shape {
-  if (typeof value !== 'object' || value === null) return false;
-  const type = (value as Shape).type;
-  const names = Array.isArray(type) ? type : [type];
-  return (
-    names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
-    names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
-  );
-}
-
 type BaseShape =
   | ({ type: 'string' } & StringConstraints)
   | ({ type: 'number' | 'integer' } & NumericConstraints)
@@ -34,37 +35,21 @@ type BaseShape =
   | ({ type: 'array' } & ArrayConstraints)
   | ({ type: 'object' } & ObjectConstraints);
 
-function nullableShapeImpl(shape: Shape): Shape {
-  if (Array.isArray(shape.type)) return shape;
-  const nullable = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
-  if ('enum' in nullable && nullable.enum && !nullable.enum.includes(null)) {
-    (nullable as { enum: readonly (string | null)[] }).enum = [...nullable.enum, null];
-  }
-  return nullable;
-}
-
 interface ShapeParts {
   base?: BaseShape;
   nullable: boolean;
 }
 
-function collectPatterns(value: unknown, found: string[]): void {
-  if (Array.isArray(value)) {
-    for (const member of value) collectPatterns(member, found);
-
-    return;
-  }
-  if (typeof value !== 'object' || value === null) return;
-
-  const { pattern } = value as { pattern?: unknown };
-  if (typeof pattern === 'string') found.push(pattern);
-
-  for (const member of Object.values(value)) collectPatterns(member, found);
-}
-
 export class Shapes {
   static is(value: unknown): value is Shape {
-    return isShapeImpl(value);
+    if (typeof value !== 'object' || value === null) return false;
+    const type = (value as Shape).type;
+    const names = Array.isArray(type) ? type : [type];
+
+    return (
+      names.some((name) => (SHAPE_TYPES as readonly unknown[]).includes(name)) &&
+      names.every((name) => name === 'null' || (SHAPE_TYPES as readonly unknown[]).includes(name))
+    );
   }
 
   /**
@@ -75,13 +60,33 @@ export class Shapes {
    */
   static patterns(shape: unknown): string[] {
     const found: string[] = [];
-    collectPatterns(shape, found);
+    Shapes.collectPatterns(shape, found);
 
     return found;
   }
 
+  private static collectPatterns(value: unknown, found: string[]): void {
+    if (Array.isArray(value)) {
+      for (const member of value) Shapes.collectPatterns(member, found);
+
+      return;
+    }
+    if (typeof value !== 'object' || value === null) return;
+
+    const { pattern } = value as { pattern?: unknown };
+    if (typeof pattern === 'string') found.push(pattern);
+
+    for (const member of Object.values(value)) Shapes.collectPatterns(member, found);
+  }
+
   static nullable(shape: Shape): Shape {
-    return nullableShapeImpl(shape);
+    if (Array.isArray(shape.type)) return shape;
+    const nullable = { ...shape, type: [shape.type, 'null'] } as unknown as Shape;
+    if ('enum' in nullable && nullable.enum && !nullable.enum.includes(null)) {
+      (nullable as { enum: readonly (string | null)[] }).enum = [...nullable.enum, null];
+    }
+
+    return nullable;
   }
 
   private static readonly cache = new WeakMap<object, ShapeParts>();
@@ -109,6 +114,20 @@ export class Shapes {
   static isNullable(shape?: Shape): boolean {
     return this.of(shape).nullable;
   }
+
+  /**
+   * `shape.type` read off the base, except that a `string` answers `date` or `choice`.
+   * FR : `shape.type` lu sur la base, sauf qu'une chaîne répond `date` ou `choice`.
+   * `typeOf({ type: ['string', 'null'], format: 'date-time' })` → `'date'`
+   */
+  static typeOf(shape?: Shape): ShapeType | undefined {
+    const base = this.of(shape).base;
+    if (!base) return undefined;
+    if (base.type !== 'string') return base.type;
+    if (base.format === 'date-time') return 'date';
+
+    return base.enum?.length ? 'choice' : 'text';
+  }
 }
 
 type Assert<T extends true> = T;
@@ -116,3 +135,8 @@ type ShapeKeys<T> = T extends unknown ? keyof T : never;
 type _ShapeConformsToJsonSchema = Assert<
   [Exclude<ShapeKeys<Shape>, keyof JSONSchema7>] extends [never] ? true : false
 >;
+type _ShapeTypesAreTheStandardsLessNull = Assert<
+  [Exclude<Exclude<JSONSchema7TypeName, 'null'>, (typeof SHAPE_TYPES)[number]>] extends [never]
+    ? true
+    : false
+>;

package/src/entity/EntityAdapterSet.ts

@@ -36,7 +36,7 @@ export class EntityAdapterSet {
     return new EntityAdapterSet(adapters);
   }
 
-  /** Folds several into one, a later field entry replacing the earlier. Takes sets only, so */
+  /** Folds several into one, a later field entry replacing the earlier. */
   static merged(adapterSets: readonly EntityAdapterSet[]): EntityAdapterSet {
     const configurations: AdapterConfigurations = {};
 
@@ -58,7 +58,7 @@ export class EntityAdapterSet {
     ];
   }
 
-  /** Follows a derivation — `pick`, `omit` and `rename` are one gesture: what remains, and */
+  /** Follows a derivation — `pick`, `omit` and `rename` are one gesture. */
   rename(transform: (key: string) => string | undefined): EntityAdapterSet {
     const renamed: AdapterConfigurations = {};
 

package/src/entity.ts

@@ -3,8 +3,8 @@ import { type EntityDeclarations } from './entity/EntityDeclarations.js';
 import { Schema, type SchemaConstructor } from './Schema.js';
 
 /**
- * So the whole framework starts from one call: fields, and what they say about themselves.
- * FR : pour que tout parte d'un appel : les champs, et ce qu'ils disent d'eux-mêmes.
+ * The one call everything derives from: the fields, and what the entity states about them.
+ * FR : l'appel dont tout dérive : les champs, et ce que l'entité en dit.
  * `class Post extends entity({ id: primary(), title: text() }, { unique: [['title']] }) {}`
  */
 export function entity<TFields extends Fields>(

package/src/field/Field.ts

@@ -6,6 +6,7 @@ import type { Meta } from './Meta.js';
 import type { Axis } from '../axis/Axis.js';
 import { FieldDeclarationValidator } from '../validator/FieldDeclarationValidator.js';
 import { FieldValueValidator } from '../validator/FieldValueValidator.js';
+import { dotted } from '../lib/validation.js';
 
 export type Fields = Record<string, Field>;
 
@@ -28,7 +29,7 @@ export class Field<T = unknown> {
     if (!verdict.success) {
       throw new Error(
         `${key ? `Field '${key}': ` : ''}` +
-          verdict.errors.map((e) => `${e.path}: ${e.message}`).join('; '),
+          verdict.errors.map((e) => `${dotted(e.path)}: ${e.message}`).join('; '),
       );
     }
 

package/src/field/FieldSet.ts

@@ -10,20 +10,19 @@ export class FieldSet<TFields extends Fields = Fields> {
   }
 
   /**
-   * So a declared unique lands where it belongs: on the field, or on the schema.
-   * FR : pour qu'une unicité déclarée atterrisse sur le champ ou sur le schéma.
-   * `declaring(fields, [['email'], ['listId', 'docId']])`
-   * → `email` carries `role.unique`, the pair becomes a schema constraint
+   * Splits a declared `unique`: a group of one lands on the field, several stay on the schema.
+   * FR : partage un `unique` déclaré : un groupe d'un va au champ, plusieurs restent au schéma.
+   * `declaring(fields, [['email'], ['listId', 'docId']])` → `email` carries it, the pair is a group
    */
   static declaring<TFields extends Fields>(
     declared: TFields,
     unique?: CompositeUnique<TFields>,
-  ): { fields: TFields; unique: CompositeUnique<TFields> | undefined } {
+  ): { fields: TFields; groups: CompositeUnique<TFields> } {
     const fields: Fields = {};
     for (const [key, field] of Object.entries(declared))
       fields[key] = new Field(field, key);
 
-    const composite: string[][] = [];
+    const composite: FieldName<TFields>[][] = [];
     for (const group of unique ?? []) {
       const missing = group.filter((key) => !Object.hasOwn(fields, key));
       if (missing.length)
@@ -40,10 +39,7 @@ export class FieldSet<TFields extends Fields = Fields> {
       composite.push([...group]);
     }
 
-    return {
-      fields: fields as TFields,
-      unique: deduplicated(composite) as CompositeUnique<TFields> | undefined,
-    };
+    return { fields: fields as TFields, groups: composite };
   }
 
   /** A second `primary` is refused, naming both, rather than the first winning silently. */
@@ -63,13 +59,3 @@ export class FieldSet<TFields extends Fields = Fields> {
   }
 
 }
-
-/** The order is part of a group: `['a','b']` and `['b','a']` are two constraints. */
-export function deduplicated(
-  groups: readonly (readonly string[])[],
-): readonly (readonly string[])[] | undefined {
-  const seen = new Map<string, readonly string[]>();
-  for (const group of groups) seen.set(JSON.stringify(group), group);
-
-  return seen.size ? [...seen.values()] : undefined;
-}

package/src/index.ts

@@ -6,14 +6,14 @@ export { Schema, ANONYMOUS_SCHEMA_NAME, type SchemaConstructor } from './Schema.
 export { type SchemaView } from './SchemaView.js';
 export { Field, type Fields } from './field/Field.js';
 export { FieldSet } from './field/FieldSet.js';
-export { type Shape, Shapes } from './axis/shape/Shape.js';
+export { type Shape, type ShapeType, Shapes } from './axis/shape/Shape.js';
 export { Role, type RoleRules } from './axis/role/Role.js';
 export { type EntityConstructor } from './axis/role/Relation.js';
 export { Lifecycle, type LifecycleRules } from './axis/lifecycle/Lifecycle.js';
 export { Boundary, type BoundaryRef } from './axis/boundary/Boundary.js';
 export { applyCreate, applyUpdate } from './axis/lifecycle/apply.js';
 export { InputRefusal } from './validator/InputRefusal.js';
-export { type ValidationError, type ValidationResult } from './validation.js';
+export { dotted, type ValidationError, type ValidationResult } from './lib/validation.js';
 
 export { Card } from './projection/card/Card.js';
 export { Bundle } from './projection/card/Bundle.js';

package/src/lib/validation.ts

@@ -0,0 +1,25 @@
+export interface ValidationError {
+  /**
+   * Where the refusal happened: the field, then where under it the shape refused.
+   * Empty when the input itself is refused. Segments, never a sentence — a field may
+   * legally be named `a.b`, and re-parsing a joined path invents a segment it never had.
+   */
+  path: readonly string[];
+  message: string;
+}
+
+export type ValidationResult<T> =
+  | { success: true; data: T }
+  | { success: false; errors: ValidationError[] };
+
+/**
+ * A field's verdict. `path` is where INSIDE the value the refusal happened — empty when the
+ * field itself is refused, `['street']` when the shape below it is.
+ */
+export type Checked = { value: unknown } | { error: string; path?: readonly string[] };
+
+/**
+ * A path as a message writes it — `addr.street`. One rendering among others, and the
+ * reason the value stays segmented: this one cannot be read back.
+ */
+export const dotted = (path: readonly string[]): string => path.join('.');

package/src/projection/Cases.ts

@@ -25,8 +25,8 @@ export interface ValidationCase {
 }
 
 /**
- * So every field has at least one case, whatever else it declares.
- * FR : pour que chaque champ ait un cas, quoi qu'il déclare par ailleurs.
+ * A value of the wrong type, so every field yields at least one case whatever it declares.
+ * FR : une valeur du mauvais type, pour que chaque champ rende au moins un cas.
  * `text()` → `42`; `number()` → `'not-a-value-of-this-shape'`
  */
 function wrongTypeFor(field: Field): unknown {
@@ -36,8 +36,8 @@ function wrongTypeFor(field: Field): unknown {
 }
 
 /**
- * So a bound stated in a shape produces the case that breaks it, and none is invented.
- * FR : pour qu'une borne énoncée produise le cas qui la casse, et aucun autre.
+ * One case per bound the shape states, and none for a bound it does not.
+ * FR : un cas par borne que la forme énonce, aucun pour une borne absente.
  * `text({ maxLength: 3 })` → one case with `'xxxx'`; `text()` → no case
  */
 function outOfBoundsFor(field: Field): { why: string; value: unknown }[] {
@@ -86,11 +86,11 @@ export class Cases {
 
   static holds(
     expected: ValidationCase['expect'],
-    result: { success: boolean; errors?: { path: string }[] },
+    result: { success: boolean; errors?: { path: readonly string[] }[] },
   ): boolean {
     if (expected === 'accept') return result.success;
     if (result.success) return false;
-    return (result.errors ?? []).some((error) => error.path === expected.reject);
+    return (result.errors ?? []).some((error) => rejected(error.path) === expected.reject);
   }
 
   static get refusals(): string[] {
@@ -103,8 +103,10 @@ export class Cases {
 }
 
 /**
- * So the four axes decide which cases exist, and no list of them is maintained by hand.
- * FR : pour que les axes décident des cas, sans liste tenue à la main.
+ * Reads the four axes rather than a list kept by hand: a case exists because a field
+ * declares the rule it breaks.
+ * FR : lit les quatre axes plutôt qu'une liste tenue à la main : un cas existe parce qu'un
+ * champ déclare la règle qu'il casse.
  */
 function enumerate(entity: SchemaView, valid: Record<string, unknown>): ValidationCase[] {
   const fields = entity.getFields();
@@ -174,3 +176,6 @@ function enumerate(entity: SchemaView, valid: Record<string, unknown>): Validati
 
   return cases;
 }
+
+/** What a case names: the input itself, or the field the refusal lands on. */
+const rejected = (path: readonly string[]): string => (path.length === 0 ? '.' : path[0]!);

package/src/projection/Visibility.ts

@@ -16,7 +16,7 @@ export class Visibility {
     for (const [name, field] of Object.entries(this.fields)) {
       const role = Role.of(field);
       if (role.isPrimary) continue;
-      if (Lifecycle.of(field).create === 'now') continue;
+      if (Lifecycle.of(field).stampedAtCreate) continue;
       if (role.isCollection) continue;
       if (Boundary.of(field).readOnly) continue;
       result[name] = field;

package/src/projection/card/Bundle.ts

@@ -16,10 +16,7 @@ export class Bundle {
     const definitions: Record<string, SchemaDescriptor> = {};
     const claimedBy = new Map<string, string>();
     const entries = Array.isArray(schemas)
-      ? schemas.map((schema) => {
-          const card = Card.fromSchema(schema);
-          return { name: card.descriptor.title ?? '', schema };
-        })
+      ? schemas.map((schema) => ({ name: Card.titleOf(schema), schema }))
       : Object.entries(schemas).map(([name, schema]) => ({ name, schema }));
 
     for (const entry of entries) {