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

package/src/descriptor/frond.ts

@@ -1,195 +0,0 @@
-/**
- * What a frond is made of — one interface per convention directory.
- *
- * Documented: [the Frond](https://fougere.dev/docs/concepts/frond).
- */
-import type { SchemaView } from '@fougere/schema';
-import type { Param, OperationContract, OperationsMap } from '../wire/operation.js';
-import type { PresenterViews } from '../prefab/presenter.js';
-import type { Fronds } from './Fronds.js';
-
-/** A discovered provider — a class under `services/` or `repositories/`, injected by type. */
-export interface ProviderEntry {
-  /**
-   * The container key — the class name as the SOURCE spells it.
-   *
-   * Read at boot off `ctor.name` for a decade of no consequence, until a bundler lowered
-   * a `static readonly` field and renamed the declaration doing it: the provider
-   * registered as `_Communes` and the handler asking for `Communes` got a container miss.
-   * A name a tool may rewrite is written down, for the same reason `deps` is.
-   */
-  name?: string;
-  /** The class constructor (default export of the file). */
-  ctor: new (...args: never[]) => unknown;
-  /** Constructor dependency type names (from AST scan). */
-  deps: string[];
-  /** Absolute file path (for debugging). */
-  filePath: string;
-}
-
-/**
- * The key a provider answers under. What the source said, and the class's own name only
- * where nobody wrote it down — a statement is read as code, and code can say it.
- */
-export const nameOf = (provider: ProviderEntry): string => provider.name ?? provider.ctor.name;
-
-/** A discovered entity (Entity subclass in entities/ dir). */
-export interface EntityEntry {
-  /** Registration key: class name lowercased first char (e.g. 'product'). */
-  name: string;
-  /** The Entity class (has static getFields()). */
-  entityClass: SchemaView;
-  /** Absolute file path (for debugging). */
-  filePath: string;
-  /** Whether this entity is part of the frond's public contract. */
-  exposed?: boolean;
-}
-
-/** A discovered handler (controls what a service exposes). */
-export interface HandlerEntry {
-  /** Registration key (e.g. 'postHandler'). */
-  name: string;
-  /**
-   * The name this handler answers to — its class name minus `Handler`, lowercased (`PostHandler` →
-   * `post`).
-   */
-  address: string;
-  /** The handler class. */
-  ctor: new (...args: never[]) => unknown;
-  /** All operations with full signatures for binding. */
-  operations: OperationsMap;
-  /** Constructor dependency type names (from AST scan). */
-  deps: string[];
-  /** Absolute file path (for debugging). */
-  filePath: string;
-  /** Whether this handler is part of the frond's public contract. */
-  exposed?: boolean;
-  /** Output schema override — when Crud(Entity, Output), restricts storage output. */
-  outputOverride?: SchemaView;
-  /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
-  surface?: string;
-}
-
-/** Return type metadata for a presenter computed field. */
-export interface PresenterFieldMeta {
-  name: string;
-  /** Inferred return type name: 'string', 'number', 'boolean', or a class name. */
-  returnType?: string;
-  /** The field emits a LIST per row — `tags(posts: Post[]): string[][]`. */
-  list?: boolean;
-  /** Whether the return is nullable. */
-  nullable?: boolean;
-  /** The declared parameters AFTER the rows. */
-  params?: Param[];
-}
-
-/** A discovered presenter (computed fields for an entity's output). */
-export interface PresenterEntry {
-  /** Entity name this presenter enriches (e.g. 'post' from PostPresenter). */
-  entityName: string;
-  /** The presenter class. */
-  ctor: new (...args: never[]) => unknown;
-  /** Computed field names (method names on prototype). */
-  fields: string[];
-  /** Per-field type metadata (inferred from source via parser). */
-  fieldMeta: PresenterFieldMeta[];
-  /**
-   * The view each computed field emits, when the presenter declares one (`Presenter(Order, {
-   * items: [OrderItemView] })`).
-   */
-  views?: PresenterViews;
-  /** Constructor dependency type names (from AST scan). */
-  deps: string[];
-  /** Absolute file path (for debugging). */
-  filePath: string;
-}
-
-/** A discovered collector (resolves handler input params from invocation context). */
-export interface CollectorEntry {
-  /** Registration key of the TYPE this collector resolves — 'user', 'ability'. */
-  typeName: string;
-  /** The collector class. */
-  ctor: new (...args: never[]) => unknown;
-  /** Constructor dependency type names (from AST scan). */
-  deps: string[];
-  /** Absolute file path (for debugging). */
-  filePath: string;
-}
-
-/**
- * A discovered middleware — a class declaring `around(ctx, next)`, which runs before and
- * after every operation in its scope.
- */
-export interface MiddlewareEntry {
-  /** Class name — what `frond.config.ts` addresses to widen the scope. */
-  name: string;
-  /** The middleware class. */
-  ctor: new (...args: never[]) => unknown;
-  /** How far it reaches: its own frond's entities, or every operation in the process. */
-  scope: 'frond' | 'app';
-  /** Constructor dependency type names (from AST scan). */
-  deps: string[];
-  /** Absolute file path (for debugging). */
-  filePath: string;
-}
-
-/** A discovered seed file (array of records or async factory). */
-export interface SeedEntry {
-  /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
-  entityName: string;
-  /** Raw default export — array or function. Resolved at runtime. */
-  data: Record<string, unknown>[] | SeedFactory;
-  /** Absolute file path (for debugging). */
-  filePath: string;
-}
-
-/** Seed factory — receives a resolver to access handlers cross-frond. */
-export type SeedFactory = (resolve: <T>(name: string) => T) => Promise<Record<string, unknown>[]>;
-
-/** Where a frond lives on disk. */
-export interface FrondSource {
-  /** Absolute path to the frond directory. */
-  path: string;
-  /** The @fronds/{name} package name. Always present. */
-  package: string;
-}
-
-export interface FrondDescriptor {
-  name: string;
-  source: FrondSource;
-  providers: ProviderEntry[];
-  entities: EntityEntry[];
-  handlers: HandlerEntry[];
-  presenters: PresenterEntry[];
-  collectors: CollectorEntry[];
-  seeds: SeedEntry[];
-  middlewares: MiddlewareEntry[];
-  /**
-   * Brought by an EXTENSION rather than by the app — `@fougere/calls` keeping its lines,
-   * `@fougere/observability` sending them on. It is installed like any other, and it is not
-   * what the app SERVES: a report that lists it describes the instrumentation, not the
-   * domain. Set by the boot, never by a declaration.
-   */
-  brought?: true;
-  /** The ops that finish a fact, in order — see `FrondConfig.pipes`. */
-  pipes?: Record<string, string[]>;
-  /**
-   * Per-surface entity lists from frond.config.ts (e.g. { graphql: ['Post'], rest: ['Post',
-   * 'Author'] }).
-   */
-  surfaces?: Record<string, string[]>;
-  /** Entities this frond may read across sources — see `FrondConfig.reads`. */
-  reads?: string[];
-  /** Per-operation overrides from frond.config.ts. */
-  operationsOverrides?: Record<string, OperationContract & {
-    kind?: 'query' | 'command';
-    /** Class name to resolve from DI (overrides default `{Entity}Handler` lookup). */
-    handlerName?: string;
-    /** Method name on the resolved handler (defaults to op name). */
-    method?: string;
-    /** The GraphQL root field this op answers to — read by `adapter/graphql`. */
-    graphql?: string;
-    /** Where it answers over REST — read by `adapter/rest`, the dual of `graphql`. */
-    rest?: { method?: string; path?: string; status?: number };
-  }>;
-}

