sonamu 0.5.7 → 0.7.0

package/src/template/template-types.ts

@@ -0,0 +1,16 @@
+/**
+ * 템플릿 그룹 (관련 템플릿 묶음 실행)
+ */
+export type TemplateGroup = {
+  name: string;
+  description?: string;
+  templates: Array<{
+    key: string;
+    getOptions: (baseOptions: Record<string, unknown>) => Record<string, unknown>;
+  }>;
+};
+
+/**
+ * 템플릿 프리셋 (템플릿별 기본 옵션)
+ */
+export type TemplatePreset = Record<string, Record<string, unknown>>;

package/src/template/template.ts

@@ -0,0 +1,105 @@
+import path from "path";
+import type { EntityNamesRecord } from "../entity/entity-manager";
+import type { TemplateKey, TemplateOptions } from "../types/types";
+import { globAsync } from "../utils/async-utils";
+import { importMembers } from "../utils/esm-utils";
+
+export type RenderedTemplate = {
+  target: string;
+  path: string;
+  body: string;
+  importKeys: string[];
+  customHeaders?: string[];
+  preTemplates?: {
+    key: TemplateKey;
+    options: TemplateOptions[TemplateKey];
+  }[];
+};
+
+/**
+ * 템플릿을 나타내는 베이스 클래스입니다.
+ */
+export abstract class Template {
+  private static templates: Map<TemplateKey, Template> = new Map();
+
+  constructor(public key: TemplateKey) {}
+
+  /**
+   * 템플릿 구현체가 있는 디렉토리의 모든 템플릿을 로드합니다.
+   * 템플릿이 필요(Template.find)해지기 전에 최소 한 번 호출해주셔야 합니다.
+   * @deprecated TemplateManager.autoload() 사용 권장
+   */
+  public static async autoload() {
+    const templateFiles = await globAsync(
+      // Sonamu의 코드베이스는 항상 빌드된 채로 dist 속에 머무르므로,
+      // 현재 파일을 기준으로 마찬가지로 dist 속에 있는 템플릿 구현체 js 파일들을 찾습니다.
+      path.join(import.meta.dirname, "implementations/*.template.js"),
+    );
+
+    for (const templateFile of templateFiles) {
+      // biome-ignore lint/suspicious/noExplicitAny: importMembers의 반환 타입을 명시적으로 지정할 수 없음
+      const templates = await importMembers<any>(templateFile);
+      if (
+        templates.length === 1 &&
+        typeof templates[0].value === "function" &&
+        templates[0].value.prototype instanceof Template
+      ) {
+        // 클래스의 인스턴스를 생성하여 등록
+        const instance = new templates[0].value();
+        Template.templates.set(instance.key, instance);
+      } else {
+        throw new Error(
+          `Template ${templateFile} should export only one class that extends Template`,
+        );
+      }
+    }
+
+    // console.log(
+    //   chalk.gray(`[Loading] Loaded ${this.templates.size} templates.`)
+    // );
+  }
+
+  /**
+   * 템플릿 **인스턴스**를 key로 찾아옵니다.
+   * 만약 템플릿이 로드(loadAll)되지 않았거나 찾는 템플릿이 없다면 에러를 던집니다.
+   * @deprecated TemplateManager.get() 사용 권장
+   * @param key
+   * @returns
+   */
+  public static find(key: TemplateKey): Template {
+    const instance = Template.templates.get(key);
+    if (!instance) {
+      throw new Error(
+        `Template ${key} not found. It might be becasuse you tried to find a template before loading all templates. Did you call Template.loadAll()?`,
+      );
+    }
+    return instance;
+  }
+
+  /**
+   * 내부용: TemplateManager에서 사용
+   */
+  public static _getTemplatesMap(): Map<TemplateKey, Template> {
+    return Template.templates;
+  }
+
+  /**
+   * 내부용: TemplateManager에서 사용
+   */
+  public static _clearTemplates(): void {
+    Template.templates.clear();
+  }
+
+  public abstract render(
+    options: TemplateOptions[TemplateKey],
+    ...extra: unknown[]
+  ): RenderedTemplate | Promise<RenderedTemplate>;
+
+  public abstract getTargetAndPath(
+    names?: EntityNamesRecord,
+    ...extra: unknown[]
+  ): {
+    target: string;
+    path: string;
+  };
+}

