sonamu 0.10.11 → 0.10.13

package/src/utils/object-utils.ts

@@ -1,3 +1,12 @@
+import {
+  isBigIntValue,
+  isFunctionValue,
+  isNumberValue,
+  isObjectValue,
+  isStringValue,
+  isSymbolValue,
+} from "./runtime-value";
+
 type Primitive = string | number | boolean | null | undefined;
 
 type TypedArray =
@@ -84,8 +93,8 @@ export interface SerializableCheckResult {
  * isSerializable({ fn: () => {} }) // { valid: false, reason: "Function at fn" }
  * isSerializable({ deep: { nested: Promise.resolve() } }) // { valid: false, reason: "Promise at deep.nested" }
  */
-export function isSerializable(
-  value: unknown,
+export function isSerializable<Value>(
+  value: Value,
   path: string[] = [],
   seen: WeakSet<object> = new WeakSet(),
 ): SerializableCheckResult {
@@ -94,23 +103,26 @@ export function isSerializable(
     return { valid: true };
   }
 
-  const type = typeof value;
-  if (type === "string" || type === "number" || type === "boolean" || type === "undefined") {
-    return { valid: true };
-  }
-  if (type === "bigint") {
+  if (
+    isStringValue(value) ||
+    isNumberValue(value) ||
+    value === true ||
+    value === false ||
+    value === undefined ||
+    isBigIntValue(value)
+  ) {
     return { valid: true };
   }
 
-  if (type === "function") {
+  if (isFunctionValue(value)) {
     return { valid: false, reason: `Function at ${formatPath(path)}` };
   }
-  if (type === "symbol") {
+  if (isSymbolValue(value)) {
     return { valid: false, reason: `Symbol at ${formatPath(path)}` };
   }
 
-  if (type === "object") {
-    const obj = value as object;
+  if (isObjectValue(value)) {
+    const obj = value;
 
     if (obj instanceof Promise) {
       return { valid: false, reason: `Promise at ${formatPath(path)}` };
@@ -126,7 +138,7 @@ export function isSerializable(
     if (obj instanceof WeakSet) {
       return { valid: false, reason: `WeakSet at ${formatPath(path)}` };
     }
-    if (typeof WeakRef !== "undefined" && obj instanceof WeakRef) {
+    if ("WeakRef" in globalThis && obj instanceof WeakRef) {
       return { valid: false, reason: `WeakRef at ${formatPath(path)}` };
     }
 
@@ -179,13 +191,11 @@ export function isSerializable(
 
     // Vitest는 Error를 허용하지만 속성은 직렬화 필요
     if (obj instanceof Error) {
-      const errorProps = Object.keys(obj).filter((k) => !["name", "message", "stack"].includes(k));
-      for (const key of errorProps) {
-        const result = isSerializable(
-          (obj as unknown as Record<string, unknown>)[key],
-          [...path, key],
-          seen,
-        );
+      const errorEntries = Object.entries(obj).filter(
+        ([key]) => !["name", "message", "stack"].includes(key),
+      );
+      for (const [key, nestedValue] of errorEntries) {
+        const result = isSerializable(nestedValue, [...path, key], seen);
         if (!result.valid) return result;
       }
       return { valid: true };
@@ -201,14 +211,14 @@ export function isSerializable(
       };
     }
 
-    for (const key of Object.keys(obj)) {
-      const result = isSerializable((obj as Record<string, unknown>)[key], [...path, key], seen);
+    for (const [key, nestedValue] of Object.entries(obj)) {
+      const result = isSerializable(nestedValue, [...path, key], seen);
       if (!result.valid) return result;
     }
     return { valid: true };
   }
 
-  return { valid: false, reason: `Unknown type (${type}) at ${formatPath(path)}` };
+  return { valid: false, reason: `Unknown value at ${formatPath(path)}` };
 }
 
 function formatPath(path: string[]): string {

package/src/utils/process-utils.ts

@@ -4,6 +4,8 @@ import { promisify } from "util";
 
 import chalk from "chalk";
 
+import { isStringValue } from "./runtime-value";
+
 const execFileAsync = promisify(execFile);
 
 /**
@@ -16,7 +18,7 @@ export async function execute(
   options?: ExecFileOptions,
 ): Promise<string> {
   const { stdout } = await execFileAsync(bin, args, options);
-  return typeof stdout === "string" ? stdout : stdout.toString();
+  return isStringValue(stdout) ? stdout : stdout.toString();
 }
 
 /**
@@ -37,6 +39,7 @@ export async function runWithGracefulShutdown(
     waitForUpTo: 20000,
   },
 ): Promise<void> {
+  // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
   let isRunning = true as boolean;
 
   const abortController = new AbortController();

package/src/utils/runtime-value.ts

@@ -0,0 +1,43 @@
+function hasPrimitiveTag<Value>(value: Value, tag: string): boolean {
+  return Object.prototype.toString.call(value) === tag && Object(value) !== value;
+}
+
+/** 런타임 값이 원시 문자열인지 판별합니다. */
+export function isStringValue<Value>(value: Value): value is Value & string {
+  return hasPrimitiveTag(value, "[object String]");
+}
+
+/** 런타임 값이 원시 숫자인지 판별합니다. */
+export function isNumberValue<Value>(value: Value): value is Value & number {
+  return hasPrimitiveTag(value, "[object Number]");
+}
+
+/** 런타임 값이 원시 심벌인지 판별합니다. */
+export function isSymbolValue<Value>(value: Value): value is Value & symbol {
+  return hasPrimitiveTag(value, "[object Symbol]");
+}
+
+/** 런타임 값이 원시 bigint인지 판별합니다. */
+export function isBigIntValue<Value>(value: Value): value is Value & bigint {
+  return hasPrimitiveTag(value, "[object BigInt]");
+}
+
+/** 런타임 값이 함수인지 판별합니다. */
+export function isFunctionValue<Value>(value: Value): value is Value & CallableFunction {
+  try {
+    const tag = Object.prototype.toString.call(value);
+    return (
+      tag === "[object Function]" ||
+      tag === "[object AsyncFunction]" ||
+      tag === "[object GeneratorFunction]" ||
+      tag === "[object AsyncGeneratorFunction]"
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** null과 함수를 제외한 객체 표현인지 판별합니다. */
+export function isObjectValue<Value>(value: Value): value is Value & object {
+  return value !== null && Object(value) === value && !isFunctionValue(value);
+}

package/src/utils/sql-parser.ts

@@ -9,15 +9,21 @@ import {
 } from "node-sql-parser";
 import { unique } from "radashi";
 
+import { isObjectValue, isStringValue } from "./runtime-value";
 import { nonNullable } from "./utils";
 
-export function getTableName(expr: ColumnRef) {
-  if ("table" in expr && expr.table !== null) {
-    return typeof expr.table === "string"
-      ? expr.table
-      : (expr.table as { type: string; value: string }).value;
+type ParserColumnRef = Omit<ColumnRef, "table"> & {
+  table?: string | { type: string; value: string } | null;
+};
+
+export function getTableName(expr: ParserColumnRef) {
+  const table = expr.table;
+  if (isStringValue(table)) {
+    return table;
   }
-  return null;
+  return isObjectValue(table) && "value" in table && isStringValue(table.value)
+    ? table.value
+    : null;
 }
 
 // where 조건에 사용된 테이블명을 추출
@@ -29,6 +35,7 @@ export function getTableNamesFromWhere(ast: AST | AST[]): string[] {
 
     const extractTableName = (expr: Expr | ExpressionValue): string[] => {
       if (expr.type === "column_ref") {
+        // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
         const table = getTableName(expr as ColumnRef);
         return table ? [table] : [];
       } else if (expr.type === "binary_expr" && "left" in expr) {

package/src/utils/type-utils.ts

@@ -1,3 +1,4 @@
+import { isObjectValue } from "./runtime-value";
 // 타입을 펼쳐서 보여주는 유틸리티 (객체에만 사용해야 함)
 type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
 
@@ -32,9 +33,9 @@ export function withProp<T extends object, P extends string, V>(
   const result = structuredClone(obj);
 
   // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 범용 배열 요소 타입
-  const setDeep = (current: any, keys: string[], value: V): void => {
-    if (keys.length === 0) return;
-    const [key, ...rest] = keys;
+  const setDeep = (current: any, pathKeys: string[]): void => {
+    if (pathKeys.length === 0) return;
+    const [key, ...rest] = pathKeys;
 
     if (rest.length === 0) {
       if (Array.isArray(current)) {
@@ -45,21 +46,22 @@ export function withProp<T extends object, P extends string, V>(
         current[key] = value;
       }
     } else {
-      if (!(key in current) || typeof current[key] !== "object") {
+      if (!(key in current) || !isObjectValue(current[key])) {
         current[key] = {};
       }
       if (Array.isArray(current[key])) {
         // oxlint-disable-next-line @typescript-eslint/no-explicit-any -- 범용 배열 요소 타입
         current[key].forEach((item: any) => {
-          setDeep(item, rest, value);
+          setDeep(item, rest);
         });
       } else {
-        setDeep(current[key], rest, value);
+        setDeep(current[key], rest);
       }
     }
   };
 
-  setDeep(result, keys, value);
+  setDeep(result, keys);
+  // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
   return result as SetPath<T, P, V>;
 }
 

package/src/utils/utils.ts

@@ -4,9 +4,11 @@ import path from "path";
 import { type FastifyRequest } from "fastify";
 
 import { type AbsolutePath } from "./path-utils";
+import { isObjectValue } from "./runtime-value";
 
 export function findAppRootPath(): AbsolutePath {
   const apiRootPath = findApiRootPath();
+  // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
   return path.dirname(apiRootPath) as AbsolutePath;
 }
 
@@ -15,15 +17,18 @@ export function findApiRootPath(): AbsolutePath {
   // 하지만 workspace 쓰면 process.cwd() 하면 되는데... 이건 나중에 협의 후 수정하는걸로
   const workspacePath = process.env.PNPM_SCRIPT_SRC_DIR ?? process.env.INIT_CWD;
   if (nonNullable(workspacePath)) {
+    // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
     return workspacePath as AbsolutePath;
   }
 
   if (nonNullable(process.env.PNPM_PACKAGE_NAME)) {
+    // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
     return process.cwd().split(path.sep).join(path.sep) as AbsolutePath;
   }
 
   const cwdPackagePath = path.join(process.cwd(), "package.json");
   if (fs.existsSync(cwdPackagePath)) {
+    // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
     return process.cwd().split(path.sep).join(path.sep) as AbsolutePath;
   }
 
@@ -35,6 +40,7 @@ export function findApiRootPath(): AbsolutePath {
 
   do {
     if (fs.existsSync(path.join(dir, "/package.json"))) {
+      // SAFETY: 선행 분기와 함수 계약이 이 타입을 보장합니다.
       return dir.split(path.sep).join(path.sep) as AbsolutePath;
     }
     dir = dir.split(path.sep).slice(0, -1).join(path.sep);
@@ -91,26 +97,18 @@ export function differenceWith<T>(
   return arr1.filter((itemA) => !arr2.some((itemB) => comparator(itemA, itemB)));
 }
 
-// biome-ignore lint/suspicious/noExplicitAny: dynamic property access
-export function merge<T extends Record<string, any>>(defaultObj: T, userObj: T): T {
-  // 원본 보존을 위해 defaultObj 복사
+export function merge<T extends object>(defaultObj: T, userObj: T): T {
+  // 원본을 보존하면서 사용자 설정의 own enumerable 속성만 병합합니다.
   const result = { ...defaultObj };
-
-  // userObj의 각 속성을 순회
-  for (const key in userObj) {
-    // userObj의 own property만 처리 (프로토타입 체인 제외)
-    if (Object.hasOwn(userObj, key)) {
-      const userValue = userObj[key];
-      const defaultValue = result[key];
-
-      // 두 값이 모두 객체이고, 배열이 아닌 경우 재귀적으로 병합
-      if (isPlainObject(userValue) && isPlainObject(defaultValue)) {
-        result[key] = merge(defaultValue, userValue);
-      } else {
-        // 그 외의 경우 userObj의 값으로 덮어쓰기
-        result[key] = userValue;
-      }
-    }
+  const defaultEntries = new Map(Object.entries(defaultObj));
+
+  for (const [key, userValue] of Object.entries(userObj)) {
+    const defaultValue = defaultEntries.get(key);
+    const mergedValue =
+      isPlainObject(userValue) && isPlainObject(defaultValue)
+        ? merge(defaultValue, userValue)
+        : userValue;
+    Object.assign(result, { [key]: mergedValue });
   }
 
   return result;
@@ -118,10 +116,10 @@ export function merge<T extends Record<string, any>>(defaultObj: T, userObj: T):
 
 // plain object 판별 헬퍼 함수
 // (배열, null, Date 등을 제외한 순수 객체만 true)
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
+export function isPlainObject<Value>(value: Value): value is Value & object {
   return (
     value !== null &&
-    typeof value === "object" &&
+    isObjectValue(value) &&
     !Array.isArray(value) &&
     Object.prototype.toString.call(value) === "[object Object]"
   );

package/src/utils/zod-error.ts

@@ -1,5 +1,7 @@
 import { type z } from "zod";
 
+import { isNumberValue, isSymbolValue } from "./runtime-value";
+
 type ValidationError = {
   path: string[];
   message: string;
@@ -8,11 +10,11 @@ type ValidationError = {
 export function humanizeZodError(error: z.ZodError): ValidationError[] {
   return error.issues.map(({ path: originPath, message }) => {
     const path = originPath.map((item) => {
-      if (typeof item === "symbol") {
+      if (isSymbolValue(item)) {
         return item.description ?? item.toString();
       }
 
-      if (typeof item === "number") {
+      if (isNumberValue(item)) {
         return `[${item}]`;
       }
 

package/src/vector/chunking.ts

@@ -1,6 +1,11 @@
 import { DEFAULT_VECTOR_CONFIG } from "./config";
 import { type Chunk, type ChunkingConfig } from "./types";
 
+interface ExtractedChunk {
+  chunk: string;
+  length: number;
+}
+
 /**
  * 텍스트 청킹
  * - 현재 가이드에서는 400토큰 이하만 저장하므로 기본적으로 사용하지 않음
@@ -69,7 +74,7 @@ export class Chunking {
     return Math.ceil(text.length / effectiveChunkSize);
   }
 
-  private extractChunk(text: string): { chunk: string; length: number } {
+  private extractChunk(text: string): ExtractedChunk {
     if (text.length <= this.config.chunkSize) {
       return { chunk: text, length: text.length };
     }

package/src/vector/embedding.ts

@@ -139,7 +139,8 @@ class EmbeddingClass {
     const model = openai.embeddingModel(openaiConfig.model);
 
     const { embeddings, usage } = await embedMany({
-      model: model as EmbeddingModel,
+      model:
+        /* SAFETY: 호출 경계의 선행 검증과 소유 타입 계약이 이 값의 타입을 보장한다. */ model as EmbeddingModel,
       values: texts,
     });
 

package/src/vector/types.ts

@@ -2,6 +2,8 @@
  * pgvector 통합을 위한 타입 정의
  */
 
+import { type JsonValue } from "../types/types";
+
 /** 임베딩 제공자 */
 export type EmbeddingProvider = "voyage" | "openai";
 
@@ -24,14 +26,14 @@ export interface Chunk {
 }
 
 /** 벡터 검색 결과 */
-export interface VectorSearchResult<T = Record<string, unknown>> {
+export interface VectorSearchResult<T = Record<string, JsonValue>> {
   id: number | string;
   similarity: number;
   data: T;
 }
 
 /** 하이브리드 검색 결과 (Vector + FTS) */
-export interface HybridSearchResult<T = Record<string, unknown>> extends VectorSearchResult<T> {
+export interface HybridSearchResult<T = Record<string, JsonValue>> extends VectorSearchResult<T> {
   vectorScore?: number;
   ftsScore?: number;
 }

package/tsdown.api.config.ts

@@ -6,9 +6,12 @@ import { defineConfig } from "tsdown";
 const srcRoot = path.resolve(process.cwd(), "src");
 const ignoredSuffixes = [".test.ts", ".test-hold.ts", ".ignore.ts", ".d.ts"];
 const ignoredDirectories = new Set(["__mocks__", "_templates", "wasted_src"]);
+interface BuildEntries {
+  [entryName: string]: string;
+}
 
-function collectEntries(directory: string): Record<string, string> {
-  const entries: Record<string, string> = {};
+function collectEntries(directory: string): BuildEntries {
+  const entries: BuildEntries = {};
 
   for (const entry of readdirSync(directory)) {
     if (ignoredDirectories.has(entry)) {