narai-primitives 2.0.0-rc.1

package/dist/connectors/db/lib/drivers/oracle.js

@@ -0,0 +1,350 @@
+/**
+ * drivers/oracle.ts — Oracle Database driver via the `oracledb` package.
+ *
+ * Design:
+ *  - Mirrors `postgresql.ts`: a lazily-created pool is cached on the driver
+ *    instance, each `connect()` checks out a connection from the pool, and
+ *    `close()` returns it. `shutdown()` drains the pool.
+ *  - oracledb 6.x defaults to **Thin mode** — pure JavaScript, no Oracle
+ *    Instant Client needed. We never call `initOracleClient()`; switching
+ *    to Thick mode is the caller's explicit choice to make in their own
+ *    process bootstrap before this driver loads.
+ *  - Read-only: every `executeReadAsync` runs a defensive `ROLLBACK`
+ *    followed by `SET TRANSACTION READ ONLY`, with `callTimeout` set on
+ *    the connection for a server-enforced bound.
+ *  - The `oracledb` module is loaded with a dynamic `import()` so this
+ *    file compiles even when the package is not installed. On a missing
+ *    install, `connect()` throws a helpful `npm install oracledb` hint.
+ */
+import { performance } from "node:perf_hooks";
+import { Column, DatabaseDriver, Table, } from "./base.js";
+import { classifySqlKeywords } from "../policy.js";
+export class OracleDriver extends DatabaseDriver {
+    _oracleModule = null;
+    _pool = null;
+    _schema = null;
+    _poolPromise = null;
+    async _loadOracle() {
+        if (this._oracleModule !== null)
+            return this._oracleModule;
+        let mod;
+        try {
+            mod = (await import("oracledb"));
+        }
+        catch (e) {
+            throw new Error(`Driver 'oracle' requires 'oracledb' — run: npm install oracledb (${e.message})`);
+        }
+        const resolved = "createPool" in mod
+            ? mod
+            : mod.default;
+        // G-ORA-PER-CALL-OPTS: oracledb 6.x exposes `outFormat` / `fetchAsString`
+        // as accessor properties on the module object whose setters throw in
+        // some ESM-import contexts ("Cannot redefine property"). We pass the
+        // option per-execute in `_readOpts()` instead of mutating module state.
+        this._oracleModule = resolved;
+        return resolved;
+    }
+    /**
+     * Options passed to every read-path `connection.execute()` — returns
+     * rows as `Record<string, unknown>[]` (matching PG/MySQL driver shape).
+     * Requires `_loadOracle()` to have populated `_oracleModule` first.
+     */
+    _readOpts() {
+        return { outFormat: this._oracleModule.OUT_FORMAT_OBJECT };
+    }
+    /**
+     * Build the pool on first call; subsequent callers receive the cached
+     * instance (or await the in-flight creation promise to avoid racing two
+     * `createPool()` calls on concurrent connects).
+     */
+    _ensurePool(envConfig) {
+        if (this._pool !== null)
+            return Promise.resolve(this._pool);
+        if (this._poolPromise !== null)
+            return this._poolPromise;
+        this._poolPromise = this._loadOracle().then(async (oracledb) => {
+            const host = typeof envConfig["host"] === "string" ? envConfig["host"] : "localhost";
+            const port = typeof envConfig["port"] === "number" ? envConfig["port"] : 1521;
+            const serviceName = typeof envConfig["service_name"] === "string"
+                ? envConfig["service_name"]
+                : typeof envConfig["database"] === "string"
+                    ? envConfig["database"]
+                    : "";
+            const sid = typeof envConfig["sid"] === "string" ? envConfig["sid"] : null;
+            // G-ORA-CONNSTRING: prefer an explicit connectString (TNS alias or
+            // EZConnect URL); otherwise compose one. SID form uses a colon
+            // separator (legacy), service-name form uses a slash (EZConnect).
+            const connectString = typeof envConfig["connectString"] === "string"
+                ? envConfig["connectString"]
+                : sid !== null
+                    ? `${host}:${port}:${sid}`
+                    : `${host}:${port}/${serviceName}`;
+            // G-ORA-IGNORE-PUBLIC-DEFAULT: `registerEnvironment` (environments.ts)
+            // defaults `schema` to "public" — a PostgreSQL-ism that makes sense
+            // only for PG's schema-per-app model. Oracle reserves PUBLIC for
+            // synonyms (`CREATE PUBLIC SYNONYM …`), not as a settable schema;
+            // applying `ALTER SESSION SET CURRENT_SCHEMA = "public"` raises
+            // ORA-01435 "user does not exist". Treat "public" as the no-override
+            // sentinel. Explicit Oracle users will pass a real schema name like
+            // "HR" or "APP_USER" which is respected as-is.
+            const rawSchema = envConfig["schema"];
+            this._schema =
+                typeof rawSchema === "string" &&
+                    rawSchema.length > 0 &&
+                    rawSchema.toLowerCase() !== "public"
+                    ? rawSchema
+                    : null;
+            const poolAttrs = {
+                connectString,
+                poolMin: 0,
+                poolMax: typeof envConfig["pool_max"] === "number"
+                    ? envConfig["pool_max"]
+                    : 10,
+                poolIncrement: 1,
+                poolTimeout: 60,
+            };
+            if (typeof envConfig["user"] === "string")
+                poolAttrs["user"] = envConfig["user"];
+            if (typeof envConfig["password"] === "string")
+                poolAttrs["password"] = envConfig["password"];
+            const pool = await oracledb.createPool(poolAttrs);
+            this._pool = pool;
+            return pool;
+        });
+        return this._poolPromise;
+    }
+    connect(envConfig) {
+        return this._ensurePool(envConfig).then(async (pool) => {
+            const connection = await pool.getConnection();
+            return { connection, schema: this._schema };
+        });
+    }
+    executeRead(_conn, _query, _params = null, _maxRows = 1000, _timeoutMs = 30_000) {
+        return {
+            status: "error",
+            error_code: "SYNC_UNSUPPORTED",
+            error: "OracleDriver.executeRead is async — call executeReadAsync() instead.",
+            execution_time_ms: 0,
+        };
+    }
+    async executeReadAsync(conn, query, params = null, maxRows = 1000, timeoutMs = 30_000) {
+        const handle = (await conn);
+        const start = performance.now();
+        const { connection } = handle;
+        try {
+            // G-ORA-TIMEOUT: oracledb enforces timeouts at the connection level
+            // (ms). Set before executing, clear in `finally` so a returned pool
+            // connection does not inherit this call's deadline.
+            connection.callTimeout = Math.max(1, timeoutMs);
+            // G-ORA-NO-READONLY-TXN: unlike PG (`BEGIN READ ONLY`) and MySQL
+            // (`SET SESSION TRANSACTION READ ONLY`), Oracle's equivalent
+            // `SET TRANSACTION READ ONLY` uses SCN-based snapshot semantics
+            // that raise ORA-01466 ("unable to read data — table definition
+            // has changed") if any referenced table was DDL'd within the
+            // read-only window's propagation delay. Skipping it here: the
+            // policy gate is the authoritative safety — it classifies every
+            // statement before the driver sees it and only READ queries
+            // reach `executeReadAsync`. Belt-and-suspenders at the DB layer
+            // would trade a real edge-case failure (reads after recent DDL)
+            // for negligible extra safety.
+            if (handle.schema !== null) {
+                // Oracle preserves the case of quoted identifiers; we pass the
+                // user-configured schema through verbatim inside double quotes
+                // (escaping any embedded quote). Unquoted names would be folded
+                // to uppercase silently.
+                const safe = handle.schema.replace(/"/g, '""');
+                await connection.execute(`ALTER SESSION SET CURRENT_SCHEMA = "${safe}"`);
+            }
+            // G-LIMIT-WRAP: wrap as a subquery so bounded semantics hold even
+            // when the outer query has a trailing comment or an inner FETCH
+            // clause. Oracle 12c+ supports FETCH FIRST N ROWS ONLY; FREEPDB1
+            // (23ai Free) and XEPDB1 (21c XE) both meet this.
+            const inner = query.trim().replace(/;\s*$/, "");
+            const limited = `SELECT * FROM (${inner}) FETCH FIRST ${maxRows + 1} ROWS ONLY`;
+            const result = await connection.execute(limited, params ?? [], this._readOpts());
+            const rawRows = (result.rows ?? []);
+            let truncated = false;
+            let rows = rawRows;
+            if (rows.length > maxRows) {
+                truncated = true;
+                rows = rows.slice(0, maxRows);
+            }
+            return {
+                status: "success",
+                rows,
+                row_count: rows.length,
+                columns: (result.metaData ?? []).map((m) => m.name),
+                execution_time_ms: roundTo2(performance.now() - start),
+                truncated,
+            };
+        }
+        catch (e) {
+            try {
+                await connection.execute("ROLLBACK");
+            }
+            catch {
+                /* best-effort */
+            }
+            const err = e;
+            const errorCode = err.errorNum !== undefined ? `ORA-${err.errorNum}` : "SQL_ERROR";
+            return {
+                status: "error",
+                error_code: errorCode,
+                error: err.message,
+                execution_time_ms: roundTo2(performance.now() - start),
+            };
+        }
+        finally {
+            try {
+                connection.callTimeout = 0;
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    getSchema(_conn, _schemaName = "", _tableFilter = null) {
+        return [];
+    }
+    async getSchemaAsync(conn, schemaName = "", tableFilter = null) {
+        const handle = (await conn);
+        const { connection } = handle;
+        try {
+            // G-ORA-OWNER: Oracle stores unquoted owner names in ALL_TABLES.OWNER
+            // as uppercase. Uppercase the caller-supplied schema so `foo` matches
+            // the `FOO` the dictionary holds. If nothing is supplied, fall back
+            // to the session's CURRENT_SCHEMA.
+            let owner;
+            if (schemaName.length > 0) {
+                owner = schemaName.toUpperCase();
+            }
+            else if (handle.schema !== null) {
+                owner = handle.schema.toUpperCase();
+            }
+            else {
+                const r = await connection.execute("SELECT SYS_CONTEXT('USERENV','CURRENT_SCHEMA') AS S FROM DUAL", [], this._readOpts());
+                const first = (r.rows ?? [])[0];
+                owner = String(first?.["S"] ?? "").toUpperCase();
+            }
+            const tableParams = [owner];
+            let tableSql = "SELECT table_name FROM all_tables WHERE owner = :1";
+            if (tableFilter !== null && tableFilter !== undefined) {
+                tableSql += " AND table_name LIKE :2 ESCAPE '!'";
+                tableParams.push(tableFilter.toUpperCase().replace(/[!_%]/g, "!$&"));
+            }
+            tableSql += " ORDER BY table_name";
+            const tablesResult = await connection.execute(tableSql, tableParams, this._readOpts());
+            const tableNames = (tablesResult.rows ?? []).map((r) => String(r["TABLE_NAME"]));
+            if (tableNames.length === 0)
+                return [];
+            // G-ORA-SCHEMA-BATCH: Oracle lacks PG's `= ANY($N::text[])`. Build
+            // a positional IN-list instead (`IN (:2, :3, ...)`) so the columns
+            // and PKs come back in 2 batch round-trips total — matching PG's
+            // 3-round-trip shape (tables + columns + PKs).
+            const placeholders = tableNames.map((_, i) => `:${i + 2}`).join(",");
+            const colsResult = await connection.execute("SELECT table_name, column_name, data_type, nullable, data_default, column_id " +
+                "FROM all_tab_columns " +
+                `WHERE owner = :1 AND table_name IN (${placeholders}) ` +
+                "ORDER BY table_name, column_id", [owner, ...tableNames], this._readOpts());
+            const pkResult = await connection.execute("SELECT c.table_name, cc.column_name " +
+                "FROM all_constraints c " +
+                "JOIN all_cons_columns cc " +
+                "  ON cc.owner = c.owner AND cc.constraint_name = c.constraint_name " +
+                `WHERE c.owner = :1 AND c.constraint_type = 'P' ` +
+                `AND c.table_name IN (${placeholders})`, [owner, ...tableNames], this._readOpts());
+            const pksByTable = new Map();
+            for (const row of pkResult.rows ?? []) {
+                const r = row;
+                const t = String(r["TABLE_NAME"]);
+                let set = pksByTable.get(t);
+                if (set === undefined) {
+                    set = new Set();
+                    pksByTable.set(t, set);
+                }
+                set.add(String(r["COLUMN_NAME"]));
+            }
+            const colsByTable = new Map();
+            for (const row of colsResult.rows ?? []) {
+                const r = row;
+                const t = String(r["TABLE_NAME"]);
+                let list = colsByTable.get(t);
+                if (list === undefined) {
+                    list = [];
+                    colsByTable.set(t, list);
+                }
+                const name = String(r["COLUMN_NAME"]);
+                list.push(new Column({
+                    name,
+                    data_type: String(r["DATA_TYPE"]),
+                    nullable: String(r["NULLABLE"]).toUpperCase() === "Y",
+                    is_primary_key: pksByTable.get(t)?.has(name) ?? false,
+                    default: r["DATA_DEFAULT"] === null || r["DATA_DEFAULT"] === undefined
+                        ? null
+                        : String(r["DATA_DEFAULT"]),
+                }));
+            }
+            const out = [];
+            for (const tableName of tableNames) {
+                out.push(new Table({
+                    name: tableName,
+                    schema: owner,
+                    columns: colsByTable.get(tableName) ?? [],
+                }));
+            }
+            return out;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Release the checked-out connection back to the pool. Does NOT destroy
+     * the pool — use {@link shutdown} for that.
+     */
+    close(conn) {
+        Promise.resolve(conn)
+            .then((h) => h.connection.close())
+            .catch((e) => {
+            process.stderr.write(`[oracle] release error (best-effort): ${e instanceof Error ? e.message : String(e)}\n`);
+        });
+    }
+    classifyOperation(query) {
+        return classifySqlKeywords(query);
+    }
+    async closeAsync(conn) {
+        const handle = (await conn);
+        try {
+            await handle.connection.close();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    async healthCheck(conn) {
+        try {
+            const handle = (await conn);
+            const r = await handle.connection.execute("SELECT 1 FROM DUAL", [], this._readOpts());
+            return (r.rows ?? []).length === 1;
+        }
+        catch {
+            return false;
+        }
+    }
+    async shutdown() {
+        const pool = this._pool;
+        this._pool = null;
+        this._poolPromise = null;
+        if (pool !== null) {
+            try {
+                await pool.close(10);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+}
+function roundTo2(n) {
+    return Math.round(n * 100) / 100;
+}
+//# sourceMappingURL=oracle.js.map

package/dist/connectors/db/lib/drivers/oracle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oracle.js","sourceRoot":"","sources":["../../../../../src/connectors/db/lib/drivers/oracle.ts"],"names":[],"mappings":"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"}

package/dist/connectors/db/lib/drivers/postgresql.d.ts

@@ -0,0 +1,65 @@
+import { DatabaseDriver, Table, type ExecuteReadResult } from "./base.js";
+import { type OperationType } from "../policy.js";
+interface PgQueryResultField {
+    name: string;
+    dataTypeID?: number;
+}
+interface PgQueryResult {
+    rows: Record<string, unknown>[];
+    rowCount: number | null;
+    fields: PgQueryResultField[];
+}
+interface PgClient {
+    query(text: string, params?: unknown[]): Promise<PgQueryResult>;
+    release(err?: Error | boolean): void;
+}
+/**
+ * Handle returned by {@link PostgresDriver.connect}. Carries the checked-out
+ * client plus a reference back to the configured default schema. The
+ * parent pool is held on the driver instance.
+ */
+interface PgHandle {
+    client: PgClient;
+    schema: string | null;
+}
+export declare class PostgresDriver extends DatabaseDriver {
+    private _pgModule;
+    private _pool;
+    private _schema;
+    private _poolPromise;
+    private _loadPg;
+    /**
+     * Build the pool on first call; subsequent callers receive the cached
+     * instance (or await the in-flight creation promise to avoid racing
+     * two `new Pool()` calls on concurrent connects).
+     */
+    private _ensurePool;
+    /**
+     * Check out a client from the pool. connection.ts tracks one handle per
+     * `getConnection()` call; `close()` releases the client back to the pool.
+     */
+    connect(envConfig: Record<string, unknown>): Promise<PgHandle>;
+    executeRead(_conn: unknown, _query: string, _params?: unknown[] | null, _maxRows?: number, _timeoutMs?: number): ExecuteReadResult;
+    executeReadAsync(conn: unknown, query: string, params?: unknown[] | null, maxRows?: number, timeoutMs?: number): Promise<ExecuteReadResult>;
+    getSchema(_conn: unknown, _schemaName?: string, _tableFilter?: string | null): Table[];
+    getSchemaAsync(conn: unknown, schemaName?: string, tableFilter?: string | null): Promise<Table[]>;
+    /**
+     * Release the checked-out client back to the pool. Does NOT destroy
+     * the pool — use {@link shutdown} for that.
+     */
+    close(conn: unknown): void;
+    classifyOperation(query: string): OperationType;
+    closeAsync(conn: unknown): Promise<void>;
+    /**
+     * Per-driver health check. Runs `SELECT 1` on the given handle. Caller
+     * still owns the handle and is responsible for {@link close}-ing it.
+     */
+    healthCheck(conn: unknown): Promise<boolean>;
+    /**
+     * Drain and destroy the pool. connection.ts's `shutdownAll()` fans out
+     * to each driver instance; this is where we actually close sockets.
+     */
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=postgresql.d.ts.map

package/dist/connectors/db/lib/drivers/postgresql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgresql.d.ts","sourceRoot":"","sources":["../../../../../src/connectors/db/lib/drivers/postgresql.ts"],"names":[],"mappings":"AAmBA,OAAO,EAEL,cAAc,EACd,KAAK,EACL,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAMvE,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AACD,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AACD,UAAU,QAAQ;IAChB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAChE,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;CACtC;AAaD;;;;GAIG;AACH,UAAU,QAAQ;IAChB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,qBAAa,cAAe,SAAQ,cAAc;IAChD,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,YAAY,CAAgC;YAEtC,OAAO;IAoBrB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAiDnB;;;OAGG;IACM,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAO9D,WAAW,CAClB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,OAAO,EAAE,GAAG,IAAW,EAChC,QAAQ,GAAE,MAAa,EACvB,UAAU,GAAE,MAAe,GAC1B,iBAAiB;IAUd,gBAAgB,CACpB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,OAAO,EAAE,GAAG,IAAW,EAC/B,OAAO,GAAE,MAAa,EACtB,SAAS,GAAE,MAAe,GACzB,OAAO,CAAC,iBAAiB,CAAC;IAqDpB,SAAS,CAChB,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,MAAW,EACxB,YAAY,GAAE,MAAM,GAAG,IAAW,GACjC,KAAK,EAAE;IAIJ,cAAc,CAClB,IAAI,EAAE,OAAO,EACb,UAAU,GAAE,MAAW,EACvB,WAAW,GAAE,MAAM,GAAG,IAAW,GAChC,OAAO,CAAC,KAAK,EAAE,CAAC;IA2FnB;;;OAGG;IACM,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAgB1B,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa;IAIlD,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9C;;;OAGG;IACG,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAUlD;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAYhC"}