@open-kingdom/shared-backend-data-access-database-setup 0.0.2-14 → 0.0.2-15

package/README.md

@@ -1,77 +1,117 @@
-# data-access-database-setup
+# `@open-kingdom/shared-backend-data-access-database-setup`
 
-This library provides a configurable database setup module for NestJS applications using Drizzle ORM with SQLite.
+A NestJS global dynamic module that opens a `better-sqlite3` connection, wraps it with Drizzle ORM, applies SQLite PRAGMAs, and provides the `BetterSQLite3Database` instance to the NestJS DI container under the `DB_TAG` injection token.
 
-## Features
+---
 
-- Dynamic module configuration for database setup
-- Configurable schema injection
-- SQLite database configuration with Drizzle ORM
-- Example schema implementation
+## Exports
 
-## Usage
+| Export                       | Kind        | Description                                                          |
+| ---------------------------- | ----------- | -------------------------------------------------------------------- |
+| `DatabaseSetupModule`        | `class`     | Global NestJS dynamic module. Use `.register(options)` to configure. |
+| `DatabaseSetupModuleOptions` | `interface` | Type-only export. Type of the argument accepted by `.register()`.    |
 
-### Basic Usage
+---
+
+## Type Definitions
+
+`DatabaseSetupModuleOptions` is a generic interface with a type parameter `TSchema extends Record<string, unknown>` (defaulting to `Record<string, unknown>`). It accepts the following properties:
+
+| Property   | Type                     | Required | Default     | Description                                                                                                                            |
+| ---------- | ------------------------ | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`   | `TSchema`                | Yes      | —           | Drizzle table definitions object. Pass all tables the application needs so relational queries resolve correctly.                       |
+| `filename` | `string`                 | No       | `'demo.db'` | Path to the SQLite database file. Relative paths resolve from the process working directory. The file is created if it does not exist. |
+| `pragmas`  | `Record<string, string>` | No       | `{}`        | SQLite PRAGMAs applied immediately after the connection opens. Each key/value pair is executed as `sqlite.pragma('key = value')`.      |
+
+The injection token is **not** exported from this package. It is `DB_TAG` from `@open-kingdom/shared-poly-util-constants`.
+
+---
+
+## Module Registration
+
+`DatabaseSetupModule` is declared `global: true`. Register it **once** in the root `AppModule`. All other modules throughout the application can inject the database without importing this module again.
 
 ```typescript
+// app.module.ts
 import { Module } from '@nestjs/common';
 import { DatabaseSetupModule } from '@open-kingdom/shared-backend-data-access-database-setup';
-import { mySchema } from './my-schema';
+import * as schema from '@open-kingdom/demo-scaffold-backend-feature-root-schema';
 
 @Module({
   imports: [
     DatabaseSetupModule.register({
-      schema: mySchema,
-      tag: 'MY_DB',
-      filename: 'my-app.db',
+      schema,
+      filename: process.env['DB_FILENAME'] ?? 'app.db',
+      pragmas: {
+        journal_mode: 'WAL',
+        foreign_keys: 'ON',
+      },
     }),
   ],
 })
 export class AppModule {}
 ```
 
-### Using the Example Schema
+---
 
-```typescript
-import { Module } from '@nestjs/common';
-import { DatabaseSetupModule, exampleSchema } from '@open-kingdom/shared-backend-data-access-database-setup';
+## Configuration Options
 
-@Module({
-  imports: [
-    DatabaseSetupModule.register({
-      schema: exampleSchema,
-    }),
-  ],
-})
-export class AppModule {}
-```
+| Option     | Type                                      | Default      | Description                                                                                                                                                                            |
+| ---------- | ----------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`   | `TSchema extends Record<string, unknown>` | — (required) | All Drizzle table definition objects the application needs. Pass the full merged schema so that relational queries (`db.query.*`) resolve correctly.                                   |
+| `filename` | `string`                                  | `'demo.db'`  | Path to the SQLite database file. Relative paths resolve from the process working directory. The file is created if it does not exist.                                                 |
+| `pragmas`  | `Record<string, string>`                  | `{}`         | SQLite PRAGMAs applied immediately after the connection opens. Each entry is executed as `sqlite.pragma('key = value')`. Common values: `{ journal_mode: 'WAL', foreign_keys: 'ON' }`. |
+
+---
 
-### Configuration Options
+## Module Behavior
 
-The `DatabaseSetupModule.register()` method accepts the following options:
+1. `DatabaseSetupModule.register(options)` returns a `DynamicModule` with `global: true`.
+2. The module factory opens (or creates) the SQLite file at `options.filename` using `better-sqlite3`.
+3. Each entry in `options.pragmas` is applied synchronously before any queries run.
+4. Drizzle ORM wraps the connection using the provided `options.schema`.
+5. The resulting `BetterSQLite3Database<TSchema>` is provided under the `DB_TAG` token and exported globally.
 
-- `schema`: **Required** - The database schema object containing table definitions
-- `tag`: **Optional** - Database connection tag (defaults to 'DB_DEV')
-- `filename`: **Optional** - SQLite database filename (defaults to 'demo.db')
+Migration execution is **not** performed automatically. Migrations are managed via `drizzle-kit` scripts in the application's `package.json`. The typical scripts are `db:generate` (runs `drizzle-kit generate`) and `db:migrate` (runs `drizzle-kit migrate`), both pointing to a `drizzle.config.ts` configuration file.
 
