uql-orm 0.65.1 → 0.67.0

package/dist/querier/abstractSqlQuerier.js

@@ -1,19 +1,14 @@
 import { COUNT_ALIAS, TOTAL_ALIAS } from '../dialect/aliases.js';
 import { decodeColumn } from '../dialect/hydrateColumn.js';
-import { getMeta, idOf, namesKey } from '../entity/index.js';
+import { getMeta, namesKey } from '../entity/index.js';
 import { COUNT_RESULT_KEY } from '../type/index.js';
-import { buildUpdateResult, cascadesOnDelete, clone, getInsertFieldKeys, insertShapeOf, idOnlyQuery, isAutoIncrement, isPagedQuery, isRecord, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, whereIds, withoutSoftDeleteFilter, } from '../util/index.js';
+import { buildUpdateResult, clone, getInsertFieldKeys, insertShapeOf, isAutoIncrement, isRecord, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
 import { streamViaCursor } from './cursorStream.js';
 import { enrichError } from './queryError.js';
 /**
- * Row indexes grouped by whether the caller supplied the key, payload order kept within each group.
- * One group when the batch agrees on it, which is the single statement it has always been.
- *
- * Deliberately coarser than {@link groupByInsertShape}, and the two must not be merged: an insert's
- * `VALUES` list takes the union of the batch's columns and fills the rest with `DEFAULT`, so the
- * key's presence is the only thing that changes what the statement can report. Splitting an insert
- * by full shape instead would turn a batch of optional fields into a statement per combination.
+ * Row indexes split by whether the row names its key, the one thing that changes what an insert can
+ * report; coarser than {@link groupByInsertShape} on purpose, since an insert fills a missing column with `DEFAULT`.
  */
 function partitionBySuppliedId(payload, idKey) {
     const supplied = [];
@@ -110,15 +105,21 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             return this.timed(query, values, () => this.internalRun(query, this.dialect.normalizeValues(values)));
         });
     }
