sonamu 0.10.12 → 0.10.13

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}"`,

package/src/template/implementations/generated_http.template.ts

@@ -6,6 +6,20 @@ import { type ExtendedApi } from "../../api/decorators";
 import { Sonamu } from "../../api/sonamu";
 import { Template } from "../template";
 
+type RequestDefaultValue =
+  | null
+  | undefined
+  | bigint
+  | boolean
+  | number
+  | string
+  | RequestDefaultValue[]
+  | RequestDefaultObject;
+
+interface RequestDefaultObject {
+  [key: string]: RequestDefaultValue;
+}
+
 export class Template__generated_http extends Template {
   constructor() {
     super("generated_http");
@@ -67,16 +81,23 @@ export class Template__generated_http extends Template {
     };
   }
 
-  zodTypeToReqDefault(zodType: z.ZodType, name: string): unknown {
+  zodTypeToReqDefault(zodType: z.ZodType, name: string): RequestDefaultValue {
     if (zodType instanceof z.ZodObject) {
       return Object.fromEntries(
-        Object.keys(zodType.shape).map((key) => [
+        Object.keys(zodType["shape"]).map((key) => [
           key,
-          this.zodTypeToReqDefault(zodType.shape[key], key),
+          this.zodTypeToReqDefault(zodType["shape"][key], key),
         ]),
       );
     } else if (zodType instanceof z.ZodArray) {
-      return [this.zodTypeToReqDefault((zodType as z.ZodArray<z.ZodType>).element, name)];
+      return [
+        this.zodTypeToReqDefault(
+          /* SAFETY: ZodArray 분기이므로 element가 배열 원소 스키마다. */ (
+            zodType as z.ZodArray<z.ZodType>
+          ).element,
+          name,
+        ),
+      ];
     } else if (zodType instanceof z.core.$ZodString) {
       // NOTE: z.ZodString으로 비교하면 z.url(), z.email() 등의 타입에서 문제가 생기므로 z.core.$ZodString으로 비교함
       if (name.endsWith("_at") || name.endsWith("_date") || name === "range") {
@@ -96,11 +117,21 @@ export class Template__generated_http extends Template {
     } else if (zodType instanceof z.ZodEnum) {
       return zodType.options[0];
     } else if (zodType instanceof z.ZodOptional) {
-      return this.zodTypeToReqDefault((zodType as z.ZodOptional<z.ZodType>).def.innerType, name);
+      return this.zodTypeToReqDefault(
+        /* SAFETY: ZodOptional 분기이므로 innerType이 선택 속성의 스키마다. */ (
+          zodType as z.ZodOptional<z.ZodType>
+        ).def.innerType,
+        name,
+      );
     } else if (zodType instanceof z.ZodNullable) {
       return null;
     } else if (zodType instanceof z.ZodUnion) {
-      return this.zodTypeToReqDefault((zodType as z.ZodUnion<z.ZodType[]>).def.options[0], name);
+      return this.zodTypeToReqDefault(
+        /* SAFETY: ZodUnion 분기이므로 options의 첫 항목이 유효한 대안 스키마다. */ (
+          zodType as z.ZodUnion<z.ZodType[]>
+        ).def.options[0],
+        name,
+      );
     } else if (zodType instanceof z.ZodUnknown) {
       return "unknown";
     } else if (zodType instanceof z.ZodTuple) {
@@ -112,20 +143,36 @@ export class Template__generated_http extends Template {
       return zodType.value;
     } else if (zodType instanceof z.ZodRecord || zodType instanceof z.ZodMap) {
       // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- ZodRecord 타입 사용
-      const kvDef = (zodType as z.ZodRecord<any, z.ZodType> | z.ZodMap<z.ZodType, z.ZodType>).def;
+      const kvDef = /* SAFETY: ZodRecord/ZodMap 분기이므로 def가 키-값 스키마 정의다. */ (
+        zodType as z.ZodRecord<any, z.ZodType> | z.ZodMap<z.ZodType, z.ZodType>
+      ).def;
       // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- ZodIntersection 타입 사용
-      const key = this.zodTypeToReqDefault(kvDef.keyType, name) as any;
+      const key = String(this.zodTypeToReqDefault(kvDef.keyType, name));
       const value = this.zodTypeToReqDefault(kvDef.valueType, name);
       return { [key]: value };
     } else if (zodType instanceof z.ZodSet) {
-      return [this.zodTypeToReqDefault((zodType as z.ZodSet<z.ZodType>).def.valueType, name)];
+      return [
+        this.zodTypeToReqDefault(
+          /* SAFETY: ZodSet 분기이므로 valueType이 집합 원소 스키마다. */ (
+            zodType as z.ZodSet<z.ZodType>
+          ).def.valueType,
+          name,
+        ),
+      ];
     } else if (zodType instanceof z.ZodIntersection) {
       return this.zodTypeToReqDefault(
-        (zodType as z.ZodIntersection<z.ZodType, z.ZodType>).def.right,
+        /* SAFETY: ZodIntersection 분기이므로 right가 교차 타입의 우측 스키마다. */ (
+          zodType as z.ZodIntersection<z.ZodType, z.ZodType>
+        ).def.right,
         name,
       );
     } else if (zodType instanceof z.ZodDefault) {
-      return this.zodTypeToReqDefault((zodType as z.ZodDefault<z.ZodType>).def.innerType, name);
+      return this.zodTypeToReqDefault(
+        /* SAFETY: ZodDefault 분기이므로 innerType이 기본값 적용 전 스키마다. */ (
+          zodType as z.ZodDefault<z.ZodType>
+        ).def.innerType,
+        name,
+      );
     } else {
       // console.log(zodType);
       return `unknown-${zodType.type}`;
@@ -135,12 +182,11 @@ export class Template__generated_http extends Template {
   resolveApiParams(
     api: ExtendedApi,
     references: { [typeName: string]: z.ZodType },
-  ): { [key: string]: unknown } {
+  ): RequestDefaultObject {
     const reqType = getZodObjectFromApi(api, references);
     try {
-      const def = this.zodTypeToReqDefault(reqType, "unknownName") as {
-        [key: string]: unknown;
-      };
+      // SAFETY: getZodObjectFromApi는 객체 스키마를 반환하므로 기본값도 객체이다.
+      const def = this.zodTypeToReqDefault(reqType, "unknownName") as RequestDefaultObject;
       return def;
     } catch (error) {
       console.error(error);

package/src/template/implementations/generated_sso.template.ts

@@ -36,6 +36,13 @@ function mapBetterAuthFieldType(type: string): string {
   }
 }
 
+function addLoaderIdTypeSafetyComments(query: string): string {
+  return query.replaceAll(
+    /fromIds as (?:number|string)\[\]/g,
+    "/* SAFETY: 로더가 전달하는 ID는 소스 엔티티의 기본 키 타입과 일치한다. */ $&",
+  );
+}
+
 export class Template__generated_sso extends Template {
   constructor() {
     super("generated_sso");
@@ -88,7 +95,8 @@ export class Template__generated_sso extends Template {
         lines: [
           `export const ${entityCamelName}LoaderQueries = {`,
           ...subsetKeys.map((subsetKey) => {
-            return `${subsetKey}: ${entity.getPuriLoaderQuery(subsetKey)},`;
+            const query = entity.getPuriLoaderQuery(subsetKey);
+            return `${subsetKey}: ${addLoaderIdTypeSafetyComments(query)},`;
           }),
           `} as const satisfies PuriLoaderQueries<${subsetKeyTypeName}>;`,
           "",
@@ -128,7 +136,7 @@ export class Template__generated_sso extends Template {
           importKeys: unique([...result.importKeys, ...ts.importKeys]),
         };
       },
-      {
+      /* SAFETY: reduce 누산기는 label을 제외한 SourceCode의 두 배열로 초기화된다. */ {
         lines: [],
         importKeys: [],
       } as Omit<SourceCode, "label">,
@@ -295,7 +303,9 @@ export class Template__generated_sso extends Template {
     }
 
     // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- additionalFields 타입이 동적임
-    const additionalFields = (authConfig as any)?.user?.additionalFields;
+    const additionalFields =
+      /* SAFETY: better-auth 설정의 user.additionalFields는 동적 필드 맵이다. */ (authConfig as any)
+        ?.user?.additionalFields;
     if (!additionalFields || Object.keys(additionalFields).length === 0) {
       // additionalFields가 없으면 기본 User 타입만 사용
       return {
@@ -310,7 +320,8 @@ export class Template__generated_sso extends Template {
     // additionalFields를 TypeScript 타입으로 변환
     const fieldLines = Object.entries(additionalFields).map(([key, value]) => {
       // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- better-auth additionalFields 구조
-      const fieldConfig = value as any;
+      const fieldConfig =
+        /* SAFETY: additionalFields의 각 값은 better-auth 필드 설정 객체이다. */ value as any;
       const isRequired = fieldConfig.required !== false;
 
       let fieldType: string;