uql-orm 0.65.1 → 0.67.0

package/dist/schema/indexDifferences.d.ts

@@ -1,51 +1,18 @@
 import type { IndexNode } from './types.js';
-/**
- * What an introspector can report about an index, and so all that diffing may compare. Anything it
- * cannot report is skipped: the entity declares it, the database never mentions it, and no migration
- * could ever make the two agree.
- *
- * Deliberately separate from the dialect's `IndexFeature`, which says what an engine can *emit* and
- * rejects outright. The two look alike and are not: Postgres emits an expression index and reads one
- * back, MySQL emits one it cannot describe afterwards.
- */
+/** What an introspector reports about an index, and so all a diff may compare; apart from `IndexFeature`, what an engine emits. */
 export type IndexFacet = 'order' | 'nulls' | 'opsClass' | 'accessMethod' | 'include';
 /**
- * Whether the table already has this index, for the additive sync that only ever *creates* one.
- *
- * Its shape, never its name: the table's indexes were named by whoever created them, so an index
- * that is already there must not be created a second time under a name we happen to prefer. A
- * derived name is no handle at all - the convention can change, an engine silently truncates one
- * past its identifier limit, and SQLite reports names it made up.
- *
- * Uniqueness counts, because a unique index and a plain one over the same columns enforce different
- * things and no engine can alter one into the other. An index over an expression or a JSON path has
- * no comparable columns - engines reprint SQL text from their parse tree, the same reason
- * {@link describeIndexDifferences} leaves those entries alone - so it falls back to its name.
+ * Whether the table has this index already, by shape rather than name, uniqueness included. An index
+ * over an expression, whose text the engine reprints, falls back to its name.
  */
 export declare function indexSignature(index: Pick<IndexNode, 'name' | 'entries' | 'unique'>): string;
 /**
- * A constraint name without its kind marker.
- *
- * What pairs two sides of a *report*: an index whose uniqueness or columns changed is one index that
- * differs, not one dropped and another created, and only a handle independent of its shape can say
- * so. Stripping the marker is what lets `idx_User_email`, named before the convention moved it to
- * the end, recognise the `User__email_idx` derived for it now, so upgrading reports no drift.
- *
- * Exactly one marker, and the trailing one first. Stripping both ends would eat a leading marker
- * that belongs to the *table* - an index over `pk_registry` is not a primary key - leaving it unable
- * to pair with its own older name. The separator is levelled last, since only one convention doubles
- * it.
+ * A constraint name without its kind marker, pairing an index with its older spelling
+ * (`idx_User_email` with `User__email_idx`). Only one marker, the trailing one first.
  */
 export declare function indexNameStem(name: string): string;
 /**
- * Everything an index differs by, named, or nothing when the two match.
- *
- * Only what both sides can state *structurally* is compared. SQL text is not: a database reprints an
- * expression and a predicate from its parse tree, so `status IN ('a','b')` reads back as
- * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
- * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
- * migration can settle. So a partial index's predicate is never compared, and an index over an
- * expression - a `raw()` one, or a JSON path, which the engines report as an expression too - has
- * its entries left alone while the rest of it still compares.
+ * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON
+ * path or a predicate is reprinted by the engine, so never compared.
  */
 export declare function describeIndexDifferences(source: IndexNode, target: IndexNode, facets: ReadonlySet<IndexFacet>): string[];

package/dist/schema/indexDifferences.js

