sonamu 0.10.11 → 0.10.13

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;

package/src/template/implementations/http_validators.template.ts

@@ -0,0 +1,175 @@
+import { type ExtendedApi } from "../../api/decorators";
+import {
+  getHttpValidatorFingerprint,
+  getHttpValidatorRouteIdentifier,
+  getHttpValidatorRouteKey,
+} from "../../api/http-validator";
+import { Sonamu } from "../../api/sonamu";
+import { type ApiParamType } from "../../types/types";
+import { isObjectValue, isStringValue } from "../../utils/runtime-value";
+import { Template } from "../template";
+
+function collectReferencedTypes(type: ApiParamType, result: Set<string>): void {
+  if (isStringValue(type)) {
+    return;
+  }
+  switch (type.t) {
+    case "ref":
+      result.add(type.id);
+      for (const argument of type.args ?? []) {
+        collectReferencedTypes(argument, result);
+      }
+      return;
+    case "array":
+      collectReferencedTypes(type.elementsType, result);
+      return;
+    case "object":
+      for (const prop of type.props) {
+        collectReferencedTypes(prop.type, result);
+      }
+      return;
+    case "union":
+    case "intersection":
+      for (const member of type.types) {
+        collectReferencedTypes(member, result);
+      }
+      return;
+    case "tuple-type":
+      for (const element of type.elements) {
+        collectReferencedTypes(element, result);
+      }
+      return;
+    case "indexed-access":
+      collectReferencedTypes(type.object, result);
+      collectReferencedTypes(type.index, result);
+      return;
+    case "type-param":
+      if (type.constraint !== undefined) {
+        collectReferencedTypes(type.constraint, result);
+      }
+      return;
+    case "function":
+      for (const parameter of type.parameters) {
+        collectReferencedTypes(parameter.type, result);
+      }
+      collectReferencedTypes(type.returnType, result);
+      return;
+    case "string-literal":
+    case "numeric-literal":
+      return;
+  }
+}
+
+export class Template__http_validators extends Template {
+  constructor() {
+    super("http_validators");
+  }
+
+  getTargetAndPath() {
+    return {
+      target: `${Sonamu.config.api.dir}/src/application`,
+      path: "sonamu.validators.generated.ts",
+    };
+  }
+
+  render() {
+    const apis = [...Sonamu.syncer.apis]
+      .filter((api) => api.websocketOptions === undefined)
+      .toSorted((left, right) =>
+        getHttpValidatorRouteKey(left).localeCompare(getHttpValidatorRouteKey(right)),
+      );
+    const routeKeys = apis.map(getHttpValidatorRouteKey);
+    const duplicateKey = routeKeys.find((key, index) => routeKeys.indexOf(key) !== index);
+    if (duplicateKey !== undefined) {
+      throw new Error(`중복된 HTTP validator route key: ${duplicateKey}`);
+    }
+
+    const fingerprint = getHttpValidatorFingerprint(apis);
+    const policy = Sonamu.config.validation?.zodCompiler;
+    const isAot = isObjectValue(policy) && policy !== null && policy.api === "aot";
+    const hasAotValidators = isAot && apis.length > 0;
+    const referencedTypes = new Set<string>();
+    for (const api of apis) {
+      for (const typeParameter of api.typeParameters) {
+        collectReferencedTypes(typeParameter, referencedTypes);
+      }
+      for (const parameter of api.parameters) {
+        collectReferencedTypes(parameter.type, referencedTypes);
+      }
+    }
+    const importKeys = [...referencedTypes]
+      .filter((typeName) => Sonamu.syncer.types[typeName] !== undefined)
+      .toSorted();
+    const body = isAot
+      ? this.renderAotRegistry(apis, fingerprint, importKeys)
+      : this.renderPlainStub(apis, fingerprint);
+
+    return {
+      ...this.getTargetAndPath(),
+      body,
+      importKeys,
+      customHeaders: [
+        "/**",
+        " * @generated",
+        " * 직접 수정하지 마세요.",
+        " */",
+        "",
+        "/* oxlint-disable */",
+        "",
+        ...(hasAotValidators
+          ? [
+              `import { compile } from "zod-compiler";`,
+              `import { fastifyCaster, getZodObjectFromApi } from "sonamu";`,
+            ]
+          : []),
+      ],
+    };
+  }
+
+  private renderAotRegistry(
+    apis: ExtendedApi[],
+    fingerprint: string,
+    importKeys: string[],
+  ): string {
+    const declarations = apis.map((api) => {
+      const identifier = `validator_${getHttpValidatorRouteIdentifier(api)}`;
+      const schemaApi = {
+        modelName: api.modelName,
+        methodName: api.methodName,
+        path: api.path,
+        options: { httpMethod: api.options.httpMethod ?? "GET" },
+        typeParameters: api.typeParameters,
+        parameters: api.parameters,
+        returnType: "unknown",
+      } satisfies ExtendedApi;
+      return `export const ${identifier} = compile(fastifyCaster(getZodObjectFromApi(${JSON.stringify(schemaApi)}, { ...types })));`;
+    });
+    const routeIds = Object.fromEntries(
+      apis.map((api) => [getHttpValidatorRouteKey(api), getHttpValidatorRouteIdentifier(api)]),
+    );
+
+    return [
+      `export const fingerprint = ${JSON.stringify(fingerprint)};`,
+      `export const routeIds = ${JSON.stringify(routeIds)};`,
+      `const types = { ${importKeys.join(", ")} };`,
+      ...declarations,
+      `export const validators = new Map([`,
+      ...apis.map((api) => {
+        const routeKey = getHttpValidatorRouteKey(api);
+        return `  [${JSON.stringify(routeKey)}, validator_${getHttpValidatorRouteIdentifier(api)}],`;
+      }),
+      `]);`,
+    ].join("\n");
+  }
+
+  private renderPlainStub(apis: ExtendedApi[], fingerprint: string): string {
+    const routeIds = Object.fromEntries(
+      apis.map((api) => [getHttpValidatorRouteKey(api), getHttpValidatorRouteIdentifier(api)]),
+    );
+    return [
+      `export const fingerprint = ${JSON.stringify(fingerprint)};`,
+      `export const routeIds = ${JSON.stringify(routeIds)};`,
+      `export const validators = new Map();`,
+    ].join("\n");
+  }
+}

