@fluojs/mongoose 1.0.0-beta.2 → 1.0.0-beta.3

package/README.ko.md

@@ -2,7 +2,7 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-fluo 애플리케이션을 위한 Mongoose 라이프사이클 및 세션 기반 트랜잭션 컨텍스트 모듈입니다. Mongoose 연결을 모듈 시스템에 연결하여 자동 연결 관리 및 선택적 요청 범위 트랜잭션을 제공합니다.
+세션 인지형 트랜잭션 처리와 라이프사이클 친화적인 외부 연결 관리를 제공하는 fluo용 Mongoose 통합 패키지입니다.
 
 ## 목차
 
@@ -19,15 +19,14 @@ fluo 애플리케이션을 위한 Mongoose 라이프사이클 및 세션 기반
 
 ```bash
 pnpm add @fluojs/mongoose
-# mongoose도 함께 설치되어 있어야 합니다.
 pnpm add mongoose
 ```
 
 ## 사용 시점
 
-- Mongoose를 MongoDB ODM으로 사용하면서 fluo의 의존성 주입 및 라이프사이클 훅과 통합하고 싶을 때.
-- 서비스 전반에서 MongoDB 세션과 트랜잭션을 중앙에서 관리하고 싶을 때.
-- 애플리케이션 종료 시 자동 연결 정리(dispose)가 필요할 때.
+- Mongoose를 나머지 애플리케이션과 같은 DI 및 라이프사이클 모델에 연결하고 싶을 때.
+- 모든 서비스에서 MongoDB 세션과 트랜잭션을 임시 배관 코드 없이 하나의 wrapper로 다루고 싶을 때.
+- 요청 범위 트랜잭션을 interceptor로 명시적으로 켜고 싶을 때.
 
 ## 빠른 시작
 
