ras-stack 0.9.0 → 0.10.0

package/README.md

@@ -16,6 +16,7 @@ The package contains independent helpers for common application infrastructure:
 - **Server requests:** same-origin mutation guards, error-normalizing RPC wrappers, canonical-host redirects, and health responses.
 - **Realtime:** Centrifugo client lifecycle, token signing, presence synchronization, and a bounded publisher with retries and graceful shutdown.
 - **Email:** SMTP environment parsing and a small Nodemailer delivery interface.
+- **Database:** standard Better SQLite lifecycle and Drizzle migration mechanics that preserve the native typed database.
 - **Uploads:** a promise-based wrapper around resumable `tus-js-client` uploads.
 - **Project configuration:** shared TypeScript and Oxlint bases.
 
@@ -35,12 +36,13 @@ The libraries underneath remain available normally. Applications still configure
 pnpm add ras-stack
 ```
 
-Nodemailer, Centrifuge, and `tus-js-client` are optional peer dependencies. Install one only when using its integration:
+Nodemailer, Centrifuge, Better SQLite/Drizzle, and `tus-js-client` are optional peer dependencies. Install them only when using their integrations:
 
 ```sh
 pnpm add nodemailer
 pnpm add centrifuge
 pnpm add tus-js-client
+pnpm add better-sqlite3 drizzle-orm
 ```
 
 ## Authentication and request security
@@ -88,6 +90,27 @@ Applications still own their auth clients, authorization, routes, router, loggin
 
 Only enable `trustForwardedHeaders` behind a proxy that replaces incoming forwarded headers. Otherwise a client could choose the origin used by the check.
 
+## Database lifecycle
+
+The SQLite entrypoint owns the native client lifecycle, standard safety PRAGMAs, and optional Drizzle migrations while returning the upstream typed database:
+
+```ts
+import { bundledDirectory } from 'ras-stack/database'
+import { openDrizzleSqlite } from 'ras-stack/database/sqlite'
+
+const database = openDrizzleSqlite({
+  file,
+  schema,
+  migrationsFolder: bundledDirectory({
+    developmentUrl: new URL('../../drizzle', import.meta.url),
+    production: import.meta.env.PROD,
+    name: 'drizzle',
+  }),
+})
+```
+
+Applications retain their schema, migrations, database path, repositories, transactions, and driver selection. Dual-database applications can use `openSqliteClient()` and `configureSqlite()` beneath their own wrapper without forcing PostgreSQL through a shared database interface.
+
 ## Realtime updates
 
 Applications choose their channel names, authorize subscriptions, and define payloads. `ras-stack` handles Centrifugo's HTTP publication, signed tokens, and repeated browser lifecycle mechanics:
@@ -236,14 +259,14 @@ The JavaScript setup action reads the Node version from `engines.node` and the p
 ```yaml
 steps:
   - uses: actions/checkout@v7
-  - uses: richardsolomou/ras-stack/actions/setup-js@v0.3.0
+  - uses: richardsolomou/ras-stack/actions/setup-js@v0.9.0
   - run: pnpm check
 ```
 
 Just is independent of the application language and is installed separately when a repository uses it:
 
 ```yaml
-- uses: richardsolomou/ras-stack/actions/setup-just@v0.2.0
+- uses: richardsolomou/ras-stack/actions/setup-just@v0.9.0
   with:
     version: '1.58.0'
 ```
@@ -256,7 +279,7 @@ release:
   needs: [check]
   permissions:
     contents: write
-  uses: richardsolomou/ras-stack/.github/workflows/release-changesets.yml@v0.3.0
+  uses: richardsolomou/ras-stack/.github/workflows/release-changesets.yml@v0.9.0
   secrets: inherit
 ```
 

package/dist/database/index.d.ts

@@ -0,0 +1,8 @@
+import { type URL } from 'node:url';
+export type BundledDirectoryOptions = {
+    developmentUrl: URL;
+    production: boolean;
+    productionEntry?: string;
+    name: string;
+};
+export declare function bundledDirectory(options: BundledDirectoryOptions): string;

package/dist/database/index.js

@@ -0,0 +1,11 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function bundledDirectory(options) {
+    if (!options.production)
+        return fileURLToPath(options.developmentUrl);
+    const entry = options.productionEntry ?? process.argv[1];
+    if (!entry)
+        throw new Error('production entrypoint is required to resolve a bundled directory');
+    return path.join(path.dirname(entry), options.name);
+}
+//# sourceMappingURL=index.js.map