package/src/template/zod-converter.ts

@@ -0,0 +1,525 @@
+/**
+ * zod-converter 구성
+ * 1. 유틸리티
+ *  - getZodTypeById
+ *
+ * 2. Zod 타입 변환 (EntityProp -> ZodType)
+ *  - propToZodType
+ *
+ * 3. EntityProp/Node -> Zod 코드 문자열
+ *  - propToZodTypeDef
+ *  - propNodeToZodTypeDef
+ *
+ * 4. Zod 타입 인스턴스를 해당하는 Zod 코드 문자열로 변환 (ZodType -> ZodCode)
+ *  - zodTypeToZodCode
+ *
+ * 5. Zod 타입을 UI 렌더링에 사용할 수 있는 RenderingNode로 변환 (ZodType -> RenderingNode)
+ *  - zodTypeToRenderingNode
+ *  - resolveRenderType
+ */
+
+import inflection from "inflection";
+import path from "path";
+import { z } from "zod";
+import type { $ZodLooseShape } from "zod/v4/core";
+import { Sonamu } from "../api/sonamu";
+import { EntityManager } from "../entity/entity-manager";
+import {
+  type EntityProp,
+  type EntityPropNode,
+  isBelongsToOneRelationProp,
+  isBigIntegerArrayProp,
+  isBigIntegerSingleProp,
+  isBooleanArrayProp,
+  isBooleanSingleProp,
+  isDateArrayProp,
+  isDateSingleProp,
+  isEnumArrayProp,
+  isEnumSingleProp,
+  isIntegerArrayProp,
+  isIntegerSingleProp,
+  isJsonProp,
+  isNumberArrayProp,
+  isNumberSingleProp,
+  isNumericArrayProp,
+  isNumericSingleProp,
+  isOneToOneRelationProp,
+  isRelationProp,
+  isStringArrayProp,
+  isStringSingleProp,
+  isUuidArrayProp,
+  isUuidSingleProp,
+  isVirtualProp,
+  type RenderingNode,
+} from "../types/types";
+import { createImportUrl } from "../utils/esm-utils";
+
+// <any>를 자제하고, Zod에서 제약하는 기본적인 Generic Type Parameter를 사용함.
+type AnyZodRecord = z.ZodRecord<z.ZodString | z.ZodNumber | z.ZodSymbol, z.ZodType>;
+type AnyZodObject = z.ZodObject<$ZodLooseShape>;
+type AnyZodNullable = z.ZodNullable<z.ZodType>;
+type AnyZodDefault = z.ZodDefault<z.ZodType>;
+type AnyZodUnion = z.ZodUnion<z.ZodType[]>;
+type AnyZodArray = z.ZodArray<z.ZodType>;
+type AnyZodOptional = z.ZodOptional<z.ZodType>;
+
+/**
+ * Zod 타입 ID로부터 동적으로 Zod 스키마를 로드합니다.
+ * dist 디렉토리에서 ESM으로 import하여 가져옵니다.
+ */
+export async function getZodTypeById(zodTypeId: string): Promise<z.ZodTypeAny> {
+  const modulePath = EntityManager.getModulePath(zodTypeId);
+  const moduleAbsPath = path.join(Sonamu.apiRootPath, "dist", "application", `${modulePath}.js`);
+  const importUrl = createImportUrl(moduleAbsPath);
+  const imported = await import(importUrl);
+
+  if (!imported[zodTypeId]) {
+    throw new Error(`존재하지 않는 zodTypeId ${zodTypeId}`);
+  }
+  return imported[zodTypeId].describe(zodTypeId);
+}
+
+/**
+ * EntityProp을 Zod 타입으로 변환합니다.
+ * 각 prop의 타입에 따라 적절한 Zod validator를 생성합니다.
+ */
+export async function propToZodType(prop: EntityProp): Promise<z.ZodTypeAny> {
+  let zodType: z.ZodTypeAny = z.unknown();
+  if (isIntegerSingleProp(prop)) {
+    zodType = z.number().int();
+  } else if (isIntegerArrayProp(prop)) {
+    zodType = z.number().int().array();
+  } else if (isBigIntegerSingleProp(prop)) {
+    zodType = z.bigint();
+  } else if (isBigIntegerArrayProp(prop)) {
+    zodType = z.bigint().array();
+  } else if (isEnumSingleProp(prop)) {
+    zodType = await getZodTypeById(prop.id);
+  } else if (isEnumArrayProp(prop)) {
+    zodType = (await getZodTypeById(prop.id)).array();
+  } else if (isStringSingleProp(prop)) {
+    if (prop.length) {
+      zodType = z.string().max(prop.length);
+    } else {
+      zodType = z.string();
+    }
+  } else if (isStringArrayProp(prop)) {
+    if (prop.length) {
+      zodType = z.string().max(prop.length).array();
+    } else {
+      zodType = z.string().array();
+    }
+  } else if (isNumberSingleProp(prop)) {
+    zodType = z.number();
+  } else if (isNumberArrayProp(prop)) {
+    zodType = z.number().array();
+  } else if (isNumericSingleProp(prop)) {
+    zodType = z.string();
+  } else if (isNumericArrayProp(prop)) {
+    zodType = z.string().array();
+  } else if (isBooleanSingleProp(prop)) {
+    zodType = z.boolean();
+  } else if (isBooleanArrayProp(prop)) {
+    zodType = z.boolean().array();
+  } else if (isDateSingleProp(prop)) {
+    zodType = z.date();
+  } else if (isDateArrayProp(prop)) {
+    zodType = z.date().array();
+  } else if (isUuidSingleProp(prop)) {
+    zodType = z.uuid();
+  } else if (isUuidArrayProp(prop)) {
+    zodType = z.uuid().array();
+  } else if (isJsonProp(prop)) {
+    zodType = await getZodTypeById(prop.id);
+  } else if (isVirtualProp(prop)) {
+    zodType = await getZodTypeById(prop.id);
+  } else if (isRelationProp(prop)) {
+    if (isBelongsToOneRelationProp(prop) || (isOneToOneRelationProp(prop) && prop.hasJoinColumn)) {
+      zodType = z.number().int();
+    }
+  } else {
+    throw new Error(`prop을 zodType으로 변환하는데 실패 ${prop}}`);
+  }
+
+  if ((prop as { unsigned?: boolean }).unsigned) {
+    zodType = (zodType as z.ZodNumber).nonnegative();
+  }
+  if (prop.nullable) {
+    zodType = zodType.nullable();
+  }
+
+  return zodType;
+}
+
+/**
+ * EntityProp을 Zod 타입 정의 코드 문자열로 변환합니다.
+ */
+export function propToZodTypeDef(prop: EntityProp, injectImportKeys: string[]): string {
+  let stmt: string;
+  if (isIntegerSingleProp(prop)) {
+    stmt = `${prop.name}: z.int()`;
+  } else if (isIntegerArrayProp(prop)) {
+    stmt = `${prop.name}: z.int().array()`;
+  } else if (isBigIntegerSingleProp(prop)) {
+    stmt = `${prop.name}: z.bigint()`;
+  } else if (isBigIntegerArrayProp(prop)) {
+    stmt = `${prop.name}: z.bigint().array()`;
+  } else if (isEnumSingleProp(prop)) {
+    stmt = `${prop.name}: ${prop.id}`;
+    injectImportKeys.push(prop.id);
+  } else if (isEnumArrayProp(prop)) {
+    stmt = `${prop.name}: ${prop.id}.array()`;
+    injectImportKeys.push(prop.id);
+  } else if (isStringSingleProp(prop)) {
+    if (prop.length) {
+      stmt = `${prop.name}: z.string().max(${prop.length})`;
+    } else {
+      stmt = `${prop.name}: z.string()`;
+    }
+  } else if (isStringArrayProp(prop)) {
+    if (prop.length) {
+      stmt = `${prop.name}: z.string().max(${prop.length}).array()`;
+    } else {
+      stmt = `${prop.name}: z.string().array()`;
+    }
+  } else if (isNumberSingleProp(prop)) {
+    stmt = `${prop.name}: z.number()`;
+  } else if (isNumberArrayProp(prop)) {
+    stmt = `${prop.name}: z.number().array()`;
+  } else if (isNumericSingleProp(prop)) {
+    stmt = `${prop.name}: z.string()`;
+  } else if (isNumericArrayProp(prop)) {
+    stmt = `${prop.name}: z.string().array()`;
+  } else if (isDateSingleProp(prop)) {
+    stmt = `${prop.name}: z.date()`;
+  } else if (isDateArrayProp(prop)) {
+    stmt = `${prop.name}: z.date().array()`;
+  } else if (isBooleanSingleProp(prop)) {
+    stmt = `${prop.name}: z.boolean()`;
+  } else if (isBooleanArrayProp(prop)) {
+    stmt = `${prop.name}: z.boolean().array()`;
+  } else if (isUuidSingleProp(prop)) {
+    stmt = `${prop.name}: z.uuid()`;
+  } else if (isUuidArrayProp(prop)) {
+    stmt = `${prop.name}: z.uuid().array()`;
+  } else if (isJsonProp(prop)) {
+    stmt = `${prop.name}: ${prop.id}`;
+    injectImportKeys.push(prop.id);
+  } else if (isVirtualProp(prop)) {
+    stmt = `${prop.name}: ${prop.id}`;
+    injectImportKeys.push(prop.id);
+  } else if (isRelationProp(prop)) {
+    if (isBelongsToOneRelationProp(prop) || (isOneToOneRelationProp(prop) && prop.hasJoinColumn)) {
+      stmt = `${prop.name}_id: z.int()`;
+    } else {
+      // 그외 relation 케이스 제외
+      return `// ${prop.name}: ${prop.relationType} ${prop.with}`;
+    }
+  } else {
+    return "// unable to resolve";
+  }
+
+  if ((prop as { unsigned?: boolean }).unsigned) {
+    stmt += ".nonnegative()";
+  }
+  if (prop.nullable) {
+    stmt += ".nullable()";
+  }
+
+  return `${stmt},`;
+}
+
+/**
+ * EntityPropNode를 Zod 타입 정의 코드 문자열로 변환합니다.
+ * plain, array, object 노드 타입을 재귀적으로 처리하여 중첩 구조를 지원합니다.
+ */
+export function propNodeToZodTypeDef(propNode: EntityPropNode, injectImportKeys: string[]): string {
+  if (propNode.nodeType === "plain") {
+    return propToZodTypeDef(propNode.prop, injectImportKeys);
+  } else if (propNode.nodeType === "array") {
+    return [
+      propNode.prop ? `${propNode.prop.name}: ` : "",
+      "z.array(z.object({",
+      propNode.children
+        .map((childPropNode) => propNodeToZodTypeDef(childPropNode, injectImportKeys))
+        .join("\n"),
+      "",
+      "})),",
+    ].join("\n");
+  } else if (propNode.nodeType === "object") {
+    return [
+      propNode.prop ? `${propNode.prop.name}: ` : "",
+      "z.object({",
+      propNode.children
+        .map((childPropNode) => propNodeToZodTypeDef(childPropNode, injectImportKeys))
+        .join("\n"),
+      "",
+      `})${propNode.prop?.nullable ? ".nullable()" : ""},`,
+    ].join("\n");
+  } else {
+    throw Error;
+  }
+}
+
+// TODO(Haze, 251031): "template_literal", "file"에 대한 지원이 필요함.
+export function zodTypeToTsTypeDef(zt: z.ZodType): string {
+  switch (zt.def.type) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "bigint":
+    case "date":
+    case "null":
+    case "undefined":
+    case "any":
+    case "unknown":
+    case "never":
+      return zt.def.type;
+    case "nullable":
+      return `${zodTypeToTsTypeDef((zt as AnyZodNullable).def.innerType)} | null`;
+    case "default":
+      return zodTypeToTsTypeDef((zt as AnyZodDefault).def.innerType);
+    case "record": {
+      const recordType = zt as AnyZodRecord;
+      return `{ [ key: ${zodTypeToTsTypeDef(recordType.def.keyType)} ]: ${zodTypeToTsTypeDef(recordType.def.valueType)}}`;
+    }
+    case "literal":
+      return Array.from((zt as z.ZodLiteral).values)
+        .map((value) => {
+          if (typeof value === "string") {
+            return `"${value}"`;
+          }
+
+          if (value === null) {
+            return `null`;
+          }
+
+          if (value === undefined) {
+            return `undefined`;
+          }
+
+          return `${value}`;
+        })
+        .join(" | ");
+    case "union":
+      return `${(zt as AnyZodUnion).options
+        .map((option) => zodTypeToTsTypeDef(option))
+        .join(" | ")}`;
+    case "enum":
+      return `${(zt as z.ZodEnum).options.map((val) => `"${val}"`).join(" | ")}`;
+    case "array":
+      return `${zodTypeToTsTypeDef((zt as AnyZodArray).element)}[]`;
+    case "object": {
+      const shape = (zt as AnyZodObject).shape;
+      return [
+        "{",
+        ...Object.keys(shape).map((key) => {
+          if (shape[key].def.type === "optional") {
+            return `${key}?: ${zodTypeToTsTypeDef(shape[key].def.innerType)},`;
+          } else {
+            return `${key}: ${zodTypeToTsTypeDef(shape[key])},`;
+          }
+        }),
+        "}",
+      ].join("\n");
+    }
+    case "optional":
+      return `${zodTypeToTsTypeDef((zt as AnyZodOptional).def.innerType)} | undefined`;
+    default:
+      throw new Error(`처리되지 않은 ZodType ${zt.def.type}`);
+  }
+}
+
+// TODO(Haze, 251031): "template_literal", "file"에 대한 지원이 필요함.
+/**
+ * Zod 타입 인스턴스를 해당하는 Zod 코드 문자열로 변환합니다.
+ */
+export function zodTypeToZodCode(zt: z.ZodType): string {
+  switch (zt.def.type) {
+    case "string":
+      return "z.string()";
+    case "number":
+      return "z.number()";
+    case "bigint":
+      return "z.bigint()";
+    case "boolean":
+      return "z.boolean()";
+    case "date":
+      return "z.date()";
+    case "null":
+      return "z.null()";
+    case "undefined":
+      return "z.undefined()";
+    case "any":
+      return "z.any()";
+    case "unknown":
+      return "z.unknown()";
+    case "never":
+      return "z.never()";
+    case "nullable":
+      return `${zodTypeToZodCode((zt as AnyZodNullable).def.innerType)}.nullable()`;
+    case "default": {
+      const zDefaultDef = (zt as AnyZodDefault).def;
+      return `${zodTypeToZodCode(zDefaultDef.innerType)}.default(${zDefaultDef.defaultValue})`;
+    }
+    case "record": {
+      const zRecordDef = (zt as AnyZodRecord).def;
+      return `z.record(${zodTypeToZodCode(zRecordDef.keyType)}, ${zodTypeToZodCode(
+        zRecordDef.valueType,
+      )})`;
+    }
+    case "literal": {
+      const items = Array.from((zt as z.ZodLiteral<string | number>).values).map((value) => {
+        if (typeof value === "string") {
+          return `"${value}"`;
+        }
+
+        if (value === null) {
+          return `null`;
+        }
+
+        if (value === undefined) {
+          return `undefined`;
+        }
+
+        return `${value}`;
+      });
+
+      if (items.length === 1) {
+        return `z.literal(${items[0]})`;
+      }
+      return `z.literal([${items.join(", ")}])`;
+    }
+    case "union":
+      return `z.union([${(zt as AnyZodUnion).def.options
+        .map((option: z.ZodType) => zodTypeToZodCode(option))
+        .join(",")}])`;
+    case "enum":
+      // NOTE: z.enum(["A", "B"])도 z.enum({ A: "A", B: "B" })로 처리됨.
+      return `z.enum({${Object.entries((zt as z.ZodEnum).def.entries)
+        .map(([key, val]) => (typeof val === "string" ? `${key}: "${val}"` : `${key}: ${val}`))
+        .join(", ")}})`;
+    case "array":
+      return `z.array(${zodTypeToZodCode((zt as z.ZodArray<z.ZodType>).def.element)})`;
+    case "object": {
+      const shape = (zt as AnyZodObject).shape;
+      return [
+        "z.object({",
+        ...Object.keys(shape).map((key) => `${key}: ${zodTypeToZodCode(shape[key])},`),
+        "})",
+      ].join("\n");
+    }
+    case "optional":
+      return `${zodTypeToZodCode((zt as z.ZodOptional<z.ZodType>).def.innerType)}.optional()`;
+    case "file":
+      return `z.file()`;
+    case "intersection": {
+      const zIntersectionDef = (zt as z.ZodIntersection<z.ZodType, z.ZodType>).def;
+      return `z.intersection(${zodTypeToZodCode(zIntersectionDef.left)}, ${zodTypeToZodCode(zIntersectionDef.right)})`;
+    }
+    default:
+      throw new Error(`처리되지 않은 ZodType ${zt.def.type}`);
+  }
+}
+
+/**
+ * Zod 타입을 UI 렌더링에 사용할 수 있는 RenderingNode로 변환합니다.
+ * 재귀적으로 중첩된 타입들을 처리합니다.
+ */
+export function zodTypeToRenderingNode(
+  zodType: z.ZodTypeAny,
+  baseKey: string = "root",
+): RenderingNode {
+  const def = {
+    name: baseKey,
+    label: inflection.camelize(baseKey, false),
+    zodType,
+  };
+  if (zodType instanceof z.ZodObject) {
+    const columnKeys = Object.keys(zodType.shape);
+    const children = columnKeys.map((key) => {
+      const innerType = zodType.shape[key];
+      return zodTypeToRenderingNode(innerType, key);
+    });
+    return {
+      ...def,
+      renderType: "object",
+      children,
+    };
+  } else if (zodType instanceof z.ZodArray) {
+    const innerType = (zodType as z.ZodArray<z.ZodTypeAny>).def.element;
+    if (innerType instanceof z.ZodString && baseKey.includes("images")) {
+      return {
+        ...def,
+        renderType: "array-images",
+      };
+    }
+    return {
+      ...def,
+      renderType: "array",
+      element: zodTypeToRenderingNode(innerType, baseKey),
+    };
+  } else if (zodType instanceof z.ZodUnion) {
+    const optionNodes = (zodType as z.ZodUnion<z.ZodType[]>).def.options.map((opt) =>
+      zodTypeToRenderingNode(opt, baseKey),
+    );
+    // TODO: ZodUnion이 들어있는 경우 핸들링
+    return optionNodes[0];
+  } else if (zodType instanceof z.ZodOptional) {
+    return {
+      ...zodTypeToRenderingNode((zodType as z.ZodOptional<z.ZodType>).def.innerType, baseKey),
+      optional: true,
+    };
+  } else if (zodType instanceof z.ZodNullable) {
+    return {
+      ...zodTypeToRenderingNode((zodType as z.ZodNullable<z.ZodType>).def.innerType, baseKey),
+      nullable: true,
+    };
+  } else {
+    return {
+      ...def,
+      renderType: resolveRenderType(baseKey, zodType),
+    };
+  }
+}
+
+/**
+ * Zod 타입과 키 이름으로부터 적절한 RenderType을 결정합니다.
+ */
+function resolveRenderType(key: string, zodType: z.ZodTypeAny): RenderingNode["renderType"] {
+  if (zodType instanceof z.ZodDate) {
+    return "datetime";
+  } else if (zodType instanceof z.ZodString) {
+    if (key.includes("img") || key.includes("image")) {
+      return "string-image";
+    } else if (zodType.description === "SQLDateTimeString") {
+      return "string-datetime";
+    } else if (key.endsWith("date")) {
+      return "string-date";
+    } else {
+      return "string-plain";
+    }
+  } else if (zodType instanceof z.ZodNumber) {
+    if (key === "id") {
+      return "number-id";
+    } else if (key.endsWith("_id")) {
+      return "number-fk_id";
+    } else {
+      return "number-plain";
+    }
+  } else if (zodType instanceof z.ZodBoolean) {
+    return "boolean";
+  } else if (zodType instanceof z.ZodEnum) {
+    return "enums";
+  } else if (zodType instanceof z.ZodRecord) {
+    return "record";
+  } else if (zodType instanceof z.ZodAny || zodType instanceof z.ZodUnknown) {
+    return "string-plain";
+  } else if (zodType instanceof z.ZodUnion) {
+    return "string-plain";
+  } else if (zodType instanceof z.ZodLiteral) {
+    return "string-plain";
+  } else {
+    throw new Error(`타입 파싱 불가 ${key} ${zodType.def.type}`);
+  }
+}