uql-orm 0.21.0 → 0.23.0

package/dist/migrate/sync/schemaSync.js

@@ -1,259 +0,0 @@
-/**
- * Schema Sync
- *
- * Orchestrates schema synchronization between entities and database
- * with configurable direction modes.
- */
-import { SchemaASTBuilder } from '../../schema/schemaASTBuilder.js';
-import { SchemaASTDiffer } from '../../schema/schemaASTDiffer.js';
-/**
- * Service for synchronizing schemas between entities and database.
- */
-export class SchemaSync {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
-    /**
-     * Execute schema synchronization.
-     */
-    async sync() {
-        const direction = this.options.direction ?? 'bidirectional';
-        switch (direction) {
-            case 'entity-to-db':
-                return this.syncEntityToDb();
-            case 'db-to-entity':
-                return this.syncDbToEntity();
-            case 'bidirectional':
-                return this.syncBidirectional();
-        }
-    }
-    /**
-     * Sync from entities to database (push).
-     */
-    async syncEntityToDb() {
-        const entityAST = this.buildEntityAST();
-        const dbAST = await this.buildDatabaseAST();
-        const differ = new SchemaASTDiffer();
-        const diff = differ.diff(entityAST, dbAST);
-        // In safe mode, filter out destructive changes
-        const safeDiff = this.options.safe ? this.filterDestructiveChanges(diff) : diff;
-        return {
-            direction: 'entity-to-db',
-            success: true,
-            dbChanges: safeDiff,
-            entityChanges: undefined,
-            conflicts: [],
-            summary: this.formatSummary('entity-to-db', safeDiff),
-            details: {
-                db: this.getDiffCounts(safeDiff),
-                entity: { created: 0, dropped: 0, altered: 0 },
-            },
-        };
-    }
-    /**
-     * Sync from database to entities (pull).
-     */
-    async syncDbToEntity() {
-        const entityAST = this.buildEntityAST();
-        const dbAST = await this.buildDatabaseAST();
-        const differ = new SchemaASTDiffer();
-        // Diff in opposite direction: DB is source, entity is target
-        const diff = differ.diff(dbAST, entityAST);
-        // Apply safe mode if enabled
-        const safeDiff = this.options.safe ? this.filterDestructiveChanges(diff) : diff;
-        return {
-            direction: 'db-to-entity',
-            success: true,
-            dbChanges: undefined,
-            entityChanges: safeDiff,
-            conflicts: [],
-            summary: this.formatSummary('db-to-entity', safeDiff),
-            details: {
-                db: { created: 0, dropped: 0, altered: 0 },
-                entity: this.getDiffCounts(safeDiff),
-            },
-        };
-    }
-    /**
-     * Bidirectional sync with conflict detection.
-     */
-    async syncBidirectional() {
-        const entityAST = this.buildEntityAST();
-        const dbAST = await this.buildDatabaseAST();
-        const differ = new SchemaASTDiffer();
-        // Get both directions
-        const entityToDb = differ.diff(entityAST, dbAST);
-        const dbToEntity = differ.diff(dbAST, entityAST);
-        // Detect conflicts (changes in both directions for same elements)
-        const conflicts = this.detectConflicts(entityToDb, dbToEntity);
-        // Filter out conflicting changes
-        let safeEntityToDb = this.filterConflictingChanges(entityToDb, conflicts);
-        let safeDbToEntity = this.filterConflictingChanges(dbToEntity, conflicts);
-        // Apply safe mode if enabled
-        if (this.options.safe) {
-            safeEntityToDb = this.filterDestructiveChanges(safeEntityToDb);
-            safeDbToEntity = this.filterDestructiveChanges(safeDbToEntity);
-        }
-        return {
-            direction: 'bidirectional',
-            success: conflicts.length === 0,
-            dbChanges: safeEntityToDb,
-            entityChanges: safeDbToEntity,
-            conflicts,
-            summary: this.formatBidirectionalSummary(safeEntityToDb, safeDbToEntity, conflicts),
-            details: {
-                db: this.getDiffCounts(safeEntityToDb),
-                entity: this.getDiffCounts(safeDbToEntity),
-            },
-        };
-    }
-    /**
-     * Build SchemaAST from entities.
-     */
-    buildEntityAST() {
-        const builder = new SchemaASTBuilder();
-        return builder.fromEntities(this.options.entities);
-    }
-    /**
-     * Build SchemaAST from database.
-     */
-    async buildDatabaseAST() {
-        return this.options.introspector.introspect();
-    }
-    /**
-     * Filter destructive changes for safe mode.
-     */
-    filterDestructiveChanges(diff) {
-        return {
-            ...diff,
-            tablesToDrop: [], // Never drop tables in safe mode
-            columnDiffs: diff.columnDiffs.filter((d) => d.type !== 'drop'), // Never drop columns
-            indexDiffs: diff.indexDiffs.filter((d) => d.type !== 'drop'),
-            relationshipDiffs: diff.relationshipDiffs.filter((d) => d.type !== 'drop'),
-        };
-    }
-    /**
-     * Detect conflicts between bidirectional changes.
-     */
-    detectConflicts(entityToDb, dbToEntity) {
-        const conflicts = [];
-        // Find column alterations that exist in both directions (type conflicts)
-        const entityColAlters = new Map(entityToDb.columnDiffs.filter((d) => d.type === 'alter').map((d) => [`${d.table}.${d.column}`, d]));
-        for (const dbColDiff of dbToEntity.columnDiffs.filter((d) => d.type === 'alter')) {
-            const key = `${dbColDiff.table}.${dbColDiff.column}`;
-            const entityColDiff = entityColAlters.get(key);
-            if (entityColDiff) {
-                // Both sides want to alter the same column - conflict
-                conflicts.push({
-                    type: 'type_mismatch',
-                    table: dbColDiff.table,
-                    column: dbColDiff.column,
-                    entityValue: entityColDiff.expected?.type,
-                    dbValue: dbColDiff.expected?.type,
-                    suggestion: `Column has different types. Entity: ${this.formatType(entityColDiff.expected?.type)}, DB: ${this.formatType(dbColDiff.expected?.type)}`,
-                });
-            }
-        }
-        return conflicts;
-    }
-    /**
-     * Filter out conflicting changes.
-     */
-    filterConflictingChanges(diff, conflicts) {
-        const conflictKeys = new Set(conflicts.map((c) => `${c.table}.${c.column ?? ''}`));
-        return {
-            ...diff,
-            columnDiffs: diff.columnDiffs.filter((d) => !conflictKeys.has(`${d.table}.${d.column}`)),
-            tablesToAlter: diff.tablesToAlter.filter((t) => !conflictKeys.has(`${t.name}.`)),
-        };
-    }
-    /**
-     * Get counts of changes from a diff.
-     */
-    getDiffCounts(diff) {
-        return {
-            created: diff.tablesToCreate.length + diff.columnDiffs.filter((d) => d.type === 'add').length,
-            dropped: diff.tablesToDrop.length + diff.columnDiffs.filter((d) => d.type === 'drop').length,
-            altered: diff.columnDiffs.filter((d) => d.type === 'alter').length,
-        };
-    }
-    /**
-     * Format summary for single-direction sync.
-     */
-    formatSummary(direction, diff) {
-        const lines = [];
-        if (direction === 'entity-to-db') {
-            lines.push('Entity → Database Changes:');
-        }
-        else {
-            lines.push('Database → Entity Changes:');
-        }
-        if (diff.tablesToCreate.length > 0) {
-            lines.push(`  + ${diff.tablesToCreate.length} table(s) to create`);
-        }
-        if (diff.tablesToDrop.length > 0) {
-            lines.push(`  - ${diff.tablesToDrop.length} table(s) to drop`);
-        }
-        if (diff.columnDiffs.length > 0) {
-            const adds = diff.columnDiffs.filter((d) => d.type === 'add').length;
-            const drops = diff.columnDiffs.filter((d) => d.type === 'drop').length;
-            const alters = diff.columnDiffs.filter((d) => d.type === 'alter').length;
-            if (adds)
-                lines.push(`  + ${adds} column(s) to add`);
-            if (drops)
-                lines.push(`  - ${drops} column(s) to drop`);
-            if (alters)
-                lines.push(`  ~ ${alters} column(s) to alter`);
-        }
-        if (diff.indexDiffs.length > 0) {
-            lines.push(`  ${diff.indexDiffs.length} index change(s)`);
-        }
-        if (!diff.hasDifferences) {
-            lines.push('  Schema is already in sync.');
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Format summary for bidirectional sync.
-     */
-    formatBidirectionalSummary(entityToDb, dbToEntity, conflicts) {
-        const lines = [];
-        lines.push('Bidirectional Sync Report');
-        lines.push('========================\n');
-        if (conflicts.length > 0) {
-            lines.push(`⚠️  ${conflicts.length} conflict(s) require manual resolution:\n`);
-            for (const conflict of conflicts) {
-                lines.push(`  • ${conflict.table}.${conflict.column ?? ''}: ${conflict.suggestion}`);
-            }
-            lines.push('');
-        }
-        if (entityToDb.hasDifferences) {
-            lines.push('Entity → Database:');
-            lines.push(this.formatSummary('entity-to-db', entityToDb).split('\n').slice(1).join('\n'));
-            lines.push('');
-        }
-        if (dbToEntity.hasDifferences) {
-            lines.push('Database → Entity:');
-            lines.push(this.formatSummary('db-to-entity', dbToEntity).split('\n').slice(1).join('\n'));
-        }
-        if (!entityToDb.hasDifferences && !dbToEntity.hasDifferences && conflicts.length === 0) {
-            lines.push('✓ Schema is in sync.');
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Format type for display.
-     */
-    formatType(type) {
-        if (!type?.category)
-            return 'unknown';
-        return type.length ? `${type.category}(${type.length})` : type.category;
-    }
-}
-/**
- * Create a SchemaSync instance.
- */
-export function createSchemaSync(options) {
-    return new SchemaSync(options);
-}

package/dist/querier/decorator/index.d.ts

@@ -1,4 +0,0 @@
-export * from './injectQuerier.js';
-export * from './log.js';
-export * from './serialized.js';
-export * from './transactional.js';

package/dist/querier/decorator/index.js

@@ -1,4 +0,0 @@
-export * from './injectQuerier.js';
-export * from './log.js';
-export * from './serialized.js';
-export * from './transactional.js';

package/dist/querier/decorator/injectQuerier.d.ts

@@ -1,3 +0,0 @@
-import type { Key, Type } from '../../type/index.js';
-export declare function InjectQuerier(): (proto: Record<PropertyKey, any>, key: string, index: number) => void;
-export declare function getInjectedQuerierIndex<S>(service: Type<S>, key: Key<S>): any;

package/dist/querier/decorator/injectQuerier.js

@@ -1,33 +0,0 @@
-const metadataKey = Symbol('InjectQuerier');
-export function InjectQuerier() {
-    // biome-ignore lint/suspicious/noExplicitAny: `any` is required - class prototypes don't satisfy Record<K, unknown>
-    return (proto, key, index) => {
-        if (!proto[metadataKey]) {
-            proto[metadataKey] = new WeakMap();
-        }
-        if (!proto[metadataKey].has(proto.constructor)) {
-            proto[metadataKey].set(proto.constructor, {});
-        }
-        const meta = proto[metadataKey].get(proto.constructor);
-        const isAlreadyInjected = key in meta;
-        if (isAlreadyInjected) {
-            throw new TypeError(`@InjectQuerier() can only appears once in '${proto.constructor.name}.${key}'}`);
-        }
-        meta[key] = index;
-    };
-}
-export function getInjectedQuerierIndex(service, key) {
-    let proto = service.prototype;
-    while (proto.constructor !== Object) {
-        const meta = proto[metadataKey]?.get(proto.constructor);
-        if (meta && key in meta) {
-            return meta[key];
-        }
-        const keys = Object.getOwnPropertyNames(proto);
-        const isOwnKey = keys.includes(key);
-        if (isOwnKey) {
-            return;
-        }
-        proto = Object.getPrototypeOf(proto);
-    }
-}

package/dist/querier/decorator/log.d.ts

@@ -1,32 +0,0 @@
-import type { LoggerWrapper } from '../../util/logger.js';
-/**
- * A driver error enriched with context by {@link enrichError}. `query` is always attached; `values`
- * only when the querier's logger is configured to surface them (see {@link enrichError}) - they can
- * carry sensitive data (PII, tokens, etc.) and would otherwise leak into whatever error-tracking
- * pipeline (Sentry, console.error, ...) serializes the error, without the developer opting in.
- */
-export interface QueryError extends Error {
-    query?: string;
-    values?: unknown[];
-}
-/**
- * Tags `err` with the query it failed on (as `QueryError`) and re-throws. `values` is only attached
- * when `logger?.willLogValues()` is true - i.e. the app already has query values surfacing somewhere
- * (query-level or slow-query logging), so attaching them here doesn't introduce a new leak surface.
- * Shared by every query call site - `@Log()`, streams, transaction statements - so this logic lives
- * in one place.
- *
- * Not typed `never`: an async `catch` that calls a `never`-returning function ahead of a `finally`
- * containing an `if` trips a TS control-flow bug (`TS7027 Unreachable code`) unrelated to this logic.
- */
-export declare function enrichError(err: unknown, logger: LoggerWrapper | undefined, query: string, values?: unknown[]): void;
-/**
- * Decorator that logs the execution of a query method.
- * It tracks execution time and logs the query, parameters, and duration.
- * The decorated class must have a `logger` property of type LoggerWrapper.
- *
- * On failure, also attaches the query (and values, when the logger surfaces them) to the thrown
- * error via {@link enrichError} - so that context survives even when nothing gets logged, or is
- * printed in full when the app already opted into it.
- */
-export declare function Log(): (_target: object, _key: string, propDescriptor: PropertyDescriptor) => void;

package/dist/querier/decorator/log.js

@@ -1,52 +0,0 @@
-/**
- * Tags `err` with the query it failed on (as `QueryError`) and re-throws. `values` is only attached
- * when `logger?.willLogValues()` is true - i.e. the app already has query values surfacing somewhere
- * (query-level or slow-query logging), so attaching them here doesn't introduce a new leak surface.
- * Shared by every query call site - `@Log()`, streams, transaction statements - so this logic lives
- * in one place.
- *
- * Not typed `never`: an async `catch` that calls a `never`-returning function ahead of a `finally`
- * containing an `if` trips a TS control-flow bug (`TS7027 Unreachable code`) unrelated to this logic.
- */
-export function enrichError(err, logger, query, values) {
-    if (err instanceof Error) {
-        const queryError = err;
-        queryError.query ??= query;
-        if (values !== undefined && logger?.willLogValues()) {
-            queryError.values ??= values;
-        }
-    }
-    throw err;
-}
-/**
- * Decorator that logs the execution of a query method.
- * It tracks execution time and logs the query, parameters, and duration.
- * The decorated class must have a `logger` property of type LoggerWrapper.
- *
- * On failure, also attaches the query (and values, when the logger surfaces them) to the thrown
- * error via {@link enrichError} - so that context survives even when nothing gets logged, or is
- * printed in full when the app already opted into it.
- */
-export function Log() {
-    return (_target, _key, propDescriptor) => {
-        const originalMethod = propDescriptor.value;
-        propDescriptor.value = async function (...args) {
-            const startTime = performance.now();
-            const isSql = typeof args[0] === 'string';
-            const query = isSql ? args[0] : _key;
-            const values = isSql ? args[1] : args;
-            try {
-                return await originalMethod.apply(this, args);
-            }
-            catch (err) {
-                enrichError(err, this.logger, query, values);
-            }
-            finally {
-                if (this.logger) {
-                    const duration = performance.now() - startTime;
-                    this.logger.logQuery(query, values, Math.round(duration));
-                }
-            }
-        };
-    };
-}

package/dist/querier/decorator/serialized.d.ts

@@ -1,6 +0,0 @@
-/**
- * Decorator that ensures the decorated method is executed serially within the Querier instance.
- * It uses a private promise queue to prevent race conditions on the database connection.
- * Note: The decorated class must extend AbstractQuerier or implement a compatible serialize method.
- */
-export declare function Serialized(): (_target: object, _key: string, propDescriptor: PropertyDescriptor) => void;

package/dist/querier/decorator/serialized.js

@@ -1,13 +0,0 @@
-/**
- * Decorator that ensures the decorated method is executed serially within the Querier instance.
- * It uses a private promise queue to prevent race conditions on the database connection.
- * Note: The decorated class must extend AbstractQuerier or implement a compatible serialize method.
- */
-export function Serialized() {
-    return (_target, _key, propDescriptor) => {
-        const originalMethod = propDescriptor.value;
-        propDescriptor.value = function (...args) {
-            return this.serialize(() => originalMethod.apply(this, args));
-        };
-    };
-}

package/dist/querier/decorator/transactional.d.ts

@@ -1,6 +0,0 @@
-import type { IsolationLevel, QuerierPool } from '../../type/index.js';
-export declare function Transactional({ propagation, pool, isolationLevel, }?: {
-    readonly propagation?: 'supported' | 'required';
-    readonly pool?: QuerierPool;
-    readonly isolationLevel?: IsolationLevel;
-}): (target: object, key: string, propDescriptor: PropertyDescriptor) => void;

package/dist/querier/decorator/transactional.js

@@ -1,48 +0,0 @@
-import { getQuerierPool } from '../../options.js';
-import { getInjectedQuerierIndex } from './injectQuerier.js';
-export function Transactional({ propagation = 'required', pool, isolationLevel, } = {}) {
-    return (target, key, propDescriptor) => {
-        // biome-ignore lint/suspicious/noExplicitAny: decorator pattern - runtime constructor type is erased
-        const theClass = target.constructor;
-        const originalMethod = propDescriptor.value;
-        const injectedQuerierIndex = getInjectedQuerierIndex(theClass, key);
-        if (injectedQuerierIndex === undefined) {
-            throw TypeError(`missing decorator @InjectQuerier() in '${target.constructor.name}.${key}'`);
-        }
-        propDescriptor.value = async function func(...args) {
-            const params = [...args];
-            let isOwnTransaction = false;
-            let querier;
-            if (params[injectedQuerierIndex]) {
-                querier = params[injectedQuerierIndex];
-            }
-            else {
-                isOwnTransaction = true;
-                pool ??= getQuerierPool();
-                querier = await pool.getQuerier();
-                params[injectedQuerierIndex] = querier;
-            }
-            try {
-                if (propagation === 'required' && !querier.hasOpenTransaction) {
-                    await querier.beginTransaction(isolationLevel ? { isolationLevel } : undefined);
-                }
-                const resp = await originalMethod.apply(this, params);
-                if (isOwnTransaction && querier.hasOpenTransaction) {
-                    await querier.commitTransaction();
-                }
-                return resp;
-            }
-            catch (err) {
-                if (isOwnTransaction && querier.hasOpenTransaction) {
-                    await querier.rollbackTransaction();
-                }
-                throw err;
-            }
-            finally {
-                if (isOwnTransaction) {
-                    await querier.release();
-                }
-            }
-        };
-    };
-}

package/dist/sqlite/betterSqlite3Dialect.d.ts

@@ -1,9 +0,0 @@
-import { SqliteDialect } from './sqliteDialect.js';
-/**
- * SQLite Dialect specialization for the `better-sqlite3` driver.
- *
- * @remarks Empty subclass by design: distinct type for pools/tests that target
- * better-sqlite3 and a hook for future driver-specific overrides.
- */
-export declare class BetterSqlite3Dialect extends SqliteDialect {
-}

package/dist/sqlite/betterSqlite3Dialect.js

@@ -1,9 +0,0 @@
-import { SqliteDialect } from './sqliteDialect.js';
-/**
- * SQLite Dialect specialization for the `better-sqlite3` driver.
- *
- * @remarks Empty subclass by design: distinct type for pools/tests that target
- * better-sqlite3 and a hook for future driver-specific overrides.
- */
-export class BetterSqlite3Dialect extends SqliteDialect {
-}