sonamu 0.10.8 → 0.10.9

package/src/database/__tests__/transaction-scope.test.ts

@@ -0,0 +1,227 @@
+import { type Knex } from "knex";
+import { describe, expect, it } from "vitest";
+
+import { type DBPreset, DBClass } from "../db";
+import { PuriTransactionWrapper } from "../puri-wrapper";
+import { UpsertBuilder } from "../upsert-builder";
+
+type TransactionScopeDB = DBClass & {
+  runWithTransactionScope?<T>(
+    preset: DBPreset,
+    transaction: PuriTransactionWrapper,
+    callback: () => Promise<T>,
+  ): Promise<T>;
+};
+
+function createTransactionWrapper(): PuriTransactionWrapper {
+  return new PuriTransactionWrapper({} as Knex.Transaction, new UpsertBuilder());
+}
+
+function createDeferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+function expectScopeRunner(db: TransactionScopeDB) {
+  expect(db.runWithTransactionScope).toBeTypeOf("function");
+  return db.runWithTransactionScope;
+}
+
+describe("DB.runWithTransactionScope", () => {
+  it("저장소가 없어도 루트 scope를 설치하고 콜백 결과를 반환한 뒤 정리한다", async () => {
+    const db = new DBClass() as TransactionScopeDB;
+    const transaction = createTransactionWrapper();
+    const runScope = expectScopeRunner(db);
+    if (!runScope) return;
+
+    let callbackContext: ReturnType<DBClass["getTransactionContext"]> | undefined;
+    const result = await runScope.call(db, "w", transaction, async () => {
+      callbackContext = db.getTransactionContext();
+      expect(db.transactionStorage.getStore()).toBe(callbackContext);
+      expect(callbackContext.getActiveTransaction()).toBe(transaction);
+      expect(callbackContext.getTransaction("w")).toBe(transaction);
+      return "완료";
+    });
+
+    expect(result).toBe("완료");
+    expect(callbackContext?.getActiveTransaction()).toBeUndefined();
+    expect(callbackContext?.getTransaction("w")).toBeUndefined();
+    expect(db.transactionStorage.getStore()).toBeUndefined();
+  });
+
+  it("scope 안에서 생성된 detached descendant가 완료된 자식 트랜잭션을 다시 사용하지 않는다", async () => {
+    const db = new DBClass() as TransactionScopeDB;
+    const parentTransaction = createTransactionWrapper();
+    const childTransaction = createTransactionWrapper();
+    const descendantReady = createDeferred();
+    const resumeDescendant = createDeferred();
+    const runScope = expectScopeRunner(db);
+    if (!runScope) return;
+
+    let parentContext: ReturnType<DBClass["getTransactionContext"]> | undefined;
+    let childContext: ReturnType<DBClass["getTransactionContext"]> | undefined;
+
+    await runScope.call(db, "r", parentTransaction, async () => {
+      parentContext = db.getTransactionContext();
+
+      let descendantPromise:
+        | Promise<{
+            context: ReturnType<DBClass["getTransactionContext"]>;
+            active: PuriTransactionWrapper | undefined;
+            write: PuriTransactionWrapper | undefined;
+            read: PuriTransactionWrapper | undefined;
+          }>
+        | undefined;
+
+      childContext = await runScope.call(db, "w", childTransaction, async () => {
+        const scopedContext = db.getTransactionContext();
+        descendantPromise = (async () => {
+          descendantReady.resolve();
+          await resumeDescendant.promise;
+          const context = db.getTransactionContext();
+          return {
+            context,
+            active: context.getActiveTransaction(),
+            write: context.getTransaction("w"),
+            read: context.getTransaction("r"),
+          };
+        })();
+
+        await descendantReady.promise;
+        return scopedContext;
+      });
+
+      expect(db.getTransactionContext()).toBe(parentContext);
+      expect(childContext.getActiveTransaction()).toBe(parentTransaction);
+      expect(childContext.getTransaction("w")).toBeUndefined();
+      expect(childContext.getTransaction("r")).toBe(parentTransaction);
+
+      resumeDescendant.resolve();
+      if (!descendantPromise) {
+        throw new Error("detached descendant가 생성되지 않았습니다");
+      }
+      const descendantResult = await descendantPromise;
+
+      expect(descendantResult.context).toBe(childContext);
+      expect(descendantResult.active).toBe(parentTransaction);
+      expect(descendantResult.write).toBeUndefined();
+      expect(descendantResult.read).toBe(parentTransaction);
+    });
+
+    expect(parentContext?.getActiveTransaction()).toBeUndefined();
+    expect(parentContext?.getTransaction("r")).toBeUndefined();
+    expect(childContext?.getActiveTransaction()).toBeUndefined();
+    expect(childContext?.getTransaction("r")).toBeUndefined();
+    expect(db.transactionStorage.getStore()).toBeUndefined();
+  });
+
+  it("같거나 다른 preset의 중첩 범위를 복원하고 같은 오류를 다시 던진다", async () => {
+    const db = new DBClass() as TransactionScopeDB;
+    const outer = createTransactionWrapper();
+    const samePresetInner = createTransactionWrapper();
+    const differentPresetInner = createTransactionWrapper();
+    const expectedError = new Error("의도한 scope 오류");
+    const runScope = expectScopeRunner(db);
+    if (!runScope) return;
+
+    await runScope.call(db, "w", outer, async () => {
+      const outerContext = db.getTransactionContext();
+      expect(outerContext.getActiveTransaction()).toBe(outer);
+
+      await runScope.call(db, "w", samePresetInner, async () => {
+        expect(db.getTransactionContext().getActiveTransaction()).toBe(samePresetInner);
+        expect(db.getTransactionContext().getTransaction("w")).toBe(samePresetInner);
+      });
+      expect(db.getTransactionContext()).toBe(outerContext);
+      expect(outerContext.getActiveTransaction()).toBe(outer);
+
+      await expect(
+        runScope.call(db, "fixture", differentPresetInner, async () => {
+          const innerContext = db.getTransactionContext();
+          expect(innerContext.getActiveTransaction()).toBe(differentPresetInner);
+          expect(innerContext.getTransaction("w")).toBe(outer);
+          expect(innerContext.getTransaction("fixture")).toBe(differentPresetInner);
+          throw expectedError;
+        }),
+      ).rejects.toBe(expectedError);
+
+      expect(db.getTransactionContext()).toBe(outerContext);
+      expect(outerContext.getActiveTransaction()).toBe(outer);
+      expect(outerContext.getTransaction("fixture")).toBeUndefined();
+    });
+
+    expect(db.transactionStorage.getStore()).toBeUndefined();
+  });
+
+  it("겹치는 sibling 범위가 완료 순서와 무관하게 서로의 활성 트랜잭션을 보지 않는다", async () => {
+    const db = new DBClass() as TransactionScopeDB;
+    const parentTransaction = createTransactionWrapper();
+    const firstTransaction = createTransactionWrapper();
+    const secondTransaction = createTransactionWrapper();
+    const firstReady = createDeferred();
+    const secondReady = createDeferred();
+    const firstExited = createDeferred();
+    const runScope = expectScopeRunner(db);
+    if (!runScope) return;
+
+    let firstContext: ReturnType<DBClass["getTransactionContext"]> | undefined;
+    let secondContext: ReturnType<DBClass["getTransactionContext"]> | undefined;
+
+    await runScope.call(db, "r", parentTransaction, async () => {
+      const parentContext = db.getTransactionContext();
+      const firstPromise = runScope.call(db, "w", firstTransaction, async () => {
+        firstReady.resolve();
+        await secondReady.promise;
+        return {
+          context: db.getTransactionContext(),
+          active: db.getTransactionContext().getActiveTransaction(),
+          write: db.getTransactionContext().getTransaction("w"),
+          inheritedRead: db.getTransactionContext().getTransaction("r"),
+        };
+      });
+
+      await firstReady.promise;
+      const secondPromise = runScope.call(db, "w", secondTransaction, async () => {
+        secondReady.resolve();
+        await firstExited.promise;
+        return {
+          context: db.getTransactionContext(),
+          active: db.getTransactionContext().getActiveTransaction(),
+          write: db.getTransactionContext().getTransaction("w"),
+          inheritedRead: db.getTransactionContext().getTransaction("r"),
+        };
+      });
+
+      const firstResult = await firstPromise;
+      firstExited.resolve();
+      const secondResult = await secondPromise;
+      firstContext = firstResult.context;
+      secondContext = secondResult.context;
+
+      expect(firstResult.context).not.toBe(secondResult.context);
+      expect(firstResult.active).toBe(firstTransaction);
+      expect(firstResult.write).toBe(firstTransaction);
+      expect(firstResult.inheritedRead).toBe(parentTransaction);
+      expect(secondResult.active).toBe(secondTransaction);
+      expect(secondResult.write).toBe(secondTransaction);
+      expect(secondResult.inheritedRead).toBe(parentTransaction);
+      expect(firstResult.context.getActiveTransaction()).toBe(parentTransaction);
+      expect(secondResult.context.getActiveTransaction()).toBe(parentTransaction);
+      expect(db.getTransactionContext()).toBe(parentContext);
+      expect(parentContext.getActiveTransaction()).toBe(parentTransaction);
+    });
+
+    expect(firstContext?.getActiveTransaction()).toBeUndefined();
+    expect(secondContext?.getActiveTransaction()).toBeUndefined();
+    expect(db.transactionStorage.getStore()).toBeUndefined();
+  });
+
+  it("기존 bootstrap helper를 런타임 API로 노출하지 않는다", () => {
+    const db = new DBClass();
+
+    expect(db).not.toHaveProperty("runWithTransaction");
+  });
+});

