@blastlabs/utils 1.12.1 → 1.13.0

package/bin/entity-generator-guide.md

@@ -0,0 +1,126 @@
+# 엔티티 자동 생성 스크립트 사용법
+
+## 개요
+
+`generate-entity.cjs` 스크립트를 사용하여 새로운 엔티티의 기본 구조를 자동으로 생성할 수 있습니다.
+
+## 사용법
+
+```bash
+# entities 폴더로 이동
+cd apps/admin/src/entities
+
+# 엔티티 생성
+node generate-entity.cjs <entity-name>
+```
+
+## 예시
+
+```bash
+# user-profile 엔티티 생성
+node generate-entity.cjs user-profile
+
+# my-entity 엔티티 생성
+node generate-entity.cjs my-entity
+
+# product-review 엔티티 생성
+node generate-entity.cjs product-review
+```
+
+## 생성되는 파일 구조
+
+```
+{entity-name}/
+├── index.ts                           # 엔티티 메인 export 파일
+├── api/
+│   ├── get-{entity-name}-list.ts      # API 호출 함수
+│   ├── {entity-name}-queries.ts       # React Query 설정
+│   ├── index.ts                       # API 모듈 export
+│   ├── mapper/
+│   │   └── map-{entity-name}.ts       # 데이터 매핑 함수
+│   └── query/
+│       └── {entity-name}-list-query.ts # 쿼리 타입 정의
+└── model/
+    └── {entity-name}.ts               # Zod 스키마 및 타입
+```
+
+## 자동 생성 후 추가 작업
+
+스크립트 실행 후 다음 작업들을 수동으로 완료해야 합니다:
+
+### 1. query-keys.ts 파일 업데이트
+
+```typescript
+export const {ENTITY_NAME}_QUERY_KEYS = {
+  all: ["{entity-name}"] as const,
+  lists: () => [...{ENTITY_NAME}_QUERY_KEYS.all, "list"] as const,
+  list: (filters: {EntityName}ListParams) =>
+    [...{ENTITY_NAME}_QUERY_KEYS.lists(), filters] as const,
+  details: () => [...{ENTITY_NAME}_QUERY_KEYS.all, "detail"] as const,
+  detail: (id: number) => [...{ENTITY_NAME}_QUERY_KEYS.details(), id] as const,
+};
+```
+
+### 2. model/{entity-name}.ts 수정
+
+실제 API 응답 구조에 맞게 Zod 스키마를 수정해주세요:
+
+```typescript
+export const {EntityName}Schema = z.object({
+  id: z.number(),
+  // 실제 필드들 추가
+  name: z.string(),
+  description: z.string().nullable(),
+  createDate: z.string(),
+  updateDate: z.string(),
+});
+```
+
+### 3. api/mapper/map-{entity-name}.ts 수정
+
+API 응답 데이터를 모델에 맞게 매핑하는 로직을 수정해주세요:
+
+```typescript
+export const map{EntityName} = (item: {EntityName}) => {
+  const res = {EntityName}Schema.safeParse({
+    id: item.id,
+    name: item.name,
+    description: item.description,
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  // ...
+};
+```
+
+### 4. api/get-{entity-name}-list.ts 수정
+
+실제 API 엔드포인트 메서드명으로 변경해주세요:
+
+```typescript
+export const get{EntityName}List = (filters: {EntityName}ListQuery) => {
+  const customApi = createInstance(import.meta.env.VITE_BASE_URL);
+  // 실제 API 메서드명으로 변경
+  return customApi.default.admin{EntityName}List(filters);
+};
+```
+
+### 5. api/query/{entity-name}-list-query.ts 수정
+
+필요한 필터링 옵션을 추가해주세요:
+
+```typescript
+export type {EntityName}ListQuery = {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  status?: string;
+  // 추가 필터 옵션들...
+};
+```
+
+## 참고사항
+
+- 엔티티 이름은 kebab-case로 입력해주세요 (예: `user-profile`, `product-review`)
+- 생성된 파일들은 기본 템플릿이므로 실제 API 구조에 맞게 수정이 필요합니다
+- popular-product, popular-review 폴더를 참고하여 패턴을 확인할 수 있습니다

