@mandujs/core 0.11.0 → 0.12.0

package/src/content/meta-store.ts

@@ -0,0 +1,209 @@
+/**
+ * MetaStore - 동기화 메타데이터 저장소
+ *
+ * API 동기화 토큰, 마지막 수정 시간, 커서 등
+ * 로더가 증분 업데이트를 수행하는 데 필요한 메타데이터 저장
+ */
+
+import type { MetaStore } from "./types";
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * MetaStore 옵션
+ */
+export interface MetaStoreOptions {
+  /** 영속화 파일 경로 */
+  filePath?: string;
+  /** 자동 저장 활성화 */
+  autoSave?: boolean;
+}
+
+/**
+ * 직렬화된 메타 스토어 형식
+ */
+interface SerializedMetaStore {
+  version: number;
+  collections: Record<string, Record<string, string>>;
+  timestamp: string;
+}
+
+const META_VERSION = 1;
+
+/**
+ * 콘텐츠 메타 저장소 구현
+ */
+export class ContentMetaStore {
+  private collections: Map<string, Map<string, string>> = new Map();
+  private options: MetaStoreOptions;
+  private dirty: boolean = false;
+
+  constructor(options: MetaStoreOptions = {}) {
+    this.options = {
+      autoSave: true,
+      ...options,
+    };
+  }
+
+  /**
+   * 컬렉션용 MetaStore 인터페이스 생성
+   */
+  getStore(collection: string): MetaStore {
+    if (!this.collections.has(collection)) {
+      this.collections.set(collection, new Map());
+    }
+
+    const store = this.collections.get(collection)!;
+
+    return {
+      get: (key: string) => store.get(key),
+
+      set: (key: string, value: string) => {
+        store.set(key, value);
+        this.dirty = true;
+        this.autoSave();
+      },
+
+      has: (key: string) => store.has(key),
+
+      delete: (key: string) => {
+        if (store.has(key)) {
+          store.delete(key);
+          this.dirty = true;
+          this.autoSave();
+        }
+      },
+
+      clear: () => {
+        if (store.size > 0) {
+          store.clear();
+          this.dirty = true;
+          this.autoSave();
+        }
+      },
+
+      entries: () => Array.from(store.entries()),
+    };
+  }
+
+  /**
+   * 컬렉션 삭제
+   */
+  deleteCollection(collection: string): void {
+    if (this.collections.has(collection)) {
+      this.collections.delete(collection);
+      this.dirty = true;
+      this.autoSave();
+    }
+  }
+
+  /**
+   * 자동 저장
+   */
+  private autoSave(): void {
+    if (this.options.autoSave && this.options.filePath) {
+      this.save();
+    }
+  }
+
+  /**
+   * 파일에서 로드
+   */
+  async load(): Promise<void> {
+    if (!this.options.filePath) return;
+
+    try {
+      if (!fs.existsSync(this.options.filePath)) {
+        return;
+      }
+
+      const content = fs.readFileSync(this.options.filePath, "utf-8");
+      const data: SerializedMetaStore = JSON.parse(content);
+
+      if (data.version !== META_VERSION) {
+        console.warn(
+          `[MetaStore] Version mismatch (${data.version} vs ${META_VERSION}), starting fresh`
+        );
+        return;
+      }
+
+      for (const [collection, entries] of Object.entries(data.collections)) {
+        const store = new Map<string, string>();
+        for (const [key, value] of Object.entries(entries)) {
+          store.set(key, value);
+        }
+        this.collections.set(collection, store);
+      }
+
+      this.dirty = false;
+    } catch (error) {
+      console.warn(
+        `[MetaStore] Failed to load:`,
+        error instanceof Error ? error.message : error
+      );
+    }
+  }
+
+  /**
+   * 파일에 저장
+   */
+  async save(): Promise<void> {
+    if (!this.options.filePath || !this.dirty) return;
+
+    try {
+      const dir = path.dirname(this.options.filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      const data: SerializedMetaStore = {
+        version: META_VERSION,
+        collections: {},
+        timestamp: new Date().toISOString(),
+      };
+
+      for (const [collection, store] of this.collections) {
+        data.collections[collection] = Object.fromEntries(store);
+      }
+
+      fs.writeFileSync(this.options.filePath, JSON.stringify(data, null, 2));
+      this.dirty = false;
+    } catch (error) {
+      console.error(
+        `[MetaStore] Failed to save:`,
+        error instanceof Error ? error.message : error
+      );
+    }
+  }
+
+  /**
+   * 전체 스토어 초기화
+   */
+  clear(): void {
+    this.collections.clear();
+    this.dirty = true;
+    this.autoSave();
+  }
+
+  /**
+   * 스토어 통계
+   */
+  getStats(): { collections: number; totalKeys: number } {
+    let totalKeys = 0;
+    for (const store of this.collections.values()) {
+      totalKeys += store.size;
+    }
+
+    return {
+      collections: this.collections.size,
+      totalKeys,
+    };
+  }
+}
+
+/**
+ * MetaStore 팩토리
+ */
+export function createMetaStore(options?: MetaStoreOptions): ContentMetaStore {
+  return new ContentMetaStore(options);
+}

package/src/content/types.ts

@@ -0,0 +1,282 @@
+/**
+ * Content Layer Type Definitions
+ *
+ * Astro Content Layer에서 영감받은 빌드 타임 콘텐츠 로딩 시스템
+ * 다양한 소스(파일, API, DB)에서 콘텐츠를 로드하고 Zod 스키마로 검증
+ */
+
+import type { z, ZodSchema } from "zod";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * 렌더링된 콘텐츠 (Markdown → HTML)
+ */
+export interface RenderedContent {
+  /** 렌더링된 HTML */
+  html: string;
+  /** 추출된 헤딩 목록 */
+  headings?: ContentHeading[];
+  /** 렌더링 메타데이터 */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 콘텐츠 헤딩 정보
+ */
+export interface ContentHeading {
+  depth: 1 | 2 | 3 | 4 | 5 | 6;
+  slug: string;
+  text: string;
+}
+
+/**
+ * 데이터 엔트리 - DataStore에 저장되는 단위
+ */
+export interface DataEntry<T = Record<string, unknown>> {
+  /** 고유 식별자 */
+  id: string;
+  /** 검증된 데이터 */
+  data: T;
+  /** 원본 파일 경로 (파일 기반 로더) */
+  filePath?: string;
+  /** 본문 콘텐츠 (Markdown 등) */
+  body?: string;
+  /** 변경 감지용 다이제스트 */
+  digest?: string;
+  /** 렌더링된 콘텐츠 */
+  rendered?: RenderedContent;
+}
+
+/**
+ * 컬렉션 정의
+ */
+export interface CollectionConfig<T = unknown> {
+  /** 콘텐츠 로더 */
+  loader: Loader;
+  /** Zod 스키마 (검증용) */
+  schema?: ZodSchema<T>;
+}
+
+/**
+ * Content 설정 파일 타입 (content.config.ts)
+ */
+export interface ContentConfig {
+  collections: Record<string, CollectionConfig>;
+}
+
+// ============================================================================
+// Loader Types
+// ============================================================================
+
+/**
+ * 로더 인터페이스 - 콘텐츠 소스 정의
+ */
+export interface Loader {
+  /** 로더 이름 */
+  name: string;
+  /** 콘텐츠 로드 함수 */
+  load: (context: LoaderContext) => Promise<void>;
+  /** 스키마 (로더 내부 기본값) */
+  schema?: ZodSchema | (() => ZodSchema | Promise<ZodSchema>);
+}
+
+/**
+ * 로더 컨텍스트 - load() 함수에 전달
+ */
+export interface LoaderContext {
+  /** 컬렉션 이름 */
+  collection: string;
+  /** 데이터 저장소 */
+  store: DataStore;
+  /** 메타 저장소 (동기화 토큰 등) */
+  meta: MetaStore;
+  /** 로거 */
+  logger: ContentLogger;
+  /** Mandu 설정 */
+  config: ManduContentConfig;
+  /** 데이터 파싱 및 검증 */
+  parseData: <T>(options: ParseDataOptions<T>) => Promise<T>;
+  /** 다이제스트 생성 */
+  generateDigest: (data: unknown) => string;
+  /** Markdown 렌더링 (선택) */
+  renderMarkdown?: (content: string) => Promise<RenderedContent>;
+  /** 파일 감시자 (dev 모드) */
+  watcher?: ContentWatcher;
+}
+
+/**
+ * parseData 옵션
+ */
+export interface ParseDataOptions<T> {
+  /** 엔트리 ID */
+  id: string;
+  /** 원본 데이터 */
+  data: unknown;
+  /** 파일 경로 (있으면) */
+  filePath?: string;
+}
+
+// ============================================================================
+// Store Interfaces
+// ============================================================================
+
+/**
+ * 데이터 저장소 인터페이스
+ */
+export interface DataStore {
+  /** 엔트리 조회 */
+  get<T = Record<string, unknown>>(id: string): DataEntry<T> | undefined;
+  /** 엔트리 저장 (변경 시 true 반환) */
+  set<T = Record<string, unknown>>(entry: DataEntry<T>): boolean;
+  /** 엔트리 삭제 */
+  delete(id: string): void;
+  /** 전체 삭제 */
+  clear(): void;
+  /** 모든 엔트리 조회 */
+  entries<T = Record<string, unknown>>(): Array<[string, DataEntry<T>]>;
+  /** 엔트리 존재 여부 */
+  has(id: string): boolean;
+  /** 엔트리 개수 */
+  size(): number;
+  /** ID 목록 */
+  keys(): string[];
+  /** 값 목록 */
+  values<T = Record<string, unknown>>(): Array<DataEntry<T>>;
+}
+
+/**
+ * 메타 저장소 인터페이스 (동기화 토큰, 커서 등)
+ */
+export interface MetaStore {
+  /** 메타 값 조회 */
+  get(key: string): string | undefined;
+  /** 메타 값 저장 */
+  set(key: string, value: string): void;
+  /** 메타 값 존재 여부 */
+  has(key: string): boolean;
+  /** 메타 값 삭제 */
+  delete(key: string): void;
+  /** 전체 삭제 */
+  clear(): void;
+  /** 모든 엔트리 */
+  entries(): Array<[string, string]>;
+}
+
+// ============================================================================
+// Logger & Watcher
+// ============================================================================
+
+/**
+ * 콘텐츠 로거
+ */
+export interface ContentLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  debug(message: string): void;
+}
+
+/**
+ * 콘텐츠 파일 감시자 (dev 모드)
+ */
+export interface ContentWatcher {
+  /** 파일 감시 추가 */
+  add(paths: string | string[]): void;
+  /** 파일 감시 제거 */
+  remove(paths: string | string[]): void;
+  /** 변경 이벤트 핸들러 */
+  on(event: "change" | "add" | "unlink", handler: (path: string) => void): void;
+  /** 감시 중지 */
+  close(): Promise<void>;
+}
+
+// ============================================================================
+// Config Types
+// ============================================================================
+
+/**
+ * Mandu Content 설정
+ */
+export interface ManduContentConfig {
+  /** 프로젝트 루트 */
+  root: string;
+  /** 콘텐츠 디렉토리 */
+  contentDir?: string;
+  /** 출력 디렉토리 */
+  outDir?: string;
+  /** 개발 모드 */
+  isDev?: boolean;
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * 콘텐츠 에러 기본 클래스
+ */
+export class ContentError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public collection?: string,
+    public entryId?: string
+  ) {
+    super(message);
+    this.name = "ContentError";
+  }
+}
+
+/**
+ * 로더 에러
+ */
+export class LoaderError extends ContentError {
+  constructor(message: string, collection?: string) {
+    super(message, "LOADER_ERROR", collection);
+    this.name = "LoaderError";
+  }
+}
+
+/**
+ * 파싱 에러
+ */
+export class ParseError extends ContentError {
+  constructor(message: string, collection?: string, entryId?: string) {
+    super(message, "PARSE_ERROR", collection, entryId);
+    this.name = "ParseError";
+  }
+}
+
+/**
+ * 검증 에러
+ */
+export class ValidationError extends ContentError {
+  constructor(
+    message: string,
+    public zodError: z.ZodError,
+    collection?: string,
+    entryId?: string
+  ) {
+    super(message, "VALIDATION_ERROR", collection, entryId);
+    this.name = "ValidationError";
+  }
+}
+
+// ============================================================================
+// Helper Types
+// ============================================================================
+
+/**
+ * 컬렉션의 데이터 타입 추론
+ */
+export type InferEntryData<T extends CollectionConfig> = T["schema"] extends ZodSchema<infer U>
+  ? U
+  : Record<string, unknown>;
+
+/**
+ * 컬렉션 엔트리 타입 (schema 포함)
+ */
+export type CollectionEntry<T extends CollectionConfig> = DataEntry<InferEntryData<T>>;

