ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/oracle/index.js

@@ -3,13 +3,26 @@
  * Oracle dialect implementation for the TypeScript ORM
  * Uses the oracledb driver for database connectivity
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OracleDialect = void 0;
 exports.createOracleDialect = createOracleDialect;
-const oracledb_1 = __importDefault(require("oracledb"));
+// Lazily-loaded `oracledb` driver. The native Oracle client is only loaded the
+// first time a connection is opened, so importing this ORM never dlopens the
+// oracledb native addon.
+let oracledbModule = null;
+function loadOracleDb() {
+    if (!oracledbModule) {
+        try {
+            oracledbModule = require('oracledb');
+        }
+        catch (err) {
+            throw new Error("The 'oracledb' package is required to use the Oracle dialect but could not be loaded. " +
+                'Install it with `npm install oracledb`. Original error: ' +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return oracledbModule;
+}
 const query_stream_helper_1 = require("../query-stream-helper");
 const errors_1 = require("../../errors");
 const crypto_1 = require("crypto");
@@ -120,7 +133,7 @@ class OracleDialect {
             // when the client isn't initialized) instead of unconditionally
             // switching to thick mode.
             if (!this.config.thinMode) {
-                await oracledb_1.default.initOracleClient();
+                await loadOracleDb().initOracleClient();
             }
             const poolOptions = {
                 ...DEFAULT_POOL_OPTIONS,
@@ -129,7 +142,7 @@ class OracleDialect {
                 password: this.config.password,
                 connectString: `${this.config.host}:${this.config.port}/${this.config.database}`,
             };
-            this.pool = await oracledb_1.default.createPool(poolOptions);
+            this.pool = await loadOracleDb().createPool(poolOptions);
             this._isConnected = true;
         }
         catch (error) {
@@ -184,7 +197,7 @@ class OracleDialect {
         try {
             const queryOptions = {
                 autoCommit: true,
-                outFormat: oracledb_1.default.OUT_FORMAT_OBJECT,
+                outFormat: loadOracleDb().OUT_FORMAT_OBJECT,
             };
             // Callers pass bind values under different option keys (`replacements`,
             // `bindings`, or `bind`); oracledb accepts either a positional array
@@ -1742,8 +1755,8 @@ class OracleDialect {
             // recognize a positional bind as an OUT bind rather than an IN value;
             // a bare `null` would be sent as an IN bind of unknown type.
             const outBind = () => ({
-                type: oracledb_1.default.STRING,
-                dir: oracledb_1.default.BIND_OUT,
+                type: loadOracleDb().STRING,
+                dir: loadOracleDb().BIND_OUT,
                 maxSize: 4000,
             });
             if (options.returning === true) {
@@ -2961,6 +2974,194 @@ END;
         const alias = options.alias ? ` ${this.quoteIdentifier(options.alias)}` : '';
         return `${options.sourceQuery} UNPIVOT ${includeNulls}(${this.quoteIdentifier(options.valueColumn)} FOR ${this.quoteIdentifier(options.forColumn)} IN (${inColumns}))${alias}`;
     }
+    // ==================== JSON query surface (Oracle 12c+/21c) ====================
+    /**
+     * Convert a dot/bracket JSON path (e.g. `address.city` or `items[0].sku`) into
+     * an Oracle JSON path expression rooted at `$` (`$.address.city`,
+     * `$.items[0].sku`). A path already starting with `$` is passed through.
+     */
+    toOracleJsonPath(path) {
+        if (path.startsWith('$')) {
+            return path;
+        }
+        // Turn `a.b[0].c` into `$.a.b[0].c`
+        const normalized = path.replace(/^\./, '');
+        return `$.${normalized}`;
+    }
+    /**
+     * Build a scalar `JSON_VALUE(column, '$.path' RETURNING type)` accessor
+     * (Oracle 12c+), the standard way to extract a scalar out of a JSON column.
+     */
+    buildJsonValue(column, path, options) {
+        const ref = this.quoteIdentifier(column);
+        const returning = options?.returning ? ` RETURNING ${options.returning}` : '';
+        const onError = options?.onError ? ` ${options.onError} ON ERROR` : '';
+        return `JSON_VALUE(${ref}, '${this.toOracleJsonPath(path)}'${returning}${onError})`;
+    }
+    /**
+     * Build a `JSON_QUERY(column, '$.path')` accessor (Oracle 12c+) for extracting
+     * a JSON object/array fragment (rather than a scalar) out of a JSON column.
+     */
+    buildJsonQuery(column, path, options) {
+        const ref = this.quoteIdentifier(column);
+        const wrapper = options?.wrapper ? ` ${options.wrapper}` : '';
+        return `JSON_QUERY(${ref}, '${this.toOracleJsonPath(path)}'${wrapper})`;
+    }
+    /**
+     * Build a `JSON_EXISTS(column, '$.path')` predicate (Oracle 12c+) for use in a
+     * WHERE clause to test for the presence of a JSON path.
+     */
+    buildJsonExists(column, path) {
+        return `JSON_EXISTS(${this.quoteIdentifier(column)}, '${this.toOracleJsonPath(path)}')`;
+    }
+    // ==================== PL/SQL packages ====================
+    /**
+     * Create an Oracle PL/SQL package specification and/or body. Emits
+     * `CREATE [OR REPLACE] PACKAGE name AS <spec> END;` and, when `body` is given,
+     * a following `CREATE [OR REPLACE] PACKAGE BODY name AS <body> END;`.
+     * At least one of `spec`/`body` must be provided.
+     */
+    async createPackage(options) {
+        const schema = options.schema || this.config?.schema;
+        const qualified = schema
+            ? `${this.escapeId(schema)}.${this.escapeId(options.name)}`
+            : this.escapeId(options.name);
+        const orReplace = options.replace === false ? '' : 'OR REPLACE ';
+        if (!options.spec && !options.body) {
+            throw new Error('createPackage requires at least one of `spec` or `body`');
+        }
+        if (options.spec) {
+            await this.query(`CREATE ${orReplace}PACKAGE ${qualified} AS\n${options.spec}\nEND ${this.escapeId(options.name)};`);
+        }
+        if (options.body) {
+            await this.query(`CREATE ${orReplace}PACKAGE BODY ${qualified} AS\n${options.body}\nEND ${this.escapeId(options.name)};`);
+        }
+    }
+    /**
+     * Drop an Oracle PL/SQL package. Pass `bodyOnly` to drop just the body and
+     * keep the specification.
+     */
+    async dropPackage(packageName, options) {
+        const schema = options?.schema || this.config?.schema;
+        const qualified = schema
+            ? `${this.escapeId(schema)}.${this.escapeId(packageName)}`
+            : this.escapeId(packageName);
+        const kind = options?.bodyOnly ? 'PACKAGE BODY' : 'PACKAGE';
+        await this.query(`DROP ${kind} ${qualified}`);
+    }
+    // ==================== Flashback query / recovery ====================
+    /**
+     * Build an Oracle flashback `AS OF` clause (`AS OF TIMESTAMP ...` or
+     * `AS OF SCN ...`) to append to a table reference for a point-in-time read.
+     * Returns an empty string when neither timestamp nor SCN is given.
+     */
+    buildFlashbackClause(options) {
+        if (options.scn !== undefined) {
+            return `AS OF SCN ${options.scn}`;
+        }
+        if (options.timestamp !== undefined) {
+            const ts = options.timestamp instanceof Date
+                ? options.timestamp.toISOString().replace('T', ' ').replace('Z', '')
+                : options.timestamp;
+            return `AS OF TIMESTAMP TO_TIMESTAMP('${String(ts).replace(/'/g, "''")}', 'YYYY-MM-DD HH24:MI:SS.FF')`;
+        }
+        return '';
+    }
+    /**
+     * Build a flashback SELECT: `SELECT ... FROM table AS OF ... [WHERE ...]`,
+     * reading the table's rows as they existed at a past timestamp or SCN.
+     */
+    buildFlashbackQuery(tableName, flashback, options) {
+        const cols = options?.attributes && options.attributes.length > 0
+            ? options.attributes.map((c) => this.escapeId(c)).join(', ')
+            : '*';
+        const asOf = this.buildFlashbackClause(flashback);
+        let sql = `SELECT ${cols} FROM ${this.quoteTable(tableName, options?.schema)} ${asOf}`;
+        let values = [];
+        if (options?.where) {
+            const { sql: whereSql, values: whereValues } = this.buildWhereClause(options.where);
+            if (whereSql) {
+                sql += ` WHERE ${whereSql}`;
+                values = whereValues;
+            }
+        }
+        return { sql: sql.trim(), values };
+    }
+    /**
+     * Flashback a table to a past point in time (`FLASHBACK TABLE t TO TIMESTAMP/SCN ...`).
+     * Requires row movement enabled on the table.
+     */
+    async flashbackTable(tableName, flashback) {
+        let target;
+        if (flashback.scn !== undefined) {
+            target = `SCN ${flashback.scn}`;
+        }
+        else if (flashback.timestamp !== undefined) {
+            const ts = flashback.timestamp instanceof Date
+                ? flashback.timestamp.toISOString().replace('T', ' ').replace('Z', '')
+                : flashback.timestamp;
+            target = `TIMESTAMP TO_TIMESTAMP('${String(ts).replace(/'/g, "''")}', 'YYYY-MM-DD HH24:MI:SS.FF')`;
+        }
+        else {
+            throw new Error('flashbackTable requires a `timestamp` or `scn`');
+        }
+        await this.query(`FLASHBACK TABLE ${this.quoteTable(tableName)} TO ${target}`);
+    }
+    /**
+     * Restore a dropped table from the recycle bin
+     * (`FLASHBACK TABLE t TO BEFORE DROP [RENAME TO newName]`).
+     */
+    async flashbackTableBeforeDrop(tableName, renameTo) {
+        let sql = `FLASHBACK TABLE ${this.quoteTable(tableName)} TO BEFORE DROP`;
+        if (renameTo) {
+            sql += ` RENAME TO ${this.escapeId(renameTo)}`;
+        }
+        await this.query(sql);
+    }
+    // ==================== External tables (FDW replacement) ====================
+    /**
+     * Create an Oracle external table (`ORGANIZATION EXTERNAL`) — the native
+     * Oracle mechanism for reading flat files / Data Pump dumps as a table, and
+     * the recommended replacement for the PostgreSQL-only foreign-table API that
+     * this dialect rejects.
+     */
+    async createExternalTable(tableName, options) {
+        const columnDefs = Object.entries(options.columns)
+            .map(([name, type]) => `${this.escapeId(name)} ${type}`)
+            .join(', ');
+        const driver = options.type || 'ORACLE_LOADER';
+        const locations = (Array.isArray(options.location) ? options.location : [options.location])
+            .map((l) => `'${String(l).replace(/'/g, "''")}'`)
+            .join(', ');
+        const accessParams = options.accessParameters
+            ? `\n    ACCESS PARAMETERS (\n${options.accessParameters}\n    )`
+            : '';
+        const rejectLimit = options.rejectLimit ?? 'UNLIMITED';
+        const sql = `CREATE TABLE ${this.quoteTable(tableName)} (${columnDefs})\n` +
+            `ORGANIZATION EXTERNAL (\n` +
+            `  TYPE ${driver}\n` +
+            `  DEFAULT DIRECTORY ${this.escapeId(options.directory)}${accessParams}\n` +
+            `  LOCATION (${locations})\n` +
+            `)\n` +
+            `REJECT LIMIT ${rejectLimit}`;
+        await this.query(sql);
+    }
+    // ==================== Oracle Text (full-text search) ====================
+    /**
+     * Build an Oracle Text `CONTAINS(column, 'query') > 0` predicate for use in a
+     * WHERE clause against a `CTXSYS.CONTEXT` index (see `createFulltextIndex`).
+     * `label` ties the predicate to a `SCORE(label)` projection.
+     */
+    buildContains(column, query, label = 1) {
+        return `CONTAINS(${this.quoteIdentifier(column)}, '${String(query).replace(/'/g, "''")}', ${label}) > 0`;
+    }
+    /**
+     * Build an Oracle Text `SCORE(label)` projection expression that reports the
+     * relevance score computed by a matching `CONTAINS(..., label)` predicate.
+     */
+    buildScore(label = 1) {
+        return `SCORE(${label})`;
+    }
 }
 exports.OracleDialect = OracleDialect;
 /** ORA-00955: name is already used by an existing object. */