@fluojs/drizzle 1.1.0 → 2.0.0

package/dist/database.js

@@ -5,19 +5,23 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { createAbortError, createRequestAbortContext, raceWithAbort, trackActiveRequestTransaction, untrackActiveRequestTransaction } from '@fluojs/runtime';
 import { Inject } from '@fluojs/core';
-import { DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_OPTIONS } from './tokens.js';
+import { createAbortError, createRequestAbortContext, raceWithAbort, trackActiveRequestTransaction, untrackActiveRequestTransaction } from '@fluojs/runtime';
 import { createDrizzlePlatformStatusSnapshot } from './status.js';
+import { DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_OPTIONS } from './tokens.js';
 const TRANSACTION_NOT_SUPPORTED_ERROR = 'Transaction not supported: Drizzle database does not implement transaction.';
 const NESTED_TRANSACTION_OPTIONS_NOT_SUPPORTED_ERROR = 'Nested Drizzle transaction options are not supported because the active transaction context is reused.';
 const TRANSACTION_UNAVAILABLE_ERROR = 'Drizzle transactions are not available during application shutdown.';
 const REQUEST_TRANSACTION_UNAVAILABLE_ERROR = 'Drizzle request transactions are not available during shutdown.';
 function createCurrentlessDrizzleFacade(target) {
   return new Proxy(target, {
-    get(database, prop, receiver) {
+    get(database, prop) {
       if (prop in database) {
-        return Reflect.get(database, prop, receiver);
+        const value = Reflect.get(database, prop, database);
+        if (typeof value === 'function') {
+          return value.bind(database);
+        }
+        return value;
       }
       const currentDatabase = database.current();
       const value = Reflect.get(currentDatabase, prop, currentDatabase);
@@ -92,7 +96,8 @@ class DrizzleDatabase {
    * @remarks
    * This compatibility helper is used by `DrizzleModule` provider wiring. Application code should prefer
    * `DrizzleModule.forRoot(...)` or `DrizzleModule.forRootAsync(...)`, then type injected repository handles as
-   * `DrizzleDatabaseFacade<TDatabase>` when direct Drizzle methods are needed.
+   * `DrizzleDatabaseFacade<TDatabase>` when direct Drizzle methods are needed. Wrapper and lifecycle methods remain
+   * bound to the lifecycle owner while unknown Drizzle query properties forward to the ambient `current()` handle.
    *
    * @param database Root Drizzle database handle registered in the module.
    * @param dispose Optional shutdown hook used to close pools or driver resources.
@@ -116,7 +121,11 @@ class DrizzleDatabase {
    * @returns The transaction-scoped database inside an active boundary, or the root database outside one.
    */
   current() {
-    return this.transactions.getStore()?.database ?? this.database;
+    const current = this.transactions.getStore();
+    if (!current || current.transactionBoundaryOwner.closed) {
+      return this.database;
+    }
+    return current.database;
   }
 
   /** Aborts active request transactions, waits for settlement, then runs the optional dispose hook. */
@@ -180,67 +189,162 @@ class DrizzleDatabase {
   async executeTransaction(fn, options, requestScoped, signal) {
     const current = this.transactions.getStore();
     if (current) {
+      if (current.transactionBoundaryOwner.closed) {
+        if (requestScoped) {
+          return this.executeInheritedRequestTransaction(current, fn, options, signal);
+        }
+        return this.executeManualRootTransaction(fn, options);
+      }
+      if (!requestScoped) {
+        return this.executeNestedManualTransaction(current.transactionBoundaryOwner, fn, options);
+      }
       if (requestScoped) {
         this.assertRequestTransactionsAvailable();
       } else {
         this.assertTransactionsAvailable();
       }
-      if (options !== undefined) {
-        throw new Error(NESTED_TRANSACTION_OPTIONS_NOT_SUPPORTED_ERROR);
-      }
       if (requestScoped) {
         return this.executeNestedRequestTransaction(current, fn, signal);
       }
-      return fn();
     }
     if (!requestScoped) {
-      this.assertTransactionsAvailable();
+      return this.executeManualRootTransaction(fn, options);
     }
-    const transactionRunner = this.resolveTransactionRunner();
-    if (!transactionRunner) {
-      if (requestScoped) {
-        return this.executeRequestFallback(fn, signal);
+    return this.executeRequestRootTransaction(fn, options, signal);
+  }
+  async executeManualRootTransaction(fn, options) {
+    const deferredRequestTransactionSettlements = new Set();
+    const fallbackTransactionOwner = {
+      closed: false,
+      callbackSettlements: new Set(),
+      requestTransactionSettlements: new Set()
+    };
+    const activeTransactionScope = this.trackAvailableTransactionScope();
+    try {
+      const transactionRunner = this.resolveTransactionRunner();
+      if (!transactionRunner) {
+        try {
+          return await this.transactions.run({
+            database: this.database,
+            fallbackTransactionOwner,
+            transactionBoundaryOwner: fallbackTransactionOwner
+          }, fn);
+        } finally {
+          await this.closeTransactionBoundaryOwner(fallbackTransactionOwner);
+        }
       }
-      return fn();
-    }
-    if (!requestScoped) {
-      const deferredRequestTransactionSettlements = new Set();
-      const activeTransactionScope = this.trackActiveTransactionScope();
-      try {
-        return await transactionRunner(transactionDatabase => this.transactions.run({
-          database: transactionDatabase,
-          deferredRequestTransactionSettlements
-        }, fn), options);
-      } finally {
-        for (const handle of deferredRequestTransactionSettlements) {
-          this.untrackActiveRequestTransaction(handle);
+      return await transactionRunner(async transactionDatabase => {
+        try {
+          return await this.transactions.run({
+            database: transactionDatabase,
+            deferredRequestTransactionSettlements,
+            transactionBoundaryOwner: fallbackTransactionOwner
+          }, fn);
+        } finally {
+          await this.closeTransactionBoundaryOwner(fallbackTransactionOwner);
         }
-        activeTransactionScope.settle();
+      }, options);
+    } finally {
+      await this.closeTransactionBoundaryOwner(fallbackTransactionOwner);
+      for (const handle of fallbackTransactionOwner.requestTransactionSettlements) {
+        this.untrackActiveRequestTransaction(handle);
       }
+      for (const handle of deferredRequestTransactionSettlements) {
+        this.untrackActiveRequestTransaction(handle);
+      }
+      activeTransactionScope.settle();
     }
-    return this.executeRequestTransaction(transactionRunner, fn, options, signal);
   }
   async executeRequestTransaction(transactionRunner, fn, options, signal) {
     this.assertRequestTransactionsAvailable();
     const abortContext = createRequestAbortContext(signal);
     const active = this.trackActiveRequestTransaction(abortContext.controller);
+    const transactionBoundaryOwner = {
+      closed: false,
+      callbackSettlements: new Set(),
+      requestTransactionSettlements: new Set()
+    };
     try {
-      const result = await transactionRunner(transactionDatabase => this.transactions.run({
-        database: transactionDatabase,
-        requestAbortSignal: abortContext.signal
-      }, () => raceWithAbort(fn, abortContext.signal)), options);
+      const result = await transactionRunner(async transactionDatabase => {
+        try {
+          return await this.transactions.run({
+            database: transactionDatabase,
+            inheritedRequestAbortSignal: signal ?? abortContext.signal,
+            requestAbortSignal: abortContext.signal,
+            transactionBoundaryOwner
+          }, () => raceWithAbort(fn, abortContext.signal));
+        } finally {
+          await this.closeTransactionBoundaryOwner(transactionBoundaryOwner);
+        }
+      }, options);
       this.throwIfRequestAborted(abortContext.signal);
       return result;
     } finally {
+      transactionBoundaryOwner.closed = true;
       abortContext.cleanup();
       this.untrackActiveRequestTransaction(active);
     }
   }
+  async executeRequestRootTransaction(fn, options, signal) {
+    const transactionRunner = this.resolveTransactionRunner();
+    if (!transactionRunner) {
+      return this.executeRequestFallback(fn, signal);
+    }
+    return this.executeRequestTransaction(transactionRunner, fn, options, signal);
+  }
+  async executeInheritedRequestTransaction(current, fn, options, signal) {
+    const inheritedRequestAbortSignal = current.inheritedRequestAbortSignal ?? current.requestAbortSignal;
+    if (!inheritedRequestAbortSignal) {
+      return this.executeRequestRootTransaction(fn, options, signal);
+    }
+    const abortSignalView = createRequestAbortSignalView(inheritedRequestAbortSignal, signal);
+    try {
+      this.throwIfRequestAborted(abortSignalView.signal);
+      return await this.executeRequestRootTransaction(fn, options, abortSignalView.signal);
+    } finally {
+      abortSignalView.cleanup();
+    }
+  }
+  async executeNestedManualTransaction(owner, fn, options) {
+    this.assertTransactionsAvailable();
+    if (options !== undefined) {
+      throw new Error(NESTED_TRANSACTION_OPTIONS_NOT_SUPPORTED_ERROR);
+    }
+    const callback = Promise.resolve().then(fn);
+    const removeSettlement = () => {
+      owner.callbackSettlements.delete(settlement);
+    };
+    const settlement = callback.then(removeSettlement, removeSettlement);
+    owner.callbackSettlements.add(settlement);
+    return callback;
+  }
   async executeNestedRequestTransaction(current, fn, signal) {
+    const fallbackTransactionOwner = current.fallbackTransactionOwner;
+    if (fallbackTransactionOwner?.closed) {
+      if (current.requestAbortSignal) {
+        const abortSignalView = createRequestAbortSignalView(current.requestAbortSignal, signal);
+        try {
+          return await this.executeRequestFallback(fn, abortSignalView.signal);
+        } finally {
+          abortSignalView.cleanup();
+        }
+      }
+      return this.executeRequestFallback(fn, signal);
+    }
+    const runCallback = () => {
+      const callback = fn();
+      const transactionBoundaryOwner = current.transactionBoundaryOwner;
+      const removeSettlement = () => {
+        transactionBoundaryOwner.callbackSettlements.delete(settlement);
+      };
+      const settlement = callback.then(removeSettlement, removeSettlement);
+      transactionBoundaryOwner.callbackSettlements.add(settlement);
+      return callback;
+    };
     if (current.requestAbortSignal) {
       const abortSignalView = createRequestAbortSignalView(current.requestAbortSignal, signal);
       try {
-        const result = await raceWithAbort(fn, abortSignalView.signal);
+        const result = await raceWithAbort(runCallback, abortSignalView.signal);
         this.throwIfRequestAborted(abortSignalView.signal);
         return result;
       } finally {
@@ -250,17 +354,27 @@ class DrizzleDatabase {
     this.assertRequestTransactionsAvailable();
     const abortContext = createRequestAbortContext(signal);
     const active = this.trackActiveRequestTransaction(abortContext.controller);
-    current.deferredRequestTransactionSettlements?.add(active);
+    let ownerDefersSettlement = false;
+    if (fallbackTransactionOwner) {
+      fallbackTransactionOwner.requestTransactionSettlements.add(active);
+      ownerDefersSettlement = true;
+    } else if (current.deferredRequestTransactionSettlements) {
+      current.deferredRequestTransactionSettlements.add(active);
+      ownerDefersSettlement = true;
+    }
     try {
       const result = await this.transactions.run({
         database: current.database,
-        requestAbortSignal: abortContext.signal
-      }, () => raceWithAbort(fn, abortContext.signal));
+        fallbackTransactionOwner,
+        inheritedRequestAbortSignal: current.inheritedRequestAbortSignal,
+        requestAbortSignal: abortContext.signal,
+        transactionBoundaryOwner: current.transactionBoundaryOwner
+      }, () => raceWithAbort(runCallback, abortContext.signal));
       this.throwIfRequestAborted(abortContext.signal);
       return result;
     } finally {
       abortContext.cleanup();
-      if (current.deferredRequestTransactionSettlements) {
+      if (ownerDefersSettlement) {
         this.markRequestTransactionInactiveForStatus(active);
       } else {
         this.untrackActiveRequestTransaction(active);
@@ -270,16 +384,46 @@ class DrizzleDatabase {
   async executeRequestFallback(fn, signal) {
     this.assertRequestTransactionsAvailable();
     const abortContext = createRequestAbortContext(signal);
+    if (abortContext.signal.aborted) {
+      const abortError = createAbortError(abortContext.signal.reason);
+      abortContext.cleanup();
+      throw abortError;
+    }
     const active = this.trackActiveRequestTransaction(abortContext.controller);
+    const fallbackTransactionOwner = {
+      closed: false,
+      callbackSettlements: new Set(),
+      requestTransactionSettlements: new Set()
+    };
     try {
-      const result = await raceWithAbort(fn, abortContext.signal);
+      const result = await raceWithAbort(() => {
+        const callback = new Promise(resolve => resolve(this.transactions.run({
+          database: this.database,
+          fallbackTransactionOwner,
+          inheritedRequestAbortSignal: signal ?? abortContext.signal,
+          requestAbortSignal: abortContext.signal,
+          transactionBoundaryOwner: fallbackTransactionOwner
+        }, fn)));
+        return callback.finally(async () => {
+          await this.closeTransactionBoundaryOwner(fallbackTransactionOwner);
+          for (const handle of fallbackTransactionOwner.requestTransactionSettlements) {
+            this.untrackActiveRequestTransaction(handle);
+          }
+          this.untrackActiveRequestTransaction(active);
+        });
+      }, abortContext.signal);
       this.throwIfRequestAborted(abortContext.signal);
       return result;
     } finally {
       abortContext.cleanup();
-      this.untrackActiveRequestTransaction(active);
     }
   }
+  async closeTransactionBoundaryOwner(owner) {
+    while (owner.callbackSettlements.size > 0) {
+      await Promise.all(owner.callbackSettlements);
+    }
+    owner.closed = true;
+  }
   assertRequestTransactionsAvailable() {
     if (this.lifecycleState !== 'ready') {
       throw new Error(REQUEST_TRANSACTION_UNAVAILABLE_ERROR);
@@ -328,6 +472,10 @@ class DrizzleDatabase {
       }
     };
   }
+  trackAvailableTransactionScope() {
+    this.assertTransactionsAvailable();
+    return this.trackActiveTransactionScope();
+  }
   resolveTransactionRunner() {
     if (typeof this.database.transaction !== 'function') {
       if (this.databaseOptions.strictTransactions) {

package/dist/module.d.ts

@@ -1,15 +1,31 @@
 import type { AsyncModuleOptions } from '@fluojs/core';
-import { type ModuleType } from '@fluojs/runtime';
+import type { ModuleType } from '@fluojs/runtime';
 import type { DrizzleDatabaseLike, DrizzleModuleOptions } from './types.js';
-type DrizzleAsyncModuleOptions<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase, TTransactionOptions> = AsyncModuleOptions<Omit<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>, 'global'>> & Pick<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>, 'global'>;
+/**
+ * Configures an async Drizzle module registration through an injected factory.
+ *
+ * @typeParam TDatabase Root Drizzle database handle registered in the module.
+ * @typeParam TTransactionDatabase Transaction-scoped database handle resolved inside transaction callbacks.
+ * @typeParam TTransactionOptions Options forwarded to the underlying Drizzle transaction runner.
+ */
+export type DrizzleAsyncModuleOptions<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase, TTransactionOptions> = AsyncModuleOptions<Omit<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>, 'global' | 'name'>> & Pick<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>, 'global' | 'name'>;
 /**
  * Module entrypoint for wiring a Drizzle database into the Fluo runtime lifecycle.
  */
 export declare class DrizzleModule {
-    /** Creates a module definition from static Drizzle options. */
+    /**
+     * Creates a module definition from static Drizzle options.
+     *
+     * @param options Static Drizzle registration options.
+     * @returns A runtime module definition for the requested Drizzle registration.
+     */
     static forRoot<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>): ModuleType;
-    /** Creates a module definition from DI-aware async Drizzle options. */
+    /**
+     * Creates a module definition from DI-aware async Drizzle options.
+     *
+     * @param options Async Drizzle registration options.
+     * @returns A runtime module definition for the requested Drizzle registration.
+     */
     static forRootAsync<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: DrizzleAsyncModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>): ModuleType;
 }
-export {};
 //# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAc5E,KAAK,yBAAyB,CAC5B,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,EACpB,mBAAmB,IACjB,kBAAkB,CAAC,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,QAAQ,CAAC,CAAC,GAChH,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,QAAQ,CAAC,CAAC;AAgI7F;;GAEG;AACH,qBAAa,aAAa;IACxB,+DAA+D;IAC/D,MAAM,CAAC,OAAO,CACZ,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAC7B,OAAO,EAAE,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GAAG,UAAU;IAIlG,uEAAuE;IACvE,MAAM,CAAC,YAAY,CACjB,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAC7B,OAAO,EAAE,yBAAyB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GAAG,UAAU;CAGxG"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,CACnC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,EACpB,mBAAmB,IACjB,kBAAkB,CAAC,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,CAAC,GACzH,IAAI,CAAC,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,CAAC;AAEtG;;GAEG;AACH,qBAAa,aAAa;IACxB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CACZ,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAC7B,OAAO,EAAE,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GAAG,UAAU;IAIlG;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CACjB,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAC7B,OAAO,EAAE,yBAAyB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GAAG,UAAU;CAGxG"}

package/dist/module.js

@@ -1,89 +1,33 @@
-import { defineModule } from '@fluojs/runtime';
-import { DrizzleDatabase } from './database.js';
-import { DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_HANDLE_PROVIDER, DRIZZLE_OPTIONS } from './tokens.js';
-const DRIZZLE_NORMALIZED_OPTIONS = Symbol('fluo.drizzle.normalized-options');
-const DRIZZLE_MODULE_EXPORTS = [DrizzleDatabase, DRIZZLE_HANDLE_PROVIDER];
-function isObjectLike(value) {
-  return typeof value === 'object' && value !== null || typeof value === 'function';
-}
-function normalizeDrizzleModuleOptions(options) {
-  if (!isObjectLike(options.database)) {
-    throw new Error('DrizzleModule requires a database option.');
-  }
-  return {
-    ...options,
-    strictTransactions: options.strictTransactions ?? false
-  };
-}
-function createRuntimeOptionsProviderValue(strictTransactions) {
-  return {
-    strictTransactions
-  };
-}
-function createDrizzleRuntimeProviders(normalizedOptionsProvider) {
-  return [normalizedOptionsProvider, {
-    inject: [DRIZZLE_NORMALIZED_OPTIONS],
-    provide: DRIZZLE_DATABASE,
-    useFactory: options => options.database
-  }, {
-    inject: [DRIZZLE_NORMALIZED_OPTIONS],
-    provide: DRIZZLE_DISPOSE,
-    useFactory: options => options.dispose
-  }, {
-    inject: [DRIZZLE_NORMALIZED_OPTIONS],
-    provide: DRIZZLE_OPTIONS,
-    useFactory: options => createRuntimeOptionsProviderValue(options.strictTransactions)
-  }, {
-    inject: [DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_OPTIONS],
-    provide: DrizzleDatabase,
-    useFactory: (database, dispose, databaseOptions) => DrizzleDatabase.createFacade(database, dispose, databaseOptions)
-  }, {
-    provide: DRIZZLE_HANDLE_PROVIDER,
-    useExisting: DrizzleDatabase
-  }];
-}
-function createDrizzleProvidersAsync(options) {
-  const normalizedOptionsProvider = {
-    inject: options.inject,
-    provide: DRIZZLE_NORMALIZED_OPTIONS,
-    scope: 'singleton',
-    useFactory: async (...deps) => normalizeDrizzleModuleOptions({
-      ...(await options.useFactory(...deps)),
-      global: options.global
-    })
-  };
-  return createDrizzleRuntimeProviders(normalizedOptionsProvider);
-}
-function buildDrizzleModule(options) {
-  class DrizzleRootModuleDefinition {}
-  return defineModule(DrizzleRootModuleDefinition, {
-    exports: DRIZZLE_MODULE_EXPORTS,
-    global: options.global ?? false,
-    providers: createDrizzleRuntimeProviders({
-      provide: DRIZZLE_NORMALIZED_OPTIONS,
-      useValue: normalizeDrizzleModuleOptions(options)
-    })
-  });
-}
-function buildDrizzleModuleAsync(options) {
-  class DrizzleAsyncModuleDefinition {}
-  return defineModule(DrizzleAsyncModuleDefinition, {
-    exports: DRIZZLE_MODULE_EXPORTS,
-    global: options.global ?? false,
-    providers: createDrizzleProvidersAsync(options)
-  });
-}
+import { buildDrizzleModule, buildDrizzleModuleAsync } from './named-registration.js';
+
+/**
+ * Configures an async Drizzle module registration through an injected factory.
+ *
+ * @typeParam TDatabase Root Drizzle database handle registered in the module.
+ * @typeParam TTransactionDatabase Transaction-scoped database handle resolved inside transaction callbacks.
+ * @typeParam TTransactionOptions Options forwarded to the underlying Drizzle transaction runner.
+ */
 
 /**
  * Module entrypoint for wiring a Drizzle database into the Fluo runtime lifecycle.
  */
 export class DrizzleModule {
-  /** Creates a module definition from static Drizzle options. */
+  /**
+   * Creates a module definition from static Drizzle options.
+   *
+   * @param options Static Drizzle registration options.
+   * @returns A runtime module definition for the requested Drizzle registration.
+   */
   static forRoot(options) {
     return buildDrizzleModule(options);
   }
 
-  /** Creates a module definition from DI-aware async Drizzle options. */
+  /**
+   * Creates a module definition from DI-aware async Drizzle options.
+   *
+   * @param options Async Drizzle registration options.
+   * @returns A runtime module definition for the requested Drizzle registration.
+   */
   static forRootAsync(options) {
     return buildDrizzleModuleAsync(options);
   }

package/dist/named-registration.d.ts

@@ -0,0 +1,20 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { DrizzleAsyncModuleOptions } from './module.js';
+import type { DrizzleDatabaseLike, DrizzleModuleOptions } from './types.js';
+/**
+ * Builds a synchronous Drizzle runtime module definition.
+ *
+ * @internal
+ * @param options Static Drizzle registration options.
+ * @returns A module definition for the default or named registration.
+ */
+export declare function buildDrizzleModule<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>): ModuleType;
+/**
+ * Builds an asynchronous Drizzle runtime module definition.
+ *
+ * @internal
+ * @param options Async Drizzle registration options.
+ * @returns A module definition for the default or named registration.
+ */
+export declare function buildDrizzleModuleAsync<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: DrizzleAsyncModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>): ModuleType;
+//# sourceMappingURL=named-registration.d.ts.map

package/dist/named-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-registration.d.ts","sourceRoot":"","sources":["../src/named-registration.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGhE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAmB7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAmF5E;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAC7B,OAAO,EAAE,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GAAG,UAAU,CAajG;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAC7B,OAAO,EAAE,yBAAyB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GAAG,UAAU,CAUtG"}

package/dist/named-registration.js

@@ -0,0 +1,84 @@
+import { defineModule } from '@fluojs/runtime';
+import { DrizzleDatabase } from './database.js';
+import { createDrizzleRuntimeProviders, getNormalizedOptionsToken, getRegistrationGuardToken } from './registration-providers.js';
+import { normalizeDrizzleRegistrationName } from './registration-name.js';
+import { DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_HANDLE_PROVIDER, DRIZZLE_OPTIONS, getDrizzleDatabaseToken, getDrizzleDisposeToken, getDrizzleHandleProviderToken, getDrizzleOptionsToken } from './tokens.js';
+import { DrizzleTransactionInterceptor } from './transaction.js';
+const DRIZZLE_MODULE_EXPORTS = [DrizzleDatabase, DrizzleTransactionInterceptor, DRIZZLE_HANDLE_PROVIDER, DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_OPTIONS];
+function isObjectLike(value) {
+  return typeof value === 'object' && value !== null || typeof value === 'function';
+}
+function assertNamedRegistrationIsScoped(name, global) {
+  if (name !== undefined && global) {
+    throw new Error('Named Drizzle registrations are scoped and cannot be registered globally.');
+  }
+}
+function normalizeDrizzleModuleOptions(options) {
+  if (!isObjectLike(options.database)) {
+    throw new Error('DrizzleModule requires a database option.');
+  }
+  const name = normalizeDrizzleRegistrationName(options.name);
+  assertNamedRegistrationIsScoped(name, options.global);
+  return {
+    ...options,
+    global: name === undefined ? options.global : false,
+    name,
+    strictTransactions: options.strictTransactions ?? false
+  };
+}
+function createDrizzleProvidersAsync(options, name) {
+  const registrationGuardToken = name === undefined ? undefined : getRegistrationGuardToken(name);
+  const normalizedOptionsProvider = {
+    inject: registrationGuardToken === undefined ? options.inject : [registrationGuardToken, ...(options.inject ?? [])],
+    provide: getNormalizedOptionsToken(name),
+    scope: 'singleton',
+    useFactory: async (...dependencies) => normalizeDrizzleModuleOptions({
+      ...(await options.useFactory(...(registrationGuardToken === undefined ? dependencies : dependencies.slice(1)))),
+      global: options.global,
+      name
+    })
+  };
+  return createDrizzleRuntimeProviders(normalizedOptionsProvider, name);
+}
+function getDrizzleModuleExports(name) {
+  return name === undefined ? DRIZZLE_MODULE_EXPORTS : [getDrizzleDatabaseToken(name), getDrizzleDisposeToken(name), getDrizzleHandleProviderToken(name), getDrizzleOptionsToken(name)];
+}
+
+/**
+ * Builds a synchronous Drizzle runtime module definition.
+ *
+ * @internal
+ * @param options Static Drizzle registration options.
+ * @returns A module definition for the default or named registration.
+ */
+export function buildDrizzleModule(options) {
+  const normalizedOptions = normalizeDrizzleModuleOptions(options);
+  const name = normalizedOptions.name;
+  class DrizzleRootModuleDefinition {}
+  return defineModule(DrizzleRootModuleDefinition, {
+    exports: getDrizzleModuleExports(name),
+    global: normalizedOptions.global ?? false,
+    providers: createDrizzleRuntimeProviders({
+      provide: getNormalizedOptionsToken(name),
+      useValue: normalizedOptions
+    }, name)
+  });
+}
+
+/**
+ * Builds an asynchronous Drizzle runtime module definition.
+ *
+ * @internal
+ * @param options Async Drizzle registration options.
+ * @returns A module definition for the default or named registration.
+ */
+export function buildDrizzleModuleAsync(options) {
+  const name = normalizeDrizzleRegistrationName(options.name);
+  assertNamedRegistrationIsScoped(name, options.global);
+  class DrizzleAsyncModuleDefinition {}
+  return defineModule(DrizzleAsyncModuleDefinition, {
+    exports: getDrizzleModuleExports(name),
+    global: name === undefined ? options.global ?? false : false,
+    providers: createDrizzleProvidersAsync(options, name)
+  });
+}

package/dist/registration-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalizes a public Drizzle registration name before it becomes part of a DI token.
+ *
+ * @internal
+ * @param name Optional registration name supplied by a module or token helper.
+ * @returns The trimmed registration name, or `undefined` for the default registration.
+ */
+export declare function normalizeDrizzleRegistrationName(name?: string): string | undefined;
+//# sourceMappingURL=registration-name.d.ts.map

package/dist/registration-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-name.d.ts","sourceRoot":"","sources":["../src/registration-name.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYlF"}

package/dist/registration-name.js

@@ -0,0 +1,17 @@
+/**
+ * Normalizes a public Drizzle registration name before it becomes part of a DI token.
+ *
+ * @internal
+ * @param name Optional registration name supplied by a module or token helper.
+ * @returns The trimmed registration name, or `undefined` for the default registration.
+ */
+export function normalizeDrizzleRegistrationName(name) {
+  if (name === undefined) {
+    return undefined;
+  }
+  const normalizedName = name.trim();
+  if (normalizedName.length === 0) {
+    throw new Error('DrizzleModule name must be a non-empty string when provided.');
+  }
+  return normalizedName;
+}