package/bin/generate-entity.cjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// 엔티티 이름을 kebab-case로 변환
+function toKebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+// 엔티티 이름을 PascalCase로 변환
+function toPascalCase(str) {
+  return str
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}
+
+// 엔티티 이름을 camelCase로 변환
+function toCamelCase(str) {
+  const pascalCase = toPascalCase(str);
+  return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+
+function createEntityStructure(entityName, targetDir) {
+  const kebabName = toKebabCase(entityName);
+  const pascalName = toPascalCase(kebabName);
+  const camelName = toCamelCase(kebabName);
+
+  // 현재 작업 디렉토리 기준으로 생성
+  const basePath = path.join(targetDir, kebabName);
+
+  // 디렉토리 생성
+  const dirs = [
+    basePath,
+    path.join(basePath, "api"),
+    path.join(basePath, "api", "mapper"),
+    path.join(basePath, "api", "query"),
+    path.join(basePath, "model"),
+  ];
+
+  dirs.forEach((dir) => {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  });
+
+  // 파일 템플릿 생성
+  createFiles(basePath, kebabName, pascalName, camelName);
+
+  console.log(`✅ ${kebabName} 엔티티가 성공적으로 생성되었습니다!`);
+  console.log(`📍 위치: ${basePath}`);
+  console.log(`\n생성된 파일들:`);
+  console.log(`📁 ${kebabName}/`);
+  console.log(`├── index.ts`);
+  console.log(`├── api/`);
+  console.log(`│   ├── get-${kebabName}-list.ts`);
+  console.log(`│   ├── get-${kebabName}-detail.ts`);
+  console.log(`│   ├── ${kebabName}-queries.ts`);
+  console.log(`│   ├── index.ts`);
+  console.log(`│   ├── mapper/`);
+  console.log(`│   │   ├── map-${kebabName}.ts`);
+  console.log(`│   │   └── map-${kebabName}-detail.ts`);
+  console.log(`│   └── query/`);
+  console.log(`│       └── ${kebabName}-list-query.ts`);
+  console.log(`└── model/`);
+  console.log(`    ├── ${kebabName}.ts`);
+  console.log(`    └── ${kebabName}-detail.ts`);
+
+  console.log(`\n⚠️  추가 작업이 필요합니다:`);
+  console.log(
+    `1. query-keys.ts 파일에 ${pascalName.toUpperCase()}_QUERY_KEYS 추가`,
+  );
+  console.log(`2. API 스키마에 맞게 model과 mapper 수정`);
+  console.log(`3. 실제 API 엔드포인트에 맞게 get-${kebabName}-list.ts 수정`);
+}
+
+function createFiles(basePath, kebabName, pascalName, camelName) {
+  // index.ts
+  const indexContent = `export * as ${camelName}Api from "./api";
+`;
+
+  // api/index.ts
+  const apiIndexContent = `export { get${pascalName}List } from "./get-${kebabName}-list";
+export { get${pascalName}Detail } from "./get-${kebabName}-detail";
+export { ${camelName}Queries } from "./${kebabName}-queries";
+`;
+
+  // api/get-{entity}-list.ts
+  const getListContent = `// TODO: API 클라이언트 import 추가
+// import { apiClient } from "@/shared/api";
+import { ${pascalName}ListQuery } from "./query/${kebabName}-list-query";
+
+export const get${pascalName}List = async (filters: ${pascalName}ListQuery) => {
+  // TODO: 실제 API 호출로 변경 필요
+  // return apiClient.get("/api/${kebabName}", { params: filters });
+  throw new Error("API 호출 구현 필요");
+};
+`;
+
+  // api/get-{entity}-detail.ts
+  const getDetailContent = `// TODO: API 클라이언트 import 추가
+// import { apiClient } from "@/shared/api";
+
+export const get${pascalName}Detail = async (id: number) => {
+  // TODO: 실제 API 호출로 변경 필요
+  // return apiClient.get(\`/api/${kebabName}/\${id}\`);
+  throw new Error("API 호출 구현 필요");
+};
+`;
+
+  // api/{entity}-queries.ts
+  const queriesContent = `import { queryOptions } from "@tanstack/react-query";
+import { ${pascalName}ListQuery } from "./query/${kebabName}-list-query";
+import { get${pascalName}List } from "./get-${kebabName}-list";
+import { get${pascalName}Detail } from "./get-${kebabName}-detail";
+import { map${pascalName} } from "./mapper/map-${kebabName}";
+import { map${pascalName}Detail } from "./mapper/map-${kebabName}-detail";
+
+export const ${camelName}Queries = {
+  all: () => ["${kebabName}"],
+  lists: () => [...${camelName}Queries.all(), "list"],
+  list: (filters: ${pascalName}ListQuery) =>
+    queryOptions({
+      queryKey: [...${camelName}Queries.lists(), filters],
+      queryFn: () => get${pascalName}List(filters),
+      select: (data) => {
+        return {
+          ...data,
+          items: data.items.map(map${pascalName}),
+        };
+      },
+    }),
+  details: () => [...${camelName}Queries.all(), "detail"],
+  detail: (id: number) =>
+    queryOptions({
+      queryKey: [...${camelName}Queries.details(), id],
+      queryFn: () => get${pascalName}Detail(id),
+      select: (data) => map${pascalName}Detail(data),
+    }),
+};
+`;
+
+  // api/mapper/map-{entity}.ts
+  const mapperContent = `import { ${pascalName}Schema } from "../../model/${kebabName}";
+
+// TODO: API 응답 타입을 실제 타입으로 변경
+type ${pascalName}Response = {
+  id: number;
+  createDate: string;
+  updateDate: string;
+};
+
+export const map${pascalName} = (item: ${pascalName}Response) => {
+  const res = ${pascalName}Schema.safeParse({
+    id: item.id,
+    // TODO: 실제 API 응답 구조에 맞게 매핑 수정 필요
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  if (!res.success) {
+    console.error(res.error);
+    return undefined;
+  }
+  return res.data;
+};
+`;
+
+  // api/mapper/map-{entity}-detail.ts
+  const mapperDetailContent = `import { ${pascalName}DetailSchema } from "../../model/${kebabName}-detail";
+
+// TODO: API 응답 타입을 실제 타입으로 변경
+type ${pascalName}DetailResponse = {
+  id: number;
+  createDate: string;
+  updateDate: string;
+};
+
+export const map${pascalName}Detail = (item: ${pascalName}DetailResponse) => {
+  const res = ${pascalName}DetailSchema.safeParse({
+    id: item.id,
+    // TODO: 실제 API 응답 구조에 맞게 매핑 수정 필요
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  if (!res.success) {
+    console.error(res.error);
+    return undefined;
+  }
+  return res.data;
+};
+`;
+
+  // api/query/{entity}-list-query.ts
+  const queryContent = `export type ${pascalName}ListQuery = {
+  limit?: number;
+  offset?: number;
+  // TODO: 추가 필터링 옵션이 필요한 경우 여기에 추가
+};
+`;
+
+  // model/{entity}.ts
+  const modelContent = `import { z } from "zod";
+
+export const ${pascalName}Schema = z.object({
+  id: z.number(),
+  createDate: z.string(),
+  updateDate: z.string(),
+  // TODO: 실제 데이터 구조에 맞게 스키마 수정 필요
+});
+
+export type ${pascalName}Type = z.infer<typeof ${pascalName}Schema>;
+`;
+
+  //model/{entity}-detail.ts
+  const detailContent = `import { z } from "zod";
+
+export const ${pascalName}DetailSchema = z.object({
+  id: z.number(),
+  createDate: z.string(),
+  updateDate: z.string(),
+});
+
+export type ${pascalName}DetailType = z.infer<typeof ${pascalName}DetailSchema>;
+`;
+
+  // 파일 쓰기
+  fs.writeFileSync(path.join(basePath, "index.ts"), indexContent);
+  fs.writeFileSync(path.join(basePath, "api", "index.ts"), apiIndexContent);
+  fs.writeFileSync(
+    path.join(basePath, "api", `get-${kebabName}-list.ts`),
+    getListContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", `get-${kebabName}-detail.ts`),
+    getDetailContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", `${kebabName}-queries.ts`),
+    queriesContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "mapper", `map-${kebabName}.ts`),
+    mapperContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "mapper", `map-${kebabName}-detail.ts`),
+    mapperDetailContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "query", `${kebabName}-list-query.ts`),
+    queryContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "model", `${kebabName}.ts`),
+    modelContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "model", `${kebabName}-detail.ts`),
+    detailContent,
+  );
+}
+
+// CLI 실행
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log("@blastlabs/utils - FSD Entity Generator\n");
+  console.log("사용법: npx blastlabs-generate-entity <entity-name>\n");
+  console.log("⚠️  entities 폴더 내에서 실행해주세요!\n");
+  console.log("예시:");
+  console.log("  cd src/entities");
+  console.log("  npx blastlabs-generate-entity user");
+  console.log("  npx blastlabs-generate-entity my-new-entity");
+  console.log("  npx blastlabs-generate-entity MyNewEntity");
+  process.exit(1);
+}
+
+const entityName = args[0];
+const targetDir = process.cwd();
+
+createEntityStructure(entityName, targetDir);

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "blastlabs-generate-entity": "./bin/generate-entity.cjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "scripts": {
     "prepare": "npm run build:tsc",