nanodb-orm 0.0.7 → 0.0.8

package/README.md

@@ -19,6 +19,11 @@ A lightweight ORM wrapper for Drizzle ORM with automatic migrations, schema intr
 npm install nanodb-orm
 ```
 
+## Monorepo
+
+This repo is managed as an npm workspace with core + plugin packages.
+See `PACKAGES.md` for layout and cross-package commands.
+
 > **Important:** All interactions should go through `nanodb-orm`.  
 > Use `nanodb-orm` exports for schema, queries, and utilities instead of importing from Drizzle directly.
 
@@ -28,6 +33,9 @@ Optional plugins:
 npm install @nanodb-orm/plugin-timestamps @nanodb-orm/plugin-soft-delete @nanodb-orm/plugin-logger
 ```
 
+> Plugin preview rule: multi-plugin mode requires `preview: { deterministicPluginOrdering: true }`.
+> Without this preview flag, `createDatabase()` accepts only one plugin.
+
 Preview features: embedded replicas (opt-in via config switch).
 
 ## CLI
@@ -207,7 +215,9 @@ const db = await createDatabase({
     autoMigrate: true,    // default: true
     dropTables: false,    // default: false
   },
-  plugins: [auditPlugin, validationPlugin], // optional
+  useSingletonConnection: false, // default: false
+  plugins: [auditPlugin], // optional
+  preview: { deterministicPluginOrdering: true }, // optional preview for multi-plugin mode
 });
 ```
 
@@ -223,6 +233,7 @@ await db.sync();           // Sync with Turso (if remote)
 await db.reset();          // Drop all, recreate, reseed
 await db.seed();           // Re-seed data
 await db.clearData();      // Delete all data (keep tables)
+await db.dispose();        // Release in-memory context and non-singleton client
 ```
 
 ### Schema Introspection (from `db.schema`)
@@ -364,14 +375,25 @@ import { queryLogger } from '@nanodb-orm/plugin-logger';
 
 const db = await createDatabase({
   tables: { users, posts },
-  plugins: [
-    timestamps(),                      // Auto createdAt/updatedAt
-    queryLogger({ level: 'info' }),    // SQL logging with timing
-    softDelete({ tables: ['posts'] }), // Soft delete for posts
-  ],
+  plugins: [timestamps()],
+});
+```
+
+To use multiple plugins, enable deterministic ordering preview:
+
+```typescript
+const db = await createDatabase({
+  tables: { users, posts },
+  plugins: [queryLogger(), softDelete(), timestamps()],
+  preview: { deterministicPluginOrdering: true },
 });
 ```
 
+Ordering rules in preview mode:
+- lower `plugin.order` runs first (default `0`)
+- ties are sorted by `plugin.name` (ascending)
+- final tie-breaker is declaration order in the `plugins` array
+
 | Package | Function | Description |
 |---------|----------|-------------|
 | `@nanodb-orm/plugin-timestamps` | `timestamps()` | Auto-add `createdAt` / `updatedAt` |
@@ -414,6 +436,7 @@ import { NanoPlugin } from 'nanodb-orm';
 
 const myPlugin: NanoPlugin = {
   name: 'my-plugin',
+  order: 0, // optional execution priority (lower runs earlier)
   
   // Lifecycle
   install: (db) => db,           // Modify db instance
@@ -471,18 +494,17 @@ const validationPlugin: NanoPlugin = {
   },
 };
 
-// Use plugins
+// Use a plugin (temporary one-plugin limit)
 const db = await createDatabase({
   tables,
-  plugins: [auditPlugin, slugPlugin, validationPlugin],
+  plugins: [auditPlugin],
 });
 
 // Hooks run automatically
-await db.insert(posts).values({ title: 'My Post' }); // slug auto-generated
-await db.insert(users).values({ email: 'invalid' }); // throws error
+await db.insert(posts).values({ title: 'My Post' });
 
 // Check loaded plugins
-db.plugins.list(); // ['audit', 'slug', 'validation']
+db.plugins.list(); // ['audit']
 ```
 
 ## Best Practices
@@ -720,7 +742,7 @@ Error output is clean and actionable:
 │ Column "email" does not exist
 │ Table: users
 │ Operation: seed
