@gesetz/sqlite-compat 3.0.0-rc.8

package/README.md

@@ -0,0 +1,65 @@
+# `@gesetz/sqlite-compat`
+
+Optional SQLite cache driver for **gesetz** on runtimes without a usable
+`node:sqlite` module — Node < 23.4, or Bun.
+
+## Why this is separate
+
+`@gesetz/core` must stay dependency-light, so it never depends on a native
+SQLite binding. It exposes a driver registry instead, and this package registers
+a `better-sqlite3`-backed implementation under the `sqlite` kind.
+
+## Install
+
+```bash
+pnpm add -D @gesetz/sqlite-compat
+```
+
+`better-sqlite3` is a dependency of this package, so this pulls the native
+module too. It is never a dependency of `@gesetz/core`.
+
+## Use
+
+Import it once from `gesetz.config.ts`. The import is the entire opt-in — it
+registers the driver as a side effect:
+
+```ts
+// gesetz.config.ts
+import '@gesetz/sqlite-compat';
+import { defineConfig } from 'gesetz';
+
+export default defineConfig({
+  rules: [
+    /* … */
+  ],
+});
+```
+
+That is the whole change — the default shared cache then works on this runtime.
+(To keep the cache somewhere specific instead, set
+`storage: { kind: 'sqlite', path: '…' }`.)
+
+`gesetz check` then uses `better-sqlite3` automatically whenever `node:sqlite`
+is unavailable. Driver selection is automatic and is **not** a user-facing
+setting: `storage` only says *whether* and *where* to cache.
+
+If `better-sqlite3` cannot be resolved, importing this module is a no-op and
+gesetz runs without a cache.
+
+## API
+
+```ts
+import { createBetterSqliteStore, registerBetterSqliteDriver } from '@gesetz/sqlite-compat';
+
+// Register explicitly instead of relying on the import side effect.
+registerBetterSqliteDriver(); // false when better-sqlite3 is not installed
+
+// Build a store directly.
+const store = await createBetterSqliteStore('/path/to/cache.db', { namespace: projectRoot });
+```
+
+- `createBetterSqliteStore(path, options?)` — throws with an actionable message
+  when `better-sqlite3` cannot be resolved. `options.ctor` and `options.load`
+  exist for tests.
+- `registerBetterSqliteDriver(load?)` — registers the driver and returns whether
+  it succeeded.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { CacheStore, SqliteLikeDatabase, SqliteStoreNamespaceOptions } from "@gesetz/core";
+
+//#region src/index.d.ts
+/**
+ * The subset of the `better-sqlite3` constructor we use. Declared structurally
+ * so this package typechecks without `@types/better-sqlite3` installed.
+ */
+interface BetterSqliteConstructor {
+  new (path: string): SqliteLikeDatabase;
+}
+/** Loads the raw `better-sqlite3` module export. Injectable for tests. */
+type BetterSqliteLoader = () => unknown | Promise<unknown>;
+interface CreateBetterSqliteStoreOptions extends SqliteStoreNamespaceOptions {
+  /** Use an already-resolved constructor instead of loading `better-sqlite3`. */
+  readonly ctor?: BetterSqliteConstructor | undefined;
+  /** Override the module loader. Intended for tests. */
+  readonly load?: BetterSqliteLoader | undefined;
+}
+/**
+ * Creates a cache store backed by `better-sqlite3`.
+ *
+ * Throws with an actionable message when `better-sqlite3` is not installed.
+ */
+declare function createBetterSqliteStore(path: string, options?: CreateBetterSqliteStoreOptions): Promise<CacheStore>;
+/**
+ * Registers the `better-sqlite3` driver with `@gesetz/core`.
+ * Returns false (and registers nothing) when `better-sqlite3` is unavailable.
+ */
+declare function registerBetterSqliteDriver(load?: BetterSqliteLoader): boolean;
+//#endregion
+export { BetterSqliteConstructor, BetterSqliteLoader, CreateBetterSqliteStoreOptions, createBetterSqliteStore, registerBetterSqliteDriver };

