sonamu 0.10.12 → 0.10.13

package/src/database/upsert-builder.ts

@@ -11,6 +11,8 @@ import {
   type DatabaseSchemaExtend,
   type EntityIndex,
 } from "../types/types";
+import { asArray } from "../utils/model";
+import { isNumberValue, isObjectValue, isStringValue } from "../utils/runtime-value";
 import { assertDefined, nonNullable } from "../utils/utils";
 import { batchUpdate } from "./_batch_update";
 import { type RowWithId } from "./_batch_update";
@@ -27,22 +29,36 @@ export type { DatabaseForeignKeys };
 type InheritableColumns<TTable extends TableName<DatabaseSchemaExtend>> =
   TTable extends keyof DatabaseSchemaExtend ? ColumnKeys<DatabaseSchemaExtend[TTable]> : never;
 
+// 참조 필드 타입
+export type UBRef = {
+  uuid: string;
+  of: string;
+  use?: string;
+};
+
+type UpsertValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | Date
+  | Buffer
+  | Knex.Raw
+  | UBRef
+  | null
+  | UpsertValue[]
+  | { [key: string]: UpsertValue | undefined };
+type UpsertRow = Record<string, UpsertValue | undefined>;
+
 // 테이블 데이터 타입
 type TableData = {
   references: Set<string>;
-  rows: Record<string, unknown>[];
+  rows: UpsertRow[];
   uniqueIndexes: EntityIndex[];
   uniquesMap: Map<string, string>;
   jsonColumns: string[];
 };
 
