@fougere/core 0.10.0-alpha.0 → 0.12.0-alpha.0

package/src/dispatch/PresenterExecutor.ts

@@ -19,37 +19,48 @@ export class PresenterExecutor {
 
     const rows = Array.isArray(result) ? result : [result];
     const values = new Map<string, unknown[]>();
-
     for (const name of this.fieldNames) {
-      const field = this.presenter[name];
-      if (typeof field !== 'function') continue;
-      try {
-        const answered = await field.call(this.presenter, rows, ...(args[name] ?? []));
-        if (!Array.isArray(answered) || answered.length !== rows.length) {
-          const actual = Array.isArray(answered) ? answered.length : typeof answered;
-          throw new Error(`expected ${rows.length} value(s) for ${rows.length} row(s), got ${actual}`);
-        }
-        values.set(name, answered);
-      } catch (cause) {
-        throw new FougereError({
-          code: ErrorCode.INTERNAL_ERROR,
-          message: `Computed field '${name}' failed: ${(cause as Error)?.message ?? cause}`,
-          entity: this.entity,
-          operation: this.operation,
-          cause,
-        });
-      }
+      const answered = await this.computed(name, rows, args[name] ?? []);
+      if (answered) values.set(name, answered);
     }
 
     const enriched = rows.map((item, index) => {
       if (item === null || typeof item !== 'object') return item;
+
       const output = { ...(item as Record<string, unknown>) };
       for (const [name, answered] of values) output[name] = answered[index];
+
       return output;
     });
 
-    return Array.isArray(result)
-      ? preserveArrayProperties(result, enriched)
-      : enriched[0];
+    return Array.isArray(result) ? preserveArrayProperties(result, enriched) : enriched[0];
+  }
+
+  /**
+   * One computed field, handed the whole PAGE — so one query per page is possible where one per
+   * row was not. It answers for every row or for none: a shorter list would silently shift the
+   * values onto the wrong rows.
+   */
+  private async computed(name: string, rows: unknown[], args: unknown[]): Promise<unknown[] | undefined> {
+    const field = this.presenter?.[name];
+    if (typeof field !== 'function') return undefined;
+
+    try {
+      const answered = await field.call(this.presenter, rows, ...args);
+      if (!Array.isArray(answered) || answered.length !== rows.length) {
+        const actual = Array.isArray(answered) ? answered.length : typeof answered;
+        throw new Error(`expected ${rows.length} value(s) for ${rows.length} row(s), got ${actual}`);
+      }
+
+      return answered;
+    } catch (cause) {
+      throw new FougereError({
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `Computed field '${name}' failed: ${(cause as Error)?.message ?? cause}`,
+        entity: this.entity,
+        operation: this.operation,
+        cause,
+      });
+    }
   }
 }

package/src/dispatch/RelationCheck.ts

@@ -0,0 +1,21 @@
+/**
+ * A `ref()` whose target the source does not hold, so the guard reads it before the write.
+ *
+ * The pair decides, never the engine: SQL keeps a foreign key over rows it can see, and a
+ * target in another source gets a column and nothing else. The boot builds one of these for
+ * each reference that falls outside its own source, and none for the rest — a co-located
+ * relation costs nothing here, because the key already refuses the same row.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export interface RelationCheck {
+  /** The field carrying the key — `authorId`. */
+  field: string;
+  /** What it points at, as the boot files it — `user`. */
+  target: string;
+  /**
+   * Which of these keys no row answers. Takes a set so a page costs one read, and so the
+   * single-row case is the same call with one member.
+   */
+  missing(keys: readonly unknown[]): Promise<readonly unknown[]>;
+}

package/src/dispatch/Release.ts