+    /** The rows of a statement the dialect builds. */
+    query(build) {
+        const ctx = this.dialect.createContext();
+        build(ctx);
+        return this.all(ctx.sql, ctx.values);
+    }
+    /** Runs a statement the dialect builds. */
+    exec(build) {
+        const ctx = this.dialect.createContext();
+        build(ctx);
+        return this.run(ctx.sql, ctx.values);
+    }
     /**
-     * `$lock` outside a transaction is always a bug, and a silent one. Every engine accepts
-     * `SELECT ... FOR UPDATE` in autocommit and then releases the lock as the statement commits,
-     * before the caller has seen a row: the SQL is correct, nothing is omitted, and no layer below
-     * this one can tell. The dialect cannot check it either, being stateless and shared by every
-     * connection of the pool, so this is the only place it can be caught.
-     *
-     * The capability check runs first on purpose: "this engine has no row locks" is the more
-     * actionable answer, and on SQLite it is the answer either way.
+     * Refuses a `$lock` the engine lacks, then one outside a transaction, where the lock would drop as the
+     * statement commits; only the querier knows whether one is open.
      */
     assertLockable(entity, q) {
         if (!q.$lock) {
@@ -130,14 +131,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         }
     }
     /**
-     * Run the `SET`s that tune an ANN index for this query, and refuse the ones that would not apply.
-     *
-     * Same shape as {@link assertLockable} and for the same reason: a `SET LOCAL` outside a transaction
-     * is accepted, applies to nothing, and leaves the query running at the engine's default recall -
-     * correct SQL, silently untuned. Only the querier knows whether a transaction is open.
-     *
-     * The statements go through `internalRun`, sharing this querier's single connection with the query
-     * they precede; `SET LOCAL` then expires with the transaction, so nothing is left behind.
+     * Runs the `SET`s tuning an ANN index for the query on its connection, refusing where they would apply to
+     * nothing: a `SET LOCAL` outside a transaction.
      */
     async applyVectorTuning(entity, q) {
         // Resolved before the transaction check, so the refusal fires only where the tuning would have
@@ -147,7 +142,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         if (!statements.length) {
             return;
         }
-        if (this.dialect.vectorTuningNeedsTransaction && !this.hasOpenTransaction) {
+        if (this.dialect.features.vectorTuningNeedsTransaction && !this.hasOpenTransaction) {
             throw new TypeError(`$candidates requires an open transaction on ${this.dialect.dialectName}; run the query inside pool.transaction(...)`);
         }
         for (const statement of statements) {
@@ -157,39 +152,23 @@ export class AbstractSqlQuerier extends AbstractQuerier {
     async internalFindMany(entity, q, opts) {
         return this.hydrateRows(entity, await this.selectRows(entity, q, opts));
     }
-    /**
-     * How to count when the total cannot ride along in the read's own `COUNT(*) OVER ()` column, or
-     * `undefined` when it can. Two clauses rule the window out: `$distinct`, because a window counts
-     * before the deduplication and so overstates the page, and `$lock` on an engine that refuses the
-     * pair outright. Both then cost a second statement; only the counting differs.
-     */
-    countedSeparately(entity, q, opts) {
-        if (q.$distinct) {
-            return (ctx) => this.dialect.countDistinct(ctx, entity, q, opts);
-        }
-        if (q.$lock && !this.dialect.supportsWindowWithRowLock) {
-            return (ctx) => this.dialect.count(ctx, entity, q, opts);
-        }
-        return undefined;
+    /** Every row `q` matches past its page, deduplicated where it reads `$distinct`. */
+    countUnpaged(entity, q, opts) {
+        return q.$distinct
+            ? this.runCount((ctx) => this.dialect.countDistinct(ctx, entity, q, opts))
+            : this.internalCount(entity, { $where: q.$where }, opts);
     }
     /**
-     * One statement for both: the page carries its own unpaged total in an extra column. An empty page
-     * has no row to carry it, which is the one case still needing a count of its own - a `$skip` past
-     * the end, or a filter nothing matched.
-     *
-     * A `$required` relation needs no special case: the window counts what the INNER JOIN left, which
-     * is exactly the total a caller of a filtered read is asking for. A `$lock` is the one clause an
-     * engine may refuse to have in the same statement, which {@link AbstractSqlDialect.supportsWindowWithRowLock}
-     * answers; where it does, the total comes from a count of its own. A `$distinct` read needs one
-     * too, and a deduplicating one: see {@link AbstractSqlDialect.countDistinct}.
+     * The page and its unpaged total in one statement, a window column on each row, and a count of its own for
+     * an empty page. A window counts before `DISTINCT`, and the Postgres family refuses one beside a `$lock`,
+     * so those count apart.
      */
     async internalFindManyAndCount(entity, q, opts) {
-        const separately = this.countedSeparately(entity, q, opts);
-        if (separately) {
-            return Promise.all([this.internalFindMany(entity, q, opts), this.runCount(separately)]);
+        if (q.$distinct || (q.$lock && !this.dialect.features.rowLockWithWindow)) {
+            return Promise.all([this.internalFindMany(entity, q, opts), this.countUnpaged(entity, q, opts)]);
         }
         const rows = await this.selectRows(entity, q, opts, TOTAL_ALIAS);
-        const total = rows.length ? Number(rows[0][TOTAL_ALIAS]) : await this.internalCount(entity, q, opts);
+        const total = rows.length ? Number(rows[0][TOTAL_ALIAS]) : await this.countUnpaged(entity, q, opts);
         for (const row of rows) {
             delete row[TOTAL_ALIAS];
         }
@@ -203,9 +182,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         if (q.$candidates !== undefined) {
             await this.applyVectorTuning(entity, q);
         }
-        const ctx = this.dialect.createContext();
-        this.dialect.find(ctx, entity, q, opts, totalAlias);
-        return this.all(ctx.sql, ctx.values);
+        return this.query((ctx) => this.dialect.find(ctx, entity, q, opts, totalAlias));
     }
     hydrateRows(entity, rows) {
         const founds = unflatObjects(rows);
@@ -219,8 +196,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             await this.applyVectorTuning(entity, q);
         }
         const meta = getMeta(entity);
-        // The one path that does not go through `all`/`run`, so it connects on its own: streaming first on
-        // a freshly acquired querier used to reach `getConn()` with nothing acquired.
+        // The one path not going through `all`/`run`, so it connects on its own.
         await this.lazyConnect();
         // No `normalizeValues` here, unlike `all`/`run`: those also take raw SQL, while every value a
         // context holds was normalized as it was bound.
@@ -319,21 +295,17 @@ export class AbstractSqlQuerier extends AbstractQuerier {
      * a catalog that does not know the table answers with no row, which is nothing counted.
      */
     async runCount(build) {
-        const ctx = this.dialect.createContext();
-        build(ctx);
-        const res = await this.all(ctx.sql, ctx.values);
-        return Number(res[0]?.[COUNT_ALIAS] ?? 0);
+        const [row] = await this.query(build);
+        return Number(row?.[COUNT_ALIAS] ?? 0);
     }
-    async internalCount(entity, q = {}, opts) {
+    async internalCount(entity, q, opts) {
         return this.runCount((ctx) => this.dialect.count(ctx, entity, q, opts));
     }
     async estimatedCount(entity) {
         return this.runCount((ctx) => this.dialect.estimatedCount(ctx, entity));
     }
     async internalAggregate(entity, q, opts) {
-        const ctx = this.dialect.createContext();
-        this.dialect.aggregate(ctx, entity, q, opts);
-        const rows = await this.all(ctx.sql, ctx.values);
+        const rows = await this.query((ctx) => this.dialect.aggregate(ctx, entity, q, opts));
         const hydratable = this.dialect.hydratableAggregates(entity, q);
         for (const row of rows) {
             const cells = row;
@@ -354,12 +326,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const idField = sole ? meta.fields[idKey] : undefined;
         const generatedKey = !!idField && isAutoIncrement(idField, true);
         for (const group of partitionBySuppliedId(rows, idKey)) {
-            // RETURNING-based ids are exact per row. Header-derived ones (LAST_INSERT_ID / lastInsertRowid
-            // arithmetic) are only sound when the key is database-generated and every row *in this
-            // statement* left it to the database. That is a property of the statement, not of the batch:
-            // asking it of the whole batch meant one supplied id made every id `undefined`, which a
-            // cascade then wrote into a child as a null foreign key. Splitting on that one axis costs at
-            // most one extra statement and keeps each of them inferable.
+            // Header ids are only sound where every row of this statement left its key to the database, so
+            // the batch is split on that alone, and a supplied id cannot void the others.
             const idsReliable = sole &&
                 (this.dialect.insertIdSource === 'returning' ||
                     (generatedKey && group.every((index) => rows[index][idKey] === undefined)));
@@ -371,9 +339,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             // Per group, not per batch: the two carry different columns - one names the key, one does not -
             // so a budget taken over their union would under-fill the statement that is missing one.
             for (const indexes of chunkByBindBudget(meta, rows, group, this.dialect.maxBindValues)) {
-                const ctx = this.dialect.createContext();
-                this.dialect.insert(ctx, entity, indexes.map((index) => rows[index]));
-                const { ids = [] } = await this.run(ctx.sql, ctx.values);
+                const chunk = indexes.map((index) => rows[index]);
+                const { ids = [] } = await this.exec((ctx) => this.dialect.insert(ctx, entity, chunk));
                 if (idsReliable) {
                     for (let position = 0; position < indexes.length; position++) {
                         rows[indexes[position]][idKey] ??= ids[position];
@@ -384,31 +351,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         await this.insertRelations(entity, rows);
     }
     async internalUpdateMany(entity, q, payload, opts) {
-        payload = clone(payload);
-        // Settled first for the reason `internalDeleteMany` settles: `ORDER BY`/`LIMIT` on an UPDATE is
-        // MySQL's alone, so a paged update has to name the rows it picked.
-        let target = q;
-        if (isPagedQuery(q)) {
-            const ids = await this.settleIds(entity, q, opts);
-            if (!ids.length) {
-                return 0;
-            }
-            target = { $where: whereIds(getMeta(entity), ids) };
-        }
-        const ctx = this.dialect.createContext();
-        this.dialect.update(ctx, entity, target, payload, opts);
-        const { changes = 0 } = await this.run(ctx.sql, ctx.values);
-        await this.updateRelations(entity, target, payload, opts);
+        const { changes = 0 } = await this.exec((ctx) => this.dialect.update(ctx, entity, q, payload, opts));
         return changes;
     }
-    /** The ids matching `q`, in `q`'s own order and page, so a write can name the rows it settled on. */
-    async settleIds(entity, q, opts) {
-        const meta = getMeta(entity);
-        const ctx = this.dialect.createContext();
-        this.dialect.find(ctx, entity, idOnlyQuery(meta, q), opts);
-        const founds = await this.all(ctx.sql, ctx.values);
-        return founds.map((found) => idOf(meta, found));
-    }
     async internalUpsertOne(entity, conflictPaths, payload) {
         return this.internalUpsertMany(entity, conflictPaths, [payload]);
     }
@@ -425,12 +370,8 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         if (statements.length === 1) {
             return this.runUpsert(entity, conflictPaths, payload);
         }
-        // `ON CONFLICT DO UPDATE SET` carries one assignment list for the whole statement, so rows of
-        // different shapes cannot share one. Neither obvious single-statement form works: taking the
-        // union writes the omitting row's `DEFAULT` (null) over a column it never mentioned, and
-        // sampling one row drops every column that row happens to lack. One statement per shape is the
-        // only form that writes exactly what each row asked for. Transactional because it is now more
-        // than one statement; `transaction` is re-entrant, so this is free inside a caller's own.
+        // An upsert's assignment list is the statement's, so rows of different shapes go in statements
+        // of their own, together in a transaction (`transaction` is re-entrant).
         return this.transaction(async () => {
             let changes = 0;
             // Placed by index, since grouping by shape reorders the rows. A statement reporting fewer ids
@@ -453,10 +394,9 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const meta = getMeta(entity);
         // Asked first: the statement fills an `onInsert` key into these rows whether it inserts them or not.
         const unnamed = meta.ids.length === 1 && payload.some((row) => !namesKey(meta, row));
-        const ctx = this.dialect.createContext();
-        this.dialect.upsert(ctx, entity, conflictPaths, payload);
-        const result = await this.run(ctx.sql, ctx.values);
-        const ordered = payload.length === 1 || (this.dialect.insertIdSource === 'returning' && this.dialect.upsertReturningOrdered);
+        const result = await this.exec((ctx) => this.dialect.upsert(ctx, entity, conflictPaths, payload));
+        const ordered = payload.length === 1 ||
+            (this.dialect.insertIdSource === 'returning' && this.dialect.features.orderedUpsertReturning);
         if (ordered && result.ids?.length === payload.length) {
             return result;
         }
@@ -470,29 +410,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             : { changes, created };
     }
     async internalDeleteMany(entity, q, opts) {
-        const meta = getMeta(entity);
-        // Resolving the ids first is what makes the two hard cases work at all: a cascade needs its
-        // parents' ids to find their children, and no engine but MySQL accepts `ORDER BY`/`LIMIT` on a
-        // DELETE, so a paged delete has to name the rows it settled on. A plain predicate needs neither,
-        // and there the round trip buys nothing: the statement can say what the caller already said.
-        if (!isPagedQuery(q) && !cascadesOnDelete(meta)) {
-            const ctx = this.dialect.createContext();
-            this.dialect.delete(ctx, entity, q, opts);
-            const { changes = 0 } = await this.run(ctx.sql, ctx.values);
-            return changes;
-        }
-        // A hard delete also targets already-soft-deleted rows, so drop the soft-delete filter when finding ids.
-        const findOpts = opts?.hardDelete ? { ...opts, filters: withoutSoftDeleteFilter(opts.filters) } : opts;
-        const ids = await this.settleIds(entity, q, findOpts);
-        if (!ids.length) {
-            return 0;
-        }
-        // Children first: they hold the foreign key, so deleting the parent ahead of them is rejected
-        // outright by any schema that declares the constraint without `ON DELETE CASCADE`.
-        await this.deleteRelations(entity, ids, opts);
-        const deleteCtx = this.dialect.createContext();
-        this.dialect.delete(deleteCtx, entity, { $where: whereIds(meta, ids) }, opts);
-        const { changes = 0 } = await this.run(deleteCtx.sql, deleteCtx.values);
+        const { changes = 0 } = await this.exec((ctx) => this.dialect.delete(ctx, entity, q, opts));
         return changes;
     }
     get hasOpenTransaction() {

package/dist/schema/canonicalType.d.ts

@@ -1,11 +1,3 @@
-/**
- * Canonical Type System
- *
- * Provides bidirectional mapping between:
- * - SQL types (dialect-specific)
- * - Canonical types (dialect-agnostic)
- * - TypeScript types (for entity generation)
- */
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { VectorCast } from '../dialect/vectorCast.js';
 import type { ColumnType, FieldOptions } from '../type/entity.js';
@@ -37,25 +29,15 @@ export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDia
  */
 export declare function canonicalToTypeScript(type: CanonicalType): string;
 /**
- * A type as `dialect` would actually store it: rendered to that engine's SQL and read back.
- *
- * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL and
- * `INTEGER` on SQLite - and only the engine settles an unstated bound, since `VARCHAR` is 255 on MySQL
- * and `TEXT` on Postgres. Both paths that diff a schema compare through this, so a migration and a
- * drift report cannot disagree about what changed.
+ * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
+ * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export declare function engineType(dialect: AbstractDialect): (type: CanonicalType) => CanonicalType;
 /**
  * Convert UQL FieldOptions to a canonical type.
  */
 export declare function fieldOptionsToCanonical(options: FieldOptions): CanonicalType;
-/**
- * Compare two canonical types for equality. Used for schema diffing.
- *
- * Nothing here guesses an engine's own default for an unstated bound: `VARCHAR` is 255 on MySQL and
- * `TEXT` on Postgres, and a comparison that assumed either was blind to that difference on the other.
- * `DiffOptions.normalizeType` is what settles it, by putting both sides through the engine first.
- */
+/** Whether two canonical types are equal, guessing no engine default: `DiffOptions.normalizeType` settles those. */
 export declare function areTypesEqual(a: CanonicalType, b: CanonicalType): boolean;
 /**
  * Whether changing a column from one type to the other can lose what it holds.

package/dist/schema/canonicalType.js

@@ -1,11 +1,4 @@
-/**
- * Canonical Type System
- *
- * Provides bidirectional mapping between:
- * - SQL types (dialect-specific)
- * - Canonical types (dialect-agnostic)
- * - TypeScript types (for entity generation)
- */
+// Canonical types, between an engine's SQL types and TypeScript's.
 import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export function isVectorCategory(category) {
@@ -92,7 +85,7 @@ const SQL_TO_CANONICAL = {
 };
 /**
  * pgvector is the only engine with three vector column types, so every other engine maps all three
- * canonical categories onto the single type it does have (see `hasNarrowVectorTypes` on the dialect,
+ * canonical categories onto the single type it does have (see `SqlDialectFeatures.narrowVectorTypes`,
  * the dialect-side half of the same fact).
  */
 function withVectorType(scalars, vector) {
@@ -242,59 +235,31 @@ const CANONICAL_TO_TS = {
  */
 export function sqlToCanonical(sqlType) {
     const normalized = sqlType.toLowerCase().trim();
-    // Check for UNSIGNED modifier before extracting base type
-    const hasUnsigned = normalized.includes('unsigned');
+    const unsigned = normalized.includes('unsigned');
     const withoutUnsigned = normalized.replace(/\s*unsigned\s*/i, ' ').trim();
     // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"]
     const match = withoutUnsigned.match(/^([a-z][a-z0-9 ]*?)(?:\(([^)]+)\))?$/);
-    if (!match) {
+    const base = match ? SQL_TO_CANONICAL[match[1]] : undefined;
+    if (!match || !base) {
         return { category: 'string', raw: sqlType };
     }
-    const [, baseType, params] = match;
-    const base = SQL_TO_CANONICAL[baseType];
-    if (!base) {
-        // Unknown type - pass through as raw
-        return { category: 'string', raw: sqlType };
-    }
-    const result = {
+    const params = match[2]?.split(',').map((param) => param.trim()) ?? [];
+    const [first, second] = params
+        .map((param) => Number.parseInt(param, 10))
+        .map((n) => (Number.isNaN(n) ? undefined : n));
+    // A length for a string or a blob, the dimensions for a vector: `VARCHAR(255)`, `VECTOR(1536)`.
+    const measured = base.category === 'string' || base.category === 'blob' || isVectorCategory(base.category);
+    const decimal = base.category === 'decimal';
+    return {
         category: base.category,
-        size: base.size,
+        // SQL Server's unbounded `(MAX)` is what it creates for a `TEXT`.
+        size: measured && params[0] === 'max' ? 'small' : base.size,
         withTimezone: base.withTimezone,
+        length: measured ? first : undefined,
+        precision: decimal ? first : undefined,
+        scale: decimal ? second : undefined,
+        unsigned: unsigned || undefined,
     };
-    // Parse parameters
-    if (params) {
-        const paramParts = params.split(',').map((p) => p.trim());
-        if (result.category === 'string' || result.category === 'blob') {
-            // VARCHAR(255) -> length
-            const length = Number.parseInt(paramParts[0], 10);
-            if (!Number.isNaN(length)) {
-                result.length = length;
-            }
-        }
-        else if (result.category === 'decimal') {
-            // DECIMAL(10,2) -> precision, scale
-            const precision = Number.parseInt(paramParts[0], 10);
-            const scale = paramParts[1] ? Number.parseInt(paramParts[1], 10) : undefined;
-            if (!Number.isNaN(precision)) {
-                result.precision = precision;
-            }
-            if (scale !== undefined && !Number.isNaN(scale)) {
-                result.scale = scale;
-            }
-        }
-        else if (isVectorCategory(result.category)) {
-            // VECTOR(1536), HALFVEC(1536), SPARSEVEC(4000) -> length (dimensions)
-            const dimensions = Number.parseInt(paramParts[0], 10);
-            if (!Number.isNaN(dimensions)) {
-                result.length = dimensions;
-            }
-        }
-    }
-    // Check for UNSIGNED modifier
-    if (hasUnsigned) {
-        result.unsigned = true;
-    }
-    return result;
 }
 /**
  * The canonical type for a column an engine reported, merging the metadata columns it reports beside
@@ -363,12 +328,8 @@ export function canonicalToTypeScript(type) {
     return CANONICAL_TO_TS[type.category];
 }
 /**
- * A type as `dialect` would actually store it: rendered to that engine's SQL and read back.
- *
- * Several canonical types share one storage type per engine - a `boolean` is `TINYINT(1)` on MySQL and
- * `INTEGER` on SQLite - and only the engine settles an unstated bound, since `VARCHAR` is 255 on MySQL
- * and `TEXT` on Postgres. Both paths that diff a schema compare through this, so a migration and a
- * drift report cannot disagree about what changed.
+ * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
+ * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export function engineType(dialect) {
     return (type) => sqlToCanonical(canonicalToSql(type, dialect));
@@ -407,13 +368,7 @@ export function fieldOptionsToCanonical(options) {
             return { category: 'string', length: options.length };
     }
 }
-/**
- * Compare two canonical types for equality. Used for schema diffing.
- *
- * Nothing here guesses an engine's own default for an unstated bound: `VARCHAR` is 255 on MySQL and
- * `TEXT` on Postgres, and a comparison that assumed either was blind to that difference on the other.
- * `DiffOptions.normalizeType` is what settles it, by putting both sides through the engine first.
- */
+/** Whether two canonical types are equal, guessing no engine default: `DiffOptions.normalizeType` settles those. */
 export function areTypesEqual(a, b) {
     return (a.category === b.category &&
         a.size === b.size &&

package/dist/schema/dependencyGraph.d.ts

@@ -4,15 +4,9 @@
  */
 export type DependenciesOf<N> = (node: N) => Iterable<N>;
 /**
- * Nodes in creation order, dependencies first. Cycle-tolerant by design: a cyclic foreign key is
- * legal SQL, handled by deferring the constraint, so a cycle orders arbitrarily rather than
- * throwing. Use {@link findCycles} to report one.
+ * Nodes in creation order, dependencies first. Cycle-tolerant: a cyclic foreign key is legal SQL,
+ * handled by deferring the constraint, so a cycle orders arbitrarily rather than throwing.
  */
 export declare function createOrder<N>(nodes: Iterable<N>, dependenciesOf: DependenciesOf<N>): N[];
 /** Nodes in drop order, dependents first. */
 export declare function dropOrder<N>(nodes: Iterable<N>, dependenciesOf: DependenciesOf<N>): N[];
-/**
- * Every dependency cycle, each starting where it closes. A separate walk from {@link createOrder}
- * rather than a flag on it: ordering must succeed on any graph, reporting must see every cycle.
- */
-export declare function findCycles<N>(nodes: Iterable<N>, dependenciesOf: DependenciesOf<N>): N[][];

package/dist/schema/dependencyGraph.js

@@ -3,9 +3,8 @@
  * describing its edges rather than by adding a branch here.
  */
 /**
- * Nodes in creation order, dependencies first. Cycle-tolerant by design: a cyclic foreign key is
- * legal SQL, handled by deferring the constraint, so a cycle orders arbitrarily rather than
- * throwing. Use {@link findCycles} to report one.
+ * Nodes in creation order, dependencies first. Cycle-tolerant: a cyclic foreign key is legal SQL,
+ * handled by deferring the constraint, so a cycle orders arbitrarily rather than throwing.
  */
 export function createOrder(nodes, dependenciesOf) {
     const ordered = [];
@@ -29,32 +28,3 @@ export function createOrder(nodes, dependenciesOf) {
 export function dropOrder(nodes, dependenciesOf) {
     return createOrder(nodes, dependenciesOf).reverse();
 }
-/**
- * Every dependency cycle, each starting where it closes. A separate walk from {@link createOrder}
- * rather than a flag on it: ordering must succeed on any graph, reporting must see every cycle.
- */
-export function findCycles(nodes, dependenciesOf) {
-    const cycles = [];
-    const visited = new Set();
-    const onPath = new Set();
-    const visit = (node, path) => {
-        // A node on the walk was handed down in `path` too, so the cycle closes where it first appears.
-        if (onPath.has(node)) {
-            cycles.push(path.slice(path.indexOf(node)));
-            return;
-        }
-        if (visited.has(node)) {
-            return;
-        }
-        visited.add(node);
-        onPath.add(node);
-        for (const dependency of dependenciesOf(node)) {
-            visit(dependency, [...path, node]);
-        }
-        onPath.delete(node);
-    };
-    for (const node of nodes) {
-        visit(node, []);
-    }
-    return cycles;
-}

package/dist/schema/index.d.ts

@@ -1,26 +1,2 @@
-/**
- * Schema AST Module
- *
- * Provides a unified graph representation of database schema for:
- * - Schema diffing and migration generation
- * - Entity code generation from database
- * - Drift detection
- * - Smart relation inference
- */
-import type { SchemaIntrospector } from '../type/migration.js';
-import type { SchemaAST } from './schemaAST.js';
-export { areTypesEqual, canonicalToColumnType, canonicalToSql, canonicalToTypeScript, fieldOptionsToCanonical, isBreakingTypeChange, sqlToCanonical, } from './canonicalType.js';
-/**
- * Introspect the database and build a SchemaAST from it.
- *
- * @param introspector - The schema introspector to use
- * @returns The SchemaAST representing the database schema
- */
-export declare function introspectSchema(introspector: SchemaIntrospector): Promise<SchemaAST>;
-export { createOrder, dropOrder, findCycles, type DependenciesOf } from './dependencyGraph.js';
 export { SchemaAST } from './schemaAST.js';
-export type { BuildSchemaASTOptions } from './schemaASTBuilder.js';
-export { buildSchemaAST } from './schemaASTBuilder.js';
-export type { DiffOptions } from './schemaASTDiffer.js';
-export { diffSchemas } from './schemaASTDiffer.js';
-export type { CanonicalType, ColumnDiff, ColumnNode, Drift, DriftReport, DriftSeverity, DriftStatus, DriftType, ForeignKeyAction, IndexDiff, IndexNode, IndexSource, IndexSyncStatus, IndexType, RelationshipDiff, RelationshipNode, RelationshipSource, RelationshipType, SchemaAST as ISchemaAST, SchemaDiffResult, SizeVariant, TableDiff, TableNode, TypeCategory, ValidationError, ValidationErrorType, } from './types.js';
+export type { Drift, DriftReport } from './types.js';

package/dist/schema/index.js

@@ -1,27 +1 @@
-/**
- * Schema AST Module
- *
- * Provides a unified graph representation of database schema for:
- * - Schema diffing and migration generation
- * - Entity code generation from database
- * - Drift detection
- * - Smart relation inference
- */
-// Canonical type utilities
-export { areTypesEqual, canonicalToColumnType, canonicalToSql, canonicalToTypeScript, fieldOptionsToCanonical, isBreakingTypeChange, sqlToCanonical, } from './canonicalType.js';
-/**
- * Introspect the database and build a SchemaAST from it.
- *
- * @param introspector - The schema introspector to use
- * @returns The SchemaAST representing the database schema
- */
-export async function introspectSchema(introspector) {
-    return introspector.introspect();
-}
-// SchemaAST class
-export { createOrder, dropOrder, findCycles } from './dependencyGraph.js';
 export { SchemaAST } from './schemaAST.js';
-// Builder
-export { buildSchemaAST } from './schemaASTBuilder.js';
-// Differ
-export { diffSchemas } from './schemaASTDiffer.js';

package/dist/schema/indexColumns.d.ts

@@ -1,10 +1,3 @@
 import type { ColumnNode, IndexNode } from './types.js';
-/**
- * The table columns an index resolves to, in order.
- *
- * Derived rather than stored: an index is defined by its entries, and a second field repeating them
- * as columns is a second thing to keep in step. It went out of step - one introspector rebuilt the
- * entries from the columns it had just built from the entries, and every fixture had to write both.
- * An expression entry resolves to no column at all, which is why the two were never the same list.
- */
+/** The table columns an index's entries resolve to, in order; an expression entry resolves to none. */
 export declare function indexColumns(index: IndexNode): ColumnNode[];

package/dist/schema/indexColumns.js

@@ -1,11 +1,4 @@
-/**
- * The table columns an index resolves to, in order.
- *
- * Derived rather than stored: an index is defined by its entries, and a second field repeating them
- * as columns is a second thing to keep in step. It went out of step - one introspector rebuilt the
- * entries from the columns it had just built from the entries, and every fixture had to write both.
- * An expression entry resolves to no column at all, which is why the two were never the same list.
- */
+/** The table columns an index's entries resolve to, in order; an expression entry resolves to none. */
 export function indexColumns(index) {
     return index.entries.flatMap((entry) => (entry.expression ? [] : (index.table.columns.get(entry.column) ?? [])));
 }