package/src/database/base-model.ts

@@ -67,6 +67,15 @@ export class BaseModelClass<
     return new PuriWrapper(db, new UpsertBuilder());
   }
 
+  private getSubsetQueryPuri(): PuriWrapper {
+    const activeTransaction = DB.getTransactionContext().getActiveTransaction();
+    if (activeTransaction) {
+      return activeTransaction;
+    }
+
+    return new PuriWrapper(this.getDB("r"), new UpsertBuilder());
+  }
+
   async destroy() {
     return DB.destroy();
   }
@@ -120,7 +129,7 @@ export class BaseModelClass<
       throw new Error("subsetQueries is not defined");
     }
 
-    const puriWrapper = new PuriWrapper(this.getDB("r"), new UpsertBuilder());
+    const puriWrapper = this.getSubsetQueryPuri();
     const qb = this.subsetQueries[subset]?.(puriWrapper);
 
     // NonAllowedAsSingleTable: 단일 테이블 컬럼 접근 방지용 마커
@@ -201,6 +210,8 @@ export class BaseModelClass<
     }
 
     const { num, page } = queryParams;
+    // 모든 로더가 root query와 같은 연결을 사용하도록 실행 시점의 knex에서 한 번만 파생한다.
+    const puriWrapper = new PuriWrapper(qb.knex, new UpsertBuilder());
 
     // COUNT 쿼리 실행 (queryMode: list일 때는 0 리턴)
     const total = await this.executeCountQuery(qb, queryParams, debug, optimizeCountQuery);