-## Schema Definition
+---
 
-Your schema should be defined using Drizzle ORM's table builders:
+## Injecting the Database
 
 ```typescript
-import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+import { Injectable, Inject } from '@nestjs/common';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import { DB_TAG } from '@open-kingdom/shared-poly-util-constants';
+import * as schema from '@open-kingdom/demo-scaffold-backend-feature-root-schema';
+
+@Injectable()
+export class MyService {
+  constructor(@Inject(DB_TAG) private db: BetterSQLite3Database<typeof schema>) {}
+
+  async findAll() {
+    return this.db.query.myTable.findMany();
+  }
+}
+```
 
-export const users = sqliteTable('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  username: text('username').notNull().unique(),
-  email: text('email').notNull().unique(),
-});
+---
 
-export const mySchema = {
-  users,
-};
-```
+## API Reference
+
+### `DatabaseSetupModule.register<TSchema>(options: DatabaseSetupModuleOptions<TSchema>): DynamicModule`
 
-## Running unit tests
+Static factory method returning a NestJS `DynamicModule`. Must be called in the `imports` array of a module decorator.
 
-Run `nx test data-access-database-setup` to execute the unit tests via [Jest](https://jestjs.io).
+**Provided token:** `DB_TAG` → `BetterSQLite3Database<TSchema>`
+
+**Global:** `true` — the provided token is visible to all modules in the application without further imports.
+
+**Throws at startup** if the SQLite file cannot be opened (permission denied, invalid directory, etc.).
+
+---
+
+## Testing
+
+```bash
+nx test @open-kingdom/shared-backend-data-access-database-setup
+```

package/dist/lib/data-access-database-setup.module.d.ts

@@ -2,6 +2,7 @@ import { DynamicModule } from '@nestjs/common';
 export interface DatabaseSetupModuleOptions<TSchema extends Record<string, unknown> = Record<string, unknown>> {
     filename?: string;
     schema: TSchema;
+    pragmas?: Record<string, string>;
 }
 export declare class DatabaseSetupModule {
     static register<TSchema extends Record<string, unknown>>(options: DatabaseSetupModuleOptions<TSchema>): DynamicModule;

package/dist/lib/data-access-database-setup.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-access-database-setup.module.d.ts","sourceRoot":"","sources":["../../src/lib/data-access-database-setup.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAKvD,MAAM,WAAW,0BAA0B,CACzC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBACa,mBAAmB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,OAAO,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC3C,aAAa;CAcjB"}
+{"version":3,"file":"data-access-database-setup.module.d.ts","sourceRoot":"","sources":["../../src/lib/data-access-database-setup.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAMvD,MAAM,WAAW,0BAA0B,CACzC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,qBACa,mBAAmB;IAC9B,MAAM,CAAC,QAAQ,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,OAAO,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC3C,aAAa;CAqBjB"}

package/dist/lib/data-access-database-setup.module.js

@@ -4,21 +4,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DatabaseSetupModule = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@nestjs/common");
-const nestjs_drizzle_better_sqlite3_1 = require("@knaadh/nestjs-drizzle-better-sqlite3");
+const better_sqlite3_1 = tslib_1.__importDefault(require("better-sqlite3"));
+const better_sqlite3_2 = require("drizzle-orm/better-sqlite3");
 const shared_poly_util_constants_1 = require("@open-kingdom/shared-poly-util-constants");
 let DatabaseSetupModule = DatabaseSetupModule_1 = class DatabaseSetupModule {
     static register(options) {
         return {
             module: DatabaseSetupModule_1,
-            imports: [
-                nestjs_drizzle_better_sqlite3_1.DrizzleBetterSQLiteModule.register({
-                    tag: shared_poly_util_constants_1.DB_TAG,
-                    sqlite3: {
-                        filename: options.filename || 'demo.db',
+            global: true,
+            providers: [
+                {
+                    provide: shared_poly_util_constants_1.DB_TAG,
+                    useFactory: () => {
+                        const sqlite = new better_sqlite3_1.default(options.filename || 'demo.db');
+                        for (const [key, value] of Object.entries(options.pragmas ?? {})) {
+                            sqlite.pragma(`${key} = ${value}`);
+                        }
+                        return (0, better_sqlite3_2.drizzle)(sqlite, { schema: options.schema });
                     },
-                    config: { schema: options.schema },
-                }),
+                },
             ],
+            exports: [shared_poly_util_constants_1.DB_TAG],
         };
     }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-kingdom/shared-backend-data-access-database-setup",
-  "version": "0.0.2-14",
+  "version": "0.0.2-15",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +23,7 @@
     }
   },
   "files": [
+    "README.md",
     "dist",
     "!**/*.tsbuildinfo"
   ],
@@ -35,8 +36,11 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@knaadh/nestjs-drizzle-better-sqlite3": "^1.2.0",
+    "@open-kingdom/shared-poly-util-constants": "0.0.2-15"
+  },
+  "peerDependencies": {
     "@nestjs/common": "^11.0.0",
-    "@open-kingdom/shared-poly-util-constants": "0.0.2-14"
+    "better-sqlite3": "^12.0.0",
+    "drizzle-orm": "^0.44.0"
   }
 }