npm - sonamu - Versions diffs - 0.7.15 → 0.7.17 - Mend

sonamu 0.7.15 → 0.7.17

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.

Files changed (96) hide show

package/dist/ai/providers/rtzr/error.d.ts +1 -1
package/dist/ai/providers/rtzr/error.d.ts.map +1 -1
package/dist/api/config.d.ts +1 -0
package/dist/api/config.d.ts.map +1 -1
package/dist/api/config.js +1 -1
package/dist/api/decorators.d.ts +1 -1
package/dist/api/decorators.d.ts.map +1 -1
package/dist/api/decorators.js +1 -1
package/dist/api/sonamu.d.ts +3 -1
package/dist/api/sonamu.d.ts.map +1 -1
package/dist/api/sonamu.js +51 -40
package/dist/database/base-model.d.ts +16 -6
package/dist/database/base-model.d.ts.map +1 -1
package/dist/database/base-model.js +44 -3
package/dist/database/base-model.types.d.ts +29 -48
package/dist/database/base-model.types.d.ts.map +1 -1
package/dist/database/base-model.types.js +12 -2
package/dist/database/puri.d.ts +2 -1
package/dist/database/puri.d.ts.map +1 -1
package/dist/database/puri.js +2 -1
package/dist/database/puri.types.d.ts +3 -3
package/dist/database/puri.types.d.ts.map +1 -1
package/dist/database/puri.types.js +1 -1
package/dist/entity/entity-manager.d.ts +8 -4
package/dist/entity/entity-manager.d.ts.map +1 -1
package/dist/entity/entity.d.ts +10 -1
package/dist/entity/entity.d.ts.map +1 -1
package/dist/entity/entity.js +84 -39
package/dist/index.d.ts +1 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +2 -1
package/dist/syncer/checksum.d.ts +8 -3
package/dist/syncer/checksum.d.ts.map +1 -1
package/dist/syncer/checksum.js +17 -9
package/dist/syncer/code-generator.js +7 -2
package/dist/syncer/syncer.d.ts +6 -6
package/dist/syncer/syncer.d.ts.map +1 -1
package/dist/syncer/syncer.js +27 -13
package/dist/tasks/workflow-manager.d.ts +3 -3
package/dist/tasks/workflow-manager.d.ts.map +1 -1
package/dist/tasks/workflow-manager.js +15 -11
package/dist/template/implementations/generated.template.d.ts.map +1 -1
package/dist/template/implementations/generated.template.js +8 -6
package/dist/template/implementations/model.template.js +5 -5
package/dist/template/implementations/services.template.d.ts +17 -0
package/dist/template/implementations/services.template.d.ts.map +1 -0
package/dist/template/implementations/services.template.js +159 -0
package/dist/template/implementations/view_form.template.js +2 -2
package/dist/template/implementations/view_id_async_select.template.js +2 -2
package/dist/template/implementations/view_list.template.js +5 -5
package/dist/types/types.d.ts +43 -25
package/dist/types/types.d.ts.map +1 -1
package/dist/types/types.js +29 -17
package/dist/ui/ai-api.d.ts +2 -0
package/dist/ui/ai-api.d.ts.map +1 -1
package/dist/ui/ai-api.js +43 -49
package/dist/ui/ai-client.d.ts +10 -0
package/dist/ui/ai-client.d.ts.map +1 -1
package/dist/ui/ai-client.js +457 -437
package/dist/ui/api.d.ts.map +1 -1
package/dist/ui/api.js +14 -3
package/dist/ui-web/assets/{index-J9MCfjCd.js → index-DzqUrTB-.js} +56 -59
package/dist/ui-web/index.html +1 -1
package/package.json +12 -8
package/src/api/config.ts +3 -0
package/src/api/decorators.ts +6 -1
package/src/api/sonamu.ts +71 -52
package/src/database/base-model.ts +66 -11
package/src/database/base-model.types.ts +79 -76
package/src/database/puri.ts +5 -1
package/src/database/puri.types.ts +3 -6
package/src/entity/entity.ts +83 -34
package/src/index.ts +1 -0
package/src/shared/app.shared.ts.txt +1 -1
package/src/shared/web.shared.ts.txt +0 -43
package/src/syncer/checksum.ts +31 -9
package/src/syncer/code-generator.ts +8 -1
package/src/syncer/syncer.ts +38 -26
package/src/tasks/workflow-manager.ts +16 -12
package/src/template/implementations/generated.template.ts +17 -3
package/src/template/implementations/model.template.ts +4 -4
package/src/template/implementations/services.template.ts +226 -0
package/src/template/implementations/view_form.template.ts +1 -1
package/src/template/implementations/view_id_async_select.template.ts +1 -1
package/src/template/implementations/view_list.template.ts +4 -4
package/src/types/types.ts +33 -16
package/src/ui/ai-api.ts +61 -60
package/src/ui/ai-client.ts +535 -499
package/src/ui/api.ts +14 -2
package/src/ui/entity.instructions.md +536 -0
package/dist/template/implementations/service.template.d.ts +0 -29
package/dist/template/implementations/service.template.d.ts.map +0 -1
package/dist/template/implementations/service.template.js +0 -202
package/dist/ui-web/assets/provider-utils_false-BKJD46kk.js +0 -1
package/dist/ui-web/assets/provider-utils_false-Bu5lmX18.js +0 -1
package/src/template/implementations/service.template.ts +0 -328

