@fluojs/mongoose 1.0.4 → 1.1.0

package/README.ko.md

@@ -11,6 +11,8 @@
 - [빠른 시작](#빠른-시작)
 - [라이프사이클과 종료](#라이프사이클과-종료)
 - [공통 패턴](#공통-패턴)
+  - [서비스 트랜잭션 경계 (@Transaction)](#서비스-트랜잭션-경계-transaction)
+  - [수동 트랜잭션과 currentSession()](#수동-트랜잭션과-currentsession)
 - [공개 API](#공개-api)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -26,7 +28,7 @@ pnpm add mongoose
 
 - Mongoose를 나머지 애플리케이션과 같은 DI 및 라이프사이클 모델에 연결하고 싶을 때.
 - 모든 서비스에서 MongoDB 세션과 트랜잭션을 임시 배관 코드 없이 하나의 wrapper로 다루고 싶을 때.
-- 요청 범위 트랜잭션을 interceptor로 명시적으로 켜고 싶을 때.
+- 애플리케이션이 이미 concrete Mongoose connection을 생성·구성하고 있고, fluo가 그 ownership을 대체하지 않고 관측하기를 원할 때.
 
 ## 빠른 시작
 
@@ -54,77 +56,103 @@ class AppModule {}
 
 ## 라이프사이클과 종료
 
-`MongooseModule`은 `MongooseConnection`을 fluo 애플리케이션 라이프사이클에 등록합니다. 이 패키지는 원본 Mongoose 연결을 직접 생성하거나 소유하지 않습니다. 애플리케이션 종료 시 외부 연결을 닫아야 한다면 `dispose` 훅을 전달하세요.
+`MongooseModule`은 `MongooseConnection`을 fluo 애플리케이션 라이프사이클에 등록합니다. 이 패키지는 원본 Mongoose 연결을 직접 생성하거나 소유하지 않습니다. `connection`에는 concrete Mongoose connection object/function을 전달하고, 연결 문자열, pool, plugin, model compilation ownership은 애플리케이션에 남겨두며, 애플리케이션 종료 시 외부 연결을 닫아야 한다면 `dispose` 훅을 전달하세요.
 
-종료 과정은 트랜잭션 정리 순서를 보존하며, 종료가 시작된 뒤에는 새 수동 또는 요청 범위 트랜잭션 경계를 거부합니다.
+종료 절차는 트랜잭션 정리 순서를 보존하고, 종료가 시작된 뒤에는 새로운 수동 또는 요청 단위 트랜잭션 경계를 거부합니다.
 
-1. 열려 있는 요청 범위 트랜잭션은 `Application shutdown interrupted an open request transaction.` 오류로 abort됩니다.
+1. 열린 요청 단위 트랜잭션은 `Application shutdown interrupted an open request transaction.`으로 abort됩니다.
 2. 활성 ambient session은 transaction callback과 session cleanup이 settle될 때까지 추적됩니다.
 3. 해당 Mongoose 세션은 `abortTransaction()`과 `endSession()` 정리를 끝냅니다.
 4. 설정한 `dispose(connection)` 훅은 활성 요청 트랜잭션과 ambient session scope가 모두 settled된 뒤에만 실행됩니다.
 
-`createMongoosePlatformStatusSnapshot(...)`은 트래픽 처리 중에는 `ready`, 요청 트랜잭션 drain 중에는 `shutting-down`, dispose 훅 완료 뒤에는 `stopped`를 보고합니다. 상태 details에는 `sessionStrategy`, `transactionContext: 'als'`, 활성 요청/session 개수, 리소스 소유권, strict/session 지원 진단이 포함됩니다. 수동 `transaction()`도 요청 범위 트랜잭션과 같은 명시적 세션 계약을 사용하므로, 트랜잭션에 참여해야 하는 Mongoose 모델 작업에는 repository 코드가 `conn.currentSession()`을 전달해야 합니다. 감싼 Mongoose 연결이 `connection.transaction(...)`을 노출하면 fluo는 Mongoose 자체 ambient-session scope를 보존하기 위해 그 API에 transaction boundary를 위임하면서도 같은 session을 `currentSession()`으로 노출합니다. 요청 범위 트랜잭션은 session을 획득하는 동안과 위임된 `connection.transaction(...)` 작업을 시작하는 동안에도 request `AbortSignal`을 관찰하므로, 요청 취소가 사용자 callback 실행 전에 이러한 시작 단계를 중단할 수 있습니다.
+`MongooseConnection.createPlatformStatusSnapshot()`과 export된 low-level `createMongoosePlatformStatusSnapshot(...)` helper는 serving 중에는 `ready`, 요청 트랜잭션을 drain하는 shutdown 중에는 `shutting-down`, dispose hook 완료 후에는 `stopped`를 보고합니다. status details에는 `sessionStrategy`, `transactionContext: 'als'`, 활성 요청/세션 수, 리소스 소유권, strict/session 지원 진단이 포함됩니다. 수동 `transaction()` 호출과 서비스 `@Transaction()` 메서드는 같은 ambient session을 `conn.model(...)`에 노출합니다. 지원되는 facade 메서드(`create`, `find`, `findOne`, `aggregate`, `bulkWrite`)는 해당 세션을 자동으로 첨부합니다. 자동 세션 주입은 `MongooseConnection.model(...)` wrapper 메서드에만 scope되며, `conn.current()`가 반환하는 raw `connection.model(...)` cache/compile 경로를 교체하거나 변형하지 않습니다. 지원되지 않는 model 메서드, `doc.save()`, 외부 유틸리티에 명시적 세션 배관이 필요할 때는 `conn.currentSession()`을 사용하세요. 래핑된 Mongoose connection이 `connection.transaction(...)`을 제공하면 fluo는 Mongoose 자체 ambient-session scope를 보존하면서 동일한 세션을 `currentSession()`으로 노출하도록 해당 API에 트랜잭션 경계를 위임합니다. 요청 단위 트랜잭션은 세션을 획득하는 동안과 위임된 `connection.transaction(...)` 작업을 시작하는 동안 request `AbortSignal`을 관찰하므로, request cancellation은 사용자 callback이 실행되기 전의 startup phase를 중단할 수 있습니다.
+
 기존 수동 `transaction(...)` boundary 안에서 열린 중첩 `requestTransaction(...)` 호출은 ambient session을 재사용하고 `details.activeRequestTransactions`에 계속 표시되며, 종료 중에 abort되어 바깥 수동 transaction이 `dispose(connection)` 실행 전에 rollback할 수 있습니다.
 
 ## 공통 패턴
 
-### `MongooseConnection`을 통한 연결 접근
+### 서비스 트랜잭션 경계 (@Transaction)
 
-`MongooseConnection` 래퍼는 기본 Mongoose 연결에 대한 접근을 제공합니다.
+`@Transaction()` 데코레이터는 서비스 레이어에서 트랜잭션 경계를 정의하는 권장 방법입니다. 이 데코레이터가 적용된 메서드 내부에서 발생하는 모든 리포지토리 호출은 동일한 MongoDB 세션을 공유합니다.
 
-```typescript
-import { MongooseConnection } from '@fluojs/mongoose';
+```ts
+import { Transaction } from '@fluojs/mongoose';
+import { UserRepository } from './user.repository';
+
+export class UserService {
+  constructor(private readonly repo: UserRepository) {}
+
+  @Transaction()
+  async onboardUser(dto: CreateUserDto) {
+    const user = await this.repo.create(dto);
+    await this.repo.initProfile(user._id);
+    return user;
+  }
+}
 
 export class UserRepository {
   constructor(private readonly conn: MongooseConnection) {}
 
-  async findById(id: string) {
-    const User = this.conn.current().model('User');
-    return User.findById(id);
+  async create(data: any) {
+    // @Transaction() 내부에서 conn.model()은 세션 인지형 facade를 반환합니다.
+    // create, find, findOne, aggregate, bulkWrite 등의 작업은
+    // 자동으로 활성 트랜잭션에 참여합니다.
+    return this.conn.model('User').create(data);
+  }
+
+  async initProfile(userId: any) {
+    return this.conn.model('Profile').create({ userId });
   }
 }
 ```
 
-### 수동 트랜잭션과 세션
+`@Transaction()` 메서드 호출은 재진입(reentrant)이 가능합니다. 데코레이터가 적용된 메서드가 다른 데코레이터 적용 메서드를 호출하더라도 하나의 동일한 MongoDB 세션 안에서 실행됩니다. 참고로 v1에서 `doc.save()`는 자동으로 세션을 주입하지 않으므로, 자동 트랜잭션 참여가 필요하다면 지원되는 facade 작업(`model.create()`, `model.find()`, `model.findOne()`, `model.aggregate()`, `model.bulkWrite()`)을 사용하세요.
 
-`conn.transaction()`으로 세션 경계를 만들고, Mongoose 모델 작업에는 세션을 명시적으로 전달합니다.
+### 수동 트랜잭션과 currentSession()
 
-```typescript
-await this.conn.transaction(async () => {
-  const session = this.conn.currentSession();
-  const User = this.conn.current().model('User');
-  
-  // 작업에 세션을 명시적으로 전달
-  await User.create([{ name: 'Ada' }], { session });
-});
-```
-
-감싼 연결이 `startSession()`을 구현하지 않으면 트랜잭션은 기본적으로 직접 실행으로 fallback합니다. fallback 대신 예외를 던지려면 `strictTransactions: true`를 설정합니다. 이때 오류 메시지는 `Transaction not supported: Mongoose connection does not implement startSession.`입니다.
+`MongooseConnection`은 활성 MongoDB 세션에 접근하기 위한 `currentSession()`과 루트 연결 handle에 접근하기 위한 `current()` 메서드를 제공합니다. 외부 유틸리티에 세션을 전달하거나 복잡한 수동 처리가 필요한 경우 escape hatch로 사용하세요.
 
-Fluo는 Mongoose operation option을 다시 쓰지 않습니다. 모델 호출이 명시적인 `{ session }`을 전달하면 그 option은 그대로 유지되며, 생략한 경우 fluo가 session을 자동 부착한다고 가정하면 안 됩니다. 같은 session에서 병렬 작업이나 중첩 transaction 기대치는 보수적으로 유지하세요. 중첩된 `MongooseConnection.transaction(...)` 호출은 같은 session에 두 번째 MongoDB transaction을 여는 대신 활성 boundary를 재사용합니다.
+```ts
+import { MongooseConnection } from '@fluojs/mongoose';
 
-### 요청 범위 트랜잭션
+export class AdvancedRepository {
+  constructor(private readonly conn: MongooseConnection) {}
 
-컨트롤러나 메서드에 `MongooseTransactionInterceptor`를 적용하면 전체 요청을 MongoDB 세션으로 감쌉니다.
+  async customOperation() {
+    const session = this.conn.currentSession();
+    const User = this.conn.current().model('User');
+    
+    // 명시적으로 세션 전달
+    return User.find({ status: 'active' }).session(session || null);
+  }
+}
+```
 
-```typescript
-import { UseInterceptors } from '@fluojs/http';
-import { MongooseTransactionInterceptor } from '@fluojs/mongoose';
+수동 트랜잭션 블록에는 `conn.transaction()`을 사용하세요:
 
-@UseInterceptors(MongooseTransactionInterceptor)
-class UserController {}
+```ts
+await this.conn.transaction(async () => {
+  const User = this.conn.model('User');
+  await User.create([{ name: 'Ada' }]);
+});
 ```
 
-HTTP interceptor 밖에서 같은 request-aware transaction boundary가 필요하다면 `MongooseConnection.requestTransaction(...)`을 직접 사용할 수 있습니다. 중첩된 service transaction은 활성 session boundary를 재사용하며, 수동 transaction 안에서 열린 중첩 request boundary도 request abort와 shutdown tracking에 참여합니다.
+래핑된 연결이 `connection.transaction(...)`을 구현하고 있다면 fluo는 이를 엄격한 트랜잭션 경계로 취급합니다. 그렇지 않고 `startSession()`이 없는 경우 트랜잭션은 기본값(`strictTransactions: false`)에서 callback 직접 실행으로 fail-open합니다. 이 모드는 local fake나 staged migration에는 유용하지만 rollback 원자성은 제공하지 않습니다. MongoDB transaction 보장이 필요한 production 흐름에서는 `strictTransactions: true`를 설정하세요. 그러면 transaction 지원 누락이 readiness `not-ready`와 helper 예외로 드러납니다.
+
+지원되는 facade 메서드에서 fluo는 기존 Mongoose 작업 옵션을 보존하고 올바른 options 인자에 ambient `{ session }`만 병합합니다. 활성 트랜잭션 내부에서 명시적으로 `{ session: null }`을 전달하거나 다른 세션 객체를 사용하면, 의도치 않은 트랜잭션 탈출을 방지하기 위해 세션 충돌 에러를 발생시킵니다.
 
 ## 공개 API
 
 - `MongooseModule.forRoot(options)` / `MongooseModule.forRootAsync(options)`
 - `MongooseConnection`
-- `MongooseTransactionInterceptor`
+- `MongooseConnection.createPlatformStatusSnapshot()` — platform observability surface를 위해 health/readiness, resource ownership, 활성 request/session drain 수, strict transaction 지원 진단을 보고합니다.
+- `MongooseConnection.model(name, ...args)` — 트랜잭션 밖에서는 raw model을 반환하고, 활성 트랜잭션 안에서는 underlying Mongoose connection을 변형하지 않으면서 `create`, `find`, `findOne`, `aggregate`, `bulkWrite`에 세션을 주입하는 facade를 반환합니다.
+- `Transaction`
 - `MONGOOSE_CONNECTION`, `MONGOOSE_DISPOSE`, `MONGOOSE_OPTIONS`
 - `createMongooseProviders(options)` — 호환성/수동 composition helper입니다. 애플리케이션-facing 등록에서는 module export와 provider visibility가 문서화된 namespace facade와 맞도록 `MongooseModule.forRoot(...)` 또는 `MongooseModule.forRootAsync(...)`를 우선 사용하세요.
 - `createMongoosePlatformStatusSnapshot(...)`
+- sync 및 async 등록 모두에서 `connection`은 실제 object/function handle이어야 하며, 누락된 handle은 모듈 등록 또는 async bootstrap 중 거부됩니다.
+- `Transaction`은 서비스 계층 세션 트랜잭션 경계를 위한 표준 TC39 method decorator입니다. 기본적으로 `this.conn`, 데코레이터가 적용된 인스턴스 자체, 또는 하나의 고유한 중첩 `this.*.conn` collaborator를 resolve합니다. `MongooseConnection`이 다른 필드에 있거나 resolution이 모호하다면 accessor를 전달하세요.
 
 ### 관련 export 타입
 
@@ -138,7 +166,7 @@ HTTP interceptor 밖에서 같은 request-aware transaction boundary가 필요
 ## 관련 패키지
 
 - `@fluojs/runtime`: 애플리케이션 라이프사이클 및 종료 훅을 관리합니다.
-- `@fluojs/http`: 인터셉터 시스템을 제공합니다.
+- `@fluojs/http`: 명시적 `requestTransaction(...)` 경계와 함께 사용할 수 있는 요청 라이프사이클 primitive를 제공합니다.
 - `@fluojs/prisma` / `@fluojs/drizzle`: 대안 데이터베이스 통합 모듈입니다.
 
 ## 예제 소스

package/README.md

@@ -11,6 +11,8 @@ Mongoose integration for fluo with session-aware transaction handling and lifecy
 - [Quick Start](#quick-start)
 - [Lifecycle and Shutdown](#lifecycle-and-shutdown)
 - [Common Patterns](#common-patterns)
+  - [Service Transaction Boundary (@Transaction)](#service-transaction-boundary-transaction)
+  - [Manual Transactions and currentSession()](#manual-transactions-and-currentsession)
 - [Public API](#public-api)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -26,7 +28,8 @@ pnpm add mongoose
 
 - when Mongoose should plug into the same DI and application lifecycle as the rest of the app
 - when MongoDB sessions and transactions need one shared wrapper instead of ad hoc session plumbing in every service
-- when request-scoped transactions should be opt-in through an interceptor
+- when request-scoped transactions need explicit `requestTransaction(...)` boundaries
+- when an application already creates and configures its concrete Mongoose connection and wants fluo to observe, not replace, that ownership
 
 ## Quick Start
 
@@ -52,7 +55,7 @@ class AppModule {}
 
 ## Lifecycle and Shutdown
 
-`MongooseModule` registers `MongooseConnection` with the fluo application lifecycle. The package does not create or own the raw Mongoose connection for you; pass a `dispose` hook when the application should close that external connection during shutdown.
+`MongooseModule` registers `MongooseConnection` with the fluo application lifecycle. The package does not create or own the raw Mongoose connection for you; pass a concrete Mongoose connection object/function as `connection`, keep connection-string, pool, plugin, and model compilation ownership in the application, and provide a `dispose` hook when the application should close that external connection during shutdown.
 
 Shutdown preserves transaction cleanup order and rejects new manual or request-scoped transaction boundaries once shutdown begins:
 
@@ -61,61 +64,93 @@ Shutdown preserves transaction cleanup order and rejects new manual or request-s
 3. Their Mongoose sessions finish `abortTransaction()` and `endSession()` cleanup.
 4. The configured `dispose(connection)` hook runs only after active request transactions and ambient session scopes have settled.
 
-`createMongoosePlatformStatusSnapshot(...)` reports `ready` while serving traffic, `shutting-down` while request transactions are draining, and `stopped` after the dispose hook completes. The status details include `sessionStrategy`, `transactionContext: 'als'`, active request/session counts, resource ownership, and strict/session support diagnostics. Manual `transaction()` calls still use the same explicit-session contract as request-scoped transactions: repository code must pass `conn.currentSession()` into Mongoose model operations that participate in the transaction. If the wrapped Mongoose connection exposes `connection.transaction(...)`, fluo delegates the transaction boundary to that API so Mongoose's own ambient-session scope is preserved while still exposing the same session through `currentSession()`. Request-scoped transactions observe the request `AbortSignal` while acquiring sessions and while starting delegated `connection.transaction(...)` work, so request cancellation can interrupt those startup phases before user callbacks run.
+`MongooseConnection.createPlatformStatusSnapshot()` and the exported low-level `createMongoosePlatformStatusSnapshot(...)` helper report `ready` while serving traffic, `shutting-down` while request transactions are draining, and `stopped` after the dispose hook completes. The status details include `sessionStrategy`, `transactionContext: 'als'`, active request/session counts, resource ownership, and strict/session support diagnostics. Manual `transaction()` calls and service `@Transaction()` methods expose the same ambient session to `conn.model(...)`; supported facade methods (`create`, `find`, `findOne`, `aggregate`, and `bulkWrite`) automatically attach that session. Automatic session injection is scoped to the `MongooseConnection.model(...)` wrapper method and does not replace or mutate the raw `connection.model(...)` cache/compile path returned by `conn.current()`. Use `conn.currentSession()` for unsupported model methods, `doc.save()`, or external utilities that need explicit session plumbing. If the wrapped Mongoose connection exposes `connection.transaction(...)`, fluo delegates the transaction boundary to that API so Mongoose's own ambient-session scope is preserved while still exposing the same session through `currentSession()`. Request-scoped transactions observe the request `AbortSignal` while acquiring sessions and while starting delegated `connection.transaction(...)` work, so request cancellation can interrupt those startup phases before user callbacks run.
 Nested `requestTransaction(...)` calls opened inside an existing manual `transaction(...)` boundary reuse the ambient session, stay visible in `details.activeRequestTransactions`, and are aborted during shutdown so the outer manual transaction can roll back before `dispose(connection)` runs.
 
 ## Common Patterns
 
-### Access the connection through `MongooseConnection`
+### 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 MongoDB session.
 
 ```ts
-import { MongooseConnection } from '@fluojs/mongoose';
+import { Transaction } from '@fluojs/mongoose';
+import { UserRepository } from './user.repository';
+
+export class UserService {
+  constructor(private readonly repo: UserRepository) {}
+
+  @Transaction()
+  async onboardUser(dto: CreateUserDto) {
+    const user = await this.repo.create(dto);
+    await this.repo.initProfile(user._id);
+    return user;
+  }
+}
 
 export class UserRepository {
   constructor(private readonly conn: MongooseConnection) {}
 
-  async findById(id: string) {
-    const User = this.conn.current().model('User');
-    return User.findById(id);
+  async create(data: any) {
+    // model() returns a session-aware facade inside @Transaction().
+    // Operations like create, find, findOne, aggregate, and bulkWrite
+    // automatically participate in the ambient transaction.
+    return this.conn.model('User').create(data);
+  }
+
+  async initProfile(userId: any) {
+    return this.conn.model('Profile').create({ userId });
   }
 }
 ```
 
-### Manual transactions still need explicit sessions
+Calls to `@Transaction()` methods are reentrant. If a decorated method calls another decorated method, they share the same underlying MongoDB session. Note that `doc.save()` is not automatically session-aware in v1; use the supported facade operations (`model.create()`, `model.find()`, `model.findOne()`, `model.aggregate()`, or `model.bulkWrite()`) for automatic transaction participation.
 
-```ts
-await this.conn.transaction(async () => {
-  const session = this.conn.currentSession();
-  const User = this.conn.current().model('User');
+### Manual Transactions and currentSession()
 
-  await User.create([{ name: 'Ada' }], { session });
-});
-```
+The `MongooseConnection` provides `currentSession()` to access the ambient MongoDB session and `current()` to access the root connection handle. Use these as escape hatches when you need to pass sessions to external utilities or perform advanced manual plumbing.
 
-If the wrapped connection does not implement `startSession()`, transactions fall back to direct execution by default. Set `strictTransactions: true` to throw `Transaction not supported: Mongoose connection does not implement startSession.` instead of falling back.
+```ts
+import { MongooseConnection } from '@fluojs/mongoose';
+
+export class AdvancedRepository {
+  constructor(private readonly conn: MongooseConnection) {}
 
-Fluo never rewrites Mongoose operation options. If a model call passes an explicit `{ session }`, that option is left intact; if it omits one, repositories should not assume fluo will attach a session for them. Keep same-session parallel work and nested transaction expectations conservative: nested `MongooseConnection.transaction(...)` calls reuse the active boundary rather than opening a second MongoDB transaction on the same session.
+  async customOperation() {
+    const session = this.conn.currentSession();
+    const User = this.conn.current().model('User');
+    
+    // Explicitly passing the session
+    return User.find({ status: 'active' }).session(session || null);
+  }
+}
+```
 
-### Request-scoped transactions
+Use `conn.transaction()` for manual transaction blocks:
 
 ```ts
-import { UseInterceptors } from '@fluojs/http';
-import { MongooseTransactionInterceptor } from '@fluojs/mongoose';
-
-@UseInterceptors(MongooseTransactionInterceptor)
-class UserController {}
+await this.conn.transaction(async () => {
+  const User = this.conn.model('User');
+  await User.create([{ name: 'Ada' }]);
+});
 ```
 
-Use `MongooseConnection.requestTransaction(...)` directly when you need the same request-aware transaction boundary outside an HTTP interceptor. Nested service transactions reuse the active session boundary, and nested request boundaries opened inside a manual transaction still participate in request abort and shutdown tracking.
+If the wrapped connection implements `connection.transaction(...)`, fluo treats that as the strict transaction boundary. Otherwise, when the connection does not implement `startSession()`, transactions use fail-open direct callback execution by default (`strictTransactions: false`), which is useful for local fakes and staged migrations but provides no rollback atomicity. Set `strictTransactions: true` for production flows that require MongoDB transaction guarantees; missing transaction support then makes readiness `not-ready` and causes transaction helpers to throw.
+
+For supported facade methods, fluo preserves existing Mongoose operation options and only merges the ambient `{ session }` into the correct options argument. If a model call passes an explicit `{ session: null }` or a different session object inside an ambient transaction, fluo throws a session conflict error to prevent accidental transaction escapes.
 
 ## Public API
 
 - `MongooseModule.forRoot(options)` / `MongooseModule.forRootAsync(options)`
 - `MongooseConnection`
-- `MongooseTransactionInterceptor`
+- `MongooseConnection.createPlatformStatusSnapshot()` — reports health/readiness, resource ownership, active request/session drain counts, and strict transaction support diagnostics for platform observability surfaces.
+- `MongooseConnection.model(name, ...args)` — returns the raw model outside transactions or a session-aware facade for `create`, `find`, `findOne`, `aggregate`, and `bulkWrite` inside an active transaction without mutating the underlying Mongoose connection.
+- `Transaction`
 - `MONGOOSE_CONNECTION`, `MONGOOSE_DISPOSE`, `MONGOOSE_OPTIONS`
 - `createMongooseProviders(options)` — compatibility/manual composition helper; prefer `MongooseModule.forRoot(...)` or `MongooseModule.forRootAsync(...)` for application-facing registration so module exports and provider visibility stay aligned.
 - `createMongoosePlatformStatusSnapshot(...)`
+- `connection` must be a concrete object/function handle for both sync and async registration; missing handles are rejected during module registration or async bootstrap.
+- `Transaction` is a standard TC39 method decorator for service-layer session transaction boundaries. It resolves `this.conn`, the decorated instance itself, or one unique nested `this.*.conn` collaborator by default; pass an accessor when the `MongooseConnection` lives under a different field or resolution would be ambiguous.
 
 ### Related exported types
 
@@ -129,7 +164,7 @@ Use `MongooseConnection.requestTransaction(...)` directly when you need the same
 ## Related Packages
 
 - `@fluojs/runtime`: manages startup and shutdown hooks
-- `@fluojs/http`: provides the interceptor chain for request transactions
+- `@fluojs/http`: provides request lifecycle primitives that can be paired with explicit `requestTransaction(...)` boundaries
 - `@fluojs/prisma` and `@fluojs/drizzle`: alternate database integrations with different transaction models
 
 ## Example Sources

package/dist/connection.d.ts

@@ -3,6 +3,7 @@ import type { MongooseConnectionLike, MongooseHandleProvider, MongooseSessionLik
 type MongooseRuntimeOptions = {
     strictTransactions: boolean;
 };
+type MongooseModelLike = Record<PropertyKey, unknown>;
 /**
  * Session-aware Mongoose wrapper that integrates request scoping and shutdown handling with the Fluo runtime.
  *
@@ -39,6 +40,14 @@ export declare class MongooseConnection<TConnection extends MongooseConnectionLi
      * @returns The ambient session inside a transaction boundary, or `undefined` outside one.
      */
     currentSession(): MongooseSessionLike | undefined;
+    /**
+     * Returns a model from the root connection, injecting the ambient transaction session into conservative operations.
+     *
+     * @param name Model name passed to the underlying Mongoose connection.
+     * @param args Additional model resolver arguments forwarded unchanged.
+     * @returns The real model outside transactions, or a model facade inside an active transaction boundary.
+     */
+    model(name: string, ...args: unknown[]): MongooseModelLike;
     /** Aborts active request transactions, waits for settlement, then runs the optional dispose hook. */
     onApplicationShutdown(): Promise<void>;
     /** Produces the shared persistence status snapshot for platform diagnostics surfaces. */

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAS7D,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAuBpB,KAAK,sBAAsB,GAAG;IAC5B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAmBF;;;;GAIG;AACH,qBACa,kBAAkB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB,CACjG,YAAW,sBAAsB,CAAC,WAAW,CAAC,EAAE,qBAAqB;IAQnE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IARpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,cAAc,CAAkD;gBAGrD,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,GAAE,CAAC,UAAU,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA,EAC3D,iBAAiB,GAAE,sBAAsD;IAG5F;;;;;;;;;OASG;IACH,OAAO,IAAI,WAAW;IAItB;;;;;;;;;OASG;IACH,cAAc,IAAI,mBAAmB,GAAG,SAAS;IAIjD,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5C,yFAAyF;IACzF,4BAA4B;IAY5B;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBtD;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IA+CnF,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,kCAAkC;YAM5B,2BAA2B;YAc3B,wBAAwB;YA4BxB,wBAAwB;IActC,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,+BAA+B;YAIzB,cAAc;CAW7B"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAS7D,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAuBpB,KAAK,sBAAsB,GAAG;IAC5B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,KAAK,iBAAiB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAyJtD;;;;GAIG;AACH,qBACa,kBAAkB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB,CACjG,YAAW,sBAAsB,CAAC,WAAW,CAAC,EAAE,qBAAqB;IAQnE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IARpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,cAAc,CAAkD;gBAGrD,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,GAAE,CAAC,UAAU,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA,EAC3D,iBAAiB,GAAE,sBAAsD;IAG5F;;;;;;;;;OASG;IACH,OAAO,IAAI,WAAW;IAItB;;;;;;;;;OASG;IACH,cAAc,IAAI,mBAAmB,GAAG,SAAS;IAIjD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,iBAAiB;IAa1D,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5C,yFAAyF;IACzF,4BAA4B;IAY5B;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBtD;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IA+CnF,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,kCAAkC;YAM5B,2BAA2B;YAc3B,wBAAwB;YA4BxB,wBAAwB;IActC,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,+BAA+B;YAIzB,cAAc;CAW7B"}

package/dist/connection.js

@@ -11,6 +11,95 @@ import { createMongoosePlatformStatusSnapshot } from './status.js';
 import { MONGOOSE_CONNECTION, MONGOOSE_DISPOSE, MONGOOSE_OPTIONS } from './tokens.js';
 const TRANSACTIONS_NOT_SUPPORTED_ERROR = 'Transaction not supported: Mongoose connection does not implement startSession.';
 const TRANSACTION_UNAVAILABLE_ERROR = 'Mongoose transactions are unavailable during application shutdown.';
+const MODEL_OPERATIONS_WITH_OPTIONS = new Set(['aggregate', 'bulkWrite', 'create', 'find', 'findOne']);
+const MODEL_OPERATIONS_WITH_PROJECTION = new Set(['find', 'findOne']);
+const MONGOOSE_CREATE_OPTION_KEYS = new Set(['aggregateErrors', 'checkKeys', 'j', 'ordered', 'populate', 'safe', 'session', 'timestamps', 'validateBeforeSave', 'validateModifiedOnly', 'w', 'writeConcern', 'wtimeout']);
+function hasExplicitSessionOption(value) {
+  return value !== null && typeof value === 'object' && 'session' in value;
+}
+function isObjectLike(value) {
+  return typeof value === 'object' && value !== null || typeof value === 'function';
+}
+function isMongooseCreateOptionsCandidate(value) {
+  if (!isObjectLike(value)) {
+    return false;
+  }
+  for (const key of MONGOOSE_CREATE_OPTION_KEYS) {
+    if (key in value) {
+      return true;
+    }
+  }
+  return false;
+}
+function isEmptyCreateOptionsCandidate(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+function resolveCreateOptionsIndex(operationArgs) {
+  if (operationArgs.length >= 2 && isMongooseCreateOptionsCandidate(operationArgs[operationArgs.length - 1])) {
+    return operationArgs.length - 1;
+  }
+  if (operationArgs.length === 2 && Array.isArray(operationArgs[0])) {
+    return 1;
+  }
+  if (operationArgs.length === 2 && isEmptyCreateOptionsCandidate(operationArgs[1])) {
+    return 1;
+  }
+  return operationArgs.length;
+}
+function resolveOptionsIndex(operation, operationArgs) {
+  if (operation === 'create') {
+    return resolveCreateOptionsIndex(operationArgs);
+  }
+  if (!MODEL_OPERATIONS_WITH_PROJECTION.has(operation)) {
+    return operationArgs.length > 1 ? 1 : operationArgs.length;
+  }
+  if (operationArgs.length >= 3) {
+    return 2;
+  }
+  if (operationArgs.length === 2 && hasExplicitSessionOption(operationArgs[1])) {
+    return 1;
+  }
+  if (operationArgs.length <= 1) {
+    return 2;
+  }
+  return operationArgs.length;
+}
+function resolveSessionOptions(opts, ambient) {
+  const options = opts && typeof opts === 'object' ? opts : {};
+  if (options.session === null) {
+    throw new Error('Explicit session: null conflicts with ambient transaction session');
+  }
+  if (options.session !== undefined && options.session !== ambient) {
+    throw new Error('Explicit session conflicts with ambient transaction session');
+  }
+  return {
+    ...options,
+    session: ambient
+  };
+}
+function createAmbientSessionModelFacade(model, ambient) {
+  return new Proxy(model, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (!MODEL_OPERATIONS_WITH_OPTIONS.has(prop) || typeof value !== 'function') {
+        return value;
+      }
+      return (...args) => {
+        const operationArgs = [...args];
+        const optionsIndex = resolveOptionsIndex(prop, operationArgs);
+        operationArgs[optionsIndex] = resolveSessionOptions(operationArgs[optionsIndex], ambient);
+        return value.apply(target, operationArgs);
+      };
+    }
+  });
+}
+function resolveModelFactory(connection) {
+  if (!isObjectLike(connection)) {
+    return undefined;
+  }
+  const modelConnection = connection;
+  return modelConnection.model;
+}
 async function executeSessionTransaction(session, fn) {
   try {
     await session.startTransaction();
@@ -77,6 +166,23 @@ class MongooseConnection {
     return this.sessions.getStore();
   }
 
+  /**
+   * Returns a model from the root connection, injecting the ambient transaction session into conservative operations.
+   *
+   * @param name Model name passed to the underlying Mongoose connection.
+   * @param args Additional model resolver arguments forwarded unchanged.
+   * @returns The real model outside transactions, or a model facade inside an active transaction boundary.
+   */
+  model(name, ...args) {
+    const modelFactory = resolveModelFactory(this.connection);
+    if (typeof modelFactory !== 'function') {
+      throw new Error('Mongoose connection does not implement model().');
+    }
+    const model = modelFactory.call(this.connection, name, ...args);
+    const ambient = this.currentSession();
+    return ambient ? createAmbientSessionModelFacade(model, ambient) : model;
+  }
+
   /** Aborts active request transactions, waits for settlement, then runs the optional dispose hook. */
   async onApplicationShutdown() {
     this.lifecycleState = 'shutting-down';
@@ -117,11 +223,11 @@ class MongooseConnection {
    * @returns The callback result after the session transaction finishes or the direct-execution fallback completes.
    */
   async transaction(fn) {
+    this.assertTransactionsAvailable();
     const currentSession = this.sessions.getStore();
     if (currentSession) {
       return fn();
     }
-    this.assertTransactionsAvailable();
     if (typeof this.connection.transaction === 'function') {
       return this.runConnectionTransaction(fn);
     }

package/dist/module.d.ts

@@ -30,7 +30,7 @@ export declare class MongooseModule {
      * Registers Mongoose providers from static options.
      *
      * @param options Mongoose module options with connection handle, optional dispose hook, and strict transaction mode.
-     * @returns A module definition that exports `MongooseConnection` and `MongooseTransactionInterceptor`.
+     * @returns A module definition that exports `MongooseConnection`.
      */
     static forRoot<TConnection extends MongooseConnectionLike>(options: MongooseModuleOptions<TConnection>): ModuleType;
     /**

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;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAahF;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,CAAC,WAAW,SAAS,sBAAsB,IAAI,kBAAkB,CACrG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CACnD,GAAG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AAiEvD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,sBAAsB,EAChF,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,QAAQ,EAAE,CAOZ;AA0BD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,SAAS,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAAG,UAAU;IAInH;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,WAAW,SAAS,sBAAsB,EAC5D,OAAO,EAAE,0BAA0B,CAAC,WAAW,CAAC,GAC/C,UAAU;CAGd"}
+{"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,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAahF;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,CAAC,WAAW,SAAS,sBAAsB,IAAI,kBAAkB,CACrG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CACnD,GAAG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AA2EvD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,sBAAsB,EAChF,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,QAAQ,EAAE,CAOZ;AA0BD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,SAAS,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAAG,UAAU;IAInH;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,WAAW,SAAS,sBAAsB,EAC5D,OAAO,EAAE,0BAA0B,CAAC,WAAW,CAAC,GAC/C,UAAU;CAGd"}

package/dist/module.js

@@ -1,7 +1,6 @@
 import { defineModule } from '@fluojs/runtime';
 import { MongooseConnection } from './connection.js';
 import { MONGOOSE_CONNECTION, MONGOOSE_DISPOSE, MONGOOSE_OPTIONS } from './tokens.js';
-import { MongooseTransactionInterceptor } from './transaction.js';
 
 /**
  * Async registration options accepted by `MongooseModule.forRootAsync(...)`.
@@ -12,8 +11,14 @@ import { MongooseTransactionInterceptor } from './transaction.js';
  */
 
 const MONGOOSE_NORMALIZED_OPTIONS = Symbol('fluo.mongoose.normalized-options');
-const MONGOOSE_MODULE_EXPORTS = [MongooseConnection, MongooseTransactionInterceptor];
+const MONGOOSE_MODULE_EXPORTS = [MongooseConnection];
+function isObjectLike(value) {
+  return typeof value === 'object' && value !== null || typeof value === 'function';
+}
 function normalizeMongooseModuleOptions(options) {
+  if (!isObjectLike(options.connection)) {
+    throw new Error('MongooseModule requires a connection option.');
+  }
   return {
     ...options,
     strictTransactions: options.strictTransactions ?? false
@@ -37,7 +42,7 @@ function createMongooseRuntimeProviders(normalizedOptionsProvider) {
     inject: [MONGOOSE_NORMALIZED_OPTIONS],
     provide: MONGOOSE_OPTIONS,
     useFactory: options => createRuntimeOptionsProviderValue(options.strictTransactions)
-  }, MongooseConnection, MongooseTransactionInterceptor];
+  }, MongooseConnection];
 }
 function createMongooseProvidersAsync(options) {
   const factory = options.useFactory;
@@ -47,7 +52,10 @@ function createMongooseProvidersAsync(options) {
     scope: 'singleton',
     useFactory: async (...deps) => {
       const resolvedOptions = await factory(...deps);
-      return normalizeMongooseModuleOptions(resolvedOptions);
+      return normalizeMongooseModuleOptions({
+        ...resolvedOptions,
+        global: options.global
+      });
     }
   };
   return createMongooseRuntimeProviders(normalizedOptionsProvider);
@@ -96,7 +104,7 @@ export class MongooseModule {
    * Registers Mongoose providers from static options.
    *
    * @param options Mongoose module options with connection handle, optional dispose hook, and strict transaction mode.
-   * @returns A module definition that exports `MongooseConnection` and `MongooseTransactionInterceptor`.
+   * @returns A module definition that exports `MongooseConnection`.
    */
   static forRoot(options) {
     return buildMongooseModule(options);

package/dist/transaction.d.ts

@@ -1,25 +1,20 @@
-import type { Interceptor, InterceptorContext } from '@fluojs/http';
-import { MongooseConnection } from './connection.js';
-import type { MongooseConnectionLike } from './types.js';
+type TransactionConnection = {
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+};
+type TransactionMethod<THost, TArgs extends unknown[], TResult> = (this: THost, ...args: TArgs) => Promise<TResult>;
 /**
- * HTTP interceptor that wraps each request in a Mongoose request transaction boundary.
+ * Wraps a service method in a `MongooseConnection.transaction(...)` boundary.
  *
  * @remarks
- * Pair this with repository/service code that reads `MongooseConnection.current()` and `currentSession()` so downstream
- * calls share the same request-scoped session.
+ * This is a TC39 standard method decorator. By default it uses `this.conn` when present, the decorated instance
+ * itself when it is transaction-capable, or one unique nested `this.*.conn` collaborator. Pass an accessor when the
+ * connection lives under a different field or more than one nested collaborator exposes a connection; the decorator
+ * does not bind arbitrary transaction-capable properties to avoid selecting the wrong persistence handle.
+ * Nested decorated calls reuse the ambient Mongoose session through `MongooseConnection.transaction(...)`.
+ *
+ * @param accessor Optional connection resolver for the decorated service instance.
+ * @returns A standard method decorator that executes the original method inside a Mongoose transaction.
  */
-export declare class MongooseTransactionInterceptor implements Interceptor {
-    private readonly connection;
-    constructor(connection: MongooseConnection<MongooseConnectionLike>);
-    /**
-     * Runs the downstream handler inside a Mongoose 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>(accessor?: (self: THost) => TransactionConnection): <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,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;GAMG;AACH,qBACa,8BAA+B,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,kBAAkB,CAAC,sBAAsB,CAAC;IAEnF;;;;;;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,qBAAqB,GAAG;IAC3B,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClD,CAAC;AAEF,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;AA6DtB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAC/B,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,qBAAqB,GAChD,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAClC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAC/C,OAAO,EAAE,2BAA2B,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,KAClF,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAW5C"}

package/dist/transaction.js

@@ -1,39 +1,65 @@
-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 { MongooseConnection } from './connection.js';
-let _MongooseTransactionI;
-/**
- * HTTP interceptor that wraps each request in a Mongoose request transaction boundary.
- *
- * @remarks
- * Pair this with repository/service code that reads `MongooseConnection.current()` and `currentSession()` so downstream
- * calls share the same request-scoped session.
- */
-class MongooseTransactionInterceptor {
-  static {
-    [_MongooseTransactionI, _initClass] = _applyDecs(this, [Inject(MongooseConnection)], []).c;
+function isTransactionConnection(value) {
+  return (typeof value === 'object' && value !== null || typeof value === 'function') && typeof value.transaction === 'function';
+}
+function collectNestedConnCandidates(self) {
+  if ((typeof self !== 'object' || self === null) && typeof self !== 'function') {
+    return [];
   }
-  constructor(connection) {
-    this.connection = connection;
+  const candidates = new Set();
+  for (const value of Object.values(self)) {
+    if ((typeof value !== 'object' || value === null) && typeof value !== 'function') {
+      continue;
+    }
+    const nestedConn = value.conn;
+    if (isTransactionConnection(nestedConn)) {
+      candidates.add(nestedConn);
+    }
   }
-
-  /**
-   * Runs the downstream handler inside a Mongoose 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.connection.requestTransaction(async () => next.handle(), context.requestContext.request.signal);
+  return Array.from(candidates);
+}
+function resolveTransactionConnection(self, accessor) {
+  if (accessor) {
+    const connection = accessor(self);
+    if (isTransactionConnection(connection)) {
+      return connection;
+    }
+    throw new Error('Mongoose @Transaction() accessor did not return a transaction-capable connection.');
+  }
+  const fallbackHost = self;
+  if (isTransactionConnection(fallbackHost.conn)) {
+    return fallbackHost.conn;
   }
-  static {
-    _initClass();
+  if (isTransactionConnection(self)) {
+    return self;
   }
+  const nestedConnCandidates = collectNestedConnCandidates(self);
+  if (nestedConnCandidates.length === 1) {
+    return nestedConnCandidates[0];
+  }
+  if (nestedConnCandidates.length > 1) {
+    throw new Error('Mongoose @Transaction() found multiple nested this.*.conn candidates; pass an accessor.');
+  }
+  throw new Error('Mongoose @Transaction() could not resolve a transaction-capable connection from this.conn.');
 }
-export { _MongooseTransactionI as MongooseTransactionInterceptor };
+
+/**
+ * Wraps a service method in a `MongooseConnection.transaction(...)` boundary.
+ *
+ * @remarks
+ * This is a TC39 standard method decorator. By default it uses `this.conn` when present, the decorated instance
+ * itself when it is transaction-capable, or one unique nested `this.*.conn` collaborator. Pass an accessor when the
+ * connection lives under a different field or more than one nested collaborator exposes a connection; the decorator
+ * does not bind arbitrary transaction-capable properties to avoid selecting the wrong persistence handle.
+ * Nested decorated calls reuse the ambient Mongoose session through `MongooseConnection.transaction(...)`.
+ *
+ * @param accessor Optional connection resolver for the decorated service instance.
+ * @returns A standard method decorator that executes the original method inside a Mongoose transaction.
+ */
+export function Transaction(accessor) {
+  return function transactionDecorator(value, _context) {
+    return async function transactionWrappedMethod(...args) {
+      const connection = resolveTransactionConnection(this, accessor);
+      return connection.transaction(() => value.apply(this, args));
+    };
+  };
+}

package/dist/types.d.ts

@@ -48,6 +48,14 @@ export interface MongooseHandleProvider<TConnection extends MongooseConnectionLi
     current(): TConnection;
     /** Returns the ambient Mongoose session for the current async context, when one exists. */
     currentSession(): MongooseSessionLike | undefined;
+    /**
+     * Returns a Mongoose model handle, or a session-aware facade inside an active transaction.
+     *
+     * @param name Model name passed to the underlying Mongoose connection.
+     * @param args Additional model resolver arguments forwarded unchanged.
+     * @returns The root model outside transactions, or a model facade inside an active transaction boundary.
+     */
+    model(name: string, ...args: unknown[]): Record<PropertyKey, unknown>;
     /**
      * Opens a Mongoose session transaction boundary around `fn`.
      *

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,iBAAiB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,UAAU,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACxG,kFAAkF;IAClF,UAAU,EAAE,WAAW,CAAC;IACxB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1D,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACzG,uFAAuF;IACvF,OAAO,IAAI,WAAW,CAAC;IACvB,2FAA2F;IAC3F,cAAc,IAAI,mBAAmB,GAAG,SAAS,CAAC;IAClD;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,iBAAiB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,UAAU,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACxG,kFAAkF;IAClF,UAAU,EAAE,WAAW,CAAC;IACxB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1D,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACzG,uFAAuF;IACvF,OAAO,IAAI,WAAW,CAAC;IACvB,2FAA2F;IAC3F,cAAc,IAAI,mBAAmB,GAAG,SAAS,CAAC;IAClD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACtE;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E"}

package/package.json

@@ -9,7 +9,7 @@
     "transaction",
     "odm"
   ],
-  "version": "1.0.4",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -37,9 +37,9 @@
   ],
   "dependencies": {
     "@fluojs/core": "^1.0.3",
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/di": "^1.0.3",
-    "@fluojs/runtime": "^1.1.1"
+    "@fluojs/http": "^1.1.2",
+    "@fluojs/di": "^1.1.0",
+    "@fluojs/runtime": "^1.1.8"
   },
   "peerDependencies": {
     "mongoose": ">=7.0.0"