-│ Detail: Row data: {"name":"Alice","email":"alice@example.com"}
+│ Detail: Failed seed columns: name, email
 └────────────────────────────────────────────────
 ```
 

package/dist/core/connection.d.ts

@@ -7,7 +7,7 @@ export interface ConnectionOverride {
     databasePath?: string;
 }
 /**
- * Thread-safe singleton database connection manager.
+ * Database connection factory with optional singleton caching.
  * Supports both Turso (remote) and local SQLite databases.
  *
  * Environment variables:

package/dist/core/connection.js

@@ -5,7 +5,7 @@ const libsql_1 = require("drizzle-orm/libsql");
 const client_1 = require("@libsql/client");
 const config_1 = require("./config");
 /**
- * Thread-safe singleton database connection manager.
+ * Database connection factory with optional singleton caching.
  * Supports both Turso (remote) and local SQLite databases.
  *
  * Environment variables:

package/dist/init.d.ts

@@ -87,6 +87,8 @@ export type NanoDatabase<S extends Schema> = LibSQLDatabase<S> & {
     plugins: PluginUtils;
     /** Hook system */
     hooks: Hooks;
+    /** Release in-memory nanodb context state */
+    dispose: () => Promise<void>;
 };
 /**
  * Configuration for createDatabase().
@@ -99,8 +101,21 @@ export interface CreateDatabaseConfig<S extends Schema = Schema> extends SchemaD
         forceLocal?: boolean;
         databasePath?: string;
     };
+    /** Reuse process-wide singleton connection (default: false) */
+    useSingletonConnection?: boolean;
     /** Plugins to extend database functionality */
     plugins?: NanoPlugin[];
+    /** Preview features */
+    preview?: {
+        /** Enables preview-gated features such as replicated database mode */
+        enabled?: true;
+        /**
+         * Enable deterministic plugin ordering for multi-plugin setups.
+         * When enabled, plugins are sorted by `order` (asc), then `name` (asc),
+         * then declaration position as a final tiebreaker.
+         */
+        deterministicPluginOrdering?: boolean;
+    };
 }
 declare const HOOK_TYPES: readonly ["beforeInsert", "afterInsert", "beforeUpdate", "afterUpdate", "beforeDelete", "afterDelete", "beforeQuery", "afterQuery"];
 type HookType = typeof HOOK_TYPES[number];
@@ -140,5 +155,5 @@ export declare function createDatabase<S extends Schema>(config: CreateDatabaseC
  *
  * @internal
  */
-export declare function initializeDatabase<S extends Schema>(schemaData: SchemaData<S>): void;
+export declare function initializeDatabase<S extends Schema>(schemaData: SchemaData<S>, contextId?: string): void;
 //# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../init.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,MAAM,EAEN,UAAU,EACV,eAAe,EACf,UAAU,EAIV,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC;AAMxD;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;IAC/C,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAC5D,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;IAC/C,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAC5D,YAAY,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;IAC/C,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAC5D,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;IAC9C,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IAC3D,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/B,GAAG,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM;IAC3C,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,aAAa,CAAC;IAC3C,mCAAmC;IACnC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;IACxC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1C,4BAA4B;IAC5B,KAAK,EAAE,MAAM;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,YAAY,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IAC1F,wCAAwC;IACxC,aAAa,EAAE,MAAM,KAAK,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1C,+BAA+B;IAC/B,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,MAAM,EAAE,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,GAAG;IAC/D,mBAAmB;IACnB,WAAW,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;IACxC,iCAAiC;IACjC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,+BAA+B;IAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,uBAAuB;IACvB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,qBAAqB;IACrB,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,qCAAqC;IACrC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACvB,0BAA0B;IAC1B,UAAU,EAAE,cAAc,CAAC;IAC3B,wBAAwB;IACxB,OAAO,EAAE,WAAW,CAAC;IACrB,kBAAkB;IAClB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,UAAU,CAAC,CAAC,CAAC;IACpF,wDAAwD;IACxD,UAAU,CAAC,EAAE;QACX,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,+CAA+C;IAC/C,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;CACxB;AAMD,QAAA,MAAM,UAAU,qIAKN,CAAC;AAEX,KAAK,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AA8D1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,MAAM,EACnD,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAuM1B;AAaD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAuBpF"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../init.ts"],"names":[],"mappings":"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"}