package/src/prefab/mirror.ts

@@ -1,60 +0,0 @@
-import type { EntityConstructor } from '@fougere/schema';
-import type { Storage } from '../storage/port.js';
-
-/** What one refresh did — enough to log it, and to decide whether to run again. */
-export interface Refreshed {
-  /** Instances written, counting a replaced one once. */
-  written: number;
-  /** The age the pull was asked to start from — absent when it asked for everything. */
-  since?: Date;
-  /** How long the whole pass took, pull included. */
-  ms: number;
-}
-
-/**
- * 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>;
-  /** Pages of rows to write. The one thing a mirror's author supplies. */
-  pull(since?: Date): AsyncIterable<Partial<T>[]>;
-  /**
-   * Pull from `since` and write every page. The mark is the CALLER's: only it knows
-   * whether a pass completed, and a pass that throws must not advance it.
-   */
-  refresh(since?: Date): Promise<Refreshed>;
-}
-
-export interface MirrorConstructor<T> {
-  new (storage: Storage<T>): MirrorOf<T>;
-  readonly __entity: unknown;
-}
-
-export function Mirror<E extends EntityConstructor>(shape: E): MirrorConstructor<InstanceType<E>> {
-  type T = InstanceType<E>;
-
-  abstract class MirrorBase implements MirrorOf<T> {
-    static readonly __entity = shape;
-
-    constructor(public storage: Storage<T>) {}
-
-    abstract pull(since?: Date): AsyncIterable<Partial<T>[]>;
-
-    async refresh(since?: Date): Promise<Refreshed> {
-      const started = Date.now();
-      let written = 0;
-      // Preserve the source's page boundaries: one page becomes one upsert.
-      for await (const page of this.pull(since)) {
-        if (page.length === 0) continue;
-        written += await this.storage.upsertAll(page);
-      }
-
-      return { written, since, ms: Date.now() - started };
-    }
-  }
-
-  return MirrorBase as unknown as MirrorConstructor<T>;
-}