@@ -1,15 +1,6 @@
 /**
- * Whether the table already has this index, for the additive sync that only ever *creates* one.
- *
- * Its shape, never its name: the table's indexes were named by whoever created them, so an index
- * that is already there must not be created a second time under a name we happen to prefer. A
- * derived name is no handle at all - the convention can change, an engine silently truncates one
- * past its identifier limit, and SQLite reports names it made up.
- *
- * Uniqueness counts, because a unique index and a plain one over the same columns enforce different
- * things and no engine can alter one into the other. An index over an expression or a JSON path has
- * no comparable columns - engines reprint SQL text from their parse tree, the same reason
- * {@link describeIndexDifferences} leaves those entries alone - so it falls back to its name.
+ * Whether the table has this index already, by shape rather than name, uniqueness included. An index
+ * over an expression, whose text the engine reprints, falls back to its name.
  */
 export function indexSignature(index) {
     const comparable = !index.entries.some((entry) => entry.expression || entry.jsonPath || entry.jsonArray);
@@ -19,17 +10,8 @@ export function indexSignature(index) {
     return `${index.unique ? 'unique' : 'plain'}(${identity})`;
 }
 /**
- * A constraint name without its kind marker.
- *
- * What pairs two sides of a *report*: an index whose uniqueness or columns changed is one index that
- * differs, not one dropped and another created, and only a handle independent of its shape can say
- * so. Stripping the marker is what lets `idx_User_email`, named before the convention moved it to
- * the end, recognise the `User__email_idx` derived for it now, so upgrading reports no drift.
- *
- * Exactly one marker, and the trailing one first. Stripping both ends would eat a leading marker
- * that belongs to the *table* - an index over `pk_registry` is not a primary key - leaving it unable
- * to pair with its own older name. The separator is levelled last, since only one convention doubles
- * it.
+ * A constraint name without its kind marker, pairing an index with its older spelling
+ * (`idx_User_email` with `User__email_idx`). Only one marker, the trailing one first.
  */
 export function indexNameStem(name) {
     const withoutSuffix = name.replace(KIND_SUFFIX, '');
@@ -45,15 +27,8 @@ const KIND_SUFFIX = /_(?:idx|fk|ck|pk|uk|uq)$/i;
  */
 const KIND_PREFIX = /^(?:idx|fk|ck|pk|uk|uq)_/i;
 /**
- * Everything an index differs by, named, or nothing when the two match.
- *
- * Only what both sides can state *structurally* is compared. SQL text is not: a database reprints an
- * expression and a predicate from its parse tree, so `status IN ('a','b')` reads back as
- * `status = ANY (ARRAY['a'::text, 'b'::text])`, `LIKE` as `~~`, and a date literal with its time zone
- * spelled out. Folding that back needs a SQL parser, and every near-miss reports drift that no
- * migration can settle. So a partial index's predicate is never compared, and an index over an
- * expression - a `raw()` one, or a JSON path, which the engines report as an expression too - has
- * its entries left alone while the rest of it still compares.
+ * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON
+ * path or a predicate is reprinted by the engine, so never compared.
  */
 export function describeIndexDifferences(source, target, facets) {
     const differences = [];

package/dist/schema/schemaAST.d.ts

@@ -1,187 +1,20 @@
-/**
- * SchemaAST Class
- *
- * The main class for working with schema graphs.
- * Provides graph operations like navigation, validation, and topological sorting.
- */
-import type { ColumnNode, IndexNode, SchemaAST as ISchemaAST, RelationshipNode, RelationshipType, TableNode, ValidationError } from './types.js';
-/**
- * A table node with its collections empty, ready to be filled. Six places build one, and the fields
- * that are pure boilerplate are exactly the ones a new field gets forgotten in: {@link TableNode.schema}
- * was added and `SchemaAST.clone` kept rebuilding nodes without it.
- */
+import type { IndexNode, RelationshipNode, TableNode } from './types.js';
+/** A table node with its collections empty, ready to be filled. */
 export declare function createTableNode(name: string, schema?: string, comment?: string): TableNode;
-/**
- * Schema AST - A graph representation of a database schema.
- *
- * Enables:
- * - Graph navigation (dependencies, dependents)
- * - Circular dependency detection
- * - Topological sorting for correct DDL order
- * - Smart relation inference
- * - Schema validation
- */
-export declare class SchemaAST implements ISchemaAST {
+/** A database schema as a graph: tables, the foreign keys between them, and their indexes. */
+export declare class SchemaAST {
     readonly tables: Map<string, TableNode>;
     readonly relationships: RelationshipNode[];
     readonly indexes: IndexNode[];
-    /**
-     * Get a table by the name it is keyed under: schema-qualified where it has one, so two tables of
-     * the same name in different schemas stay distinct. Build the key with `qualifyName`.
-     */
+    /** A table by the key it is stored under: schema-qualified where it has one (see `qualifyName`). */
     getTable(name: string): TableNode | undefined;
-    /**
-     * Add a table to the schema.
-     */
     addTable(table: TableNode): void;
-    /**
-     * Remove a table from the schema.
-     */
-    removeTable(name: string): boolean;
-    /**
-     * Get all table nodes.
-     */
     getTables(): TableNode[];
-    /**
-     * Get all table names.
-     */
-    getTableNames(): string[];
-    /**
-     * Get all tables that depend on this table (have FKs pointing to it).
-     * These are tables that reference this table's primary key.
-     */
-    getDependentTables(table: TableNode): TableNode[];
-    /**
-     * Get all tables this table depends on (has FKs to).
-     * These are tables that this table references.
-     */
-    getDependencies(table: TableNode): TableNode[];
-    /**
-     * Get the relationship between two tables (if any).
-     */
-    getRelationship(from: TableNode, to: TableNode): RelationshipNode | undefined;
-    /**
-     * Get all relationships for a table.
-     */
-    getTableRelationships(table: TableNode): RelationshipNode[];
-    /**
-     * Get the column that a foreign key column references.
-     */
-    getReferencedColumn(fkColumn: ColumnNode): ColumnNode | undefined;
-    /**
-     * Detect circular foreign key dependencies.
-     * Returns arrays of tables that form cycles.
-     */
-    detectCircularDependencies(): TableNode[][];
-    /**
-     * Check if there are any circular dependencies.
-     */
-    hasCircularDependencies(): boolean;
-    /**
-     * Get tables in correct order for CREATE (dependencies first).
-     * Tables with no dependencies come first, then tables that depend on them, etc.
-     */
+    /** Tables in `CREATE` order, each after the tables it references. */
     getCreateOrder(): TableNode[];
-    /**
-     * Get tables in correct order for DROP (dependents first).
-     * Tables that depend on others come first, then the tables they depend on.
-     */
+    /** Tables in `DROP` order, each before the tables it references. */
     getDropOrder(): TableNode[];
-    /**
-     * Validate schema integrity.
-     * Checks for:
-     * - Missing FK targets
-     * - Circular dependencies
-     * - Orphan columns
-     * - Duplicate indexes
-     */
-    validate(): ValidationError[];
-    /**
-     * Check if the schema is valid (no validation errors).
-     */
-    isValid(): boolean;
-    /**
-     * Check if a table looks like a junction table (ManyToMany through).
-     * Junction tables typically have:
-     * - Exactly 2 foreign keys
-     * - Few other columns (id, maybe timestamps)
-     * - Primary key might be composite of the FKs
-     */
-    isJunctionTable(table: TableNode): boolean;
-    /**
-     * Infer relation type from schema structure.
-     */
-    inferRelationType(rel: RelationshipNode): RelationshipType;
-    /**
-     * Get the inverse relation type.
-     */
-    getInverseRelationType(type: RelationshipType): RelationshipType;
-    /**
-     * Add an index to the schema.
-     */
     addIndex(index: IndexNode): void;
-    /**
-     * Get all indexes for a table.
-     */
-    getTableIndexes(tableName: string): IndexNode[];
-    /**
-     * Find an index by name.
-     */
-    getIndex(name: string): IndexNode | undefined;
-    /**
-     * Add a relationship to the schema.
-     */
+    /** Adds a foreign key, linking it from both tables and both column sets. */
     addRelationship(rel: RelationshipNode): void;
-    /**
-     * Remove a relationship from the schema.
-     */
-    removeRelationship(name: string): boolean;
-    /**
-     * Create a deep clone of this schema.
-     */
-    clone(): SchemaAST;
-    /**
-     * Get statistics about the schema.
-     */
-    getStats(): {
-        tableCount: number;
-        columnCount: number;
-        relationshipCount: number;
-        indexCount: number;
-    };
-    /**
-     * The schema as a plain object, for serialization and debugging. The graph links are what is left
-     * out - they are cycles, and nothing else is: listing the fields to keep instead dropped every
-     * option a column had gained since, `defaultValue` and `enum` included.
-     */
-    toJSON(): {
-        tables: {
-            name: string;
-            columns: {
-                name: string;
-                type: import("./types.js").CanonicalType;
-                nullable: boolean;
-                defaultValue?: unknown;
-                isPrimaryKey: boolean;
-                isAutoIncrement: boolean;
-                isUnique: boolean;
-                enum?: import("./types.js").EnumValues;
-                generatedAs?: string;
-                comment?: string;
-            }[];
-            indexes: {
-                name: string;
-                columns: string[];
-                unique: boolean;
-            }[];
-        }[];
-        relationships: {
-            name: string;
-            type: RelationshipType;
-            from: string;
-            to: string;
-            onDelete: import("./types.js").ForeignKeyAction | undefined;
-            onUpdate: import("./types.js").ForeignKeyAction | undefined;
-        }[];
-    };
 }