@@ -210,7 +221,15 @@ export class BaseModelClass<
     }
 
     // LIST 쿼리 실행
-    const computedRows = await this.executeListQuery(subset, qb, queryParams, num, page, debug);
+    const computedRows = await this.executeListQuery(
+      subset,
+      qb,
+      queryParams,
+      num,
+      page,
+      debug,
+      puriWrapper,
+    );
 
     // Enhancer 적용
     const enhancer = (params as any).enhancers?.[subset];
@@ -457,6 +476,7 @@ export class BaseModelClass<
     num: number,
     page: number,
     debug: boolean,
+    puriWrapper: PuriWrapper,
   ): Promise<any[]> {
     if (params.queryMode === "count") {
       return [];
@@ -478,7 +498,7 @@ export class BaseModelClass<
     // 로더 처리
     const loaders = (this.loaderQueries as any)[subset];
     if (loaders && Array.isArray(loaders)) {
-      unloadedRows = await this.processLoaders(unloadedRows, loaders, debug);
+      unloadedRows = await this.processLoaders(unloadedRows, loaders, debug, puriWrapper);
     }
 
     return this.hydrate(unloadedRows);
@@ -487,12 +507,17 @@ export class BaseModelClass<
   /**
    * 재귀적 로더 처리
    */
-  private async processLoaders(rows: any[], loaders: any[], debug: boolean): Promise<any[]> {
+  private async processLoaders(
+    rows: any[],
+    loaders: any[],
+    debug: boolean,
+    puriWrapper: PuriWrapper,
+  ): Promise<any[]> {
     for (const resolveLoader of loaders) {
       const { as, refId, qb: resolveLoaderQbFn, loaders: nestedLoaders } = resolveLoader;
 
       const resolveLoaderQb = resolveLoaderQbFn(
-        new PuriWrapper(this.getDB("r"), new UpsertBuilder()),
+        puriWrapper,
         rows.map((row) => row[refId]),
       );
 
@@ -504,7 +529,7 @@ export class BaseModelClass<
 
       // 중첩 loaders가 있으면 재귀 처리
       if (nestedLoaders && nestedLoaders.length > 0) {
-        loadedRows = await this.processLoaders(loadedRows, nestedLoaders, debug);
+        loadedRows = await this.processLoaders(loadedRows, nestedLoaders, debug, puriWrapper);
       }
 
       const subRowGroups = group(loadedRows, (row) => row.refId);

package/src/database/db.ts

@@ -6,6 +6,7 @@ import { type Knex } from "knex";
 import { type DatabaseConfig, type SonamuConfig } from "../api/config";
 import { getSonamuEnvironment, type EnvironmentSnapshots, type SonamuEnvironment } from "../env";
 import { createKnexInstance } from "./knex";
+import { type PuriTransactionWrapper } from "./puri-wrapper";
 import { TransactionContext } from "./transaction-context";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -155,8 +156,22 @@ export class DBClass {
 
   public transactionStorage = new AsyncLocalStorage<TransactionContext>();
 
-  public runWithTransaction<T>(callback: () => Promise<T>): Promise<T> {
-    return this.transactionStorage.run(new TransactionContext(), callback);
+  public runWithTransactionScope<T>(
+    preset: DBPreset,
+    transaction: PuriTransactionWrapper,
+    callback: () => Promise<T>,
+  ): Promise<T> {
+    const parentContext = this.transactionStorage.getStore();
+    const transactionContext = new TransactionContext(parentContext, { preset, transaction });
+
+    return this.transactionStorage.run(transactionContext, async () => {
+      try {
+        return await callback();
+      } finally {
+        // detached descendant가 완료된 트랜잭션을 다시 사용하지 않도록 local scope를 비운다.
+        transactionContext.clearLocal();
+      }
+    });
   }
 
   setConfig(dbConfig: SonamuDBConfig): void {

package/src/database/puri-wrapper.ts

@@ -99,11 +99,8 @@ export class PuriWrapper<TSchema extends DatabaseSchemaExtend = DatabaseSchemaEx
   ): Promise<T> {
     const { isolation, readOnly, dbPreset = "w" } = options;
 
-    // @transactional 데코레이터와 동일한 로직: 이미 트랜잭션 컨텍스트가 있는지 확인
     const { DB } = await import("./db");
-    const existingContext = DB.transactionStorage.getStore();
 
-    // AsyncLocalStorage 컨텍스트가 없거나 해당 preset의 트랜잭션이 없으면 새로 시작
     const startTransaction = async (
       knex: Knex | Knex.Transaction,
       upsertBuilder: UpsertBuilder,
@@ -112,33 +109,19 @@ export class PuriWrapper<TSchema extends DatabaseSchemaExtend = DatabaseSchemaEx
         async (trx) => {
           const trxWrapper = new PuriTransactionWrapper(trx, upsertBuilder);
 
-          // TransactionContext에 트랜잭션 저장
-          DB.getTransactionContext().setTransaction(dbPreset, trxWrapper);
-
-          try {
-            return await callback(trxWrapper);
-          } finally {
-            // 트랜잭션 제거
-            DB.getTransactionContext().deleteTransaction(dbPreset);
-          }
+          return DB.runWithTransactionScope(dbPreset, trxWrapper, () => callback(trxWrapper));
         },
         { isolationLevel: isolation, readOnly },
       );
     };
 
-    // AsyncLocalStorage 컨텍스트가 없으면 새로 생성
-    if (!existingContext) {
-      return DB.runWithTransaction(() => startTransaction(this.knex, this.upsertBuilder));
-    }
-
-    // 해당 preset의 트랜잭션이 이미 있으면 SAVEPOINT로 중첩 트랜잭션 생성
-    const existingTrx = existingContext.getTransaction(dbPreset);
+    const existingTrx = DB.transactionStorage.getStore()?.getTransaction(dbPreset);
     if (existingTrx) {
+      // 같은 preset의 중첩 트랜잭션은 기존 연결에서 SAVEPOINT로 시작한다.
       return startTransaction(existingTrx.trx, existingTrx.upsertBuilder);
-    } else {
-      // 컨텍스트는 있지만 이 preset의 트랜잭션은 없는 경우 (같은 컨텍스트 내에서 실행)
-      return startTransaction(this.knex, this.upsertBuilder);
     }
+
+    return startTransaction(this.knex, this.upsertBuilder);
   }
 
   ubRegister<TTable extends TableName<TSchema>>(

package/src/database/transaction-context.ts

@@ -2,17 +2,25 @@ import { type DBPreset } from "./db";
 import { type PuriTransactionWrapper } from "./puri-wrapper";
 
 export class TransactionContext {
-  private transactions: Map<DBPreset, PuriTransactionWrapper> = new Map();
+  constructor(
+    private readonly parent?: TransactionContext,
+    private local?: {
+      preset: DBPreset;
+      transaction: PuriTransactionWrapper;
+    },
+  ) {}
 
   getTransaction(preset: DBPreset): PuriTransactionWrapper | undefined {
-    return this.transactions.get(preset);
+    return this.local?.preset === preset
+      ? this.local.transaction
+      : this.parent?.getTransaction(preset);
   }
 
-  setTransaction(preset: DBPreset, trx: PuriTransactionWrapper): void {
-    this.transactions.set(preset, trx);
+  getActiveTransaction(): PuriTransactionWrapper | undefined {
+    return this.local?.transaction ?? this.parent?.getActiveTransaction();
   }
 
-  deleteTransaction(preset: DBPreset): void {
-    this.transactions.delete(preset);
+  clearLocal(): void {
+    this.local = undefined;
   }
 }

package/src/naite/naite-reporter.ts

@@ -6,6 +6,11 @@
  *
  * 프로젝트별로 고유한 소켓을 사용하기 위해 sonamu.config.ts 경로의 해시를 사용합니다.
  *
+ * 모듈 싱글턴이지만 인스턴스는 프로세스마다 별개입니다. run/start·run/end는
+ * Vitest 메인 프로세스(NaiteVitestReporter 커스텀 리포터)에서, test/result는
+ * 각 worker 프로세스(bootstrap의 afterEach)에서 전송되므로 buffer와 소켓
+ * 연결을 서로 공유하지 않습니다.
+ *
  * fs mock 충돌을 피하기 위해 net 모듈만 사용합니다.
  */
 /* oxlint-disable @typescript-eslint/no-explicit-any */ // Naite는 expect와 호응하도록 any를 허용함
@@ -112,7 +117,7 @@ class NaiteReporterClass {
   }
 
   /**
-   * beforeAll에서 호출합니다.
+   * Vitest 커스텀 리포터(NaiteVitestReporter)의 onTestRunStart에서 호출합니다.
    * 테스트 run 시작을 알립니다 (데이터 클리어 신호).
    */
   async startTestRun(): Promise<void> {
@@ -127,7 +132,7 @@ class NaiteReporterClass {
   }
 
   /**
-   * afterEach에서 호출합니다.
+   * bootstrap()의 afterEach에서 호출합니다.
    * 테스트 케이스 결과를 traces와 함께 전송합니다.
    */
   async reportTestResult(
@@ -145,7 +150,7 @@ class NaiteReporterClass {
   }
 
   /**
-   * afterAll에서 호출합니다.
+   * Vitest 커스텀 리포터(NaiteVitestReporter)의 onTestRunEnd에서 호출합니다.
    * 테스트 run 종료를 알립니다.
    */
   async endTestRun(): Promise<void> {