package/src/content/watcher.ts

@@ -0,0 +1,135 @@
+/**
+ * Content Watcher - 개발 모드 파일 감시
+ *
+ * 콘텐츠 파일 변경 시 자동 리로드
+ */
+
+import type { ContentWatcher } from "./types";
+import chokidar, { type FSWatcher } from "chokidar";
+
+/**
+ * ContentWatcher 옵션
+ */
+export interface ContentWatcherOptions {
+  /** 루트 디렉토리 */
+  root: string;
+  /** 무시할 패턴 */
+  ignored?: string[];
+  /** 디바운스 (ms) */
+  debounce?: number;
+}
+
+/**
+ * ContentWatcher 구현
+ */
+class ContentWatcherImpl implements ContentWatcher {
+  private watcher: FSWatcher;
+  private handlers: Map<string, Set<(path: string) => void>> = new Map();
+  private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
+  private debounceMs: number;
+
+  constructor(options: ContentWatcherOptions) {
+    const { root, ignored = ["**/node_modules/**", "**/.git/**"], debounce = 300 } = options;
+
+    this.debounceMs = debounce;
+
+    this.watcher = chokidar.watch([], {
+      cwd: root,
+      ignored,
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: debounce,
+        pollInterval: 100,
+      },
+    });
+
+    // 이벤트 핸들러 연결
+    this.watcher.on("change", (path) => this.emit("change", path));
+    this.watcher.on("add", (path) => this.emit("add", path));
+    this.watcher.on("unlink", (path) => this.emit("unlink", path));
+  }
+
+  /**
+   * 파일/패턴 감시 추가
+   */
+  add(paths: string | string[]): void {
+    this.watcher.add(paths);
+  }
+
+  /**
+   * 파일/패턴 감시 제거
+   */
+  remove(paths: string | string[]): void {
+    this.watcher.unwatch(paths);
+  }
+
+  /**
+   * 이벤트 핸들러 등록
+   */
+  on(event: "change" | "add" | "unlink", handler: (path: string) => void): void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+  }
+
+  /**
+   * 이벤트 핸들러 제거
+   */
+  off(event: "change" | "add" | "unlink", handler: (path: string) => void): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+
+  /**
+   * 감시 종료
+   */
+  async close(): Promise<void> {
+    // 모든 디바운스 타이머 정리
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+
+    await this.watcher.close();
+  }
+
+  /**
+   * 이벤트 발생 (디바운스 적용)
+   */
+  private emit(event: "change" | "add" | "unlink", path: string): void {
+    const key = `${event}:${path}`;
+
+    // 기존 타이머 취소
+    if (this.debounceTimers.has(key)) {
+      clearTimeout(this.debounceTimers.get(key)!);
+    }
+
+    // 디바운스 적용
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(key);
+
+      const handlers = this.handlers.get(event);
+      if (handlers) {
+        for (const handler of handlers) {
+          try {
+            handler(path);
+          } catch (error) {
+            console.error(
+              `[ContentWatcher] Handler error for ${event}:`,
+              error instanceof Error ? error.message : error
+            );
+          }
+        }
+      }
+    }, this.debounceMs);
+
+    this.debounceTimers.set(key, timer);
+  }
+}
+
+/**
+ * ContentWatcher 팩토리
+ */
+export function createContentWatcher(options: ContentWatcherOptions): ContentWatcher {
+  return new ContentWatcherImpl(options);
+}