@healthzkit/sqlite 0.0.1

package/README.md

@@ -0,0 +1,174 @@
+# @healthzkit/sqlite
+
+SQLite **healthzkit** `HealthAdapter` helpers for **[`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3)** (synchronous), **[`sqlite3`](https://github.com/TryGhost/node-sqlite3)** (callback driver), and **[`@libsql/client`](https://github.com/tursodatabase/libsql-client-ts)** (libSQL / Turso). Successful checks run a lightweight SQL probe (default **`SELECT 1`**) and return `ok` with `metadata.latencyMs` plus any fields from an optional `metadata` hook; failures return `fail` with the caught error.
+
+## Install
+
+```bash
+npm install @healthzkit/sqlite healthzkit
+# plus one of:
+npm install better-sqlite3
+npm install sqlite3
+npm install @libsql/client
+```
+
+All drivers are optional peers—install only the one you use.
+
+## Package entrypoints
+
+| Import                              | Exports                                                              |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| `@healthzkit/sqlite`                | `betterSqlite3Adapter`, `sqlite3Adapter`, `libsqlAdapter`, and types |
+| `@healthzkit/sqlite/better-sqlite3` | `betterSqlite3Adapter` only                                          |
+| `@healthzkit/sqlite/sqlite3`        | `sqlite3Adapter` only                                                |
+| `@healthzkit/sqlite/libsql`         | `libsqlAdapter` only                                                 |
+
+Use subpath imports when you want to avoid pulling unused drivers into your bundle analysis path.
+
+## Shared options
+
+Every factory accepts `BaseSqliteOptions`:
+
+| Option     | Description                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `query`    | SQL executed for the probe. Default `SELECT 1`.                                                       |
+| `metadata` | Optional `(client) => Record<string, unknown>` (sync or async) merged into metadata with `latencyMs`. |
+
+Pass either connection credentials or an existing `client` (not both). The shape depends on the adapter (see below).
+
+## `betterSqlite3Adapter` (`better-sqlite3`)
+
+**Peer:** `better-sqlite3` ≥ 12.
+
+Runs `client.prepare(query).get()` and records round-trip latency. Best for embedded SQLite in the same process.
+
+### Connection string
+
+The adapter lazily imports `better-sqlite3`, opens the database once, and reuses it across checks.
+
+```ts
+import { createHealthKit } from "healthzkit";
+import { betterSqlite3Adapter } from "@healthzkit/sqlite";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "sqlite",
+      type: ["readiness"],
+      adapter: betterSqlite3Adapter({
+        connectionString: process.env.SQLITE_PATH ?? ":memory:",
+        options: { readonly: true },
+      }),
+    },
+  ],
+});
+```
+
+`connectionString` is a file path (e.g. `./data/app.db`) or `:memory:`.
+
+### Existing client
+
+```ts
+import Database from "better-sqlite3";
+import { betterSqlite3Adapter } from "@healthzkit/sqlite/better-sqlite3";
+
+const db = new Database("app.db");
+
+const adapter = betterSqlite3Adapter({
+  client: db,
+  query: "SELECT sqlite_version()",
+  metadata: (client) => ({ path: "app.db" }),
+});
+```
+
+## `sqlite3Adapter` (`sqlite3`)
+
+**Peer:** `sqlite3` ≥ 5 or ≥ 6.
+
+Uses the classic callback API: `client.get(query, callback)`. Suitable when you already depend on `node-sqlite3`.
+
+### Connection string
+
+Opens the database via `new sqlite3.Database(connectionString, mode, callback)` and caches the handle. Default open mode is `OPEN_READWRITE | OPEN_CREATE`.
+
+```ts
+import { sqlite3Adapter } from "@healthzkit/sqlite/sqlite3";
+
+const adapter = sqlite3Adapter({
+  connectionString: "./data/app.db",
+  mode: undefined, // optional; defaults to read/write + create
+});
+```
+
+### Existing client
+
+```ts
+import sqlite3 from "sqlite3";
+import { sqlite3Adapter } from "@healthzkit/sqlite";
+
+const db = new sqlite3.Database(":memory:");
+
+const adapter = sqlite3Adapter({ client: db });
+```
+
+## `libsqlAdapter` (`@libsql/client`)
+
+**Peer:** `@libsql/client` ≥ 0.14.
+
+Runs `await client.execute(query)`. Use for [libSQL](https://github.com/tursodatabase/libsql) and [Turso](https://turso.tech/) (`libsql://`, `https://`, file URLs, etc.).
+
+### URL and token
+
+The adapter lazily imports `@libsql/client`, calls `createClient` once, and reuses the client across checks.
+
+```ts
+import { libsqlAdapter } from "@healthzkit/sqlite/libsql";
+
+const adapter = libsqlAdapter({
+  url: process.env.TURSO_DATABASE_URL!,
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+### Existing client
+
+```ts
+import { createClient } from "@libsql/client";
+import { libsqlAdapter } from "@healthzkit/sqlite";
+
+const client = createClient({ url: "file:local.db" });
+
+const adapter = libsqlAdapter({
+  client,
+  metadata: async () => ({ backend: "libsql" }),
+});
+```
+
+## Check result
+
+On success:
+
+```json
+{
+  "status": "ok",
+  "metadata": { "latencyMs": 2 }
+}
+```
+
+On failure, `status` is `"fail"` and `error` is set (see [healthzkit](https://github.com/alasti-company/healthzkit) for how that rolls up into probe responses).
+
+## Scheduling
+
+For databases that should not be queried on every probe, pair these adapters with a **`schedule`** on the check so readiness reads cached results. See the **Scheduling** section in the `healthzkit` README.
+
+## Development
+
+From the monorepo root:
+
+```bash
+vp install
+vp test --filter @healthzkit/sqlite
+vp pack --filter @healthzkit/sqlite
+```
+
+See the repo root `AGENTS.md` for Vite+ / `vp` conventions.

package/dist/better-sqlite3.d.mts

@@ -0,0 +1,19 @@
+import { n as HealthAdapter, t as BaseSqliteOptions } from "./shared-BIWNv8eR.mjs";
+import BetterSqlite3Constructor, { Database } from "better-sqlite3";
+
+//#region src/better-sqlite3.d.ts
+type BetterSqlite3OpenOptions = NonNullable<ConstructorParameters<typeof BetterSqlite3Constructor>[1]>;
+interface BetterSqlite3AdapterOptionsWithClient extends BaseSqliteOptions<Database> {
+  client: Database;
+  connectionString?: never;
+  options?: never;
+}
+interface BetterSqlite3AdapterOptionsWithConnectionString extends BaseSqliteOptions<Database> {
+  connectionString: string;
+  options?: BetterSqlite3OpenOptions;
+  client?: never;
+}
+type BetterSqlite3AdapterOptions = BetterSqlite3AdapterOptionsWithClient | BetterSqlite3AdapterOptionsWithConnectionString;
+declare function betterSqlite3Adapter(options: BetterSqlite3AdapterOptions): HealthAdapter;
+//#endregion
+export { BetterSqlite3AdapterOptions, BetterSqlite3AdapterOptionsWithClient, BetterSqlite3AdapterOptionsWithConnectionString, betterSqlite3Adapter };

package/dist/better-sqlite3.mjs

@@ -0,0 +1 @@
+import{n as e,r as t}from"./shared-BpZLjEOH.mjs";function n(n){let r=null,i=null;async function a(){if(`connectionString`in n&&n.connectionString)return r||(i||=(async()=>{try{let{default:e}=await import(`better-sqlite3`),t=new e(n.connectionString,n.options);return r=t,t}finally{i=null}})(),i);if(`client`in n&&n.client!==void 0)return n.client;throw Error(`betterSqlite3Adapter: provide a non-empty connectionString or a client`)}return{async check(){try{let e=await a(),r=Date.now();e.prepare(n.query??`SELECT 1`).get();let i=Date.now()-r,o=n.metadata?n.metadata(e):void 0;return t(i,o instanceof Promise?await o:o)}catch(t){return e(t)}}}}export{n as betterSqlite3Adapter};

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { BetterSqlite3AdapterOptions, betterSqlite3Adapter } from "./better-sqlite3.mjs";
+import { Sqlite3AdapterOptions, sqlite3Adapter } from "./sqlite3.mjs";
+import { LibsqlAdapterOptions, libsqlAdapter } from "./libsql.mjs";
+export { type BetterSqlite3AdapterOptions, type LibsqlAdapterOptions, type Sqlite3AdapterOptions, betterSqlite3Adapter, libsqlAdapter, sqlite3Adapter };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{betterSqlite3Adapter as e}from"./better-sqlite3.mjs";import{sqlite3Adapter as t}from"./sqlite3.mjs";import{libsqlAdapter as n}from"./libsql.mjs";export{e as betterSqlite3Adapter,n as libsqlAdapter,t as sqlite3Adapter};

package/dist/libsql.d.mts

@@ -0,0 +1,18 @@
+import { n as HealthAdapter, t as BaseSqliteOptions } from "./shared-BIWNv8eR.mjs";
+import { Client } from "@libsql/client";
+
+//#region src/libsql.d.ts
+interface LibsqlAdapterOptionsWithClient extends BaseSqliteOptions<Client> {
+  client: Client;
+  url?: never;
+  authToken?: never;
+}
+interface LibsqlAdapterOptionsWithConnectionString extends BaseSqliteOptions<Client> {
+  url: string;
+  authToken?: string;
+  client?: never;
+}
+type LibsqlAdapterOptions = LibsqlAdapterOptionsWithClient | LibsqlAdapterOptionsWithConnectionString;
+declare function libsqlAdapter(options: LibsqlAdapterOptions): HealthAdapter;
+//#endregion
+export { LibsqlAdapterOptions, LibsqlAdapterOptionsWithClient, LibsqlAdapterOptionsWithConnectionString, libsqlAdapter };

package/dist/libsql.mjs

@@ -0,0 +1 @@
+import{n as e,r as t}from"./shared-BpZLjEOH.mjs";function n(n){let r=null,i=null;async function a(){if(`url`in n&&n.url)return r||(i||=(async()=>{try{let{createClient:e}=await import(`@libsql/client`),t=e({url:n.url,authToken:n.authToken});return r=t,t}finally{i=null}})(),i);if(`client`in n&&n.client!==void 0)return n.client;throw Error(`libsqlAdapter: provide a non-empty url or a client`)}return{async check(){try{let e=await a(),r=Date.now();await e.execute(n.query??`SELECT 1`);let i=Date.now()-r,o=n.metadata?n.metadata(e):void 0;return t(i,o instanceof Promise?await o:o)}catch(t){return e(t)}}}}export{n as libsqlAdapter};

package/dist/shared-BIWNv8eR.d.mts

@@ -0,0 +1,18 @@
+import { HealthAdapter } from "healthzkit";
+
+//#region src/shared.d.ts
+type MetadataFn<TClient> = (client: TClient) => Promise<Record<string, unknown>> | Record<string, unknown>;
+interface BaseSqliteOptions<TClient> {
+  /**
+   * Query to run as the healthcheck.
+   * @default "SELECT 1"
+   */
+  query?: string;
+  /**
+   * Optional function to populate metadata in the check result.
+   * Receives the resolved client so you can run additional queries.
+   */
+  metadata?: MetadataFn<TClient>;
+}
+//#endregion
+export { HealthAdapter as n, BaseSqliteOptions as t };

package/dist/shared-BpZLjEOH.mjs

@@ -0,0 +1 @@
+const e=`SELECT 1`;function t(e,t){return{status:`ok`,metadata:{...t,latencyMs:e}}}function n(e){return{status:`fail`,error:e instanceof Error?e:Error(String(e))}}export{n,t as r,e as t};

package/dist/sqlite3.d.mts

@@ -0,0 +1,18 @@
+import { n as HealthAdapter, t as BaseSqliteOptions } from "./shared-BIWNv8eR.mjs";
+import { Database } from "sqlite3";
+
+//#region src/sqlite3.d.ts
+interface Sqlite3AdapterOptionsWithClient extends BaseSqliteOptions<Database> {
+  client: Database;
+  connectionString?: never;
+  mode?: never;
+}
+interface Sqlite3AdapterOptionsWithConnectionString extends BaseSqliteOptions<Database> {
+  connectionString: string;
+  mode?: number;
+  client?: never;
+}
+type Sqlite3AdapterOptions = Sqlite3AdapterOptionsWithClient | Sqlite3AdapterOptionsWithConnectionString;
+declare function sqlite3Adapter(options: Sqlite3AdapterOptions): HealthAdapter;
+//#endregion
+export { Sqlite3AdapterOptions, Sqlite3AdapterOptionsWithClient, Sqlite3AdapterOptionsWithConnectionString, sqlite3Adapter };

package/dist/sqlite3.mjs

@@ -0,0 +1 @@
+import{n as e,r as t}from"./shared-BpZLjEOH.mjs";function n(n){let r=null,i=null;async function a(){if(`connectionString`in n&&n.connectionString)return r||(i||=(async()=>{try{let{default:e}=await import(`sqlite3`),t=await new Promise((t,r)=>{let i=n.mode??e.OPEN_READWRITE|e.OPEN_CREATE,a=new e.Database(n.connectionString,i,e=>{if(e){r(e);return}queueMicrotask(()=>t(a))})});return r=t,t}finally{i=null}})(),i);if(`client`in n&&n.client!==void 0)return n.client;throw Error(`sqlite3Adapter: provide a non-empty connectionString or a client`)}return{async check(){try{let e=await a(),r=Date.now();await new Promise((t,r)=>{e.get(n.query??`SELECT 1`,e=>{e?r(e):t()})});let i=Date.now()-r,o=n.metadata?n.metadata(e):void 0;return t(i,o instanceof Promise?await o:o)}catch(t){return e(t)}}}}export{n as sqlite3Adapter};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@healthzkit/sqlite",
+  "version": "0.0.1",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasti-company/healthzkit.dev",
+    "directory": "packages/sqlite"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./better-sqlite3": "./dist/better-sqlite3.mjs",
+    "./libsql": "./dist/libsql.mjs",
+    "./sqlite3": "./dist/sqlite3.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@libsql/client": "^0.17.3",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "better-sqlite3": "^12.10.0",
+    "bumpp": "^11.1.0",
+    "healthzkit": "workspace:*",
+    "sqlite3": "^6.0.1",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.1.20"
+  },
+  "peerDependencies": {
+    "@libsql/client": ">=0.14.0",
+    "better-sqlite3": ">=12.0.0",
+    "sqlite3": ">=5.0.0 || >=6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@libsql/client": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "sqlite3": {
+      "optional": true
+    }
+  }
+}