@@ -0,0 +1,180 @@
+/** What a delete does to the rows that name it, when no foreign key does it instead. */
+import { FieldSet, type SchemaView } from '@fougere/schema';
+import type { Dependent } from './Dependent.js';
+import type { Journal } from './Journal.js';
+import { ErrorCode } from '../wire/ErrorCode.js';
+import { FougereError } from '../wire/FougereError.js';
+
+/** The gestures a release reaches a dependent's rows through. */
+export interface Rows {
+  findAllByKeys(field: string, keys: readonly string[]): Promise<Map<string, Record<string, unknown>[]>>;
+  update(id: string, patch: Record<string, unknown>): Promise<unknown>;
+  delete(id: string): Promise<boolean>;
+}
+
+/** What the guard hands a release: who depends on an entity, and how to reach their rows. */
+export interface Releasing {
+  dependentsOf(entity: string): readonly Dependent[];
+  rowsOf(entity: string): Rows | undefined;
+  schemaOf(entity: string): SchemaView | undefined;
+  /** Written down while it happens, when a package provides one — absent is the plain walk. */
+  journal(entity: string): Journal | undefined;
+  /** Every declared remote — each one walks its own tree, and is alone able to. */
+  peers(): readonly { release(entity: string, key: unknown, visited: readonly string[]): Promise<void> }[];
+}
+
+/**
+ * The rows that name a key, taken out or emptied, deepest FIRST.
+ *
+ * Order is the whole guarantee: a child never outlives its parent, so an interruption leaves
+ * fewer children and never an orphan. That is what lets a release cross a process without a
+ * two-phase commit — and why nothing here needs to be undone, only finished.
+ *
+ * A row already visited is not visited again, which is what ends a cycle: `Category.parentId`
+ * pointing at its own entity walks down and stops when a key repeats.
+ *
+ * Documented: [entities](https://fougere.dev/docs/schema/entities).
+ */
+export async function release(
+  entity: string,
+  key: unknown,
+  world: Releasing,
+  visited: readonly string[] = [],
+  row?: () => Promise<unknown>,
+): Promise<void> {
+  const mark = `${entity}#${String(key)}`;
+  // Already on the trail means SOMEONE upstream is asking every process about this row, so
+  // asking again would be the bounce two processes declaring each other would never end. The
+  // local walk still runs: being asked is exactly the point, and only this process can do it.
+  const asked = visited.includes(mark);
+  const trail = asked ? visited : [...visited, mark];
+
+  // Written down before the first hop, so a process that stops mid-way leaves a row saying so.
+  // Absent, the hops are the same and nothing finishes them.
+  const journal = world.journal(entity);
+  if (journal && await journal.open(entity, String(key)) === 'busy') return;
+
+  // Every declared remote, and every one of them: a frond behind `remotes:` may have no sources
+  // here, so this process cannot see that its rows name ours — only that process can.
+  if (!asked) for (const peer of world.peers()) await peer.release(entity, key, trail);
+
+  try {
+    await walk(entity, [key], world, new Set([mark]), trail);
+  } catch (refusal) {
+    // A refusal is an outcome, not an interruption: the framework decided, and redoing it
+    // would only decide again — a run kept open for one would be swept forever. Anything
+    // else stopped us mid-tree, and THAT is what a run is for.
+    if (refusal instanceof FougereError) await journal?.close(entity, String(key));
+    throw refusal;
+  }
+
+  // The row itself, LAST — handed in by whoever owns the gesture, so a run covers the whole
+  // thing rather than stopping one statement short of it. Whatever the row answers, the
+  // release did its part: what depends on this one is dealt with, and nothing is left to redo.
+  try {
+    await row?.();
+  } finally {
+    await journal?.close(entity, String(key));
+  }
+}
+
+async function walk(
+  entity: string,
+  keys: readonly unknown[],
+  world: Releasing,
+  seen: Set<string>,
+  trail: readonly string[],
+): Promise<void> {
+  const dependents = world.dependentsOf(entity);
+
+  // Every refusal of this level BEFORE any of its rows move: two fields of one entity are two
+  // dependents, and declaration order would otherwise let a cascade beside a `restrict` win.
+  // Depth needs no such pass — a level acts only once the level below it came back.
+  for (const dependent of dependents.filter((one) => one.onDelete === 'restrict')) {
+    await refuseHeld(entity, dependent, keys, world);
+  }
+
+  for (const dependent of dependents.filter((one) => one.onDelete !== 'restrict')) {
+    await carryOut(entity, dependent, keys, world, seen, trail);
+  }
+}
+
+/** True once, and remembers — a key already on the path is what ends a cycle. */
+function taken(seen: Set<string>, entity: string, key: unknown): boolean {
+  const mark = `${entity}#${String(key)}`;
+  if (seen.has(mark)) return true;
+  seen.add(mark);
+
+  return false;
+}
+
+function keyOf(world: Releasing, entity: string): string {
+  const schema = world.schemaOf(entity);
+
+  return (schema && FieldSet.of(schema.getFields()).primary) ?? 'id';
+}
+
+/** What names these rows and states `restrict` stops the whole release, before anything moves. */
+async function refuseHeld(
+  entity: string,
+  dependent: Dependent,
+  keys: readonly unknown[],
+  world: Releasing,
+): Promise<void> {
+  const rows = world.rowsOf(dependent.entity);
+  if (!rows) return;
+
+  const found = [...(await rows.findAllByKeys(dependent.field, keys.map(String))).values()].flat();
+  if (found.length === 0) return;
+
+  throw new FougereError({
+    code: ErrorCode.CONFLICT,
+    message: `${dependent.entity}.${dependent.field} holds ${found.length} row(s) naming this one, `
+      + `and states onDelete 'restrict' — take them out first, or declare what should happen.`,
+    entity,
+    operation: 'delete',
+  });
+}
+
+/**
+ * One dependent level: cleared here, or asked of whoever holds it.
+ *
+ * Nothing here holds those rows — every declared remote is asked about THIS level, and the one
+ * that holds them walks its own tree from there. The trail grows by one mark per level, so a
+ * deeper ask is never mistaken for the bounce of a shallower one.
+ */
+async function carryOut(
+  entity: string,
+  dependent: Dependent,
+  keys: readonly unknown[],
+  world: Releasing,
+  seen: Set<string>,
+  trail: readonly string[],
+): Promise<void> {
+  const rows = world.rowsOf(dependent.entity);
+  if (!rows) {
+    for (const key of keys) {
+      // A level already on the trail is one somebody is asking every process about, so asking
+      // again is the bounce — the same reason `release` reads it before crossing.
+      if (trail.includes(`${entity}#${String(key)}`)) continue;
+      for (const peer of world.peers()) await peer.release(entity, key, trail);
+    }
+
+    return;
+  }
+
+  const found = [...(await rows.findAllByKeys(dependent.field, keys.map(String))).values()].flat();
+  if (found.length === 0) return;
+
+  const primary = keyOf(world, dependent.entity);
+  if (dependent.onDelete === 'set null') {
+    for (const row of found) await rows.update(String(row[primary]), { [dependent.field]: null });
+
+    return;
+  }
+
+  const below = found.map((row) => row[primary]).filter((id) => !taken(seen, dependent.entity, id));
+  // Deepest first: what names THESE rows goes before they do, all the way down.
+  await walk(dependent.entity, below, world, seen, trail);
+  for (const id of below) await rows.delete(String(id));
+}

