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

package/src/storage/Store.ts

@@ -1,4 +1,4 @@
-import { applyCreate, applyUpdate, Lifecycle, Role, type SchemaView } from '@fougere/schema';
+import { applyCreate, applyUpdate, Role, type SchemaView } from '@fougere/schema';
 import { comparisonOf, comparisonsIn, type Comparison } from './Comparison.js';
 import type { Storage } from './Storage.js';
 import type { StorageFactory } from './StorageFactory.js';
@@ -21,7 +21,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
   return (entity: SchemaView, name: string): Storage => {
     const fields = entity.getFields();
     const store = open(entity, name);
-    const pk = Object.entries(fields).find(([, field]) => Role.of(field).isPrimary)?.[0] ?? 'id';
+    const pk = Object.entries(fields).find(([, field]) => Role.of(field).isPrimary())?.[0] ?? 'id';
     // `Storage.findById(id: string)` — but a key can hold a number, and a Map keyed on
     // `1` does not answer `'1'`. SQL never had the question; here the divergence was
     // silent and only on this storage.
@@ -46,20 +46,18 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
         ? Object.fromEntries(Object.entries(values).filter(([key]) => selected.has(key)))
         : values);
 
-      // Same contract as SQL: the key and the creation stamps survive an overwrite.
+      // Same contract as SQL: a row that is already there is UPDATED, so what the write leaves
+      // out stays where it was.
       // Named, and not reached through `this`: a caller may have wrapped these gestures,
       // and a derived one that goes back through the front facade is judged twice.
       const upsert = async (input: Partial<Record<string, unknown>>): Promise<Values> => {
-        const values = applyCreate(fields, applyUpdate(fields, input));
-        const id = values[pk] as string | undefined;
+        const created = applyCreate(fields, applyUpdate(fields, input));
+        const id = created[pk] as string | undefined;
         if (id === undefined) throw new Error(`${name}.upsert(): no \`${pk}\` — an upsert needs the key it writes at.`);
         const previous = await store.get(keyOf(id));
-        if (previous) {
-          for (const [key, field] of Object.entries(fields)) {
-            if (key === pk || Lifecycle.of(field).stampedOnce) values[key] = previous[key];
-          }
-        }
+        const values = previous ? { ...previous, ...applyUpdate(fields, input) } : created;
         await store.set(keyOf(id), values);
+
         return pick(values);
       };
 
@@ -74,10 +72,12 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
         },
         async findById(id: string) {
           const values = await store.get(keyOf(id));
+
           return values && pick(values);
         },
         async findBy(criteria: Record<string, unknown>) {
           const values = (await store.all()).find((held) => matches(held, criteria));
+
           return values && pick(values);
         },
         async findAllBy(criteria: Record<string, unknown>) {
@@ -90,6 +90,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
             const values = await store.get(keyOf(id));
             if (values) found.set(String(id), pick(values));
           }
+
           return found;
         },
         // The dual, same contract as SQL: grouped by the value read off the instance.
@@ -103,11 +104,13 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
             const bucket = grouped.get(key);
             if (bucket) bucket.push(pick(values)); else grouped.set(key, [pick(values)]);
           }
+
           return grouped;
         },
         upsert,
         async upsertAll(inputs: readonly Partial<Record<string, unknown>>[]) {
           for (const input of inputs) await upsert(input);
+
           return inputs.length;
         },
         async create(input: Partial<Record<string, unknown>>) {
@@ -128,6 +131,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
             throw new Error(`${name}.create: '${pk}' ${JSON.stringify(id)} already exists.`);
           }
           await store.set(keyOf(id), values);
+
           return pick(values);
         },
         async update(id: string, input: Partial<Record<string, unknown>>) {
@@ -135,6 +139,7 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
           if (!existing) throw new Error(`Not found: ${id}`);
           const updated = { ...existing, ...applyUpdate(fields, input), [pk]: existing[pk] };
           await store.set(keyOf(id), updated);
+
           return pick(updated);
         },
         async delete(id: string) { return await store.delete(keyOf(id)); },

