@fastrack/starter-db-oracle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fastrack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @fastrack/starter-db-oracle
+
+Oracle pooled connections via `oracledb`. Contract: query(sql, params), transaction(fn), health() with lightweight readiness query.
+
+See [docs/starters.md](../../docs/starters.md).

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fastrack/starter-db-oracle — Oracle pool, query/transaction, health.
+ */
+export { oracleStarter } from "./plugin.js";
+export type { OracleStarterConfig, OracleClient } from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * @fastrack/starter-db-oracle — Oracle pool, query/transaction, health.
+ */
+export { oracleStarter } from "./plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,21 @@
+import { type Static } from "@sinclair/typebox";
+import type { FastrackStarter } from "@fastrack/core";
+export declare const OracleStarterConfigSchema: import("@sinclair/typebox").TObject<{
+    connectionString: import("@sinclair/typebox").TString;
+    user: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    password: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    poolMin: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    poolMax: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type OracleStarterConfig = Static<typeof OracleStarterConfigSchema>;
+export interface OracleClient {
+    query(sql: string, params?: unknown[]): Promise<unknown[]>;
+    transaction<T>(fn: (tx: {
+        query: (sql: string, params?: unknown[]) => Promise<unknown[]>;
+    }) => Promise<T>): Promise<T>;
+    health(): Promise<{
+        ok: boolean;
+    }>;
+}
+export declare const oracleStarter: FastrackStarter<OracleStarterConfig>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,gBAAgB,CAAC;AAGvE,eAAO,MAAM,yBAAyB;;;;;;EAMpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE3E,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3D,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvH,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,aAAa,EAAE,eAAe,CAAC,mBAAmB,CA4D9D,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,77 @@
+import { Type } from "@sinclair/typebox";
+import oracledb from "oracledb";
+import { registerHealthContributor } from "@fastrack/starter-actuator";
+export const OracleStarterConfigSchema = Type.Object({
+    connectionString: Type.String(),
+    user: Type.Optional(Type.String()),
+    password: Type.Optional(Type.String()),
+    poolMin: Type.Optional(Type.Number({ default: 0 })),
+    poolMax: Type.Optional(Type.Number({ default: 10 })),
+});
+export const oracleStarter = {
+    name: "db-oracle",
+    configSchema: OracleStarterConfigSchema,
+    defaults: { poolMin: 0, poolMax: 10 },
+    register(app, ctx, config) {
+        const poolConfig = {
+            user: config.user,
+            password: config.password,
+            connectString: config.connectionString,
+            poolMin: config.poolMin ?? 0,
+            poolMax: config.poolMax ?? 10,
+        };
+        let pool = null;
+        async function getPool() {
+            if (!pool)
+                pool = await oracledb.createPool(poolConfig);
+            return pool;
+        }
+        const client = {
+            async query(sqlText, params) {
+                const p = await getPool();
+                const conn = await p.getConnection();
+                try {
+                    const result = await conn.execute(sqlText, params ?? []);
+                    return (result.rows ?? []);
+                }
+                finally {
+                    await conn.close();
+                }
+            },
+            async transaction(fn) {
+                const p = await getPool();
+                const conn = await p.getConnection();
+                try {
+                    await conn.execute("BEGIN NULL; END;");
+                    const tx = {
+                        query: async (sqlText, params) => {
+                            const result = await conn.execute(sqlText, params ?? []);
+                            return (result.rows ?? []);
+                        },
+                    };
+                    const out = await fn(tx);
+                    return out;
+                }
+                finally {
+                    await conn.close();
+                }
+            },
+            async health() {
+                try {
+                    const rows = await client.query("SELECT 1 FROM DUAL");
+                    return { ok: Array.isArray(rows) && rows.length > 0 };
+                }
+                catch {
+                    return { ok: false };
+                }
+            },
+        };
+        app.decorate("oracle", client);
+        registerHealthContributor(app, "oracle", () => client.health());
+        ctx.onShutdown?.(async () => {
+            if (pool)
+                await pool.close(10);
+        });
+    },
+};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@fastrack/starter-db-oracle",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.34",
+    "fastify": "^5.1.0",
+    "oracledb": "^6.7.0",
+    "@fastrack/core": "0.1.0",
+    "@fastrack/starter-actuator": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "echo ok",
+    "test": "echo ok"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @fastrack/starter-db-oracle — Oracle pool, query/transaction, health.
+ */
+export { oracleStarter } from "./plugin.js";
+export type { OracleStarterConfig, OracleClient } from "./plugin.js";

package/src/oracledb.d.ts

@@ -0,0 +1,18 @@
+declare module "oracledb" {
+  export interface PoolAttributes {
+    user?: string;
+    password?: string;
+    connectString?: string;
+    poolMin?: number;
+    poolMax?: number;
+  }
+  export interface Pool {
+    getConnection(): Promise<Connection>;
+    close(gracePeriod?: number): Promise<void>;
+  }
+  export interface Connection {
+    execute(sql: string, params?: unknown[]): Promise<{ rows?: unknown[] }>;
+    close(): Promise<void>;
+  }
+  export function createPool(config: PoolAttributes): Promise<Pool>;
+}

package/src/plugin.ts

@@ -0,0 +1,83 @@
+import { Type, type Static } from "@sinclair/typebox";
+import oracledb from "oracledb";
+import type { FastifyInstance } from "fastify";
+import type { FastrackStarter, FastrackContext } from "@fastrack/core";
+import { registerHealthContributor } from "@fastrack/starter-actuator";
+
+export const OracleStarterConfigSchema = Type.Object({
+  connectionString: Type.String(),
+  user: Type.Optional(Type.String()),
+  password: Type.Optional(Type.String()),
+  poolMin: Type.Optional(Type.Number({ default: 0 })),
+  poolMax: Type.Optional(Type.Number({ default: 10 })),
+});
+
+export type OracleStarterConfig = Static<typeof OracleStarterConfigSchema>;
+
+export interface OracleClient {
+  query(sql: string, params?: unknown[]): Promise<unknown[]>;
+  transaction<T>(fn: (tx: { query: (sql: string, params?: unknown[]) => Promise<unknown[]> }) => Promise<T>): Promise<T>;
+  health(): Promise<{ ok: boolean }>;
+}
+
+export const oracleStarter: FastrackStarter<OracleStarterConfig> = {
+  name: "db-oracle",
+  configSchema: OracleStarterConfigSchema,
+  defaults: { poolMin: 0, poolMax: 10 },
+  register(app: FastifyInstance, ctx: FastrackContext, config: OracleStarterConfig) {
+    const poolConfig: oracledb.PoolAttributes = {
+      user: config.user,
+      password: config.password,
+      connectString: config.connectionString,
+      poolMin: config.poolMin ?? 0,
+      poolMax: config.poolMax ?? 10,
+    };
+    let pool: oracledb.Pool | null = null;
+    async function getPool(): Promise<oracledb.Pool> {
+      if (!pool) pool = await oracledb.createPool(poolConfig);
+      return pool;
+    }
+    const client: OracleClient = {
+      async query(sqlText: string, params?: unknown[]) {
+        const p = await getPool();
+        const conn = await p.getConnection();
+        try {
+          const result = await conn.execute(sqlText, params ?? []);
+          return (result.rows ?? []) as unknown[];
+        } finally {
+          await conn.close();
+        }
+      },
+      async transaction<T>(fn: (tx: { query: (s: string, p?: unknown[]) => Promise<unknown[]> }) => Promise<T>) {
+        const p = await getPool();
+        const conn = await p.getConnection();
+        try {
+          await conn.execute("BEGIN NULL; END;");
+          const tx = {
+            query: async (sqlText: string, params?: unknown[]) => {
+              const result = await conn.execute(sqlText, params ?? []);
+              return (result.rows ?? []) as unknown[];
+            },
+          };
+          const out = await fn(tx);
+          return out;
+        } finally {
+          await conn.close();
+        }
+      },
+      async health() {
+        try {
+          const rows = await client.query("SELECT 1 FROM DUAL");
+          return { ok: Array.isArray(rows) && rows.length > 0 };
+        } catch {
+          return { ok: false };
+        }
+      },
+    };
+    app.decorate("oracle", client);
+    registerHealthContributor(app, "oracle", () => client.health());
+    ctx.onShutdown?.(async () => {
+      if (pool) await pool.close(10);
+    });
+  },
+};

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}