@fougere/core 0.9.0-alpha.0 → 0.9.2-alpha.0

package/src/prefab/collector.ts

@@ -1,4 +1,8 @@
-/** Collector(Type) — resolves one handler input parameter from the invocation context. */
+/**
+ * Collector(Type) — resolves one handler input parameter from the invocation context.
+ *
+ * Documented: [collectors](https://fougere.dev/docs/business/collectors).
+ */
 
 import { upperFirst } from '@fougere/schema';
 

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 {
@@ -112,7 +112,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/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/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';