package/src/verify.ts

@@ -42,6 +42,7 @@ function registrationsOf(frond: FrondDescriptor): Map<string, Registration> {
     put(storageKeyOf(e.name), 'storage');
     put(repositoryKeyOf(e.name), 'repository');
   }
+
   return out;
 }
 
@@ -143,6 +144,7 @@ export function verify(app: { fronds: readonly FrondDescriptor[] }): Misplaced[]
       }
     }
   }
+
   return violations;
 }
 

package/src/wire/AppMiddleware.ts

@@ -1,7 +1,16 @@
 import type { OperationContext } from './OperationContext.js';
 import type { AppNext } from './AppNext.js';
 
-export type AppMiddleware = (ctx: OperationContext, next: AppNext) => Promise<unknown>;
+/**
+ * A middleware answers what the chain answered — the same TYPE, whatever it does with the value.
+ *
+ * `T` is the whole rule and nothing enforces it at runtime: a middleware is handed a type it
+ * cannot name, so the only value of that type it can produce is the one `next()` gave it. It may
+ * observe it, log it, replace it with another of the same shape, or refuse by throwing; it may
+ * not wrap it in `{ data, meta }` nor invent one, because a caller reads the handler's signature
+ * and nothing tells that signature a middleware stood in the way.
+ */
+export type AppMiddleware = <T>(ctx: OperationContext, next: AppNext<T>) => Promise<T>;
 
 // ── Runner ──────────────────────────────────────
 
@@ -18,7 +27,9 @@ export function runMiddlewares(
     if (index < middlewares.length) {
       return middlewares[index++](ctx, next);
     }
+
     return handler();
   };
+
   return next();
 }

package/src/wire/AppNext.ts

@@ -1 +1,2 @@
-export type AppNext = () => Promise<unknown>;
+/** What a middleware holds: the rest of the chain, and the answer it will hand back. */
+export type AppNext<T = unknown> = () => Promise<T>;

package/src/wire/Facade.ts

@@ -10,10 +10,22 @@ type Served = keyof FougereOperations & string;
  */
 type AddressIn<Key> = Key extends `${infer Address}.${string}` ? Address : never;
 
-/** The facade built in front of a handler — the framework's second port, after `Storage`. */
+/**
+ * The facade built in front of a handler — the framework's second port, after `Storage`.
+ *
+ * What the handler knows is WHICH operations exist and what each one answers. The two ends are
+ * the port's own: an invocation goes in where the handler takes positional arguments, and a
+ * promise comes back where the handler may answer a bare value. A facade is a crossing, and a
+ * crossing is awaited before any transport — the dispatch resolves a route, runs the middlewares
+ * and awaits the collectors, so `readLocation(): string` was typed as answering now and never did.
+ *
+ * `Awaited` because a promise does not stack: `Promise.resolve(p)` IS `p`, so writing
+ * `Promise<R>` over an async handler would describe a `Promise<Promise<Post>>` that no value can
+ * have — `.then` would hand its callback a promise the runtime never delivers.
+ */
 export type Facade<T> = {
   [K in keyof T]: T[K] extends (...args: never[]) => infer R
-    ? (invocation?: InvocationContext) => R
+    ? (invocation?: InvocationContext) => Promise<Awaited<R>>
     : never;
 };
 

package/src/wire/FougereError.ts

