@fluojs/drizzle 1.0.1 → 1.1.0

package/README.ko.md

@@ -2,17 +2,18 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-트랜잭션 인지형 데이터베이스 래퍼와 선택적 dispose hook을 제공하는 fluo용 Drizzle ORM 통합 패키지입니다.
+Node.js 전용 트랜잭션 인지형 데이터베이스 래퍼와 선택적 dispose hook을 제공하는 fluo용 Drizzle ORM 통합 패키지입니다.
 
 ## 목차
 
 - [설치](#설치)
+- [런타임 지원](#런타임-지원)
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
-  - [repository에서 `DrizzleDatabase.current()` 사용하기](#repository에서-drizzledatabasecurrent-사용하기)
-  - [수동 트랜잭션 경계](#수동-트랜잭션-경계)
-  - [인터셉터 기반 요청 단위 트랜잭션](#인터셉터-기반-요청-단위-트랜잭션)
+  - [서비스 트랜잭션 경계 (@Transaction)](#서비스-트랜잭션-경계-transaction)
+  - [수동 트랜잭션과 current()](#수동-트랜잭션과-current)
+  - [요청 전체 컨트롤러 경계](#요청-전체-컨트롤러-경계)
   - [종료와 상태 계약](#종료와-상태-계약)
 - [수동 모듈 구성](#수동-모듈-구성)
 - [공개 API 개요](#공개-api-개요)
@@ -27,9 +28,17 @@ npm install @fluojs/drizzle drizzle-orm
 npm install pg
 ```
 
+## 런타임 지원
+
+루트 `@fluojs/drizzle` 패키지는 현재 Node.js 20+ 통합입니다. ambient transaction context를 유지하기 위해 Node의 `node:async_hooks` 모듈을 import하고, package manifest는 `engines.node >=20.0.0`을 선언합니다.
+
+Drizzle ORM 자체는 Bun SQL이나 Cloudflare D1 같은 driver도 대상으로 할 수 있지만, 비 Node transaction-context adapter가 문서화되기 전까지 해당 driver runtime은 이 fluo wrapper 범위 밖입니다.
+
+비 Node 런타임에서는 루트 패키지를 import하지 마세요. Bun, Deno, Cloudflare Workers 또는 다른 비 Node Drizzle driver에서는 raw Drizzle driver handle을 `{ provide, useFactory }`나 `{ provide, useValue }` 같은 애플리케이션 소유 fluo provider 뒤에 등록하고, repository에는 해당 애플리케이션 토큰을 주입하세요. Canonical package chooser/surface 문서와 Bun/Cloudflare book 장에서 이런 raw-provider 패턴을 보여 줍니다.
+
 ## 사용 시점
 
-- Drizzle을 다른 fluo 모듈과 같은 DI·모듈·라이프사이클 모델 안에 넣고 싶을 때
+- Node.js 20+ 애플리케이션에서 Drizzle을 다른 fluo 모듈과 같은 DI·모듈·라이프사이클 모델 안에 넣고 싶을 때
 - repository 코드가 root handle과 현재 트랜잭션 handle 사이를 `current()` 하나로 다루고 싶을 때
 - 애플리케이션 종료 시 underlying driver 정리 로직도 함께 실행해야 할 때
 
@@ -66,49 +75,118 @@ export class AppModule {}
 
 ## 주요 패턴
 
-### repository에서 `DrizzleDatabase.current()` 사용하기
+### 서비스 트랜잭션 경계 (@Transaction)
+
+`@Transaction()` 데코레이터는 서비스 레이어에서 트랜잭션 경계를 정의하는 권장 방법입니다. 이 데코레이터가 적용된 메서드 내부에서 발생하는 모든 리포지토리 호출은 동일한 Drizzle 트랜잭션을 공유합니다.
+
+```ts
+import { Transaction, DrizzleDatabase, type DrizzleDatabaseFacade } from '@fluojs/drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { users, profiles } from './schema';
+
+type AppDatabase = ReturnType<typeof drizzle>;
+
+export class UserService {
+  constructor(private readonly repo: UserRepository) {}
+
+  @Transaction()
+  async onboardUser(dto: any) {
+    const user = await this.repo.create(dto);
+    await this.repo.initProfile(user.id);
+    return user;
+  }
+}
+
+export class UserRepository {
+  constructor(private readonly db: DrizzleDatabaseFacade<AppDatabase>) {}
+
+  async create(data: any) {
+    // facade 타입은 표준 Drizzle 메서드를 노출합니다.
+    // @Transaction() 내부에서 호출되면 자동으로 활성 트랜잭션에 참여합니다.
+    return this.db.insert(users).values(data);
+  }
+
+  async initProfile(userId: string) {
+    return this.db.insert(profiles).values({ userId });
+  }
+}
+```
+
+`@Transaction()` 메서드 호출은 재진입(reentrant)이 가능합니다. 데코레이터가 적용된 메서드가 다른 데코레이터 적용 메서드를 호출하더라도 하나의 동일한 Drizzle 트랜잭션 안에서 실행됩니다.
+
+기본적으로 `@Transaction()`은 작은 host-object heuristic으로 대상을 고릅니다. 먼저 `this.db`를 확인하고, 그다음 데코레이터가 붙은 인스턴스의 직접 property, 마지막으로 그 값들의 중첩 `.db` property 중 `transaction(...)` 메서드를 노출하는 첫 값을 사용합니다. 이 덕분에 `constructor(private readonly db: DrizzleDatabase<...>)` 같은 일반 서비스는 간결하게 유지할 수 있지만, 하나의 서비스가 Drizzle wrapper를 둘 이상 소유한다면 property 순서에 의존하지 마세요. 데코레이터가 붙은 host가 여러 transaction-capable client를 갖거나 `.db`를 노출하는 repository를 감싸는 경우에는 `@Transaction((self) => self.ordersDb)` 또는 `@Transaction((self) => self.analyticsDb, options)`처럼 명시적 accessor를 전달하세요.
+
+### 수동 트랜잭션과 current()
+
+`DrizzleDatabase`는 트랜잭션 범위 내에 있으면 자동으로 활성 트랜잭션 handle을, 그렇지 않으면 root handle을 반환하는 `current()` 메서드를 제공합니다. 외부 유틸리티에 handle을 전달하거나 복잡한 수동 트랜잭션 처리가 필요한 경우 escape hatch로 사용하세요.
 
 ```ts
 import { DrizzleDatabase } from '@fluojs/drizzle';
-import { eq } from 'drizzle-orm';
+import { drizzle } from 'drizzle-orm/node-postgres';
 import { users } from './schema';
 
-export class UserRepository {
-  constructor(private readonly db: DrizzleDatabase) {}
+type AppDatabase = ReturnType<typeof drizzle>;
 
-  async findById(id: string) {
-    return this.db.current().select().from(users).where(eq(users.id, id));
+export class AdvancedRepository {
+  constructor(private readonly db: DrizzleDatabase<AppDatabase>) {}
+
+  async customOperation() {
+    const tx = this.db.current();
+    // fluo가 자동으로 감싸지 않는 작업을 수행하거나,
+    // Drizzle handle을 직접 기대하는 외부 유틸리티에 전달할 때 tx를 사용하세요.
+    return tx.select().from(users);
   }
 }
 ```
 
-### 수동 트랜잭션 경계
+수동 트랜잭션 블록에는 `db.transaction()`을 사용하세요:
 
 ```ts
 await this.db.transaction(async () => {
-  const tx = this.db.current();
-  await tx.insert(users).values(user);
-  await tx.insert(profiles).values(profile);
+  const current = this.db.current();
+
+  await current.insert(users).values(user);
+  await current.insert(profiles).values(profile);
 });
 ```
 
 중첩 호출은 활성 transaction boundary를 재사용합니다. 이미 boundary가 활성화되어 있는데 중첩 호출이 transaction option을 전달하면, 기존 transaction을 조용히 바꾸지 않고 해당 중첩 option을 거부합니다.
 
-`database.transaction(...)`을 사용할 수 없고 `strictTransactions`가 `false`이면 `transaction()`과 `requestTransaction()`은 직접 실행으로 fallback합니다. 요청 범위 호출은 이 경우에도 `AbortSignal`을 존중합니다.
+`database.transaction(...)`을 사용할 수 없고 `strictTransactions`가 `false`(기본값)이면 `transaction()`과 `requestTransaction()`은 의도적으로 fail-open(fail-open fallback)하여 callback을 root handle에서 직접 실행합니다. 이는 local fake, read-only adapter, 점진적 migration에는 유용하지만 원자적이지 않으므로 실제 데이터베이스 transaction으로 취급하면 안 됩니다. rollback 보장이 필요한 production 경로에서는 `strictTransactions: true`를 설정하세요. 그러면 startup 및 readiness 진단에서 누락된 `database.transaction(...)` 지원을 드러내고, transaction helper는 트랜잭션 없이 조용히 실행하는 대신 예외를 던집니다. 요청 범위 fallback은 그래도 `AbortSignal`을 존중하므로, Drizzle transaction runner가 없어도 취소된 요청은 직접 실행 전이나 도중에 중단될 수 있습니다.
 
-### 인터셉터 기반 요청 단위 트랜잭션
+### 요청 전체 컨트롤러 경계
+
+비즈니스 작업에는 서비스 레벨 `@Transaction()`을 우선 사용하세요. 전체 요청을 하나의 transaction으로 감싸던 NestJS controller/interceptor 패턴을 마이그레이션해야 한다면 controller, route adapter, request orchestration 경계에서 `requestTransaction(...)`을 명시적으로 호출하고 가능한 경우 request `AbortSignal`을 전달하세요.
 
 ```ts
-import { UseInterceptors } from '@fluojs/http';
-import { DrizzleTransactionInterceptor } from '@fluojs/drizzle';
+import { Controller, Post } from '@fluojs/http';
+import { DrizzleDatabase } from '@fluojs/drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
 
-@UseInterceptors(DrizzleTransactionInterceptor)
-class UsersController {}
+type AppDatabase = ReturnType<typeof drizzle>;
+
+@Controller('/checkout')
+export class CheckoutController {
+  constructor(
+    private readonly db: DrizzleDatabase<AppDatabase>,
+    private readonly checkout: CheckoutService,
+  ) {}
+
+  @Post()
+  create(input: CheckoutInput, requestSignal?: AbortSignal) {
+    return this.db.requestTransaction(
+      () => this.checkout.createOrder(input),
+      requestSignal,
+    );
+  }
+}
 ```
 
+import할 수 있는 Drizzle `*TransactionInterceptor` export는 없습니다. 기존 NestJS interceptor 설계는 대부분의 transaction boundary를 서비스로 옮기고, 전체 request 작업이 서비스 메서드 하나가 아니라 같은 boundary를 공유해야 하는 드문 controller-level 호환성 사례에만 명시적 `requestTransaction(...)`을 남기세요.
+
 ### 종료와 상태 계약
 
-`DrizzleTransactionInterceptor`는 각 HTTP 요청을 `DrizzleDatabase.requestTransaction(...)`으로 실행합니다. 애플리케이션 종료 중에는 `DrizzleDatabase`가 아직 활성 상태인 요청 트랜잭션을 abort하고, 열린 요청 및 수동 transaction callback이 settle되거나 rollback될 때까지 기다린 뒤 선택적 `dispose(database)` hook을 실행합니다. 이 순서는 pool이나 외부 관리 리소스를 닫기 전에 driver가 commit/rollback/cleanup 작업을 끝낼 수 있게 보장합니다.
+애플리케이션 종료 중에는 `DrizzleDatabase`가 아직 활성 상태인 요청 트랜잭션을 abort하고, 열린 요청 및 수동 transaction callback이 settle되거나 rollback될 때까지 기다린 뒤 선택적 `dispose(database)` hook을 실행합니다. 이 순서는 pool이나 외부 관리 리소스를 닫기 전에 driver가 commit/rollback/cleanup 작업을 끝낼 수 있게 보장합니다.
 기존 요청 boundary 안에서 열린 중첩 `requestTransaction(...)` 호출은 활성 Drizzle transaction을 재사용하면서도 ambient request abort signal을 관찰합니다. 기존 수동 transaction boundary 안에서 열린 중첩 `requestTransaction(...)` 호출도 두 번째 Drizzle transaction을 열지 않고 shutdown settlement tracking에 참여하며, 해당 settlement handle은 바깥 수동 transaction이 settle될 때까지 tracking에 남아 shutdown이 `dispose(database)`를 실행하기 전에 그 바깥 경계까지 drain하게 합니다. 단, platform status activity count는 더 짧게 유지됩니다. 중첩 request callback이 settle되는 즉시, 바깥 수동 transaction이 계속 실행 중이어도 `details.activeRequestTransactions`는 감소합니다.
 종료가 시작된 뒤 새 `transaction(...)` 및 `requestTransaction(...)` 호출은 거부되므로, 종료 boundary를 지난 뒤 시작되는 늦은 트랜잭션보다 dispose가 먼저 실행되는 상황을 방지합니다.
 요청 callback이 완료된 뒤 underlying Drizzle transaction runner가 commit 또는 rollback을 끝내기 전에 request signal이 abort되면, `requestTransaction(...)`은 먼저 해당 runner가 settle될 때까지 기다린 다음 abort reason으로 reject합니다. 이 동작은 Drizzle cleanup을 request cancellation과 직렬화하면서, 완료된 callback 결과를 반환하는 대신 늦은 request abort를 caller에게 드러냅니다.
@@ -127,7 +205,7 @@ class UsersController {}
 
 ```ts
 import { defineModule } from '@fluojs/runtime';
-import { DrizzleDatabase, DrizzleModule, DrizzleTransactionInterceptor } from '@fluojs/drizzle';
+import { DrizzleModule } from '@fluojs/drizzle';
 
 const database = {
   transaction: async <T>(callback: (tx: typeof database) => Promise<T>) => callback(database),
@@ -136,7 +214,6 @@ const database = {
 class ManualDrizzleModule {}
 
 defineModule(ManualDrizzleModule, {
-  exports: [DrizzleDatabase, DrizzleTransactionInterceptor],
   imports: [DrizzleModule.forRoot({ database })],
 });
 ```
@@ -145,8 +222,10 @@ defineModule(ManualDrizzleModule, {
 
 - `DrizzleModule.forRoot(options)` / `DrizzleModule.forRootAsync(options)`
 - `DrizzleDatabase`
-- `DrizzleTransactionInterceptor`
+- `DrizzleDatabaseFacade<TDatabase>`
+- `Transaction`
 - `DRIZZLE_DATABASE`, `DRIZZLE_DISPOSE`, `DRIZZLE_HANDLE_PROVIDER`, `DRIZZLE_OPTIONS`
+- `DrizzleDatabase.createFacade(...)` (호환성 전용 provider wiring helper; 애플리케이션 등록은 `DrizzleModule.forRoot(...)` / `forRootAsync(...)`를 우선 사용)
 - `createDrizzlePlatformStatusSnapshot(...)`
 - `DrizzleDatabaseLike`
 - `DrizzleModuleOptions`
@@ -154,17 +233,22 @@ defineModule(ManualDrizzleModule, {
 
 `DRIZZLE_HANDLE_PROVIDER`는 lifecycle-aware `DrizzleDatabase` wrapper를 가리키는 alias token입니다. `@fluojs/terminus` 같은 health integration은 이 token을 통해 raw database ping으로 fallback하기 전에 `createPlatformStatusSnapshot()`을 읽습니다.
 
+provider가 `current()`, `transaction(...)`, `requestTransaction(...)`, `createPlatformStatusSnapshot()` 같은 wrapper 메서드만 필요로 하면 `DrizzleDatabase<TDatabase>`를 사용하세요. 리포지토리 주입에서 Drizzle query 메서드를 직접 호출해야 한다면 `DrizzleDatabaseFacade<TDatabase>`를 사용합니다. 이 facade는 활성 트랜잭션 handle이 있으면 그 handle로, 없으면 root handle로 호출을 전달합니다. `DrizzleDatabase.createFacade(...)`는 module provider wiring을 위한 low-level compatibility helper로 유지됩니다. 애플리케이션 코드는 `DrizzleModule.forRoot(...)` / `forRootAsync(...)`를 우선 사용하세요.
+
+`Transaction`은 서비스 계층 트랜잭션 경계를 위한 표준 TC39 method decorator입니다. 데코레이터가 붙은 host에서 `this.db`, 직접 property, 중첩 `.db` property 순서로 transaction-capable 대상을 resolve하고, 명시적 client 선택에는 accessor를 받을 수 있으며, 외부 경계에는 Drizzle transaction option을 전달할 수 있습니다.
+
 ### `DrizzleModule`
 
 - `DrizzleModule.forRoot(options)` / `DrizzleModule.forRootAsync(options)`
 - `forRootAsync(...)`는 database/dispose/transaction 설정을 factory에서 반환하는 DI-aware Drizzle 옵션을 받습니다. provider를 전역으로 노출해야 할 때는 최상위 async 등록 옵션에 `global`을 전달하세요.
 - `forRootAsync(...)`는 애플리케이션 container마다 옵션을 한 번 resolve합니다. 테스트나 multi-app process에서 같은 module definition을 재사용해도 memoized factory result를 공유하지 않고 각 container가 독립적인 database/dispose 결과를 받습니다.
 - `strictTransactions: true`를 설정하면 transaction 지원이 없는 database handle에서 예외를 던집니다.
+- sync 및 async 등록 모두에서 `database`는 실제 object/function handle이어야 하며, 누락된 handle은 모듈 등록 또는 async bootstrap 중 거부됩니다.
 
 ## 관련 패키지
 
 - `@fluojs/runtime`: 모듈 시작과 종료 순서를 관리합니다.
-- `@fluojs/http`: 요청 단위 트랜잭션에 쓰이는 인터셉터 파이프라인을 제공합니다.
+- `@fluojs/http`: 명시적 `requestTransaction(...)` 경계와 함께 사용할 수 있는 요청 라이프사이클 primitive를 제공합니다.
 - `@fluojs/prisma`, `@fluojs/mongoose`: 같은 런타임 모델 위에서 동작하는 다른 데이터 통합 패키지입니다.
 
 ## 예제 소스

package/README.md

@@ -2,18 +2,19 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-Drizzle ORM integration for fluo with a transaction-aware database wrapper and an optional dispose hook.
+Node.js-only Drizzle ORM integration for fluo with a transaction-aware database wrapper and an optional dispose hook.
 
 ## Table of Contents
 
 - [Installation](#installation)
+- [Runtime Support](#runtime-support)
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
-  - [Use `DrizzleDatabase.current()` inside repositories](#use-drizzledatabasecurrent-inside-repositories)
-  - [Manual transaction boundaries](#manual-transaction-boundaries)
-  - [Request-scoped transactions with an interceptor](#request-scoped-transactions-with-an-interceptor)
-  - [Shutdown and status contracts](#shutdown-and-status-contracts)
+  - [Service Transaction Boundary (@Transaction)](#service-transaction-boundary-transaction)
+  - [Manual Transactions and current()](#manual-transactions-and-current)
+  - [Request-Wide Controller Boundaries](#request-wide-controller-boundaries)
+  - [Shutdown and Status Contracts](#shutdown-and-status-contracts)
 - [Manual Module Composition](#manual-module-composition)
 - [Public API Overview](#public-api-overview)
 - [Related Packages](#related-packages)
@@ -27,9 +28,17 @@ npm install @fluojs/drizzle drizzle-orm
 npm install pg
 ```
 
+## Runtime Support
+
+The root `@fluojs/drizzle` package is currently a Node.js 20+ integration. It imports Node's `node:async_hooks` module to maintain the ambient transaction context and the package manifest declares `engines.node >=20.0.0`.
+
+Drizzle ORM itself can target drivers such as Bun SQL or Cloudflare D1, but those driver runtimes are outside this fluo wrapper until a non-Node transaction-context adapter is documented.
+
+Non-Node runtimes should not import the root package. For Bun, Deno, Cloudflare Workers, or other non-Node Drizzle drivers, register the raw Drizzle driver handle behind application-owned fluo providers such as `{ provide, useFactory }` or `{ provide, useValue }`, then inject that application token into repositories. The canonical package chooser/surface docs and the Bun/Cloudflare book chapters show those raw-provider patterns.
+
 ## When to Use
 
-- when Drizzle should participate in the same module, DI, and lifecycle model as the rest of the app
+- when a Node.js 20+ application needs Drizzle to participate in the same module, DI, and lifecycle model as the rest of the app
 - when repositories need a single `current()` seam that switches between the root handle and the active transaction handle
 - when application shutdown should also run an explicit cleanup hook for the underlying driver resources
 
@@ -66,49 +75,118 @@ export class AppModule {}
 
 ## Common Patterns
 
-### Use `DrizzleDatabase.current()` inside repositories
+### Service Transaction Boundary (@Transaction)
+
+The `@Transaction()` decorator is the recommended way to define transaction boundaries in your service layer. It ensures that all repository calls made within the decorated method share the same Drizzle transaction.
+
+```ts
+import { Transaction, DrizzleDatabase, type DrizzleDatabaseFacade } from '@fluojs/drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { users, profiles } from './schema';
+
+type AppDatabase = ReturnType<typeof drizzle>;
+
+export class UserService {
+  constructor(private readonly repo: UserRepository) {}
+
+  @Transaction()
+  async onboardUser(dto: any) {
+    const user = await this.repo.create(dto);
+    await this.repo.initProfile(user.id);
+    return user;
+  }
+}
+
+export class UserRepository {
+  constructor(private readonly db: DrizzleDatabaseFacade<AppDatabase>) {}
+
+  async create(data: any) {
+    // The facade type exposes standard Drizzle methods.
+    // When called inside @Transaction(), they automatically participate in the ambient transaction.
+    return this.db.insert(users).values(data);
+  }
+
+  async initProfile(userId: string) {
+    return this.db.insert(profiles).values({ userId });
+  }
+}
+```
+
+Calls to `@Transaction()` methods are reentrant. If a decorated method calls another decorated method, they share the same underlying Drizzle transaction.
+
+By default, `@Transaction()` selects its target with a small host-object heuristic: it first checks `this.db`, then direct properties on the decorated instance, then a nested `.db` property on those values, and uses the first value that exposes a `transaction(...)` method. This keeps common `constructor(private readonly db: DrizzleDatabase<...>)` services concise, but services with more than one Drizzle wrapper should not rely on property order. Pass an explicit accessor such as `@Transaction((self) => self.ordersDb)` or `@Transaction((self) => self.analyticsDb, options)` whenever the decorated host owns multiple transaction-capable clients or wraps a repository that also exposes `.db`.
+
+### Manual Transactions and current()
+
+The `DrizzleDatabase` provides a `current()` method that returns the active transaction handle if inside a transaction scope, or the root handle otherwise. Use this as an escape hatch when you need to pass the handle to external utilities or perform advanced manual transaction plumbing.
 
 ```ts
 import { DrizzleDatabase } from '@fluojs/drizzle';
-import { eq } from 'drizzle-orm';
+import { drizzle } from 'drizzle-orm/node-postgres';
 import { users } from './schema';
 
-export class UserRepository {
-  constructor(private readonly db: DrizzleDatabase) {}
+type AppDatabase = ReturnType<typeof drizzle>;
 
-  async findById(id: string) {
-    return this.db.current().select().from(users).where(eq(users.id, id));
+export class AdvancedRepository {
+  constructor(private readonly db: DrizzleDatabase<AppDatabase>) {}
+
+  async customOperation() {
+    const tx = this.db.current();
+    // Use tx for operations that fluo doesn't automatically wrap,
+    // or when passing to an external utility that expects a Drizzle database handle.
+    return tx.select().from(users);
   }
 }
 ```
 
-### Manual transaction boundaries
+Use `db.transaction()` for manual transaction blocks:
 
 ```ts
 await this.db.transaction(async () => {
-  const tx = this.db.current();
-  await tx.insert(users).values(user);
-  await tx.insert(profiles).values(profile);
+  const current = this.db.current();
+
+  await current.insert(users).values(user);
+  await current.insert(profiles).values(profile);
 });
 ```
 
 Nested calls reuse the active transaction boundary. If a nested call passes transaction options while a boundary is already active, the package rejects those nested options instead of silently changing the existing transaction.
 
-When `database.transaction(...)` is unavailable and `strictTransactions` is `false`, `transaction()` and `requestTransaction()` fall back to direct execution; request-scoped calls still honor `AbortSignal`.
+When `database.transaction(...)` is unavailable and `strictTransactions` is `false` (the default), `transaction()` and `requestTransaction()` intentionally fail open (fail-open fallback) by running the callback directly against the root handle. This is useful for local fakes, read-only adapters, or gradual migrations, but it is not atomic and should not be treated as a real database transaction. Set `strictTransactions: true` in production paths that require rollback guarantees; startup and readiness diagnostics then surface missing `database.transaction(...)` support and transaction helpers throw instead of silently running without a transaction. Request-scoped fallback still honors `AbortSignal`, so a cancelled request can stop before or during direct execution even though no Drizzle transaction runner exists.
 
-### Request-scoped transactions with an interceptor
+### Request-Wide Controller Boundaries
+
+Prefer service-level `@Transaction()` for business operations. If you are migrating a NestJS controller/interceptor pattern where an entire request must be transactional, call `requestTransaction(...)` explicitly at the controller, route adapter, or request orchestration boundary and pass the request `AbortSignal` when one is available:
 
 ```ts
-import { UseInterceptors } from '@fluojs/http';
-import { DrizzleTransactionInterceptor } from '@fluojs/drizzle';
+import { Controller, Post } from '@fluojs/http';
+import { DrizzleDatabase } from '@fluojs/drizzle';
+import { drizzle } from 'drizzle-orm/node-postgres';
 
-@UseInterceptors(DrizzleTransactionInterceptor)
-class UsersController {}
+type AppDatabase = ReturnType<typeof drizzle>;
+
+@Controller('/checkout')
+export class CheckoutController {
+  constructor(
+    private readonly db: DrizzleDatabase<AppDatabase>,
+    private readonly checkout: CheckoutService,
+  ) {}
+
+  @Post()
+  create(input: CheckoutInput, requestSignal?: AbortSignal) {
+    return this.db.requestTransaction(
+      () => this.checkout.createOrder(input),
+      requestSignal,
+    );
+  }
+}
 ```
 
+There is no Drizzle `*TransactionInterceptor` export to import. Existing NestJS interceptor designs should move most transaction boundaries to services and reserve explicit `requestTransaction(...)` for rare controller-level compatibility cases where all request work, not just a service method, must share the same boundary.
+
 ### Shutdown and status contracts
 
-`DrizzleTransactionInterceptor` runs each HTTP request through `DrizzleDatabase.requestTransaction(...)`. During application shutdown, `DrizzleDatabase` aborts any still-active request transaction, waits for open request and manual transaction callbacks to settle or roll back, and only then runs the optional `dispose(database)` hook. This ordering lets drivers finish commit/rollback/cleanup work before pools or externally managed resources are closed.
+During application shutdown, `DrizzleDatabase` aborts any still-active request transaction, waits for open request and manual transaction callbacks to settle or roll back, and only then runs the optional `dispose(database)` hook. This ordering lets drivers finish commit/rollback/cleanup work before pools or externally managed resources are closed.
 Nested `requestTransaction(...)` calls opened inside an existing request boundary observe the ambient request abort signal while still reusing the active Drizzle transaction. Nested `requestTransaction(...)` calls opened inside an existing manual transaction boundary also join shutdown settlement tracking without opening a second Drizzle transaction, and their settlement handle remains tracked until the outer manual transaction settles so shutdown drains that outer boundary before `dispose(database)` runs. The platform status activity count is intentionally shorter lived: once the nested request callback settles, `details.activeRequestTransactions` is decremented even if the outer manual transaction continues running.
 New `transaction(...)` and `requestTransaction(...)` calls are rejected once shutdown begins, so disposal cannot overtake a late transaction that starts after the shutdown boundary is crossed.
 If the request signal aborts after the request callback has completed but before the underlying Drizzle transaction runner finishes committing or rolling back, `requestTransaction(...)` waits for that runner to settle first and then rejects with the abort reason. This keeps Drizzle cleanup serialized with request cancellation while making the late request abort visible to the caller instead of returning the completed callback result.
@@ -127,7 +205,7 @@ Use `DrizzleModule.forRoot(...)` / `forRootAsync(...)` to register Drizzle. When
 
 ```ts
 import { defineModule } from '@fluojs/runtime';
-import { DrizzleDatabase, DrizzleModule, DrizzleTransactionInterceptor } from '@fluojs/drizzle';
+import { DrizzleModule } from '@fluojs/drizzle';
 
 const database = {
   transaction: async <T>(callback: (tx: typeof database) => Promise<T>) => callback(database),
@@ -136,7 +214,6 @@ const database = {
 class ManualDrizzleModule {}
 
 defineModule(ManualDrizzleModule, {
-  exports: [DrizzleDatabase, DrizzleTransactionInterceptor],
   imports: [DrizzleModule.forRoot({ database })],
 });
 ```
@@ -145,8 +222,10 @@ defineModule(ManualDrizzleModule, {
 
 - `DrizzleModule.forRoot(options)` / `DrizzleModule.forRootAsync(options)`
 - `DrizzleDatabase`
-- `DrizzleTransactionInterceptor`
+- `DrizzleDatabaseFacade<TDatabase>`
+- `Transaction`
 - `DRIZZLE_DATABASE`, `DRIZZLE_DISPOSE`, `DRIZZLE_HANDLE_PROVIDER`, `DRIZZLE_OPTIONS`
+- `DrizzleDatabase.createFacade(...)` (compatibility-only provider wiring helper; prefer `DrizzleModule.forRoot(...)` / `forRootAsync(...)` for application registration)
 - `createDrizzlePlatformStatusSnapshot(...)`
 - `DrizzleDatabaseLike`
 - `DrizzleModuleOptions`
@@ -154,17 +233,22 @@ defineModule(ManualDrizzleModule, {
 
 `DRIZZLE_HANDLE_PROVIDER` is an alias token for the lifecycle-aware `DrizzleDatabase` wrapper. Health integrations such as `@fluojs/terminus` use this token to read `createPlatformStatusSnapshot()` before falling back to raw database pings.
 
+Use `DrizzleDatabase<TDatabase>` when a provider only needs wrapper methods such as `current()`, `transaction(...)`, `requestTransaction(...)`, or `createPlatformStatusSnapshot()`. Use `DrizzleDatabaseFacade<TDatabase>` for repository injections that call Drizzle query methods directly; the facade forwards those calls to the active transaction handle when one exists and to the root handle otherwise. `DrizzleDatabase.createFacade(...)` is retained as a low-level compatibility helper for module-provider wiring; application code should prefer `DrizzleModule.forRoot(...)` / `forRootAsync(...)`.
+
+`Transaction` is a standard TC39 method decorator for service-layer transaction boundaries. It resolves a transaction-capable target from the decorated host by checking `this.db`, then direct properties, then nested `.db` properties, accepts an accessor for explicit client selection, and can forward Drizzle transaction options to the outer boundary.
+
 ### `DrizzleModule`
 
 - `DrizzleModule.forRoot(options)` / `DrizzleModule.forRootAsync(options)`
 - `forRootAsync(...)` accepts DI-aware Drizzle options whose factory returns the database/dispose/transaction settings; pass `global` on the top-level async registration when the providers should be visible globally.
 - `forRootAsync(...)` resolves options once per application container. Reusing the same module definition across tests or multi-app processes creates isolated database/dispose results for each container instead of sharing a memoized factory result.
 - Supports `strictTransactions: true` to throw if transaction support is missing.
+- `database` must be a concrete object/function handle for both sync and async registration; missing handles are rejected during module registration or async bootstrap.
 
 ## Related Packages
 
 - `@fluojs/runtime`: owns module startup and shutdown sequencing
-- `@fluojs/http`: provides the interceptor pipeline used for request transactions
+- `@fluojs/http`: provides request lifecycle primitives that can be paired with explicit `requestTransaction(...)` boundaries
 - `@fluojs/prisma` and `@fluojs/mongoose`: alternate ORM/ODM integrations with the same fluo runtime model
 
 ## Example Sources

package/dist/database.d.ts

@@ -20,6 +20,20 @@ export declare class DrizzleDatabase<TDatabase extends DrizzleDatabaseLike<TTran
     private activeRequestTransactionStatusCount;
     private lifecycleState;
     constructor(database: TDatabase, dispose?: ((database: TDatabase) => Promise<void> | void) | undefined, databaseOptions?: DrizzleRuntimeOptions);
+    /**
+     * Creates the low-level DI facade that forwards unknown Drizzle API properties to the ambient `current()` handle.
+     *
+     * @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.
+     *
+     * @param database Root Drizzle database handle registered in the module.
+     * @param dispose Optional shutdown hook used to close pools or driver resources.
+     * @param databaseOptions Runtime transaction options consumed by the Fluo wrapper.
+     * @returns A transaction-aware facade that exposes wrapper methods plus the root Drizzle handle surface.
+     */
+    static createFacade<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(database: TDatabase, dispose?: (database: TDatabase) => Promise<void> | void, databaseOptions?: DrizzleRuntimeOptions): DrizzleDatabaseFacade<TDatabase, TTransactionDatabase, TTransactionOptions>;
     /**
      * Returns the active transaction handle when present, otherwise the root Drizzle database handle.
      *
@@ -77,5 +91,18 @@ export declare class DrizzleDatabase<TDatabase extends DrizzleDatabaseLike<TTran
     private trackActiveTransactionScope;
     private resolveTransactionRunner;
 }
+/**
+ * Injection-facing Drizzle facade type that combines the Fluo wrapper methods with the registered database handle.
+ *
+ * @remarks
+ * `DrizzleModule` resolves `DrizzleDatabase` to a proxy that forwards unknown properties to `current()`. Use this type
+ * in repositories that call Drizzle query methods directly, and use `DrizzleDatabase<TDatabase>` when only the wrapper
+ * methods (`current()`, `transaction(...)`, `requestTransaction(...)`, and status snapshots) are needed.
+ *
+ * @typeParam TDatabase Root Drizzle database handle registered in the module.
+ * @typeParam TTransactionDatabase Transaction-scoped database handle resolved inside `database.transaction(...)` callbacks.
+ * @typeParam TTransactionOptions Options forwarded to the underlying Drizzle transaction runner.
+ */
+export type DrizzleDatabaseFacade<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown> = DrizzleDatabase<TDatabase, TTransactionDatabase, TTransactionOptions> & Omit<TDatabase, keyof DrizzleDatabase<TDatabase, TTransactionDatabase, TTransactionOptions>>;
 export {};
 //# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAK7D,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAgCpB,KAAK,qBAAqB,GAAG;IAC3B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AA8CF;;;;;;GAMG;AACH,qBACa,eAAe,CAC1B,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,CAC7B,YAAW,qBAAqB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,qBAAqB;IAS3G,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe;IATlC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqE;IAClG,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqC;IAC7E,OAAO,CAAC,mCAAmC,CAAK;IAChD,OAAO,CAAC,cAAc,CAAkD;gBAGrD,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,GAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA,EACvD,eAAe,GAAE,qBAAqD;IAGzF;;;;;;;;;OASG;IACH,OAAO,IAAI,SAAS,GAAG,oBAAoB;IAI3C,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5C,yFAAyF;IACzF,4BAA4B;IAS5B;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrF;;;;;;;;;;;;OAYG;IACG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;YAIpG,kBAAkB;YA0DlB,yBAAyB;YA8BzB,+BAA+B;YA6C/B,sBAAsB;IAkBpC,OAAO,CAAC,kCAAkC;IAM1C,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,6BAA6B;IAOrC,OAAO,CAAC,+BAA+B;IAKvC,OAAO,CAAC,uCAAuC;IAO/C,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,wBAAwB;CAWjC"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAK7D,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAgCpB,KAAK,qBAAqB,GAAG;IAC3B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAmEF;;;;;;GAMG;AACH,qBACa,eAAe,CAC1B,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,CAC7B,YAAW,qBAAqB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,qBAAqB;IAS3G,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe;IATlC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqE;IAClG,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAqC;IAC7E,OAAO,CAAC,mCAAmC,CAAK;IAChD,OAAO,CAAC,cAAc,CAAkD;gBAGrD,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,GAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA,EACvD,eAAe,GAAE,qBAAqD;IAGzF;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,YAAY,CACjB,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,EAE7B,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EACvD,eAAe,GAAE,qBAAqD,GACrE,qBAAqB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC;IAM9E;;;;;;;;;OASG;IACH,OAAO,IAAI,SAAS,GAAG,oBAAoB;IAI3C,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5C,yFAAyF;IACzF,4BAA4B;IAS5B;;;;;;;;;;;;;OAaG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrF;;;;;;;;;;;;OAYG;IACG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;YAIpG,kBAAkB;YAgElB,yBAAyB;YA8BzB,+BAA+B;YA6C/B,sBAAsB;IAkBpC,OAAO,CAAC,kCAAkC;IAM1C,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,6BAA6B;IAOrC,OAAO,CAAC,+BAA+B;IAKvC,OAAO,CAAC,uCAAuC;IAO/C,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,wBAAwB;CAWjC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,qBAAqB,CAC/B,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAChF,oBAAoB,GAAG,SAAS,EAChC,mBAAmB,GAAG,OAAO,IAC3B,eAAe,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,GACvE,IAAI,CAAC,SAAS,EAAE,MAAM,eAAe,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,CAAC,CAAC"}

package/dist/database.js

@@ -13,6 +13,21 @@ const TRANSACTION_NOT_SUPPORTED_ERROR = 'Transaction not supported: Drizzle data
 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) {
+      if (prop in database) {
+        return Reflect.get(database, prop, receiver);
+      }
+      const currentDatabase = database.current();
+      const value = Reflect.get(currentDatabase, prop, currentDatabase);
+      if (typeof value === 'function') {
+        return value.bind(currentDatabase);
+      }
+      return value;
+    }
+  });
+}
 function createRequestAbortSignalView(parentSignal, signal) {
   if (!signal) {
     return {
@@ -71,6 +86,25 @@ class DrizzleDatabase {
     this.databaseOptions = databaseOptions;
   }
 
+  /**
+   * Creates the low-level DI facade that forwards unknown Drizzle API properties to the ambient `current()` handle.
+   *
+   * @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.
+   *
+   * @param database Root Drizzle database handle registered in the module.
+   * @param dispose Optional shutdown hook used to close pools or driver resources.
+   * @param databaseOptions Runtime transaction options consumed by the Fluo wrapper.
+   * @returns A transaction-aware facade that exposes wrapper methods plus the root Drizzle handle surface.
+   */
+  static createFacade(database, dispose, databaseOptions = {
+    strictTransactions: false
+  }) {
+    return createCurrentlessDrizzleFacade(new _DrizzleDatabase(database, dispose, databaseOptions));
+  }
+
   /**
    * Returns the active transaction handle when present, otherwise the root Drizzle database handle.
    *
@@ -146,6 +180,11 @@ class DrizzleDatabase {
   async executeTransaction(fn, options, requestScoped, signal) {
     const current = this.transactions.getStore();
     if (current) {
+      if (requestScoped) {
+        this.assertRequestTransactionsAvailable();
+      } else {
+        this.assertTransactionsAvailable();
+      }
       if (options !== undefined) {
         throw new Error(NESTED_TRANSACTION_OPTIONS_NOT_SUPPORTED_ERROR);
       }
@@ -302,4 +341,17 @@ class DrizzleDatabase {
     _initClass();
   }
 }
+
+/**
+ * Injection-facing Drizzle facade type that combines the Fluo wrapper methods with the registered database handle.
+ *
+ * @remarks
+ * `DrizzleModule` resolves `DrizzleDatabase` to a proxy that forwards unknown properties to `current()`. Use this type
+ * in repositories that call Drizzle query methods directly, and use `DrizzleDatabase<TDatabase>` when only the wrapper
+ * methods (`current()`, `transaction(...)`, `requestTransaction(...)`, and status snapshots) are needed.
+ *
+ * @typeParam TDatabase Root Drizzle database handle registered in the module.
+ * @typeParam TTransactionDatabase Transaction-scoped database handle resolved inside `database.transaction(...)` callbacks.
+ * @typeParam TTransactionOptions Options forwarded to the underlying Drizzle transaction runner.
+ */
 export { _DrizzleDatabase as DrizzleDatabase };

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;AAKhE,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;AA6G7F;;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;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"}

package/dist/module.js

@@ -1,10 +1,15 @@
 import { defineModule } from '@fluojs/runtime';
 import { DrizzleDatabase } from './database.js';
 import { DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_HANDLE_PROVIDER, DRIZZLE_OPTIONS } from './tokens.js';
-import { DrizzleTransactionInterceptor } from './transaction.js';
 const DRIZZLE_NORMALIZED_OPTIONS = Symbol('fluo.drizzle.normalized-options');
-const DRIZZLE_MODULE_EXPORTS = [DrizzleDatabase, DrizzleTransactionInterceptor, DRIZZLE_HANDLE_PROVIDER];
+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
@@ -28,17 +33,24 @@ function createDrizzleRuntimeProviders(normalizedOptionsProvider) {
     inject: [DRIZZLE_NORMALIZED_OPTIONS],
     provide: DRIZZLE_OPTIONS,
     useFactory: options => createRuntimeOptionsProviderValue(options.strictTransactions)
-  }, DrizzleDatabase, {
+  }, {
+    inject: [DRIZZLE_DATABASE, DRIZZLE_DISPOSE, DRIZZLE_OPTIONS],
+    provide: DrizzleDatabase,
+    useFactory: (database, dispose, databaseOptions) => DrizzleDatabase.createFacade(database, dispose, databaseOptions)
+  }, {
     provide: DRIZZLE_HANDLE_PROVIDER,
     useExisting: DrizzleDatabase
-  }, DrizzleTransactionInterceptor];
+  }];
 }
 function createDrizzleProvidersAsync(options) {
   const normalizedOptionsProvider = {
     inject: options.inject,
     provide: DRIZZLE_NORMALIZED_OPTIONS,
     scope: 'singleton',
-    useFactory: async (...deps) => normalizeDrizzleModuleOptions(await options.useFactory(...deps))
+    useFactory: async (...deps) => normalizeDrizzleModuleOptions({
+      ...(await options.useFactory(...deps)),
+      global: options.global
+    })
   };
   return createDrizzleRuntimeProviders(normalizedOptionsProvider);
 }

package/dist/transaction.d.ts

@@ -1,25 +1,20 @@
-import type { Interceptor, InterceptorContext } from '@fluojs/http';
-import { DrizzleDatabase } from './database.js';
-import type { DrizzleDatabaseLike } from './types.js';
+type TransactionCapableDrizzle<TTransactionOptions = unknown> = {
+    transaction<T>(fn: () => Promise<T>, options?: TTransactionOptions): Promise<T>;
+};
+type TransactionAccessor<THost, TTransactionOptions> = (self: THost) => TransactionCapableDrizzle<TTransactionOptions>;
+type TransactionMethod<THost, TArgs extends unknown[], TResult> = (this: THost, ...args: TArgs) => Promise<TResult>;
 /**
- * HTTP interceptor that wraps each request in a Drizzle request transaction boundary.
+ * Standard TC39 method decorator that runs a service method inside a Drizzle transaction boundary.
  *
  * @remarks
- * Pair this with repository/service code that reads `DrizzleDatabase.current()` so downstream calls share the same
- * request-scoped transaction handle.
+ * `@Transaction()` uses `this.db` when present and otherwise treats the decorated instance itself as the
+ * transaction-capable `DrizzleDatabase`. Pass an accessor such as `@Transaction((self) => self.analyticsDb)` to select
+ * another Drizzle wrapper explicitly. Non-function factory input is forwarded as Drizzle transaction options.
+ *
+ * @param accessorOrOptions Optional target accessor, or Drizzle transaction options.
+ * @param options Optional Drizzle transaction options when an accessor is supplied.
+ * @returns A standard 2023-11 method decorator.
  */
-export declare class DrizzleTransactionInterceptor implements Interceptor {
-    private readonly database;
-    constructor(database: DrizzleDatabase<DrizzleDatabaseLike<unknown, unknown>, unknown, unknown>);
-    /**
-     * Runs the downstream handler inside a Drizzle request transaction boundary.
-     *
-     * @param context Interceptor context that supplies the request abort signal.
-     * @param next Downstream handler chain.
-     * @returns The downstream handler result after the request transaction settles.
-     */
-    intercept(context: InterceptorContext, next: {
-        handle(): Promise<unknown>;
-    }): Promise<unknown>;
-}
+export declare function Transaction<THost, TTransactionOptions = unknown>(accessorOrOptions?: TransactionAccessor<THost, TTransactionOptions> | TTransactionOptions, options?: TTransactionOptions): <TArgs extends unknown[], TResult>(value: TransactionMethod<THost, TArgs, TResult>, context: ClassMethodDecoratorContext<THost, TransactionMethod<THost, TArgs, TResult>>) => TransactionMethod<THost, TArgs, TResult>;
+export {};
 //# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;GAMG;AACH,qBACa,6BAA8B,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,eAAe,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;IAE/G;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE;QAAE,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAGrG"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,KAAK,yBAAyB,CAAC,mBAAmB,GAAG,OAAO,IAAI;IAC9D,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjF,CAAC;AAEF,KAAK,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,IAAI,CACrD,IAAI,EAAE,KAAK,KACR,yBAAyB,CAAC,mBAAmB,CAAC,CAAC;AAEpD,KAAK,iBAAiB,CAAC,KAAK,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,IAAI,CAChE,IAAI,EAAE,KAAK,EACX,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AAwCtB;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,EAC9D,iBAAiB,CAAC,EAAE,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,CAAC,GAAG,mBAAmB,EACzF,OAAO,CAAC,EAAE,mBAAmB,IAOZ,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAC/C,OAAO,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAC/C,SAAS,2BAA2B,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,KACpF,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAc5C"}

package/dist/transaction.js

@@ -1,39 +1,52 @@
-let _initClass;
-function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
-function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
-function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-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 { Inject } from '@fluojs/core';
-import { DrizzleDatabase } from './database.js';
-let _DrizzleTransactionIn;
-/**
- * HTTP interceptor that wraps each request in a Drizzle request transaction boundary.
- *
- * @remarks
- * Pair this with repository/service code that reads `DrizzleDatabase.current()` so downstream calls share the same
- * request-scoped transaction handle.
- */
-class DrizzleTransactionInterceptor {
-  static {
-    [_DrizzleTransactionIn, _initClass] = _applyDecs(this, [Inject(DrizzleDatabase)], []).c;
-  }
-  constructor(database) {
-    this.database = database;
+function isTransactionCapableDrizzle(value) {
+  return typeof value?.transaction === 'function';
+}
+function findNestedTransactionTarget(value) {
+  if (!value || typeof value !== 'object' && typeof value !== 'function') {
+    return undefined;
   }
-
-  /**
-   * Runs the downstream handler inside a Drizzle request transaction boundary.
-   *
-   * @param context Interceptor context that supplies the request abort signal.
-   * @param next Downstream handler chain.
-   * @returns The downstream handler result after the request transaction settles.
-   */
-  async intercept(context, next) {
-    return this.database.requestTransaction(async () => next.handle(), context.requestContext.request.signal);
+  const directDatabase = value.db;
+  if (isTransactionCapableDrizzle(directDatabase)) {
+    return directDatabase;
   }
-  static {
-    _initClass();
+  for (const propertyValue of Object.values(value)) {
+    if (isTransactionCapableDrizzle(propertyValue)) {
+      return propertyValue;
+    }
+    const nestedDatabase = propertyValue?.db;
+    if (isTransactionCapableDrizzle(nestedDatabase)) {
+      return nestedDatabase;
+    }
   }
+  return undefined;
 }
-export { _DrizzleTransactionIn as DrizzleTransactionInterceptor };
+function resolveDefaultTransactionTarget(self) {
+  const implicitTarget = findNestedTransactionTarget(self) ?? self;
+  return implicitTarget;
+}
+
+/**
+ * Standard TC39 method decorator that runs a service method inside a Drizzle transaction boundary.
+ *
+ * @remarks
+ * `@Transaction()` uses `this.db` when present and otherwise treats the decorated instance itself as the
+ * transaction-capable `DrizzleDatabase`. Pass an accessor such as `@Transaction((self) => self.analyticsDb)` to select
+ * another Drizzle wrapper explicitly. Non-function factory input is forwarded as Drizzle transaction options.
+ *
+ * @param accessorOrOptions Optional target accessor, or Drizzle transaction options.
+ * @param options Optional Drizzle transaction options when an accessor is supplied.
+ * @returns A standard 2023-11 method decorator.
+ */
+export function Transaction(accessorOrOptions, options) {
+  const accessor = typeof accessorOrOptions === 'function' ? accessorOrOptions : undefined;
+  const transactionOptions = accessor ? options : accessorOrOptions;
+  return function (value, context) {
+    if (context.kind !== 'method') {
+      throw new Error('@Transaction() can only decorate methods.');
+    }
+    return async function transactionMethod(...args) {
+      const drizzleDatabase = accessor ? accessor(this) : resolveDefaultTransactionTarget(this);
+      return drizzleDatabase.transaction(() => value.apply(this, args), transactionOptions);
+    };
+  };
+}

package/package.json

@@ -9,7 +9,7 @@
     "transaction",
     "als"
   ],
-  "version": "1.0.1",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -37,9 +37,8 @@
   ],
   "dependencies": {
     "@fluojs/core": "^1.0.3",
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/di": "^1.0.3",
-    "@fluojs/runtime": "^1.1.1"
+    "@fluojs/di": "^1.1.0",
+    "@fluojs/runtime": "^1.1.8"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.30.0"
@@ -50,7 +49,8 @@
     }
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@fluojs/http": "^1.1.2"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",