@fougere/adapter-sql 0.6.0-alpha.0 → 0.8.0-alpha.0

package/src/table.ts

@@ -1,18 +1,8 @@
 import { Lifecycle, Role } from '@fougere/schema';
-/**
- * Entity → table description, with no SQL in sight.
- *
- * This is the neutral middle term: one projection reads the entity's axes and
- * produces a `TableDef`; a `Dialect` turns that into SQL. Neither half knows the
- * other — the dialect never mentions a field. Adding a dialect touches only the
- * second half.
- *
- * `ColumnDef.stated` is the one member the axes did not produce. It names one engine's
- * column type, so dropping it leaves every column describable.
- */
-import { Anatomy, FieldGroup, Unique, fieldsOf, lowerFirst, schemaOf, type Field, type SchemaView, type SchemaOrCard } from '@fougere/schema';
+/** Entity → table description, with no SQL in sight. */
+import { Shapes, lowerFirst, type Field, type SchemaView } from '@fougere/schema';
 import { boundsOf, type ShapeBounds } from './check.js';
-import type { SqlField } from './fields.js';
+import { sqlEntries, type SqlField } from './fields.js';
 
 /** The shape keywords a dialect needs to choose a column type. */
 export interface ColumnShape {
@@ -62,11 +52,7 @@ export interface TableDef {
   columns: ColumnDef[];
   /** PK column names when the key is composite — empty for a simple key. */
   compositePrimary: string[];
-  /**
-   * Column groups unique together, from `entity(fields, { unique: [...] })`.
-   * A single-field group is left to the column's own `unique` — this is the
-   * table-level form, for facts no column can hold alone.
-   */
+  /** Column groups unique together, from `entity(fields, { unique: [...] })`. */
   uniqueGroups: string[][];
 }
 
@@ -83,11 +69,7 @@ function isStored(field: Field): boolean {
   return !Role.of(field).isCollection;
 }
 
-/**
- * The target's primary key column. A live thunk (an in-process entity) answers
- * for real; a relation reconstructed from a lone `Card` (without a `Bundle`) has lost it to a
- * name stand-in with no `getFields` — the convention there is to assume `id`.
- */
+/** The target's primary key column. */
 function primaryColumnOf(target: Partial<SchemaView>): string {
   if (typeof target.getFields !== 'function') return 'id';
   for (const [name, field] of Object.entries(target.getFields())) {
@@ -96,28 +78,11 @@ function primaryColumnOf(target: Partial<SchemaView>): string {
   return 'id'; // declared no primary() field — defensive, shouldn't happen
 }
 
-/**
- * The FK target for a `ref()` field: the table it points at plus its PK column.
- *
- * `tableNameOf` is an identity map — built once per app generation pass, see
- * {@link toTables} — from a LIVE entity class to the table name already resolved
- * for it. Reusing that name (instead of re-deriving one from the class name) is
- * what keeps a custom `tableName` resolver honest: `demos/schema-ecommerce`
- * names `Category`'s table `"categories"` (an irregular plural its resolver
- * special-cases) — re-deriving from `Category.name` through the DEFAULT
- * convention would silently produce `"categorys"` instead.
- *
- * A miss (the target isn't part of this batch — a cross-frond target, or a live
- * class the app substituted for one a package hardcoded — e.g.
- * `@fougere/auth-better`'s `AuthSession` always points at its own default
- * `AuthUser`, never at whatever `opts.user` the app actually registered) falls
- * back to deriving the name from the class — correct when that class follows
- * the default convention, wrong if the app ALSO overrides `tableName` for it.
- */
+/** The FK target for a `ref()` field. */
 function referenceFor(
   field: Field,
   resolve: (name: string) => string,
-  tableNameOf?: Map<SchemaOrCard, string>,
+  tableNameOf?: Map<SchemaView, string>,
   hosted?: HostedNames,
 ): ColumnReference | undefined {
   const relation = Role.of(field).relation;
@@ -156,14 +121,14 @@ function toColumn(
   fieldName: string,
   field: Field,
   resolve: (name: string) => string,
-  tableNameOf?: Map<SchemaOrCard, string>,
+  tableNameOf?: Map<SchemaView, string>,
   hosted?: HostedNames,
   stated?: SqlField,
 ): ColumnDef {
   // The column type comes from the `shape` axis alone. `anatomy` strips the
   // nullable union so a nullable integer stays an integer instead of falling
   // through to text.
-  const { base, nullable } = Anatomy.of(field.shape);
+  const { base, nullable } = Shapes.of(field.shape);
   const lifecycle = Lifecycle.of(field);
   const column: ColumnDef = {
     field: fieldName,
@@ -180,8 +145,7 @@ function toColumn(
   // redundant constraint on every engine. So would indexing what `unique` constrains.
   // Only a constraint of ONE becomes a column constraint; a group of several is a table
   // constraint, emitted once from `uniqueGroups` rather than once per member column.
-  const soleUnique = FieldGroup.on(field, Unique).some((group) => group.members.length <= 1);
-  if (soleUnique && !column.primary) column.unique = true;
+  if (Role.of(field).isUnique && !column.primary) column.unique = true;
   if (Role.of(field).isIndexed && !column.primary && !column.unique) column.index = true;
   const references = referenceFor(field, resolve, tableNameOf, hosted);
   if (references) column.references = references;
@@ -194,7 +158,7 @@ export interface RelationResolve {
   /** Same resolver used for every entity's own table (default or a custom `tableName`). */
   resolve: (name: string) => string;
   /** Live entity class → its already-resolved table name, reused instead of re-derived. */
-  tableNameOf?: Map<SchemaOrCard, string>;
+  tableNameOf?: Map<SchemaView, string>;
   /** Which entities this batch holds and which live in another source — decided by NAME. */
   hosted?: HostedNames;
 }
@@ -207,46 +171,29 @@ export interface HostedNames {
   elsewhere: ReadonlySet<string>;
 }
 
-/**
- * Describe one entity as a table — the single reader of the axes.
- *
- * Takes the entity as a live class or as a card. Read ONCE into `fields`: `fieldsOf`
- * reconstructs a descriptor on each call, so re-reading per loop would rebuild the schema
- * as many times as this function iterates.
- *
- * A lone card has no live relation targets, so a `ref()` falls back to the conventions
- * `referenceFor`/`primaryColumnOf` already document (name-derived table, `id` as the key).
- * Pass a descriptor through `Bundle.toSchemas` first when the FKs matter — it resolves the
- * targets, and its output is the live-class case again.
- */
-export function toTable(tableName: string, entity: SchemaOrCard, relations?: RelationResolve): TableDef {
+/** Describe one entity as a table — the single reader of the axes. */
+export function toTable(tableName: string, schema: SchemaView, relations?: RelationResolve): TableDef {
   const resolve = relations?.resolve ?? toTableName;
-  const fields = fieldsOf(entity);
+  const fields = schema.getFields();
   // Read off the entity, since that is where it is declared and addressed by field key.
-  const stated = schemaOf(entity).getAdapters()?.sql;
+  const configuration = schema.getAdapters().sql;
+  // Judged HERE and not at `entity()`: this runs at boot, after every import, so the
+  // format is always loaded. A validator registered with `schema` would depend on which
+  // module was imported first.
+  sqlEntries.assert(configuration, `${schema.name}.adapters.sql`);
   const columns: ColumnDef[] = [];
   for (const [fieldName, field] of Object.entries(fields)) {
     if (!isStored(field)) continue;
-    columns.push(toColumn(fieldName, field, resolve, relations?.tableNameOf, relations?.hosted, stated?.[fieldName]));
+    columns.push(toColumn(fieldName, field, resolve, relations?.tableNameOf, relations?.hosted, configuration?.[fieldName]));
   }
   const primaries = columns.filter((column) => column.primary).map((column) => column.name);
   const stored = new Set(columns.map((column) => column.name));
-  // Read off the fields, not off `getUnique()`: a card has no entity-level declaration to
-  // offer, and the members carry the same fact either way. One reader for both forms.
-  //
-  // Declared in field names, realized in column names — and a group that names a field the
-  // storage does not keep is not enforceable, so it is dropped here rather than emitted
-  // against a column that will not exist.
-  const groups = new Map<string, string[]>();
-  for (const [fieldName, field] of Object.entries(fields)) {
-    for (const group of FieldGroup.on(field, Unique)) {
-      const members = group.resolvedOn(fieldName).members.map(toSnakeCase);
-      if (members.length > 1 && members.every((column) => stored.has(column))) {
-        groups.set(members.join(' '), members);
-      }
-    }
-  }
-  const uniqueGroups = [...groups.values()];
+  // Declared in field names, realized in column names — and a group naming a field the
+  // storage does not keep is not enforceable, so it is dropped rather than emitted against
+  // a column that will not exist.
+  const uniqueGroups = (schema.getUnique() ?? [])
+    .map((group) => group.map(toSnakeCase))
+    .filter((members) => members.every((column) => stored.has(column)));
 
   return {
     name: tableName,
@@ -257,12 +204,8 @@ export function toTable(tableName: string, entity: SchemaOrCard, relations?: Rel
 }
 
 /**
- * Is this column part of a key? MySQL and SQL Server refuse an unbounded text
- * column in a primary key or an index, so the dialect needs to know.
- *
- * `unique` and `index` count, and until they could be declared nothing did but the
- * primary key — the comment above already said "or an index" while the code answered
- * for the key alone, because no vocabulary word produced one to answer for.
+ * Is this column part of a key? MySQL and SQL Server refuse an unbounded text column in a primary
+ * key or an index, so the dialect needs to know.
  */
 export function isKeyed(table: TableDef, column: ColumnDef): boolean {
   return column.primary
@@ -280,8 +223,8 @@ export function toTableName(name: string): string {
 
 export interface EntityEntry {
   name: string;
-  /** A live class in-process, a card from a frond whose class never crossed. */
-  entityClass: SchemaOrCard;
+  /** A live class in-process, or one rebuilt from the card of a frond that never crossed. */
+  entityClass: SchemaView;
 }
 
 export interface FrondLike {
@@ -292,43 +235,25 @@ export interface FrondLike {
 export interface AppLike {
   fronds: FrondLike[];
   /** Auth runtime entities are migrated alongside scanned fronds when present. */
-  auth?: { entities: Record<string, SchemaOrCard> };
-  /**
-   * Entities this app hosts in ANOTHER source — named so a miss can be read.
-   *
-   * Without it every miss looked alike, so a `ref()` fell back to a derived table name
-   * and the constraint was emitted against a table that might not exist. Absent means
-   * one source, where a miss can only be a mistake.
-   */
+  auth?: { entities: Record<string, SchemaView> };
+  /** Entities this app hosts in ANOTHER source — named so a miss can be read. */
   elsewhere?: string[];
 }
 
-/**
- * A schema says whether it holds rows; this adapter decides what to emit for it.
- *
- * A root always did. A derivation describes ANOTHER's rows — `Post.pick('id','title')` is
- * a shape, and one dropped under `entities/` used to get a table of its own: measured on a
- * real app, where a projection of an archived entity created a duplicate in the OTHER
- * database. `.anchor()` is what says otherwise, and it is the entity's own word, never a
- * key of the app's config: a frond stays mountable without its host knowing.
- */
+/** A schema says whether it holds rows; this adapter decides what to emit for it. */
 function verdictOn(entry: EntityEntry): 'table' | 'answer' {
-  const schema = schemaOf(entry.entityClass);
+  const { entityClass } = entry;
 
-  return !schema.derivation || schema.anchored ? 'table' : 'answer';
+  return !entityClass.derivation || entityClass.anchored ? 'table' : 'answer';
 }
 
-/**
- * Every entity this app hosts, once each. The same class reaches here under one
- * registration name from two lists — a frond's `entities/` and the auth runtime's map —
- * and two entries for one name are two CREATE TABLE for one table.
- */
+/** Every entity this app hosts, once each. */
 function collectEntities(app: AppLike): EntityEntry[] {
   const entries: EntityEntry[] = [];
-  const held = new Set<string>();
+  const seen = new Set<string>();
   const hold = (entry: EntityEntry) => {
-    if (held.has(lowerFirst(entry.name))) return;
-    held.add(lowerFirst(entry.name));
+    if (seen.has(lowerFirst(entry.name))) return;
+    seen.add(lowerFirst(entry.name));
     entries.push(entry);
   };
 
@@ -345,14 +270,12 @@ function collectEntities(app: AppLike): EntityEntry[] {
 }
 
 /**
- * Every entity an app hosts, as FK-aware tables — the shared middle step behind
- * `generateSQL` (a from-scratch create pass) and `desiredTables` (the diff's
- * target state). Builds the identity map once (see `referenceFor`'s doc) so a
- * `ref()` target reuses the SAME resolved name as the entity's own table.
+ * Every entity an app hosts, as FK-aware tables — the shared middle step behind `generateSQL` (a
+ * from-scratch create pass) and `desiredTables` (the diff's target state).
  */
 export function toTables(app: AppLike, resolve: (name: string) => string): TableDef[] {
   const entries = collectEntities(app);
-  const tableNameOf = new Map<SchemaOrCard, string>(entries.map((entry) => [entry.entityClass, resolve(entry.name)]));
+  const tableNameOf = new Map<SchemaView, string>(entries.map((entry) => [entry.entityClass, resolve(entry.name)]));
   const hosted = app.elsewhere
     ? { here: new Set(entries.map((entry) => lowerFirst(entry.name))), elsewhere: new Set(app.elsewhere.map(lowerFirst)) }
     : undefined;
@@ -360,69 +283,3 @@ export function toTables(app: AppLike, resolve: (name: string) => string): Table
 }
 
 // ─── Ordering — a referenced table before its referrer ─────────────────────
-
-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).
- *
- * A cycle (`Post → Author → Post`, legal in the model — role.ts's relation
- * thunk exists precisely so two entities can reference each other) has no such
- * order: the loop is broken by deferring ONE of its edges per remaining cycle —
- * that FK is added after every table exists, instead of inline. A self-reference
- * (`parentId: ref(() => Category)`) is not a cycle here: a table may always
- * reference its own not-yet-populated rows inline, standard support across
- * every engine — so it's excluded from the dependency graph 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/values.ts

@@ -1,20 +1,4 @@
-/**
- * The values a driver accepts, and the values an entity declares.
- *
- * A driver binds numbers, strings, buffers and null — nothing else. An entity declares
- * booleans, dates, lists and objects. Something has to sit between the two, and until
- * now nothing did: `done: bool()` threw at insert ("SQLite3 can only bind numbers,
- * strings, bigints, buffers, and null"), a `date()` could only be written as the ISO
- * string its own type forbids, and both came back as whatever the column held.
- *
- * The pair below is derived from the column's shape alone — no new declaration, no axis
- * to read. It lives in the storage adapter because that is where the driver's limits are
- * known; the entity keeps saying `boolean` and `Date`.
- *
- * Drivers differ in how much they already do (Postgres hands back real booleans and
- * Dates, SQLite hands back 0/1 and text), so every read guards on what it actually got
- * instead of assuming.
- */
+/** The values a driver accepts, and the values an entity declares. */
 import type { ColumnShape } from './table.js';
 
 export interface ValueCodec {
@@ -46,13 +30,8 @@ const json: ValueCodec = {
 };
 
 /**
- * A driver may answer a number as a BigInt — Postgres does it for `count(*)` and for
- * `bigint` columns, DuckDB for every count. The entity declares a number, so that is
- * what comes back.
- *
- * Out of range it REFUSES rather than rounding. `Number(9007199254740993n)` is
- * `9007199254740992` — a wrong answer, silently, and the row would look fine. A value
- * that large is a real identifier somewhere, and its field should say `text()`.
+ * A driver may answer a number as a BigInt — Postgres does it for `count(*)` and for `bigint`
+ * columns, DuckDB for every count.
  */
 const numeric: ValueCodec = {
   write: (v) => (typeof v === 'bigint' ? fits(v) : v),