sonamu 0.10.11 → 0.10.13

package/src/tasks/decorator.ts

@@ -13,18 +13,18 @@ import { type Executable } from "../types/types";
 import { type WorkflowFunction } from "./workflow-manager";
 
 // 워크플로우의 메타데이터 객체
-export interface WorkflowMetadata {
+export interface WorkflowMetadata<RawInput = unknown, Input = unknown, Output = unknown> {
   type: "workflow";
   id: string;
   name: string;
   version: string | null;
-  schema: StandardSchemaV1<unknown, unknown> | undefined;
+  schema: StandardSchemaV1<RawInput, Input> | undefined;
   schedules: {
     name: string;
     expression: string;
-    input: Executable<SchemaInput<unknown, unknown> | undefined>;
+    input: Executable<RawInput | undefined>;
   }[];
-  fn: WorkflowFunction<unknown, unknown>;
+  fn: WorkflowFunction<Input, Output>;
   retryPolicy?: RetryPolicy;
 }
 
@@ -50,22 +50,30 @@ export type DefineWorkflowOptions<
 // 이것들은 syncer에서 한번에 load한 다음, WorkflowManager에서 synchronize를 통해 등록됨.
 export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
   options: DefineWorkflowOptions<Input, Output, TSchema>,
-): (fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => WorkflowMetadata;
+): (
+  fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>,
+) => WorkflowMetadata<SchemaInput<TSchema, Input>, SchemaOutput<TSchema, Input>, Output>;
 export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
   options: DefineWorkflowOptions<Input, Output, TSchema>,
   fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>,
-): WorkflowMetadata;
+): WorkflowMetadata<SchemaInput<TSchema, Input>, SchemaOutput<TSchema, Input>, Output>;
 export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
   options: DefineWorkflowOptions<Input, Output, TSchema>,
   fn?: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>,
 ):
