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

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

@@ -1,4 +1,7 @@
 import { lowerFirst } from '@fougere/schema';
+import { computeBindingPlan } from './binding.js';
+import type { OperationContract } from './OperationContract.js';
+import type { OperationsMap } from './OperationsMap.js';
 
 /**
  * What an emitter injects. PARTIAL, because announcing is what REALIZES the fact's
@@ -52,6 +55,26 @@ export function factsAwaitedBy(handlers: readonly { deps: readonly string[] }[])
   return factsIn(handlers, factOfAwaitKey);
 }
 
+/**
+ * What a set of handlers LISTENS to — the dual of what it announces, and the half no
+ * dependency spells: accepting a `Fact<T>` IS the subscription, so it is read from the
+ * binding plan, where `Emissions` reads it too.
+ */
+export function factsListenedTo(handlers: readonly { operations: OperationsMap }[]): string[] {
+  const taken = (contract: OperationContract): string[] => {
+    const plan = contract.binding
+      ?? (contract.signature ? computeBindingPlan(contract.signature.params, NO_COLLECTOR) : []);
+
+    return plan.flatMap((bound) =>
+      bound.source.kind === 'fact' || bound.source.kind === 'pipe' ? [bound.source.factName] : []);
+  };
+
+  return [...new Set(handlers.flatMap((handler) => [...handler.operations.values()].flatMap(taken)))];
+}
+
+/** `Fact` and `Pipe` name themselves, and the plan reads them before it reads a collector. */
+const NO_COLLECTOR = new Set<string>();
+
 function factsIn(
   handlers: readonly { deps: readonly string[] }[],
   behindKey: (key: string) => string | undefined,

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;
@@ -31,8 +33,9 @@ export class Invocation implements InvocationContext {
   readonly trace?: string;
   readonly identity?: string;
   readonly caller?: string;
+  readonly runAt?: number;
 
-  /** Gives every entry and every transport the same seven-member value, frozen. */
+  /** Gives every entry and every transport the same eight-member value, frozen. */
   private constructor(context: PartialInvocation) {
     this.params = canonicalRecord(context.params);
     this.query = canonicalRecord(context.query);
@@ -43,6 +46,7 @@ export class Invocation implements InvocationContext {
     if (context.trace !== undefined) this.trace = context.trace;
     if (context.identity !== undefined) this.identity = context.identity;
     if (context.caller !== undefined) this.caller = context.caller;
+    if (context.runAt !== undefined) this.runAt = context.runAt;
     Object.freeze(this);
   }
 
@@ -51,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/InvocationContext.ts

@@ -6,4 +6,6 @@ export interface InvocationContext {
   trace?: string;
   identity?: string;
   caller?: string;
+  /** Epoch milliseconds before which this call is not to run. */
+  runAt?: number;
 }

package/src/wire/SignedCall.ts

@@ -9,4 +9,6 @@ export interface SignedCall {
   query?: Record<string, unknown>;
   input?: unknown;
   state?: Record<string, unknown>;
+  /** The hour, pinned like the input: moving it is moving the call. */
+  runAt?: number;
 }

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. */