@mandujs/core 0.11.0 → 0.12.0

package/src/content/loaders/file.ts

@@ -0,0 +1,169 @@
+/**
+ * File Loader - 단일 파일 로더
+ *
+ * JSON, YAML, TOML 파일을 로드하고 파싱
+ *
+ * @example
+ * ```ts
+ * file({ path: 'data/settings.json' })
+ * file({ path: 'config/app.yaml' })
+ * ```
+ */
+
+import type { Loader, FileLoaderOptions } from "./types";
+import type { LoaderContext } from "../types";
+import { LoaderError, ParseError } from "../types";
+import { generateFileDigest } from "../digest";
+import { inferParser } from "./types";
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * JSON 파싱
+ */
+function parseJson(content: string, filePath: string): unknown {
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new ParseError(
+      `Failed to parse JSON: ${error instanceof Error ? error.message : error}`,
+      undefined,
+      filePath
+    );
+  }
+}
+
+/**
+ * YAML 파싱 (동적 임포트)
+ */
+async function parseYaml(content: string, filePath: string): Promise<unknown> {
+  try {
+    // yaml 패키지 동적 로드
+    const yaml = await import("yaml").catch(() => null);
+
+    if (!yaml) {
+      throw new Error("yaml package not installed. Run: pnpm add yaml");
+    }
+
+    return yaml.parse(content);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not installed")) {
+      throw error;
+    }
+    throw new ParseError(
+      `Failed to parse YAML: ${error instanceof Error ? error.message : error}`,
+      undefined,
+      filePath
+    );
+  }
+}
+
+/**
+ * TOML 파싱 (동적 임포트)
+ */
+async function parseToml(content: string, filePath: string): Promise<unknown> {
+  try {
+    // @iarna/toml 또는 toml 패키지 동적 로드
+    const toml = await import("@iarna/toml").catch(() =>
+      import("toml").catch(() => null)
+    );
+
+    if (!toml) {
+      throw new Error("toml package not installed. Run: pnpm add @iarna/toml");
+    }
+
+    return toml.parse(content);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("not installed")) {
+      throw error;
+    }
+    throw new ParseError(
+      `Failed to parse TOML: ${error instanceof Error ? error.message : error}`,
+      undefined,
+      filePath
+    );
+  }
+}
+
+/**
+ * File Loader 팩토리
+ */
+export function file(options: FileLoaderOptions): Loader {
+  const { path: filePath, parser: explicitParser } = options;
+
+  return {
+    name: "file",
+
+    async load(context: LoaderContext): Promise<void> {
+      const { store, config, logger, parseData, generateDigest } = context;
+
+      // 절대 경로 계산
+      const absolutePath = path.isAbsolute(filePath)
+        ? filePath
+        : path.join(config.root, filePath);
+
+      // 파일 존재 확인
+      if (!fs.existsSync(absolutePath)) {
+        throw new LoaderError(
+          `File not found: ${absolutePath}`,
+          context.collection
+        );
+      }
+
+      // 파일 읽기
+      const content = fs.readFileSync(absolutePath, "utf-8");
+
+      // 다이제스트 생성
+      const digest = generateFileDigest(content);
+
+      // 기존 엔트리와 비교
+      const existingEntry = store.get("_single");
+      if (existingEntry?.digest === digest) {
+        logger.debug("File unchanged, skipping parse");
+        return;
+      }
+
+      // 파서 결정
+      const parserType = explicitParser ?? inferParser(absolutePath);
+
+      if (!parserType || parserType === "markdown") {
+        throw new LoaderError(
+          `Cannot determine parser for file: ${absolutePath}. Use .json, .yaml, .yml, or .toml extension, or specify parser option.`,
+          context.collection
+        );
+      }
+
+      // 파싱
+      let rawData: unknown;
+
+      switch (parserType) {
+        case "json":
+          rawData = parseJson(content, absolutePath);
+          break;
+        case "yaml":
+          rawData = await parseYaml(content, absolutePath);
+          break;
+        case "toml":
+          rawData = await parseToml(content, absolutePath);
+          break;
+      }
+
+      // 스키마 검증
+      const data = await parseData({
+        id: "_single",
+        data: rawData,
+        filePath: absolutePath,
+      });
+
+      // 저장
+      store.set({
+        id: "_single",
+        data: data as Record<string, unknown>,
+        filePath: absolutePath,
+        digest,
+      });
+
+      logger.info(`Loaded file: ${filePath}`);
+    },
+  };
+}

