@fougere/adapter-sql 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/index.ts

@@ -1,15 +1,15 @@
 export { createTableSQL, createIndexSQL, indexSQL, addForeignKeyConstraintSQL, generateSQL, autoMigrate, compiler } from './ddl.js';
 export { onQuery, logQueries, type QueryEvent, type QuerySink } from './query.js';
+export type { FkEdge, TableOrder } from './order.js';
 export type { GenerateOptions, SqlSink } from './ddl.js';
-export { toTable, toTables, toTableName, toSnakeCase, isKeyed, orderTables } from './table.js';
+export { toTable, toTables, toTableName, toSnakeCase, isKeyed } from './table.js';
+export { orderTables } from './order.js';
 export type {
   TableDef,
   ColumnDef,
   ColumnShape,
   ColumnReference,
   RelationResolve,
-  FkEdge,
-  TableOrder,
   EntityEntry,
   FrondLike,
   AppLike,
@@ -25,15 +25,15 @@ export {
 } from './dialect.js';
 export type { Dialect, DialectName } from './dialect.js';
 export type { SqlField, SqlFields } from './fields.js';
-export { SqlEntityOrm, createOrmFactory } from './crud.js';
-export type { OrmFactoryOptions } from './crud.js';
+export { SqlStorage, createStorageFactory } from './crud.js';
+export type { StorageFactoryOptions } from './crud.js';
 export { codecFor, codecsOf } from './values.js';
 export type { ValueCodec } from './values.js';
 // The driver this package owns is NOT here: `better-sqlite3` is native and `node:fs` is a
 // builtin, and an index that re-exported them made the whole adapter unreachable from a
 // runtime that has neither. It lives at `@fougere/adapter-sql/sqlite`.
 export { setupKysely, sqlSink } from './setup.js';
-export type { Setup, SetupOptions } from './setup.js';
+export type { Setup, SqlSource, SetupOptions } from './setup.js';
 export { actualState, desiredTables, delta, orderChanges, changeSQL, planMigration, migrate } from './diff.js';
 export type { SchemaState, Change } from './diff.js';
 // The non-additive half — realised only from a step a human wrote down.

package/src/order.ts

@@ -0,0 +1,63 @@
+/**
+ * In what order a batch of tables is created — the one question that reads a `TableDef` and
+ * knows nothing above it: no entity, no axis, no schema.
+ */
+import type { ColumnDef, TableDef } from './table.js';
+
+export interface FkEdge {
+  table: TableDef;
+  column: ColumnDef;
+}
+
+export interface TableOrder {
+  /** Tables in dependency order — a `ref()` target always precedes its referrer. */
+  ordered: TableDef[];
+  /** FK columns whose target could not be ordered first — a cycle. Constrain after creation. */
+  deferred: FkEdge[];
+}
+
+/**
+ * Order a table set so a `ref()`'s target always exists before the table that points at it —
+ * required by every engine except SQLite, which resolves FK targets lazily and accepts any order
+ * (and has no `ALTER TABLE ADD CONSTRAINT` to close a cycle with — a caller on that dialect skips
+ * this function entirely).
+ */
+export function orderTables(tables: TableDef[]): TableOrder {
+  const byName = new Map(tables.map((table) => [table.name, table]));
+  const needs = new Map(
+    tables.map((table) => [
+      table.name,
+      new Set(
+        table.columns
+          .filter((c) => c.references && c.references.table !== table.name && byName.has(c.references.table))
+          .map((c) => c.references!.table),
+      ),
+    ]),
+  );
+
+  const ordered: TableDef[] = [];
+  const deferred: FkEdge[] = [];
+  const done = new Set<string>();
+
+  while (needs.size > 0) {
+    const ready = [...needs.keys()].find((name) => [...needs.get(name)!].every((dep) => done.has(dep)));
+    if (ready) {
+      ordered.push(byName.get(ready)!);
+      done.add(ready);
+      needs.delete(ready);
+      continue;
+    }
+    // Every table left waits on another table left — a cycle. Break it by
+    // deferring one edge: every column of the first remaining table that points
+    // at its first unmet dependency.
+    const [name, deps] = [...needs.entries()][0];
+    const dep = [...deps].find((d) => !done.has(d))!;
+    const table = byName.get(name)!;
+    for (const column of table.columns) {
+      if (column.references?.table === dep) deferred.push({ table, column });
+    }
+    deps.delete(dep);
+  }
+
+  return { ordered, deferred };
+}

package/src/query.ts

@@ -5,12 +5,7 @@ export interface QueryEvent {
   /** Which storage ran it — a process may open several (`sources:`). */
   storage: string;
   sql: string;
-  /**
-   * How MANY parameters, never their values.
-   *
-   * They are user data nobody chose to expose — the rule the call log states for a body.
-   * The count is what a reader needs anyway: it is how you see an `IN (?, ?, ?)` grow.
-   */
+  /** How MANY parameters, never their values. */
   parameters: number;
   /** Rounded to three decimals: a sub-microsecond statement reports 17 digits otherwise. */
   ms: number;
@@ -22,17 +17,7 @@ export type QuerySink = (event: QueryEvent) => void;
 
 const sinks: QuerySink[] = [];
 
-/**
- * Be told about every statement this process runs, and get the unsubscription back.
- *
- * A subscription and not an option, for one reason that decides it: Kysely takes its `log`
- * at CONSTRUCTION, and the storage is built during the boot — before any extension's
- * `up(app)` runs. So the only way to subscribe afterwards is for the log to be installed
- * from the start and route to whoever is listening.
- *
- * The same shape core states for `onLog` and observability for `onSpan`. Costs nothing when
- * nobody listens: `logQueries` returns on an empty list before touching the event.
- */
+/** Be told about every statement this process runs, and get the unsubscription back. */
 export function onQuery(sink: QuerySink): () => void {
   sinks.push(sink);
 

package/src/setup.ts

@@ -1,53 +1,46 @@
-/**
- * Storage setup — the shape every engine answers, and no driver at all.
- *
- * Fougere has no business choosing a driver (`pg`, `mysql2`, `tedious`, `better-sqlite3`,
- * a D1 binding), so the caller builds the Kysely dialect and hands it over — no dynamic
- * import, no optional dependency. This file therefore reaches for nothing: it is what a
- * runtime with no filesystem imports. The one driver this package does own lives behind
- * `@fougere/adapter-sql/sqlite`.
- */
+/** Storage setup — the shape every engine answers, and no driver at all. */
 import { Kysely, sql, type Dialect as KyselyDialect } from 'kysely';
-import { createOrmFactory, type OrmFactoryOptions } from './crud.js';
+import type { Source, SourceView } from '@fougere/core';
+import { createStorageFactory, type StorageFactoryOptions } from './crud.js';
 import { logQueries } from './query.js';
+import { migrate } from './diff.js';
+import { toTableName } from './table.js';
 import type { DialectName } from './dialect.js';
 import type { SqlSink } from './ddl.js';
 
 export interface SetupOptions {
   /** Override naming for specific entities (e.g. better-auth wants singular table names). */
-  ormFactoryOptions?: OrmFactoryOptions;
-  /**
-   * What to call this storage when a query is reported.
-   *
-   * A process may open several (`sources:`), and a module-level sink sees them all — without
-   * a name, two statements from two databases read as one stream. Defaults to what
-   * distinguishes them anyway: the engine here, the file path for SQLite.
-   */
+  storageFactoryOptions?: StorageFactoryOptions;
+  /** What to call this storage when a query is reported. */
   name?: string;
 }
 
-export interface Setup {
+/** A `Source` realized by SQL — and the three members that are SQL's, not the routing's. */
+export interface SqlSource extends Source {
   dialect: DialectName;
-  ormFactory: ReturnType<typeof createOrmFactory>;
+  storageFactory: ReturnType<typeof createStorageFactory>;
   /** Runs raw statements — what `autoMigrate` writes through. */
   sink: SqlSink;
   /**
-   * The Kysely instance, for what precedes any entity: `migrate(app, setup)` writes the
-   * schema through it, and a script may need it before a container exists.
-   *
-   * It is not the way to reach data from inside an app — that is the injected `EntityOrm`,
-   * whose `client` gives the same handle while keeping the scope of its entity.
+   * The Kysely instance, for what precedes any entity: `migrate(app, setup)` writes the schema
+   * through it, and a script may need it before a container exists.
    */
   db: Kysely<any>;
-  /**
-   * Run `fn` inside one transaction of this engine, with an ORM factory bound to it.
-   *
-   * The transaction belongs to the engine, so obtaining one is a gesture on the engine and
-   * nowhere else. Nothing new is handed back: `Transaction<DB> extends Kysely<DB>` and
-   * `SqlEntityOrm` takes a `Kysely<any>`, so the SAME ORM is rebuilt over the substituted
-   * connection — which is why a frame needs no support in this package.
-   */
-  transacted<R>(fn: (ormFactory: ReturnType<typeof createOrmFactory>) => Promise<R>): Promise<R>;
+  /** Run `fn` inside one transaction of this engine, with a storage factory bound to it. */
+  transacted<R>(fn: (storageFactory: ReturnType<typeof createStorageFactory>) => Promise<R>): Promise<R>;
+}
+
+/** The name this shape answered to before it was one realization among several. */
+export type Setup = SqlSource;
+
+/** The migration of what lives in ONE sql source, carrying its own dialect. */
+function migrating(db: Kysely<any>, dialect: DialectName, opts: SetupOptions) {
+  return async (view: SourceView): Promise<void> => {
+    await migrate(view as never, db, {
+      dialect,
+      tableName: opts.storageFactoryOptions?.tableName ?? toTableName,
+    });
+  };
 }
 
 /** A sink that runs statements through Kysely — works on every engine. */
@@ -60,13 +53,16 @@ export function setupKysely(
   kyselyDialect: KyselyDialect,
   dialect: DialectName,
   opts: SetupOptions = {},
-): Setup {
+): SqlSource {
   const db = new Kysely<any>({ dialect: kyselyDialect, log: logQueries(opts.name ?? dialect) });
   return {
     db,
     dialect,
-    ormFactory: createOrmFactory(db, opts.ormFactoryOptions, dialect),
+    storageFactory: createStorageFactory(db, opts.storageFactoryOptions, dialect),
     sink: sqlSink(db),
-    transacted: (fn) => db.transaction().execute((trx) => fn(createOrmFactory(trx, opts.ormFactoryOptions, dialect))),
+    migrate: migrating(db, dialect, opts),
+    close: () => db.destroy(),
+    name: opts.name ?? dialect,
+    transacted: (fn) => db.transaction().execute((trx) => fn(createStorageFactory(trx, opts.storageFactoryOptions, dialect))),
   };
 }

package/src/sqlite.ts

@@ -1,26 +1,21 @@
-/**
- * SQLite on a file — the convention a first run meets, and the only driver this package owns.
- *
- * It sits behind its own subpath because `better-sqlite3` is a NATIVE module and `node:fs`
- * is a builtin: a bundler cannot prune a module that imports them, so re-exporting this
- * from the index made the whole adapter unreachable from a runtime that has neither. Same
- * cut as `@fougere/transport-http/receive`, and for the same reason — share the projection,
- * never the plumbing.
- */
+/** SQLite on a file — the convention a first run meets, and the only driver this package owns. */
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Kysely, SqliteDialect } from 'kysely';
 import Database from 'better-sqlite3';
-import { createOrmFactory } from './crud.js';
+import { createStorageFactory } from './crud.js';
 import { logQueries } from './query.js';
-import { sqlSink, type Setup, type SetupOptions } from './setup.js';
+import { sqlSink, type SetupOptions, type SqlSource } from './setup.js';
+import { migrate } from './diff.js';
+import { toTableName } from './table.js';
+import { Sources, type Source, type SourceConfig, type SourceView } from '@fougere/core';
 
 export interface SqliteSetupOptions extends SetupOptions {
   /** Filesystem path to the database. Defaults to a project-local file. */
   path?: string;
 }
 
-export interface SqliteSetup extends Setup {
+export interface SqliteSetup extends SqlSource {
   /** The raw handle, for pragmas and synchronous exec. */
   sqlite: Database.Database;
 }
@@ -37,8 +32,27 @@ export function setupSqlite(opts: SqliteSetupOptions = {}): SqliteSetup {
     db,
     sqlite,
     dialect: 'sqlite',
-    ormFactory: createOrmFactory(db, opts.ormFactoryOptions, 'sqlite'),
+    storageFactory: createStorageFactory(db, opts.storageFactoryOptions, 'sqlite'),
     sink: sqlSink(db),
-    transacted: (fn) => db.transaction().execute((trx) => fn(createOrmFactory(trx, opts.ormFactoryOptions, 'sqlite'))),
+    migrate: async (view: SourceView) => {
+      await migrate(view as never, db, { dialect: 'sqlite', tableName: opts.storageFactoryOptions?.tableName ?? toTableName });
+    },
+    close: () => db.destroy(),
+    name: opts.name ?? path,
+    transacted: (fn) => db.transaction().execute((trx) => fn(createStorageFactory(trx, opts.storageFactoryOptions, 'sqlite'))),
   };
 }
+
+/** `source. */
+Sources.register('sql', (conf: SourceConfig): Source => {
+  const dialect = conf.dialect as string | undefined;
+  if (dialect !== undefined && dialect !== 'sqlite') {
+    throw new Error(
+      `source 'sql', dialect '${dialect}': cannot be built from a name — only 'sqlite' can, `
+      + 'because it is the one driver this package owns. Build the Kysely dialect yourself and '
+      + `call setupKysely(dialect, '${dialect}'), then hand it in as a source.`,
+    );
+  }
+
+  return setupSqlite({ path: conf.path as string | undefined, name: conf.name as string | undefined });
+});

package/src/step.ts

@@ -1,15 +1,4 @@
-/**
- * The half `delta()` refuses — realised from an intention that was written down.
- *
- * `diff.ts` states its own guarantee: additive only, because "a rename is not even
- * detectable from a diff (it reads as a drop plus an add)". That still holds, and this
- * file does not weaken it. What changed is upstream: a frozen step (`fougere freeze`)
- * carries a rename because a human declared it at the moment they made it. The intention
- * exists now, so it can be realised — and only what the step actually says.
- *
- * A drop and a rename both touch live data, so this is the only place either can come
- * from: never introspection, never a guess.
- */
+/** The half `delta()` refuses — realised from an intention that was written down. */
 import { sql, type Kysely } from 'kysely';
 import type { Change as ShapeChange, SetDiff } from '@fougere/schema';
 import { dequal } from 'dequal';
@@ -42,25 +31,11 @@ export interface Plan {
 export interface PlanOptions {
   /** Entity key → table name. Same resolver `desiredTables` takes. */
   tableName?: (name: string) => string;
-  /**
-   * What the database actually holds, from `actualState`. Given, a change already
-   * realised is skipped.
-   *
-   * Idempotence by OBSERVATION and not by bookkeeping — the same choice `delta` makes.
-   * A ledger of applied steps would be a second record of a fact the columns already
-   * carry, and the two would disagree the day someone renamed a column by hand.
-   */
+  /** What the database actually holds, from `actualState`. */
   actual?: SchemaState;
 }
 
-/**
- * Collapse a chain of steps into one, following each field through its renames.
- *
- * A step judges itself on two names — old gone, new here — so an intermediate rename is
- * unrecognisable once its target has been renamed again: both names are absent and it is
- * proposed forever. Composing the chain first asks the question about the name the field
- * ENDS on, which is the only one the tables can answer.
- */
+/** Collapse a chain of steps into one, following each field through its renames. */
 export function collapseChain(steps: readonly SetDiff[]): SetDiff {
   const entities: SetDiff['entities'] = {};
   const added: string[] = [];
@@ -70,9 +45,9 @@ export function collapseChain(steps: readonly SetDiff[]): SetDiff {
     added.push(...step.entitiesAdded);
     removed.push(...step.entitiesRemoved);
     for (const [entity, answer] of Object.entries(step.entities)) {
-      const held = (entities[entity] ??= { changes: [], ambiguous: [] });
-      held.ambiguous.push(...answer.ambiguous);
-      for (const change of answer.changes) compose(held.changes, change);
+      const entry = (entities[entity] ??= { changes: [], ambiguous: [] });
+      entry.ambiguous.push(...answer.ambiguous);
+      for (const change of answer.changes) compose(entry.changes, change);
     }
   }
 
@@ -80,9 +55,8 @@ export function collapseChain(steps: readonly SetDiff[]): SetDiff {
 }
 
 /**
- * Add one change to what the chain has said so far, rewriting rather than appending when
- * it continues a field already moved. A rename back to its origin cancels: the tables
- * never held the name in between, so there is nothing for them to do.
+ * Add one change to what the chain has said so far, rewriting rather than appending when it
+ * continues a field already moved.
  */
 function compose(held: ShapeChange[], change: ShapeChange): void {
   if (change.kind === 'renamed') {
@@ -113,11 +87,7 @@ function compose(held: ShapeChange[], change: ShapeChange): void {
   held.push({ ...change, field: origin.from });
 }
 
-/**
- * Turn a frozen step into what the tables must do, and what nobody may decide for you.
- *
- * Pure, like `delta` — the comparison is one thing, running it is another.
- */
+/** Turn a frozen step into what the tables must do, and what nobody may decide for you. */
 export function planStep(step: SetDiff, tables: TableDef[], options: PlanOptions = {}): Plan {
   const resolve = options.tableName ?? toTableName;
   const actual = options.actual;
@@ -191,7 +161,7 @@ function realise(
 
     case 'reshaped':
       // A tightened bound is a CHECK, and altering one on a live table is engine-specific
-      // AND may be refused by rows already stored. The judge still enforces it at the door.
+      // AND may be refused by rows already stored. The validator still enforces it at the door.
       return {
         entity,
         field: change.field,
@@ -203,13 +173,7 @@ function realise(
   }
 }
 
-/**
- * An axis other than shape moved. Only some of it is a fact about the table.
- *
- * `boundary` never is — it says who may read or write, which no column holds. `lifecycle`
- * is one only through the DEFAULT clause. `role` is one three times over, and two of those
- * are constraints a live table may already contradict.
- */
+/** An axis other than shape moved. */
 function restated(entity: string, change: Extract<ShapeChange, { kind: 'restated' }>): { change?: StepChange } | Refusal {
   const refuse = (reason: string): Refusal => ({ entity, field: change.field, reason });
 
@@ -246,13 +210,7 @@ function literalOf(rules: { create?: unknown } | undefined): unknown {
 
 const show = (value: unknown): string => (value === undefined ? 'none' : JSON.stringify(value));
 
-/**
- * Has the table already moved? Read off the columns themselves.
- *
- * A rename whose old name is gone and whose new one is there has happened; a drop whose
- * column is absent has happened. Unknown state (no introspection given) answers no, so a
- * plan built without it proposes everything the step says.
- */
+/** Has the table already moved? Read off the columns themselves. */
 function done(change: StepChange, columns: Set<string> | undefined): boolean {
   if (!columns) return false;
   return change.kind === 'renameColumn'