ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/duckdb/index.d.ts

@@ -0,0 +1,440 @@
+/**
+ * DuckDB dialect implementation
+ *
+ * DuckDB is an embedded, in-process OLAP database (similar in deployment
+ * model to SQLite - a single file or `:memory:`, no server/host/port/auth)
+ * but with a genuinely modern analytical SQL engine: real window functions,
+ * recursive CTEs, rich composite types (LIST/STRUCT/MAP), first-class
+ * Parquet/CSV/JSON table functions, native sequences, and a real extension
+ * system (INSTALL/LOAD).
+ *
+ * The `duckdb` npm driver's public API (`duckdb/lib/duckdb.d.ts`) is
+ * callback-based (`new duckdb.Database(path, cb)`, `db.all(sql, ...args, cb)`,
+ * `db.run(sql, ...args, cb)`). All of that is wrapped in Promises here.
+ */
+import type * as duckdb from 'duckdb';
+import { Dialect, DialectOptions, ColumnDefinition, TableOptions, DropTableOptions, TableDescription, IndexOptions, IndexDefinition, InsertOptions, UpdateOptions as DUpdateOptions, DeleteOptions, SelectOptions, UpsertQueryOptions, ConstraintDefinition, DropConstraintOptions, DropIndexOptions, ViewOptions, DropViewOptions, DropSchemaOptions, CreateExtensionOptions, DropExtensionOptions, ExtensionInfo, BuildOptions, FdwForeignServerOptions, FdwAlterForeignServerOptions, FdwUserMappingOptions, FdwForeignTableOptions, FdwImportForeignSchemaOptions } from '../dialect';
+import { Transaction, TransactionOptions, QueryResult, QueryOptions, DataType, WhereOptions, Order, CreatePartitionOptions, AttachPartitionOptions, DetachPartitionOptions, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, TriggerOptions, DropTriggerOptions, SequenceOptions, DropSequenceOptions, StreamOptions } from '../../types';
+import { Readable } from 'stream';
+/**
+ * A single `ON CONFLICT (...) DO ...` target for multi-target upserts, mirroring
+ * SQLite's chained-conflict-target support (DuckDB's `ON CONFLICT` grammar is the
+ * same PostgreSQL-derived grammar SQLite adopted).
+ */
+export interface ConflictTarget {
+    fields: string[];
+    action?: 'DO NOTHING' | 'DO UPDATE';
+    updateColumns?: string[];
+    where?: string;
+}
+/**
+ * Options accepted by the DuckDB dialect.
+ *
+ * DuckDB is embedded (like SQLite): there is no host/port/username/password -
+ * everything is a local file path or `:memory:`. `DuckDBDialectOptions`
+ * extends the shared `DialectOptions` (which declares those network fields as
+ * optional) purely so the constructor accepts the same shape other dialects
+ * do without a type error when callers pass a generic config object; any
+ * host/port/username/password values are accepted and silently ignored.
+ */
+export interface DuckDBDialectOptions extends DialectOptions {
+    /** File path to the database, or ':memory:' (default) */
+    storage?: string;
+    /** Open the database in read-only mode */
+    readonly?: boolean;
+    /** DuckDB config options passed through to the Database constructor (e.g. { max_memory: '4GB' }) */
+    config?: Record<string, string>;
+}
+/**
+ * DuckDB dialect class implementing the shared `Dialect` interface.
+ */
+export declare class DuckDBDialect implements Dialect {
+    readonly name = "duckdb";
+    readonly library = "duckdb";
+    private db;
+    private connection;
+    private _isConnected;
+    private config;
+    private transactionDepth;
+    constructor(config: DuckDBDialectOptions);
+    /**
+     * Connect to the DuckDB database (embedded - opens a local file or :memory:).
+     * host/port/username/password (if present on the config for API parity with
+     * networked dialects) are intentionally ignored - DuckDB is single-process.
+     */
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnection(): duckdb.Connection | null;
+    isConnected(): boolean;
+    /**
+     * Stream query results by paging through `sql` via repeated
+     * dialect-appropriate LIMIT/OFFSET queries (see
+     * `createPaginatedQueryStream()` in `src/dialects/query-stream-helper.ts`)
+     * instead of loading the whole result set into memory at once.
+     * @param sql - The SELECT statement to stream
+     * @param options - Streaming options (batch size, backpressure watermark, model mapping)
+     */
+    queryStream(sql: string, options?: StreamOptions): Readable;
+    /**
+     * Execute a raw SQL query with retry support.
+     */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    private executeWithRetry;
+    /**
+     * Replace placeholders in SQL with actual values.
+     */
+    replaceReplacements(sql: string, replacements?: Record<string, unknown> | unknown[]): string;
+    /**
+     * Escape a value for use in a query. DuckDB uses standard SQL literals -
+     * TRUE/FALSE for booleans (not 0/1), single-quoted strings, and a
+     * `'\x..'::BLOB` cast for binary data.
+     */
+    escape(value: unknown): string;
+    private escapeString;
+    escapeId(identifier: unknown): string;
+    quoteIdentifier(identifier: string): string;
+    quoteTable(tableName: string, schema?: string): string;
+    getDatabaseVersion(): Promise<string>;
+    createDatabaseSQL(options: {
+        name: string;
+        encoding?: string;
+        lcCollate?: string;
+        lcCtype?: string;
+        template?: string;
+        tablespace?: string;
+        collate?: string;
+        isTemplate?: boolean;
+    }): string;
+    dropDatabaseSQL(name: string): string;
+    /**
+     * Attach another DuckDB (or SQLite/Postgres, via the respective DuckDB
+     * extension) database file under `alias`, making it queryable as
+     * `alias.table`.
+     */
+    attachDatabase(path: string, alias: string, options?: {
+        readOnly?: boolean;
+        type?: string;
+    }): Promise<void>;
+    detachDatabase(alias: string): Promise<void>;
+    createSavepointSQL(name?: string): string;
+    releaseSavepointSQL(name: string): string;
+    rollbackToSavepointSQL(name: string): string;
+    createSchema(schema: string): Promise<void>;
+    dropSchema(schema: string, options?: DropSchemaOptions): Promise<void>;
+    showAllSchemas(): Promise<string[]>;
+    listSchemas(): Promise<string[]>;
+    createExtension(extensionName: string, options?: CreateExtensionOptions): Promise<void>;
+    dropExtension(_extensionName: string, _options?: DropExtensionOptions): Promise<void>;
+    getExtensions(): Promise<ExtensionInfo[]>;
+    hasExtension(extensionName: string): Promise<boolean>;
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions): Promise<void>;
+    private _autoIncrementSequenceName;
+    private buildConstraintSql;
+    private getColumnDefinitionSql;
+    private getDefaultValue;
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    createPartitionedTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions & {
+        partitionBy: {
+            type: 'range' | 'list' | 'hash';
+            column: string | string[];
+        };
+        partitions?: {
+            name: string;
+            bound?: any;
+            tablespace?: string;
+            storageParameters?: Record<string, string | number>;
+        }[];
+    }): Promise<void>;
+    createPartition(options: CreatePartitionOptions): Promise<void>;
+    attachPartition(options: AttachPartitionOptions): Promise<void>;
+    detachPartition(options: DetachPartitionOptions): Promise<void>;
+    dropPartition(partitionName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    listPartitions(tableName: string): Promise<Array<{
+        name: string;
+        parent_table: string;
+        bound: string | null;
+        is_detached: boolean;
+    }>>;
+    createView(viewName: string, query: string, options?: ViewOptions): Promise<void>;
+    dropView(viewName: string, options?: DropViewOptions): Promise<void>;
+    showViews(): Promise<string[]>;
+    /**
+     * Materialized views (not supported). DuckDB has no `CREATE MATERIALIZED
+     * VIEW` statement - the closest equivalents are a plain table populated via
+     * `CREATE TABLE ... AS SELECT ...` (refreshed by re-running the query) or
+     * exporting to Parquet with `copyTo()` and reading it back with
+     * `readParquet()`.
+     */
+    createMaterializedView(): Promise<void>;
+    refreshMaterializedView(): Promise<void>;
+    dropMaterializedView(): Promise<void>;
+    hasMaterializedView(): Promise<boolean>;
+    showMaterializedViews(): Promise<string[]>;
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    changeColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    renameColumn(tableName: string, oldColumnName: string, newColumnName: string): Promise<void>;
+    addForeignKey(tableName: string, _columnName: string, _referencedTableName: string, _referencedColumnName: string): Promise<void>;
+    bulkInsert(tableName: string, records: Record<string, any>[], _options?: any): Promise<QueryResult>;
+    showTables(): Promise<string[]>;
+    showConstraints(tableName: string): Promise<any[]>;
+    addConstraint(tableName: string, options: {
+        type: 'UNIQUE' | 'CHECK' | 'PRIMARY KEY' | 'FOREIGN KEY';
+        fields: string[];
+        name?: string;
+        references?: {
+            table: string;
+            fields: string[];
+        };
+        check?: string;
+    }): Promise<void>;
+    removeConstraint(tableName: string, constraintName: string): Promise<void>;
+    showIndexes(tableName: string): Promise<any[]>;
+    describeTable(tableName: string): Promise<TableDescription>;
+    renameTable(oldName: string, newName: string): Promise<void>;
+    addIndex(tableName: string, indexName: string, fields?: string[], options?: IndexOptions): Promise<void>;
+    removeIndex(_tableName: string, indexName: string): Promise<void>;
+    createIndex(tableName: string, indexDef: IndexDefinition): Promise<void>;
+    createFulltextIndex(): Promise<void>;
+    createSpatialIndex(): Promise<void>;
+    dropIndex(_tableName: string, indexName: string, _options?: DropIndexOptions): Promise<void>;
+    createConstraint(tableName: string, constraintDef: ConstraintDefinition): Promise<void>;
+    dropConstraint(tableName: string, constraintName: string, options?: DropConstraintOptions): Promise<void>;
+    changeOwner(): Promise<void>;
+    private fdwNotSupported;
+    createForeignDataWrapper(): Promise<void>;
+    dropForeignDataWrapper(): Promise<void>;
+    createForeignServer(): Promise<void>;
+    dropForeignServer(): Promise<void>;
+    createForeignTable(): Promise<void>;
+    buildCreateServerQuery(_name: string, _opts: FdwForeignServerOptions): string;
+    buildAlterServerQuery(_name: string, _opts: FdwAlterForeignServerOptions): string;
+    buildDropServerQuery(): string;
+    buildCreateUserMappingQuery(_opts: FdwUserMappingOptions): string;
+    buildAlterUserMappingQuery(_opts: FdwUserMappingOptions): string;
+    buildDropUserMappingQuery(): string;
+    createUserMapping(): Promise<void>;
+    dropUserMapping(): Promise<void>;
+    buildCreateForeignTableQuery(_tableName: string, _opts: FdwForeignTableOptions): string;
+    buildDropForeignTableQuery(): string;
+    buildImportForeignSchemaQuery(_remoteSchema: string, _serverName: string, _opts?: FdwImportForeignSchemaOptions): string;
+    getServersQuery(): string;
+    createSecurityPolicy(): Promise<void>;
+    dropSecurityPolicy(): Promise<void>;
+    private userMgmtNotSupported;
+    buildCreateUserQuery(): string;
+    buildAlterUserQuery(): string;
+    buildDropUserQuery(): string;
+    getUsersQuery(): string;
+    buildGrantQuery(): string;
+    buildRevokeQuery(): string;
+    buildShowGrantsQuery(): string;
+    buildFlushPrivilegesQuery(): string;
+    buildCreateRoleQuery(): string;
+    buildDropRoleQuery(): string;
+    buildGrantRoleQuery(): string;
+    buildRevokeRoleQuery(): string;
+    getRolesQuery(): string;
+    createStoredProcedure(options: StoredProcedureOptions): Promise<void>;
+    createProcedure(options: StoredProcedureOptions): Promise<void>;
+    dropStoredProcedure(procedureName: string, _options?: DropStoredProcedureOptions): Promise<void>;
+    dropProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    executeStoredProcedure(options: ExecuteStoredProcedureOptions): Promise<QueryResult>;
+    hasStoredProcedure(): Promise<boolean>;
+    createTrigger(options: TriggerOptions): Promise<void>;
+    dropTrigger(triggerName: string, _tableName: string, _options?: DropTriggerOptions): Promise<void>;
+    hasTrigger(): Promise<boolean>;
+    createSequence(options: SequenceOptions): Promise<void>;
+    dropSequence(sequenceName: string, options?: DropSequenceOptions): Promise<void>;
+    nextSequenceValue(sequenceName: string): Promise<number>;
+    hasSequence(sequenceName: string, schema?: string): Promise<boolean>;
+    listSequences(): Promise<string[]>;
+    createPolicy(): Promise<void>;
+    dropPolicy(): Promise<void>;
+    enableRLS(): Promise<void>;
+    disableRLS(): Promise<void>;
+    hasPolicy(): Promise<boolean>;
+    commentTable(tableName: string, comment: string): Promise<void>;
+    commentColumn(tableName: string, columnName: string, comment: string): Promise<void>;
+    createPartialIndex(): Promise<void>;
+    createExpressionIndex(tableName: string, indexName: string, expression: string, options?: IndexOptions): Promise<void>;
+    createIdentityColumn(tableName: string, columnName: string, options?: {
+        startWith?: number;
+        incrementBy?: number;
+    }): Promise<void>;
+    createComputedColumn(tableName: string, columnName: string, expression: string, options?: {
+        persisted?: boolean;
+        type?: string;
+    }): Promise<void>;
+    startTransaction(options?: TransactionOptions): Promise<Transaction>;
+    commitTransaction(transaction: Transaction): Promise<void>;
+    rollbackTransaction(transaction: Transaction): Promise<void>;
+    getDataTypeSql(dataType: DataType, columnName?: string): string;
+    buildWhereClause(where: WhereOptions, _options?: BuildOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    buildOrderClause(order: Order): string;
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    buildInsertQuery(tableName: string, values: Record<string, unknown>, options?: InsertOptions & {
+        doNothing?: boolean;
+        conflictTargets?: ConflictTarget[];
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    private buildOnConflictClause;
+    private buildConflictTargetsSql;
+    buildUpsertQuery(tableName: string, values: Record<string, unknown>, options?: UpsertQueryOptions & {
+        doNothing?: boolean;
+        conflictTargets?: ConflictTarget[];
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    buildIncrementQuery(tableName: string, fields: string | string[] | Record<string, number>, where: WhereOptions, options?: {
+        by?: number;
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    buildUpdateQuery(tableName: string, values: Record<string, unknown>, where: WhereOptions, options?: DUpdateOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    buildSelectQuery(options: SelectOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Formats a SELECT attribute string: bare identifiers get quoted, anything
+     * that already looks like an expression (function call, `*`, operators,
+     * DuckDB's `EXCLUDE`/`REPLACE` column-transform syntax) passes through
+     * verbatim so callers can supply raw analytical SQL.
+     */
+    private formatMaybeExpression;
+    buildJsonExtract(column: string, path: string, asText?: boolean): string;
+    private escapeStringForJsonPath;
+    buildJsonQuery(column: string, path: string, value?: unknown, operator?: string): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a `read_parquet(...)` table-function expression usable in a FROM
+     * clause, e.g. `FROM ${dialect.readParquet('data/*.parquet')}`.
+     */
+    readParquet(path: string | string[], options?: {
+        hivePartitioning?: boolean;
+        unionByName?: boolean;
+        filename?: boolean;
+        columns?: Record<string, string>;
+    }): string;
+    /**
+     * Build a `read_csv_auto(...)` (or `read_csv(...)` with explicit options)
+     * table-function expression usable in a FROM clause.
+     */
+    readCsv(path: string | string[], options?: {
+        header?: boolean;
+        delim?: string;
+        columns?: Record<string, string>;
+        autoDetect?: boolean;
+        allVarchar?: boolean;
+    }): string;
+    /**
+     * Build a `read_json_auto(...)` (or `read_json(...)` with explicit options)
+     * table-function expression usable in a FROM clause.
+     */
+    readJson(path: string | string[], options?: {
+        format?: 'auto' | 'newline_delimited' | 'array';
+        columns?: Record<string, string>;
+        autoDetect?: boolean;
+    }): string;
+    /**
+     * Export the results of a query straight to a Parquet/CSV/JSON file via
+     * DuckDB's `COPY (query) TO 'file' (FORMAT ...)`.
+     */
+    copyTo(query: string, path: string, format: 'PARQUET' | 'CSV' | 'JSON', options?: {
+        partitionBy?: string[];
+        overwrite?: boolean;
+        compression?: string;
+        header?: boolean;
+    }): Promise<void>;
+    /**
+     * Configure S3 access via DuckDB httpfs `SET s3_...` session/global
+     * variables. Only emits a `SET` statement for options that are actually
+     * provided. Simpler than `createSecret()` but global to the instance (later
+     * calls overwrite earlier ones; there is no per-bucket scoping) - prefer
+     * `createSecret()` when multiple credentials/buckets are in play.
+     *
+     * Requires the `httpfs` extension to be installed/loaded first (see
+     * `createExtension('httpfs')`).
+     */
+    configureS3Credentials(options: {
+        region?: string;
+        accessKeyId?: string;
+        secretAccessKey?: string;
+        sessionToken?: string;
+        endpoint?: string;
+        urlStyle?: 'vhost' | 'path';
+        useSsl?: boolean;
+    }): Promise<void>;
+    /**
+     * Create a named DuckDB Secrets Manager secret of `TYPE S3` for use with
+     * `read_parquet`/`read_csv`/`read_json`/`copyTo` against `s3://` paths.
+     * This is the newer, DuckDB-recommended alternative to
+     * `configureS3Credentials()`'s global `SET s3_...` variables: secrets are
+     * named, can be scoped to a path prefix, and multiple secrets (for
+     * different buckets/credentials) can coexist.
+     *
+     * Requires the `httpfs` extension to be installed/loaded first (see
+     * `createExtension('httpfs')`).
+     */
+    createSecret(name: string, options?: {
+        keyId?: string;
+        secret?: string;
+        region?: string;
+        sessionToken?: string;
+        endpoint?: string;
+        urlStyle?: 'vhost' | 'path';
+        useSsl?: boolean;
+        scope?: string | string[];
+        replace?: boolean;
+        persistent?: boolean;
+    }): Promise<void>;
+    /**
+     * Drop a previously created `CREATE SECRET` (see `createSecret()`).
+     */
+    dropSecret(name: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+}
+/**
+ * DuckDB-specific transaction class. DuckDB supports SAVEPOINT for nested
+ * transactions (in addition to top-level BEGIN/COMMIT/ROLLBACK).
+ */
+export declare class DuckDBTransaction implements Transaction {
+    private dialect?;
+    id: string;
+    finished: boolean;
+    options: TransactionOptions;
+    parent: Transaction | null;
+    savepoints: string[];
+    constructor(depth: number, options?: TransactionOptions, dialect?: {
+        commitTransaction(tx: Transaction): Promise<void>;
+        rollbackTransaction(tx: Transaction): Promise<void>;
+    } | undefined);
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+/**
+ * Create a new DuckDB dialect instance.
+ */
+export declare function createDuckDBDialect(options?: DuckDBDialectOptions): DuckDBDialect;
+export default DuckDBDialect;

package/dist/dialects/duckdb/index.js

@@ -13,43 +13,26 @@
  * callback-based (`new duckdb.Database(path, cb)`, `db.all(sql, ...args, cb)`,
  * `db.run(sql, ...args, cb)`). All of that is wrapped in Promises here.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DuckDBTransaction = exports.DuckDBDialect = void 0;
 exports.createDuckDBDialect = createDuckDBDialect;
-const duckdb = __importStar(require("duckdb"));
+// Lazily-loaded `duckdb` driver. This native addon is only loaded the first
+// time a connection is opened, so importing this ORM never dlopens the duckdb
+// native binding.
+let duckdbModule = null;
+function loadDuckDb() {
+    if (!duckdbModule) {
+        try {
+            duckdbModule = require('duckdb');
+        }
+        catch (err) {
+            throw new Error("The 'duckdb' package is required to use the DuckDB dialect but could not be loaded. " +
+                'Install it with `npm install duckdb`. Original error: ' +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return duckdbModule;
+}
 const query_stream_helper_1 = require("../query-stream-helper");
 const prorm_1 = require("../../prorm");
 const operators_1 = require("../../operators");
@@ -127,7 +110,7 @@ class DuckDBDialect {
                         accessMode = { ...accessMode, access_mode: 'READ_ONLY' };
                     }
                     else if (!accessMode) {
-                        accessMode = duckdb.OPEN_READONLY;
+                        accessMode = loadDuckDb().OPEN_READONLY;
                     }
                 }
                 const cb = (err) => {
@@ -142,9 +125,10 @@ class DuckDBDialect {
                     else
                         resolve(database);
                 };
+                const DuckDbDatabase = loadDuckDb().Database;
                 const database = accessMode
-                    ? new duckdb.Database(this.config.storage, accessMode, cb)
-                    : new duckdb.Database(this.config.storage, cb);
+                    ? new DuckDbDatabase(this.config.storage, accessMode, cb)
+                    : new DuckDbDatabase(this.config.storage, cb);
             });
             this.connection = this.db.connect();
             this._isConnected = true;