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

package/src/dispatch/StorageGuard.ts

@@ -1,4 +1,4 @@
-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';
@@ -34,22 +34,37 @@ export class StorageGuard {
     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' && validation.releasing) {
-      // 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.
-      guarded.delete = async function (id) {
-        let gone = false;
-        await release(validation.entity, id, validation.releasing!, [], async () => {
-          gone = await remove.call(this, id);
-        });
-
-        return gone;
-      };
-    }
+    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');
@@ -74,29 +89,29 @@ export class StorageGuard {
 
     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));
-        // The keys of the whole page in one read per relation, for the reason above: a page
-        // refused on its fourth row has already written three.
         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);
+    };
   }
 
   /**
@@ -123,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) {
@@ -166,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.
    *
@@ -186,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);
   }
@@ -199,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) {
@@ -266,5 +287,5 @@ export class StorageGuard {
   }
 }
 
-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';

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) };
 }

package/src/storage/Store.ts

@@ -3,6 +3,7 @@ import { comparisonOf, comparisonsIn, type Comparison } from './Comparison.js';
 import type { Storage } from './Storage.js';
 import type { StorageFactory } from './StorageFactory.js';
 import type { Values } from './Values.js';
+import type { ListResult } from './ListResult.js';
 
 /** Instances addressed by key — what an adapter supplies, and all of it. */
 export interface Store {
@@ -68,24 +69,8 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
           let items = await store.all();
           if (options?.where) items = items.filter((values) => matches(values, options.where));
           if (options?.orderBy) items = sorted(items, options.orderBy, options.order);
-          // Held before the page is cut, and after the filter: `total` answers "how many
-          // match", which is what a paginator divides. Reading `store.size` at the end
-          // answered a different question — everything the store holds, including the ones
-          // the filter exists to keep out of this caller's sight.
-          const matching = items.length;
-          const limit = options?.limit;
-          const offset = options?.page && limit ? (options.page - 1) * limit : options?.offset ?? 0;
-          if (offset > 0) items = items.slice(offset);
-          const hasMore = limit ? items.length > limit : false;
-          if (limit) items = items.slice(0, limit);
-          // The cursor is read before the scope cuts: a view that drops the key still
-          // pages, the way it does over SQL.
-          const endCursor = items.length > 0 ? String((items[items.length - 1] as any)[pk] ?? '') : undefined;
-          const result = items.map(pick) as any;
-          result.hasMore = hasMore;
-          result.endCursor = endCursor;
-          if (options?.count) result.total = matching;
-          return result;
+
+          return paged(items, options, pk, pick);
         },
         async findById(id: string) {
           const values = await store.get(keyOf(id));
@@ -206,3 +191,39 @@ const rank = (left: unknown, right: unknown): number => {
 
   return held === against ? 0 : held < against ? -1 : 1;
 };
+
+/**
+ * The page cut out of what matched.
+ *
+ * `total` is held BEFORE the cut and after the filter — it answers "how many match", which is
+ * what a paginator divides. Reading the store's size at the end answered a different question:
+ * everything it holds, including the rows the filter exists to keep out of this caller's sight.
+ */
+function paged(
+  matched: Values[],
+  options: { limit?: number; page?: number; offset?: number; count?: boolean } | undefined,
+  pk: string,
+  pick: (values: Values) => Values,
+): ListResult<Values> {
+  const matching = matched.length;
+  const limit = options?.limit;
+  const offset = options?.page && limit ? (options.page - 1) * limit : options?.offset ?? 0;
+
+  let items = offset > 0 ? matched.slice(offset) : matched;
+  const hasMore = limit ? items.length > limit : false;
+  if (limit) items = items.slice(0, limit);
+
+  // The cursor is read before the scope cuts: a view that drops the key still pages, the way it
+  // does over SQL.
+  const endCursor = items.length > 0
+    ? String((items[items.length - 1] as Record<string, unknown>)[pk] ?? '')
+    : undefined;
+
+  // An array that carries the page's terms on itself — what `ListResult` is.
+  const result = items.map(pick) as ListResult<Values>;
+  result.hasMore = hasMore;
+  result.endCursor = endCursor;
+  if (options?.count) result.total = matching;
+
+  return result;
+}

package/src/verify.ts

@@ -17,6 +17,16 @@ export type Misplaced = Diagnostic & {
 /** A dependency declared in a frond's scope, and what kind of thing it is. */
 type Registration = { frond: string; kind: string };
 
+/** Everything above a frond in the tree — what its scope reaches by walking up. */
+function ancestors(frond: FrondDescriptor, byName: Map<string, FrondDescriptor>): Set<string> {
+  const above = new Set<string>();
+  for (let at = frond.extends; at !== undefined && !above.has(at); at = byName.get(at)?.extends) {
+    above.add(at);
+  }
+
+  return above;
+}
+
 /**
  * The container keys a frond registers in its own scope, keyed as a handler's `deps` spell them —
  * DI resolves by type name, so both sides are PascalCase.
@@ -50,6 +60,7 @@ function injectablesOf(frond: FrondDescriptor) {
  */
 export function verify(app: { fronds: readonly FrondDescriptor[] }): Misplaced[] {
   const index = new Map<string, Registration>();
+  const byName = new Map(app.fronds.map((frond) => [frond.name, frond]));
   for (const frond of app.fronds) {
     for (const [key, reg] of registrationsOf(frond)) index.set(key, reg);
   }
@@ -76,6 +87,10 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Misplaced[]
         // façade key, or an unresolved name. None is a boundary crossing, and
         // an unresolved dependency is the container's complaint, not this rule's.
         if (!declared || declared.frond === frond.name) continue;
+        // An ANCESTOR is not across: the frond tree says this one resolves what that one
+        // declared, and its scope hangs off it. A sibling, a descendant or a stranger stays
+        // refused — inheriting code is not calling a frond.
+        if (ancestors(frond, byName).has(declared.frond)) continue;
         violations.push({
           code: 'cross-frond-dependency',
           severity: 'warning',

package/src/wire/Invocation.ts

@@ -24,6 +24,8 @@ function canonicalRecord(value: unknown): Record<string, unknown> {
 
 /** Canonical invocation shared by every entry and transport. */
 export class Invocation implements InvocationContext {
+  static readonly empty = Invocation.from();
+
   readonly params: Record<string, unknown>;
   readonly query: Record<string, unknown>;
   readonly input: unknown;
@@ -53,7 +55,6 @@ export class Invocation implements InvocationContext {
     return context instanceof Invocation ? context : new Invocation(context ?? {});
   }
 
-  static readonly empty = Invocation.from();
 
   /** Replaces the input — how the façade hands on the value it parsed. */
   withInput(input: unknown): Invocation {

package/src/wire/binding.ts

@@ -48,66 +48,34 @@ export function computeBindingPlan(
   params: Param[],
   collectorTypeNames: Set<string>,
 ): BindingPlan {
-  return params.map((param) => {
-    const typeName = param.type.name;
-    // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the
-    // scan spells it, and the two agree on one word only — `AuthorUser` looked up as
-    // `authoruser` missed `authorUser` and fell through to branch 4, the request input.
-    const typeKey = lowerFirst(typeName);
-
-    // 0. Fact, or the same fact before it is final. Both name themselves, so nothing has
-    //    to be known in advance, and they come FIRST because branch 4 would otherwise hand
-    //    either the caller's input under the name of something that happened.
-    const announced = param.type.name === 'Fact' || param.type.name === 'Pipe'
-      ? param.type.generics?.[0]?.name
-      : undefined;
-    if (announced) {
-      return {
-        name: param.name,
-        source: {
-          kind: (param.type.name === 'Pipe' ? 'pipe' : 'fact') as 'pipe' | 'fact',
-          factName: lowerFirst(announced),
-        },
-        optional: param.optional ?? false,
-      };
-    }
+  return params.map((param) => ({
+    name: param.name,
+    source: sourceOf(param, collectorTypeNames),
+    optional: param.optional ?? false,
+  }));
+}
 
-    // 1. Collector — param type matches a type some collector answers for
-    if (collectorTypeNames.has(typeKey)) {
-      return {
-        name: param.name,
-        source: { kind: 'collector' as const, typeName: typeKey },
-        optional: param.optional ?? false,
-      };
-    }
+/**
+ * Where ONE parameter gets its value, in the order the branches must be asked.
+ *
+ * A fact and a link name themselves, so they come FIRST: asked later, the last branch would hand
+ * the caller's input under the name of something that happened.
+ */
+function sourceOf(param: Param, collectorTypeNames: Set<string>): ParamSource {
+  const typeName = param.type.name;
+  // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the scan spells it,
+  // and the two agree on one word only — `AuthorUser` looked up as `authoruser` missed
+  // `authorUser` and fell through to the request input.
+  const typeKey = lowerFirst(typeName);
 
-    // 2. InvocationContext — inject the full context
-    if (typeName === 'InvocationContext') {
-      return {
-        name: param.name,
-        source: { kind: 'context' as const },
-        optional: param.optional ?? false,
-      };
-    }
+  const announced = typeName === 'Fact' || typeName === 'Pipe' ? param.type.generics?.[0]?.name : undefined;
+  if (announced) {
+    return { kind: typeName === 'Pipe' ? 'pipe' : 'fact', factName: lowerFirst(announced) };
+  }
 
-    // 3. Primitives — matched by name from params > query
-    if (PRIMITIVES.has(typeName)) {
-      return {
-        name: param.name,
-        source: {
-          kind: 'param' as const,
-          name: param.name,
-          coerce: coercionFor(typeName),
-        },
-        optional: param.optional ?? false,
-      };
-    }
+  if (collectorTypeNames.has(typeKey)) return { kind: 'collector', typeName: typeKey };
+  if (typeName === 'InvocationContext') return { kind: 'context' };
+  if (PRIMITIVES.has(typeName)) return { kind: 'param', name: param.name, coerce: coercionFor(typeName) };
 
-    // 4. Everything else — input
-    return {
-      name: param.name,
-      source: { kind: 'input' as const },
-      optional: param.optional ?? false,
-    };
-  });
+  return { kind: 'input' };
 }

package/src/wire/drift.ts

@@ -15,8 +15,14 @@ export interface CardDrift {
 }
 
 /** Every facade of a card, by name. */
-function facadesOf(card: IdentityCard, frond: string): Map<string, { ops: Set<string>; schema?: SchemaDescriptor }> {
-  const found = new Map<string, { ops: Set<string>; schema?: SchemaDescriptor }>();
+/** What a door of that card answers, and the shape of the row it hands back. */
+interface Answering {
+  ops: Set<string>;
+  schema?: SchemaDescriptor;
+}
+
+function facadesOf(card: IdentityCard, frond: string): Map<string, Answering> {
+  const found = new Map<string, Answering>();
   for (const one of card.fronds) {
     if (one.name !== frond) continue;
     for (const facade of one.facades) {
@@ -37,37 +43,58 @@ function factsOf(card: IdentityCard, frond: string): Map<string, SchemaDescripto
 
 /** What a consumer's synced copy no longer matches in what the producer serves. */
 export function driftOf(mine: IdentityCard, theirs: IdentityCard, frond: string): CardDrift {
-  const mineFacades = facadesOf(mine, frond);
-  const served = facadesOf(theirs, frond);
   const drift: CardDrift = { frond, missingDoors: [], missingOps: [], shapes: [], facts: [] };
 
-  for (const [name, facade] of mineFacades) {
-    const there = served.get(name);
-    if (!there) { drift.missingDoors.push(name); continue; }
+  driftInDoors(facadesOf(mine, frond), facadesOf(theirs, frond), drift);
+  driftInFacts(factsOf(mine, frond), factsOf(theirs, frond), drift);
+
+  return drift;
+}
+
+/** A door that is gone, an operation it no longer answers, or a row that changed shape. */
+function driftInDoors(
+  mine: Map<string, Answering>,
+  theirs: Map<string, Answering>,
+  drift: CardDrift,
+): void {
+  for (const [name, facade] of mine) {
+    const there = theirs.get(name);
+    if (!there) {
+      drift.missingDoors.push(name);
+      continue;
+    }
 
     const missing = [...facade.ops].filter((op) => !there.ops.has(op));
     if (missing.length > 0) drift.missingOps.push({ facade: name, ops: missing.sort() });
 
-    if (facade.schema && there.schema) {
-      // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
-      // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so
-      // the pair is reported as it is and a human reads it.
-      const moved = Card.fromDescriptor(facade.schema).diff(Card.fromDescriptor(there.schema));
-      if (moved.changes.length > 0) drift.shapes.push({ facade: name, changes: moved.changes });
-    }
+    if (!facade.schema || !there.schema) continue;
+
+    // `Card.diff` never guesses a rename — a field gone plus a field appeared lands in
+    // `ambiguous`, and only a declaration settles it. Here nobody can declare one, so the
+    // pair is reported as it is and a human reads it.
+    const moved = Card.fromDescriptor(facade.schema).diff(Card.fromDescriptor(there.schema));
+    if (moved.changes.length > 0) drift.shapes.push({ facade: name, changes: moved.changes });
   }
+}
+
+/** A fact nobody announces any more, or one whose payload moved under its readers. */
+function driftInFacts(
+  mine: Map<string, SchemaDescriptor | undefined>,
+  theirs: Map<string, SchemaDescriptor | undefined>,
+  drift: CardDrift,
+): void {
+  for (const [name, shape] of mine) {
+    if (!theirs.has(name)) {
+      drift.facts.push({ fact: name, changes: 'gone' });
+      continue;
+    }
 
-  const heldFacts = factsOf(mine, frond);
-  const servedFacts = factsOf(theirs, frond);
-  for (const [name, shape] of heldFacts) {
-    if (!servedFacts.has(name)) { drift.facts.push({ fact: name, changes: 'gone' }); continue; }
-    const there = servedFacts.get(name);
+    const there = theirs.get(name);
     if (!shape || !there) continue;
+
     const moved = Card.fromDescriptor(shape).diff(Card.fromDescriptor(there));
     if (moved.changes.length > 0) drift.facts.push({ fact: name, changes: moved.changes });
   }
-
-  return drift;
 }
 
 /** Whether anything at all separates the two cards. */