@fastrack/starter-db-mssql 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-mssql
+
+MSSQL pooled connections via `mssql` driver. Contract: query(sql, params), transaction(fn), health() with SELECT 1. Parameterized queries only.
+
+See [docs/starters.md](../../docs/starters.md).

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fastrack/starter-db-mssql — MSSQL pool, query/transaction, health SELECT 1.
+ */
+export { mssqlStarter } from "./plugin.js";
+export type { MssqlStarterConfig, MssqlClient } 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,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * @fastrack/starter-db-mssql — MSSQL pool, query/transaction, health SELECT 1.
+ */
+export { mssqlStarter } 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,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,18 @@
+import { type Static } from "@sinclair/typebox";
+import type { FastrackStarter } from "@fastrack/core";
+export declare const MssqlStarterConfigSchema: import("@sinclair/typebox").TObject<{
+    connectionString: import("@sinclair/typebox").TString;
+    poolMax: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export type MssqlStarterConfig = Static<typeof MssqlStarterConfigSchema>;
+export interface MssqlClient {
+    query(sql: string, params?: Record<string, unknown>): Promise<unknown[]>;
+    transaction<T>(fn: (tx: {
+        query: (sql: string, params?: Record<string, unknown>) => Promise<unknown[]>;
+    }) => Promise<T>): Promise<T>;
+    health(): Promise<{
+        ok: boolean;
+    }>;
+}
+export declare const mssqlStarter: FastrackStarter<MssqlStarterConfig>;
+//# 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,wBAAwB;;;EAGnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEzE,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACzE,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrI,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACpC;AAED,eAAO,MAAM,YAAY,EAAE,eAAe,CAAC,kBAAkB,CAuD5D,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,71 @@
+import { Type } from "@sinclair/typebox";
+import sql from "mssql";
+import { registerHealthContributor } from "@fastrack/starter-actuator";
+export const MssqlStarterConfigSchema = Type.Object({
+    connectionString: Type.String(),
+    poolMax: Type.Optional(Type.Number({ default: 10 })),
+});
+export const mssqlStarter = {
+    name: "db-mssql",
+    configSchema: MssqlStarterConfigSchema,
+    defaults: { poolMax: 10 },
+    register(app, ctx, config) {
+        const pool = new sql.ConnectionPool(config.connectionString, { max: config.poolMax ?? 10 });
+        let poolPromise = null;
+        async function getPool() {
+            if (!poolPromise)
+                poolPromise = pool.connect();
+            return poolPromise;
+        }
+        const client = {
+            async query(sqlText, params) {
+                const p = await getPool();
+                const req = p.request();
+                if (params)
+                    for (const [k, v] of Object.entries(params))
+                        req.input(k, v);
+                const result = await req.query(sqlText);
+                return result.recordset ?? [];
+            },
+            async transaction(fn) {
+                const p = await getPool();
+                const t = new sql.Transaction(p);
+                await t.begin();
+                try {
+                    const tx = {
+                        query: async (sqlText, params) => {
+                            const req = new sql.Request(t);
+                            if (params)
+                                for (const [k, v] of Object.entries(params))
+                                    req.input(k, v);
+                            const result = await req.query(sqlText);
+                            return result.recordset ?? [];
+                        },
+                    };
+                    const out = await fn(tx);
+                    await t.commit();
+                    return out;
+                }
+                catch (e) {
+                    await t.rollback();
+                    throw e;
+                }
+            },
+            async health() {
+                try {
+                    const rows = await client.query("SELECT 1 AS n");
+                    return { ok: Array.isArray(rows) && rows.length > 0 };
+                }
+                catch {
+                    return { ok: false };
+                }
+            },
+        };
+        app.decorate("mssql", client);
+        registerHealthContributor(app, "mssql", () => client.health());
+        ctx.onShutdown?.(async () => {
+            await pool.close();
+        });
+    },
+};
+//# 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-mssql",
+  "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",
+    "mssql": "^11.0.1",
+    "@fastrack/starter-actuator": "0.1.0",
+    "@fastrack/core": "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-mssql — MSSQL pool, query/transaction, health SELECT 1.
+ */
+export { mssqlStarter } from "./plugin.js";
+export type { MssqlStarterConfig, MssqlClient } from "./plugin.js";

package/src/mssql.d.ts

@@ -0,0 +1,25 @@
+declare module "mssql" {
+  export interface ConnectionPool {
+    connect(): Promise<ConnectionPool>;
+    request(): Request;
+    close(): Promise<void>;
+  }
+  export interface Request {
+    input(name: string, value: unknown): Request;
+    query(sql: string): Promise<{ recordset: unknown[] }>;
+  }
+  export interface Transaction {
+    begin(): Promise<void>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+  }
+  export class ConnectionPool {
+    constructor(config: string | Record<string, unknown>, options?: { max?: number });
+  }
+  export class Transaction {
+    constructor(pool: ConnectionPool);
+  }
+  export class Request {
+    constructor(transaction?: Transaction);
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,75 @@
+import { Type, type Static } from "@sinclair/typebox";
+import sql from "mssql";
+import type { FastifyInstance } from "fastify";
+import type { FastrackStarter, FastrackContext } from "@fastrack/core";
+import { registerHealthContributor } from "@fastrack/starter-actuator";
+
+export const MssqlStarterConfigSchema = Type.Object({
+  connectionString: Type.String(),
+  poolMax: Type.Optional(Type.Number({ default: 10 })),
+});
+
+export type MssqlStarterConfig = Static<typeof MssqlStarterConfigSchema>;
+
+export interface MssqlClient {
+  query(sql: string, params?: Record<string, unknown>): Promise<unknown[]>;
+  transaction<T>(fn: (tx: { query: (sql: string, params?: Record<string, unknown>) => Promise<unknown[]> }) => Promise<T>): Promise<T>;
+  health(): Promise<{ ok: boolean }>;
+}
+
+export const mssqlStarter: FastrackStarter<MssqlStarterConfig> = {
+  name: "db-mssql",
+  configSchema: MssqlStarterConfigSchema,
+  defaults: { poolMax: 10 },
+  register(app: FastifyInstance, ctx: FastrackContext, config: MssqlStarterConfig) {
+    const pool = new sql.ConnectionPool(config.connectionString, { max: config.poolMax ?? 10 });
+    let poolPromise: Promise<sql.ConnectionPool> | null = null;
+    async function getPool(): Promise<sql.ConnectionPool> {
+      if (!poolPromise) poolPromise = pool.connect();
+      return poolPromise;
+    }
+    const client: MssqlClient = {
+      async query(sqlText: string, params?: Record<string, unknown>) {
+        const p = await getPool();
+        const req = p.request();
+        if (params) for (const [k, v] of Object.entries(params)) req.input(k, v);
+        const result = await req.query(sqlText);
+        return result.recordset ?? [];
+      },
+      async transaction<T>(fn: (tx: { query: (s: string, p?: Record<string, unknown>) => Promise<unknown[]> }) => Promise<T>) {
+        const p = await getPool();
+        const t = new sql.Transaction(p);
+        await t.begin();
+        try {
+          const tx = {
+            query: async (sqlText: string, params?: Record<string, unknown>) => {
+              const req = new sql.Request(t);
+              if (params) for (const [k, v] of Object.entries(params)) req.input(k, v);
+              const result = await req.query(sqlText);
+              return result.recordset ?? [];
+            },
+          };
+          const out = await fn(tx);
+          await t.commit();
+          return out;
+        } catch (e) {
+          await t.rollback();
+          throw e;
+        }
+      },
+      async health() {
+        try {
+          const rows = await client.query("SELECT 1 AS n");
+          return { ok: Array.isArray(rows) && rows.length > 0 };
+        } catch {
+          return { ok: false };
+        }
+      },
+    };
+    app.decorate("mssql", client);
+    registerHealthContributor(app, "mssql", () => client.health());
+    ctx.onShutdown?.(async () => {
+      await pool.close();
+    });
+  },
+};

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"]
+}