@fougere/core 0.9.0-alpha.1 → 0.9.3-alpha.0

package/src/prefab/crud.ts

@@ -4,8 +4,8 @@ import type { OperationContract } from '../wire/operation.js';
 import { targetOf } from './prefab.js';
 
 /**
- * So a class is recognized by what it ANSWERS, since the mixin leaves no other trace.
- * FR : pour qu'une classe se reconnaisse à ce qu'elle répond, le mixin ne laissant rien d'autre.
+ * A class is recognized by what it ANSWERS — the mixin leaves no other trace.
+ * FR : une classe se reconnaît à ce qu'elle répond, le mixin ne laissant rien d'autre.
  * `inheritsCrud(class PostHandler extends Crud(Post) {})` → `true`
  */
 export function inheritsCrud(ctor: unknown): boolean {
@@ -15,8 +15,8 @@ export function inheritsCrud(ctor: unknown): boolean {
 }
 
 /**
- * So storage follows the shape the handler was built on, which may differ from its address.
- * FR : pour que le stockage suive la forme sur laquelle le handler est bâti.
+ * Storage follows the shape the handler was built on, which may differ from its address.
+ * FR : le stockage suit la forme sur laquelle le handler est bâti, pas son adresse.
  * `subjectOf(class Draft extends Crud(Post) {}, 'draft')` → `'post'`
  */
 export function subjectOf(ctor: unknown, address: string): string {
@@ -35,8 +35,11 @@ const inputParam = (entity: string) => ({ name: 'input', type: { raw: `Partial<$
 const returns = (raw: string, name: string, extra?: { array?: boolean; nullable?: boolean }) =>
   ({ raw, name, ...extra });
 
-/** The five ops a Crud handler brings, declared rather than discovered. */
-/** `output` says the entity, and saying it costs nothing at runtime. */
+/**
+ * The five ops a Crud handler brings, declared rather than discovered.
+ *
+ * `output` says the entity, and saying it costs nothing at runtime.
+ */
 function crudOps(entity: SchemaView & { partial?: () => SchemaView }): Record<string, OperationContract> {
   const name = (entity as { name?: string }).name ?? 'Entity';
   const input = inputParam(name);
@@ -112,7 +115,11 @@ export interface CrudConstructor<T, V = {}> {
   readonly __ops: Record<string, OperationContract>;
 }
 
-/** Mixin — extends Crud(Entity) to get all 5 typed CRUD methods. */
+/**
+ * Mixin — extends Crud(Entity) to get all 5 typed CRUD methods.
+ *
+ * Documented: [handlers](https://fougere.dev/docs/business/handlers).
+ */
 export function Crud<E extends EntityConstructor, V extends CrudViews | EntityConstructor = {}>(
   entity: E,
   output?: V,

package/src/prefab/mirror.ts

@@ -11,7 +11,11 @@ export interface Refreshed {
   ms: number;
 }
 
-/** A paginated local copy of a source that cannot be queried directly. */
+/**
+ * A paginated local copy of a source that cannot be queried directly.
+ *
+ * Documented: [the base](https://fougere.dev/docs/concepts/the-base).
+ */
 export interface MirrorOf<T> {
   /** The copy's own storage — where a page lands. */
   storage: Storage<T>;

package/src/prefab/presenter.ts

@@ -1,4 +1,8 @@
-/** Presenter(Entity) — enriches an entity's output with computed fields. */
+/**
+ * Presenter(Entity) — enriches an entity's output with computed fields.
+ *
+ * Documented: [presenters](https://fougere.dev/docs/business/presenters).
+ */
 
 import { upperFirst, type EntityConstructor } from '@fougere/schema';
 
@@ -8,7 +12,7 @@ import { upperFirst, type EntityConstructor } from '@fougere/schema';
  */
 export type PresenterViews = Record<string, EntityConstructor | [EntityConstructor]>;
 
-/** `Presenter(Order, { items. */
+/** `Presenter(Order, { items: [OrderItemView] })` — the views its computed fields emit. */
 export function Presenter<E extends EntityConstructor>(entity: E, views?: PresenterViews) {
   class PresenterBase {
     static readonly __entity = entity;

package/src/prefab/repository.ts

@@ -2,7 +2,11 @@ import { upperFirst, type EntityConstructor } from '@fougere/schema';
 import type { Storage, ListOptions, ListResult, SelectOption } from '../storage/port.js';
 import type { SchemaView } from '@fougere/schema';
 
-/** Repository(…entities) — who owns an entity's storage, and where its questions are named. */
+/**
+ * Repository(…entities) — who owns an entity's storage, and where its questions are named.
+ *
+ * Documented: [repositories](https://fougere.dev/docs/business/repositories).
+ */
 
 /**
  * The shape a repository of ONE entity has — the port itself, plus whatever the subclass names on

package/src/scan.ts

@@ -1,6 +1,5 @@
 import type { Fronds } from './descriptor/Fronds.js';
 
-/** Result of scanning a project directory. */
 /** Something the scan could NOT do — recorded instead of swallowed. */
 export interface ScanDiagnostic {
   /**
@@ -22,6 +21,7 @@ export interface ScanDiagnostic {
   cause?: unknown;
 }
 
+/** Result of scanning a project directory. */
 export interface ScanResult {
   fronds: Fronds;
   /** What the scan could not do. Empty is a claim, not a default — see {@link ScanDiagnostic}. */

package/src/source.ts

@@ -12,7 +12,11 @@ export function declares(schema: SchemaView, constraint: Constraint): boolean {
   return Object.values(schema.getFields()).some((field) => Role.of(field).isUnique);
 }
 
-/** A place rows live, whatever realizes it. */
+/**
+ * A place rows live, whatever realizes it.
+ *
+ * Documented: [sources](https://fougere.dev/docs/infra/sources).
+ */
 export interface Source {
   storageFactory: StorageFactory;
   /**

package/src/storage/port.ts

@@ -102,8 +102,81 @@ export interface Storage<T = Record<string, unknown>> {
   delete(id: string): Promise<boolean>;
   /** Returns a scoped storage that restricts all read results to the fields of the given schema. */
   output(schema: SchemaView): Storage<T>;
+}
+
+/**
+ * What each link of a chain stands in front of.
+ *
+ * A SYMBOL on the instance, set through a cast so it joins no declaration: `Storage` is an
+ * interface as well as a class, and the realizations satisfy it structurally —
+ * `storageOver` returns an object literal, and one more member would stop it being a
+ * storage. A `#private` field says the same thing and makes the class NOMINAL, which
+ * refuses every realization at once.
+ *
+ * On the instance and not in a `WeakMap` beside it, because `StorageGuard.guard` hands out
+ * `Object.create(storage)` — a new object whose prototype is the link. A symbol is found
+ * through that chain; a map keyed on the link is not, and the guarded object read
+ * `undefined`.
+ */
+const BEHIND = Symbol('fougere.storage.behind');
+
+const behind = <T>(link: object): Storage<T> =>
+  (link as Record<symbol, unknown>)[BEHIND] as Storage<T>;
+
+/**
+ * A storage that stands in front of another — the base a wrapper extends, and the only
+ * thing that makes `Storage` a seam rather than a shape.
+ *
+ * Merged with the interface above, so the class carries the thirteen gestures as a TYPE
+ * while its prototype carries them as a FORWARD. A wrapper writes what it changes and
+ * nothing else:
+ *
+ * ```ts
+ * class Audit extends Storage {
+ *   constructor(private inner: Storage) { super(inner); }
+ *   async create(row) { await say(row); return this.inner.create(row); }
+ * }
+ * ```
+ *
+ * `ports: { Storage: ['Audit'] }` orders the chain when a frond declares two, which is the
+ * same key, the same order and the same refusals a port gets. A realization does not extend
+ * this: it is handed in by `storageFactory` and is the last link, so what a wrapper does not
+ * override reaches it through these forwards.
+ *
+ * Documented: [storage](https://fougere.dev/docs/business/storage) and
+ * [ports](https://fougere.dev/docs/business/ports).
+ */
+export abstract class Storage<T = Record<string, unknown>> {
+  constructor(inner: Storage<T>) {
+    (this as Record<symbol, unknown>)[BEHIND] = inner;
+  }
+
+  list(options?: ListOptions & SelectOption): Promise<ListResult<T>> { return behind<T>(this).list(options); }
+  findById(id: string, options?: SelectOption): Promise<T | undefined> { return behind<T>(this).findById(id, options); }
+  findBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption): Promise<T | undefined> {
+    return behind<T>(this).findBy(criteria, options);
+  }
+  findAllBy(criteria: Partial<T> | Record<string, unknown>, options?: SelectOption): Promise<T[]> {
+    return behind<T>(this).findAllBy(criteria, options);
+  }
+  findByKeys(ids: readonly string[], options?: SelectOption): Promise<Map<string, T>> {
+    return behind<T>(this).findByKeys(ids, options);
+  }
+  findAllByKeys(field: string, keys: readonly string[], options?: SelectOption): Promise<Map<string, T[]>> {
+    return behind<T>(this).findAllByKeys(field, keys, options);
+  }
+  create(input: Partial<T>, options?: SelectOption): Promise<T> { return behind<T>(this).create(input, options); }
+  upsert(input: Partial<T>, options?: SelectOption): Promise<T> { return behind<T>(this).upsert(input, options); }
+  upsertAll(inputs: readonly Partial<T>[], options?: SelectOption): Promise<number> {
+    return behind<T>(this).upsertAll(inputs, options);
+  }
+  update(id: string, input: Partial<T>, options?: SelectOption): Promise<T> {
+    return behind<T>(this).update(id, input, options);
+  }
+  delete(id: string): Promise<boolean> { return behind<T>(this).delete(id); }
+  output(schema: SchemaView): Storage<T> { return behind<T>(this).output(schema); }
   /** What this storage wraps — the Kysely instance for the SQL one, something else elsewhere. */
-  readonly client: unknown;
+  get client(): unknown { return behind<T>(this).client; }
 }
 
 /**

package/src/wire/call.ts

@@ -30,10 +30,10 @@ export interface FrondCall {
 /** A transport executes a call somewhere else. Failures surface as thrown FougereError. */
 export type Transport = (call: FrondCall, invocation: InvocationContext) => Promise<unknown>;
 
-/** Reserved namespace — calls the runner answers itself, never a façade. */
 /** What a receiver accepts before it stops reading an input. */
 export const MAX_BODY_BYTES = 1024 * 1024;
 
+/** Reserved namespace — calls the runner answers itself, never a façade. */
 export const RPC_ENTITY = 'rpc';
 
 /** What an `rpc` op answers — the door for what the app says about ITSELF, never about a row. */
@@ -98,6 +98,33 @@ export interface Edge {
   errors: number;
 }
 
+/** A frond the config knows of, and where it says to reach it. */
+export interface DeclaredFrond {
+  frond: string;
+  placement: 'local' | 'remote';
+  /**
+   * Host and port of the address `remotes:` names, absent when the frond runs here. Never the
+   * whole address: a declared one may carry credentials, and this answer leaves the process.
+   */
+  at?: string;
+}
+
+/** One frond reaching another, read from a handler's dependencies rather than from a call. */
+export interface DeclaredEdge {
+  from: string;
+  to: string;
+}
+
+/**
+ * What the config SAYS, beside what the runtime SAW. The two disagree exactly when something
+ * is misconfigured, and a frond that never answered is absent from the observed half — so
+ * without this one, nothing tells a silent dependency from an absent one.
+ */
+export interface DeclaredTopology {
+  fronds: DeclaredFrond[];
+  edges: DeclaredEdge[];
+}
+
 /** The shape of the system as ONE process discovered it — the answer to `rpc.topology`. */
 export interface TopologyReport {
   /** When this process started counting — an edge count is read against it. */
@@ -106,6 +133,7 @@ export interface TopologyReport {
   active: number;
   fronds: FrondPlacement[];
   edges: Edge[];
+  declared: DeclaredTopology;
 }
 
 /** The shape a card must have to be walked — `fronds`, and each frond's `doors`. */

package/src/wire/emit.ts

@@ -1,4 +1,8 @@
-/** Announcing a fact — the half of the topology `remotes:` never covered. */
+/**
+ * Announcing a fact — the half of the topology `remotes:` never covered.
+ *
+ * Documented: [facts](https://fougere.dev/docs/business/facts).
+ */
 import { lowerFirst } from '@fougere/schema';
 
 /**

package/src/wire/errors.ts

@@ -1,4 +1,8 @@
-/** The error vocabulary — what a refusal IS, independently of who hears it. */
+/**
+ * The error vocabulary — what a refusal IS, independently of who hears it.
+ *
+ * Documented: [errors](https://fougere.dev/docs/business/errors).
+ */
 
 import type { ValidationError } from '@fougere/schema';
 

package/src/wire/signature.ts

@@ -1,4 +1,3 @@
-/** A method's signature, as a contract is built from it — the shape, never the reading. */
 /** A type reference — primitives, entities, arrays, generics. */
 export interface TypeRef {
   /** Raw type text as written in source (e.g. 'Pagination<Post>'). */
@@ -26,7 +25,7 @@ export interface Param {
   optional?: boolean;
 }
 
-/** A method signature. */
+/** A method's signature, as a contract is built from it — the shape, never the reading. */
 export interface Signature {
   name: string;
   params: Param[];