ts-prorm-orm 1.1.0

package/dist/dialects/firebird/index.js

@@ -0,0 +1,495 @@
+"use strict";
+/**
+ * Firebird dialect implementation for the TypeScript ORM
+ *
+ * This dialect provides Firebird SQL generation. A real deployment would use a
+ * dedicated Firebird driver (e.g. `node-firebird`); here it extends the
+ * PostgreSQL dialect and overrides only the SQL grammar that differs, reusing
+ * PostgresDialect's query-builder scaffolding for everything Firebird shares
+ * with standard SQL.
+ *
+ * Notable Firebird SQL differences overridden below:
+ *
+ * - Row limiting: Firebird has no `LIMIT ... OFFSET ...` clause. It uses
+ *   `SELECT FIRST n SKIP m ...` placed right after the `SELECT` keyword (e.g.
+ *   `SELECT FIRST 10 SKIP 20 * FROM ...`). We override `buildLimitOffset` to
+ *   emit nothing (so the base's trailing LIMIT/OFFSET disappears) and
+ *   `buildSelectQuery` to inject the `FIRST/SKIP` fragment after the top-level
+ *   `SELECT`. `UPDATE`/`DELETE` row limiting uses `ROWS n` (not `LIMIT n`),
+ *   handled in `buildUpdateQuery`/`buildDeleteQuery`.
+ * - Upsert: Firebird has no PostgreSQL `INSERT ... ON CONFLICT`. It uses
+ *   `UPDATE OR INSERT INTO t (...) VALUES (...) MATCHING (...)` instead, where
+ *   `MATCHING` names the key columns (defaulting to the primary key when
+ *   omitted). `buildUpsertQuery` and the upsert branch of `buildInsertQuery`
+ *   emit this form. Because `UPDATE OR INSERT` always overwrites every listed
+ *   column, `updateOnDuplicate` (a subset of columns to update) has no Firebird
+ *   equivalent and is ignored.
+ * - Auto-increment: Firebird 3+ uses `GENERATED BY DEFAULT AS IDENTITY` rather
+ *   than PostgreSQL's `SERIAL`. `getDataTypeSql` maps auto-increment
+ *   INTEGER/BIGINT accordingly, `getIdentityColumnSql` builds a full identity
+ *   column definition, and `createTable`/`addColumn` emit IDENTITY (not SERIAL)
+ *   for auto-increment columns.
+ * - Column DDL: Firebird omits the `COLUMN` keyword in `ALTER TABLE`. Adding a
+ *   column is `ALTER TABLE t ADD col type` and dropping is `ALTER TABLE t DROP
+ *   col` (PostgreSQL spells these `ADD COLUMN` / `DROP COLUMN`).
+ * - Generators/sequences: Firebird's sequence objects are historically called
+ *   "generators". `createGenerator(name)` emits `CREATE SEQUENCE name` (the
+ *   modern, SQL-standard spelling Firebird accepts).
+ * - Type mapping: Firebird uses `BLOB SUB_TYPE TEXT` for long text (no `TEXT`
+ *   type), `DOUBLE PRECISION`, `TIMESTAMP`, `BOOLEAN`, and `INTEGER`/`BIGINT`.
+ *   `getDataTypeSql` overrides the relevant mappings.
+ * - Identifiers: Firebird upper-cases unquoted identifiers; quoting an
+ *   identifier with double quotes makes it case-sensitive. We keep the base's
+ *   double-quote quoting (`"identifier"`), which preserves case as written.
+ * - RETURNING: Firebird DOES support `RETURNING` on INSERT/UPDATE/DELETE (for
+ *   singleton statements), so the inherited RETURNING handling is kept.
+ *
+ * The default SQL port is 3050 (Firebird's default), not PostgreSQL's 5432.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirebirdDialect = void 0;
+exports.createFirebirdDialect = createFirebirdDialect;
+const postgres_1 = require("../postgres");
+const prorm_1 = require("../../prorm");
+/**
+ * Firebird dialect class. Extends the PostgreSQL dialect and overrides the SQL
+ * grammar that Firebird spells differently.
+ */
+class FirebirdDialect extends postgres_1.PostgresDialect {
+    constructor(config = {}) {
+        // Firebird's default SQL service port is 3050 (not PostgreSQL's 5432).
+        super({ port: 3050, ...config });
+        this.name = 'firebird';
+    }
+    // ==========================================================================
+    // Row limiting (FIRST / SKIP)
+    // ==========================================================================
+    /**
+     * Firebird does not support a trailing `LIMIT ... OFFSET ...` clause, so we
+     * emit nothing here. The actual row-limiting keywords (`FIRST`/`SKIP`) are
+     * injected right after the `SELECT` keyword by `buildSelectQuery` below.
+     */
+    buildLimitOffset(_limit, _offset) {
+        return '';
+    }
+    /**
+     * Build the Firebird `FIRST n SKIP m` fragment (without surrounding spaces).
+     * Returns an empty string when neither limit nor offset is provided.
+     *
+     * Firebird allows `SKIP` on its own (`SELECT SKIP 20 ...`), so an offset with
+     * no limit is emitted as just `SKIP m`. `FIRST` always precedes `SKIP`.
+     */
+    buildFirstSkip(limit, offset) {
+        const parts = [];
+        if (limit !== undefined) {
+            parts.push(`FIRST ${Number(limit)}`);
+        }
+        if (offset !== undefined) {
+            parts.push(`SKIP ${Number(offset)}`);
+        }
+        return parts.join(' ');
+    }
+    /**
+     * Find the index just past the top-level `SELECT ` keyword in a compiled
+     * query so the `FIRST/SKIP` fragment can be inserted there. Scans at
+     * parenthesis depth 0 so that `SELECT`s inside CTEs/sub-selects (which live
+     * inside parentheses) are skipped and the main query's `SELECT` is targeted.
+     * Returns -1 if no top-level `SELECT ` is found.
+     */
+    mainSelectInsertIndex(sql) {
+        let depth = 0;
+        for (let i = 0; i < sql.length; i++) {
+            const ch = sql[i];
+            if (ch === '(') {
+                depth++;
+            }
+            else if (ch === ')') {
+                depth--;
+            }
+            else if (depth === 0 &&
+                (ch === 'S' || ch === 's') &&
+                /^select\s/i.test(sql.slice(i, i + 7)) &&
+                (i === 0 || !/[A-Za-z0-9_]/.test(sql[i - 1]))) {
+                // Skip past `SELECT` plus the single following whitespace char.
+                return i + 'SELECT '.length;
+            }
+        }
+        return -1;
+    }
+    /**
+     * Build a SELECT query using Firebird's `FIRST n SKIP m` row limiting instead
+     * of a trailing `LIMIT/OFFSET`. Delegates the heavy lifting to the base
+     * PostgreSQL builder (whose `buildLimitOffset` we've neutralized above), then
+     * injects the `FIRST/SKIP` fragment right after the top-level `SELECT` — so
+     * it works uniformly for plain SELECTs, JOINs, GROUP BY/HAVING, DISTINCT, and
+     * queries fronted by a `WITH` CTE (whose inner SELECTs are parenthesized and
+     * therefore skipped by `mainSelectInsertIndex`).
+     */
+    buildSelectQuery(options) {
+        const built = super.buildSelectQuery(options);
+        const firstSkip = this.buildFirstSkip(options.limit, options.offset);
+        if (!firstSkip) {
+            return built;
+        }
+        const insertAt = this.mainSelectInsertIndex(built.sql);
+        if (insertAt < 0) {
+            // Defensive: no top-level SELECT found (shouldn't happen for a SELECT).
+            return built;
+        }
+        const sql = `${built.sql.slice(0, insertAt)}${firstSkip} ${built.sql.slice(insertAt)}`;
+        return { sql, values: built.values };
+    }
+    // ==========================================================================
+    // INSERT / UPSERT
+    // ==========================================================================
+    /**
+     * Build an INSERT query. When `options.upsert` is set, Firebird uses
+     * `UPDATE OR INSERT INTO ... MATCHING (...)` instead of PostgreSQL's
+     * `INSERT ... ON CONFLICT`. `MATCHING` names the key columns; when
+     * `conflictFields` is omitted Firebird matches on the primary key.
+     */
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        let paramIndex = 1;
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push(`$${paramIndex}`);
+                processedValues.push(value);
+                paramIndex++;
+            }
+        }
+        const cols = columns.map((c) => this.escapeId(c)).join(', ');
+        const vals = placeholders.join(', ');
+        let sql;
+        if (options?.upsert) {
+            sql = `UPDATE OR INSERT INTO ${this.escapeId(tableName)} (${cols}) VALUES (${vals})`;
+            if (options.conflictFields && options.conflictFields.length > 0) {
+                sql += ` MATCHING (${options.conflictFields.map((c) => this.escapeId(c)).join(', ')})`;
+            }
+        }
+        else {
+            sql = `INSERT INTO ${this.escapeId(tableName)} (${cols}) VALUES (${vals})`;
+        }
+        sql += this.buildReturningClause(options?.returning);
+        return { sql, values: processedValues };
+    }
+    /**
+     * Build an UPSERT query for Firebird using
+     * `UPDATE OR INSERT INTO t (...) VALUES (...) MATCHING (...)`.
+     *
+     * Unlike PostgreSQL's `ON CONFLICT ... DO UPDATE SET <subset>`, Firebird's
+     * `UPDATE OR INSERT` always overwrites every listed column on a match, so a
+     * `updateOnDuplicate` subset has no Firebird equivalent and is ignored.
+     * `conflictFields`, when given, becomes the `MATCHING` key column list;
+     * otherwise Firebird matches on the table's primary key.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        let paramIndex = 1;
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push(`$${paramIndex}`);
+                processedValues.push(value);
+                paramIndex++;
+            }
+        }
+        const cols = columns.map((c) => this.escapeId(c)).join(', ');
+        let sql = `UPDATE OR INSERT INTO ${this.escapeId(tableName)} (${cols}) VALUES (${placeholders.join(', ')})`;
+        if (options?.conflictFields && options.conflictFields.length > 0) {
+            sql += ` MATCHING (${options.conflictFields.map((c) => this.escapeId(c)).join(', ')})`;
+        }
+        sql += this.buildReturningClause(options?.returning);
+        return { sql, values: processedValues };
+    }
+    /**
+     * Build a ` RETURNING ...` suffix (or empty string). Firebird supports
+     * RETURNING on singleton INSERT/UPDATE/DELETE/UPDATE-OR-INSERT statements.
+     */
+    buildReturningClause(returning) {
+        if (!returning) {
+            return '';
+        }
+        if (returning === true) {
+            return ' RETURNING *';
+        }
+        if (Array.isArray(returning)) {
+            return ` RETURNING ${returning.map((c) => this.escapeId(c)).join(', ')}`;
+        }
+        return '';
+    }
+    // ==========================================================================
+    // UPDATE / DELETE (ROWS instead of LIMIT)
+    // ==========================================================================
+    /**
+     * Build an UPDATE query. Firebird limits affected rows with `ROWS n`, not
+     * PostgreSQL's `LIMIT n`; we delegate to the base builder and rewrite the
+     * emitted `LIMIT n` fragment to `ROWS n` (positioned identically, before any
+     * RETURNING clause).
+     */
+    buildUpdateQuery(tableName, values, where, options) {
+        const built = super.buildUpdateQuery(tableName, values, where, options);
+        if (options?.limit) {
+            built.sql = built.sql.replace(` LIMIT ${options.limit}`, ` ROWS ${options.limit}`);
+        }
+        return built;
+    }
+    /**
+     * Build a DELETE query. Firebird limits affected rows with `ROWS n`, not
+     * PostgreSQL's `LIMIT n`; rewrite the base builder's `LIMIT n` accordingly.
+     */
+    buildDeleteQuery(tableName, where, options) {
+        const built = super.buildDeleteQuery(tableName, where, options);
+        if (options?.limit && !options.truncate) {
+            built.sql = built.sql.replace(` LIMIT ${options.limit}`, ` ROWS ${options.limit}`);
+        }
+        return built;
+    }
+    // ==========================================================================
+    // Type mapping
+    // ==========================================================================
+    /**
+     * Map an ORM data type to its Firebird SQL spelling. Overrides the mappings
+     * that differ from PostgreSQL and delegates everything else to the base.
+     */
+    getDataTypeSql(dataType) {
+        if (!dataType || typeof dataType !== 'object') {
+            return super.getDataTypeSql(dataType);
+        }
+        const dt = dataType;
+        switch (dt.key) {
+            case 'STRING':
+                return `VARCHAR(${dt.length || 255})`;
+            case 'CHAR':
+                return `CHAR(${dt.length || 1})`;
+            case 'TEXT':
+                // Firebird has no `TEXT` type; long text is stored as a text BLOB.
+                return 'BLOB SUB_TYPE TEXT';
+            case 'INTEGER':
+                return dt.autoIncrement
+                    ? 'INTEGER GENERATED BY DEFAULT AS IDENTITY'
+                    : 'INTEGER';
+            case 'BIGINT':
+                return dt.autoIncrement
+                    ? 'BIGINT GENERATED BY DEFAULT AS IDENTITY'
+                    : 'BIGINT';
+            case 'FLOAT':
+                return 'FLOAT';
+            case 'DOUBLE':
+                return 'DOUBLE PRECISION';
+            case 'DECIMAL':
+                return `DECIMAL(${dt.precision || 10},${dt.scale || 0})`;
+            case 'BOOLEAN':
+                return 'BOOLEAN';
+            case 'DATE':
+                // ORM DATE == timestamp; Firebird spells it TIMESTAMP.
+                return dt.precision ? `TIMESTAMP(${dt.precision})` : 'TIMESTAMP';
+            case 'DATEONLY':
+                return 'DATE';
+            case 'TIME':
+                return dt.precision ? `TIME(${dt.precision})` : 'TIME';
+            case 'BLOB':
+                return 'BLOB';
+            case 'JSON':
+            case 'JSONB':
+                // Firebird has no native JSON type; store as a text BLOB.
+                return 'BLOB SUB_TYPE TEXT';
+            default:
+                return super.getDataTypeSql(dataType);
+        }
+    }
+    // ==========================================================================
+    // DDL: CREATE TABLE / ALTER TABLE columns
+    // ==========================================================================
+    /**
+     * Build a Firebird `CREATE TABLE` statement. Unlike the PostgreSQL base,
+     * auto-increment columns use `GENERATED BY DEFAULT AS IDENTITY` (not
+     * `SERIAL`). Firebird does not support `CREATE TABLE IF NOT EXISTS`, so that
+     * option is ignored. Exposed separately from `createTable` so the generated
+     * SQL can be asserted without a live connection.
+     */
+    buildCreateTableSQL(tableName, columns, options) {
+        const defs = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            defs.push(this.getFirebirdColumnSql(columnName, definition));
+        }
+        if (options?.constraints) {
+            for (const constraint of options.constraints) {
+                const sql = this.buildFirebirdConstraintSql(constraint);
+                if (sql) {
+                    defs.push(sql);
+                }
+            }
+        }
+        return `CREATE TABLE ${this.escapeId(tableName)} (${defs.join(', ')})`;
+    }
+    /**
+     * Create a table using Firebird DDL (identity columns, no SERIAL). After the
+     * table is created, unique keys, indexes and a table comment (if requested)
+     * are applied as separate statements, mirroring the base dialect's behaviour.
+     */
+    async createTable(tableName, columns, options) {
+        await this.query(this.buildCreateTableSQL(tableName, columns, options));
+        // Unique keys as separate ALTER TABLE ... ADD CONSTRAINT statements.
+        if (options?.uniqueKeys && !Array.isArray(options.uniqueKeys)) {
+            for (const [keyName, fields] of Object.entries(options.uniqueKeys)) {
+                const constraintName = keyName || `${tableName}_${fields.join('_')}_key`;
+                await this.query(`ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${this.escapeId(constraintName)} UNIQUE (${fields
+                    .map((f) => this.escapeId(f))
+                    .join(', ')})`);
+            }
+        }
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.addIndex(tableName, index.name || `idx_${tableName}_${index.fields.join('_')}`, index.fields, { unique: index.unique, using: index.using, where: index.where });
+            }
+        }
+        if (options?.comment) {
+            await this.query(`COMMENT ON TABLE ${this.escapeId(tableName)} IS ${this.escape(options.comment)}`);
+        }
+    }
+    /**
+     * Build a single Firebird column definition (used by CREATE TABLE and
+     * ADD COLUMN). Auto-increment INTEGER/BIGINT columns become identity columns.
+     */
+    getFirebirdColumnSql(columnName, definition) {
+        const dt = definition.type;
+        const isAutoInt = !!definition.autoIncrement && (!dt?.key || dt.key === 'INTEGER' || dt.key === 'BIGINT');
+        let typeSql;
+        if (isAutoInt) {
+            const baseType = dt?.key === 'BIGINT' ? 'BIGINT' : 'INTEGER';
+            typeSql = `${baseType} GENERATED BY DEFAULT AS IDENTITY`;
+        }
+        else {
+            typeSql = this.getDataTypeSql(definition.type);
+        }
+        let sql = `${this.escapeId(columnName)} ${typeSql}`;
+        // Firebird requires DEFAULT before NOT NULL. Identity columns take no default.
+        if (!isAutoInt && definition.defaultValue !== undefined) {
+            sql += ` DEFAULT ${this.escape(definition.defaultValue)}`;
+        }
+        if (definition.allowNull === false) {
+            sql += ' NOT NULL';
+        }
+        if (definition.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        if (definition.unique) {
+            sql += ' UNIQUE';
+        }
+        if (definition.references) {
+            const refField = definition.references.field;
+            const refFieldSql = Array.isArray(refField)
+                ? `(${refField.map((f) => this.escapeId(f)).join(', ')})`
+                : `(${this.escapeId(refField)})`;
+            sql += ` REFERENCES ${this.escapeId(definition.references.table)} ${refFieldSql}`;
+            if (definition.references.onDelete) {
+                sql += ` ON DELETE ${definition.references.onDelete}`;
+            }
+            if (definition.references.onUpdate) {
+                sql += ` ON UPDATE ${definition.references.onUpdate}`;
+            }
+        }
+        return sql;
+    }
+    /**
+     * Build an inline table constraint for Firebird CREATE TABLE.
+     */
+    buildFirebirdConstraintSql(constraint) {
+        const name = constraint.name ? `CONSTRAINT ${this.escapeId(constraint.name)} ` : '';
+        const fields = (constraint.fields || []).map((f) => this.escapeId(f)).join(', ');
+        switch (constraint.type) {
+            case 'PRIMARY KEY':
+                return `${name}PRIMARY KEY (${fields})`;
+            case 'UNIQUE':
+                return `${name}UNIQUE (${fields})`;
+            case 'CHECK':
+                return constraint.check ? `${name}CHECK (${constraint.check})` : null;
+            case 'FOREIGN KEY': {
+                if (!constraint.references) {
+                    return null;
+                }
+                const refField = constraint.references.field;
+                const refFieldSql = Array.isArray(refField)
+                    ? refField.map((f) => this.escapeId(f)).join(', ')
+                    : this.escapeId(refField);
+                let sql = `${name}FOREIGN KEY (${fields}) REFERENCES ${this.escapeId(constraint.references.table)} (${refFieldSql})`;
+                if (constraint.references.onDelete) {
+                    sql += ` ON DELETE ${constraint.references.onDelete}`;
+                }
+                if (constraint.references.onUpdate) {
+                    sql += ` ON UPDATE ${constraint.references.onUpdate}`;
+                }
+                return sql;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Add a column to a table. Firebird's `ALTER TABLE ... ADD` omits the
+     * `COLUMN` keyword that PostgreSQL uses.
+     */
+    async addColumn(tableName, columnName, definition) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} ADD ${this.getFirebirdColumnSql(columnName, definition)}`;
+        await this.query(sql);
+    }
+    /**
+     * Remove a column from a table. Firebird's `ALTER TABLE ... DROP` omits the
+     * `COLUMN` keyword that PostgreSQL uses.
+     */
+    async removeColumn(tableName, columnName) {
+        const sql = `ALTER TABLE ${this.escapeId(tableName)} DROP ${this.escapeId(columnName)}`;
+        await this.query(sql);
+    }
+    // ==========================================================================
+    // Identity columns & generators
+    // ==========================================================================
+    /**
+     * Build a Firebird identity-column definition, e.g.
+     * `"id" INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`.
+     *
+     * Firebird 3+ replaces PostgreSQL's `SERIAL` shorthand with the SQL-standard
+     * `GENERATED BY DEFAULT AS IDENTITY` clause.
+     *
+     * @param columnName - Name of the identity column
+     * @param options - `type` selects INTEGER (default) or BIGINT; `primaryKey`
+     *   appends `PRIMARY KEY`
+     */
+    getIdentityColumnSql(columnName, options) {
+        const baseType = options?.type === 'BIGINT' ? 'BIGINT' : 'INTEGER';
+        let sql = `${this.escapeId(columnName)} ${baseType} GENERATED BY DEFAULT AS IDENTITY`;
+        if (options?.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        return sql;
+    }
+    /**
+     * Build the SQL to create a Firebird generator (sequence). Firebird's
+     * sequence objects were historically called "generators"; modern Firebird
+     * accepts the SQL-standard `CREATE SEQUENCE` spelling, which is emitted here.
+     *
+     * @param name - Generator/sequence name
+     * @returns `CREATE SEQUENCE "name"`
+     */
+    createGenerator(name) {
+        return `CREATE SEQUENCE ${this.escapeId(name)}`;
+    }
+}
+exports.FirebirdDialect = FirebirdDialect;
+/**
+ * Create a new Firebird dialect instance
+ */
+function createFirebirdDialect(options) {
+    return new FirebirdDialect(options || {});
+}
+exports.default = FirebirdDialect;