package/src/template/implementations/model.template.ts

@@ -33,7 +33,9 @@ export class Template__model extends Template {
     const listParamsNode = zodTypeToRenderingNode(listParamsZodType);
 
     const subsetKeyZodType = await getZodTypeById(`${entityId}SubsetKey`);
-    const subsetKeys = (subsetKeyZodType as z.ZodEnum).enum;
+    const subsetKeys =
+      /* SAFETY: 생성된 *SubsetKey 타입은 enum 스키마로 등록된다. */ (subsetKeyZodType as z.ZodEnum)
+        .enum;
 
     const names = EntityManager.getNamesFromId(entityId);
     const entity = EntityManager.get(entityId);

package/src/template/implementations/sd.template.ts

@@ -52,8 +52,9 @@ const SUPPORTED_LOCALES = ${JSON.stringify(supportedLocales)} as const;
 function getCurrentLocale(): (typeof SUPPORTED_LOCALES)[number] {
   try {
     const ctx = Sonamu.getContext();
-    return ctx.locale as (typeof SUPPORTED_LOCALES)[number] ?? DEFAULT_LOCALE;
-  } catch (_) {
+    const locale = ctx.locale;
+    return SUPPORTED_LOCALES.find((supportedLocale) => supportedLocale === locale) ?? DEFAULT_LOCALE;
+  } catch {
     return DEFAULT_LOCALE;
   }
 }
@@ -61,14 +62,14 @@ function getCurrentLocale(): (typeof SUPPORTED_LOCALES)[number] {
         : `
 const DEFAULT_LOCALE = "${defaultLocale}" as const;
 export const SUPPORTED_LOCALES = ${JSON.stringify(supportedLocales)} as const;
-let _currentLocale: (typeof SUPPORTED_LOCALES)[number] = DEFAULT_LOCALE;
+let currentLocale: (typeof SUPPORTED_LOCALES)[number] = DEFAULT_LOCALE;
 
 export function setLocale(locale: (typeof SUPPORTED_LOCALES)[number]) {
-  _currentLocale = locale;
+  currentLocale = locale;
 }
 
 export function getCurrentLocale(): (typeof SUPPORTED_LOCALES)[number] {
-  return _currentLocale;
+  return currentLocale;
 }
 `.trim();
 
@@ -126,7 +127,10 @@ export function defineLocale(dict: Partial<MergedDictionary>) {
 }
 
 // 각 locale별로 rc-keys + entity labels + 프로젝트 dict 합침
-const dictionaries: Record<string, Partial<MergedDictionary>> = {
+type DictionaryRegistry = {
+  [L in (typeof SUPPORTED_LOCALES)[number]]: Partial<MergedDictionary>;
+};
+const dictionaries: DictionaryRegistry = {
   ${defaultLocale}: { ...${getRCKeysVarName(defaultLocale)}, ...entityLabels, ...${defaultLocale} },
   ${supportedLocales
     .filter((locale) => locale !== defaultLocale)
@@ -138,29 +142,33 @@ type SDReturnType<K extends DictKey> = MergedDictionary[K] extends (...args: inf
   ? (...args: P) => LocalizedString
   : LocalizedString;
 
-function getDictValue<K extends DictKey>(key: K, locale: string): SDReturnType<K> {
+function getDictValue<K extends DictKey>(key: K, locale: (typeof SUPPORTED_LOCALES)[number]): SDReturnType<K> {
   // 1. 지정된 locale에서 조회
   const dict = dictionaries[locale];
   if (dict?.[key] !== undefined) {
-    return dict[key] as unknown as SDReturnType<K>;
+    // SAFETY: 요청 locale의 같은 키는 MergedDictionary가 정한 반환 종류를 유지합니다.
+    return dict[key] as SDReturnType<K>;
   }
 
   // 2. default locale에서 조회
   if (locale !== DEFAULT_LOCALE && dictionaries[DEFAULT_LOCALE]?.[key] !== undefined) {
-    return dictionaries[DEFAULT_LOCALE][key] as unknown as SDReturnType<K>;
+    // SAFETY: 기본 locale의 같은 키는 MergedDictionary가 정한 반환 종류를 유지합니다.
+    return dictionaries[DEFAULT_LOCALE][key] as SDReturnType<K>;
   }
 
   // 3. supported locales 순회
   for (const supportedLocale of SUPPORTED_LOCALES) {
     if (supportedLocale !== locale && supportedLocale !== DEFAULT_LOCALE) {
       if (dictionaries[supportedLocale]?.[key] !== undefined) {
-        return dictionaries[supportedLocale][key] as unknown as SDReturnType<K>;
+        // SAFETY: 대체 locale의 같은 키는 MergedDictionary가 정한 반환 종류를 유지합니다.
+        return dictionaries[supportedLocale][key] as SDReturnType<K>;
       }
     }
   }
 
-  // 4. 모두 실패 시 key 반환
-  return key as unknown as SDReturnType<K>;
+  // 모든 locale에 값이 없으면 동적으로 조합된 키를 그대로 노출합니다.
+  // SAFETY: 누락된 사전 키의 문자열 표현은 LocalizedString fallback 규약을 따릅니다.
+  return String(key) as SDReturnType<K>;
 }
 
 /**
@@ -226,58 +234,85 @@ type LocalizedColumnCandidate<T, K extends string> =
 type LocalizedColumnReturn<T, K extends string> =
   | LocalizedColumnValueFrom<LocalizedColumnCandidate<T, K>>
   | undefined;
-type LocaleValueMap = Partial<Record<(typeof SUPPORTED_LOCALES)[number], unknown>>;
+type LocaleValueMap = {
+  [L in (typeof SUPPORTED_LOCALES)[number]]?: LocalizedColumnValue;
+};
+function isString<V>(value: V): value is V & string {
+  return Object.prototype.toString.call(value) === "[object String]";
+}
 
-function isLocalizedColumnValue(value: unknown): value is LocalizedColumnValue {
-  return typeof value === "string" || (Array.isArray(value) && value.every((item) => typeof item === "string"));
+function isLocalizedColumnValue<V>(value: V): value is V & LocalizedColumnValue {
+  return isString(value) || (Array.isArray(value) && value.every(isString));
 }
 
-function isLocalizedColumnScalarValue(value: unknown): value is LocalizedColumnScalarValue {
-  return ["string", "number", "boolean", "bigint"].includes(typeof value);
+function isLocalizedColumnScalarValue<V>(value: V): value is V & LocalizedColumnScalarValue {
+  return ["[object String]", "[object Number]", "[object Boolean]", "[object BigInt]"].includes(
+    Object.prototype.toString.call(value),
+  );
 }
 
-function isEmptyLocalizedColumnValue(value: unknown): value is null | undefined | "" {
+function isEmptyLocalizedColumnValue<V>(value: V): value is V & (null | undefined | "") {
   return value === null || value === undefined || value === "";
 }
 
-function getNestedLocaleValue<T extends Record<string, unknown>, K extends LocalizedBaseColumn<T>>(
+type PropertyValue<T, K extends PropertyKey> = K extends keyof T ? T[K] : undefined;
+
+function getProperty<T extends object, K extends PropertyKey>(row: T, key: K): PropertyValue<T, K> {
+  if (!(key in row)) {
+    // SAFETY: 존재하지 않는 후보 키는 조건부 속성 타입에서도 undefined입니다.
+    return undefined as PropertyValue<T, K>;
+  }
+
+  // SAFETY: own/inherited 키 존재를 확인했으므로 해당 키의 조건부 속성 타입으로 좁힐 수 있습니다.
+  return (row as T & Record<K, PropertyValue<T, K>>)[key];
+}
+
+function getNestedLocaleValue<T extends object, K extends LocalizedBaseColumn<T>>(
   row: T,
   column: K,
   locale: (typeof SUPPORTED_LOCALES)[number],
-): unknown {
-  const columnValue = row[column];
-  if (columnValue === null || typeof columnValue !== "object" || Array.isArray(columnValue)) {
+): LocalizedColumnValue | undefined {
+  const columnValue = getProperty(row, column);
+  if (columnValue === null || Object.prototype.toString.call(columnValue) !== "[object Object]") {
     return undefined;
   }
 
+  // SAFETY: 일반 객체 검사를 통과한 값만 locale별 값 맵으로 조회합니다.
   return (columnValue as LocaleValueMap)[locale];
 }
 
-export function localizedColumn<T extends Record<string, unknown>, K extends LocalizedBaseColumn<T>>(
+function localizedKey<K extends string>(columnName: K, localeName: (typeof SUPPORTED_LOCALES)[number]) {
+  return \`\${columnName}_\${localeName}\`;
+}
+
+export function localizedColumn<T extends object, K extends LocalizedBaseColumn<T>>(
   row: T,
   column: K,
 ): LocalizedColumnReturn<T, K> {
-  const currentLocale = getCurrentLocale();
-  const locale = SUPPORTED_LOCALES.includes(currentLocale) ? currentLocale : DEFAULT_LOCALE;
-  const otherLocales = SUPPORTED_LOCALES.filter((l: string) => l !== locale && l !== DEFAULT_LOCALE);
-  const localizedKey = (column: K, locale: (typeof SUPPORTED_LOCALES)[number]) => \`\${column}_\${locale}\`;
+  const requestedLocale = getCurrentLocale();
+  const locale = SUPPORTED_LOCALES.includes(requestedLocale) ? requestedLocale : DEFAULT_LOCALE;
+  const otherLocales = SUPPORTED_LOCALES.filter(
+    (candidateLocale) => candidateLocale !== locale && candidateLocale !== DEFAULT_LOCALE,
+  );
   const values = [
-    { value: row[localizedKey(column, locale)], source: "direct" },
+    { value: getProperty(row, localizedKey(column, locale)), source: "direct" },
     { value: getNestedLocaleValue(row, column, locale), source: "nested" },
-    { value: row[column], source: "direct" },
-    { value: row[localizedKey(column, DEFAULT_LOCALE)], source: "direct" },
+    { value: getProperty(row, column), source: "direct" },
+    { value: getProperty(row, localizedKey(column, DEFAULT_LOCALE)), source: "direct" },
     { value: getNestedLocaleValue(row, column, DEFAULT_LOCALE), source: "nested" },
     ...otherLocales.flatMap((l) => [
-      { value: row[localizedKey(column, l)], source: "direct" },
+      { value: getProperty(row, localizedKey(column, l)), source: "direct" },
       { value: getNestedLocaleValue(row, column, l), source: "nested" },
     ]),
   ];
 
   for (const { value, source } of values) {
     if (!isEmptyLocalizedColumnValue(value) && isLocalizedColumnValue(value)) {
+      // SAFETY: 값 가드가 선택한 컬럼의 문자열 또는 문자열 배열임을 확인했습니다.
       return value as LocalizedColumnReturn<T, K>;
     }
     if (source === "direct" && !isEmptyLocalizedColumnValue(value) && isLocalizedColumnScalarValue(value)) {
+      // SAFETY: 직접 컬럼의 스칼라 값은 문자열로 변환해 지역화 반환 타입을 충족합니다.
       return String(value) as LocalizedColumnReturn<T, K>;
     }
   }
@@ -292,14 +327,19 @@ export function localizedColumn<T extends Record<string, unknown>, K extends Loc
  * @example
  * SD.enumLabels("TagOrderBy")[key]  // → 현재 locale의 라벨
  */
-SD.enumLabels = (enumName: string): Record<string, LocalizedString> => {
-  return new Proxy({} as Record<string, LocalizedString>, {
+interface EnumLabels {
+  [key: string]: LocalizedString;
+}
+
+SD.enumLabels = (enumName: string): EnumLabels => {
+  return new Proxy<EnumLabels>({}, {
     get(_, key: string | symbol) {
-      if (typeof key === "symbol") {
+      if (Object.prototype.toString.call(key) === "[object Symbol]") {
         return undefined;
       }
 
-      const dictKey = \`enum.\${enumName}.\${key}\` as DictKey;
+      // SAFETY: 생성된 enum 이름과 값의 조합은 enum 사전 키 형식을 따릅니다.
+      const dictKey = \`enum.\${enumName}.\${String(key)}\` as DictKey;
       return getDictValue(dictKey, getCurrentLocale());
     }
   });
@@ -318,16 +358,16 @@ SD.enumLabels = (enumName: string): Record<string, LocalizedString> => {
    * react-components의 rc-keys를 추출합
    * sonamu/src/dict/rc-keys.ts 파일의 소스 코드를 직접 읽어서 반환
    */
-  private extractRCKeysSourceCode(): { ko: string; en: string } {
+  private extractRCKeysSourceCode() {
     try {
       // rc-keys.ts 파일 경로
-      const __filename = fileURLToPath(import.meta.url);
-      const __dirname = path.dirname(__filename);
+      const currentFilename = fileURLToPath(import.meta.url);
+      const currentDirectory = path.dirname(currentFilename);
 
       // dist에서 실행될 때는 src로 경로 변경
-      const basePath = __dirname.includes("/dist/")
-        ? __dirname.replace("/dist/", "/src/")
-        : __dirname;
+      const basePath = currentDirectory.includes("/dist/")
+        ? currentDirectory.replace("/dist/", "/src/")
+        : currentDirectory;
 
       const rcKeysPath = path.join(basePath, "../../dict/rc-keys.ts");
 

package/src/template/implementations/services.template.ts

@@ -11,6 +11,7 @@ import { Sonamu } from "../../api/sonamu";
 import { EntityManager } from "../../entity/entity-manager";
 import { type TemplateOptions } from "../../types/types";
 import { ApiParamType } from "../../types/types";
+import { isStringValue } from "../../utils/runtime-value";
 import { assertDefined } from "../../utils/utils";
 import { Template } from "../template";
 import { BUILT_IN_TYPES, zodTypeToTsTypeDef } from "../zod-converter";
@@ -197,8 +198,7 @@ export function ${methodNameWebSocketCamelized}(
             .map((param) => {
               // primitive 타입인지 체크
               const isPrimitive =
-                typeof param.type === "string" &&
-                ["string", "number", "boolean"].includes(param.type);
+                isStringValue(param.type) && ["string", "number", "boolean"].includes(param.type);
 
               if (isPrimitive) {
                 // primitive: 직접 formData.append