@fluojs/drizzle 1.0.0-beta.1 → 1.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ko.md CHANGED
@@ -10,6 +10,10 @@
10
10
  - [사용 시점](#사용-시점)
11
11
  - [빠른 시작](#빠른-시작)
12
12
  - [주요 패턴](#주요-패턴)
13
+ - [repository에서 `DrizzleDatabase.current()` 사용하기](#repository에서-drizzledatabasecurrent-사용하기)
14
+ - [수동 트랜잭션 경계](#수동-트랜잭션-경계)
15
+ - [인터셉터 기반 요청 단위 트랜잭션](#인터셉터-기반-요청-단위-트랜잭션)
16
+ - [종료와 상태 계약](#종료와-상태-계약)
13
17
  - [수동 모듈 구성](#수동-모듈-구성)
14
18
  - [공개 API 개요](#공개-api-개요)
15
19
  - [관련 패키지](#관련-패키지)
@@ -86,6 +90,10 @@ await this.db.transaction(async () => {
86
90
  });
87
91
  ```
88
92
 
93
+ 중첩 호출은 활성 transaction boundary를 재사용합니다. 이미 boundary가 활성화되어 있는데 중첩 호출이 transaction option을 전달하면, 기존 transaction을 조용히 바꾸지 않고 해당 중첩 option을 거부합니다.
94
+
95
+ `database.transaction(...)`을 사용할 수 없고 `strictTransactions`가 `false`이면 `transaction()`과 `requestTransaction()`은 직접 실행으로 fallback합니다. 요청 범위 호출은 이 경우에도 `AbortSignal`을 존중합니다.
96
+
89
97
  ### 인터셉터 기반 요청 단위 트랜잭션
90
98
 
91
99
  ```ts
@@ -96,6 +104,18 @@ import { DrizzleTransactionInterceptor } from '@fluojs/drizzle';
96
104
  class UsersController {}
97
105
  ```
98
106
 
107
+ ### 종료와 상태 계약
108
+
109
+ `DrizzleTransactionInterceptor`는 각 HTTP 요청을 `DrizzleDatabase.requestTransaction(...)`으로 실행합니다. 애플리케이션 종료 중에는 `DrizzleDatabase`가 아직 활성 상태인 요청 트랜잭션을 abort하고, 해당 transaction callback이 settle되거나 rollback될 때까지 기다린 뒤 선택적 `dispose(database)` hook을 실행합니다. 이 순서는 pool이나 외부 관리 리소스를 닫기 전에 driver가 rollback/cleanup 작업을 끝낼 수 있게 보장합니다.
110
+
111
+ `createDrizzlePlatformStatusSnapshot(...)`과 `DrizzleDatabase.createPlatformStatusSnapshot()`은 같은 계약을 진단 surface에 노출합니다.
112
+
113
+ - Drizzle이 종료 중이거나 중지된 상태이면, 또는 `strictTransactions`가 켜져 있는데 `database.transaction(...)` 지원이 없으면 `readiness.status`는 `not-ready`입니다.
114
+ - 요청 트랜잭션을 drain하는 종료 중에는 `health.status`가 `degraded`이고, dispose 이후에는 `unhealthy`입니다.
115
+ - `details.activeRequestTransactions`, `details.lifecycleState`, `details.strictTransactions`, `details.supportsTransaction`은 현재 요청 트랜잭션과 트랜잭션 지원 상태를 설명합니다.
116
+ - `details.transactionContext: 'als'`는 요청 및 service transaction boundary가 사용하는 async-local transaction context를 나타냅니다.
117
+ - `ownership.externallyManaged: true`와 `ownership.ownsResources: false`는 이 패키지가 설정된 dispose hook은 실행하지만 underlying driver resource의 소유권을 주장하지 않는다는 뜻입니다.
118
+
99
119
  ## 수동 모듈 구성
100
120
 
101
121
  `DrizzleModule.forRoot(...)` / `forRootAsync(...)`를 사용해 Drizzle을 등록합니다. 커스텀 `defineModule(...)` 안에서 Drizzle 지원을 조합해야 할 때도 동일한 모듈 entrypoint를 import해서 사용하세요.
@@ -123,11 +143,14 @@ defineModule(ManualDrizzleModule, {
123
143
  - `DrizzleTransactionInterceptor`
124
144
  - `DRIZZLE_DATABASE`, `DRIZZLE_DISPOSE`, `DRIZZLE_OPTIONS`
125
145
  - `createDrizzlePlatformStatusSnapshot(...)`
146
+ - `DrizzleDatabaseLike`
147
+ - `DrizzleModuleOptions`
148
+ - `DrizzleHandleProvider`
126
149
 
127
150
  ### `DrizzleModule`
128
151
 
129
152
  - `DrizzleModule.forRoot(options)` / `DrizzleModule.forRootAsync(options)`
130
- - `forRootAsync(...)`는 `AsyncModuleOptions<DrizzleModuleOptions<...>>`를 받습니다.
153
+ - `forRootAsync(...)`는 database/dispose/transaction 설정을 factory에서 반환하는 DI-aware Drizzle 옵션을 받습니다. provider를 전역으로 노출해야 할 때는 최상위 async 등록 옵션에 `global`을 전달하세요.
131
154
  - `strictTransactions: true`를 설정하면 transaction 지원이 없는 database handle에서 예외를 던집니다.
132
155
 
133
156
  ## 관련 패키지
package/README.md CHANGED
@@ -10,6 +10,10 @@ Drizzle ORM integration for fluo with a transaction-aware database wrapper and a
10
10
  - [When to Use](#when-to-use)
11
11
  - [Quick Start](#quick-start)
12
12
  - [Common Patterns](#common-patterns)
13
+ - [Use `DrizzleDatabase.current()` inside repositories](#use-drizzledatabasecurrent-inside-repositories)
14
+ - [Manual transaction boundaries](#manual-transaction-boundaries)
15
+ - [Request-scoped transactions with an interceptor](#request-scoped-transactions-with-an-interceptor)
16
+ - [Shutdown and status contracts](#shutdown-and-status-contracts)
13
17
  - [Manual Module Composition](#manual-module-composition)
14
18
  - [Public API Overview](#public-api-overview)
15
19
  - [Related Packages](#related-packages)
@@ -86,6 +90,10 @@ await this.db.transaction(async () => {
86
90
  });
87
91
  ```
88
92
 
93
+ 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.
94
+
95
+ When `database.transaction(...)` is unavailable and `strictTransactions` is `false`, `transaction()` and `requestTransaction()` fall back to direct execution; request-scoped calls still honor `AbortSignal`.
96
+
89
97
  ### Request-scoped transactions with an interceptor
90
98
 
91
99
  ```ts
@@ -96,6 +104,18 @@ import { DrizzleTransactionInterceptor } from '@fluojs/drizzle';
96
104
  class UsersController {}
97
105
  ```
98
106
 
107
+ ### Shutdown and status contracts
108
+
109
+ `DrizzleTransactionInterceptor` runs each HTTP request through `DrizzleDatabase.requestTransaction(...)`. During application shutdown, `DrizzleDatabase` aborts any still-active request transaction, waits for its transaction callback to settle or roll back, and only then runs the optional `dispose(database)` hook. This ordering lets drivers finish rollback/cleanup work before pools or externally managed resources are closed.
110
+
111
+ `createDrizzlePlatformStatusSnapshot(...)` and `DrizzleDatabase.createPlatformStatusSnapshot()` expose the same contract to diagnostics surfaces:
112
+
113
+ - `readiness.status` is `not-ready` while Drizzle is shutting down or stopped, and when `strictTransactions` is enabled without `database.transaction(...)` support.
114
+ - `health.status` is `degraded` while request transactions are draining during shutdown and `unhealthy` after disposal.
115
+ - `details.activeRequestTransactions`, `details.lifecycleState`, `details.strictTransactions`, and `details.supportsTransaction` describe the current request transaction and transaction-capability state.
116
+ - `details.transactionContext: 'als'` identifies the async-local transaction context used by request and service transaction boundaries.
117
+ - `ownership.externallyManaged: true` and `ownership.ownsResources: false` mean the package runs your configured dispose hook but does not claim ownership of the underlying driver resources.
118
+
99
119
  ## Manual Module Composition
100
120
 
101
121
  Use `DrizzleModule.forRoot(...)` / `forRootAsync(...)` to register Drizzle. When you need to compose Drizzle support inside a custom `defineModule(...)` registration, import the module entrypoint there as well.
@@ -123,11 +143,14 @@ defineModule(ManualDrizzleModule, {
123
143
  - `DrizzleTransactionInterceptor`
124
144
  - `DRIZZLE_DATABASE`, `DRIZZLE_DISPOSE`, `DRIZZLE_OPTIONS`
125
145
  - `createDrizzlePlatformStatusSnapshot(...)`
146
+ - `DrizzleDatabaseLike`
147
+ - `DrizzleModuleOptions`
148
+ - `DrizzleHandleProvider`
126
149
 
127
150
  ### `DrizzleModule`
128
151
 
129
152
  - `DrizzleModule.forRoot(options)` / `DrizzleModule.forRootAsync(options)`
130
- - `forRootAsync(...)` accepts `AsyncModuleOptions<DrizzleModuleOptions<...>>`.
153
+ - `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.
131
154
  - Supports `strictTransactions: true` to throw if transaction support is missing.
132
155
 
133
156
  ## Related Packages
package/dist/module.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { AsyncModuleOptions } from '@fluojs/core';
2
2
  import { type ModuleType } from '@fluojs/runtime';
3
3
  import type { DrizzleDatabaseLike, DrizzleModuleOptions } from './types.js';
4
+ type DrizzleAsyncModuleOptions<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase, TTransactionOptions> = AsyncModuleOptions<Omit<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>, 'global'>> & Pick<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>, 'global'>;
4
5
  /**
5
6
  * Module entrypoint for wiring a Drizzle database into the Fluo runtime lifecycle.
6
7
  */
@@ -8,6 +9,7 @@ export declare class DrizzleModule {
8
9
  /** Creates a module definition from static Drizzle options. */
9
10
  static forRoot<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>): ModuleType;
10
11
  /** Creates a module definition from DI-aware async Drizzle options. */
11
- static forRootAsync<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: AsyncModuleOptions<DrizzleModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>>): ModuleType;
12
+ static forRootAsync<TDatabase extends DrizzleDatabaseLike<TTransactionDatabase, TTransactionOptions>, TTransactionDatabase = TDatabase, TTransactionOptions = unknown>(options: DrizzleAsyncModuleOptions<TDatabase, TTransactionDatabase, TTransactionOptions>): ModuleType;
12
13
  }
14
+ export {};
13
15
  //# sourceMappingURL=module.d.ts.map
@@ -1 +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;AA0I5E;;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,kBAAkB,CAAC,oBAAoB,CAAC,SAAS,EAAE,oBAAoB,EAAE,mBAAmB,CAAC,CAAC,GAAG,UAAU;CAGvH"}
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;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 CHANGED
@@ -56,6 +56,7 @@ function buildDrizzleModule(options) {
56
56
  class DrizzleRootModuleDefinition {}
57
57
  return defineModule(DrizzleRootModuleDefinition, {
58
58
  exports: DRIZZLE_MODULE_EXPORTS,
59
+ global: options.global ?? false,
59
60
  providers: createDrizzleRuntimeProviders({
60
61
  provide: DRIZZLE_NORMALIZED_OPTIONS,
61
62
  useValue: normalizeDrizzleModuleOptions(options)
@@ -66,6 +67,7 @@ function buildDrizzleModuleAsync(options) {
66
67
  class DrizzleAsyncModuleDefinition {}
67
68
  return defineModule(DrizzleAsyncModuleDefinition, {
68
69
  exports: DRIZZLE_MODULE_EXPORTS,
70
+ global: options.global ?? false,
69
71
  providers: createDrizzleProvidersAsync(options)
70
72
  });
71
73
  }
package/dist/types.d.ts CHANGED
@@ -22,6 +22,8 @@ export interface DrizzleModuleOptions<TDatabase extends DrizzleDatabaseLike<TTra
22
22
  database: TDatabase;
23
23
  /** Optional shutdown hook used to close pools or driver resources during application shutdown. */
24
24
  dispose?: (database: TDatabase) => MaybePromise<void>;
25
+ /** Whether Drizzle providers should be visible globally. Defaults to `false`. */
26
+ global?: boolean;
25
27
  /**
26
28
  * Throws when transaction helpers are used against a database that does not expose `transaction(...)`.
27
29
  *
@@ -1 +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,KAAK,0BAA0B,CAAC,oBAAoB,EAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtH,KAAK,wBAAwB,CAAC,oBAAoB,EAAE,mBAAmB,IAAI,CAAC,CAAC,EAC3E,QAAQ,EAAE,0BAA0B,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAC7D,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,oBAAoB,GAAG,OAAO,EAAE,mBAAmB,GAAG,OAAO;IAChG,WAAW,CAAC,EAAE,wBAAwB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,CAAC;CACnF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,SAAS,EAAE,mBAAmB,GAAG,OAAO;IACrL,8EAA8E;IAC9E,QAAQ,EAAE,SAAS,CAAC;IACpB,kGAAkG;IAClG,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,SAAS,EAAE,mBAAmB,GAAG,OAAO;IACtL,mGAAmG;IACnG,OAAO,IAAI,SAAS,GAAG,oBAAoB,CAAC;IAC5C;;;;;;;OAOG;IACH,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,CAAC;IAC7G;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjF"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,KAAK,0BAA0B,CAAC,oBAAoB,EAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtH,KAAK,wBAAwB,CAAC,oBAAoB,EAAE,mBAAmB,IAAI,CAAC,CAAC,EAC3E,QAAQ,EAAE,0BAA0B,CAAC,oBAAoB,EAAE,CAAC,CAAC,EAC7D,OAAO,CAAC,EAAE,mBAAmB,KAC1B,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,oBAAoB,GAAG,OAAO,EAAE,mBAAmB,GAAG,OAAO;IAChG,WAAW,CAAC,EAAE,wBAAwB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,CAAC;CACnF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,SAAS,EAAE,mBAAmB,GAAG,OAAO;IACrL,8EAA8E;IAC9E,QAAQ,EAAE,SAAS,CAAC;IACpB,kGAAkG;IAClG,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IACtD,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,mBAAmB,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,SAAS,EAAE,mBAAmB,GAAG,OAAO;IACtL,mGAAmG;IACnG,OAAO,IAAI,SAAS,GAAG,oBAAoB,CAAC;IAC5C;;;;;;;OAOG;IACH,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,CAAC;IAC7G;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjF"}
package/package.json CHANGED
@@ -9,7 +9,7 @@
9
9
  "transaction",
10
10
  "als"
11
11
  ],
12
- "version": "1.0.0-beta.1",
12
+ "version": "1.0.0-beta.3",
13
13
  "private": false,
14
14
  "license": "MIT",
15
15
  "repository": {
@@ -36,10 +36,10 @@
36
36
  "dist"
37
37
  ],
38
38
  "dependencies": {
39
- "@fluojs/runtime": "^1.0.0-beta.1",
40
- "@fluojs/di": "^1.0.0-beta.1",
41
- "@fluojs/core": "^1.0.0-beta.1",
42
- "@fluojs/http": "^1.0.0-beta.1"
39
+ "@fluojs/core": "^1.0.0-beta.4",
40
+ "@fluojs/http": "^1.0.0-beta.10",
41
+ "@fluojs/di": "^1.0.0-beta.6",
42
+ "@fluojs/runtime": "^1.0.0-beta.11"
43
43
  },
44
44
  "peerDependencies": {
45
45
  "drizzle-orm": ">=0.30.0"