package/src/content/loaders/glob.ts

@@ -0,0 +1,252 @@
+/**
+ * Glob Loader - 패턴 매칭 파일 로더
+ *
+ * Glob 패턴으로 여러 파일을 로드 (Markdown, JSON 등)
+ *
+ * @example
+ * ```ts
+ * glob({ pattern: 'content/posts/**\/*.md' })
+ * glob({ pattern: ['content/blog/**\/*.md', 'content/news/**\/*.md'] })
+ * ```
+ */
+
+import type { Loader, GlobLoaderOptions, ParsedMarkdown } from "./types";
+import type { LoaderContext, DataEntry } from "../types";
+import { LoaderError, ParseError } from "../types";
+import { generateFileDigest, combineDigests } from "../digest";
+import { inferParser, MARKDOWN_EXTENSIONS } from "./types";
+import * as fs from "fs";
+import * as path from "path";
+
+// fast-glob 동적 임포트
+async function fastGlob(patterns: string[], options: { onlyFiles: boolean; absolute: boolean }): Promise<string[]> {
+  const fg = await import("fast-glob");
+  return fg.glob(patterns, options);
+}
+
+/**
+ * 프론트매터 파싱 (---로 구분된 YAML)
+ */
+async function parseFrontmatter(
+  content: string,
+  filePath: string
+): Promise<ParsedMarkdown> {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    // 프론트매터 없음
+    return {
+      data: {},
+      body: content.trim(),
+    };
+  }
+
+  const [, rawFrontmatter, body] = match;
+
+  try {
+    // yaml 동적 로드
+    const yaml = await import("yaml").catch(() => null);
+
+    if (!yaml) {
+      // yaml 없으면 빈 데이터 반환
+      console.warn(
+        `[GlobLoader] yaml package not installed, frontmatter ignored for ${filePath}`
+      );
+      return {
+        data: {},
+        body: body.trim(),
+        rawFrontmatter,
+      };
+    }
+
+    const data = yaml.parse(rawFrontmatter) || {};
+
+    return {
+      data: typeof data === "object" ? data : {},
+      body: body.trim(),
+      rawFrontmatter,
+    };
+  } catch (error) {
+    throw new ParseError(
+      `Failed to parse frontmatter: ${error instanceof Error ? error.message : error}`,
+      undefined,
+      filePath
+    );
+  }
+}
+
+/**
+ * 파일 경로에서 ID 생성 (기본)
+ */
+function defaultGenerateId(params: { filePath: string; base: string }): string {
+  const { filePath, base } = params;
+
+  // base 기준 상대 경로
+  const relativePath = path.relative(base, filePath);
+
+  // 확장자 제거, 경로 구분자를 슬래시로 통일
+  const withoutExt = relativePath.replace(/\.[^.]+$/, "");
+  const normalized = withoutExt.replace(/\\/g, "/");
+
+  // index 파일은 상위 폴더명 사용
+  if (normalized.endsWith("/index")) {
+    return normalized.slice(0, -6) || "index";
+  }
+
+  return normalized;
+}
+
+/**
+ * Glob Loader 팩토리
+ */
+export function glob(options: GlobLoaderOptions): Loader {
+  const { pattern, base, generateId = defaultGenerateId } = options;
+
+  return {
+    name: "glob",
+
+    async load(context: LoaderContext): Promise<void> {
+      const { store, config, logger, parseData, renderMarkdown, watcher } = context;
+
+      // 기본 디렉토리
+      const baseDir = base
+        ? path.isAbsolute(base)
+          ? base
+          : path.join(config.root, base)
+        : config.root;
+
+      // 패턴 배열로 통일
+      const patterns = Array.isArray(pattern) ? pattern : [pattern];
+
+      // 절대 패턴으로 변환
+      const absolutePatterns = patterns.map((p) =>
+        path.isAbsolute(p) ? p : path.join(config.root, p)
+      );
+
+      // 파일 검색
+      const filePaths = await fastGlob(absolutePatterns, {
+        onlyFiles: true,
+        absolute: true,
+      });
+
+      if (filePaths.length === 0) {
+        logger.warn(`No files matched pattern: ${patterns.join(", ")}`);
+        return;
+      }
+
+      // 파일 감시 추가 (dev 모드)
+      if (watcher) {
+        watcher.add(absolutePatterns);
+      }
+
+      // 기존 엔트리 ID 수집 (삭제 감지용)
+      const existingIds = new Set(store.keys());
+      const processedIds = new Set<string>();
+
+      // 병렬 처리
+      await Promise.all(
+        filePaths.map(async (filePath) => {
+          const id = generateId({ filePath, base: baseDir });
+          processedIds.add(id);
+
+          try {
+            await processFile(context, filePath, id, baseDir);
+          } catch (error) {
+            logger.error(
+              `Failed to process ${filePath}: ${error instanceof Error ? error.message : error}`
+            );
+          }
+        })
+      );
+
+      // 삭제된 파일 처리
+      for (const id of existingIds) {
+        if (!processedIds.has(id)) {
+          store.delete(id);
+          logger.debug(`Removed deleted entry: ${id}`);
+        }
+      }
+
+      logger.info(`Processed ${processedIds.size} files`);
+    },
+  };
+}
+
+/**
+ * 단일 파일 처리
+ */
+async function processFile(
+  context: LoaderContext,
+  filePath: string,
+  id: string,
+  baseDir: string
+): Promise<void> {
+  const { store, parseData, renderMarkdown, logger } = context;
+
+  // 파일 읽기
+  const content = fs.readFileSync(filePath, "utf-8");
+  const fileDigest = generateFileDigest(content);
+
+  // 기존 엔트리와 비교
+  const existingEntry = store.get(id);
+  if (existingEntry?.digest === fileDigest) {
+    logger.debug(`Unchanged: ${id}`);
+    return;
+  }
+
+  // 파서 타입 결정
+  const parserType = inferParser(filePath);
+
+  let entry: DataEntry;
+
+  if (parserType === "markdown") {
+    // Markdown 파일 처리
+    const parsed = await parseFrontmatter(content, filePath);
+
+    // 프론트매터 검증
+    const data = await parseData({
+      id,
+      data: parsed.data,
+      filePath,
+    });
+
+    // 다이제스트 (프론트매터 + 본문)
+    const digest = combineDigests([
+      fileDigest,
+      context.generateDigest(parsed.data),
+    ]);
+
+    entry = {
+      id,
+      data: data as Record<string, unknown>,
+      filePath,
+      body: parsed.body,
+      digest,
+    };
+
+    // Markdown 렌더링 (옵션)
+    if (renderMarkdown) {
+      entry.rendered = await renderMarkdown(parsed.body);
+    }
+  } else if (parserType === "json") {
+    // JSON 파일
+    const rawData = JSON.parse(content);
+    const data = await parseData({ id, data: rawData, filePath });
+
+    entry = {
+      id,
+      data: data as Record<string, unknown>,
+      filePath,
+      digest: fileDigest,
+    };
+  } else {
+    // 지원하지 않는 파일 타입
+    logger.warn(`Unsupported file type: ${filePath}`);
+    return;
+  }
+
+  // 저장
+  store.set(entry);
+  logger.debug(`Processed: ${id}`);
+}