@@ -20,7 +20,7 @@ export class FougereError<Code extends ErrorCode = ErrorCode> extends Error {
 
   constructor(options: FougereErrorOptions<Code>) {
     super(options.message, { cause: options.cause });
-    this.name = new.target.name;
+    this.name = 'FougereError';
     this.code = options.code;
     this.entity = options.entity;
     this.operation = options.operation;
@@ -41,6 +41,7 @@ export class FougereError<Code extends ErrorCode = ErrorCode> extends Error {
   static fromJSON(json: unknown): FougereError {
     const raw = (typeof json === 'object' && json !== null ? json : {}) as Record<string, unknown>;
     const known = Object.values(ErrorCode).includes(raw.code as ErrorCode);
+
     return new FougereError({
       code: known ? (raw.code as ErrorCode) : ErrorCode.INTERNAL_ERROR,
       message: typeof raw.message === 'string' ? raw.message : 'Unknown error',
@@ -65,5 +66,6 @@ export function validationErrorsOf(error: unknown): ValidationError[] | undefine
       && Array.isArray((entry as ValidationError).path)
       && typeof (entry as ValidationError).message === 'string',
   );
+
   return refusals.length === details.length ? refusals : undefined;
 }

package/src/wire/Invocation.ts

@@ -8,6 +8,7 @@ function canonicalValue(value: unknown): unknown {
 
   const prototype = Object.getPrototypeOf(value);
   if (prototype !== Object.prototype && prototype !== null) return value;
+
   return canonicalRecord(value);
 }
 
@@ -19,6 +20,7 @@ function canonicalRecord(value: unknown): Record<string, unknown> {
   for (const [key, member] of Object.entries(value)) {
     if (member !== undefined) result[key] = canonicalValue(member);
   }
+
   return Object.freeze(result);
 }
 

package/src/wire/OperationContract.ts

@@ -36,9 +36,10 @@ export function cardinalityOf(type: TypeRef | undefined): OperationContract['car
   if (!type) return undefined;
   const inner = type.name === 'Promise' ? type.generics?.[0] : type;
   if (!inner) return 'none';
-  if (inner.name === 'ListResult') return 'page';
+  if (inner.name === 'Page' || inner.name === 'ListResult') return 'page';
   if (inner.array) return 'many';
   if (PRIMITIVE_RETURNS.has(inner.name)) return 'none';
+
   return inner.nullable || inner.undefined ? 'maybe' : 'one';
 }
 

package/src/wire/Page.ts

@@ -0,0 +1,50 @@
+/**
+ * What a paged operation answers — the rows, and what the storage said about the rest of them.
+ *
+ * An ENVELOPE rather than the array `Storage.list` hands back: that one carries `total` and
+ * `hasMore` as properties OF the array, and `JSON.stringify` keeps only the indices. Measured
+ * 2026-09-18 — `page.total` is 42 in this process and `undefined` behind `fronds:`, off the same
+ * code. What crosses has to be named, so it is a field.
+ *
+ * `Storage.list` keeps its array: it answers inside a frond and never crosses.
+ */
+export interface Page<Row> {
+  items: Row[];
+  /** Only when the caller asked to count. */
+  total?: number;
+  hasMore?: boolean;
+  endCursor?: string;
+}
+
+/**
+ * The array `Storage.list` answers, read as the page an operation hands over.
+ *
+ * A storage handed in by a host may answer the envelope already — `storageFactory` is its door,
+ * and nothing there is obliged to subclass an array. Taken as it comes in that case.
+ */
+export function pageOf<Row>(rows: Page<Row> | readonly Row[]): Page<Row> {
+  if (!Array.isArray(rows)) return rows as Page<Row>;
+
+  const { total, hasMore, endCursor } = rows as unknown as Omit<Page<Row>, 'items'>;
+
+  return {
+    items: [...rows],
+    ...(total !== undefined && { total }),
+    ...(hasMore !== undefined && { hasMore }),
+    ...(endCursor !== undefined && { endCursor }),
+  };
+}
+
+/**
+ * The value read as a page, or nothing.
+ *
+ * Read from the FORM, and arbitrated by the schema: an entity legally declaring a field named
+ * `items` answers a row, not a page, and it is the only thing that could tell the two apart.
+ */
+export function asPage(value: unknown, fields: Record<string, unknown>): Page<unknown> | undefined {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  if ('items' in fields) return undefined;
+  const page = value as Page<unknown>;
+
+  return Array.isArray(page.items) ? page : undefined;
+}

package/src/wire/RouteAddress.ts

@@ -3,6 +3,7 @@ import type { RouteAddressInput } from './RouteAddressInput.js';
 /** Refuses an empty segment, so no address can be built that nothing can serve. */
 function required(value: string, name: string): string {
   if (value.trim().length === 0) throw new TypeError(`Route ${name} cannot be empty`);
+
   return value;
 }
 
@@ -38,6 +39,7 @@ export class RouteAddress {
   /** Writes the address the way a log and an error message name it. */
   toString(): string {
     const audience = this.surface ? `${this.surface}/` : '';
+
     return `${audience}${this.entity}.${this.operation}`;
   }
 

package/src/wire/Signature.ts

@@ -10,4 +10,11 @@ export interface Signature {
   inherited?: boolean;
   /** The operation in words — the first sentence of the method's doc comment. */
   description?: string;
+  /**
+   * The first thing in the return type that is not data — its path, and the type sitting there.
+   *
+   * Written whenever a checker read the signature, and judged only where nothing converts the
+   * output: what a declared entity answers is encoded by its fields.
+   */
+  notData?: string;
 }

package/src/wire/binding.ts

@@ -38,6 +38,7 @@ const PRIMITIVES = new Set(['string', 'number', 'boolean']);
 function coercionFor(typeName: string): 'number' | 'boolean' | undefined {
   if (typeName === 'number') return 'number';
   if (typeName === 'boolean') return 'boolean';
+
   return undefined;
 }
 

package/src/wire/card/IdentityCard.ts

@@ -27,6 +27,7 @@ export function assertIdentityCard(value: unknown, source: string): IdentityCard
     if (!frond || typeof frond.name !== 'string') throw cardRefusal(source, 'a frond with no name');
     if (!Array.isArray(frond.facades)) throw cardRefusal(source, `frond '${frond.name}' has no valid facades array`);
   }
+
   return card as IdentityCard;
 }
 

package/src/wire/drift.ts

@@ -29,6 +29,7 @@ function facadesOf(card: IdentityCard, frond: string): Map<string, Answering> {
       found.set(facade.name, { ops: new Set(facade.ops.map((op) => op.name)), schema: facade.schema });
     }
   }
+
   return found;
 }
 
@@ -38,6 +39,7 @@ function factsOf(card: IdentityCard, frond: string): Map<string, SchemaDescripto
     if (one.name !== frond) continue;
     for (const fact of one.facts ?? []) found.set(fact.name, fact.schema as SchemaDescriptor | undefined);
   }