@@ -51,6 +50,8 @@ const connection = mongoose.createConnection('mongodb://localhost:27017/test');
 class AppModule {}
 ```
 
+`MongooseModule.forRootAsync(...)`는 주입된 의존성과 동기 또는 비동기로 옵션을 반환하는 `useFactory`를 지원합니다. provider를 전역으로 노출해야 할 때는 최상위 async 등록 옵션에 `global`을 전달하세요. 해석된 옵션은 모듈 인스턴스 안에서 재사용되므로 연결 설정과 dispose hook이 모든 provider에서 일관되게 유지됩니다.
+
 ## 라이프사이클과 종료
 
 `MongooseModule`은 `MongooseConnection`을 fluo 애플리케이션 라이프사이클에 등록합니다. 이 패키지는 원본 Mongoose 연결을 직접 생성하거나 소유하지 않습니다. 애플리케이션 종료 시 외부 연결을 닫아야 한다면 `dispose` 훅을 전달하세요.
@@ -61,7 +62,7 @@ class AppModule {}
 2. 해당 Mongoose 세션은 `abortTransaction()`과 `endSession()` 정리를 끝냅니다.
 3. 설정한 `dispose(connection)` 훅은 활성 요청 트랜잭션이 모두 settled된 뒤에만 실행됩니다.
 
-`createMongoosePlatformStatusSnapshot(...)`은 트래픽 처리 중에는 `ready`, 요청 트랜잭션 drain 중에는 `shutting-down`, dispose 훅 완료 뒤에는 `stopped`를 보고합니다. 수동 `transaction()`도 요청 범위 트랜잭션과 같은 명시적 세션 계약을 사용하므로, 트랜잭션에 참여해야 하는 Mongoose 모델 작업에는 repository 코드가 `conn.currentSession()`을 전달해야 합니다.
+`createMongoosePlatformStatusSnapshot(...)`은 트래픽 처리 중에는 `ready`, 요청 트랜잭션 drain 중에는 `shutting-down`, dispose 훅 완료 뒤에는 `stopped`를 보고합니다. 상태 details에는 `sessionStrategy`, `transactionContext: 'als'`, 리소스 소유권, strict/session 지원 진단이 포함됩니다. 수동 `transaction()`도 요청 범위 트랜잭션과 같은 명시적 세션 계약을 사용하므로, 트랜잭션에 참여해야 하는 Mongoose 모델 작업에는 repository 코드가 `conn.currentSession()`을 전달해야 합니다.
 
 ## 공통 패턴
 
@@ -84,7 +85,7 @@ export class UserRepository {
 
 ### 수동 트랜잭션과 세션
 
-`conn.transaction()`을 사용하여 세션을 관리합니다. Prisma와 달리 Mongoose는 각 작업에 세션을 명시적으로 전달해야 합니다.
+`conn.transaction()`으로 세션 경계를 만들고, Mongoose 모델 작업에는 세션을 명시적으로 전달합니다.
 
 ```typescript
 await this.conn.transaction(async () => {
@@ -96,9 +97,11 @@ await this.conn.transaction(async () => {
 });
 ```
 
-### 자동 요청 트랜잭션
+감싼 연결이 `startSession()`을 구현하지 않으면 트랜잭션은 기본적으로 직접 실행으로 fallback합니다. fallback 대신 예외를 던지려면 `strictTransactions: true`를 설정합니다. 이때 오류 메시지는 `Transaction not supported: Mongoose connection does not implement startSession.`입니다.
+
+### 요청 범위 트랜잭션
 
-컨트롤러나 메서드에 `MongooseTransactionInterceptor`를 적용하면 전체 요청을 자동으로 MongoDB 세션으로 감쌉니다.
+컨트롤러나 메서드에 `MongooseTransactionInterceptor`를 적용하면 전체 요청을 MongoDB 세션으로 감쌉니다.
 
 ```typescript
 import { UseInterceptors } from '@fluojs/http';
@@ -108,6 +111,8 @@ import { MongooseTransactionInterceptor } from '@fluojs/mongoose';
 class UserController {}
 ```
 
+HTTP interceptor 밖에서 같은 request-aware transaction boundary가 필요하다면 `MongooseConnection.requestTransaction(...)`을 직접 사용할 수 있습니다. 중첩된 service transaction은 활성 session boundary를 재사용합니다.
+
 ## 공개 API
 
 - `MongooseModule.forRoot(options)` / `MongooseModule.forRootAsync(options)`
@@ -122,6 +127,7 @@ class UserController {}
 - `MongooseModuleOptions<TConnection>`
 - `MongooseConnectionLike`
 - `MongooseSessionLike`
+- `MongooseHandleProvider`
 
 ## 관련 패키지
 
@@ -131,6 +137,6 @@ class UserController {}
 
 ## 예제 소스
 
-- `packages/mongoose/src/vertical-slice.test.ts`: 표준 DTO → 서비스 → 리포지토리 → Mongoose 흐름 예제.
-- `packages/mongoose/src/module.test.ts`: 모듈 등록과 수명 주기 계약 예제.
-- `packages/mongoose/src/public-api.test.ts`: 공개 export 검증 예제.
+- `packages/mongoose/src/vertical-slice.test.ts`
+- `packages/mongoose/src/module.test.ts`
+- `packages/mongoose/src/public-api.test.ts`

package/README.md

@@ -48,6 +48,8 @@ const connection = mongoose.createConnection('mongodb://localhost:27017/test');
 class AppModule {}
 ```
 
+`MongooseModule.forRootAsync(...)` accepts injected dependencies and a `useFactory` that may return options synchronously or asynchronously. Pass `global` on the top-level async registration when the providers should be visible globally. The resolved options are reused for the module instance, so connection setup and disposal hooks stay consistent across all providers.
+
 ## 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.
@@ -58,7 +60,7 @@ Shutdown preserves request transaction cleanup order:
 2. Their Mongoose sessions finish `abortTransaction()` and `endSession()` cleanup.
 3. The configured `dispose(connection)` hook runs only after active request transactions have settled.
 
-`createMongoosePlatformStatusSnapshot(...)` reports `ready` while serving traffic, `shutting-down` while request transactions are draining, and `stopped` after the dispose hook completes. 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.
+`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'`, 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.
 
 ## Common Patterns
 
@@ -88,6 +90,8 @@ await this.conn.transaction(async () => {
 });
 ```
 
+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.
+
 ### Request-scoped transactions
 
 ```ts
@@ -98,6 +102,8 @@ import { MongooseTransactionInterceptor } from '@fluojs/mongoose';
 class UserController {}
 ```
 
+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.
+
 ## Public API
 
 - `MongooseModule.forRoot(options)` / `MongooseModule.forRootAsync(options)`
@@ -112,6 +118,7 @@ class UserController {}
 - `MongooseModuleOptions<TConnection>`
 - `MongooseConnectionLike`
 - `MongooseSessionLike`
+- `MongooseHandleProvider`
 
 ## Related Packages
 

package/dist/module.d.ts

@@ -2,6 +2,7 @@ import type { AsyncModuleOptions } from '@fluojs/core';
 import type { Provider } from '@fluojs/di';
 import { type ModuleType } from '@fluojs/runtime';
 import type { MongooseConnectionLike, MongooseModuleOptions } from './types.js';
+type MongooseAsyncModuleOptions<TConnection extends MongooseConnectionLike> = AsyncModuleOptions<Omit<MongooseModuleOptions<TConnection>, 'global'>> & Pick<MongooseModuleOptions<TConnection>, 'global'>;
 /**
  * Creates Mongoose providers for manual module composition.
  *
@@ -16,6 +17,7 @@ export declare class MongooseModule {
     /** Creates a module definition from static Mongoose options. */
     static forRoot<TConnection extends MongooseConnectionLike>(options: MongooseModuleOptions<TConnection>): ModuleType;
     /** Creates a module definition from DI-aware async Mongoose options. */
-    static forRootAsync<TConnection extends MongooseConnectionLike>(options: AsyncModuleOptions<MongooseModuleOptions<TConnection>>): ModuleType;
+    static forRootAsync<TConnection extends MongooseConnectionLike>(options: MongooseAsyncModuleOptions<TConnection>): ModuleType;
 }
+export {};
 //# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;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;AA4FhF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,sBAAsB,EAChF,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,QAAQ,EAAE,CAOZ;AAwBD;;GAEG;AACH,qBAAa,cAAc;IACzB,gEAAgE;IAChE,MAAM,CAAC,OAAO,CAAC,WAAW,SAAS,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAAG,UAAU;IAInH,wEAAwE;IACxE,MAAM,CAAC,YAAY,CAAC,WAAW,SAAS,sBAAsB,EAC5D,OAAO,EAAE,kBAAkB,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,GAC9D,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;AAKhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAahF,KAAK,0BAA0B,CAAC,WAAW,SAAS,sBAAsB,IAAI,kBAAkB,CAC9F,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CACnD,GAAG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AAiFvD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,sBAAsB,EAChF,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,QAAQ,EAAE,CAOZ;AA0BD;;GAEG;AACH,qBAAa,cAAc;IACzB,gEAAgE;IAChE,MAAM,CAAC,OAAO,CAAC,WAAW,SAAS,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAAG,UAAU;IAInH,wEAAwE;IACxE,MAAM,CAAC,YAAY,CAAC,WAAW,SAAS,sBAAsB,EAC5D,OAAO,EAAE,0BAA0B,CAAC,WAAW,CAAC,GAC/C,UAAU;CAGd"}

package/dist/module.js

@@ -70,6 +70,7 @@ function buildMongooseModule(options) {
   class MongooseRootModuleDefinition {}
   return defineModule(MongooseRootModuleDefinition, {
     exports: MONGOOSE_MODULE_EXPORTS,
+    global: options.global ?? false,
     providers: createMongooseProviders(options)
   });
 }
@@ -77,6 +78,7 @@ function buildMongooseModuleAsync(options) {
   class MongooseAsyncModuleDefinition {}
   return defineModule(MongooseAsyncModuleDefinition, {
     exports: MONGOOSE_MODULE_EXPORTS,
+    global: options.global ?? false,
     providers: createMongooseProvidersAsync(options)
   });
 }

package/dist/types.d.ts

@@ -27,6 +27,8 @@ export interface MongooseModuleOptions<TConnection extends MongooseConnectionLik
     connection: TConnection;
     /** Optional shutdown hook used to close the connection or surrounding driver resources. */
     dispose?: (connection: TConnection) => MaybePromise<void>;
+    /** Whether Mongoose providers should be visible globally. Defaults to `false`. */
+    global?: boolean;
     /**
      * Throws when transaction helpers are used against a connection that does not implement `startSession()`.
      *

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;CAC/C;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;;;;;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;CAC/C;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"}

package/package.json

@@ -9,7 +9,7 @@
     "transaction",
     "odm"
   ],
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/http": "^1.0.0-beta.1",
-    "@fluojs/di": "^1.0.0-beta.2",
-    "@fluojs/runtime": "^1.0.0-beta.2"
+    "@fluojs/http": "^1.0.0-beta.10",
+    "@fluojs/di": "^1.0.0-beta.6",
+    "@fluojs/core": "^1.0.0-beta.4",
+    "@fluojs/runtime": "^1.0.0-beta.11"
   },
   "peerDependencies": {
     "mongoose": ">=7.0.0"