package/src/wire/call.ts

@@ -1,150 +0,0 @@
-/** Call contract — a frond call is a value. */
-import { Card, type SchemaDescriptor } from '@fougere/schema';
-import { factsAnnouncedBy } from './emit.js';
-import { Invocation, type InvocationContext, type PartialInvocation } from './Invocation.js';
-import type { RouteAddress } from './RouteAddress.js';
-import { FougereError, ErrorCode } from './errors.js';
-
-/** One normalized request, frozen: where it goes and what the caller supplied. */
-export class Call {
-  readonly address: RouteAddress;
-  readonly invocation: Invocation;
-
-  constructor(address: RouteAddress, invocation?: PartialInvocation) {
-    this.address = address;
-    this.invocation = Invocation.from(invocation);
-    Object.freeze(this);
-  }
-}
-
-/** Target of a call — which façade operation, wherever it lives. */
-export interface FrondCall {
-  /** Frond name, when the caller knows it. Routing hint only. */
-  frond?: string;
-  /** Entity registration key (e.g. 'product'). */
-  entity: string;
-  /** Façade operation name (e.g. 'findById', 'search'). */
-  op: string;
-}
-
-/** A transport executes a call somewhere else. Failures surface as thrown FougereError. */
-export type Transport = (call: FrondCall, invocation: InvocationContext) => Promise<unknown>;
-
-/** Reserved namespace — calls the runner answers itself, never a façade. */
-/** What a receiver accepts before it stops reading an input. */
-export const MAX_BODY_BYTES = 1024 * 1024;
-
-export const RPC_ENTITY = 'rpc';
-
-/** What an `rpc` op answers — the door for what the app says about ITSELF, never about a row. */
-export type RpcAnswer = (invocation: InvocationContext, surface?: string) => unknown;
-
-/** Everything a caller's envelope covers — the call as the sender meant it. */
-export interface SignedCall {
-  entity: string;
-  op: string;
-  params?: Record<string, unknown>;
-  query?: Record<string, unknown>;
-  input?: unknown;
-  state?: Record<string, unknown>;
-}
-
-/**
- * One operation, as a stranger meets it — its name, what it is for, what it takes and whether it
- * reads or writes.
- */
-export interface CardOp {
-  name: string;
-  /** The author's own doc sentence, when the method carries one. */
-  description?: string;
-  /** JSON Schema of what it accepts, when the contract names a view. */
-  input?: SchemaDescriptor;
-  /** JSON Schema of what it emits, when the contract names one. */
-  output?: SchemaDescriptor;
-  /** `query` reads, `command` writes — the same call REST turns into GET vs POST. */
-  kind: 'query' | 'command';
-  /** How much `output` describes. */
-  cardinality?: 'one' | 'maybe' | 'many' | 'page' | 'none';
-}
-
-/** What an app hosts — the wire projection of its scanned fronds. */
-export interface IdentityCard {
-  fronds: {
-    name: string;
-    doors: {
-      name: string;
-      ops: CardOp[];
-      /** The shape stored under this name — **absent when nothing is**. */
-      schema?: SchemaDescriptor;
-    }[];
-    /** The facts this frond ANNOUNCES — one entry per `Emit<T>` its handlers inject. */
-    facts: { name: string; schema?: SchemaDescriptor }[];
-  }[];
-}
-
-/** A frond this process knows about, and whether it runs here. */
-export interface FrondPlacement {
-  frond: string;
-  placement: 'local' | 'remote';
-  entities: number;
-  doors: number;
-}
-
-/** One frond calling another — an edge of the graph, counted where the call was made. */
-export interface Edge {
-  from: string;
-  to: string;
-  count: number;
-  errors: number;
-}
-
-/** The shape of the system as ONE process discovered it — the answer to `rpc.topology`. */
-export interface TopologyReport {
-  /** When this process started counting — an edge count is read against it. */
-  since: number;
-  /** Calls running right now: the one signal a static shape cannot carry. */
-  active: number;
-  fronds: FrondPlacement[];
-  edges: Edge[];
-}
-
-/** The shape a card must have to be walked — `fronds`, and each frond's `doors`. */
-export function assertIdentityCard(value: unknown, source: string): IdentityCard {
-  const card = value as IdentityCard | undefined;
-  const fronds = Array.isArray(card?.fronds) ? card.fronds : undefined;
-  if (!fronds) throw cardRefusal(source, 'no fronds array');
-  for (const frond of fronds) {
-    if (!frond || typeof frond.name !== 'string') throw cardRefusal(source, 'a frond with no name');
-    if (!Array.isArray(frond.doors)) throw cardRefusal(source, `frond '${frond.name}' has no valid doors array`);
-  }
-  return card as IdentityCard;
-}
-
-function cardRefusal(source: string, what: string): FougereError {
-  return new FougereError({
-    code: ErrorCode.INTERNAL_ERROR,
-    message:
-      `${source} answered an invalid identity card: ${what}.\n`
-      + `  A card is what tells this process what the other one hosts, so nothing can be routed from it.\n`
-      + `  - Check that the address serves a Fougere app, and that its version still speaks this card.`,
-  });
-}
-
-/** A façade as the runtime holds it: op names to functions, nothing typed about them. */
-
-/** The door built in front of a handler — the framework's second port, after `Storage`. */
-export type Facade<T> = {
-  [K in keyof T]: T[K] extends (...args: never[]) => infer R
-    ? (invocation?: InvocationContext) => R
-    : never;
-};
-
-/** The container key of a façade — THE one place that spells the format. */
-export function facadeKeyOf(entityName: string, surface?: string): string {
-  return surface ? `${surface}:${entityName}Handler` : `${entityName}Handler`;
-}
-
-/** Where the contracts behind a façade live — the dual of `facadeKeyOf`. */
-export function contractsKeyOf(entityName: string, surface?: string): string {
-  return `${facadeKeyOf(entityName, surface)}:contracts`;
-}