package/src/content/loaders/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Content Loaders - 빌트인 로더 모음
+ *
+ * @example
+ * ```ts
+ * import { file, glob, api } from '@mandujs/core/content';
+ *
+ * export default defineContentConfig({
+ *   collections: {
+ *     settings: { loader: file({ path: 'data/settings.json' }) },
+ *     posts: { loader: glob({ pattern: 'content/posts/**\/*.md' }) },
+ *     products: { loader: api({ url: 'https://api.example.com/products' }) },
+ *   },
+ * });
+ * ```
+ */
+
+export { file } from "./file";
+export { glob } from "./glob";
+export { api } from "./api";
+
+// 타입 재export
+export type {
+  Loader,
+  FileLoaderOptions,
+  GlobLoaderOptions,
+  ApiLoaderOptions,
+  PaginationConfig,
+  ParsedMarkdown,
+  LoaderEntry,
+  LoaderFactory,
+} from "./types";
+
+export { inferParser, FILE_PARSERS, MARKDOWN_EXTENSIONS } from "./types";

package/src/content/loaders/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Loader Types - 로더 공통 인터페이스
+ *
+ * 모든 로더가 구현해야 하는 인터페이스와 유틸리티 타입
+ */
+
+import type { ZodSchema } from "zod";
+import type { LoaderContext, DataEntry, RenderedContent } from "../types";
+
+/**
+ * 로더 인터페이스
+ */
+export interface Loader {
+  /** 로더 이름 (디버깅용) */
+  name: string;
+  /** 콘텐츠 로드 함수 */
+  load: (context: LoaderContext) => Promise<void>;
+  /** 기본 스키마 (컬렉션 설정보다 우선순위 낮음) */
+  schema?: ZodSchema | (() => ZodSchema | Promise<ZodSchema>);
+}
+
+/**
+ * File Loader 옵션
+ */
+export interface FileLoaderOptions {
+  /** 파일 경로 (프로젝트 루트 기준) */
+  path: string;
+  /** 파서 타입 (자동 감지됨) */
+  parser?: "json" | "yaml" | "toml";
+}
+
+/**
+ * Glob Loader 옵션
+ */
+export interface GlobLoaderOptions {
+  /** Glob 패턴 */
+  pattern: string | string[];
+  /** 기본 디렉토리 */
+  base?: string;
+  /** ID 생성 함수 */
+  generateId?: (params: { filePath: string; base: string }) => string;
+}
+
+/**
+ * API Loader 옵션
+ */
+export interface ApiLoaderOptions {
+  /** API URL */
+  url: string | (() => string | Promise<string>);
+  /** HTTP 메서드 */
+  method?: "GET" | "POST";
+  /** 요청 헤더 */
+  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+  /** 요청 바디 (POST) */
+  body?: unknown | (() => unknown | Promise<unknown>);
+  /** 응답 변환 */
+  transform?: (response: unknown) => unknown[] | Promise<unknown[]>;
+  /** 캐시 TTL (초) */
+  cacheTTL?: number;
+  /** 페이지네이션 설정 */
+  pagination?: PaginationConfig;
+}
+
+/**
+ * 페이지네이션 설정
+ */
+export interface PaginationConfig {
+  /** 다음 페이지 URL 추출 */
+  getNextUrl?: (response: unknown, currentUrl: string) => string | null;
+  /** 총 페이지 수 추출 */
+  getTotalPages?: (response: unknown) => number;
+  /** 페이지 크기 */
+  pageSize?: number;
+}
+
+/**
+ * Markdown 프론트매터 파싱 결과
+ */
+export interface ParsedMarkdown {
+  /** 프론트매터 데이터 */
+  data: Record<string, unknown>;
+  /** Markdown 본문 */
+  body: string;
+  /** 원본 프론트매터 문자열 */
+  rawFrontmatter?: string;
+}
+
+/**
+ * 로더 결과 엔트리 (store.set 전)
+ */
+export interface LoaderEntry<T = Record<string, unknown>> {
+  /** 고유 ID */
+  id: string;
+  /** 데이터 */
+  data: T;
+  /** 파일 경로 (파일 기반) */
+  filePath?: string;
+  /** 본문 (Markdown 등) */
+  body?: string;
+  /** 다이제스트 */
+  digest?: string;
+  /** 렌더링된 콘텐츠 */
+  rendered?: RenderedContent;
+}
+
+/**
+ * 로더 팩토리 함수 타입
+ */
+export type LoaderFactory<TOptions> = (options: TOptions) => Loader;
+
+/**
+ * 지원 파일 확장자별 파서
+ */
+export const FILE_PARSERS = {
+  ".json": "json",
+  ".yaml": "yaml",
+  ".yml": "yaml",
+  ".toml": "toml",
+} as const;
+
+/**
+ * Markdown 파일 확장자
+ */
+export const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx", ".markdown"]);
+
+/**
+ * 파일 확장자로 파서 타입 추론
+ */
+export function inferParser(filePath: string): "json" | "yaml" | "toml" | "markdown" | null {
+  const ext = filePath.toLowerCase().slice(filePath.lastIndexOf("."));
+
+  if (MARKDOWN_EXTENSIONS.has(ext)) {
+    return "markdown";
+  }
+
+  return FILE_PARSERS[ext as keyof typeof FILE_PARSERS] ?? null;
+}