package/dist/database/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/database/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAY,MAAM,UAAU,CAAA;AASlD,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,IAAI,CAAC,OAAO,CAAC,UAAU;QAAE,OAAO,aAAa,CAAC,OAAO,CAAC,cAAc,CAAC,CAAA;IACrE,MAAM,KAAK,GAAG,OAAO,CAAC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACxD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;IAC/F,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;AACrD,CAAC","sourcesContent":["import path from 'node:path'\nimport { fileURLToPath, type URL } from 'node:url'\n\nexport type BundledDirectoryOptions = {\n  developmentUrl: URL\n  production: boolean\n  productionEntry?: string\n  name: string\n}\n\nexport function bundledDirectory(options: BundledDirectoryOptions) {\n  if (!options.production) return fileURLToPath(options.developmentUrl)\n  const entry = options.productionEntry ?? process.argv[1]\n  if (!entry) throw new Error('production entrypoint is required to resolve a bundled directory')\n  return path.join(path.dirname(entry), options.name)\n}\n"]}

package/dist/database/sqlite.d.ts

@@ -0,0 +1,25 @@
+import Database from 'better-sqlite3';
+import { type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+export type SqlitePragmas = {
+    journalMode?: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+    busyTimeout?: number;
+    foreignKeys?: boolean;
+};
+export type OpenSqliteOptions = {
+    database?: Database.Options;
+    pragmas?: SqlitePragmas | false;
+};
+export declare function openSqliteClient(file: string, options?: OpenSqliteOptions): Database.Database;
+export declare function configureSqlite(client: Database.Database, pragmas?: SqlitePragmas): Database.Database;
+export type OpenDrizzleSqliteOptions<TSchema extends Record<string, unknown>> = OpenSqliteOptions & {
+    file: string;
+    schema: TSchema;
+    migrationsFolder?: string;
+};
+export declare function openDrizzleSqlite<TSchema extends Record<string, unknown>>(options: OpenDrizzleSqliteOptions<TSchema>): BetterSQLite3Database<TSchema> & {
+    $client: Database.Database;
+};
+export declare function closeDrizzleSqlite(database: {
+    $client: Database.Database;
+}): void;

package/dist/database/sqlite.js

@@ -0,0 +1,49 @@
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+export function openSqliteClient(file, options = {}) {
+    if (file !== ':memory:')
+        mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+    const client = new Database(file, options.database);
+    try {
+        if (options.pragmas !== false)
+            configureSqlite(client, options.pragmas);
+        return client;
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
+}
+export function configureSqlite(client, pragmas = {}) {
+    const journalMode = pragmas.journalMode ?? 'WAL';
+    const synchronous = pragmas.synchronous ?? 'FULL';
+    const busyTimeout = pragmas.busyTimeout ?? 5000;
+    const foreignKeys = pragmas.foreignKeys ?? true;
+    if (!Number.isInteger(busyTimeout) || busyTimeout < 0)
+        throw new Error('busyTimeout must be a non-negative integer');
+    client.pragma(`journal_mode = ${journalMode}`);
+    client.pragma(`synchronous = ${synchronous}`);
+    client.pragma(`busy_timeout = ${busyTimeout}`);
+    client.pragma(`foreign_keys = ${foreignKeys ? 'ON' : 'OFF'}`);
+    return client;
+}
+export function openDrizzleSqlite(options) {
+    const client = openSqliteClient(options.file, options);
+    try {
+        const database = drizzle({ client, schema: options.schema });
+        if (options.migrationsFolder)
+            migrate(database, { migrationsFolder: options.migrationsFolder });
+        return database;
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
+}
+export function closeDrizzleSqlite(database) {
+    database.$client.close();
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/database/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/database/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAA;AACrC,OAAO,EAAE,OAAO,EAA8B,MAAM,4BAA4B,CAAA;AAChF,OAAO,EAAE,OAAO,EAAE,MAAM,qCAAqC,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,IAAI,MAAM,WAAW,CAAA;AAc5B,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAO,GAAsB,EAAE;IAC5E,IAAI,IAAI,KAAK,UAAU;QAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACzF,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnD,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;YAAE,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;QACvE,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAyB,EAAE,OAAO,GAAkB,EAAE;IACpF,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,KAAK,CAAA;IAChD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAA;IACjD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAA;IAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAA;IAC/C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IACpH,MAAM,CAAC,MAAM,CAAC,kBAAkB,WAAW,EAAE,CAAC,CAAA;IAC9C,MAAM,CAAC,MAAM,CAAC,iBAAiB,WAAW,EAAE,CAAC,CAAA;IAC7C,MAAM,CAAC,MAAM,CAAC,kBAAkB,WAAW,EAAE,CAAC,CAAA;IAC9C,MAAM,CAAC,MAAM,CAAC,kBAAkB,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;IAC7D,OAAO,MAAM,CAAA;AACf,CAAC;AAQD,MAAM,UAAU,iBAAiB,CAC/B,OAA0C;IAE1C,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACtD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QAC5D,IAAI,OAAO,CAAC,gBAAgB;YAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;QAC/F,OAAO,QAAQ,CAAA;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,QAAwC;IACzE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;AAC1B,CAAC","sourcesContent":["import Database from 'better-sqlite3'\nimport { drizzle, type BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'\nimport { migrate } from 'drizzle-orm/better-sqlite3/migrator'\nimport { mkdirSync } from 'node:fs'\nimport path from 'node:path'\n\nexport type SqlitePragmas = {\n  journalMode?: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF'\n  synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA'\n  busyTimeout?: number\n  foreignKeys?: boolean\n}\n\nexport type OpenSqliteOptions = {\n  database?: Database.Options\n  pragmas?: SqlitePragmas | false\n}\n\nexport function openSqliteClient(file: string, options: OpenSqliteOptions = {}): Database.Database {\n  if (file !== ':memory:') mkdirSync(path.dirname(path.resolve(file)), { recursive: true })\n  const client = new Database(file, options.database)\n  try {\n    if (options.pragmas !== false) configureSqlite(client, options.pragmas)\n    return client\n  } catch (error) {\n    client.close()\n    throw error\n  }\n}\n\nexport function configureSqlite(client: Database.Database, pragmas: SqlitePragmas = {}): Database.Database {\n  const journalMode = pragmas.journalMode ?? 'WAL'\n  const synchronous = pragmas.synchronous ?? 'FULL'\n  const busyTimeout = pragmas.busyTimeout ?? 5000\n  const foreignKeys = pragmas.foreignKeys ?? true\n  if (!Number.isInteger(busyTimeout) || busyTimeout < 0) throw new Error('busyTimeout must be a non-negative integer')\n  client.pragma(`journal_mode = ${journalMode}`)\n  client.pragma(`synchronous = ${synchronous}`)\n  client.pragma(`busy_timeout = ${busyTimeout}`)\n  client.pragma(`foreign_keys = ${foreignKeys ? 'ON' : 'OFF'}`)\n  return client\n}\n\nexport type OpenDrizzleSqliteOptions<TSchema extends Record<string, unknown>> = OpenSqliteOptions & {\n  file: string\n  schema: TSchema\n  migrationsFolder?: string\n}\n\nexport function openDrizzleSqlite<TSchema extends Record<string, unknown>>(\n  options: OpenDrizzleSqliteOptions<TSchema>,\n): BetterSQLite3Database<TSchema> & { $client: Database.Database } {\n  const client = openSqliteClient(options.file, options)\n  try {\n    const database = drizzle({ client, schema: options.schema })\n    if (options.migrationsFolder) migrate(database, { migrationsFolder: options.migrationsFolder })\n    return database\n  } catch (error) {\n    client.close()\n    throw error\n  }\n}\n\nexport function closeDrizzleSqlite(database: { $client: Database.Database }) {\n  database.$client.close()\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Composable full-stack primitives shared across Richard Solomou's applications.",
   "keywords": [
     "authentication",
@@ -34,6 +34,14 @@
       "types": "./dist/email/index.d.ts",
       "default": "./dist/email/index.js"
     },
+    "./database": {
+      "types": "./dist/database/index.d.ts",
+      "default": "./dist/database/index.js"
+    },
+    "./database/sqlite": {
+      "types": "./dist/database/sqlite.d.ts",
+      "default": "./dist/database/sqlite.js"
+    },
     "./policy": {
       "types": "./dist/policy/index.d.ts",
       "default": "./dist/policy/index.js"
@@ -94,9 +102,12 @@
     "@changesets/cli": "^2.31.1",
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-start": "^1.168.32",
+    "@types/better-sqlite3": "9.6.0",
     "@types/node": "^26.0.0",
     "@types/nodemailer": "^8.0.1",
+    "better-sqlite3": "12.11.1",
     "centrifuge": "5.7.0",
+    "drizzle-orm": "0.45.2",
     "nodemailer": "^9.0.3",
     "oxfmt": "^0.61.0",
     "oxlint": "^1.74.0",
@@ -109,7 +120,9 @@
   "peerDependencies": {
     "@tanstack/react-query": ">=5 <6",
     "@tanstack/react-start": ">=1 <2",
+    "better-sqlite3": ">=12 <13",
     "centrifuge": ">=5 <6",
+    "drizzle-orm": ">=0.45 <1",
     "nodemailer": ">=9 <10",
     "tus-js-client": ">=4 <5"
   },
@@ -120,9 +133,15 @@
     "@tanstack/react-start": {
       "optional": true
     },
+    "better-sqlite3": {
+      "optional": true
+    },
     "centrifuge": {
       "optional": true
     },
+    "drizzle-orm": {
+      "optional": true
+    },
     "nodemailer": {
       "optional": true
     },