+
   return found;
 }
 
@@ -117,6 +119,7 @@ export function explain(drift: CardDrift): string[] {
     if (changes === 'gone') { lines.push(`${fact} — you subscribe to it, it is no longer announced`); continue; }
     for (const change of changes) lines.push(`${fact} — ${describe(change)} → re-sync and deploy the readers, THEN the sender`);
   }
+
   return lines;
 }
 

package/src/wire/http-error.ts

@@ -40,6 +40,7 @@ export function toPublicError(err: FougereError): ReturnType<FougereError['toJSO
   if (err.code !== ErrorCode.INTERNAL_ERROR) return err.toJSON();
   const where = [err.entity, err.operation].filter(Boolean).join('.');
   log.error(`${where || 'internal'}: ${err.message}`, err.cause ?? err);
+
   return {
     code: ErrorCode.INTERNAL_ERROR,
     message: 'Internal error',
@@ -60,5 +61,6 @@ export function toHttpError(err: unknown): { status: number; body: ReturnType<Fo
     message: (err as { message?: string })?.message ?? 'Internal error',
     cause: err,
   });
+
   return { status: 500, body: toPublicError(framed) };
 }

package/src/wire/loggerMiddleware.ts

@@ -19,6 +19,7 @@ export function loggerMiddleware(logger: Logger): AppMiddleware {
       const result = await next();
       const ms = (performance.now() - start).toFixed(1);
       logger.info(`${ctx.entity}.${ctx.operation} (${ms}ms)`);
+
       return result;
     } catch (err) {
       const ms = (performance.now() - start).toFixed(1);