package/src/dispatch/StorageGuard.ts

@@ -1,9 +1,11 @@
-import { FieldSet, FieldValueValidator, InputRefusal, type Fields } from '@fougere/schema';
+import { FieldSet, FieldValueValidator, InputRefusal, type Fields, type Verdict } from '@fougere/schema';
 import { COMPARISONS, comparisonOf, unknownIn } from '../storage/Comparison.js';
 import { assertListOptions } from '../storage/Storage.js';
 import { ErrorCode } from '../wire/ErrorCode.js';
 import { FougereError } from '../wire/FougereError.js';
 import type { GuardReport } from './GuardReport.js';
+import type { RelationCheck } from './RelationCheck.js';
+import { release, type Releasing } from './Release.js';
 
 /** The gestures this guard grafts onto. */
 interface Writer {
@@ -11,6 +13,7 @@ interface Writer {
   update(...args: [unknown, Record<string, unknown>, ...unknown[]]): Promise<unknown>;
   upsert?(...args: [Record<string, unknown>, ...unknown[]]): Promise<unknown>;
   upsertAll?(...args: [readonly Record<string, unknown>[], ...unknown[]]): Promise<unknown>;
+  delete?(id: string): Promise<boolean>;
   list?(...args: unknown[]): unknown;
 }
 
@@ -23,22 +26,55 @@ export class StorageGuard {
     private readonly fields: Fields,
     private readonly entity: string,
     private readonly report: GuardReport = {},
+    private readonly relations: readonly RelationCheck[] = [],
+    private readonly releasing?: Releasing,
   ) {}
 
   guard<T extends object>(storage: T): T {
     const writer = storage as unknown as Writer;
     if (typeof writer.create !== 'function' || typeof writer.update !== 'function') return storage;
 
-    const validation = this;
     const guarded = Object.create(storage) as T & Writer;
 
+    this.guardDelete(guarded, writer);
+    this.guardWrites(guarded, writer);
+    this.guardList(guarded, writer);
+
+    return guarded;
+  }
+
+  /**
+   * What names this row goes first, and this row last: an interruption then leaves fewer
+   * children rather than an orphan. A key holds the rest, at the rows, in one statement.
+   */
+  private guardDelete(guarded: Writer, writer: Writer): void {
+    const remove = writer.delete;
+    if (typeof remove !== 'function' || !this.releasing) return;
+
+    const validation = this;
+    guarded.delete = async function (id) {
+      let gone = false;
+      await release(validation.entity, id, validation.releasing!, [], async () => {
+        gone = await remove.call(this, id);
+      });
+
+      return gone;
+    };
+  }
+
+  /** Every gesture that puts a row down: judged first, and handed on the value it parsed. */
+  private guardWrites(guarded: Writer, writer: Writer): void {
+    const validation = this;
+
     guarded.create = async function (...args) {
       args[0] = validation.validated(args[0], 'create');
+      await validation.targetsOf([args[0]], 'create');
       return writer.create.apply(this, args);
     };
 
     guarded.update = async function (...args) {
       args[1] = validation.validated(args[1], 'update');
+      await validation.targetsOf([args[1]], 'update');
       return writer.update.apply(this, args);
     };
 
@@ -46,32 +82,36 @@ export class StorageGuard {
     if (typeof upsert === 'function') {
       guarded.upsert = async function (...args) {
         args[0] = validation.validated(args[0], 'upsert');
+        await validation.targetsOf([args[0]], 'upsert');
         return upsert.apply(this, args);
       };
     }
 
     const upsertAll = writer.upsertAll;
     if (typeof upsertAll === 'function') {
-      // Every row before the first write: a page refused halfway leaves rows behind that
-      // the caller asked for as one, and the refusal is readable from the input alone.
+      // Every row before the first write, and the keys of the whole page in one read per
+      // relation: a page refused on its fourth row has already written three.
       guarded.upsertAll = async function (...args) {
         args[0] = args[0].map((row, index) => validation.validated(row, 'upsertAll', index));
+        await validation.targetsOf(args[0], 'upsertAll');
         return upsertAll.apply(this, args);
       };
     }
+  }
 
+  /** A criterion is read where the entity declares it, so a page is asked for what it can answer. */
+  private guardList(guarded: Writer, writer: Writer): void {
     const list = writer.list;
-    if (typeof list === 'function') {
-      guarded.list = async function (...args: unknown[]) {
-        const options = args[0] as { where?: Record<string, unknown> } | undefined;
-        assertListOptions(options, validation.entity, Object.keys(validation.fields));
-        if (options?.where) args[0] = { ...options, where: validation.criteria(options.where) };
+    if (typeof list !== 'function') return;
 
-        return list.apply(this, args);
-      };
-    }
+    const validation = this;
+    guarded.list = async function (...args: unknown[]) {
+      const options = args[0] as { where?: Record<string, unknown> } | undefined;
+      assertListOptions(options, validation.entity, Object.keys(validation.fields));
+      if (options?.where) args[0] = { ...options, where: validation.criteria(options.where) };
 
-    return guarded;
+      return list.apply(this, args);
+    };
   }
 
   /**
@@ -98,34 +138,12 @@ export class StorageGuard {
     const parsed: Record<string, unknown> = {};
 
     for (const [key, asked] of Object.entries(where)) {
-      const field = this.fields[key];
-      if (!field) {
-        errors.push(`${key}: ${InputRefusal.unknownField}`);
-        continue;
-      }
-      // A comparison names its own vocabulary, and a typo in it would otherwise be a
-      // criterion that filters nothing — the silent truncation this facade exists to stop.
-      const comparison = comparisonOf(field, asked);
-      if (comparison) {
-        const unknown = unknownIn(comparison);
-        if (unknown.length) {
-          errors.push(`${key}: unknown comparison ${unknown.join(', ')} — one of ${COMPARISONS.join(', ')}`);
-          continue;
-        }
-        parsed[key] = comparison;
+      const read = this.criterion(key, asked);
+      if ('message' in read) errors.push(`${key}: ${read.message}`);
+      else {
+        parsed[key] = read.value;
         this.beyondTheView(key);
-        continue;
       }
-
-      const values = Array.isArray(asked) ? asked : [asked];
-      const each = values.map((value) => this.value(field, value));
-      const refused = each.find((one) => typeof one === 'object' && one !== null && 'error' in one);
-      if (refused) {
-        errors.push(`${key}: ${(refused as { error: string }).error}`);
-        continue;
-      }
-      parsed[key] = Array.isArray(asked) ? each.map(unwrap) : unwrap(each[0]);
-      this.beyondTheView(key);
     }
 
     if (errors.length > 0) {
@@ -141,6 +159,33 @@ export class StorageGuard {
     return parsed;
   }
 
+  /**
+   * One criterion, told from a value by the FIELD and never by its own shape.
+   *
+   * A comparison names its own vocabulary, and a typo in it would otherwise be a criterion that
+   * filters nothing — the silent truncation this facade exists to stop.
+   */
+  private criterion(key: string, asked: unknown): Verdict {
+    const field = this.fields[key];
+    if (!field) return { message: InputRefusal.unknownField };
+
+    const comparison = comparisonOf(field, asked);
+    if (comparison) {
+      const unknown = unknownIn(comparison);
+
+      return unknown.length
+        ? { message: `unknown comparison ${unknown.join(', ')} — one of ${COMPARISONS.join(', ')}` }
+        : { value: comparison };
+    }
+
+    const values = Array.isArray(asked) ? asked : [asked];
+    const each = values.map((value) => this.value(field, value));
+    const refused = each.find((one) => 'message' in one);
+    if (refused) return refused;
+
+    return { value: Array.isArray(asked) ? each.map(unwrap) : unwrap(each[0]) };
+  }
+
   /**
    * A filter on a field this facade does not hand back.
    *
@@ -161,7 +206,19 @@ export class StorageGuard {
   }
 
   /** One value against one field — validated, then decoded the way the wire hands it. */
-  private value(field: Fields[string], asked: unknown): { value: unknown } | { error: string } {
+  /**
+   * One key a handler wrote. A key the entity does not declare has no column to land in and no
+   * judge to pass: on the client facade it is a typo, and on this one a mapping that went stale.
+   */
+  private written(key: string, item: unknown): Verdict {
+    const field = this.fields[key];
+    if (!field) return { message: InputRefusal.unknownField };
+    if (item === undefined) return { value: item };
+
+    return FieldValueValidator.of(field).parse(item);
+  }
+
+  private value(field: Fields[string], asked: unknown): Verdict {
     if (asked === null || asked === undefined) return { value: asked };
     return FieldValueValidator.of(field).parse(asked);
   }
@@ -174,20 +231,9 @@ export class StorageGuard {
     const parsed: Record<string, unknown> = {};
 
     for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
-      const field = this.fields[key];
-      // A key the entity does not declare has no column to land in and no judge to pass:
-      // on the client facade it is a typo, and on this one it is a mapping that went stale.
-      if (!field) {
-        errors.push(`${where}${key}: ${InputRefusal.unknownField}`);
-        continue;
-      }
-      if (item === undefined) {
-        parsed[key] = item;
-        continue;
-      }
-      const value = FieldValueValidator.of(field).parse(item);
-      if ('error' in value) errors.push(`${where}${key}: ${value.error}`);
-      else parsed[key] = value.value;
+      const read = this.written(key, item);
+      if ('message' in read) errors.push(`${where}${key}: ${read.message}`);
+      else parsed[key] = read.value;
     }
 
     if (errors.length > 0) {
@@ -202,7 +248,44 @@ export class StorageGuard {
 
     return parsed as T;
   }
+
+  /**
+   * The rows a `ref()` points at, read before the write lands.
+   *
+   * Only the references the boot could not leave to a foreign key reach here — a target in
+   * the same source is already refused by the key, at the rows, which this cannot be: the
+   * target may be deleted between the read and the write. It catches what a key catches in
+   * practice, which is a key that was never right: a row copied from another environment,
+   * an author deleted months ago, an id from a test.
+   *
+   * A patch that does not carry the field says nothing about it, so it is skipped rather
+   * than read as `null`.
+   */
+  private async targetsOf(rows: readonly Record<string, unknown>[], operation: string): Promise<void> {
+    if (this.relations.length === 0) return;
+
+    const refused = await Promise.all(this.relations.map(async (relation) => {
+      const keys = [...new Set(
+        rows.map((row) => row[relation.field]).filter((key) => key !== undefined && key !== null),
+      )];
+      if (keys.length === 0) return [];
+      const missing = await relation.missing(keys);
+
+      return missing.map((key) => `${relation.field} ${JSON.stringify(key)} — no ${relation.target} holds it`);
+    }));
+
+    const errors = refused.flat();
+    if (errors.length === 0) return;
+
+    throw new FougereError({
+      code: ErrorCode.VALIDATION_FAILED,
+      message: `Refused on the way out — ${errors.join(', ')}`,
+      entity: this.entity,
+      operation,
+      details: errors,
+    });
+  }
 }
 
-const unwrap = (one: { value: unknown } | { error: string }): unknown =>
+const unwrap = (one: Verdict): unknown =>
   'value' in one ? one.value : undefined;

package/src/index.ts

@@ -6,6 +6,9 @@ export type { Extension } from './boot/Extension.js';
 export { defineFougere } from './define.js';
 export type { AdapterConfig } from './AdapterConfig.js';
 export type { FougereConfig } from './FougereConfig.js';
+export { statesModule, type FrondsStated, type FrondStated } from './FrondsStated.js';
+export { statedFronds, type StatedFrond } from './StatedFrond.js';
+export { nested } from './boot/nesting.js';
 export type { AnswerFor } from './AnswerFor.js';
 export type { FougereNames } from './FougereNames.js';
 export type { FougerePorts } from './FougerePorts.js';
@@ -33,10 +36,15 @@ export { Repository, type RepositoryConstructor } from './prefab/RepositoryConst
 export { type RepositoryOf } from './prefab/RepositoryOf.js';
 export { Invocation } from './contract.js';
 export type { InvocationContext } from './contract.js';
+export type { PartialInvocation } from './contract.js';
 export { Call } from './contract.js';
 export { RouteAddress } from './contract.js';
 export { DispatchLifecycle } from './dispatch/DispatchLifecycle.js';
 export { Dispatcher } from './dispatch/Dispatcher.js';
+export { release, type Releasing } from './dispatch/Release.js';
+export { releasing } from './boot/relations.js';
+export { type Dependent } from './dispatch/Dependent.js';
+export { JOURNAL, type Journal } from './dispatch/Journal.js';
 // The class and not only its type: an observer RECEIVES these, so a package that folds
 // them — or a test of one — has to be able to make one through the facade.
 export { DispatchEvent } from './dispatch/DispatchEvent.js';

package/src/node.ts

@@ -1,6 +1,7 @@
 /** What Fougere does with a filesystem, minus the scan — that is `@fougere/compiler`. */
 export { setModuleLoader, getModuleLoader } from './loader.js';
-export { loadConfig, loadCascadedConfig } from './FougereConfig.js';
+export { loadConfig, loadCascadedConfig, remotesOf } from './FougereConfig.js';
+export { statedModules } from './StatedModules.js';
 export { defineFrond, loadFrondConfig } from './FrondConfig.js';
 
 // Making a key and binding a name to it happen once, at a deployment, on a machine with

package/src/storage/Storage.ts

@@ -172,7 +172,7 @@ const KINDS = '|';
 /** The members behind a frame key, or `undefined` when the key is not one. */
 export function membersOfTogetherKey(key: string): { entities: string[]; providers: string[] } | undefined {
   if (key.length <= FRAME.length || !key.endsWith(FRAME)) return undefined;
-  const [entities, providers = ''] = key.slice(0, -FRAME.length).split(KINDS);
+  const [entities = '', providers = ''] = key.slice(0, -FRAME.length).split(KINDS);
   const split = (list: string) => list.split(SEPARATOR).filter(Boolean);
-  return { entities: split(entities!), providers: split(providers) };
+  return { entities: split(entities), providers: split(providers) };
 }