ts-prorm-orm 1.1.0 → 1.2.0

package/dist/sqlite-advanced.d.ts

@@ -0,0 +1,572 @@
+/**
+ * SQLite Advanced Features Module
+ *
+ * Comprehensive support for SQLite advanced features including:
+ * - Views (Standard and updatable)
+ * - Triggers (BEFORE/AFTER INSERT/UPDATE/DELETE, recursive triggers)
+ * - Foreign Tables (FTS5, carray, etc.)
+ * - Full-Text Search (FTS5) - MATCH, rank, highlighting
+ * - JSON JSON1 extension - JSON each, extract
+ * - Generated Columns - VIRTUAL, STORED
+ * - Indexes - Partial, UNIQUE, expression indexes
+ * - Window Functions - SQLite 3.25+ (ROW_NUMBER, etc.)
+ * - CTEs - WITH RECURSIVE
+ * - Common Table Expressions
+ * - VACUUM and ANALYZE - Optimization
+ * - Savepoints - Transaction management
+ * - UPSERT - INSERT ... ON CONFLICT
+ * - Table-valued Functions - json_each, fts5, etc.
+ * - Extensions - Loadable extensions
+ * - SQLite-specific Types - INTEGER PRIMARY KEY, affinity
+ * - Constraints - CHECK, UNIQUE, NOT NULL with ON CONFLICT
+ */
+import { QueryResult } from './types';
+import { SQLiteDialect } from './dialects/sqlite';
+/**
+ * Trigger timing options
+ */
+export type TriggerTiming = 'BEFORE' | 'AFTER' | 'INSTEAD OF';
+/**
+ * Trigger event options
+ */
+export type TriggerEvent = 'INSERT' | 'UPDATE' | 'DELETE';
+/**
+ * FTS5 tokenizers
+ */
+export type FTS5Tokenizer = 'porter' | 'unicode61' | 'trigram' | 'ascii';
+/**
+ * Generated column storage type
+ */
+export type GeneratedStorageType = 'VIRTUAL' | 'STORED';
+/**
+ * Conflict resolution algorithms
+ */
+export type ConflictAlgorithm = 'ROLLBACK' | 'ABORT' | 'FAIL' | 'IGNORE' | 'REPLACE';
+/**
+ * SQLite Advanced Features Class
+ * Provides comprehensive SQLite-specific features beyond standard SQL
+ */
+export declare class SQLiteAdvanced {
+    private dialect;
+    private connection;
+    constructor(dialect: SQLiteDialect);
+    /**
+     * Create a standard or updatable view
+     * SQLite views are read-only by default, but can be made updatable via INSTEAD OF triggers
+     */
+    createView(viewName: string, query: string, options?: {
+        replace?: boolean;
+        temporary?: boolean;
+        columns?: string[];
+    }): Promise<void>;
+    /**
+     * Drop a view
+     */
+    dropView(viewName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * List all views in the database
+     */
+    listViews(schema?: string): Promise<string[]>;
+    /**
+     * Get view definition
+     */
+    getViewDefinition(viewName: string): Promise<string | null>;
+    /**
+     * Create a trigger
+     */
+    createTrigger(triggerName: string, timing: TriggerTiming, events: TriggerEvent[], tableName: string, body: string, options?: {
+        replace?: boolean;
+        forEachRow?: boolean;
+        whenCondition?: string;
+    }): Promise<void>;
+    /**
+     * Create an AFTER INSERT trigger
+     */
+    createAfterInsertTrigger(triggerName: string, tableName: string, body: string): Promise<void>;
+    /**
+     * Create an AFTER UPDATE trigger
+     */
+    createAfterUpdateTrigger(triggerName: string, tableName: string, body: string, columns?: string[]): Promise<void>;
+    /**
+     * Create an AFTER DELETE trigger
+     */
+    createAfterDeleteTrigger(triggerName: string, tableName: string, body: string): Promise<void>;
+    /**
+     * Create a BEFORE INSERT trigger
+     */
+    createBeforeInsertTrigger(triggerName: string, tableName: string, body: string): Promise<void>;
+    /**
+     * Create a BEFORE UPDATE trigger
+     */
+    createBeforeUpdateTrigger(triggerName: string, tableName: string, body: string): Promise<void>;
+    /**
+     * Create an INSTEAD OF trigger (for views)
+     */
+    createInsteadOfTrigger(triggerName: string, viewName: string, events: TriggerEvent[], body: string): Promise<void>;
+    /**
+     * Create a recursive trigger
+     */
+    createRecursiveTrigger(triggerName: string, tableName: string, insertBody: string, updateBody: string, deleteBody?: string): Promise<void>;
+    /**
+     * Drop a trigger
+     */
+    dropTrigger(triggerName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * List all triggers
+     */
+    listTriggers(tableName?: string): Promise<string[]>;
+    /**
+     * Get trigger definition
+     */
+    getTriggerDefinition(triggerName: string): Promise<string | null>;
+    /**
+     * Create an FTS5 virtual table for full-text search
+     */
+    createFTS5Table(tableName: string, columns: {
+        name: string;
+        type?: string;
+        notindexed?: boolean;
+    }[], options?: {
+        tokenizer?: FTS5Tokenizer | {
+            name: FTS5Tokenizer;
+            options?: Record<string, unknown>;
+        };
+        content?: string;
+        contentRowId?: string;
+        prefix?: number[] | 'all';
+    }): Promise<void>;
+    /**
+     * Create FTS5 table with existing content table
+     */
+    createFTS5FromTable(ftsTableName: string, sourceTable: string, sourceColumns: string[], options?: {
+        tokenizer?: FTS5Tokenizer;
+    }): Promise<void>;
+    /**
+     * Drop an FTS5 table
+     */
+    dropFTS5Table(tableName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * Perform full-text search
+     */
+    fullTextSearch(ftsTable: string, searchQuery: string, options?: {
+        columns?: string[];
+        orderBy?: {
+            column: string;
+            desc?: boolean;
+        }[];
+        limit?: number;
+        offset?: number;
+        highlight?: {
+            before?: string;
+            after?: string;
+            column?: string;
+        };
+        snippet?: {
+            before?: string;
+            after?: string;
+            columns?: string[];
+            maxTokens?: number;
+        };
+        bm25?: boolean;
+    }): Promise<QueryResult>;
+    /**
+     * Rebuild FTS5 index
+     */
+    rebuildFTS5(tableName: string): Promise<void>;
+    /**
+     * Optimize FTS5 index
+     */
+    optimizeFTS5(tableName: string): Promise<void>;
+    /**
+     * Parse JSON string
+     */
+    parseJson(jsonString: string): unknown;
+    /**
+     * Extract value from JSON
+     */
+    jsonExtract(jsonColumn: string, path: string): string;
+    /**
+     * Set value in JSON
+     */
+    jsonSet(jsonColumn: string, path: string, value: unknown): string;
+    /**
+     * Insert into JSON array
+     */
+    jsonArrayAppend(jsonColumn: string, path: string, value: unknown): string;
+    /**
+     * Remove from JSON
+     */
+    jsonRemove(jsonColumn: string, path: string): string;
+    /**
+     * Get JSON array length
+     */
+    jsonArrayLength(jsonColumn: string, path?: string): string;
+    /**
+     * Check if JSON contains value
+     *
+     * Note: SQLite's JSON1 extension has no `json_contains` function (that name is
+     * MySQL-specific); calling this would fail at runtime with "no such function:
+     * json_contains". Emulate it with json_extract() equality instead.
+     */
+    jsonContains(jsonColumn: string, value: unknown, path?: string): string;
+    /**
+     * Query JSON array as table
+     */
+    jsonEach(jsonColumn: string, path?: string): string;
+    /**
+     * Query JSON object as table
+     */
+    jsonTree(jsonColumn: string, path?: string): string;
+    /**
+     * Get JSON type
+     */
+    jsonType(jsonColumn: string, path?: string): string;
+    /**
+     * Valid JSON check
+     */
+    jsonValid(jsonColumn: string): string;
+    /**
+     * Query using json_each (table-valued function)
+     */
+    jsonEachQuery(jsonColumn: string, path?: string, options?: {
+        key?: string;
+        value?: string;
+        type?: string;
+        id?: string;
+        parent?: string;
+    }): Promise<QueryResult>;
+    /**
+     * Create table with generated columns
+     */
+    createTableWithGeneratedColumns(tableName: string, columns: {
+        name: string;
+        type: string;
+        primaryKey?: boolean;
+        notNull?: boolean;
+        defaultValue?: unknown;
+        generated?: {
+            expression: string;
+            type: GeneratedStorageType;
+        };
+    }[]): string;
+    /**
+     * Create a VIRTUAL generated column
+     */
+    createVirtualColumn(name: string, type: string, expression: string): string;
+    /**
+     * Create a STORED generated column
+     */
+    createStoredColumn(name: string, type: string, expression: string): string;
+    /**
+     * Create a UNIQUE index
+     */
+    createUniqueIndex(tableName: string, indexName: string, columns: string[]): Promise<void>;
+    /**
+     * Create a partial index (with WHERE clause)
+     */
+    createPartialIndex(tableName: string, indexName: string, columns: string[], whereCondition: string): Promise<void>;
+    /**
+     * Create an expression index
+     */
+    createExpressionIndex(tableName: string, indexName: string, expression: string): Promise<void>;
+    /**
+     * Create an index with IF NOT EXISTS
+     */
+    createIndexIfNotExists(tableName: string, indexName: string, columns: string[], options?: {
+        unique?: boolean;
+        where?: string;
+    }): Promise<void>;
+    /**
+     * List all indexes for a table
+     */
+    listIndexes(tableName: string): Promise<{
+        name: string;
+        unique: boolean;
+        partial: boolean;
+    }[]>;
+    /**
+     * Reindex a table or database
+     */
+    reindex(target?: string): Promise<void>;
+    /**
+     * Build a window function query
+     */
+    buildWindowFunction(functionName: string, options?: {
+        distinct?: boolean;
+        filter?: string;
+        over?: {
+            partitionBy?: string[];
+            orderBy?: {
+                column: string;
+                desc?: boolean;
+            }[];
+            rows?: {
+                start?: number;
+                end?: number;
+            };
+            range?: {
+                start?: number;
+                end?: number;
+            };
+            frame?: 'ROWS' | 'RANGE' | 'GROUPS';
+        };
+    }): string;
+    /**
+     * ROW_NUMBER() window function
+     */
+    rowNumber(options?: {
+        partitionBy?: string[];
+        orderBy?: {
+            column: string;
+            desc?: boolean;
+        }[];
+    }): string;
+    /**
+     * RANK() window function
+     */
+    rank(options?: {
+        partitionBy?: string[];
+        orderBy?: {
+            column: string;
+            desc?: boolean;
+        }[];
+    }): string;
+    /**
+     * DENSE_RANK() window function
+     */
+    denseRank(options?: {
+        partitionBy?: string[];
+        orderBy?: {
+            column: string;
+            desc?: boolean;
+        }[];
+    }): string;
+    /**
+     * NTILE(n) window function
+     */
+    ntile(n: number, options?: {
+        partitionBy?: string[];
+        orderBy?: {
+            column: string;
+            desc?: boolean;
+        }[];
+    }): string;
+    /**
+     * LAG() window function
+     */
+    lag(column: string, offset?: number, defaultValue?: unknown): string;
+    /**
+     * LEAD() window function
+     */
+    lead(column: string, offset?: number, defaultValue?: unknown): string;
+    /**
+     * FIRST_VALUE() window function
+     */
+    firstValue(column: string): string;
+    /**
+     * LAST_VALUE() window function
+     */
+    lastValue(column: string): string;
+    /**
+     * NTH_VALUE() window function
+     */
+    nthValue(column: string, n: number): string;
+    /**
+     * Build a CTE query
+     */
+    buildCTE(cteName: string, columns: string[], query: string, recursive?: boolean): string;
+    /**
+     * Build multiple CTEs
+     */
+    buildMultipleCTEs(ctes: {
+        name: string;
+        columns?: string[];
+        query: string;
+    }[], mainQuery: string, recursive?: boolean): string;
+    /**
+     * Execute a recursive CTE query
+     */
+    executeRecursiveCTE(cteName: string, baseQuery: string, recursiveQuery: string, finalQuery: string): Promise<QueryResult>;
+    /**
+     * Recursive CTE example: Generate sequence
+     */
+    generateSequence(start: number, end: number): string;
+    /**
+     * VACUUM the database
+     * Reclaims disk space and defragments the database
+     */
+    vacuum(options?: {
+        schema?: string;
+        shrinkTo?: number;
+        analyze?: boolean;
+    }): Promise<void>;
+    /**
+     * ANALYZE the database
+     * Updates statistics for the query optimizer
+     */
+    analyze(target?: string): Promise<void>;
+    /**
+     * ANALYZE with detailed information
+     */
+    analyzeDetailed(tableName?: string): Promise<QueryResult>;
+    /**
+     * Get table statistics
+     */
+    getTableStats(tableName: string): Promise<QueryResult>;
+    /**
+     * Get index statistics
+     */
+    getIndexStats(indexName: string): Promise<QueryResult>;
+    /**
+     * Create a savepoint
+     */
+    savepoint(savepointName: string): Promise<void>;
+    /**
+     * Release a savepoint
+     */
+    releaseSavepoint(savepointName: string): Promise<void>;
+    /**
+     * Rollback to a savepoint
+     */
+    rollbackToSavepoint(savepointName: string): Promise<void>;
+    /**
+     * Execute within a savepoint
+     */
+    withSavepoint<T>(savepointName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Build an UPSERT query
+     */
+    buildUpsertQuery(tableName: string, columns: string[], conflictColumns: string[], updateColumns?: string[], options?: {
+        ignore?: boolean;
+        replace?: boolean;
+    }): string;
+    /**
+     * Perform an upsert
+     */
+    upsert(tableName: string, values: Record<string, unknown>, conflictColumns: string[], updateColumns?: string[]): Promise<QueryResult>;
+    /**
+     * Use json_each as table-valued function
+     */
+    jsonEachAsTable(jsonColumn: string, path?: string): Promise<QueryResult>;
+    /**
+     * Use json_tree as table-valued function
+     */
+    jsonTreeAsTable(jsonColumn: string, path?: string): Promise<QueryResult>;
+    /**
+     * Generate series using recursive CTE
+     */
+    generateSeries(start: number, end: number, step?: number): Promise<QueryResult>;
+    /**
+     * Use fts5 as table-valued function
+     */
+    fts5Search(ftsTable: string, query: string): Promise<QueryResult>;
+    /**
+     * Load a SQLite extension
+     */
+    loadExtension(extensionPath: string): void;
+    /**
+     * Enable/disable extension loading
+     */
+    setExtensionLoading(enabled: boolean): void;
+    /**
+     * Get list of loaded extensions
+     */
+    getLoadedExtensions(): string[];
+    /**
+     * Create INTEGER PRIMARY KEY column definition
+     */
+    createIntegerPrimaryKey(columnName: string, autoIncrement?: boolean): string;
+    /**
+     * Create column with specific affinity
+     */
+    createColumnWithAffinity(columnName: string, affinity: 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'NUMERIC'): string;
+    /**
+     * Get column affinity
+     */
+    getColumnAffinity(type: string): string;
+    /**
+     * Create CHECK constraint
+     */
+    createCheckConstraint(columnName: string, condition: string): string;
+    /**
+     * Create table with ON CONFLICT clause
+     */
+    createTableWithOnConflict(tableName: string, columns: {
+        name: string;
+        type: string;
+        constraints?: string[];
+    }[], conflictAlgorithm?: ConflictAlgorithm): string;
+    /**
+     * Add ON CONFLICT to column definition
+     */
+    addOnConflictClause(constraint: string, conflictAlgorithm: ConflictAlgorithm): string;
+    /**
+     * Create UNIQUE constraint
+     */
+    createUniqueConstraint(columns: string[]): string;
+    /**
+     * Create NOT NULL constraint with ON CONFLICT
+     */
+    createNotNullConstraint(columnName: string, conflictAlgorithm?: ConflictAlgorithm): string;
+    /**
+     * Execute a PRAGMA command
+     */
+    pragma(pragmaName: string, value?: unknown): Promise<QueryResult>;
+    /**
+     * Get database info
+     */
+    getDatabaseInfo(): Promise<{
+        schemaVersion: number;
+        userVersion: number;
+        foreignKeys: boolean;
+        journalingMode: string;
+        synchronous: string;
+        cacheSize: number;
+        pageSize: number;
+    }>;
+    /**
+     * Set database options
+     */
+    setDatabaseOptions(options: {
+        foreignKeys?: boolean;
+        journalingMode?: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
+        synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+        cacheSize?: number;
+    }): Promise<void>;
+    /**
+     * Get table info using PRAGMA
+     */
+    getTableInfo(tableName: string): Promise<QueryResult>;
+    /**
+     * Get index list for table
+     */
+    getIndexList(tableName: string): Promise<QueryResult>;
+    /**
+     * Get foreign key list for table
+     */
+    getForeignKeyList(tableName: string): Promise<QueryResult>;
+    /**
+     * Escape identifier
+     */
+    escapeId(identifier: unknown): string;
+    /**
+     * Escape a JSON path (or any other value) for safe interpolation inside a
+     * single-quoted SQL string literal, by doubling embedded single quotes.
+     */
+    private escapePathLiteral;
+    /**
+     * Escape value
+     */
+    escape(value: unknown): string;
+}
+/**
+ * Create SQLiteAdvanced instance from dialect
+ */
+export declare function createSQLiteAdvanced(dialect: SQLiteDialect): SQLiteAdvanced;

package/dist/streams/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stream utilities for ORM operations
+ * Provides transform streams for streaming data processing
+ */
+export { MapTransform, FilterTransform, BatchTransform, StreamIterator, MapTransformOptions, FilterTransformOptions, BatchTransformOptions, StreamIteratorOptions, } from './transforms';

package/dist/streams/transforms.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Transform streams for ORM operations
+ * Provides MapTransform and FilterTransform for streaming data processing
+ */
+import { Transform, TransformOptions } from 'stream';
+/**
+ * Options for MapTransform
+ */
+export interface MapTransformOptions<T = any, R = any> extends TransformOptions {
+    /**
+     * Transform function to apply to each record
+     */
+    mapFn: (record: T) => R | Promise<R>;
+    /**
+     * Number of records to buffer (default: 1000)
+     */
+    highWaterMark?: number;
+}
+/**
+ * Transform stream that maps each record through a transform function
+ * Supports both synchronous and asynchronous transform functions
+ */
+export declare class MapTransform<T = any, R = any> extends Transform {
+    private mapFn;
+    constructor(options: MapTransformOptions<T, R>);
+    /**
+     * Transform a chunk (record)
+     */
+    _transform(record: T, encoding: string, callback: (error?: Error | null, data?: R) => void): Promise<void>;
+}
+/**
+ * Options for FilterTransform
+ */
+export interface FilterTransformOptions<T = any> extends TransformOptions {
+    /**
+     * Filter function to determine if a record should be included
+     */
+    filterFn: (record: T) => boolean | Promise<boolean>;
+    /**
+     * Number of records to buffer (default: 1000)
+     */
+    highWaterMark?: number;
+}
+/**
+ * Transform stream that filters records based on a predicate function
+ * Supports both synchronous and asynchronous filter functions
+ */
+export declare class FilterTransform<T = any> extends Transform {
+    private filterFn;
+    constructor(options: FilterTransformOptions<T>);
+    /**
+     * Transform and filter a chunk (record)
+     */
+    _transform(record: T, encoding: string, callback: (error?: Error | null, data?: T) => void): Promise<void>;
+}
+/**
+ * Options for BatchTransform
+ */
+export interface BatchTransformOptions<T = any> extends TransformOptions {
+    /**
+     * Batch size for grouping records
+     */
+    batchSize: number;
+    /**
+     * Number of records to buffer (default: 1000)
+     */
+    highWaterMark?: number;
+}
+/**
+ * Transform stream that batches records into arrays
+ */
+export declare class BatchTransform<T = any> extends Transform {
+    private batchSize;
+    private buffer;
+    constructor(options: BatchTransformOptions<T>);
+    /**
+     * Transform - batch records
+     */
+    _transform(record: T, encoding: string, callback: (error?: Error | null, data?: T[]) => void): void;
+    /**
+     * Flush remaining records in buffer
+     */
+    _flush(callback: (error?: Error | null, data?: T[]) => void): void;
+}
+/**
+ * Options for StreamIterator
+ */
+export interface StreamIteratorOptions<T = any> extends TransformOptions {
+    /**
+     * Number of records to buffer (default: 1000)
+     */
+    highWaterMark?: number;
+}
+/**
+ * Transform stream that converts a readable stream into an async iterator
+ * Allows using stream.pipe(new StreamIterator()) and then for await...of
+ */
+export declare class StreamIterator<T = any> extends Transform {
+    private buffer;
+    private waiting;
+    private ended;
+    private error;
+    constructor(options?: StreamIteratorOptions<T>);
+    /**
+     * Transform a chunk
+     */
+    _transform(chunk: T, encoding: string, callback: (error?: Error | null, data?: T) => void): void;
+    /**
+     * Handle stream end
+     */
+    _flush(callback: (error?: Error | null, data?: T) => void): void;
+    /**
+     * Process waiting promises
+     */
+    private _processWaiting;
+    /**
+     * Create async iterator from this transform stream
+     */
+    [Symbol.asyncIterator](): NodeJS.AsyncIterator<any, any, unknown>;
+}