package/dist/index.js

@@ -0,0 +1,86 @@
+import { createRequire } from "node:module";
+import { createSqliteStoreFromDatabase, registerCacheDriver } from "@gesetz/core";
+//#region src/index.ts
+/**
+* `@gesetz/sqlite-compat` — optional SQLite cache driver for runtimes without a
+* usable `node:sqlite` module (Node < 23.4, or Bun).
+*
+* ## Why this is a separate package
+*
+* `@gesetz/core` must stay dependency-light, so it never depends on a native
+* SQLite binding. Instead it exposes a driver registry, and this package
+* registers a `better-sqlite3`-backed implementation under the `sqlite` kind.
+*
+* ## Usage
+*
+* Install `better-sqlite3` and this package, then import it once from
+* `gesetz.config.ts` — the registration is the entire opt-in:
+*
+* ```ts
+* // gesetz.config.ts
+* import '@gesetz/sqlite-compat';
+* import { defineConfig } from 'gesetz';
+*
+* export default defineConfig({
+*   storage: { kind: 'sqlite', path: '.gesetz/cache.db' },
+*   rules: [/* … *\/],
+* });
+* ```
+*
+* `gesetz check` will then use `better-sqlite3` automatically when
+* `node:sqlite` is unavailable. To force it even where `node:sqlite` exists,
+* set `storage: { kind: 'sqlite', path, driver: 'compat' }`.
+*
+* If `better-sqlite3` cannot be resolved, importing this module is a no-op and
+* gesetz falls back to the JSON cache.
+*/
+const SQLITE_MODULE = "better-sqlite3";
+/** Accepts either `module.exports = Ctor` or `{ default: Ctor }`. */
+function resolveConstructor(module) {
+	if (typeof module === "function") return module;
+	if (module !== null && typeof module === "object") {
+		const candidate = module.default;
+		if (typeof candidate === "function") return candidate;
+	}
+	return null;
+}
+let cachedConstructor;
+function loadConstructor() {
+	cachedConstructor ??= (() => {
+		try {
+			return resolveConstructor(createRequire(import.meta.url)(SQLITE_MODULE));
+		} catch {
+			return null;
+		}
+	})();
+	return cachedConstructor;
+}
+/**
+* Creates a cache store backed by `better-sqlite3`.
+*
+* Throws with an actionable message when `better-sqlite3` is not installed.
+*/
+async function createBetterSqliteStore(path, options = {}) {
+	const ctor = options.ctor ?? (options.load !== void 0 ? resolveConstructor(await options.load()) : loadConstructor());
+	if (ctor === null) throw new Error(`gesetz: ${SQLITE_MODULE} is not installed, so @gesetz/sqlite-compat cannot back the cache. Install it with: pnpm add -D ${SQLITE_MODULE}`);
+	return createSqliteStoreFromDatabase(new ctor(path), {
+		namespace: options.namespace,
+		ttlMs: options.ttlMs
+	});
+}
+/**
+* Registers the `better-sqlite3` driver with `@gesetz/core`.
+* Returns false (and registers nothing) when `better-sqlite3` is unavailable.
+*/
+function registerBetterSqliteDriver(load = () => loadConstructor()) {
+	const resolved = resolveConstructor(load());
+	if (resolved === null) return false;
+	registerCacheDriver("sqlite", (path, options) => createBetterSqliteStore(path, {
+		ctor: resolved,
+		...options ?? {}
+	}));
+	return true;
+}
+registerBetterSqliteDriver();
+//#endregion
+export { createBetterSqliteStore, registerBetterSqliteDriver };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@gesetz/sqlite-compat",
+  "version": "3.0.0-rc.8",
+  "description": "Optional better-sqlite3 cache driver for gesetz on runtimes without node:sqlite",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "better-sqlite3": "^13.0.0",
+    "@gesetz/core": "3.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.0.0"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown"
+  }
+}