package/dist/ui-web/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{projectName}}: Sonamu UI</title>
-    <script type="module" crossorigin src="/sonamu-ui/assets/index-J9MCfjCd.js"></script>
+    <script type="module" crossorigin src="/sonamu-ui/assets/index-DzqUrTB-.js"></script>
     <link rel="stylesheet" crossorigin href="/sonamu-ui/assets/index-CpaB9P6g.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "sonamu",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "Sonamu — TypeScript Fullstack API Framework",
   "keywords": [
     "typescript",
@@ -81,10 +81,10 @@
     "tsicli": "^1.0.5",
     "vitest": "^4.0.10",
     "zod": "^4.1.12",
-    "@sonamu-kit/hmr-hook": "^0.4.1",
+    "@sonamu-kit/hmr-runner": "^0.1.1",
+    "@sonamu-kit/tasks": "^0.1.1",
     "@sonamu-kit/ts-loader": "^2.1.3",
-    "@sonamu-kit/tasks": "^0.1.0",
-    "@sonamu-kit/hmr-runner": "^0.1.1"
+    "@sonamu-kit/hmr-hook": "^0.4.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.7",
@@ -100,12 +100,13 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@ai-sdk/openai": "3.0.0-beta.75",
-    "@ai-sdk/provider": "3.0.0-beta.22",
-    "@ai-sdk/provider-utils": "4.0.0-beta.40",
+    "@ai-sdk/openai": "3.0.0",
+    "@ai-sdk/provider": "3.0.0",
+    "@ai-sdk/provider-utils": "4.0.0",
+    "@ai-sdk/anthropic": "3.0.0",
     "@swc/cli": "^0.7.8",
     "@swc/core": "^1.13.5",
-    "ai": "6.0.0-beta.138",
+    "ai": "6.0.1",
     "fastify": "^4.23.2",
     "knex": "^3.1.0",
     "pgvector": "^0.2.1",
@@ -122,6 +123,9 @@
     "@ai-sdk/provider-utils": {
       "optional": true
     },
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
     "ai": {
       "optional": true
     },

package/src/api/config.ts CHANGED Viewed

@@ -53,6 +53,9 @@ export type SonamuConfig = {
 };
 export type SonamuServerOptions = {
+  // 프로젝트 외부에서 접근할 수 있는 URL. 기본값은 {server.listen.host}:{server.listen.port} 입니다.
+  baseUrl?: string;
   fastify?: FastifyServerOptions;
   listen?: {

package/src/api/decorators.ts CHANGED Viewed

@@ -21,7 +21,12 @@ export interface GuardKeys {
   user: true;
 }
 export type GuardKey = keyof GuardKeys;
-export type ServiceClient = "axios" | "axios-multipart" | "swr" | "window-fetch";
+export type ServiceClient =
+  | "axios"
+  | "axios-multipart"
+  | "tanstack-query"
+  | "tanstack-mutation"
+  | "window-fetch";
 export type ApiDecoratorOptions = {
   httpMethod?: HTTPMethods;
   contentType?:

package/src/api/sonamu.ts CHANGED Viewed

@@ -363,7 +363,7 @@ class SonamuClass {
             (api.options.httpMethod ?? "GET") === request.method.toUpperCase(),
         );
         if (found) {
-          return this.getApiHandler(found, config)(request, reply);
+          return this.createApiHandler(found, config)(request, reply);
         }
         if (request.url.startsWith("/api/")) {
@@ -385,13 +385,13 @@ class SonamuClass {
         server.route({
           method: api.options.httpMethod ?? "GET",
           url: this.config.api.route.prefix + api.path,
-          handler: this.getApiHandler(api, config),
+          handler: this.createApiHandler(api, config),
         }); // END server.route
       }
     }
   }
-  getApiHandler(
+  createApiHandler(
     api: ExtendedApi,
     config: SonamuFastifyConfig,
   ): (request: FastifyRequest, reply: FastifyReply) => Promise<unknown> {
@@ -429,56 +429,74 @@ class SonamuClass {
       // Content-Type
       reply.type(api.options.contentType ?? "application/json");
-      // createSSEFactory 함수에 미리 request의 socket과 reply를 바인딩.
-      const { createSSEFactory } = await import("../stream/sse");
-      const createSSE = (<T extends ZodObject>(
-        _request: FastifyRequest,
-        _reply: FastifyReply,
-        _events: T,
-      ) => createSSEFactory(_request.socket, _reply, _events)).bind(null, request, reply);
-      const context: Context = {
-        ...(await Promise.resolve(
-          config.contextProvider(
-            {
-              request,
-              reply,
-              headers: request.headers,
-              createSSE,
-              naiteStore: Naite.createStore(),
-              // auth
-              user: request.user ?? null,
-              passport: {
-                login: request.login.bind(request) as AuthContext["passport"]["login"],
-                logout: request.logout.bind(request) as AuthContext["passport"]["logout"],
-              },
-            },
-            request,
-            reply,
-          ),
-        )),
-      };
-      const model = this.syncer.models[api.modelName];
-      return this.asyncLocalStorage.run({ context }, async () => {
-        const { ApiParamType } = await import("../types/types");
-        // biome-ignore lint/suspicious/noExplicitAny: model은 모델 인스턴스이므로 메서드 호출 가능
-        const result = await (model as any)[api.methodName].apply(
-          model,
-          api.parameters.map((param) => {
-            // Context 인젝션
-            if (ApiParamType.isContext(param.type)) {
-              return context;
-            } else {
-              return reqBody[param.name];
-            }
-          }),
-        );
-        reply.type(api.options.contentType ?? "application/json");
+      // Context 생성
+      const context: Context = await this.createContext(config, request, reply);
-        return result;
+      // 모델 메소드 args 생성하여 호출
+      const { ApiParamType } = await import("../types/types");
+      const args = api.parameters.map((param) => {
+        // Context 인젝션
+        if (ApiParamType.isContext(param.type)) {
+          return context;
+        } else {
+          return reqBody[param.name];
+        }
       });
+      return this.invokeModelMethod(api, args, context, reply);
+    };
+  }
+  async invokeModelMethod(
+    api: ExtendedApi,
+    args: unknown[],
+    context: Context,
+    reply: FastifyReply,
+  ): Promise<unknown> {
+    const model = this.syncer.models[api.modelName];
+    return this.asyncLocalStorage.run({ context }, async () => {
+      // biome-ignore lint/suspicious/noExplicitAny: model은 모델 인스턴스이므로 메서드 호출 가능
+      const result = await (model as any)[api.methodName].apply(model, args);
+      reply.type(api.options.contentType ?? "application/json");
+      return result;
+    });
+  }
+  async createContext(
+    config: SonamuFastifyConfig,
+    request: FastifyRequest,
+    reply: FastifyReply,
+  ): Promise<Context> {
+    // createSSEFactory 함수에 미리 request의 socket과 reply를 바인딩.
+    const { createSSEFactory } = await import("../stream/sse");
+    const createSSE = (<T extends ZodObject>(
+      _request: FastifyRequest,
+      _reply: FastifyReply,
+      _events: T,
+    ) => createSSEFactory(_request.socket, _reply, _events)).bind(null, request, reply);
+    const context: Context = {
+      ...(await Promise.resolve(
+        config.contextProvider(
+          {
+            request,
+            reply,
+            headers: request.headers,
+            createSSE,
+            naiteStore: Naite.createStore(),
+            // auth
+            user: request.user ?? null,
+            passport: {
+              login: request.login.bind(request) as AuthContext["passport"]["login"],
+              logout: request.logout.bind(request) as AuthContext["passport"]["logout"],
+            },
+          },
+          request,
+          reply,
+        ),
+      )),
     };
+    return context;
   }
   async startWatcher(): Promise<void> {
@@ -595,7 +613,7 @@ class SonamuClass {
   private async initializeWorkflows(options: SonamuTaskOptions | undefined) {
     const { WorkflowManager } = await import("../tasks/workflow-manager");
     // NOTE: @sonamu-kit/tasks 안에선 knex config를 수정하기 때문에 connection이 아닌 config 째로 보냅니다.
-    this._workflows = await WorkflowManager.create(DB.getDBConfig("w"), true);
+    this._workflows = new WorkflowManager(DB.getDBConfig("w"));
     if (!options) {
       return;
     }
@@ -608,7 +626,7 @@ class SonamuClass {
     };
     if (enableWorker) {
-      await this.workflows.setupWorker({
+      this.workflows.setupWorker({
         ...defaultWorkerOptions,
         ...options.workerOptions,
       });
@@ -645,6 +663,7 @@ class SonamuClass {
     server
       .listen({ port, host })
       .then(async () => {
+        await this.workflows.startWorker();
         await options.lifecycle?.onStart?.(server);
       })
       .catch(async (err) => {

package/src/database/base-model.ts CHANGED Viewed

@@ -1,20 +1,18 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: Puri의 타입은 개별 모델에서 확정되므로 BaseModel에서는 any를 허용함 */
 import type { Knex } from "knex";
-import { group, isObject, omit, set } from "radashi";
+import { cloneDeep, group, isObject, omit, set } from "radashi";
 import type { ListResult } from "..";
 import { Sonamu } from "../api";
+import { EntityManager } from "../entity/entity-manager";
 import type { DatabaseSchemaExtend, SonamuQueryMode } from "../types/types";
 import { getJoinTables, getTableNamesFromWhere } from "../utils/sql-parser";
 import { chunk } from "../utils/utils";
-import type {
-  EnhancerMap,
-  ResolveSubsetIntersection,
-  UnionExtractedTTables,
-} from "./base-model.types";
+import type { EnhancerMap, ResolveSubsetIntersection } from "./base-model.types";
 import type { DBPreset } from "./db";
 import { DB } from "./db";
 import { Puri } from "./puri";
+import type { UnionExtractedTTables } from "./puri.types";
 import type { InferAllSubsets, PuriLoaderQueries, PuriSubsetFn } from "./puri-subset.types";
 import { PuriWrapper } from "./puri-wrapper";
 import { UpsertBuilder } from "./upsert-builder";
@@ -137,7 +135,12 @@ export class BaseModelClass<
    * 타입 검증 및 추론을 도와줌
    */
   createEnhancers<T extends TSubsetKey>(
-    enhancers: EnhancerMap<T, InferAllSubsets<TSubsetQueries, TLoaderQueries>, TSubsetMapping>,
+    enhancers: EnhancerMap<
+      T,
+      InferAllSubsets<TSubsetQueries, TLoaderQueries>,
+      TSubsetMapping,
+      TSubsetQueries
+    >,
   ) {
     return enhancers;
   }
@@ -169,7 +172,7 @@ export class BaseModelClass<
       };
       debug?: boolean;
       optimizeCountQuery?: boolean;
-    } & EnhancerParam<TSubsetKey, TComputedResults, TSubsetMapping>,
+    } & EnhancerParam<TSubsetKey, TComputedResults, TSubsetMapping, TSubsetQueries>,
   ): Promise<ListResult<LP, TSubsetMapping[T]>> {
     const { subset, qb, params: queryParams, debug = false, optimizeCountQuery = false } = params;
@@ -191,10 +194,18 @@ export class BaseModelClass<
     // Enhancer 적용
     const enhancer = (params as any).enhancers?.[subset];
-    const rows = (await Promise.all(
+    const enhancedRows = (await Promise.all(
       computedRows.map((row) => enhancer?.(row) ?? row),
     )) as TSubsetMapping[T][];
+    // Internal 필드 제거
+    const entity = EntityManager.get(this.modelName);
+    const internalFields = entity.subsetsInternal[subset] ?? [];
+    const rows =
+      internalFields.length > 0
+        ? enhancedRows.map((row) => this.omitInternalFields(row, internalFields))
+        : enhancedRows;
     if (queryParams.queryMode === "list") {
       // 리스트만 리턴
       return { rows } as ListResult<LP, TSubsetMapping[T]>;
@@ -204,6 +215,49 @@ export class BaseModelClass<
     }
   }
+  /**
+   * 객체에서 internal 필드 제거
+   * 중첩 필드(예: "user.email") 및 배열(예: "employees.salary")도 처리
+   */
+  omitInternalFields<T extends object>(row: T, fields: string[]): T {
+    const result = cloneDeep(row);
+    for (const field of fields) {
+      this.deleteField(result, field.split("."));
+    }
+    return result;
+  }
+  /**
+   * 중첩 필드 삭제 (배열 내 객체도 처리)
+   */
+  deleteField(obj: any, parts: string[]): void {
+    if (!obj || typeof obj !== "object") {
+      return;
+    }
+    if (parts.length === 1) {
+      if (Array.isArray(obj)) {
+        obj.forEach((item) => {
+          if (item && typeof item === "object") {
+            delete item[parts[0]];
+          }
+        });
+      } else {
+        delete obj[parts[0]];
+      }
+      return;
+    }
+    const [first, ...rest] = parts;
+    const next = obj[first];
+    if (Array.isArray(next)) {
+      next.map((item) => this.deleteField(item, rest));
+    } else if (next && typeof next === "object") {
+      this.deleteField(next, rest);
+    }
+  }
   /**
    * COUNT 쿼리 실행 (내부 메서드)
    */
@@ -401,9 +455,10 @@ type EnhancerParam<
   TSubsetKey extends string,
   TComputedResults extends Record<TSubsetKey, any>,
   TSubsetMapping extends Record<TSubsetKey, any>,
+  TSubsetQueries extends Record<TSubsetKey, PuriSubsetFn>,
 > = [RequiredEnhancerKeys<TSubsetKey, TComputedResults, TSubsetMapping>] extends [never]
-  ? { enhancers?: EnhancerMap<TSubsetKey, TComputedResults, TSubsetMapping> }
-  : { enhancers: EnhancerMap<TSubsetKey, TComputedResults, TSubsetMapping> };
+  ? { enhancers?: EnhancerMap<TSubsetKey, TComputedResults, TSubsetMapping, TSubsetQueries> }
+  : { enhancers: EnhancerMap<TSubsetKey, TComputedResults, TSubsetMapping, TSubsetQueries> };
 type RequiredEnhancerKeys<
   TSubsetKey extends string,

package/src/database/base-model.types.ts CHANGED Viewed

@@ -7,29 +7,11 @@
  * Enhancer, SubsetQuery 교집합 등 Model 계층에서 필요한 타입 정의.
  */
-import type { ListResult } from "..";
 import type { DatabaseSchemaExtend } from "../types/types";
 import type { Puri } from "./puri";
+import type { ExtractTTables } from "./puri.types";
 import type { PuriSubsetFn } from "./puri-subset.types";
-// ============================================================================
-// Puri 테이블 추출 유틸리티
-// ============================================================================
-/**
- * Puri 인스턴스에서 TTables 타입 추출
- */
-export type ExtractPuriTables<T> = T extends Puri<any, infer TTables, any> ? TTables : never;
-/**
- * SubsetQueries에서 모든 TTables의 유니온 추출
- * getSubsetQueries의 qb 타입 정의에 사용
- */
-export type UnionExtractedTTables<
-  TSubsetKey extends string,
-  TSubsetQueries extends Record<TSubsetKey, PuriSubsetFn>,
-> = ExtractPuriTables<ReturnType<TSubsetQueries[TSubsetKey]>>;
 // ============================================================================
 // Subset 교집합 계산 (onSubset 메서드용)
 // ============================================================================
@@ -37,11 +19,12 @@ export type UnionExtractedTTables<
 /**
  * 두 Puri의 테이블 교집합을 가진 새로운 Puri 생성
  */
-type MergePuriTables<A, B, TA = ExtractPuriTables<A>, TB = ExtractPuriTables<B>> = Puri<
-  DatabaseSchemaExtend,
-  Pick<TA, Extract<keyof TA, keyof TB>>,
-  any
->;
+type MergePuriTables<
+  A extends Puri<any, any, any>,
+  B extends Puri<any, any, any>,
+  TA = ExtractTTables<A>,
+  TB = ExtractTTables<B>,
+> = Puri<DatabaseSchemaExtend, Pick<TA, Extract<keyof TA, keyof TB>>, any>;
 /**
  * 서브셋 키 배열을 순회하며 테이블 교집합 Puri 계산
@@ -62,24 +45,79 @@ export type ResolveSubsetIntersection<
 // Enhancer
 // ============================================================================
+/**
+ * SubsetQueries의 Puri 반환 타입에서 TTables를 추출하고,
+ * TTables의 키 중 DatabaseSchemaExtend의 키와 일치하는 것이 메인 테이블.
+ * 해당 테이블의 BaseSchema에서 __virtual_query__ 키를 추출.
+ */
+type ExtractMainTable<TSubsetQueries extends Record<string, PuriSubsetFn>> = Extract<
+  keyof ExtractTTables<ReturnType<TSubsetQueries[keyof TSubsetQueries]>>,
+  keyof DatabaseSchemaExtend
+>;
+type ExtractVirtualQueryKeys<TSubsetQueries extends Record<string, PuriSubsetFn>> =
+  ExtractMainTable<TSubsetQueries> extends infer TTable extends keyof DatabaseSchemaExtend
+    ? DatabaseSchemaExtend[TTable] extends { __virtual_query__: readonly (infer K)[] }
+      ? K
+      : never
+    : never;
+/**
+ * TSubsetMapping에서 virtualQuery 키를 optional로 만든 타입
+ * Enhancer 필수 여부 판단 시 사용
+ */
+type OmitVirtualQueryFromMapping<TMapping, TVirtualQueryKeys> = Omit<
+  TMapping,
+  TVirtualQueryKeys & keyof TMapping
+> &
+  Partial<Pick<TMapping, TVirtualQueryKeys & keyof TMapping>>;
+/**
+ * Computed가 Mapping에 호환되는지 판단 (virtualQuery 키 제외)
+ */
+type IsEnhancerOptional<
+  TSubsetKey extends string,
+  TComputedResults extends Record<TSubsetKey, any>,
+  TSubsetMapping extends Record<TSubsetKey, any>,
+  TSubsetQueries extends Record<TSubsetKey, PuriSubsetFn>,
+  K extends TSubsetKey,
+> = TComputedResults[K] extends OmitVirtualQueryFromMapping<
+  TSubsetMapping[K],
+  ExtractVirtualQueryKeys<TSubsetQueries>
+>
+  ? true
+  : false;
 /**
  * 단일 Enhancer 함수 타입
- * computed 결과를 받아 최종 mapping 타입으로 변환
+ * computed 결과 + virtualQuery props를 받아 최종 mapping 타입으로 변환
  */
-export type EnhancerFn<TComputed, TMapping> = (row: TComputed) => TMapping | Promise<TMapping>;
+type EnhancerFnWithVirtualQuery<TComputed, TMapping, TVirtualQueryKeys> = (
+  row: TComputed & Pick<TMapping, TVirtualQueryKeys & keyof TMapping>,
+) => TMapping | Promise<TMapping>;
 /**
  * Enhancer가 필수인 SubsetKey 추출
  *
  * ComputedResults[K]가 SubsetMapping[K]에 할당 불가능하면 해당 K는 필수
  * (즉, virtual 필드 등 추가 변환이 필요한 경우)
+ * 단, virtualQuery 키는 무시 (사용자가 appendSelect로 직접 추가)
  */
 export type RequiredEnhancerKeys<
   TSubsetKey extends string,
   TComputedResults extends Record<TSubsetKey, any>,
   TSubsetMapping extends Record<TSubsetKey, any>,
+  TSubsetQueries extends Record<TSubsetKey, PuriSubsetFn>,
 > = {
-  [K in TSubsetKey]: TComputedResults[K] extends TSubsetMapping[K] ? never : K;
+  [K in TSubsetKey]: IsEnhancerOptional<
+    TSubsetKey,
+    TComputedResults,
+    TSubsetMapping,
+    TSubsetQueries,
+    K
+  > extends true
+    ? never
+    : K;
 }[TSubsetKey];
 /**
@@ -87,6 +125,7 @@ export type RequiredEnhancerKeys<
  *
  * - ComputedResults[K]가 SubsetMapping[K]에 assignable하면 → enhancer 선택적
  * - 그렇지 않으면 → enhancer 필수
+ * - 단, virtualQuery 키는 무시 (사용자가 appendSelect로 직접 추가)
  *
  * @example
  * // virtual 필드 employee_count가 있는 경우
@@ -98,59 +137,23 @@ export type EnhancerMap<
   TSubsetKey extends string,
   TComputedResults extends Record<TSubsetKey, any>,
   TSubsetMapping extends Record<TSubsetKey, any>,
+  TSubsetQueries extends Record<TSubsetKey, PuriSubsetFn>,
+  TRequiredKeys extends TSubsetKey = RequiredEnhancerKeys<
+    TSubsetKey,
+    TComputedResults,
+    TSubsetMapping,
+    TSubsetQueries
+  >,
 > = {
-  // Computed가 Mapping에 호환되면 선택적
-  [K in TSubsetKey as TComputedResults[K] extends TSubsetMapping[K] ? K : never]?: EnhancerFn<
+  [K in Exclude<TSubsetKey, TRequiredKeys>]?: EnhancerFnWithVirtualQuery<
     TComputedResults[K],
-    TSubsetMapping[K]
+    TSubsetMapping[K],
+    ExtractVirtualQueryKeys<TSubsetQueries>
   >;
 } & {
-  // 호환되지 않으면 필수
-  [K in TSubsetKey as TComputedResults[K] extends TSubsetMapping[K] ? never : K]: EnhancerFn<
+  [K in TRequiredKeys]: EnhancerFnWithVirtualQuery<
     TComputedResults[K],
-    TSubsetMapping[K]
+    TSubsetMapping[K],
+    ExtractVirtualQueryKeys<TSubsetQueries>
   >;
 };
-// ============================================================================
-// executeSubsetQuery
-// ============================================================================
-/**
- * executeSubsetQuery 기본 파라미터
- */
-export type ExecuteSubsetQueryBaseParams<TSubsetKey extends string> = {
-  subset: TSubsetKey;
-  qb: Puri<any, any, any>;
-  params: {
-    num?: number;
-    page?: number;
-    queryMode?: "list" | "count" | "both";
-  };
-  debug?: boolean;
-  optimizeCountQuery?: boolean;
-};
-/**
- * executeSubsetQuery 파라미터 (Enhancer 포함)
- *
- * RequiredEnhancerKeys가 없으면 enhancers 선택적, 있으면 필수
- */
-export type ExecuteSubsetQueryParams<
-  TSubsetKey extends string,
-  TComputedResults extends Record<TSubsetKey, any>,
-  TSubsetMapping extends Record<TSubsetKey, any>,
-  T extends TSubsetKey,
-> = ExecuteSubsetQueryBaseParams<T> &
-  ([RequiredEnhancerKeys<TSubsetKey, TComputedResults, TSubsetMapping>] extends [never]
-    ? { enhancers?: EnhancerMap<TSubsetKey, TComputedResults, TSubsetMapping> }
-    : { enhancers: EnhancerMap<TSubsetKey, TComputedResults, TSubsetMapping> });
-/**
- * executeSubsetQuery 반환 타입
- */
-export type ExecuteSubsetQueryResult<
-  TSubsetMapping extends Record<string, any>,
-  T extends string,
-  LP extends { queryMode?: "list" | "count" | "both" },
-> = ListResult<LP, TSubsetMapping[T]>;

package/src/database/puri.ts CHANGED Viewed

@@ -1205,12 +1205,14 @@ export class JoinClauseGroup<
   TResolved: 쿼리 실행 후 반환될 결과 타입
   TReturning: RETURNING 절에 사용될 타입
 */
-export class ResolvedPuri<TResolved, TReturning> {
+export class ResolvedPuri<TResolved, TReturning> implements Promise<TResolved> {
   constructor(
     public knexQuery: Knex.QueryBuilder,
     private knex: Knex,
   ) {}
+  [Symbol.toStringTag]: string = "Promise";
   toQuery(): string {
     return this.knexQuery.toQuery();
   }
@@ -1227,11 +1229,13 @@ export class ResolvedPuri<TResolved, TReturning> {
     Naite.t("puri:executed-query", this.toQuery());
     return this.knexQuery.then(onfulfilled as any, onrejected);
   }
   catch<TResult2 = never>(
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
   ): Promise<TResolved | TResult2> {
     return this.knexQuery.catch(onrejected);
   }
   finally(onfinally?: (() => void) | null): Promise<TResolved> {
     return this.knexQuery.finally(onfinally);
   }

package/src/database/puri.types.ts CHANGED Viewed

@@ -3,7 +3,7 @@
 import type { QueryResult } from "pg";
 import type { DatabaseForeignKeys, DatabaseSchemaExtend } from "../types/types";
 import type { Puri } from "./puri";
-import type { PuriWrapper } from "./puri-wrapper";
+import type { PuriSubsetFn } from "./puri-subset.types";
 // ============================================
 // 내부 타입 키 (메타데이터)
@@ -342,15 +342,12 @@ export type InsertData<T> = Omit<
 export type InsertResult = Pick<QueryResult<any>, "command" | "rowCount" | "rows" | "oid">;
 // SubsetQuery를 위한 타입 유틸리티
-type ExtractTTables<T extends Puri<any, any, any>> = T extends Puri<any, infer TTables, any>
+export type ExtractTTables<T extends Puri<any, any, any>> = T extends Puri<any, infer TTables, any>
   ? TTables
   : never;
 export type UnionExtractedTTables<
   SubsetKey extends string,
-  SubsetQueries extends Record<
-    SubsetKey,
-    (qbWrapper: PuriWrapper<DatabaseSchemaExtend>) => Puri<any, any, any>
-  >,
+  SubsetQueries extends Record<SubsetKey, PuriSubsetFn>,
 > = {
   [K in SubsetKey]: ExtractTTables<ReturnType<SubsetQueries[K]>>;
 }[SubsetKey];