@fougere/core 0.3.0-alpha.0 → 0.4.0-alpha.0

package/src/boot/binding.ts

@@ -0,0 +1,182 @@
+/**
+ * Where each parameter of an operation gets its value — decided once at boot from the
+ * parsed signature, replayed per call by `resolveArgs`.
+ *
+ * The branches are ORDERED and each states why it sits where it does; the list used to
+ * be repeated here too, and it had already lost `Fact` — the one whose position is
+ * load-bearing, since the fall-through would otherwise hand it the caller's body.
+ */
+import type { ParsedParam } from '../scan/handler-parser.js';
+import type { InvocationContext } from '../wire/invocation.js';
+import { lowerFirst } from '@fougere/schema';
+
+// ── Types ─────────────────────────────────────
+
+type ParamSource =
+  | { kind: 'collector'; typeName: string }
+  /**
+   * `Fact<PostPublished>` — something that happened, not something a caller typed.
+   *
+   * It resolves from the body exactly like `body` does, and that is deliberate: an
+   * emission and a direct call ARE the same call, so a subscriber cannot tell them apart
+   * and does not need to. The branch exists so the PLAN says what this parameter is —
+   * that sentence is what makes the subscriber index readable without reparsing types.
+   */
+  | { kind: 'fact'; factName: string }
+  | { kind: 'param'; name: string; coerce?: 'number' | 'boolean' }
+  | { kind: 'body' }
+  | { kind: 'context' }
+  /** The whole query bag, for an op whose argument IS the options (list). */
+  | { kind: 'query' };
+
+interface ParamBinding {
+  name: string;
+  source: ParamSource;
+  optional: boolean;
+}
+
+export type BindingPlan = ParamBinding[];
+
+// ── Primitives ────────────────────────────────
+
+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;
+}
+
+// ── Compute ───────────────────────────────────
+
+/**
+ * Build a BindingPlan from parsed method params.
+ *
+ * @param params - Parsed parameter list from AST
+ * @param collectorTypeNames - Registration keys of the types a Collector answers for
+ */
+export function computeBindingPlan(
+  params: ParsedParam[],
+  collectorTypeNames: Set<string>,
+): BindingPlan {
+  return params.map((param) => {
+    const typeName = param.type.name;
+    // `lowerFirst`, never `toLowerCase()`: the collector set is keyed the way the
+    // scan spells it, and the two agree on one word only — `AuthorUser` looked up as
+    // `authoruser` missed `authorUser` and fell through to branch 4, the request body.
+    const typeKey = lowerFirst(typeName);
+
+    // 0. Fact — `Fact<X>` names itself, so nothing has to be known in advance. It comes
+    //    FIRST because branch 4 would otherwise hand it the caller's body under the name
+    //    of something that happened.
+    const factOf = param.type.name === 'Fact' ? param.type.generics?.[0]?.name : undefined;
+    if (factOf) {
+      return {
+        name: param.name,
+        source: { kind: 'fact' as const, factName: lowerFirst(factOf) },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 1. Collector — param type matches a type some collector answers for
+    if (collectorTypeNames.has(typeKey)) {
+      return {
+        name: param.name,
+        source: { kind: 'collector' as const, typeName: typeKey },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 2. InvocationContext — inject the full context
+    if (typeName === 'InvocationContext') {
+      return {
+        name: param.name,
+        source: { kind: 'context' as const },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 3. Primitives — matched by name from params > query
+    if (PRIMITIVES.has(typeName)) {
+      return {
+        name: param.name,
+        source: {
+          kind: 'param' as const,
+          name: param.name,
+          coerce: coercionFor(typeName),
+        },
+        optional: param.optional ?? false,
+      };
+    }
+
+    // 4. Everything else — body
+    return {
+      name: param.name,
+      source: { kind: 'body' as const },
+      optional: param.optional ?? false,
+    };
+  });
+}
+
+// ── Resolve ───────────────────────────────────
+
+export interface CollectorResolver {
+  collect(ctx: InvocationContext): Promise<unknown>;
+}
+
+/**
+ * Resolve handler arguments from a BindingPlan + InvocationContext.
+ */
+export async function resolveArgs(
+  plan: BindingPlan,
+  ctx: InvocationContext,
+  resolveCollector?: (typeName: string) => CollectorResolver | undefined,
+): Promise<unknown[]> {
+  const args: unknown[] = [];
+
+  for (const binding of plan) {
+    switch (binding.source.kind) {
+      case 'collector': {
+        const collector = resolveCollector?.(binding.source.typeName);
+        args.push(collector ? await collector.collect(ctx) : undefined);
+        break;
+      }
+      case 'context': {
+        args.push(ctx);
+        break;
+      }
+      case 'param': {
+        // `null` is a value, not a miss. Nullish coalescing used to make an explicit
+        // nullable path/GraphQL argument fall through to query (or become undefined),
+        // collapsing `T | null` into `T | undefined`. Only undefined means absent.
+        const fromParams = ctx.params[binding.source.name];
+        let val: unknown = fromParams === undefined
+          ? ctx.query[binding.source.name]
+          : fromParams;
+        if (val != null && binding.source.coerce === 'number') val = Number(val);
+        if (val != null && binding.source.coerce === 'boolean') val = val === 'true' || val === '1' || val === true;
+        args.push(val);
+        break;
+      }
+      case 'fact': {
+        // A fact IS the payload — the whole of what happened, never a piece of it.
+        // Identical to `body` today, and deliberately not sharing its branch: the two
+        // agree by coincidence, not by rule, and the day `body` learns to look up a
+        // value by parameter name a subscriber would receive ONE FIELD of the fact it
+        // subscribed to. Splitting it costs nothing and removes that trap.
+        args.push(ctx.body);
+        break;
+      }
+      case 'body': {
+        args.push(ctx.body);
+        break;
+      }
+      case 'query': {
+        args.push(ctx.query);
+        break;
+      }
+    }
+  }
+
+  return args;
+}

package/src/boot/boot.ts

@@ -0,0 +1,125 @@
+import { createApp } from './bootstrap.js';
+import { seeding } from './seed.js';
+import { scanProject } from '../scan/scanner.js';
+import { loadConfig, type FougereConfig } from '../config-loader.js';
+import { Logger } from '../builtins/logger.js';
+import { applyConfig } from './apply.js';
+import type { App, CreateAppOptions } from './types.js';
+import { migrating, type Extension } from './AppLifecycle.js';
+import type { Transport } from '../wire/call.js';
+import type { Container } from '@fougere/container';
+
+interface BootOptions {
+  /** Project root. Defaults to process.cwd(). */
+  root?: string;
+  /** Override config (merged with fougere.config.ts). */
+  config?: Partial<FougereConfig>;
+  /** Container factory. Required. */
+  createContainer: () => Container;
+  /** Only boot these fronds (by name). Absent = all. */
+  fronds?: string[];
+  /**
+   * Remote fronds — label → address. A declared remote wins over local
+   * presence (the frond runs elsewhere). Requires `remoteTransport`.
+   */
+  remotes?: Record<string, string>;
+  /** Builds the transport to reach `remotes`. Supplied by a layer-2 package. */
+  remoteTransport?: (url: string) => Transport;
+  /**
+   * Carries an announced fact out of this process. Forwarded rather than dropped: a
+   * caller handing one in has no other way to reach the emitter, and this path silently
+   * kept it to itself.
+   */
+  onEmit?: CreateAppOptions['onEmit'];
+  /**
+   * ORM setup — returns the storage handle (db), an ormFactory, and its two halves.
+   * The `db` value is forwarded to the auth provider via AuthContext when `auth` is set.
+   */
+  db?: (config: FougereConfig) => {
+    db?: unknown;
+    ormFactory: CreateAppOptions['ormFactory'];
+    /**
+     * Bring the schema up to date — an extension's `up`, because it runs after the
+     * container. It used to be called `afterBoot`, a word that also meant the host's
+     * post-boot and was read in four places under two senses.
+     */
+    migrate?: (app: App) => Promise<void> | void;
+    /** Closes what the factory opened — `boot()` called it, so `boot()` releases it. */
+    close?: () => Promise<void>;
+  };
+  /**
+   * What this app takes on beyond its fronds. Appended after the framework's own, so a
+   * host adds to the ascent — or replaces a member of it by declaring the same name.
+   */
+  extensions?: readonly (Extension | undefined)[];
+}
+
+/**
+ * Boot a Fougere app from fougere.config.ts.
+ *
+ * Handles: config loading, container creation, DB setup, seeding.
+ * Works for any surface (Nuxt, GraphQL standalone, CLI, tests).
+ */
+export async function boot(options: BootOptions): Promise<App> {
+  const bootStart = performance.now();
+  const log = new Logger('boot');
+
+  const root = options.root ?? process.cwd();
+  log.info(`root: ${root}`);
+
+  log.debug('loading config');
+  const fileConfig = await loadConfig(root);
+  const config: FougereConfig = { ...fileConfig, ...options.config };
+  // What this config changes in the process, said the same way at boot and at reload —
+  // there is one applier, and a host re-reading later calls the very same function.
+  applyConfig(config);
+  log.info('config loaded');
+
+  let dbSetup: ReturnType<NonNullable<BootOptions['db']>> | undefined;
+  if (options.db) {
+    log.debug('initializing database');
+    dbSetup = options.db(config);
+    log.info('database initialized');
+  }
+
+  log.debug('creating app (scan + container)');
+  const app = await createApp({
+    // boot() lives on the Node entry, so boot() is what reads the disk. `createApp` is
+    // handed the answer and reaches for nothing.
+    scan: await scanProject(root, options.fronds, config.conventions),
+    createContainer: options.createContainer,
+    ormFactory: dbSetup?.ormFactory,
+    db: dbSetup?.db,
+    auth: config.auth,
+    remotes: options.remotes,
+    ports: config.ports,
+    // Read from the config for the same reason `ports` is, one line up: it is a fact the
+    // project states, not one the caller passes. Absent here, `serveRest` and
+    // `serveGraphQL` both answered `pass` on an app whose config declared them — the
+    // hosts got it right through their own boot (`app/shared/src/boot.ts`), and this
+    // path, the conventional one, served nothing.
+    adapters: config.adapters,
+    // boot() called the factory, so boot() owns closing what it opened. Not an extension:
+    // it was opened before the container existed, so it closes after the container goes.
+    onDispose: dbSetup?.close,
+    /**
+     * The whole ascent, in one ordered list — tables, then rows, then whatever the host
+     * takes on. It was four call sites under the name `afterBoot`, two of which meant
+     * different things and one of which was generated into a Nitro plugin.
+     */
+    extensions: [
+      migrating(dbSetup?.migrate),
+      seeding((message) => log.debug(message)),
+      ...(options.extensions ?? []),
+    ],
+    onEmit: options.onEmit,
+    remoteTransport: options.remoteTransport,
+  });
+
+  log.info(`ascent: ${app.extensions().join(' → ') || 'nothing declared'}`);
+
+  const ms = (performance.now() - bootStart).toFixed(0);
+  log.info(`ready in ${ms}ms — ${app.fronds.length} frond(s)`);
+
+  return app;
+}