-// 참조 필드 타입
-export type UBRef = {
-  uuid: string;
-  of: string;
-  use?: string;
-};
-
 // upsert 옵션
 export type UpsertOptions<TTable extends TableName<DatabaseSchemaExtend>> = {
   chunkSize?: number;
@@ -55,13 +71,8 @@ export type InsertOnlyOptions = {
   chunkSize?: number;
 };
 
-export function isRefField(field: unknown): field is UBRef {
-  return (
-    field !== undefined &&
-    field !== null &&
-    (field as UBRef)?.of !== undefined &&
-    (field as UBRef)?.uuid !== undefined
-  );
+export function isRefField<Value>(field: Value): field is Value & UBRef {
+  return isObjectValue(field) && "of" in field && "uuid" in field;
 }
 
 export class UpsertBuilder {
@@ -99,22 +110,19 @@ export class UpsertBuilder {
     return this.tables.has(tableName);
   }
 
-  register<T extends string>(
-    tableName: string,
-    row: {
-      [key in T]?: UBRef | string | number | boolean | bigint | null | object | unknown;
-    },
-  ): UBRef {
+  register<Row extends object>(tableName: string, row: Row): UBRef {
     const table = this.getTable(tableName);
 
     // 해당 테이블의 unique 인덱스를 순회하며 키 생성
     const uniqueKeys = table.uniqueIndexes
       .map((unqIndex) => {
         const uniqueKeyArray = unqIndex.columns.map((unqCol) => {
+          // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
           const val = row[unqCol.name as keyof typeof row];
           if (isRefField(val)) {
             return val.uuid;
           } else {
+            // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
             return row[unqCol.name as keyof typeof row] ?? randomUUID(); // nullable인 경우 uuid로 랜덤값 삽입
           }
         });
@@ -154,32 +162,33 @@ export class UpsertBuilder {
 
     // 이 테이블에 사용된 RefField를 순회하여, 현재 테이블 정보에 어떤 필드를 참조하는지 추가
     // 이 정보를 나중에 치환할 때 사용
-    row = Object.fromEntries(
+    const normalizedRow = Object.fromEntries(
       Object.entries(row).map(([rowKey, rowValue]) => {
         if (isRefField(rowValue)) {
           rowValue.use ??= "id";
           table.references.add(`${rowValue.of}.${rowValue.use}`);
-          return [rowKey, rowValue];
+          return [rowKey, rowValue] as const;
         } else if (table.jsonColumns.includes(rowKey) && rowValue !== null) {
           // JSON 컬럼인 경우 JSON.stringify 처리 (Knex는 JSON 타입을 지원하지 않음)
-          return [rowKey, JSON.stringify(rowValue)];
+          return [rowKey, JSON.stringify(rowValue)] as const;
         } else if (isArray(rowValue)) {
           // 배열은 그대로 저장
-          return [rowKey, rowValue];
+          return [rowKey, rowValue] as const;
         } else {
-          return [rowKey, rowValue];
+          return [rowKey, rowValue] as const;
         }
       }),
-    ) as { [key in T]?: unknown };
+    );
 
     table.rows.push({
       uuid,
-      ...row,
+      ...normalizedRow,
     });
 
     const result: UBRef = {
       of: tableName,
-      uuid: (row as { uuid?: string }).uuid ?? uuid,
+      // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
+      uuid: isStringValue(normalizedRow.uuid) ? normalizedRow.uuid : uuid,
     };
 
     Naite.t("puri:ub-register", {
@@ -235,19 +244,21 @@ export class UpsertBuilder {
 
     // 전체 테이블 순회하여 현재 테이블 참조하는 모든 테이블 추출
     const { references, refTables } = Array.from(this.tables).reduce(
-      (r, [, table]) => {
-        const reference = Array.from(table.references.values()).find((ref) =>
+      (r, [, candidateTable]) => {
+        const reference = Array.from(candidateTable.references.values()).find((ref) =>
           ref.includes(`${tableName}.`),
         );
         if (reference) {
           r.references.push(reference);
-          r.refTables.push(table);
+          r.refTables.push(candidateTable);
         }
 
         return r;
       },
       {
+        // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
         references: [] as string[],
+        // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
         refTables: [] as TableData[],
       },
     );
@@ -262,7 +273,7 @@ export class UpsertBuilder {
       throw new Error(`${tableName}에 순환 자기 참조가 있습니다.`);
     }
 
-    const uuidMap = new Map<string, unknown>();
+    const uuidMap = new Map<string, UpsertRow & { id: number | string }>();
     const allIds: (number | string)[] = [];
 
     // 레벨별로 순차 처리
@@ -282,7 +293,8 @@ export class UpsertBuilder {
 
             if (!parent) throw new Error(`존재하지 않는 uuid ${value.uuid} -- in ${tableName}`);
 
-            resolved[key] = (parent as Record<string, unknown>)[value.use ?? "id"];
+            // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
+            resolved[key] = (parent as UpsertRow)[value.use ?? "id"];
 
             Naite.t("puri:ub-ref-resolved", {
               tableName,
@@ -309,10 +321,15 @@ export class UpsertBuilder {
         });
 
         // uuid를 별도로 보관하고, DB에 저장할 데이터에서 제거
+        // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
         const originalUuids = dataChunk.map((r) => r.uuid as string);
-        const dataForDb = dataChunk.map(({ uuid: _, ...rest }) => rest);
+        const dataForDb = dataChunk.map((row) => {
+          const rest = { ...row };
+          delete rest.uuid;
+          return rest;
+        });
 
-        let resultRows: { id: number | string; [key: string]: unknown }[];
+        let resultRows: (UpsertRow & { id: number | string })[];
 
         if (mode === "insert") {
           // INSERT 모드 - RETURNING 사용
@@ -339,9 +356,11 @@ export class UpsertBuilder {
               if (conditions.length === 0) continue;
 
               // 배치 SELECT
+              // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
               const existingRows = (await wdb(tableName)
-                .whereIn(columns, conditions as Record<string, unknown>[][])
-                .select("id", ...columns)) as Record<string, unknown>[];
+                // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
+                .whereIn(columns, conditions as UpsertRow[][])
+                .select("id", ...columns)) as UpsertRow[];
 
               // Map 생성: unique 컬럼 조합 → id
               const existingMap = new Map<string, number | string>();
@@ -350,7 +369,7 @@ export class UpsertBuilder {
                   .map((col) => String(existing[col] ?? ""))
                   .join("---delimiter---");
                 const id = existing.id;
-                if (typeof id === "number" || typeof id === "string") {
+                if (isNumberValue(id) || isStringValue(id)) {
                   existingMap.set(key, id);
                 }
               }
@@ -377,6 +396,7 @@ export class UpsertBuilder {
 
           // inherit 옵션 처리 - inherit 컬럼은 update 대상에서 제외
           if (options?.inherit?.length) {
+            // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
             const inheritColumns = options.inherit as string[];
 
             const excludedFromUpdate = updateColumns.filter((c) => inheritColumns.includes(c));
@@ -415,8 +435,8 @@ export class UpsertBuilder {
     }
 
     // 해당 테이블 참조를 실제 밸류로 변경
-    for (const table of refTables) {
-      table.rows = table.rows.map((row) => {
+    for (const referencingTable of refTables) {
+      referencingTable.rows = referencingTable.rows.map((row) => {
         for (const key of Object.keys(row)) {
           const prop = row[key];
           if (isRefField(prop) && prop.of === tableName) {
@@ -425,7 +445,8 @@ export class UpsertBuilder {
               console.error(prop);
               throw new Error(`존재하지 않는 uuid ${prop.uuid} -- in ${tableName}`);
             }
-            const resolvedValue = (parent as Record<string, unknown>)[prop.use ?? "id"];
+            // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
+            const resolvedValue = parent[prop.use ?? "id"];
             row[key] = resolvedValue;
 
             Naite.t("puri:ub-ref-resolved", {
@@ -442,9 +463,7 @@ export class UpsertBuilder {
 
     if (options?.cleanOrphans) {
       const cleanOrphans = options.cleanOrphans;
-      const fkColumns = isArray(cleanOrphans)
-        ? (cleanOrphans as ForeignKeyColumns<TTable>[])
-        : [cleanOrphans as ForeignKeyColumns<TTable>];
+      const fkColumns = asArray(cleanOrphans);
 
       // 현재 register된 레코드들의 FK 값들 추출
       const fkConditions = fkColumns.map((fkCol) => {
@@ -458,6 +477,7 @@ export class UpsertBuilder {
 
         // 각 FK 컬럼에 대한 WHERE IN 조건 추가
         for (const { column, values } of fkConditions) {
+          // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
           deleteQuery = deleteQuery.whereIn(column, values as Knex.Value[]);
         }
 
@@ -486,6 +506,7 @@ export class UpsertBuilder {
       returnedIds: allIds,
     });
 
+    // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
     return allIds as IdType<DatabaseSchemaExtend, TTable>[];
   }
 
@@ -516,6 +537,7 @@ export class UpsertBuilder {
     const whereColumns = Array.isArray(options.where) ? options.where : [options.where ?? "id"];
     const rows = table.rows.map((_row) => {
       const { uuid: _, ...row } = _row; // uuid 제외
+      // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
       return row as RowWithId<string>;
     });
 
@@ -542,10 +564,7 @@ export class UpsertBuilder {
    * - 자기 참조 없는 경우 : 모든 rows가 Level 0
    * - 자기 참조 있는 경우 : 자기 참조 관계를 위상 정렬하여 레벨별로 그룹화
    */
-  private buildInsertLevels(
-    rows: Record<string, unknown>[],
-    tableName: string,
-  ): { levels: Record<string, unknown>[][]; hasCircular: boolean } {
+  private buildInsertLevels(rows: UpsertRow[], tableName: string) {
     // 1. 자기 참조가 없으면 한 레벨로 처리
     const hasSelfRef = rows
       .flatMap((row) => Object.values(row))
@@ -553,24 +572,26 @@ export class UpsertBuilder {
     if (!hasSelfRef) return { levels: [rows], hasCircular: false };
 
     // 2. uuid → row 매핑 (중복 uuid 방지)
-    const rowByUuid = new Map<string, Record<string, unknown>>();
+    const rowByUuid = new Map<string, UpsertRow>();
     for (const row of rows) {
+      // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
       const uuid = row.uuid as string | undefined;
       if (!uuid) throw new Error(`buildInsertLevels: uuid가 없는 row -- in ${tableName}`);
       rowByUuid.set(uuid, row);
     }
 
     let pending = Array.from(rowByUuid.values());
-    const levels: Record<string, unknown>[][] = [];
+    const levels: UpsertRow[][] = [];
     const inserted = new Set<string>();
 
     // 3. 레벨별 분류
     while (pending.length > 0) {
-      const currentLevel: Record<string, unknown>[] = [];
-      const nextPending: Record<string, unknown>[] = [];
+      const currentLevel: UpsertRow[] = [];
+      const nextPending: UpsertRow[] = [];
 
       for (const row of pending) {
         // 이 row가 참조하는 자기 참조들
+        // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
         const selfRefs = Object.values(row).filter(
           (value) => isRefField(value) && value.of === tableName,
         ) as UBRef[];
@@ -596,6 +617,7 @@ export class UpsertBuilder {
       // 레벨 확정 + inserted 갱신
       levels.push(currentLevel);
       for (const row of currentLevel) {
+        // SAFETY: 쿼리 빌더의 제네릭 계약과 선행 검증이 이 타입을 보장합니다.
         inserted.add(row.uuid as string);
       }
 

package/src/dict/sd.ts

@@ -16,7 +16,10 @@ type MergedDictionary = {
     ? (...args: P) => string
     : string;
 };
-const dictionaries: Record<string, MergedDictionary> = {
+interface DictionariesByLocale {
+  [locale: string]: MergedDictionary;
+}
+const dictionaries: DictionariesByLocale = {
   ko,
   en,
 };
@@ -44,25 +47,32 @@ function getDictValue<K extends DictKey>(key: K, locale: string): SDReturnType<K
   // 1. 지정된 locale에서 조회
   const dict = dictionaries[locale];
   if (dict?.[key] !== undefined) {
-    return dict[key] as unknown as SDReturnType<K>;
+    return /* SAFETY: 동기화된 사전 계약에서 문자열 브랜드만 추가한다. */ dict[
+      key
+    ] as SDReturnType<K>;
   }
 
   // 2. default locale에서 조회
   if (locale !== defaultLocale && dictionaries[defaultLocale]?.[key] !== undefined) {
-    return dictionaries[defaultLocale][key] as unknown as SDReturnType<K>;
+    return /* SAFETY: 동기화된 사전 계약에서 문자열 브랜드만 추가한다. */ dictionaries[
+      defaultLocale
+    ][key] as SDReturnType<K>;
   }
 
   // 3. supported locales 순회
   for (const supportedLocale of supportedLocales) {
     if (supportedLocale !== locale && supportedLocale !== defaultLocale) {
       if (dictionaries[supportedLocale]?.[key] !== undefined) {
-        return dictionaries[supportedLocale][key] as unknown as SDReturnType<K>;
+        return /* SAFETY: 동기화된 사전 계약에서 문자열 브랜드만 추가한다. */ dictionaries[
+          supportedLocale
+        ][key] as SDReturnType<K>;
       }
     }
   }
 
   // 4. 모두 실패 시 key 반환
-  return key as unknown as SDReturnType<K>;
+  const missingValue: MergedDictionary[DictKey] = key;
+  return /* SAFETY: 누락 키 문자열에 LocalizedString 브랜드만 추가한다. */ missingValue as SDReturnType<K>;
 }
 
 /**

package/src/dict/sonamu-dictionary.ts

@@ -303,10 +303,7 @@ export class SonamuDictionary {
   /**
    * 함수 값들에서 사용되는 헬퍼 함수를 감지합니다.
    */
-  private detectUsedHelpers(entries: DictEntry[]): {
-    helpers: string[];
-    usesFormat: boolean;
-  } {
+  private detectUsedHelpers(entries: DictEntry[]) {
     const functionEntries = entries.filter((e) => e.isFunction);
     const helpers: string[] = [];
 
@@ -547,7 +544,7 @@ export class SonamuDictionary {
   /**
    * Project dict 파일([locale].ts)에서 딕셔너리 로드
    */
-  loadProjectDict(locale: string): { entries: DictEntry[] } {
+  loadProjectDict(locale: string) {
     const dictPath = path.join(Sonamu.apiRootPath, "src", "i18n", `${locale}.ts`);
     if (!fs.existsSync(dictPath)) {
       return { entries: [] };
@@ -795,7 +792,10 @@ export class SonamuDictionary {
       }
 
       const key = rowValues.key;
-      const source = rowValues.source as "entity" | "project";
+      const source =
+        /* SAFETY: 동기화된 사전 키와 값 계약이 이 값의 타입을 보장한다. */ rowValues.source as
+          | "entity"
+          | "project";
 
       if (!key || !source) continue;
 

package/src/dict/utils.ts

@@ -1,12 +1,20 @@
+import { isFunctionValue } from "../utils/runtime-value";
+
 export type PluralForms = {
   zero?: string | ((n: number) => string);
   one?: string | ((n: number) => string);
   other?: string | ((n: number) => string);
 };
 
+type PluralResolver = (n: number) => string;
+
+function isPluralResolver(form: PluralForms[keyof PluralForms]): form is PluralResolver {
+  return isFunctionValue(form);
+}
+
 export function plural(n: number, forms: PluralForms): string {
   const form = (n === 0 && forms.zero) || (n === 1 && forms.one) || forms.other;
-  return typeof form === "function" ? form(n) : (form ?? n.toString());
+  return isPluralResolver(form) ? form(n) : (form ?? n.toString());
 }
 
 export function createFormat(locale: string) {

package/src/entity/entity-manager.ts

@@ -30,6 +30,19 @@ export type TableSpec = {
   uniqueIndexes: EntityIndex[];
   jsonColumns: string[];
 };
+
+function parseEntityJson(source: string) {
+  try {
+    return JSON.parse(source);
+  } catch (cause) {
+    // JSON 파서 계약 밖의 오류는 구문 오류로 정규화하고 원인을 보존합니다.
+    if (!(cause instanceof SyntaxError)) {
+      throw new SyntaxError("entity.json 파싱 중 예기치 않은 오류가 발생했습니다.", { cause });
+    }
+    throw cause;
+  }
+}
+
 class EntityManagerClass {
   private entities: Map<string, Entity> = new Map();
   public modulePaths: Map<string, string> = new Map();
@@ -37,23 +50,25 @@ class EntityManagerClass {
   public isAutoloaded: boolean = false;
 
   // 경로 전달받아 모든 entity.json 파일 로드
-  async autoload(_: boolean = false) {
+  async autoload(doSilent: boolean = false) {
     if (this.isAutoloaded) {
       return;
     }
     const pathPattern = path.join(Sonamu.apiRootPath, "/src/application/**/*.entity.json");
 
     for await (const file of glob(path.resolve(pathPattern))) {
-      const json = JSON.parse((await readFile(file)).toString());
+      const json = parseEntityJson((await readFile(file)).toString());
 
       // entity.json 스키마 검증
       const error = this.schemaValidate(json);
       if (error) {
         const relativePath = path.relative(Sonamu.apiRootPath, file);
         const errorMessage = prettifyError(error);
-        console.error(
-          chalk.red(`Invalid entity.json schema: ${relativePath}\n${chalk.yellow(errorMessage)}`),
-        );
+        if (!doSilent) {
+          console.error(
+            chalk.red(`Invalid entity.json schema: ${relativePath}\n${chalk.yellow(errorMessage)}`),
+          );
+        }
       }
 
       await this.register(json, { deferSearchTextJsonSourceValidation: true });
@@ -65,7 +80,7 @@ class EntityManagerClass {
     this.isAutoloaded = true;
   }
 
-  schemaValidate(json: unknown) {
+  schemaValidate<Value>(json: Value) {
     const result = EntityJsonSchema.safeParse(json);
     return result.success ? null : result.error;
   }
@@ -180,7 +195,9 @@ class EntityManagerClass {
   }
 
   getByTable(table: string): Entity {
-    const entity = Array.from(this.entities.values()).find((entity) => entity.table === table);
+    const entity = Array.from(this.entities.values()).find(
+      (candidate) => candidate.table === table,
+    );
     if (entity === undefined) {
       throw new Error(`존재하지 않는 Entity 요청 ${table}`);
     }
@@ -242,7 +259,7 @@ class EntityManagerClass {
     return tableSpec;
   }
 
-  getNamesFromId(entityId: string): EntityNamesRecord {
+  getNamesFromId(entityId: string) {
     // entityId가 단복수 동형 단어인 경우 List 붙여서 생성
     const pluralized =
       inflection.pluralize(entityId) === entityId
@@ -258,7 +275,7 @@ class EntityManagerClass {
       capitalPlural: pluralized,
       upper: entityId.toUpperCase(),
       constant: inflection.underscore(entityId).toUpperCase(),
-    };
+    } satisfies EntityNamesRecord;
   }
 
   /**

package/src/entity/entity-template-cone.ts

@@ -14,6 +14,7 @@ import {
   isRelationProp,
   isSubsetDefWithCone,
 } from "../types/types";
+import { isStringValue } from "../utils/runtime-value";
 
 /**
  * Entity의 템플릿 cone을 생성합니다.
@@ -21,15 +22,7 @@ import {
  * LLM을 사용하지 않고 faker-mappings.ts를 활용하여 기본 cone을 생성합니다.
  * stub entity 생성 시 자동으로 호출되어 최소한의 cone 메타데이터를 제공합니다.
  */
-export function generateTemplateCones(
-  entity: EntityJson,
-  locale: "ko" | "en" | "ja" = "ko",
-): {
-  entityCone?: Cone;
-  propCones: Record<string, Cone>;
-  subsetCones: Record<string, Cone>;
-  enumCones: Record<string, Cone>;
-} {
+export function generateTemplateCones(entity: EntityJson, locale: "ko" | "en" | "ja" = "ko") {
   const mapping = fakerMappings[locale];
 
   if (!mapping) {
@@ -77,6 +70,7 @@ export function generateTemplateCones(
           };
           return acc;
         },
+        // SAFETY: 스키마 검증과 메타데이터 계약이 이 타입을 보장합니다.
         {} as Record<string, { note: string }>,
       ),
     };
@@ -188,6 +182,7 @@ function shouldHaveDataSource(prop: EntityProp): boolean {
 
   // OneToOne은 hasJoinColumn: true인 경우에만 dataSource 필요
   if (isOneToOneRelationProp(prop)) {
+    // SAFETY: 스키마 검증과 메타데이터 계약이 이 타입을 보장합니다.
     return (prop as OneToOneRelationProp).hasJoinColumn;
   }
 
@@ -199,7 +194,7 @@ function shouldHaveDataSource(prop: EntityProp): boolean {
  */
 function getSubsetScale(key: string, subset: SubsetDef, locale: "ko" | "en" | "ja"): string {
   const fields = isSubsetDefWithCone(subset) ? subset.fields : subset;
-  const fieldNames = fields.map((f) => (typeof f === "string" ? f : f.field)).join(", ");
+  const fieldNames = fields.map((f) => (isStringValue(f) ? f : f.field)).join(", ");
 
   const templates = {
     ko: `${key} 서브셋. 포함된 필드: ${fieldNames}`,