@fluojs/prisma 1.0.0-beta.5 → 1.0.0-beta.6

package/README.ko.md

@@ -14,6 +14,7 @@ fluo 애플리케이션을 위한 Prisma 라이프사이클 및 ALS 기반 트
   - [여러 클라이언트를 위한 이름 있는 등록](#여러-클라이언트를-위한-이름-있는-등록)
   - [수동 트랜잭션](#수동-트랜잭션)
   - [자동 요청 트랜잭션](#자동-요청-트랜잭션)
+  - [종료와 status 계약](#종료와-status-계약)
   - [비동기 설정과 격리](#비동기-설정과-격리)
   - [수동 모듈 조합](#수동-모듈-조합)
 - [공개 API 개요](#공개-api-개요)
@@ -135,6 +136,18 @@ class UserController {
 
 `PrismaTransactionInterceptor`는 기본 이름 없는 `PrismaService`를 대상으로 합니다. 이름 있는 다중 클라이언트 등록에서는 해당 이름의 `PrismaService`를 주입한 뒤 필요한 위치에서 명시적으로 `transaction()` / `requestTransaction()` 경계를 여세요.
 
+### 종료와 status 계약
+
+`PrismaService.requestTransaction(...)`은 정상 serving 전과 중에는 사용할 수 있지만, 애플리케이션 종료가 시작된 뒤에는 새 요청 범위 트랜잭션을 거부합니다. 종료 중에는 열린 요청 트랜잭션을 abort하고, 바깥 트랜잭션 경계가 settle될 때까지 추적한 뒤, 모두 drain한 다음 `$disconnect()`를 실행합니다. 기존 수동 `transaction(...)` 경계 안에서 열린 중첩 `requestTransaction(...)` 호출도 여기에 포함됩니다. 이 호출은 ambient Prisma transaction client를 재사용하고, 바깥 경계가 끝날 때까지 `details.activeRequestTransactions`에 남으며, 두 번째 Prisma 트랜잭션을 열지 않습니다.
+
+`createPrismaPlatformStatusSnapshot(...)`와 `PrismaService.createPlatformStatusSnapshot()`은 같은 라이프사이클 계약을 진단 surface에 노출합니다.
+
+- `readiness.status`는 Prisma가 종료 중이거나 stopped 상태일 때, 그리고 `strictTransactions`가 켜져 있는데 `$transaction(...)`을 지원하지 않을 때 `not-ready`입니다.
+- `health.status`는 종료 중 요청 트랜잭션을 drain하는 동안 `degraded`, disconnect 이후 `unhealthy`입니다.
+- `details.activeRequestTransactions`, `details.lifecycleState`, `details.strictTransactions`, `details.supportsTransaction`, `details.transactionAbortSignalSupport`는 현재 요청 트랜잭션과 트랜잭션 capability 상태를 설명합니다.
+- `details.transactionContext: 'als'`는 요청 및 서비스 트랜잭션 경계가 사용하는 async-local transaction context를 식별합니다.
+- `ownership.externallyManaged: false`와 `ownership.ownsResources: true`는 패키지가 fluo 애플리케이션 라이프사이클 안에서 등록된 클라이언트의 `$connect()` / `$disconnect()` lifecycle hook을 소유한다는 의미입니다.
+
 ### 비동기 설정과 격리
 
 주입된 설정이나 다른 비동기 소스에서 Prisma 클라이언트를 만들어야 할 때는 `PrismaModule.forRootAsync(...)`를 사용하세요. 비동기 factory는 애플리케이션 컨테이너마다 한 번 resolve되며, 테스트나 여러 앱을 띄우는 프로세스에서 같은 모듈 정의를 재사용하더라도 별도 bootstrap 사이에서 공유되지 않습니다.

package/README.md

@@ -14,6 +14,7 @@ Prisma lifecycle and ALS-backed transaction context for fluo applications. Conne
   - [Named Registrations for Multiple Clients](#named-registrations-for-multiple-clients)
   - [Manual Transactions](#manual-transactions)
   - [Automatic Request Transactions](#automatic-request-transactions)
+  - [Shutdown and Status Contracts](#shutdown-and-status-contracts)
   - [Async Configuration and Isolation](#async-configuration-and-isolation)
   - [Manual Module Composition](#manual-module-composition)
 - [Public API Overview](#public-api-overview)
@@ -135,6 +136,18 @@ class UserController {
 
 `PrismaTransactionInterceptor` targets the default unnamed `PrismaService`. For named multi-client registrations, inject the corresponding named `PrismaService` and open explicit `transaction()` / `requestTransaction()` boundaries where needed.
 
+### Shutdown and Status Contracts
+
+`PrismaService.requestTransaction(...)` is available before and during normal serving, but new request-scoped transactions are rejected once application shutdown has started. During shutdown, open request transactions are aborted, tracked until their outer transaction boundary has settled, and drained before `$disconnect()` runs. This includes nested `requestTransaction(...)` calls opened inside an existing manual `transaction(...)` boundary: they reuse the ambient Prisma transaction client, stay visible in `details.activeRequestTransactions` until the outer boundary finishes, and do not open a second Prisma transaction.
+
+`createPrismaPlatformStatusSnapshot(...)` and `PrismaService.createPlatformStatusSnapshot()` expose the same lifecycle contract to diagnostics surfaces:
+
+- `readiness.status` is `not-ready` while Prisma is shutting down or stopped, and when `strictTransactions` is enabled without `$transaction(...)` support.
+- `health.status` is `degraded` while request transactions are draining during shutdown and `unhealthy` after disconnect.
+- `details.activeRequestTransactions`, `details.lifecycleState`, `details.strictTransactions`, `details.supportsTransaction`, and `details.transactionAbortSignalSupport` describe the current request transaction and transaction-capability state.
+- `details.transactionContext: 'als'` identifies the async-local transaction context used by request and service transaction boundaries.
+- `ownership.externallyManaged: false` and `ownership.ownsResources: true` mean the package owns the registered client's `$connect()` / `$disconnect()` lifecycle hooks inside the fluo application lifecycle.
+
 ### Async Configuration and Isolation
 
 Use `PrismaModule.forRootAsync(...)` when the Prisma client must be created from injected configuration or another async source. The async factory is resolved once per application container and is not shared across separate bootstraps, even when the same module definition is reused in tests or multi-app processes.

package/dist/service.d.ts

@@ -77,6 +77,10 @@ export declare class PrismaService<TClient extends PrismaClientLike<TTransaction
      * error type/message depends on the runtime abort implementation.
      */
     requestTransaction<T>(fn: () => Promise<T>, signal?: AbortSignal, options?: TTransactionOptions): Promise<T>;
+    private runWithRequestTransactionClient;
+    private runNestedRequestTransaction;
+    private assertRequestTransactionsAvailable;
+    private throwIfRequestAborted;
     private runRequestTransactionWithAbortSignal;
     private canAttemptTransactionAbortSignalOption;
     private runTransactionWithAbortSignalFallback;

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK3E,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAC7B,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAKpB,UAAU,oBAAoB;IAC5B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAcD;;;;;;GAMG;AACH,qBACa,aAAa,CACxB,OAAO,SAAS,gBAAgB,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,EACzE,kBAAkB,GAAG,4BAA4B,CAAC,OAAO,CAAC,EAC1D,mBAAmB,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAE5D,YAAW,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,CAAC,EAAE,YAAY,EAAE,qBAAqB;IAQpH,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAPjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA+C;IAC5E,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,6BAA6B,CAA4C;IACjF,OAAO,CAAC,cAAc,CAAgE;gBAGnE,MAAM,EAAE,OAAO,EACf,cAAc,GAAE,oBAAoD;IAGvF;;;;;;;;;OASG;IACH,OAAO,IAAI,OAAO,GAAG,kBAAkB;YAIzB,wBAAwB;IA2BhC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5C;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAQrF;;;;;;;;;;;;;;;;;;OAkBG;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;IAiBlH,OAAO,CAAC,oCAAoC;IAY5C,OAAO,CAAC,sCAAsC;YAYhC,qCAAqC;IAyBnD,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,0BAA0B;IAWlC,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,+BAA+B;CAGxC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK3E,OAAO,KAAK,EACV,4BAA4B,EAC5B,6BAA6B,EAC7B,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB,UAAU,oBAAoB;IAC5B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAoBD;;;;;;GAMG;AACH,qBACa,aAAa,CACxB,OAAO,SAAS,gBAAgB,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,EACzE,kBAAkB,GAAG,4BAA4B,CAAC,OAAO,CAAC,EAC1D,mBAAmB,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAE5D,YAAW,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,CAAC,EAAE,YAAY,EAAE,qBAAqB;IAQpH,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAPjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmE;IAChG,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,6BAA6B,CAA4C;IACjF,OAAO,CAAC,cAAc,CAAgE;gBAGnE,MAAM,EAAE,OAAO,EACf,cAAc,GAAE,oBAAoD;IAGvF;;;;;;;;;OASG;IACH,OAAO,IAAI,OAAO,GAAG,kBAAkB;YAIzB,wBAAwB;IAuChC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5C;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;IAQrF;;;;;;;;;;;;;;;;;;OAkBG;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;YAkCpG,+BAA+B;YAuB/B,2BAA2B;IAqCzC,OAAO,CAAC,kCAAkC;IAM1C,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,oCAAoC;IAY5C,OAAO,CAAC,sCAAsC;YAYhC,qCAAqC;IAyBnD,OAAO,CAAC,6BAA6B;IAUrC,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,0BAA0B;IAWlC,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,+BAA+B;CAGxC"}

package/dist/service.js

@@ -5,11 +5,12 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { createRequestAbortContext, raceWithAbort, trackActiveRequestTransaction, untrackActiveRequestTransaction } from '@fluojs/runtime';
+import { createAbortError, createRequestAbortContext, raceWithAbort, trackActiveRequestTransaction, untrackActiveRequestTransaction } from '@fluojs/runtime';
 import { Inject } from '@fluojs/core';
 import { createPrismaPlatformStatusSnapshot } from './status.js';
 import { PRISMA_CLIENT, PRISMA_OPTIONS } from './tokens.js';
 const NESTED_TRANSACTION_OPTIONS_NOT_SUPPORTED_ERROR = 'Nested Prisma transaction options are not supported because the active transaction context is reused.';
+const REQUEST_TRANSACTION_UNAVAILABLE_ERROR = 'Prisma request transactions are not available during shutdown.';
 let _PrismaService;
 /**
  * Prisma runtime facade that owns lifecycle hooks and transaction context access.
@@ -44,7 +45,7 @@ class PrismaService {
    * @returns The request/transaction-scoped client when a transaction is active; otherwise the root client.
    */
   current() {
-    return this.transactions.getStore() ?? this.client;
+    return this.transactions.getStore()?.client ?? this.client;
   }
   async runWithTransactionClient(fn, run, options) {
     if (this.transactions.getStore()) {
@@ -59,7 +60,17 @@ class PrismaService {
       }
       return fn();
     }
-    return run(transactionClient => this.transactions.run(transactionClient, fn), options);
+    const deferredRequestTransactionHandles = new Set();
+    try {
+      return await run(transactionClient => this.transactions.run({
+        client: transactionClient,
+        deferredRequestTransactionHandles
+      }, fn), options);
+    } finally {
+      for (const handle of deferredRequestTransactionHandles) {
+        this.untrackActiveRequestTransaction(handle);
+      }
+    }
   }
   async onModuleInit() {
     if (typeof this.client.$connect === 'function') {
@@ -138,15 +149,72 @@ class PrismaService {
    * error type/message depends on the runtime abort implementation.
    */
   async requestTransaction(fn, signal, options) {
+    const current = this.transactions.getStore();
+    if (current) {
+      if (options !== undefined) {
+        throw new Error(NESTED_TRANSACTION_OPTIONS_NOT_SUPPORTED_ERROR);
+      }
+      return this.runNestedRequestTransaction(current, fn, signal);
+    }
+    this.assertRequestTransactionsAvailable();
     const abortContext = createRequestAbortContext(signal);
     const active = this.trackActiveRequestTransaction(abortContext.controller);
     try {
-      return await this.runWithTransactionClient(() => raceWithAbort(fn, abortContext.signal), (callback, transactionOptions) => this.runRequestTransactionWithAbortSignal(callback, abortContext.signal, transactionOptions), options);
+      const result = await this.runWithRequestTransactionClient(() => raceWithAbort(fn, abortContext.signal), (callback, transactionOptions) => this.runRequestTransactionWithAbortSignal(callback, abortContext.signal, transactionOptions), options, abortContext.signal);
+      this.throwIfRequestAborted(abortContext.signal);
+      return result;
     } finally {
       abortContext.cleanup();
       this.untrackActiveRequestTransaction(active);
     }
   }
+  async runWithRequestTransactionClient(fn, run, options, signal) {
+    if (typeof this.client.$transaction !== 'function') {
+      if (this.serviceOptions.strictTransactions) {
+        throw new Error('Transaction not supported: Prisma client does not implement $transaction.');
+      }
+      return fn();
+    }
+    return run(transactionClient => this.transactions.run({
+      client: transactionClient,
+      requestAbortSignal: signal
+    }, fn), options);
+  }
+  async runNestedRequestTransaction(current, fn, signal) {
+    if (current.requestAbortSignal) {
+      if (signal) {
+        return raceWithAbort(fn, signal);
+      }
+      return fn();
+    }
+    this.assertRequestTransactionsAvailable();
+    const abortContext = createRequestAbortContext(signal);
+    const active = this.trackActiveRequestTransaction(abortContext.controller);
+    current.deferredRequestTransactionHandles?.add(active);
+    try {
+      const result = await this.transactions.run({
+        client: current.client,
+        requestAbortSignal: abortContext.signal
+      }, () => raceWithAbort(fn, abortContext.signal));
+      this.throwIfRequestAborted(abortContext.signal);
+      return result;
+    } finally {
+      abortContext.cleanup();
+      if (!current.deferredRequestTransactionHandles) {
+        this.untrackActiveRequestTransaction(active);
+      }
+    }
+  }
+  assertRequestTransactionsAvailable() {
+    if (this.lifecycleState === 'shutting-down' || this.lifecycleState === 'stopped') {
+      throw new Error(REQUEST_TRANSACTION_UNAVAILABLE_ERROR);
+    }
+  }
+  throwIfRequestAborted(signal) {
+    if (signal.aborted) {
+      throw createAbortError(signal.reason);
+    }
+  }
   runRequestTransactionWithAbortSignal(callback, signal, options) {
     if (!this.canAttemptTransactionAbortSignalOption(options)) {
       return this.client.$transaction(callback, options);

package/dist/status.js

@@ -63,8 +63,8 @@ export function createPrismaPlatformStatusSnapshot(input) {
     },
     health: createHealth(input),
     ownership: {
-      externallyManaged: true,
-      ownsResources: false
+      externallyManaged: false,
+      ownsResources: true
     },
     readiness: createReadiness(input)
   };

package/package.json

@@ -9,7 +9,7 @@
     "transaction",
     "als"
   ],
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.5",
+    "@fluojs/core": "^1.0.0-beta.6",
     "@fluojs/validation": "^1.0.0-beta.4",
-    "@fluojs/http": "^1.0.0-beta.10",
-    "@fluojs/di": "^1.0.0-beta.7",
+    "@fluojs/http": "^1.0.0-beta.11",
+    "@fluojs/di": "^1.0.0-beta.8",
     "@fluojs/runtime": "^1.0.0-beta.12"
   },
   "peerDependencies": {