@fougere/app 0.2.0-alpha.2 → 0.4.0-alpha.0

package/src/express.ts

@@ -0,0 +1,208 @@
+/**
+ * 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.
+ */
+import { readExpressBody } from '@fougere/http';
+import { serveRest, serveRpc, rpcParseError } from './serve.js';
+import { serveGraphQL } from './graphql.js';
+import { sessionViewOf } from './session.js';
+import { useFougereApp } from './boot.js';
+
+/** What a middleware reads off an Express request. Structural, not imported. */
+interface ExpressRequest {
+  method: string;
+  path?: string;
+  originalUrl?: string;
+  url?: string;
+  query?: Record<string, unknown>;
+  headers?: Record<string, unknown>;
+  body?: unknown;
+  /** Filled by an auth middleware that ran before us, if any. */
+  fougereState?: Record<string, unknown>;
+  user?: unknown;
+}
+
+interface ExpressResponse {
+  status(code: number): ExpressResponse;
+  set(field: string, value: unknown): ExpressResponse;
+  json(body: unknown): unknown;
+}
+
+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.
+ */
+function stateOf(req: ExpressRequest): Record<string, unknown> {
+  if (req.fougereState) return req.fougereState;
+  return req.user ? { user: req.user } : {};
+}
+
+function pathOf(req: ExpressRequest): string {
+  return req.path ?? String(req.originalUrl ?? req.url ?? '').split('?')[0]!;
+}
+
+function queryOf(req: ExpressRequest): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(req.query ?? {}).map(([key, value]) => [
+      key,
+      String(Array.isArray(value) ? value[0] : value),
+    ]),
+  );
+}
+
+/** Turn a thrown failure into Express's own error pipeline, unless it is a refusal we own. */
+function fail(res: ExpressResponse, next: Next, err: unknown): void {
+  const code = (err as { name?: string })?.name === 'MalformedJsonError' ? 400 : 0;
+  if (code === 400) {
+    res.status(400).json({ code: 'BAD_REQUEST', message: 'Malformed JSON body' });
+    return;
+  }
+  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.
+ */
+export function fougereCall(mountPath = '/_fougere/call'): ExpressMiddleware {
+  return (req, res, next) => {
+    const path = pathOf(req);
+    if (req.method !== 'POST' || !path.startsWith(mountPath)) return next();
+
+    void (async () => {
+      try {
+        const app = await useFougereApp();
+        let body: unknown;
+        try {
+          body = await readExpressBody(req);
+        } catch {
+          res.status(200).json(rpcParseError());
+          return;
+        }
+        res.status(200).json(await serveRpc(app, { path, body, state: stateOf(req) }));
+      } catch (err) {
+        fail(res, next, err);
+      }
+    })();
+  };
+}
+
+/** The session view, at `/_fougere/session`. */
+export function fougereSession(mountPath = '/_fougere/session'): ExpressMiddleware {
+  return (req, res, next) => {
+    if (req.method !== 'GET' || pathOf(req) !== mountPath) return next();
+    res.status(200).json(sessionViewOf(stateOf(req)));
+  };
+}
+
+/**
+ * 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.
+ */
+export function fougereRest(mountPath = '/api'): ExpressMiddleware {
+  return (req, res, next) => {
+    const path = pathOf(req);
+    if (!path.startsWith(`${mountPath}/`)) return next();
+
+    void (async () => {
+      try {
+        const app = await useFougereApp();
+        const outcome = await serveRest(app, {
+          method: req.method,
+          path: path.slice(mountPath.length + 1),
+          query: queryOf(req),
+          body: await readExpressBody(req),
+          state: stateOf(req),
+        });
+
+        // Not ours — Express's own passthrough, which is what `pass` always meant.
+        if (outcome.kind === 'pass') return next();
+
+        if (outcome.kind === 'error' && outcome.headers) {
+          for (const [key, value] of Object.entries(outcome.headers)) res.set(key, value);
+        }
+        res.status(outcome.status).json(outcome.body);
+      } catch (err) {
+        fail(res, next, err);
+      }
+    })();
+  };
+}
+
+/** GraphQL, at `/graphql` by default. Declines when the app declares no such adapter. */
+export function fougereGraphQL(mountPath = '/graphql'): ExpressMiddleware {
+  return (req, res, next) => {
+    if (req.method !== 'POST' || pathOf(req) !== mountPath) return next();
+
+    void (async () => {
+      try {
+        const app = await useFougereApp();
+        const body = ((await readExpressBody(req)) ?? {}) as {
+          query?: string;
+          variables?: Record<string, unknown>;
+          operationName?: string;
+        };
+        const outcome = await serveGraphQL(app, { ...body, state: stateOf(req) });
+        if (outcome.kind === 'pass') return next();
+        res.status(outcome.status).json(outcome.body);
+      } catch (err) {
+        fail(res, next, err);
+      }
+    })();
+  };
+}
+
+/** Every door, for an app that wants all of them. What each one SERVES is still the
+ *  app's declaration — mounting is not publishing. */
+export function fougere(): ExpressMiddleware {
+  const doors = [fougereCall(), fougereSession(), fougereRest(), fougereGraphQL()];
+  return (req, res, next) => {
+    let index = 0;
+    const step = (err?: unknown) => {
+      if (err) return next(err);
+      const door = doors[index++];
+      if (!door) return next();
+      door(req, res, step);
+    };
+    step();
+  };
+}

package/src/form.ts

@@ -0,0 +1,237 @@
+import { Lifecycle } from '@fougere/schema';
+/**
+ * Form contract, pure part — derives what a create/edit form is made of
+ * from the entity's field axes. No Vue, no Nuxt: testable headless,
+ * usable by any renderer (the page owns the widgets).
+ */
+import { Anatomy, lowerFirst, Role, Visibility } from '@fougere/schema';
+import type { Field, SchemaView, ValidationError, ValidationResult } from '@fougere/schema';
+
+/**
+ * What an entity class exposes to a form — the schema statics it already has.
+ *
+ * `SchemaView` and the real `Field`, not a local re-description of the axes: this file
+ * used to declare its own `FieldLike` with `shape?` optional, so it kept judging by a
+ * looser contract than the schema's own and would never have seen `shape` become
+ * required.
+ */
+export type FormEntity = SchemaView;
+
+/**
+ * The literal a field is born with, when it declares one.
+ *
+ * `text({ default: 'x' })` and `oneOf('a', 'b', { default: 'a' })` both compile to
+ * `lifecycle.create = { value }` — the create rule that answers the field's absence.
+ * The other create rules ('now', { generate }, 'optional') name no literal: their value
+ * is decided at write time, so a form has nothing to show for them.
+ */
+function defaultOf(field: Field): unknown {
+  return Lifecycle.of(field).literal?.value;
+}
+
+export interface FormField {
+  name: string;
+  /** Rendering hint derived from the shape — the page maps it to widgets. */
+  control: 'text' | 'email' | 'url' | 'number' | 'boolean' | 'date' | 'select';
+  required: boolean;
+  /** i18n key by convention: `entity.field`. The schema never carries display text. */
+  labelKey: string;
+  /** Fallback label when no i18n message fills the key. */
+  label: string;
+  /** Enum values, when control is 'select'. */
+  options?: string[];
+  /**
+   * What the browser enforces, under the names it already knows — spread this on the
+   * input and the page states no rule of its own.
+   *
+   * The shape holds `minLength`/`maximum`/`pattern`; a browser holds `minlength`/
+   * `max`/`pattern` and enforces them with no JavaScript at all. Carrying them here
+   * is a projection, not a second rule: the judge reads the same shape, and a form
+   * that ignores these still gets the same verdict — it just gets it later, and a
+   * screen reader never gets it at all.
+   *
+   * `type` is part of the contract, not decoration: `email` and `url` are formats the
+   * shape states and the browser checks live, per field, as one types. A page writing
+   * `type="email"` by hand is spelling a second time what the card already said.
+   *
+   * Three deliberate absences, each one a place where the attribute would mean
+   * something the shape does not say:
+   * - a `date` field gets no `type` — neither `date` nor `datetime-local` produces the
+   *   RFC 3339 string a `date-time` shape judges, so the browser would accept what the
+   *   judge refuses;
+   * - `select` and `boolean` are not inputs — the page picks the widget, `control` says
+   *   which;
+   * - a required `boolean` gets no `required` — on a checkbox that attribute means
+   *   "must be CHECKED", where the shape only says the value must be supplied.
+   */
+  attrs?: {
+    type?: 'text' | 'email' | 'url' | 'number';
+    required?: boolean;
+    minlength?: number;
+    maxlength?: number;
+    min?: number;
+    max?: number;
+    pattern?: string;
+  };
+  /**
+   * The value the field is born with — the literal its `lifecycle.create` rule names.
+   * Present so the form can SHOW what is about to be written; the storage realizes it
+   * either way, so a form that ignores this still produces the same row.
+   */
+  default?: unknown;
+}
+
+/** The base JSON type of a shape — unwraps the `[T,'null']` union. */
+function baseType(type: unknown): string {
+  if (Array.isArray(type)) return (type.find((t) => t !== 'null') as string) ?? 'string';
+  return (type as string) ?? 'string';
+}
+
+/** The formats a browser has an input type for — the rest stay `text`, judged later. */
+const CONTROL_BY_FORMAT: Record<string, FormField['control']> = {
+  'date-time': 'date',
+  email: 'email',
+  uri: 'url',
+};
+
+function controlOf(field: Field): FormField['control'] {
+  // Through `anatomy`, never `shape.type` directly: the nullable form is the `[T,'null']`
+  // union, which a direct comparison misses in silence. It is also what narrows the shape
+  // union, so `enum` and `format` are only reachable on the branches that carry them.
+  const base = Anatomy.of(field.shape).base;
+  if (base?.type === 'string' && base.enum?.length) return 'select';
+  if (base?.type === 'number' || base?.type === 'integer') return 'number';
+  if (base?.type === 'boolean') return 'boolean';
+  if (base?.type === 'string' && base.format) return CONTROL_BY_FORMAT[base.format] ?? 'text';
+  return 'text';
+}
+
+/** A closed set's members, when the shape declares one — `oneOf('draft','live')`. */
+function enumOf(field: Field): readonly (string | null)[] | undefined {
+  const base = Anatomy.of(field.shape).base;
+  return base?.type === 'string' ? base.enum : undefined;
+}
+
+/** Controls that ARE an `<input type>` — see the two absences on {@link FormField.attrs}. */
+const INPUT_TYPES = new Set(['text', 'email', 'url', 'number']);
+
+/** The shape's bounds, under the names a browser already enforces. */
+function attrsOf(field: Field, control: FormField['control'], required: boolean): NonNullable<FormField['attrs']> {
+  const base = Anatomy.of(field.shape).base;
+  const text = base?.type === 'string' ? base : undefined;
+  const numeric = base?.type === 'number' || base?.type === 'integer' ? base : undefined;
+  const attrs = {
+    type: INPUT_TYPES.has(control) ? control : undefined,
+    required: (required && control !== 'boolean') || undefined,
+    minlength: text?.minLength,
+    maxlength: text?.maxLength,
+    min: numeric?.minimum,
+    max: numeric?.maximum,
+    pattern: text?.pattern,
+  };
+  return Object.fromEntries(Object.entries(attrs).filter(([, v]) => v !== undefined));
+}
+
+/**
+ * The label convention, spelled once for both projections: an i18n key by convention and
+ * the field's own name as the fallback. The schema never carries display text.
+ */
+function labelOf(name: string, entityKey: string): Pick<FormField, 'labelKey' | 'label'> {
+  return { labelKey: `${entityKey}.${name}`, label: name.charAt(0).toUpperCase() + name.slice(1) };
+}
+
+/**
+ * The fields a create form is made of: membership from the io projection
+ * (`Visibility.input` — what a client may supply), requiredness from the
+ * lifecycle axis (any create rule makes absence legal).
+ */
+export function formFieldsOf(entity: FormEntity, entityKey: string): FormField[] {
+  return Object.entries(Visibility.of(entity.getFields()).input).map(([name, field]) => {
+    const f = field;
+    const control = controlOf(f);
+    const required = Lifecycle.of(f).requiredAtCreate;
+    const attrs = attrsOf(f, control, required);
+    return {
+      name,
+      control,
+      required,
+      ...labelOf(name, entityKey),
+      ...(Array.isArray(enumOf(f))
+        ? { options: enumOf(f)!.filter((value): value is string => typeof value === 'string') }
+        : {}),
+      ...(Object.keys(attrs).length ? { attrs } : {}),
+      ...(defaultOf(f) !== undefined ? { default: defaultOf(f) } : {}),
+    };
+  });
+}
+
+export interface TableColumn {
+  name: string;
+  /**
+   * How to print the value — the dual of {@link FormField.control}, and deliberately not
+   * the same list: a closed set prints as its value, a reference prints as a link.
+   */
+  render: 'text' | 'number' | 'boolean' | 'date' | 'json' | 'link';
+  /** The same key a form uses for the same field — one convention, two projections. */
+  labelKey: string;
+  label: string;
+  /**
+   * The entity a `link` points at, under the key its door is named by. Always present on a
+   * reference: the card carries the target's name, and a card rebuilt with no sibling to
+   * resolve to keeps it as a stand-in rather than losing it.
+   */
+  to?: string;
+}
+
+/** Asked of the relation before the shape: a reference's own shape is a bare string. */
+function renderOf(field: Field): TableColumn['render'] {
+  if (Role.of(field).isReference) return 'link';
+  const base = Anatomy.of(field.shape).base;
+  if (base?.type === 'number' || base?.type === 'integer') return 'number';
+  if (base?.type === 'boolean') return 'boolean';
+  if (base?.type === 'object' || base?.type === 'array') return 'json';
+  if (base?.type === 'string' && base.format === 'date-time') return 'date';
+  return 'text';
+}
+
+/**
+ * The columns a list is made of: membership from the io projection (`Visibility.output` — what
+ * may leave), minus collections, because a cell holds one value and a `many()` is a page.
+ *
+ * Which column identifies the row is NOT answered here — `FieldSet.primary` answers it for a
+ * shape, and its own doc records what five private copies of that loop cost.
+ */
+export function tableColumnsOf(entity: FormEntity, entityKey: string): TableColumn[] {
+  return Object.entries(Visibility.of(entity.getFields()).output)
+    .filter(([, field]) => !Role.of(field).isCollection)
+    .map(([name, field]) => {
+      const target = Role.of(field).target;
+      return {
+        name,
+        render: renderOf(field),
+        ...labelOf(name, entityKey),
+        ...(target ? { to: lowerFirst(target.name) } : {}),
+      };
+    });
+}
+
+/**
+ * The wire body of the form's values — an empty control is an absent value
+ * at the create boundary (absence is judged by the lifecycle axis, an empty
+ * string would be judged as a present bad value).
+ */
+export function payloadOf(values: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(values).filter(([, v]) => v !== undefined && v !== ''),
+  );
+}
+
+/** Index judge errors by field — local judge and remote judge share this shape. */
+export function errorsByField(errors: ValidationError[]): Record<string, string> {
+  const byField: Record<string, string> = {};
+  for (const err of errors) {
+    const field = err.path.split('.')[0] || err.path;
+    byField[field] ??= err.message;
+  }
+  return byField;
+}

