@fougere/app 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/boot.ts

@@ -1,98 +1,35 @@
 import { Role } from '@fougere/schema';
 import { Lifecycle } from '@fougere/schema';
-/**
- * Fougere server bootstrap — single entry point for an app's lifecycle,
- * whatever hosts it.
- *
- * Nothing here knows h3, Nitro, Vue or React: a boot reads `fougere.config.ts`,
- * scans fronds off the filesystem and hands back an `App`. That is why it lives
- * in `@fougere/app` rather than in one of the two adapters — the second host
- * would otherwise have copied it, and a copied boot drifts (the seeding loop
- * already did, `core/src/boot/seed.ts`).
- *
- * Default path (zero-config): fougere.config.ts declares `db: 'sqlite'` and
- * everything else; this module auto-resolves the storage handle, builds an
- * ormFactory, runs auto-DDL from the entities, and boots the app.
- *
- * Escape hatch: `configureFougere({ db, ormFactory })` can be called from the
- * host's own startup (a Nitro plugin, a Next instrumentation hook) if the user
- * wants a custom data layer — alternative driver, managed migrations, etc.
- */
+/** Fougere server bootstrap — single entry point for an app's lifecycle, whatever hosts it. */
 import { createApp, identityFromEnv, Logger, migrating, seeding } from '@fougere/core';
 import { scanProject, loadCascadedConfig, setModuleLoader, frondAliases, resolveConventions } from '@fougere/core/node';
 import type { Extension } from '@fougere/core';
 import { createContainer } from '@fougere/container';
-import type { App, CreateAppOptions, EntityOrm, FougereConfig, Transport } from '@fougere/core';
+import { createMemoryStorage } from '@fougere/adapter-memory';
+import type { App, CreateAppOptions, Storage, FougereConfig, Transport } from '@fougere/core';
+import type { ResolvedStorage } from '@fougere/defaults';
 import { applyCreate, applyUpdate, type SchemaView } from '@fougere/schema';
 
 // ── Public types ─────────────────────────────────
 
 export interface FougereServerConfig {
-  /** Storage handle. Forwarded to the auth provider via AuthContext.db. */
-  db?: unknown;
-  /** Per-entity ORM factory. */
-  ormFactory?: (entity: SchemaView, name: string) => EntityOrm;
   /**
-   * What this app takes on beyond its fronds, each stating what it does and what it undoes.
-   *
-   * It replaced `afterBoot`, which a host used to CLAIM the whole post-boot to get its own
-   * seeding — Nuxt's generated plugin did exactly that, and its copy of the seeding loop
-   * drifted. Declaring `{ name: 'seeds', up }` replaces that one member and leaves the
-   * rest of the ascent alone.
+   * The whole data layer, as `resolveStorage` composed it — where the rows are, which source
+   * transacts, what to close. Handed over as ONE subject: a host that passed the factory alone
+   * lost the transaction and the connection's owner, and nothing said so.
    */
+  storage?: ResolvedStorage;
+  /** What this app takes on beyond its fronds, each stating what it does and what it undoes. */
   extensions?: CreateAppOptions['extensions'];
-  /**
-   * What the boot line names as the host — 'Nuxt/Nitro', 'Next'. Stated by the
-   * adapter, never sniffed: a boot that guesses its host from what happens to be
-   * importable is the hidden runtime the doctrine refuses.
-   */
+  /** What the boot line names as the host — 'Nuxt/Nitro', 'Next'. */
   host?: string;
-  /**
-   * What this app is built from, when the host already knows.
-   *
-   * Absent, `boot()` reads the fronds off the disk — right on a server, impossible on a
-   * runtime that has none: measured on workerd, `readdir` throws through unenv's shim and
-   * the app comes up with ZERO fronds, so every page renders and every door answers
-   * NOT_FOUND. A host that scanned at BUILD time can say so instead, and `fougere build`
-   * writes exactly this value down.
-   *
-   * Same slot as `CreateAppOptions.scan` and for the same reason: producing the value
-   * reads a disk, consuming it does not.
-   */
+  /** What this app is built from, when the host already knows. */
   scan?: CreateAppOptions['scan'];
-  /**
-   * What this app STATES it hosts — `frond('blog', { entities: [Post] })`.
-   *
-   * Stating this and no `scan` is how a host stops scanning at boot: nothing reads a
-   * disk, nothing loads `typescript`, and what was not named does not exist. It is the
-   * one door Next, Vite, React, Svelte and a bare Express share — none of them scans on
-   * its own, they all arrive here, and this line used to end in a scan for every one.
-   */
+  /** What this app STATES it hosts — `frond('blog', { entities: [Post] })`. */
   fronds?: CreateAppOptions['fronds'];
-  /**
-   * What `fougere.config.ts` says, when the host already read it.
-   *
-   * The same rule as `scan`, and found the same way: `boot()` re-reads the file at
-   * runtime, which a Worker cannot do — measured, a consumer's `remotes:` never reached
-   * the boot and its pages rendered empty with nothing said. A host that read the config
-   * at BUILD time states it here instead.
-   *
-   * `auth` is deliberately not part of what a codegen'd host can carry: it holds a live
-   * provider, not a value. An app that authenticates reads its own config.
-   */
+  /** What `fougere.config.ts` says, when the host already read it. */
   config?: Partial<FougereConfig>;
-  /**
-   * Who performs an outgoing call, when the default cannot.
-   *
-   * `boot()` builds an HTTP transport from `remotes:` and that is right nearly
-   * everywhere. It is not right on Cloudflare: a Worker calling a sibling's public URL
-   * is refused by the edge with error 1042, so two Workers of one account reach each
-   * other through a SERVICE BINDING and through nothing else. A binding is a value only
-   * the host holds, so only the host can state this.
-   *
-   * It replaces the default entirely — signing included, since a host that builds its
-   * own transport is the one that knows what to put on the wire.
-   */
+  /** Who performs an outgoing call, when the default cannot. */
   remoteTransport?: (url: string) => Transport;
 }
 