-  | WorkflowMetadata
-  | ((fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => WorkflowMetadata) {
-  const decorated = (fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => {
+  | WorkflowMetadata<SchemaInput<TSchema, Input>, SchemaOutput<TSchema, Input>, Output>
+  | ((
+      fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>,
+    ) => WorkflowMetadata<SchemaInput<TSchema, Input>, SchemaOutput<TSchema, Input>, Output>) {
+  const decorated = (workflowFunction: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => {
     const id = randomUUID();
-    const workflowName = options.name ?? inflection.underscore(fn.name);
+    const workflowName = options.name ?? inflection.underscore(workflowFunction.name);
 
-    const metadata: WorkflowMetadata = {
+    const metadata: WorkflowMetadata<
+      SchemaInput<TSchema, Input>,
+      SchemaOutput<TSchema, Input>,
+      Output
+    > = {
       type: "workflow" as const,
       id,
       name: workflowName,
@@ -78,7 +86,7 @@ export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undef
           input: schedule.input,
         };
       }),
-      fn: fn as WorkflowFunction<unknown, unknown>,
+      fn: workflowFunction,
       retryPolicy: options.retryPolicy,
     };
 

package/src/tasks/step-wrapper.ts

@@ -6,6 +6,10 @@ export type RunnableStep<TArgs extends unknown[], TResult> = {
   run: StepFunction<TArgs, Promise<TResult>>;
 };
 
+interface StepConfig {
+  name: string;
+}
+
 export type MethodNames<T, TKey extends keyof T> = T[TKey] extends (
   ...args: infer _TArgs
 ) => infer _TResult
@@ -14,7 +18,7 @@ export type MethodNames<T, TKey extends keyof T> = T[TKey] extends (
 
 export type MethodArguments<T, TKey extends keyof T> = T[TKey] extends (
   ...args: infer TArgs
-) => unknown
+) => infer _TResult
   ? TArgs
   : never;
 
@@ -37,7 +41,7 @@ export class StepWrapper {
     TKey extends keyof T,
     TArgs extends MethodArguments<T, TKey>,
     TResult extends MethodReturnType<T, TKey>,
-  >(config: { name: string }, object: T, name: MethodNames<T, TKey>): RunnableStep<TArgs, TResult>;
+  >(config: StepConfig, object: T, name: MethodNames<T, TKey>): RunnableStep<TArgs, TResult>;
   get<
     T,
     TKey extends keyof T,
@@ -50,20 +54,26 @@ export class StepWrapper {
     TArgs extends MethodArguments<T, TKey>,
     TResult extends MethodReturnType<T, TKey>,
   >(
-    ...args: [{ name: string }, T, MethodNames<T, TKey>] | [T, MethodNames<T, TKey>]
+    ...definitionArgs: [StepConfig, T, MethodNames<T, TKey>] | [T, MethodNames<T, TKey>]
   ): RunnableStep<TArgs, TResult> {
-    let config: { name: string };
+    let config: StepConfig;
     let fn: StepFunction<TArgs, Exclude<TResult, never>>;
 
-    if (args.length === 2) {
-      const [rawObject, methodName] = args;
-      const method = rawObject[methodName] as CallableFunction;
+    if (definitionArgs.length === 2) {
+      const [rawObject, methodName] = definitionArgs;
+      const method =
+        /* SAFETY: 작업 데코레이터와 워크플로 정의가 이 값의 타입을 보장한다. */ rawObject[
+          methodName
+        ] as CallableFunction;
       config = { name: inflection.underscore(methodName.toString()) };
 
       fn = (...args: TArgs) => method.bind(rawObject)(...args);
     } else {
-      const [rawConfig, rawObject, name] = args;
-      const method = rawObject[name] as CallableFunction;
+      const [rawConfig, rawObject, name] = definitionArgs;
+      const method =
+        /* SAFETY: 작업 데코레이터와 워크플로 정의가 이 값의 타입을 보장한다. */ rawObject[
+          name
+        ] as CallableFunction;
 
       config = { name: rawConfig.name ?? inflection.underscore(name.toString()) };
       fn = (...args: TArgs) => method.bind(rawObject)(...args);

package/src/tasks/workflow-manager.ts

@@ -25,6 +25,7 @@ import { convertDomainToCategory } from "../logger/category";
 import { Naite } from "../naite/naite";
 import { createMockSSEFactory } from "../stream/sse";
 import { type Executable } from "../types/types";
+import { isFunctionValue } from "../utils/runtime-value";
 import { type WorkflowMetadata } from "./decorator";
 import { StepWrapper } from "./step-wrapper";
 
@@ -126,7 +127,7 @@ export class WorkflowManager {
     await Promise.allSettled(
       Array.from(this.#workflowsMap.entries())
         .filter(([key]) => !workflowMap.has(key))
-        .flatMap(([_, workflows]) =>
+        .flatMap(([, workflows]) =>
           workflows.map((workflow) => {
             return Promise.allSettled([
               ...workflow.schedules.map((schedule) => this.unscheduleTask(schedule.name)),
@@ -140,7 +141,7 @@ export class WorkflowManager {
     await Promise.allSettled(
       Array.from(workflowMap.entries())
         .filter(([key]) => !this.#workflowsMap.has(key))
-        .flatMap(([_, workflows]) =>
+        .flatMap(([, workflows]) =>
           workflows.map((workflow) => {
             this.registerWorkflow({
               id: workflow.id,
@@ -167,7 +168,7 @@ export class WorkflowManager {
           assert(previousWorkflows, "previous workflows not found");
           return [key, [previousWorkflows, newWorkflows]];
         })
-        .map(async ([_, [previousWorkflows, newWorkflows]]) => {
+        .map(async ([, [previousWorkflows, newWorkflows]]) => {
           // 기존 것들을 삭제부터 해야함.
           await Promise.allSettled(
             previousWorkflows
@@ -237,7 +238,7 @@ export class WorkflowManager {
         { name, version }: Pick<WorkflowMetadata, "name" | "version">,
         { input }: WorkflowMetadata["schedules"][number],
       ) => {
-        const inputData = await (typeof input === "function"
+        const inputData = await (isFunctionValue(input)
           ? Promise.resolve(input())
           : Promise.resolve(input));
 
@@ -287,17 +288,22 @@ export class WorkflowManager {
         version: string | null;
       }>,
     ) => {
-      const baseContext = {
+      const baseContext: Context = {
         transport: "http" as const,
-        request: null,
-        reply: null,
+        // 워크플로우에는 HTTP 요청이 없으므로 잘못된 접근을 즉시 드러냅니다.
+        get request(): Context["request"] {
+          throw new Error("HTTP request is unavailable in workflow context");
+        },
+        get reply(): Context["reply"] {
+          throw new Error("HTTP reply is unavailable in workflow context");
+        },
         headers: {},
-        createSSE: (schema: ZodObject) => createMockSSEFactory(schema),
+        createSSE: <T extends ZodObject>(schema: T) => createMockSSEFactory(schema),
         naiteStore: Naite.createStore(),
         locale: "",
         user: null,
         session: null,
-      } as unknown as Context;
+      };
 
       const contextProvider = Sonamu.config.tasks?.contextProvider;
       const context: Context = contextProvider

package/src/template/__tests__/http_validators.template.test.ts

@@ -0,0 +1,160 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { type SonamuConfig } from "../../api/config";
+import { type ExtendedApi } from "../../api/decorators";
+import { Sonamu } from "../../api/sonamu";
+import { Syncer } from "../../syncer/syncer";
+import { Template__http_validators } from "../implementations/http_validators.template";
+
+function createApi(overrides: {
+  httpMethod: "GET" | "POST";
+  modelName: string;
+  path: string;
+  parameterType?: "number" | "string";
+}): ExtendedApi {
+  return {
+    modelName: overrides.modelName,
+    methodName: "find",
+    path: overrides.path,
+    options: {
+      httpMethod: overrides.httpMethod,
+    },
+    typeParameters: [],
+    parameters: [
+      {
+        name: "filter",
+        optional: false,
+        type: {
+          t: "object",
+          props: [
+            {
+              name: "page",
+              optional: false,
+              type: overrides.parameterType ?? "number",
+            },
+          ],
+        },
+      },
+    ],
+    returnType: "unknown",
+  };
+}
+
+function readFingerprint(body: string): string {
+  const match = body.match(/fingerprint\w*\s*[:=]\s*["']([^"']+)["']/i);
+  if (match?.[1] === undefined) {
+    throw new Error("generated validator registry에 fingerprint가 없습니다");
+  }
+  return match[1];
+}
+
+const testConfig = {
+  api: { dir: ".", route: { prefix: "/api" } },
+  i18n: { defaultLocale: "ko", supportedLocales: ["ko"] },
+  sync: { targets: [] },
+  validation: { zodCompiler: { api: "aot" } },
+  database: {},
+  server: {
+    apiConfig: {
+      contextProvider: (defaultContext) => defaultContext,
+      guardHandler: () => undefined,
+    },
+  },
+} satisfies SonamuConfig;
+
+function setSyncerState(apis: ExtendedApi[]) {
+  const syncer = new Syncer();
+  syncer.apis = apis;
+  syncer.types = {};
+  Sonamu.syncer = syncer;
+}
+
+describe("Template__http_validators 생성 계약", () => {
+  const tempRoots: string[] = [];
+
+  beforeEach(() => {
+    Sonamu.config = testConfig;
+  });
+
+  afterEach(async () => {
+    await Promise.all(
+      tempRoots.splice(0).map((rootPath) => rm(rootPath, { recursive: true, force: true })),
+    );
+  });
+
+  it("충돌 없는 route key와 fingerprint로 최종 caster의 explicit compile registry를 결정적으로 만든다", () => {
+    const apis = [
+      createApi({ httpMethod: "GET", modelName: "ReportModel", path: "/report/find" }),
+      createApi({ httpMethod: "GET", modelName: "AuditModel", path: "/audit/find" }),
+      createApi({ httpMethod: "POST", modelName: "ReportModel", path: "/report/find" }),
+      createApi({ httpMethod: "GET", modelName: "ReportModel", path: "/report/find-alternate" }),
+    ];
+    const template = new Template__http_validators();
+
+    setSyncerState(apis);
+    const first = template.render();
+    setSyncerState(apis.toReversed());
+    const reordered = template.render();
+
+    expect(first.body).toBe(reordered.body);
+    expect(first.body.match(/\bcompile\(/g)).toHaveLength(4);
+    expect(first.body).toMatch(/compile\(\s*fastifyCaster\(/);
+    expect(readFingerprint(first.body)).toBe(readFingerprint(reordered.body));
+
+    const changedApis = [
+      ...apis.slice(0, -1),
+      createApi({
+        httpMethod: "GET",
+        modelName: "ReportModel",
+        parameterType: "string",
+        path: "/report/find-alternate",
+      }),
+    ];
+    setSyncerState(changedApis);
+    const changed = template.render();
+
+    expect(readFingerprint(changed.body)).not.toBe(readFingerprint(first.body));
+  });
+
+  it("동일한 canonical route key가 중복되면 registry 생성을 거부한다", () => {
+    const duplicatedApi = createApi({
+      httpMethod: "GET",
+      modelName: "ReportModel",
+      path: "/report/find",
+    });
+    setSyncerState([duplicatedApi, { ...duplicatedApi }]);
+
+    const template = new Template__http_validators();
+
+    expect(() => template.render()).toThrow();
+  });
+
+  it("REST API가 0개인 AOT registry는 compiler import 없이 내보내며 독립적으로 로드된다", async () => {
+    setSyncerState([]);
+
+    const rendered = new Template__http_validators().render();
+    const source = [...(rendered.customHeaders ?? []), rendered.body].join("\n");
+
+    expect(rendered.body).toMatch(/export const validators = new Map\(\[\s*\]\);/);
+    expect(rendered.body).toContain("export const routeIds = {}");
+    expect(source).not.toContain('from "zod-compiler"');
+    expect(source).not.toContain('from "sonamu"');
+    expect(source).not.toMatch(/\bcompile\(/);
+    expect(readFingerprint(rendered.body)).toHaveLength(64);
+
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), "sonamu-zero-registry-load-test-"));
+    tempRoots.push(tempRoot);
+    const modulePath = path.join(tempRoot, "sonamu.validators.generated.mjs");
+    await writeFile(modulePath, source);
+
+    await expect(import(`${pathToFileURL(modulePath).href}?test=zero`)).resolves.toMatchObject({
+      routeIds: {},
+      validators: expect.any(Map),
+    });
+  });
+});

package/src/template/__tests__/services.template.mutation.test.ts

@@ -1,35 +1,36 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { beforeEach, describe, expect, it } from "vitest";
 
 import { Sonamu } from "../../api";
+import { type SonamuConfig } from "../../api/config";
 import { type ExtendedApi } from "../../api/decorators";
+import { Syncer } from "../../syncer/syncer";
 import { Template__services } from "../implementations/services.template";
 
-describe("Template__services mutation hooks", () => {
-  let originalConfig: unknown;
-  let originalSyncer: unknown;
+const testConfig = {
+  api: { dir: ".", route: { prefix: "/api" } },
+  i18n: { defaultLocale: "ko", supportedLocales: ["ko"] },
+  sync: { targets: [] },
+  database: {},
+  server: {
+    apiConfig: {
+      contextProvider: (defaultContext) => defaultContext,
+      guardHandler: () => undefined,
+    },
+  },
+} satisfies SonamuConfig;
 
-  beforeEach(() => {
-    originalConfig = Reflect.get(Sonamu, "_config");
-    originalSyncer = Reflect.get(Sonamu, "_syncer");
-    Reflect.set(Sonamu, "_config", {
-      api: {
-        route: {
-          prefix: "/api",
-        },
-      },
-    });
-  });
+function renderServices(apis: ExtendedApi[]) {
+  const syncer = new Syncer();
+  syncer.apis = apis;
+  Sonamu.syncer = syncer;
+  return new Template__services().render({}).body;
+}
 
-  afterEach(() => {
-    Reflect.set(Sonamu, "_config", originalConfig);
-    Reflect.set(Sonamu, "_syncer", originalSyncer);
+describe("Template__services mutation hooks", () => {
+  beforeEach(() => {
+    Sonamu.config = testConfig;
   });
 
-  const renderServices = (apis: ExtendedApi[]) => {
-    Reflect.set(Sonamu, "_syncer", { apis });
-    return new Template__services().render({}).body;
-  };
-
   it("파라미터가 있는 일반 mutation에서 namespace와 인자 순서를 유지한다", () => {
     const body = renderServices([
       {

package/src/template/__tests__/services.template.websocket.test.ts

@@ -1,33 +1,29 @@
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import { z } from "zod";
 
 import { Sonamu } from "../../api";
+import { type SonamuConfig } from "../../api/config";
 import { type ExtendedApi } from "../../api/decorators";
 import { EntityManager } from "../../entity/entity-manager";
+import { Syncer } from "../../syncer/syncer";
 import { Template__services } from "../implementations/services.template";
 
-describe("Template__services websocket event refs", () => {
-  let originalConfig: unknown;
-  let originalSyncer: unknown;
-
-  beforeEach(() => {
-    originalConfig = Reflect.get(Sonamu, "_config");
-    originalSyncer = Reflect.get(Sonamu, "_syncer");
-  });
-
-  afterEach(() => {
-    Reflect.set(Sonamu, "_config", originalConfig);
-    Reflect.set(Sonamu, "_syncer", originalSyncer);
-  });
+const testConfig = {
+  api: { dir: ".", route: { prefix: "/api" } },
+  i18n: { defaultLocale: "ko", supportedLocales: ["ko"] },
+  sync: { targets: [] },
+  database: {},
+  server: {
+    apiConfig: {
+      contextProvider: (defaultContext) => defaultContext,
+      guardHandler: () => undefined,
+    },
+  },
+} satisfies SonamuConfig;
 
-  it("reuses websocket event type names when they are importable", () => {
-    Reflect.set(Sonamu, "_config", {
-      api: {
-        route: {
-          prefix: "/api",
-        },
-      },
-    });
+describe("Template__services websocket event refs", () => {
+  it("가져올 수 있는 websocket 이벤트 타입 이름을 재사용한다", () => {
+    Sonamu.config = testConfig;
 
     const apis: ExtendedApi[] = [
       {
@@ -62,9 +58,9 @@ describe("Template__services websocket event refs", () => {
         returnType: "void",
       },
     ];
-    Reflect.set(Sonamu, "_syncer", {
-      apis,
-    });
+    const syncer = new Syncer();
+    syncer.apis = apis;
+    Sonamu.syncer = syncer;
 
     EntityManager.setModulePath("ChatOutEvents", "chat/chat.types");
     EntityManager.setModulePath("ChatInEvents", "chat/chat.types");

package/src/template/entity-converter.ts

@@ -1,6 +1,6 @@
 import assert from "assert";
 
-import z from "zod";
+import { z } from "zod";
 
 import { SD } from "../dict/sd";
 import { EntityManager } from "../entity/entity-manager";
@@ -26,7 +26,10 @@ export async function getColumnsNode(entityId: string, subsetKey: string): Promi
   };
 
   // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- zod 스키마를 로드할 때 사용하는 타입
-  const columnsZodType = (await propNodeToZodType(rootPropNode)) as z.ZodObject<any>;
+  const columnsZodType =
+    /* SAFETY: 선행 Zod 종류 분기와 템플릿 입력 계약이 이 값의 타입을 보장한다. */ (await propNodeToZodType(
+      rootPropNode,
+    )) as z.ZodObject<any>;
 
   const columnsNode = zodTypeToRenderingNode(columnsZodType);
   assert(columnsNode.children !== undefined, "columnsNode.children is undefined");

package/src/template/helpers.ts

@@ -5,6 +5,13 @@ import { type EntityNamesRecord } from "../entity/entity-manager";
 import { isEnumProp, isRelationProp } from "../types/types";
 import { type RelationProp } from "../types/types";
 
+interface EnumColumnInfo {
+  id: string;
+  targetEntityNames: EntityNamesRecord;
+  targetEntityId: string;
+  title: string;
+}
+
 /**
  * Enum의 표시용 라벨을 가져옵니다.
  * OrderBy, SearchField 등 특수한 경우와 일반 Enum을 구분하여 처리합니다.
@@ -29,15 +36,7 @@ export function getLabel(entityId: string, enumId: string): string {
  * 컬럼 이름으로부터 Enum 정보를 추출합니다.
  * Entity의 prop 중 enum 타입인 것을 찾아 관련 정보를 반환합니다.
  */
-export function getEnumInfoFromColName(
-  entityId: string,
-  colName: string,
-): {
-  id: string;
-  targetEntityNames: EntityNamesRecord;
-  targetEntityId: string;
-  title: string;
-} {
+export function getEnumInfoFromColName(entityId: string, colName: string): EnumColumnInfo {
   const baseEntity = EntityManager.get(entityId);
   const prop = baseEntity.props.find((p) => p.name === colName);
   if (prop && isEnumProp(prop)) {

package/src/template/implementations/generated.template.ts

@@ -70,7 +70,7 @@ export class Template__generated extends Template {
           importKeys: unique([...result.importKeys, ...ts.importKeys].toSorted()),
         };
       },
-      {
+      /* SAFETY: reduce 누산기는 label을 제외한 SourceCode의 두 배열로 초기화된다. */ {
         lines: [],
         importKeys: [],
       } as Omit<SourceCode, "label">,
@@ -83,7 +83,7 @@ export class Template__generated extends Template {
     );
     if (cdImportKeys.length > 0) {
       const customScalarLines = cdImportKeys.flatMap((importKey) => {
-        const entity = entities.find((entity) => entity.types[importKey]);
+        const entity = entities.find((candidateEntity) => candidateEntity.types[importKey]);
         if (!entity) {
           throw new Error(`ZodType not found ${importKey}`);
         }
@@ -109,7 +109,8 @@ export class Template__generated extends Template {
     // import
     // sourceCode.importKeys에 내장 타입의 스키마가 있으면 sonamu import에 추가
     const builtInSchemaNames = Object.values(BUILT_IN_TYPES).map(
-      (info) => info.schemaName as string,
+      (info) =>
+        /* SAFETY: BUILT_IN_TYPES의 모든 항목은 생성 코드에 쓸 schemaName을 가진다. */ info.schemaName as string,
     );
     const builtInSchemas = sourceCode.importKeys.filter((key) => builtInSchemaNames.includes(key));
     const sonamuImports = [
@@ -146,7 +147,7 @@ export class Template__generated extends Template {
     return {
       label: `Enums: ${entity.id}`,
       lines: Object.entries(entity.enumLabels)
-        .filter(([_, enumLabel]) => Object.keys(enumLabel).length > 0)
+        .filter(([, enumLabel]) => Object.keys(enumLabel).length > 0)
         .flatMap(([enumId, enumLabel]) => [
           `export const ${enumId} = z.enum([${Object.keys(enumLabel).map(
             (el) => `"${el}"`,