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

package/src/StatedModules.ts

@@ -3,13 +3,17 @@
  * of your own. Reading one means importing it, which is why this lives on the node entry and
  * never on the one a Worker runs.
  *
- * What a module hands back decides where it goes: a shape stating `up` or `down` is an
+ * What a module hands back decides where it goes: a shape stating `up`, `down` or `state` is an
  * extension and rises with the app, anything else is a frond and is installed like the rest.
  * The author of a config does not have to know which one their package exports — the same
  * reading `extensions/` already does off a module's form.
+ *
+ * A frond the config BUILT in place — `auth: betterAuth({ … })` — is handed over the same way,
+ * with nothing to import: the config file already did.
  */
 import type { Extension } from './boot/Extension.js';
 import type { FrondDescriptor } from './descriptor/FrondDescriptor.js';
+import { isExtension } from './descriptor/ExtensionEntry.js';
 import { statesModule, type FrondsStated } from './FrondsStated.js';
 import { statedFronds } from './StatedFrond.js';
 import { getModuleLoader } from './loader.js';
@@ -21,13 +25,7 @@ function exportedBy(specifier: string): string {
   return last.replace(/\.[cm]?[jt]s$/, '');
 }
 
-function rises(built: unknown): built is Extension {
-  const shape = built as { up?: unknown; down?: unknown } | null;
-
-  return typeof shape?.up === 'function' || typeof shape?.down === 'function';
-}
-
-/** What a config's module keys hand over, sorted by what each one turned out to be. */
+/** What a config hands over as code — its module keys and the fronds it built — sorted by what each one is. */
 export async function statedModules(
   stated: FrondsStated | undefined,
 ): Promise<{ fronds: FrondDescriptor[]; extensions: Extension[] }> {
@@ -36,6 +34,16 @@ export async function statedModules(
   const loader = getModuleLoader();
 
   for (const entry of statedFronds(stated)) {
+    if (entry.held) {
+      if (entry.held.name !== entry.key) {
+        throw new Error(
+          `Fougere config: the entry '${entry.path}' holds the frond '${entry.held.name}'. `
+          + `Name the entry '${entry.held.name}' — the key is how \`only:\` and an address find it.`,
+        );
+      }
+      fronds.push(entry.held);
+      continue;
+    }
     if (!statesModule(entry.key)) continue;
 
     const module = await loader(entry.key) as Record<string, unknown>;
@@ -50,7 +58,7 @@ export async function statedModules(
     }
 
     const built = (factory as (argument?: unknown) => unknown)(entry.value);
-    if (rises(built)) extensions.push(built);
+    if (isExtension(built)) extensions.push(built as Extension);
     else fronds.push(built as FrondDescriptor);
   }
 

package/src/boot/App.ts

@@ -3,10 +3,10 @@ import type { Fronds } from '../descriptor/Fronds.js';
 import type { SchemaView } from '@fougere/schema';
 import type { AppMiddleware } from '../wire/AppMiddleware.js';
 import type { RpcAnswer } from '../wire/RpcAnswer.js';
-import type { AuthRuntime } from './AuthRuntime.js';
 import type { EffectiveOperationsMap } from '../EffectiveOperationsMap.js';
 import type { DispatchObserver } from '../dispatch/DispatchObserver.js';
 import type { DispatchPort } from '../dispatch/DispatchPort.js';
+import type { Storage } from '../storage/Storage.js';
 
 /** The App object returned by createApp(). */
 export interface App extends DispatchPort {
@@ -42,7 +42,7 @@ export interface App extends DispatchPort {
    * The storage an entity is backed by, resolved through its owning frond's scope — the dual of
    * {@link facadeFor}.
    */
-  storageFor(entity: string): unknown | undefined;
+  storageFor<T = Record<string, unknown>>(entity: string): Storage<T> | undefined;
   /** The presenter of an entity, resolved through its owning frond's scope. */
   presenterFor(entity: string): unknown | undefined;
   /** Dispose the root container. */
@@ -66,6 +66,4 @@ export interface App extends DispatchPort {
   use(middleware: AppMiddleware): void;
   /** Register an app middleware scoped to a specific entity. */
   use(entity: string, middleware: AppMiddleware): void;
-  /** Auth runtime, present when fougere.config.ts declares `auth`. */
-  auth?: AuthRuntime;
 }

package/src/boot/AppLifecycle.ts

@@ -1,5 +1,6 @@
 import type { App } from './App.js';
 import type { Extension } from './Extension.js';
+import { StateShape } from '../wire/StateShape.js';
 
 /** Runs application extensions up in order and down in reverse order. */
 export class AppLifecycle {
@@ -20,23 +21,39 @@ export class AppLifecycle {
     return this.members.map((extension) => extension.name);
   }
 
+  /** Read off the members that stay, so an extension replaced by name declares nothing. */
+  state(): StateShape {
+    return StateShape.of(this.members);
+  }
+
   async up(app: App): Promise<void> {
     for (const extension of this.members) await extension.up?.(app);
   }
 
   async down(app: App): Promise<void> {
-    const refused: unknown[] = [];
-    for (const extension of [...this.members].reverse()) {
-      try {
-        await extension.down?.(app);
-      } catch (error) {
-        refused.push(error);
-      }
-    }
-    if (refused.length > 0) {
-      throw new AggregateError(refused, `${refused.length} extension(s) refused to release`);
+    await closeAll(
+      [...this.members].reverse().map((extension) => () => extension.down?.(app)),
+      'extension(s) refused to release',
+    );
+  }
+}
+
+/**
+ * Every level told to close even when one refuses, the refusals leaving together in one
+ * `AggregateError` — one already carried by a level is flattened into the list.
+ */
+export async function closeAll(levels: readonly (() => unknown)[], refusals: string): Promise<void> {
+  const refused: unknown[] = [];
+  for (const level of levels) {
+    try {
+      await level();
+    } catch (error) {
+      if (error instanceof AggregateError) refused.push(...error.errors);
+      else refused.push(error);
     }
   }
+
+  if (refused.length > 0) throw new AggregateError(refused, `${refused.length} ${refusals}`);
 }
 
 /** The replaceable migration slot of the application lifecycle. */

package/src/boot/AuthRuntime.ts

@@ -1,19 +1,12 @@
-import type { SchemaView } from '@fougere/schema';
-import type { Storage } from '../storage/Storage.js';
-
-/**
- * Runtime returned by an auth provider's create(config, ctx) function.
- * The core mounts this on the App and the HTTP layer (Nuxt module / router) uses it.
- */
+/** What an auth extension registers under {@link AUTH} once it has risen. */
 export interface AuthRuntime {
-  /** Entities used by the provider, including any defaults it filled in. */
-  entities: Record<string, SchemaView>;
-  /** Per-entity ORMs the provider built for itself. */
-  storages: Record<string, Storage>;
-  /** Web Standard handler that processes /auth/* requests. */
+  /** Web Standard handler that processes `/auth/*` requests. */
   handler: (request: Request) => Promise<Response>;
   /** Programmatic API exposed by the provider (getSession, signOut, ...). */
   api: Record<string, unknown>;
-  /** Effective mount path (echoes config.basePath or the provider's default). */
+  /** Effective mount path. */
   basePath: string;
 }
+
+/** The container key an auth provider registers its runtime under. */
+export const AUTH = 'AuthRuntime';

package/src/boot/CreateAppOptions.ts

@@ -6,8 +6,6 @@ import type { StorageFactory } from '../storage/StorageFactory.js';
 import type { Constraint } from '../Constraint.js';
 import type { Transport } from '../wire/Transport.js';
 import type { Extension } from './Extension.js';
-import type { AuthConfig } from './AuthConfig.js';
-import type { DispatchObserver } from '../dispatch/DispatchObserver.js';
 import type { App } from './App.js';
 
 /** Options for createApp(). */
@@ -86,13 +84,4 @@ export interface CreateAppOptions {
   adapters?: Record<string, boolean | undefined>;
   /** Carries an announced fact out of this process — a broker, a queue, a log. */
   onEmit?: (fact: string, payload: unknown) => void | Promise<void>;
-  /** Passive observers of every dispatch transition. */
-  dispatchObservers?: readonly DispatchObserver[];
-  /**
-   * Storage handle to expose to the auth provider via AuthContext.db.
-   * Required when `auth` is set.
-   */
-  db?: unknown;
-  /** Auth declaration to wire into the app at boot. */
-  auth?: AuthConfig;
 }

package/src/boot/Emissions.ts

@@ -1,4 +1,5 @@
 import { applyCreate, dotted, lowerFirst, type SchemaView } from '@fougere/schema';
+import { addressOf, facadeKeyOf } from '../wire/Facade.js';
 import type { Container } from '@fougere/container';
 import { validationErrorsOf } from '../wire/FougereError.js';
 import { awaitKeyOf, emitKeyOf, factsAnnouncedBy, factsAwaitedBy } from '../wire/Emit.js';
@@ -368,12 +369,7 @@ export class Emissions {
   }
 }
 
-/**
- * The container key a declared CLASS NAME answers under — `RedactHandler` → `redactHandler`,
- * the same key `facadeKeyOf` builds from an address.
- */
+/** The container key a declared CLASS NAME answers under — `RedactHandler` → `redactHandler`. */
 function facadeOf(declared: string): string {
-  const key = lowerFirst(declared);
-
-  return key.endsWith('Handler') ? key : `${key}Handler`;
+  return facadeKeyOf(addressOf(declared));
 }

package/src/boot/Extension.ts

@@ -1,4 +1,5 @@
 import type { App } from './App.js';
+import type { Field } from '@fougere/schema';
 import type { FrondDescriptor } from '../descriptor/FrondDescriptor.js';
 
 /**
@@ -15,6 +16,11 @@ export interface Extension {
    * signature is the only way to ask for one.
    */
   fronds?: readonly FrondDescriptor[];
+  /**
+   * The members it puts on a call's `state` — `{ user: json(User) }`. A member nobody declares
+   * is refused at the facade, and one declared twice refuses the boot.
+   */
+  state?: Readonly<Record<string, Field>>;
   up?(app: App): void | Promise<void>;
   down?(app: App): void | Promise<void>;
 }

package/src/boot/Hosting.ts

@@ -2,6 +2,7 @@ import type { SchemaView } from '@fougere/schema';
 import type { Constraint } from '../Constraint.js';
 import type { Peer } from './Peer.js';
 import type { Journal } from '../dispatch/Journal.js';
+import type { Storage } from '../storage/Storage.js';
 
 /**
  * Where an entity's rows are hosted, and what the host keeps — what a `ref()` asks the boot.
@@ -17,7 +18,7 @@ export interface Hosting {
    * Resolved through the frond that owns it, never the asking frond's scope: a scope sees its
    * parent and not its siblings, so a target of another frond was answered by nothing.
    */
-  storageOf(entity: string): unknown | undefined;
+  storageOf(entity: string): Storage | undefined;
   /** Every entity of every frond — a row is named from wherever its namer was declared. */
   entities(): ReadonlyMap<string, SchemaView>;
   /**