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

package/src/boot/together.ts

@@ -48,42 +48,59 @@ function resolve(
   refused: Diagnostic[],
 ): Members | undefined {
   const before = refused.length;
+  const entities = entitiesNamed(names.entities, world, asked, refused);
+  const providers = providersNamed(names.providers, declared, asked, refused);
 
-  const entities = names.entities.flatMap((member) => {
+  return refused.length === before ? { entities, providers } : undefined;
+}
+
+/** The first list names ENTITIES — a class of this frond goes in the second. */
+function entitiesNamed(
+  named: readonly string[],
+  world: FrameWorld,
+  asked: Asked,
+  refused: Diagnostic[],
+): { name: string; schema: SchemaView }[] {
+  return named.flatMap((member) => {
     const name = lowerFirst(member);
     const schema = world.entityByName.get(name);
-    if (!schema) {
-      refused.push({
-        ...asked,
-        code: 'together-entity-unknown',
-        message: `Together<[…${member}…]>: no entity named '${member}' is scanned in this app. `
-          + 'The first list names entities; a class of this frond goes in the second.',
-      });
+    if (schema) return [{ name, schema }];
 
-      return [];
-    }
+    refused.push({
+      ...asked,
+      code: 'together-entity-unknown',
+      message: `Together<[…${member}…]>: no entity named '${member}' is scanned in this app. `
+        + 'The first list names entities; a class of this frond goes in the second.',
+    });
 
-    return [{ name, schema }];
+    return [];
   });
+}
 
-  const providers = names.providers.flatMap((member) => {
+/**
+ * The second list names the classes to REBUILD inside the frame — a service, a mirror, a
+ * repository — so that what they write is covered by the unwind.
+ */
+function providersNamed(
+  named: readonly string[],
+  declared: readonly ProviderEntry[],
+  asked: Asked,
+  refused: Diagnostic[],
+): ProviderEntry[] {
+  return named.flatMap((member) => {
     const entry = declared.find((provider) => provider.ctor.name === member);
-    if (!entry) {
-      refused.push({
-        ...asked,
-        code: 'together-provider-unknown',
-        message: `Together<[…], [… ${member} …]>: this frond declares no class named '${member}'. `
-          + 'The second list names providers to rebuild inside the frame — a service, a mirror, '
-          + 'a repository — so that what they write is covered by the unwind.',
-      });
+    if (entry) return [entry];
 
-      return [];
-    }
+    refused.push({
+      ...asked,
+      code: 'together-provider-unknown',
+      message: `Together<[…], [… ${member} …]>: this frond declares no class named '${member}'. `
+        + 'The second list names providers to rebuild inside the frame — a service, a mirror, '
+        + 'a repository — so that what they write is covered by the unwind.',
+    });
 
-    return [entry];
+    return [];
   });
-
-  return refused.length === before ? { entities, providers } : undefined;
 }
 
 /** Who asked for the frame, and where they wrote it — the same three fields every refusal here carries. */
@@ -160,11 +177,14 @@ export function registerFrames(
 ): void {
   let registered = 0;
   const seen = new Set<string>();
+
   for (const { key, filePath } of wanted) {
     if (seen.has(key)) continue;
     seen.add(key);
+
     const names = membersOfTogetherKey(key);
     if (!names) continue;
+
     registered += 1;
     const asked = { severity: 'blocking', filePath, subject: key } as const;
     if (!world.storageFactory) {
@@ -179,47 +199,12 @@ export function registerFrames(
     const members = resolve(names, providers, world, asked, refused);
     // Nothing left to build a frame out of, and the refusals above already say what is missing.
     if (!members) continue;
+
     remoteMembers(members, world, asked, refused);
     uncoveredWrites(members, world, asked, refused);
-
-    const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
-    const validator = (storage: Storage, name: string, schema: SchemaView) =>
-      new StorageGuard(schema.getFields(), name, {}, heldBy(schema, name, world.hosting), releasing(world.hosting)).guard(storage);
-
-    // One engine and a way into it: the engine gives the unwind AND the isolation. The
-    // question goes to the source these members live in — a composition answering for the
-    // default one would compensate a frame whose own engine holds transactions.
-    const source = sources.size === 1 ? [...sources][0]! : undefined;
-    if (world.transacted && source !== undefined && (world.transacts?.(source) ?? true)) {
-      world.log.info(`${key} — transaction, source '${source}'`);
-      scope.registerValue(key, {
-        run: <R>(fn: (entities: never, providers: never) => Promise<R>) =>
-          ambient.enterFrame(key, () =>
-            world.transacted!(source, (factory) => inScope(scope, members, factory, validator, fn as never))),
-      });
-      continue;
-    }
-
-    // Split, or an engine that hands out no transaction: the frame keeps the before-image
-    // of every write and replays the inverses itself. `validator` stays OUTSIDE `recording`, so
-    // a write the entity refuses never enters the journal.
-    const why = sources.size > 1
-      ? members.entities.map((m) => `${m.name} in '${world.sourceOf?.(m.name) ?? 'db'}'`).join(', ')
-      : 'this storage hands out no transaction';
-    world.log.info(`${key} — compensated: ${why} — no isolation`);
-    scope.registerValue(key, {
-      run: <R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R> => ambient.enterFrame(key, async () => {
-        const journal: Undo[] = [];
-        const record = (storage: Storage, name: string, schema: SchemaView) =>
-          validator(recording(storage, name, schema, journal), name, schema);
-        try {
-          return await inScope(scope, members, world.storageFactory!, record, fn as never);
-        } catch (cause) {
-          return unwind(journal, cause, world.log);
-        }
-      }),
-    });
+    scope.registerValue(key, frameOver(key, members, scope, world));
   }
+
   if (registered > 0 && ambient.degraded) {
     world.log.warn(
       'no async context on this runtime — frames run one at a time, and a frame opened '
@@ -227,3 +212,53 @@ export function registerFrames(
     );
   }
 }
+
+/**
+ * A transaction when one engine holds every member, a compensation otherwise.
+ *
+ * One engine and a way into it: the engine gives the unwind AND the isolation. The question goes
+ * to the SOURCE these members live in — a composition answering for the default one would
+ * compensate a frame whose own engine holds transactions.
+ */
+function frameOver(key: string, members: Members, scope: Container, world: FrameWorld): Frame {
+  const sources = new Set(members.entities.map((member) => world.sourceOf?.(member.name) ?? 'db'));
+  const validator = (storage: Storage, name: string, schema: SchemaView) =>
+    new StorageGuard(schema.getFields(), name, {}, heldBy(schema, name, world.hosting), releasing(world.hosting)).guard(storage);
+
+  const source = sources.size === 1 ? [...sources][0]! : undefined;
+  if (world.transacted && source !== undefined && (world.transacts?.(source) ?? true)) {
+    world.log.info(`${key} — transaction, source '${source}'`);
+
+    return {
+      run: <R>(fn: (entities: never, providers: never) => Promise<R>) =>
+        ambient.enterFrame(key, () =>
+          world.transacted!(source, (factory) => inScope(scope, members, factory, validator, fn as never))),
+    };
+  }
+
+  // Split, or an engine that hands out no transaction: the frame keeps the before-image of every
+  // write and replays the inverses itself. `validator` stays OUTSIDE `recording`, so a write the
+  // entity refuses never enters the journal.
+  const why = sources.size > 1
+    ? members.entities.map((one) => `${one.name} in '${world.sourceOf?.(one.name) ?? 'db'}'`).join(', ')
+    : 'this storage hands out no transaction';
+  world.log.info(`${key} — compensated: ${why} — no isolation`);
+
+  return {
+    run: <R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R> => ambient.enterFrame(key, async () => {
+      const journal: Undo[] = [];
+      const record = (storage: Storage, name: string, schema: SchemaView) =>
+        validator(recording(storage, name, schema, journal), name, schema);
+      try {
+        return await inScope(scope, members, world.storageFactory!, record, fn as never);
+      } catch (cause) {
+        return unwind(journal, cause, world.log);
+      }
+    }),
+  };
+}
+
+/** What a `Together<[…]>` key resolves to — the block, and nothing else. */
+interface Frame {
+  run<R>(fn: (entities: never, providers: never) => Promise<R>): Promise<R>;
+}

package/src/descriptor/FrondDescriptor.ts

@@ -34,6 +34,13 @@ export interface FrondDescriptor {
    * domain. Set by the boot, never by a declaration.
    */
   brought?: true;
+  /**
+   * The frond this one inherits code from — its scope hangs off that one's, so a service, a
+   * repository, a port or a middleware declared there answers here too. The same word the
+   * config uses, set by the boot from `FougereConfig.fronds` and never by a scan: the disk is
+   * flat, and a directory says nothing about who shares its code.
+   */
+  extends?: string;
   /** The ops that finish a fact, in order — see `FrondConfig.pipes`. */
   pipes?: Record<string, string[]>;
   /**

package/src/descriptor/MiddlewareEntry.ts

@@ -1,14 +1,15 @@
 /**
- * A discovered middleware — a class declaring `around(ctx, next)`, which runs before and
- * after every operation in its scope.
+ * A discovered middleware — a class declaring `around(ctx, next)`, which runs before and after
+ * every operation of its frond, and of the fronds that inherit from it.
+ *
+ * How far it reaches is not written here: it is where the frond sits in `FougereConfig.fronds`,
+ * and stating it twice would put one decision in two places.
  */
 export interface MiddlewareEntry {
-  /** Class name — what `frond.config.ts` addresses to widen the scope. */
+  /** Class name — the key it registers under in its frond's scope. */
   name: string;
   /** The middleware class. */
   ctor: new (...args: never[]) => unknown;
-  /** How far it reaches: its own frond's entities, or every operation in the process. */
-  scope: 'frond' | 'app';
   /** Constructor dependency type names (from AST scan). */
   deps: string[];
   /** Absolute file path (for debugging). */

package/src/descriptor/ProviderEntry.ts

@@ -15,4 +15,11 @@ export interface ProviderEntry {
   deps: string[];
   /** Absolute file path (for debugging). */
   filePath: string;
+  /**
+   * It stated `implements AsyncDisposable` — so there is ONE of it per frond, and that frond's
+   * scope closes it. The language's own marker, which `App` already answers; a provider that
+   * says nothing is built per consumer and closed by nobody, which is right for one that holds
+   * nothing.
+   */
+  kept?: true;
 }

package/src/dispatch/HandlerFacade.ts

@@ -40,6 +40,11 @@ export class HandlerFacade {
   /** A computed field's parameters and the collectors in scope are both boot-time facts. */
   private readonly presenterPlans: Map<string, BindingPlan>;
 
+  private collectorResolver = (typeName: string): CollectorResolver | undefined => {
+    try { return this.scope.resolve(collectorKeyOf(typeName)) as CollectorResolver; }
+    catch { return undefined; }
+  };
+
   constructor(
     private readonly handler: HandlerEntry,
     private readonly scope: Container,
@@ -93,20 +98,30 @@ export class HandlerFacade {
       invocation,
     };
 
-    return runMiddlewares(this.facade.middlewares(), context, async () => {
-      const validated = validateInput(contract.input, invocation, entity, op);
-      context.invocation = validated;
+    return runMiddlewares(this.facade.middlewares(), context, () => this.answer(op, contract, context, invocation));
+  }
 
-      const args = contract.binding
-        ? await this.arguments.resolve(contract.binding, validated)
-        : [];
-      const { instance, method } = this.resolveImplementation(op);
-      const view = this.viewOf(op);
-      const output = view.project(await instance[method](...args));
+  /**
+   * What the handler answers, once the middlewares let the call through: the input judged, the
+   * arguments bound, the row projected onto the view this audience sees.
+   */
+  private async answer(
+    op: string,
+    contract: OperationContract,
+    context: OperationContext,
+    invocation: Invocation,
+  ): Promise<unknown> {
+    const validated = validateInput(contract.input, invocation, this.handler.address, op);
+    context.invocation = validated;
 
-      const { presenter } = this.facade;
-      return view.closed || !presenter ? output : this.present(op, presenter, output, validated);
-    });
+    const args = contract.binding ? await this.arguments.resolve(contract.binding, validated) : [];
+    const { instance, method } = this.resolveImplementation(op);
+    const view = this.viewOf(op);
+    const output = view.project(await instance[method](...args));
+
+    const { presenter } = this.facade;
+
+    return view.closed || !presenter ? output : this.present(op, presenter, output, validated);
   }
 
   /** The computed fields a presenter adds, over the page the façade just projected. */
@@ -168,11 +183,6 @@ export class HandlerFacade {
     return resolved;
   }
 
-  private collectorResolver = (typeName: string): CollectorResolver | undefined => {
-    try { return this.scope.resolve(collectorKeyOf(typeName)) as CollectorResolver; }
-    catch { return undefined; }
-  };
-
   /** The handler itself, resolved on first call — never at boot. */
   private resolveHandler(): any {
     if (!this.instance) this.instance = this.scope.resolve(this.handlerKey);

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/Release.ts

@@ -86,57 +86,16 @@ async function walk(
   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')) {
-    const rows = world.rowsOf(dependent.entity);
-    if (!rows) continue;
-    const found = [...(await rows.findAllByKeys(dependent.field, keys.map(String))).values()].flat();
-    if (found.length === 0) continue;
-
-    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',
-    });
+    await refuseHeld(entity, dependent, keys, world);
   }
 
   for (const dependent of dependents.filter((one) => one.onDelete !== 'restrict')) {
-    const rows = world.rowsOf(dependent.entity);
-    // Nothing here holds those rows. The process that does answers the same two readings core
-    // serves everywhere, so the ask crosses and the work happens on ITS side of the wire —
-    // which is what keeps the declaration identical whatever the topology.
-    // 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.
-    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);
-      }
-      continue;
-    }
-
-    const naming = await rows.findAllByKeys(dependent.field, keys.map(String));
-    const found = [...naming.values()].flat();
-    if (found.length === 0) continue;
-
-    if (dependent.onDelete === 'set null') {
-      const primary = keyOf(world, dependent.entity);
-      for (const row of found) await rows.update(String(row[primary]), { [dependent.field]: null });
-      continue;
-    }
-
-    const primary = keyOf(world, dependent.entity);
-    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));
+    await carryOut(entity, dependent, keys, world, seen, trail);
   }
 }
 
@@ -154,3 +113,68 @@ function keyOf(world: Releasing, entity: string): string {
 
   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));
+}