@fougere/core 0.7.0-alpha.0 → 0.8.0-alpha.0

package/src/scan/statement.ts

@@ -1,9 +1,9 @@
 /** The scan, written as the STATEMENT an author would have written. */
 import { relative } from 'node:path';
+import { nameOf } from '../descriptor/frond.js';
 import type { FrondDescriptor } from '../descriptor/frond.js';
 import type { ScanResult } from './result.js';
-
-type Live = { name?: string };
+import { type Aliases, type Live, operationsOf } from './contract.js';
 
 /**
  * A file becomes the specifier the PROJECT already uses for it: `@fronds/blog/…`, the import scope
@@ -17,30 +17,66 @@ function specifierOf(filePath: string, frond: FrondDescriptor): string {
 }
 
 /** One alias per file, so a class imported twice is one binding and one identity. */
-class Imports {
+class Imports implements Aliases {
   private readonly byPath = new Map<string, string>();
+  private readonly byValue = new Map<Live, string>();
+  private readonly byClassName = new Map<string, Live>();
   private readonly lines: string[] = [];
+  /** The frond a file belongs to — a named import needs the specifier its default got. */
+  private frondOfFile = new Map<string, FrondDescriptor>();
 
-  default(filePath: string, frond: FrondDescriptor): string {
+  default(filePath: string, frond: FrondDescriptor, value?: Live): string {
+    this.frondOfFile.set(filePath, frond);
     const known = this.byPath.get(filePath);
-    if (known) return known;
+    if (known) {
+      if (value) this.remember(value, known);
+
+      return known;
+    }
     const alias = `_${this.byPath.size}`;
     this.lines.push(`import ${alias} from '${specifierOf(filePath, frond)}';`);
     this.byPath.set(filePath, alias);
+    if (value) this.remember(value, alias);
+
+    return alias;
+  }
+
+  /** A view a handler declares beside itself — `PostPublic` is exported by name. */
+  named(value: Live, filePath: string, name: string): string {
+    const known = this.byValue.get(value);
+    if (known) return known;
+    const frond = this.frondOfFile.get(filePath);
+    if (!frond) {
+      throw new Error(
+        `A statement cannot be written: ${name} lives in ${filePath}, which no frond imported first.`,
+      );
+    }
+    const alias = `_${this.byPath.size}_${name}`;
+    this.lines.push(`import { ${name} as ${alias} } from '${specifierOf(filePath, frond)}';`);
+    this.remember(value, alias);
 
     return alias;
   }
 
+  aliasOf(value: Live): string | undefined { return this.byValue.get(value); }
+  classNamed(name: string): Live | undefined { return this.byClassName.get(name); }
+
+  private remember(value: Live, alias: string): void {
+    this.byValue.set(value, alias);
+    const name = (value as { name?: string }).name;
+    if (name) this.byClassName.set(name, value);
+  }
+
   render(): string {
     return this.lines.join('\n');
   }
 }
 
 /** `{ ctor: X, deps: [...] }` when there is something to say, the bare class otherwise. */
-function subject(alias: string, deps: string[], extra = ''): string {
+function subject(alias: string, deps: string[], ...extra: string[]): string {
   const parts = [
     ...(deps.length ? [`deps: ${JSON.stringify(deps)}`] : []),
-    ...(extra ? [extra] : []),
+    ...extra.filter(Boolean),
   ];
 
   return parts.length ? `{ ctor: ${alias}, ${parts.join(', ')} }` : alias;
@@ -50,12 +86,21 @@ function frondOf(frond: FrondDescriptor, imports: Imports): string {
   const list = (items: string[]): string => `[${items.join(', ')}]`;
   const members: string[] = [];
 
+  // Entities first, and by VALUE: an operation names its input and output as schemas, and
+  // the one a `Partial<X>` derives from is found here rather than imported a second time.
   if (frond.entities.length) {
-    members.push(`entities: ${list(frond.entities.map((e) => imports.default(e.filePath, frond)))}`);
+    members.push(`entities: ${list(frond.entities.map((e) =>
+      imports.default(e.filePath, frond, e.entityClass as Live)))}`);
   }
   if (frond.handlers.length) {
-    members.push(`handlers: ${list(frond.handlers.map((h) =>
-      subject(imports.default(h.filePath, frond), h.deps, h.surface ? `surface: ${JSON.stringify(h.surface)}` : '')))}`);
+    members.push(`handlers: ${list(frond.handlers.map((h) => subject(
+      imports.default(h.filePath, frond, h.ctor as Live),
+      h.deps,
+      h.surface ? `surface: ${JSON.stringify(h.surface)}` : '',
+      // What the scan read from source, and what no class carries at runtime. Without it
+      // a host that boots from this statement serves a prefab's five ops and nothing else.
+      h.operations.size ? `operations: ${operationsOf(h.operations, h.filePath, imports, '      ')}` : '',
+    )))}`);
   }
   if (frond.presenters.length) {
     members.push(`presenters: ${list(frond.presenters.map((p) => subject(imports.default(p.filePath, frond), p.deps)))}`);
@@ -64,13 +109,26 @@ function frondOf(frond: FrondDescriptor, imports: Imports): string {
     members.push(`collectors: ${list(frond.collectors.map((c) => subject(imports.default(c.filePath, frond), c.deps)))}`);
   }
   if (frond.providers.length) {
-    members.push(`providers: ${list(frond.providers.map((p) => subject(imports.default(p.filePath, frond), p.deps)))}`);
+    members.push(`providers: ${list(frond.providers.map((p) => subject(
+      imports.default(p.filePath, frond, p.ctor as Live),
+      p.deps,
+      // The container key, and a bundler is free to rewrite the class's own name — it did,
+      // and a handler asking for `Communes` met a provider registered as `_Communes`.
+      `name: ${JSON.stringify(nameOf(p))}`,
+    )))}`);
   }
   // A seed is DATA, not a class — the one member a statement cannot derive from an import.
   if (frond.seeds.length) {
     members.push(`seeds: ${JSON.stringify(frond.seeds.map((s) => ({ entityName: s.entityName, data: s.data })))}`);
   }
   if (frond.surfaces) members.push(`surfaces: ${JSON.stringify(frond.surfaces)}`);
+  // What `frond.config.ts` states — read BY the scan, so a host that boots from a written
+  // statement never sees the file. It is the only answer for the kind of an op whose name
+  // leads with no known verb, and the only one for a method inherited from a base class
+  // the workspace scan cannot see.
+  if (frond.operationsOverrides && Object.keys(frond.operationsOverrides).length) {
+    members.push(`operationsOverrides: ${JSON.stringify(frond.operationsOverrides)}`);
+  }
 
   const scope = (frond.source.package as string | undefined)?.split('/')[0];
   if (scope) members.push(`scope: ${JSON.stringify(scope)}`);

package/src/source.ts

@@ -1,13 +1,32 @@
-import { Registry, type SchemaView } from '@fougere/schema';
+import { Registry, Role, type SchemaView } from '@fougere/schema';
 import type { StorageFactory } from './storage.js';
 
+/** A promise the judge at the door cannot keep, because it is about rows it never sees. */
+export type Constraint = 'unique';
+
+/** Whether an entity asks for one, anywhere but on its key. */
+export function declares(schema: SchemaView, constraint: Constraint): boolean {
+  if (constraint !== 'unique') return false;
+  if ((schema.getUnique() ?? []).length > 0) return true;
+
+  return Object.values(schema.getFields()).some((field) => Role.of(field).isUnique);
+}
+
 /** A place rows live, whatever realizes it. */
 export interface Source {
   storageFactory: StorageFactory;
-  /** Bring the shape of what lives here up to date. */
-  migrate?(view: SourceView): Promise<void>;
+  /**
+   * Bring the shape of what lives here up to date, and say what it could not bring.
+   *
+   * A pass is additive by design and leaves what already exists alone — which is a
+   * promise worth keeping and a silence worth breaking: what it declined to change is
+   * still a difference, and a boot is where a reader can act on it.
+   */
+  migrate?(view: SourceView): Promise<void | string>;
   /** Run `fn` as ONE unit of work, with a factory bound to it. */
   transacted?<R>(fn: (factory: StorageFactory) => Promise<R>): Promise<R>;
+  /** What it refuses at the rows themselves. Absent leaves the judge alone with it. */
+  enforces?: readonly Constraint[];
   close?(): Promise<void>;
   /** What distinguishes it when a query is reported. */
   name?: string;

package/src/store.ts

@@ -1,5 +1,6 @@
 /** The thirteen gestures of {@link Storage}, derived from four. */
 import { applyCreate, applyUpdate, Lifecycle, Role, type SchemaView } from '@fougere/schema';
+import { comparisonOf, comparisonsIn, type Comparison } from './criterion.js';
 import type { Storage, StorageFactory } from './storage.js';
 
 /** One instance, as every realization hands it over. */
@@ -27,10 +28,16 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
     // 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.
+    // A comparison is told from a value by the FIELD, never by the criterion's own shape.
     const matches = (values: Record<string, unknown>, criteria: Record<string, unknown>) =>
-      Object.entries(criteria).every(([key, value]) => Array.isArray(value)
-        ? value.some((v) => Object.is(values[key], v))
-        : Object.is(values[key], value));
+      Object.entries(criteria).every(([key, value]) => {
+        const comparison = comparisonOf(fields[key], value);
+        if (comparison) return compares(values[key], comparison);
+
+        return Array.isArray(value)
+          ? value.some((v) => Object.is(values[key], v))
+          : Object.is(values[key], value);
+      });
 
     // A store holds whole instances and reads them whole, so the scope SQL puts in its
     // SELECT is applied here on the way out. Same set of gestures either way: everything
@@ -150,3 +157,35 @@ export function storageOver(open: (entity: SchemaView, name: string) => Store):
     return scoped();
   };
 }
+
+/**
+ * The same comparisons SQL compiles, answered in memory. Every one a criterion names has
+ * to hold — the rule two criteria already follow.
+ */
+function compares(held: unknown, comparison: Comparison): boolean {
+  return comparisonsIn(comparison).every(([name, asked]) => {
+    switch (name) {
+      case 'gte': return ordered(held, asked, (a, b) => a >= b);
+      case 'lte': return ordered(held, asked, (a, b) => a <= b);
+      case 'gt': return ordered(held, asked, (a, b) => a > b);
+      case 'lt': return ordered(held, asked, (a, b) => a < b);
+      case 'ne': return !Object.is(held, asked);
+      case 'contains': return String(held ?? '').includes(String(asked));
+      case 'notIn': return !(asked as readonly unknown[]).some((one) => Object.is(held, one));
+      case 'isNull': return (held === null || held === undefined) === Boolean(asked);
+      case 'between': {
+        const [low, high] = asked as [unknown, unknown];
+
+        return ordered(held, low, (a, b) => a >= b) && ordered(held, high, (a, b) => a <= b);
+      }
+    }
+  });
+}
+
+/** A row that holds nothing compares to nothing — the answer SQL gives for NULL. */
+const ordered = (held: unknown, asked: unknown, holds: (a: number, b: number) => boolean): boolean =>
+  held === null || held === undefined ? false : holds(order(held), order(asked));
+
+/** What a Date and a number have in common, and a string keeps for itself. */
+const order = (value: unknown): number =>
+  value instanceof Date ? value.getTime() : (value as number);