package/src/wire/middleware.ts

@@ -1,43 +0,0 @@
-/** App-level middleware — intercepts handler facade operations. */
-
-// ── Types ───────────────────────────────────────
-export interface OperationContext {
-  /** Entity name (e.g. 'product'). */
-  entity: string;
-  /**
-   * Which frond owns this operation — the unit that gets deployed, and therefore the
-   * one a reader groups by first. Absent only where no frond claims the call.
-   */
-  frond?: string;
-  /** Operation name (e.g. 'create', 'findById', 'searchByTitle'). */
-  operation: string;
-  /** Arguments passed to the operation. */
-  args: unknown[];
-  /** Extensible bag — middlewares deposit data here (user, permissions, etc.). */
-  state: Record<string, unknown>;
-  /** Transport-agnostic invocation context (params, query, input, state). */
-  invocation?: import('../wire/Invocation.js').InvocationContext;
-}
-
-export type AppNext = () => Promise<unknown>;
-export type AppMiddleware = (ctx: OperationContext, next: AppNext) => Promise<unknown>;
-
-// ── Runner ──────────────────────────────────────
-
-/**
- * Execute a middleware chain (onion model) then the handler.
- */
-export function runMiddlewares(
-  middlewares: AppMiddleware[],
-  ctx: OperationContext,
-  handler: AppNext,
-): Promise<unknown> {
-  let index = 0;
-  const next = (): Promise<unknown> => {
-    if (index < middlewares.length) {
-      return middlewares[index++](ctx, next);
-    }
-    return handler();
-  };
-  return next();
-}