@mandujs/core 0.17.0 → 0.18.0

package/src/resource/parser.ts

@@ -0,0 +1,139 @@
+/**
+ * Resource Schema Parser
+ * Parse and validate resource schema files
+ */
+
+import type { ResourceDefinition } from "./schema";
+import { validateResourceDefinition } from "./schema";
+import path from "path";
+
+// ============================================
+// Parser Result
+// ============================================
+
+export interface ParsedResource {
+  /** 원본 정의 */
+  definition: ResourceDefinition;
+  /** 파일 경로 */
+  filePath: string;
+  /** 파일명 (확장자 제외) */
+  fileName: string;
+  /** 리소스 이름 */
+  resourceName: string;
+}
+
+// ============================================
+// Parse Resource Schema
+// ============================================
+
+/**
+ * Parse resource schema from file
+ *
+ * @param filePath - Absolute path to resource schema file
+ * @returns Parsed resource with metadata
+ *
+ * @example
+ * ```typescript
+ * const parsed = await parseResourceSchema("/path/to/spec/resources/user.resource.ts");
+ * console.log(parsed.resourceName); // "user"
+ * console.log(parsed.definition.fields); // { id: {...}, email: {...}, ... }
+ * ```
+ */
+export async function parseResourceSchema(filePath: string): Promise<ParsedResource> {
+  // Validate file path
+  if (!filePath.endsWith(".resource.ts")) {
+    throw new Error(
+      `Invalid resource schema file: "${filePath}". Must end with ".resource.ts"`
+    );
+  }
+
+  // Extract file name
+  const fileName = path.basename(filePath, ".resource.ts");
+
+  // Import the resource definition
+  let definition: ResourceDefinition;
+  try {
+    const module = await import(filePath);
+    definition = module.default;
+
+    if (!definition) {
+      throw new Error(
+        `Resource schema file "${filePath}" must export a default ResourceDefinition`
+      );
+    }
+  } catch (error) {
+    throw new Error(
+      `Failed to import resource schema "${filePath}": ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+
+  // Validate definition
+  try {
+    validateResourceDefinition(definition);
+  } catch (error) {
+    throw new Error(
+      `Invalid resource schema in "${filePath}": ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+
+  return {
+    definition,
+    filePath,
+    fileName,
+    resourceName: definition.name,
+  };
+}
+
+/**
+ * Parse multiple resource schemas
+ *
+ * @param filePaths - Array of absolute paths to resource schema files
+ * @returns Array of parsed resources
+ */
+export async function parseResourceSchemas(filePaths: string[]): Promise<ParsedResource[]> {
+  const results = await Promise.allSettled(filePaths.map(parseResourceSchema));
+
+  const errors: string[] = [];
+  const parsed: ParsedResource[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    if (result.status === "fulfilled") {
+      parsed.push(result.value);
+    } else {
+      errors.push(`${filePaths[i]}: ${result.reason}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Failed to parse resource schemas:\n${errors.join("\n")}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Validate resource name uniqueness
+ */
+export function validateResourceUniqueness(resources: ParsedResource[]): void {
+  const names = new Set<string>();
+  const duplicates: string[] = [];
+
+  for (const resource of resources) {
+    const name = resource.resourceName;
+    if (names.has(name)) {
+      duplicates.push(name);
+    }
+    names.add(name);
+  }
+
+  if (duplicates.length > 0) {
+    throw new Error(
+      `Duplicate resource names found: ${duplicates.join(", ")}. Resource names must be unique.`
+    );
+  }
+}

package/src/resource/schema.ts

@@ -0,0 +1,252 @@
+/**
+ * Resource Schema Definition
+ * Resource-Centric Architecture의 핵심 스키마 정의
+ */
+
+import { z } from "zod";
+
+// ============================================
+// Field Types
+// ============================================
+
+export const FieldTypes = [
+  "string",
+  "number",
+  "boolean",
+  "date",
+  "uuid",
+  "email",
+  "url",
+  "json",
+  "array",
+  "object",
+] as const;
+
+export type FieldType = (typeof FieldTypes)[number];
+
+// ============================================
+// Field Definition
+// ============================================
+
+export interface ResourceField {
+  /** 필드 타입 */
+  type: FieldType;
+  /** 필수 여부 */
+  required?: boolean;
+  /** 기본값 */
+  default?: unknown;
+  /** 설명 */
+  description?: string;
+  /** 배열 타입인 경우 요소 타입 */
+  items?: FieldType;
+  /** 커스텀 Zod 스키마 (고급 사용) */
+  schema?: z.ZodType<any>;
+}
+
+// ============================================
+// Resource Options
+// ============================================
+
+export interface ResourceOptions {
+  /** 리소스 설명 */
+  description?: string;
+  /** API 태그 */
+  tags?: string[];
+  /** 자동 복수형 사용 여부 (기본: true) */
+  autoPlural?: boolean;
+  /** 커스텀 복수형 이름 */
+  pluralName?: string;
+  /** 활성화할 엔드포인트 */
+  endpoints?: {
+    list?: boolean;
+    get?: boolean;
+    create?: boolean;
+    update?: boolean;
+    delete?: boolean;
+  };
+  /** 인증 필요 여부 */
+  auth?: boolean;
+  /** 페이지네이션 설정 */
+  pagination?: {
+    defaultLimit?: number;
+    maxLimit?: number;
+  };
+}
+
+// ============================================
+// Resource Definition
+// ============================================
+
+export interface ResourceDefinition {
+  /** 리소스 이름 (단수형) */
+  name: string;
+  /** 필드 정의 */
+  fields: Record<string, ResourceField>;
+  /** 옵션 */
+  options?: ResourceOptions;
+}
+
+// ============================================
+// defineResource API
+// ============================================
+
+/**
+ * Define a resource with fields and options
+ *
+ * @example
+ * ```typescript
+ * const UserResource = defineResource({
+ *   name: "user",
+ *   fields: {
+ *     id: { type: "uuid", required: true },
+ *     email: { type: "email", required: true },
+ *     name: { type: "string", required: true },
+ *     createdAt: { type: "date", required: true },
+ *   },
+ *   options: {
+ *     description: "User management API",
+ *     tags: ["users"],
+ *     endpoints: {
+ *       list: true,
+ *       get: true,
+ *       create: true,
+ *       update: true,
+ *       delete: true,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineResource(definition: ResourceDefinition): ResourceDefinition {
+  // Validation
+  validateResourceDefinition(definition);
+
+  // Default options
+  const options: ResourceOptions = {
+    autoPlural: true,
+    endpoints: {
+      list: true,
+      get: true,
+      create: true,
+      update: true,
+      delete: true,
+    },
+    pagination: {
+      defaultLimit: 10,
+      maxLimit: 100,
+    },
+    ...definition.options,
+  };
+
+  return {
+    ...definition,
+    options,
+  };
+}
+
+// ============================================
+// Validation
+// ============================================
+
+/**
+ * Validate resource definition
+ */
+export function validateResourceDefinition(definition: ResourceDefinition): void {
+  // Name validation
+  if (!definition.name) {
+    throw new Error("Resource name is required");
+  }
+
+  if (!/^[a-z][a-z0-9_]*$/i.test(definition.name)) {
+    throw new Error(
+      `Invalid resource name: "${definition.name}". Must start with a letter and contain only letters, numbers, and underscores.`
+    );
+  }
+
+  // Fields validation
+  if (!definition.fields || Object.keys(definition.fields).length === 0) {
+    throw new Error(`Resource "${definition.name}" must have at least one field`);
+  }
+
+  for (const [fieldName, field] of Object.entries(definition.fields)) {
+    validateField(definition.name, fieldName, field);
+  }
+}
+
+/**
+ * Validate individual field
+ */
+function validateField(resourceName: string, fieldName: string, field: ResourceField): void {
+  // Field name validation
+  if (!/^[a-z][a-z0-9_]*$/i.test(fieldName)) {
+    throw new Error(
+      `Invalid field name: "${fieldName}" in resource "${resourceName}". Must start with a letter and contain only letters, numbers, and underscores.`
+    );
+  }
+
+  // Type validation
+  if (!FieldTypes.includes(field.type)) {
+    throw new Error(
+      `Invalid field type: "${field.type}" for field "${fieldName}" in resource "${resourceName}". Must be one of: ${FieldTypes.join(", ")}`
+    );
+  }
+
+  // Array type requires items
+  if (field.type === "array" && !field.items && !field.schema) {
+    throw new Error(
+      `Field "${fieldName}" in resource "${resourceName}" is array type but missing "items" property`
+    );
+  }
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+/**
+ * Get plural name for resource
+ */
+export function getPluralName(definition: ResourceDefinition): string {
+  if (definition.options?.pluralName) {
+    return definition.options.pluralName;
+  }
+
+  if (definition.options?.autoPlural === false) {
+    return definition.name;
+  }
+
+  // Simple pluralization: add 's'
+  // TODO: Add more sophisticated pluralization rules if needed
+  return `${definition.name}s`;
+}
+
+/**
+ * Get enabled endpoints
+ */
+export function getEnabledEndpoints(definition: ResourceDefinition): string[] {
+  const endpoints = definition.options?.endpoints ?? {
+    list: true,
+    get: true,
+    create: true,
+    update: true,
+    delete: true,
+  };
+
+  return Object.entries(endpoints)
+    .filter(([_, enabled]) => enabled)
+    .map(([name]) => name);
+}
+
+/**
+ * Check if field is required
+ */
+export function isFieldRequired(field: ResourceField): boolean {
+  return field.required ?? false;
+}
+
+/**
+ * Get field default value
+ */
+export function getFieldDefault(field: ResourceField): unknown | undefined {
+  return field.default;
+}