ts-prorm-orm 1.1.0 → 1.2.1

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

@@ -0,0 +1,230 @@
+/**
+ * Trino (formerly PrestoSQL) dialect implementation for the TypeScript ORM.
+ *
+ * Trino is a distributed, federated SQL query engine. It is *not* a storage
+ * engine of its own: it runs ANSI SQL over pluggable connectors (Hive, Iceberg,
+ * MySQL, PostgreSQL, Kafka, ...). Because its SQL surface is ANSI-flavored and
+ * it quotes identifiers with double quotes (like PostgreSQL), this dialect
+ * extends {@link PostgresDialect} and overrides only where Trino differs.
+ *
+ * Key differences from PostgreSQL that this dialect implements:
+ *
+ * - **Default port 8080.** Trino's HTTP/query port is 8080, not 5432.
+ *   The constructor injects it via `super({ port: 8080, ...config })`.
+ *
+ * - **Three-part table names: `catalog.schema.table`.** A Trino table lives in
+ *   a connector *catalog* and a *schema*. When a `catalog` is configured (and,
+ *   optionally, a default `schema`), {@link TrinoDialect.quoteTable} emits the
+ *   fully-qualified `"catalog"."schema"."table"` form. Without a catalog it
+ *   falls back to the PostgreSQL `schema.table` behavior.
+ *
+ * - **Connector table properties via `WITH (...)`.** `CREATE TABLE ... WITH
+ *   (format = 'ORC', partitioning = ARRAY['col'])` configures the underlying
+ *   connector (file format, partitioning, bucketing, ...). Exposed through
+ *   {@link TrinoTableOptions} (`format`, `partitioning`, `tableProperties`).
+ *
+ * - **`CREATE TABLE AS SELECT` (CTAS).** Trino's primary way to materialize a
+ *   table from a query. Exposed via {@link TrinoDialect.buildCreateTableAsSelectSQL}
+ *   (sync SQL builder) and {@link TrinoDialect.createTableAsSelect} (executes it).
+ *
+ * - **No PRIMARY KEY / FOREIGN KEY / UNIQUE enforcement.** Trino does not
+ *   support (or enforce) key constraints — `CREATE TABLE` here omits any
+ *   `PRIMARY KEY`, `FOREIGN KEY`, or `UNIQUE` clause entirely. Constraint
+ *   metadata on columns/tables is ignored for DDL purposes.
+ *
+ * - **No AUTO_INCREMENT / identity / sequences.** Trino has no
+ *   SERIAL/BIGSERIAL/IDENTITY. Surrogate keys are *not* auto-generated;
+ *   application code (or the source connector) must supply key values. The
+ *   `autoIncrement` column flag is ignored.
+ *
+ * - **Type mapping.** Trino uses unbounded `VARCHAR` (no length required),
+ *   `DOUBLE` (not `DOUBLE PRECISION`), `BOOLEAN`, and `TIMESTAMP`. See
+ *   {@link TrinoDialect.getDataTypeSql}.
+ */
+import { PostgresDialect, PostgresDialectOptions } from '../postgres/index';
+import { ColumnDefinition, TableOptions, DropTableOptions, InsertOptions, UpdateOptions, DeleteOptions, UpsertQueryOptions, IndexOptions, IndexDefinition, DropIndexOptions } from '../dialect';
+import { DataType, WhereOptions } from '../../types';
+/**
+ * Trino-specific connection options. Adds a connector `catalog` and default
+ * `schema` on top of the PostgreSQL options; both feed the three-part naming
+ * in {@link TrinoDialect.quoteTable}.
+ */
+export interface TrinoDialectOptions extends PostgresDialectOptions {
+    /** Connector catalog (e.g. `'hive'`, `'iceberg'`). Enables `catalog.schema.table` naming. */
+    catalog?: string;
+    /** Default schema used when a query/table doesn't specify one. */
+    schema?: string;
+}
+/**
+ * Trino connector table properties, emitted as `CREATE TABLE ... WITH (...)`.
+ */
+export interface TrinoTableOptions extends TableOptions {
+    /** Storage file format, e.g. `'ORC'`, `'PARQUET'`, `'AVRO'`. Emits `format = '...'`. */
+    format?: string;
+    /** Partitioning columns, emitted as `partitioning = ARRAY['col1', 'col2']`. */
+    partitioning?: string[];
+    /** Arbitrary additional connector properties, emitted as `key = value` (strings are quoted). */
+    tableProperties?: Record<string, string | number | boolean>;
+    /** Schema override for this specific table. */
+    schema?: string;
+}
+/**
+ * Options for {@link TrinoDialect.buildCreateTableAsSelectSQL} / createTableAsSelect.
+ */
+export interface TrinoCTASOptions extends TrinoTableOptions {
+    /** Emit `WITH NO DATA` to create the table structure without copying rows. */
+    withNoData?: boolean;
+}
+/**
+ * Trino / PrestoSQL federated query engine dialect. Extends {@link PostgresDialect}
+ * (ANSI SQL, double-quoted identifiers) and overrides Trino-specific behavior.
+ */
+export declare class TrinoDialect extends PostgresDialect {
+    readonly name = "trino";
+    /** Configured connector catalog (undefined => fall back to PG-style naming). */
+    protected readonly trinoCatalog?: string;
+    /** Configured default schema for three-part naming. */
+    protected readonly trinoSchema?: string;
+    constructor(config: TrinoDialectOptions);
+    /**
+     * Quote a table name. When a connector catalog is configured, emit the Trino
+     * three-part `"catalog"."schema"."table"` form; otherwise defer to the
+     * PostgreSQL `schema.table` behavior.
+     */
+    quoteTable(tableName: string, schema?: string): string;
+    /**
+     * Map a data type to Trino SQL. Trino uses unbounded `VARCHAR`, `DOUBLE`,
+     * `BOOLEAN`, and `TIMESTAMP`, and has no SERIAL/identity types.
+     */
+    getDataTypeSql(dataType: DataType): string;
+    /**
+     * Build a column definition fragment for Trino DDL. PRIMARY KEY, UNIQUE,
+     * FOREIGN KEY (references) and auto-increment are intentionally NOT emitted —
+     * Trino neither supports nor enforces them.
+     */
+    protected getTrinoColumnDefinitionSql(columnName: string, definition: ColumnDefinition): string;
+    /**
+     * Build the `WITH (...)` connector-properties clause (or '' when there are
+     * no properties). Handles `format`, `partitioning`, and `tableProperties`.
+     */
+    protected buildTablePropertiesClause(options?: TrinoTableOptions): string;
+    /**
+     * Build (synchronously) a Trino `CREATE TABLE` statement. Omits all key
+     * constraints (PK/FK/UNIQUE) and appends connector `WITH (...)` properties.
+     */
+    buildCreateTableSQL(tableName: string, columns: Record<string, ColumnDefinition>, options?: TrinoTableOptions): string;
+    /**
+     * Build (synchronously) a Trino `CREATE TABLE ... AS SELECT` (CTAS) statement.
+     *
+     * @param tableName - Name of the table to create.
+     * @param selectQuery - The `SELECT ...` query (raw SQL) to populate it from.
+     * @param options - Connector properties and CTAS options.
+     */
+    buildCreateTableAsSelectSQL(tableName: string, selectQuery: string, options?: TrinoCTASOptions): string;
+    /**
+     * Create a table in Trino. Overrides the PostgreSQL implementation to omit
+     * key constraints and support connector `WITH (...)` properties.
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TrinoTableOptions): Promise<void>;
+    /**
+     * Execute a `CREATE TABLE AS SELECT` (CTAS) statement.
+     */
+    createTableAsSelect(tableName: string, selectQuery: string, options?: TrinoCTASOptions): Promise<void>;
+    /**
+     * Drop a table. Trino's `DROP TABLE` supports `IF EXISTS` but has no
+     * `CASCADE` (there are no dependent constraints to cascade).
+     */
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    /**
+     * Add a column. Uses the Trino column-definition builder (no constraints /
+     * default / SERIAL) and the catalog-qualified table name.
+     */
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * Remove a column. `ALTER TABLE ... DROP COLUMN` with catalog-qualified name.
+     */
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    /**
+     * Build an INSERT query. Trino form: `INSERT INTO t (cols) VALUES (...)`.
+     * No `RETURNING`. Trino has no `ON CONFLICT`, but it DOES support the ANSI
+     * `MERGE INTO` statement (on connectors that implement row-level writes, e.g.
+     * Iceberg/Delta/Hive-ACID), so an `upsert` request is routed to
+     * {@link TrinoDialect.buildUpsertMergeQuery} rather than forcing the caller to hand-
+     * write raw SQL. `conflictFields` is required to build the MERGE `ON` clause.
+     */
+    buildInsertQuery(tableName: string, values: Record<string, unknown>, options?: InsertOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an upsert. Trino has no PostgreSQL-style `INSERT ... ON CONFLICT`, but
+     * it does implement the ANSI SQL `MERGE INTO` statement, which is the correct,
+     * connector-native way to express an upsert on connectors that support
+     * row-level writes (Iceberg, Delta, Hive ACID, and the JDBC connectors).
+     * Delegates to {@link TrinoDialect.buildUpsertMergeQuery} so no raw SQL is required.
+     */
+    buildUpsertQuery(tableName: string, values: Record<string, unknown>, options?: UpsertQueryOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a Trino `MERGE INTO` statement implementing a single-row upsert.
+     *
+     *   MERGE INTO "cat"."sch"."t" AS t
+     *   USING (VALUES (?, ?)) AS s ("id", "name")
+     *   ON t."id" = s."id"
+     *   WHEN MATCHED THEN UPDATE SET "name" = s."name"
+     *   WHEN NOT MATCHED THEN INSERT ("id", "name") VALUES (s."id", s."name")
+     *
+     * The source row is presented as an inline `(VALUES (...)) AS s (cols)`
+     * relation. Rows are matched on `conflictFields` (required — Trino has no
+     * primary/unique key metadata to infer them from); matched rows update every
+     * non-key column (or the explicit `updateOnDuplicate` list) and unmatched
+     * rows are inserted. Actual execution requires a connector that supports
+     * `MERGE`/row-level writes.
+     *
+     * @param tableName - Target table (catalog-qualified via {@link quoteTable}).
+     * @param values - Column/value pairs for the row to upsert.
+     * @param options - `conflictFields` (required) picks the `ON` key columns;
+     *   `updateOnDuplicate` restricts the WHEN MATCHED update set; `schema`
+     *   overrides the default schema for the target table.
+     */
+    buildUpsertMergeQuery(tableName: string, values: Record<string, unknown>, options?: {
+        conflictFields?: string[];
+        updateOnDuplicate?: string[];
+        schema?: string;
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an UPDATE query. No `RETURNING`, no `LIMIT` (Trino supports neither
+     * on UPDATE). Actual UPDATE support is connector-dependent at run time.
+     */
+    buildUpdateQuery(tableName: string, values: Record<string, unknown>, where: WhereOptions, _options?: UpdateOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a DELETE query. No `RETURNING`, no `LIMIT`. Trino has no `TRUNCATE`,
+     * so a `truncate` request degrades to an unqualified `DELETE FROM t`. Actual
+     * DELETE support is connector-dependent at run time.
+     */
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    private noIndexes;
+    addIndex(_tableName: string, _indexName: string, _fields?: string[], _options?: IndexOptions): Promise<void>;
+    createIndex(_tableName: string, _indexDef: IndexDefinition): Promise<void>;
+    removeIndex(_tableName: string, _indexName: string): Promise<void>;
+    dropIndex(_tableName: string, _indexName: string, _options?: DropIndexOptions): Promise<void>;
+    createPartialIndex(_tableName: string, _indexName: string, _fields: string[], _where: string, _options?: IndexOptions): Promise<void>;
+    createExpressionIndex(_tableName: string, _indexName: string, _expression: string, _options?: IndexOptions): Promise<void>;
+}
+/**
+ * Create a new Trino dialect instance.
+ */
+export declare function createTrinoDialect(options?: TrinoDialectOptions): TrinoDialect;
+export default TrinoDialect;

package/dist/dialects/trino/index.js

@@ -301,13 +301,19 @@ class TrinoDialect extends index_1.PostgresDialect {
     // ==========================================================================
     /**
      * Build an INSERT query. Trino form: `INSERT INTO t (cols) VALUES (...)`.
-     * No `RETURNING` and no `ON CONFLICT`/upsert — requesting an upsert throws.
+     * No `RETURNING`. Trino has no `ON CONFLICT`, but it DOES support the ANSI
+     * `MERGE INTO` statement (on connectors that implement row-level writes, e.g.
+     * Iceberg/Delta/Hive-ACID), so an `upsert` request is routed to
+     * {@link TrinoDialect.buildUpsertMergeQuery} rather than forcing the caller to hand-
+     * write raw SQL. `conflictFields` is required to build the MERGE `ON` clause.
      */
     buildInsertQuery(tableName, values, options) {
         if (options?.upsert) {
-            throw new Error('Trino does not support upsert / ON CONFLICT. Trino has no primary-key or ' +
-                'unique constraints to conflict on. Use INSERT, or MERGE (on connectors ' +
-                'that support it) issued as raw SQL.');
+            return this.buildUpsertMergeQuery(tableName, values, {
+                conflictFields: options.conflictFields,
+                updateOnDuplicate: options.updateOnDuplicate,
+                schema: options.schema,
+            });
         }
         const columns = Object.keys(values);
         const processedValues = [];
@@ -330,13 +336,82 @@ class TrinoDialect extends index_1.PostgresDialect {
         return { sql, values: processedValues };
     }
     /**
-     * Trino has no upsert. Kept explicit so callers get a clear error instead of
-     * inheriting PostgreSQL's `INSERT ... ON CONFLICT` (invalid in Trino).
+     * Build an upsert. Trino has no PostgreSQL-style `INSERT ... ON CONFLICT`, but
+     * it does implement the ANSI SQL `MERGE INTO` statement, which is the correct,
+     * connector-native way to express an upsert on connectors that support
+     * row-level writes (Iceberg, Delta, Hive ACID, and the JDBC connectors).
+     * Delegates to {@link TrinoDialect.buildUpsertMergeQuery} so no raw SQL is required.
      */
-    buildUpsertQuery(_tableName, _values, _options) {
-        throw new Error('Trino does not support upsert / ON CONFLICT. Trino has no primary-key or ' +
-            'unique constraints to conflict on. Use INSERT, or MERGE (on connectors ' +
-            'that support it) issued as raw SQL.');
+    buildUpsertQuery(tableName, values, options) {
+        return this.buildUpsertMergeQuery(tableName, values, {
+            conflictFields: options?.conflictFields,
+            updateOnDuplicate: options?.updateOnDuplicate,
+            schema: options?.schema,
+        });
+    }
+    /**
+     * Build a Trino `MERGE INTO` statement implementing a single-row upsert.
+     *
+     *   MERGE INTO "cat"."sch"."t" AS t
+     *   USING (VALUES (?, ?)) AS s ("id", "name")
+     *   ON t."id" = s."id"
+     *   WHEN MATCHED THEN UPDATE SET "name" = s."name"
+     *   WHEN NOT MATCHED THEN INSERT ("id", "name") VALUES (s."id", s."name")
+     *
+     * The source row is presented as an inline `(VALUES (...)) AS s (cols)`
+     * relation. Rows are matched on `conflictFields` (required — Trino has no
+     * primary/unique key metadata to infer them from); matched rows update every
+     * non-key column (or the explicit `updateOnDuplicate` list) and unmatched
+     * rows are inserted. Actual execution requires a connector that supports
+     * `MERGE`/row-level writes.
+     *
+     * @param tableName - Target table (catalog-qualified via {@link quoteTable}).
+     * @param values - Column/value pairs for the row to upsert.
+     * @param options - `conflictFields` (required) picks the `ON` key columns;
+     *   `updateOnDuplicate` restricts the WHEN MATCHED update set; `schema`
+     *   overrides the default schema for the target table.
+     */
+    buildUpsertMergeQuery(tableName, values, options) {
+        const conflictFields = options?.conflictFields;
+        if (!conflictFields || conflictFields.length === 0) {
+            throw new Error('Trino MERGE (upsert) requires explicit `conflictFields` to build the ON clause. ' +
+                'Trino has no primary-key/unique metadata to infer the match key from.');
+        }
+        const columns = Object.keys(values);
+        if (columns.length === 0) {
+            throw new Error('buildUpsertMergeQuery requires at least one column to upsert.');
+        }
+        const processedValues = [];
+        let paramIndex = 1;
+        const sourceExprs = columns.map((col) => {
+            const value = values[col];
+            if (value instanceof prorm_1.Literal) {
+                return value.val;
+            }
+            processedValues.push(value);
+            return `$${paramIndex++}`;
+        });
+        const sourceCols = columns.map((c) => this.escapeId(c)).join(', ');
+        const onClause = conflictFields
+            .map((c) => `t.${this.escapeId(c)} = s.${this.escapeId(c)}`)
+            .join(' AND ');
+        const conflictSet = new Set(conflictFields);
+        const updateFields = (options?.updateOnDuplicate && options.updateOnDuplicate.length > 0
+            ? options.updateOnDuplicate
+            : columns).filter((c) => !conflictSet.has(c));
+        let sql = `MERGE INTO ${this.quoteTable(tableName, options?.schema)} AS t` +
+            ` USING (VALUES (${sourceExprs.join(', ')})) AS s (${sourceCols})` +
+            ` ON ${onClause}`;
+        if (updateFields.length > 0) {
+            const setClause = updateFields
+                .map((c) => `${this.escapeId(c)} = s.${this.escapeId(c)}`)
+                .join(', ');
+            sql += ` WHEN MATCHED THEN UPDATE SET ${setClause}`;
+        }
+        const insertCols = columns.map((c) => this.escapeId(c)).join(', ');
+        const insertVals = columns.map((c) => `s.${this.escapeId(c)}`).join(', ');
+        sql += ` WHEN NOT MATCHED THEN INSERT (${insertCols}) VALUES (${insertVals})`;
+        return { sql, values: processedValues };
     }
     /**
      * Build an UPDATE query. No `RETURNING`, no `LIMIT` (Trino supports neither

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

@@ -0,0 +1,98 @@
+/**
+ * Turso / libSQL dialect implementation.
+ *
+ * Turso is a hosted libSQL service; libSQL itself is a SQLite-compatible
+ * fork, so the SQL this dialect generates (DDL, JSON helpers, upsert
+ * syntax, LIMIT/OFFSET pagination, etc.) is identical to `SQLiteDialect`'s.
+ * Rather than duplicate ~90 pure SQL-generation methods, this class
+ * extends `SQLiteDialect` and overrides only the pieces that depend on the
+ * driver: connection lifecycle, query execution, streaming, and
+ * transactions. `SQLiteDialect` reaches those through its own `private`
+ * fields, which subclasses can't touch, so this class keeps entirely
+ * separate connection/transaction state and never touches the parent's.
+ *
+ * The `@libsql/client` driver works identically for a local embedded
+ * replica (`file:` / `:memory:` URLs) and a remote Turso database
+ * (`libsql:`/`https:` URLs with an `authToken`), unlike `better-sqlite3`
+ * which is local-only — that's the whole point of this dialect existing
+ * separately from `SQLiteDialect`.
+ */
+import { type Client } from '@libsql/client';
+import { SQLiteDialect } from '../sqlite/index';
+import { DialectOptions } from '../dialect';
+import { Transaction, TransactionOptions, QueryResult, QueryOptions, StreamOptions } from '../../types';
+import { Readable } from 'stream';
+import { StreamableDialect } from '../query-stream-helper';
+export interface TursoDialectOptions extends DialectOptions {
+    /**
+     * Database URL. Use `libsql://<db>.turso.io` (or `https://...`) for a
+     * hosted Turso database, `file:./local.db` for a local libSQL file, or
+     * `:memory:` for an in-memory database.
+     */
+    url?: string;
+    /** Auth token for a hosted Turso database. Not needed for `file:`/`:memory:`. */
+    authToken?: string;
+    /** Encryption key for an encrypted local database file. */
+    encryptionKey?: string;
+    /** URL of a remote database to sync an embedded replica against. */
+    syncUrl?: string;
+    /** Sync interval in seconds when `syncUrl` is set. */
+    syncInterval?: number;
+}
+/**
+ * Turso / libSQL dialect. See the module-level doc comment for why this
+ * extends `SQLiteDialect` instead of implementing `Dialect` from scratch.
+ */
+export declare class TursoDialect extends SQLiteDialect implements StreamableDialect {
+    readonly name = "turso";
+    readonly library = "@libsql/client";
+    private client;
+    private _tursoConnected;
+    private tursoConfig;
+    private tursoTransactionDepth;
+    constructor(config: TursoDialectOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnection(): Client | null;
+    isConnected(): boolean;
+    /**
+     * `SQLiteAdvanced` (the parent class's `.advanced` getter) drives
+     * better-sqlite3's synchronous `Database` API directly, which the
+     * `@libsql/client` connection this dialect wraps doesn't expose.
+     */
+    get advanced(): never;
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * `@libsql/client` has no native server-side cursor — `execute()` always
+     * returns the full result set — so this uses the same generic
+     * LIMIT/OFFSET-paginated fallback the other non-cursor dialects use
+     * (`buildLimitOffset()` is inherited unchanged from `SQLiteDialect`,
+     * since libSQL's pagination syntax is identical to SQLite's).
+     */
+    queryStream(sql: string, options?: StreamOptions): Readable;
+    private toLibsqlArgs;
+    private rowToObject;
+    getDatabaseVersion(): Promise<string>;
+    /**
+     * The parent runs setter PRAGMAs through better-sqlite3's synchronous
+     * `exec()` (which TursoDialect has no handle for — `this.connection` is
+     * always null here). Route them through the async libSQL driver instead so
+     * table-rebuild paths (e.g. addForeignKey's `PRAGMA foreign_keys=OFF/ON`)
+     * actually take effect over the wire.
+     */
+    protected setPragma(pragma: string): Promise<void>;
+    attachDatabase(path: string, alias: string): Promise<void>;
+    detachDatabase(alias: string): Promise<void>;
+    startTransaction(options?: TransactionOptions): Promise<Transaction>;
+    commitTransaction(transaction: Transaction): Promise<void>;
+    rollbackTransaction(transaction: Transaction): Promise<void>;
+    /**
+     * Pull the local embedded replica up to date with its `syncUrl` remote.
+     * No-op (well, throws) if this client wasn't configured with a `syncUrl`.
+     */
+    sync(): Promise<void>;
+}
+/**
+ * Create a new Turso/libSQL dialect instance.
+ */
+export declare function createTursoDialect(options?: TursoDialectOptions): TursoDialect;

package/dist/dialects/turso/index.js

@@ -157,6 +157,16 @@ class TursoDialect extends index_1.SQLiteDialect {
         const result = await this.query('SELECT sqlite_version() AS version');
         return String(result.rows[0]?.version ?? 'unknown');
     }
+    /**
+     * The parent runs setter PRAGMAs through better-sqlite3's synchronous
+     * `exec()` (which TursoDialect has no handle for — `this.connection` is
+     * always null here). Route them through the async libSQL driver instead so
+     * table-rebuild paths (e.g. addForeignKey's `PRAGMA foreign_keys=OFF/ON`)
+     * actually take effect over the wire.
+     */
+    async setPragma(pragma) {
+        await this.query(`PRAGMA ${pragma}`);
+    }
     async attachDatabase(path, alias) {
         const aliasId = this.quoteIdentifier(alias);
         await this.client.execute({ sql: `ATTACH DATABASE ? AS ${aliasId}`, args: [path] });