@@ -112,15 +49,7 @@ export function configureFougere(config: FougereServerConfig) {
   _appPromise = null;
 }
 
-/**
- * Add to what is already stated, instead of replacing it.
- *
- * A host states its app in PIECES when the pieces are known at different moments: a
- * build writes the scan and the config into a generated plugin, and a value only the
- * running process holds — a Cloudflare service binding — cannot be written there at all.
- * Its dual is `configureFougere`, which replaces; `reloadFougere` depends on that
- * replacement, so merging silently would have broken the turn of the ring.
- */
+/** Add to what is already stated, instead of replacing it. */
 export function extendFougere(config: Partial<FougereServerConfig>) {
   _config = { ..._config, ...config };
   _appPromise = null;
@@ -134,22 +63,7 @@ export function useFougereApp(): Promise<App> {
   return _appPromise;
 }
 
-/**
- * Turn the ring: instantiate the app again, then let the previous one go.
- *
- * This is what "reload" means for anything the config CONSUMED — a value that built
- * something cannot move under what it built, so the thing is built again. Its dual is
- * `applyConfig`, for values that are merely consulted and need no turn at all.
- *
- * Every door reaches the app through `useFougereApp()` inside the request it serves and
- * none holds it across two, which is what makes the swap invisible: the next request
- * lands on the new app whether or not the old one has finished being released.
- *
- * A call already running finishes on the OLD app: it is drained before being released,
- * so nothing has its storage closed underneath it. `timeoutMs` bounds that wait, and a
- * drain that runs out REJECTS — the app is left alone rather than released under work,
- * because a caller who cannot wait must choose that on purpose.
- */
+/** Turn the ring. */
 export async function reloadFougere(timeoutMs?: number): Promise<App> {
   const previous = _appPromise;
   _appPromise = null;
@@ -208,32 +122,16 @@ async function boot(): Promise<App> {
   // Auto-resolve the data layer from config.db when the user didn't provide a
   // custom one via configureFougere. The resolution itself lives in @fougere/defaults
   // — this host must not know which storage package backs `db:`.
-  let db = _config.db;
-  let ormFactory = _config.ormFactory;
-  // The storage's two halves, kept together: its ascent is an extension, its connection
-  // is not — it is opened here, before the container, so it closes after the container.
-  let storageMigrate: Extension['up'] | undefined;
-  let closeStorage: (() => Promise<void>) | undefined;
-  // Where the rows are, and how to open a transaction there — read from the same storage
-  // resolution, because a frame's realization is decided by `sources:` and nothing else.
-  let sourceOf: ((entityName: string) => string) | undefined;
-  let transacted: CreateAppOptions['transacted'];
-  if (!ormFactory) {
+  let storage = _config.storage;
+  if (!storage) {
     const { resolveStorage } = await import('@fougere/defaults');
-    const storage = resolveStorage(fileConfig.db as never, (fileConfig as { sources?: unknown }).sources as never);
-    if (storage.ormFactory) {
-      log.debug('auto-resolving storage from config.db');
-      db = storage.db;
-      ormFactory = storage.ormFactory;
-      sourceOf = storage.sourceOf;
-      transacted = storage.transacted as never;
-      storageMigrate = storage.migrate;
-      closeStorage = storage.close;
-    } else {
-      log.debug('no db declared — falling back to in-memory ORM');
-      ormFactory = createMemoryOrm;
-    }
+    storage = resolveStorage(fileConfig.db as never, (fileConfig as { sources?: unknown }).sources as never);
+    log.debug(storage.storageFactory ? 'auto-resolving storage from config.db' : 'no db declared — falling back to in-memory storage');
   }
+  // The storage's two halves, kept together: its ascent is an extension, its connection
+  // is not — it is opened here, before the container, so it closes after the container.
+  const storageFactory = storage.storageFactory ?? createMemoryStorage;
+  const storageMigrate: Extension['up'] | undefined = storage.migrate;
 
   // Layer-2 wiring: `remotes: { catalog: 'http://...' }` in fougere.config.ts
   // is all the user writes — the default transport comes from here.
@@ -265,19 +163,16 @@ async function boot(): Promise<App> {
       ? { scan: await scanProject(root, undefined, conventions) }
       : {}),
     createContainer,
-    ormFactory,
-    sourceOf,
-    transacted,
-    db,
+    storageFactory,
+    sourceOf: storage.sourceOf,
+    transacts: storage.transacts,
+    transacted: storage.transacted as never,
+    db: storage.db,
     auth: fileConfig.auth,
     adapters: fileConfig.adapters,
     remotes: fileConfig.remotes,
     remoteTransport,
-    /**
-     * The whole ascent, one ordered list: tables, then rows, then what the host adds.
-     * A host wanting its OWN seeding declares `{ name: 'seeds', … }` and replaces that
-     * member — it no longer has to claim everything after the boot to get it.
-     */
+    /** The whole ascent, one ordered list. */
     extensions: [
       // The slot is declared even when this host resolved no storage — a host that resolved
       // its own (the Nitro plugin does, for its bundler) then REPLACES this member in place
@@ -289,7 +184,7 @@ async function boot(): Promise<App> {
     // Opened before the container, so released after it. Never wired here until now:
     // this host boots the storage and no host closed one, which is what made a reload
     // leak the pool of every app it discarded.
-    onDispose: closeStorage,
+    onDispose: storage.close,
   });
 
   log.info(`ascent: ${app.extensions().join(' → ') || 'nothing declared'}`);
@@ -300,127 +195,3 @@ async function boot(): Promise<App> {
   return app;
 }
 
-// ── Fallback ORM ─────────────────────────────────
-
-/**
- * The store an app with no `db` runs on.
- *
- * It used to ignore both its arguments — `(_entity, _name)` — so it forced the field
- * name `id`, minted a uuid whatever the entity declared, and realized none of the
- * lifecycle rules: `created()` stamped nothing, a declared default stayed absent. The
- * same page therefore behaved one way here and another way on SQLite.
- *
- * It reads the axes now, through the one realization every storage shares.
- */
-export function createMemoryOrm(entity: SchemaView, name: string): EntityOrm {
-  const fields = entity.getFields();
-  const pk = Object.entries(fields).find(([, field]) => Role.of(field).isPrimary)?.[0] ?? 'id';
-  const store = new Map<string, Record<string, unknown>>();
-  // `EntityOrm.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.
-  const keyOf = (value: unknown) => String(value);
-  // Same contract as SQL: a criterion may name a SET, and an empty set matches nothing.
-  const matches = (row: Record<string, unknown>, criteria: Record<string, unknown>) =>
-    Object.entries(criteria).every(([key, value]) => Array.isArray(value)
-      ? value.some((v) => Object.is(row[key], v))
-      : Object.is(row[key], value));
-  return {
-    client: store,
-    async list(options?: any) {
-      let items = [...store.values()];
-      if (options?.where) items = items.filter((row) => matches(row, options.where));
-      // 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 — every row 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);
-      const result = items as any;
-      result.hasMore = hasMore;
-      result.endCursor = items.length > 0 ? String((items[items.length - 1] as any)[pk] ?? '') : undefined;
-      if (options?.count) result.total = matching;
-      return result;
-    },
-    async findById(id: string) { return store.get(keyOf(id)); },
-    async findBy(criteria: Record<string, unknown>) {
-      return [...store.values()].find((row) => matches(row, criteria));
-    },
-    async findAllBy(criteria: Record<string, unknown>) {
-      return [...store.values()].filter((row) => matches(row, criteria));
-    },
-    // Same contract as SQL: a map keyed by the primary key, a miss being an absent key.
-    async findByKeys(ids: readonly string[]) {
-      const found = new Map<string, Record<string, unknown>>();
-      for (const id of ids) {
-        const row = store.get(keyOf(id));
-        if (row) found.set(String(id), row);
-      }
-      return found;
-    },
-    // The dual, same contract as SQL: grouped by the value read off the ROW.
-    async findAllByKeys(field: string, keys: readonly string[]) {
-      const grouped = new Map<string, Record<string, unknown>[]>();
-      if (keys.length === 0) return grouped;
-      const wanted = new Set(keys.map(String));
-      for (const row of store.values()) {
-        const key = String(row[field]);
-        if (!wanted.has(key)) continue;
-        const held = grouped.get(key);
-        if (held) held.push(row); else grouped.set(key, [row]);
-      }
-      return grouped;
-    },
-    // Same contract as SQL: the key and the creation stamps survive an overwrite.
-    async upsert(input: Partial<Record<string, unknown>>) {
-      const record = applyCreate(fields, applyUpdate(fields, input));
-      const id = record[pk] as string | undefined;
-      if (id === undefined) throw new Error(`${name}.upsert(): no \`${pk}\` — an upsert needs the key it writes at.`);
-      const held = store.get(keyOf(id));
-      if (held) {
-        for (const [key, field] of Object.entries(fields)) {
-          if (key === pk || Lifecycle.of(field).stampedOnce) record[key] = held[key];
-        }
-      }
-      store.set(keyOf(id), record);
-      return record;
-    },
-    async upsertAll(inputs: readonly Partial<Record<string, unknown>>[]) {
-      for (const input of inputs) await (this as any).upsert(input);
-      return inputs.length;
-    },
-    async create(input: Partial<Record<string, unknown>>) {
-      const record = applyCreate(fields, input);
-      const id = record[pk] as string | undefined;
-      // `primary(text())` declares no generator, so nothing fills the hole and the
-      // caller has to. Keying on `undefined` would let the second create overwrite the
-      // first, in silence — the old version hid this by inventing an `id` field the
-      // entity never declared.
-      if (id === undefined) {
-        throw new Error(`${name}.create: '${pk}' is the primary key and nothing supplied it — this entity declares no generator for it.`);
-      }
-      // A create is not an upsert. `Map.set` overwrites, so a second create under the
-      // same key answered "created" while destroying the previous row — SQL answers a
-      // constraint violation, and a store that loses data silently is worse than one
-      // that fails.
-      if (store.has(keyOf(id))) {
-        throw new Error(`${name}.create: '${pk}' ${JSON.stringify(id)} already exists.`);
-      }
-      store.set(keyOf(id), record);
-      return record;
-    },
-    async update(id: string, input: Partial<Record<string, unknown>>) {
-      const existing = store.get(keyOf(id));
-      if (!existing) throw new Error(`Not found: ${id}`);
-      const updated = { ...existing, ...applyUpdate(fields, input), [pk]: existing[pk] };
-      store.set(keyOf(id), updated);
-      return updated;
-    },
-    async delete(id: string) { return store.delete(keyOf(id)); },
-    output(_schema: SchemaView) { return this; },
-  };
-}

package/src/client.ts

@@ -1,17 +1,6 @@
 /**
- * The couple, minus the reactivity — everything `useQuery`/`useCommand` decide
- * before a framework's state primitives get involved.
- *
- * Designation is class + verb: the imported entity class carries the metadata,
- * its name carries the registration key. That is true in Vue and in React, and so
- * is the link — a successful command on an entity revalidates every mounted query
- * on that entity, because the entity is designated on both sides and nothing has
- * to be declared. What differs between hosts is only HOW a value becomes reactive
- * and how a revalidation is triggered, which is ~50 lines each and belongs to them.
- *
- * Browser-safe by construction: this module reaches `@fougere/core/contract` and
- * the transport's client subpath, never the boot. `@fougere/app/client` is the
- * subpath that keeps it that way.
+ * The couple, minus the reactivity — everything `useQuery`/`useCommand` decide before a
+ * framework's state primitives get involved.
  */
 import {
   FougereError,
@@ -26,7 +15,7 @@ import { frameCall, unframeResponse, type RpcResponse } from '@fougere/transport
 export type EntityClass = { name: string };
 
 /** What a page provides of an invocation — the rest is stamped server-side. */
-export type CallInput = Partial<Pick<InvocationContext, 'params' | 'query' | 'body'>>;
+export type CallInput = Partial<Pick<InvocationContext, 'params' | 'query' | 'input'>>;
 
 /** The one door the browser knows. A named surface adds `/{surface}` to it. */
 export const CALL_ENDPOINT = '/_fougere/call';
@@ -45,14 +34,10 @@ export function callOf(entity: EntityClass, op: string): FrondCall {
 }
 
 export function invocationOf(input?: CallInput): InvocationContext {
-  return { params: {}, query: {}, body: undefined, state: {}, ...input };
+  return { params: {}, query: {}, input: undefined, state: {}, ...input };
 }
 
-/**
- * The cache key of a read. Same designation and same input means the same key —
- * which is what lets two components asking the same thing share one request, and
- * what the command side matches against to revalidate.
- */
+/** The cache key of a read. */
 export function queryKeyOf(entityKey: string, op: string, input?: CallInput): string {
   return `fougere:${entityKey}.${op}:${JSON.stringify(input ?? {})}`;
 }
@@ -88,14 +73,7 @@ export function mountedKeys(entityKey: string): string[] {
   return [...(mounted.get(entityKey) ?? [])];
 }
 
-/**
- * `mountedKeys` says WHICH reads a command invalidates; these say how to make one
- * happen. Both halves turned out to be host-independent — Nuxt is the exception,
- * because `refreshNuxtData` already is this registry.
- *
- * They lived in `@fougere/react` until a second non-Nuxt client needed them, which
- * is when it became visible that nothing in them is React.
- */
+/** `mountedKeys` says WHICH reads a command invalidates; these say how to make one happen. */
 const refetchers = new Map<string, Set<() => void>>();
 
 /** Register a mounted read's refetch. Returns the unregistration. */
@@ -135,11 +113,7 @@ export function pageOf(data: unknown): { total?: number; hasMore?: boolean; endC
   return (data ?? {}) as { total?: number; hasMore?: boolean; endCursor?: string };
 }
 
-/**
- * Whatever failed, as the error the primitives promise. A transport failure is not
- * a domain refusal, so it arrives under SERVICE_UNAVAILABLE rather than borrowing a
- * code the server never sent.
- */
+/** Whatever failed, as the error the primitives promise. */
 export function asFougereError(err: unknown, entityKey: string, op: string): FougereError {
   return err instanceof FougereError
     ? err

package/src/express.ts

@@ -1,35 +1,4 @@
-/**
- * The doors as Express middlewares — the form an Express app expects.
- *
- * ```ts
- * const app = express();
- * app.use(express.json());
- * app.use(fougere());          // ← one line, like cors() or express.json()
- * ```
- *
- * This replaces an earlier `mountDoors(createExpressRouter(app))`, which was wrong in
- * two ways at once. It handed the app INTO a function instead of adding something to
- * the app, and it made the caller name Express 5's wildcard syntax (`/api/*splat`) —
- * a detail that belongs to the framework, not to its user. Worse, it mounted all
- * three doors together with no way to take two of them.
- *
- * A middleware fixes both by construction, because Express already says WHERE:
- *
- * ```ts
- * app.use(fougere());                 // the three doors, at the paths the client knows
- * app.use('/admin', fougereRest());   // REST only, wherever you want it
- * ```
- *
- * And `next()` is the passthrough these doors were already imitating: `serveRest`
- * answers `{ kind: 'pass' }` for a path it does not serve, which is exactly what
- * Express means by calling the next handler. The middleware stops inventing it.
- *
- * The names mirror `@fougere/app/web` on purpose — same doors, host-shaped. `/web`
- * gives you `Request` → `Response` handlers; this gives you middlewares.
- *
- * Nothing here imports express: the shapes are structural, so the package keeps its
- * dependency list and a test can hand it a plain object.
- */
+/** The doors as Express middlewares — the form an Express app expects. */
 import { readExpressBody } from '@fougere/http';
 import { serveRest, serveRpc, rpcParseError } from './serve.js';
 import { serveGraphQL } from './graphql.js';
@@ -59,14 +28,7 @@ interface ExpressResponse {
 type Next = (err?: unknown) => void;
 export type ExpressMiddleware = (req: any, res: any, next: Next) => void;
 
-/**
- * Who the caller is, from what ran before.
- *
- * Express has no ambient request, so an app that resolves its own session says so by
- * putting it on the request — `req.fougereState`, or a bare `req.user`, which is what
- * passport and most middlewares already set. Nothing is taken from the payload: the
- * browser sits outside the topology.
- */
+/** Who the caller is, from what ran before. */
 function stateOf(req: ExpressRequest): Record<string, unknown> {
   if (req.fougereState) return req.fougereState;
   return req.user ? { user: req.user } : {};
@@ -95,12 +57,7 @@ function fail(res: ExpressResponse, next: Next, err: unknown): void {
   next(err);
 }
 
-/**
- * The call envelope, at `/_fougere/call` — the door the browser primitives use.
- *
- * Mounted with `app.use()`, Express strips nothing, so the path still carries the
- * audience segment (`/_fougere/call/public`) that `surfaceOf` reads.
- */
+/** The call envelope, at `/_fougere/call` — the door the browser primitives use. */
 export function fougereCall(mountPath = '/_fougere/call'): ExpressMiddleware {
   return (req, res, next) => {
     const path = pathOf(req);
@@ -132,12 +89,7 @@ export function fougereSession(mountPath = '/_fougere/session'): ExpressMiddlewa
   };
 }
 
-/**
- * The REST projection, under `/api` by default.
- *
- * A path this app does not serve calls `next()` — so an app's own `/api/health` keeps
- * answering whether it was registered before or after this middleware.
- */
+/** The REST projection, under `/api` by default. */
 export function fougereRest(mountPath = '/api'): ExpressMiddleware {
   return (req, res, next) => {
     const path = pathOf(req);