package/src/graphql.ts

@@ -0,0 +1,85 @@
+/**
+ * The GraphQL door — declared like the others, mounted like the others.
+ *
+ * Until now GraphQL was the odd one out: `adapters: { graphql: true }` was
+ * declarable and nothing read it, while an app that wanted a schema wrote fifteen
+ * lines of its own (a Pothos builder, a query type, a mutation type, `registerAll`,
+ * then `registerGraphQL` on a router). Every one of those lines is convention —
+ * there is no decision in them — so the app declaring the adapter is enough.
+ *
+ * The package is imported LAZILY, the same shape `db: 'sqlite'` uses (`resolveStorage`
+ * pulls `@fougere/adapter-sql` only when a database is declared). A schema builder is
+ * heavy and most apps serve none, so a host must not carry one to find out. Declaring
+ * the adapter without installing it is refused by name, the way an unresolvable dialect is.
+ *
+ * This file used to BUILD the schema — a Pothos builder, `registerAll`, then `graphql()`
+ * — which made it the only schema constructor in the repo, in the package least entitled
+ * to be one. Two costs, one cause: the derivation sat away from the adapter whose job it
+ * is, and `graphql` guards its types with `instanceOf`, so a schema built on one side of
+ * the package boundary was refused on the other as coming *"from another module or
+ * realm"*. Both are gone: `@fougere/adapter-graphql` derives and executes, this door
+ * translates the result into an `Outcome`.
+ */
+import type { App } from '@fougere/core';
+import type { Outcome } from './serve.js';
+
+/** What a GraphQL request carries, whatever host read it. */
+export interface GraphQLRequest {
+  query?: string;
+  variables?: Record<string, unknown>;
+  operationName?: string;
+  /** The audience, when the door was mounted per surface. */
+  surface?: string;
+  state: Record<string, unknown>;
+}
+
+type ExecuteOn = (app: unknown, request: {
+  query: string;
+  variables?: Record<string, unknown>;
+  operationName?: string;
+  surface?: string;
+  state?: Record<string, unknown>;
+}) => Promise<unknown>;
+
+async function executor(): Promise<ExecuteOn> {
+  try {
+    const { executeOn } = await import('@fougere/adapter-graphql');
+    return executeOn as unknown as ExecuteOn;
+  } catch (cause) {
+    throw new Error(
+      "adapters: { graphql: true } is declared, but the package that serves it is not " +
+      'installed. Add `@fougere/adapter-graphql` — it is not a dependency of the host, ' +
+      'because an app that serves no GraphQL should not carry a schema builder to find ' +
+      'that out.',
+      { cause },
+    );
+  }
+}
+
+/**
+ * Execute a GraphQL request against the app's own operations.
+ *
+ * `pass` when the app declares no GraphQL adapter — the same answer `serveRest` gives,
+ * so a host that mounted the door takes nothing away from an app that did not ask for it.
+ */
+export async function serveGraphQL(app: App, request: GraphQLRequest): Promise<Outcome> {
+  if (!app.adapters?.graphql) return { kind: 'pass' };
+
+  if (!request.query) {
+    return { kind: 'error', status: 400, body: { message: 'Missing query' } };
+  }
+
+  const executeOn = await executor();
+  const result = await executeOn(app, {
+    query: request.query,
+    variables: request.variables,
+    operationName: request.operationName,
+    surface: request.surface,
+    // The same state every other door stamps: what the server resolved, never the wire.
+    state: request.state,
+  });
+
+  // A GraphQL error is not an HTTP error: the transport succeeded, and the errors ride
+  // in the body where a client is required to look for them.
+  return { kind: 'ok', status: 200, body: result as Record<string, unknown> };
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * `@fougere/app` — what an app host needs and what no host owns.
+ *
+ * Two adapters read this package: `@fougere/nuxt` and `@fougere/next`. Between
+ * them they share the boot, the three doors' decisions, the REST table, the form
+ * contract and the session view; what they do NOT share is how a request arrives,
+ * how routes are mounted, and how a value becomes reactive.
+ *
+ * The root entry pulls in the boot, which reads the filesystem — client code wants
+ * `@fougere/app/client`.
+ */
+export {
+  configureFougere,
+  extendFougere,
+  useFougereApp,
+  reloadFougere,
+  createMemoryOrm,
+  type FougereServerConfig,
+} from './boot.js';
+
+export { useFougereAuth } from './auth.js';
+
+export {
+  tableOf,
+  matchRoute,
+  type Matchable,
+  type RouteMatch,
+} from './rest.js';
+
+export {
+  serveRest,
+  shapeRest,
+  serveRpc,
+  surfaceOf,
+  rpcParseError,
+  invokeOn,
+  type DoorRequest,
+  type Outcome,
+} from './serve.js';
+
+export {
+  formFieldsOf,
+  tableColumnsOf,
+  payloadOf,
+  errorsByField,
+  type FormEntity,
+  type FormField,
+  type TableColumn,
+} from './form.js';
+
+export { sessionViewOf, type SessionView } from './session.js';
+
+export { stateFor } from './state.js';
+
+export { serveGraphQL, type GraphQLRequest } from './graphql.js';