@interactive-inc/docs-client 1.1.1 → 2.0.0

package/README.md

@@ -0,0 +1,448 @@
+# @interactive-inc/docs-client
+
+Markdown ベースのドキュメントを型安全に管理する TypeScript ライブラリ。
+
+## Features
+
+- Markdown ファイルの読み書きと FrontMatter メタデータ管理
+- Zod スキーマによる型安全なバリデーション
+- ドキュメント間のリレーション
+- 複数ストレージバックエンド（Node.js, GitHub, JSON, Mock）
+- アーカイブ/リストア
+- ファイルツリー生成
+- `.safe` プロキシによるエラーハンドリング
+
+## Installation
+
+```bash
+vp add @interactive-inc/docs-client
+```
+
+## Development
+
+```bash
+vp install
+vp lint
+vp fmt
+vp test
+vp run check
+vp run build
+```
+
+## Quick Start
+
+```typescript
+import { DocClient } from "@interactive-inc/docs-client"
+import { DocFileSystemNode } from "@interactive-inc/docs-client/file-system-node"
+
+const fileSystem = new DocFileSystemNode({ basePath: "./docs" })
+const client = new DocClient({ fileSystem })
+
+// .safe を使うと throw の代わりに Error を返す
+const entity = await client.safe.mdFile("articles/hello.md").read()
+
+if (!(entity instanceof Error)) {
+  console.log(entity.content().title)
+  console.log(entity.content().body)
+}
+
+// try/catch でも使える
+try {
+  const entity = await client.mdFile("articles/hello.md").read()
+  console.log(entity.content().title)
+} catch (error) {
+  console.error(error)
+}
+```
+
+## Core Concepts
+
+### DocClient
+
+メインのエントリポイント。
+
+```typescript
+const client = new DocClient({
+  fileSystem,
+  config: {
+    defaultIndexIcon: "📃",
+    indexFileName: "index.md",
+    archiveDirectoryName: "_",
+    defaultDirectoryName: "Directory",
+    indexMetaIncludes: [],
+    directoryExcludes: [".vitepress"],
+    metaFileName: ".meta.json",
+  },
+})
+```
+
+### References
+
+ファイルやディレクトリへの遅延参照。`read()` を呼ぶまで I/O は発生しない。
+
+```typescript
+const fileRef = client.mdFile("articles/hello.md")
+
+const dirRef = client.directory("articles")
+
+const indexRef = client.indexFile("articles")
+```
+
+### Entities
+
+読み取り後の不変データオブジェクト。
+
+```typescript
+const entity = await fileRef.read()
+
+const title = entity.content().title
+const body = entity.content().body
+const description = entity.content().description
+
+const meta = entity.content().meta()
+
+// with*() で新しいインスタンスを作成（不変）
+const updated = entity.withTitle("New Title")
+```
+
+### Error Handling - `.safe` プロキシ
+
+Reference や DocClient のメソッドは通常 throw でエラーを伝播する。`.safe` プロキシを使うと、全 async メソッドが `T | Error` を返す。
+
+```typescript
+// throw する（try/catch が必要）
+const entity = await fileRef.read()
+
+// Error を返す（instanceof チェック）
+const entity = await fileRef.safe.read()
+
+if (entity instanceof Error) {
+  console.error(entity.message)
+  return
+}
+
+console.log(entity.content().title)
+```
+
+## File Operations
+
+### Reading Files
+
+```typescript
+const fileRef = client.mdFile("articles/hello.md")
+const entity = await fileRef.read()
+
+// ディレクトリ内の全ファイルを読み取り
+const dirRef = client.directory("articles")
+const entities = await dirRef.readMdFiles()
+
+// 生テキストとして読み取り
+const text = await fileRef.readText()
+```
+
+### Writing Files
+
+```typescript
+const entity = fileRef.empty()
+const updated = entity.withTitle("Hello World").withDescription("My first article")
+await fileRef.write(updated)
+
+// 生テキストで書き込み
+await fileRef.writeText("# Hello\n\nContent here")
+
+// デフォルトコンテンツで新規ファイル作成
+await dirRef.createMdFile("new-article.md")
+```
+
+### Archive and Restore
+
+ファイルをアーカイブディレクトリ（デフォルト: `_/`）に移動。
+
+```typescript
+const archivedRef = await fileRef.archive()
+
+const restoredRef = await archivedRef.restore()
+```
+
+### File Information
+
+```typescript
+const exists = await fileRef.exists()
+const size = await fileRef.size()
+const lastModified = await fileRef.lastModified()
+const createdAt = await fileRef.createdAt()
+```
+
+## Schema Definition
+
+FrontMatter メタデータの構造をスキーマで定義する。
+
+### Using .meta.json (Recommended)
+
+ディレクトリに `.meta.json` を配置:
+
+```json
+{
+  "icon": "📄",
+  "schema": {
+    "title": {
+      "type": "text",
+      "required": true,
+      "title": "Title",
+      "description": "Document title",
+      "default": null
+    },
+    "category": {
+      "type": "select-text",
+      "required": false,
+      "title": "Category",
+      "description": null,
+      "options": ["tutorial", "reference", "guide"],
+      "default": null
+    },
+    "tags": {
+      "type": "multi-text",
+      "required": false,
+      "title": "Tags",
+      "description": null,
+      "default": []
+    },
+    "author": {
+      "type": "relation",
+      "required": false,
+      "title": "Author",
+      "description": null,
+      "path": "authors",
+      "default": null
+    }
+  }
+}
+```
+
+### Using index.md FrontMatter (Fallback)
+
+`.meta.json` がなければ `index.md` の FrontMatter からスキーマを読み取る:
+
+```markdown
+---
+icon: 📄
+schema:
+  title:
+    type: text
+    required: true
+  category:
+    type: select-text
+    options:
+      - tutorial
+      - reference
+---
+
+# Articles
+
+Directory description here.
+```
+
+### Type-Safe Schema in Code
+
+`defineSchema` で型安全にスキーマを定義:
+
+```typescript
+import { defineSchema, docCustomSchemaField } from "@interactive-inc/docs-client"
+
+const articleSchema = defineSchema({
+  title: { type: "text", required: true },
+  views: { type: "number", required: false },
+  published: { type: "boolean", required: true },
+  category: { type: "select-text", required: false },
+  tags: { type: "multi-text", required: false },
+  author: docCustomSchemaField.relation(false, "authors"),
+  relatedArticles: docCustomSchemaField.multiRelation(false, "articles"),
+})
+
+// スキーマ付きでディレクトリを取得
+const dirRef = client.directory("articles", articleSchema)
+const fileRef = dirRef.mdFile("hello")
+const entity = await fileRef.read()
+
+// 型安全なメタデータアクセス
+const title = entity.content().meta().field("title") // string
+const views = entity.content().meta().field("views") // number | null
+```
+
+### Schema Field Types
+
+| Type                  | Value Type | Description                |
+| --------------------- | ---------- | -------------------------- |
+| `text`                | `string`   | 単一テキスト               |
+| `number`              | `number`   | 数値                       |
+| `boolean`             | `boolean`  | 真偽値                     |
+| `select-text`         | `string`   | テキスト選択肢から単一選択 |
+| `select-number`       | `number`   | 数値選択肢から単一選択     |
+| `multi-text`          | `string[]` | 複数テキスト               |
+| `multi-number`        | `number[]` | 複数数値                   |
+| `multi-select-text`   | `string[]` | テキスト選択肢から複数選択 |
+| `multi-select-number` | `number[]` | 数値選択肢から複数選択     |
+| `relation`            | `string`   | 他ドキュメントへの参照     |
+| `multi-relation`      | `string[]` | 他ドキュメントへの複数参照 |
+
+## Relations
+
+ドキュメント間のリレーション。
+
+```typescript
+const pageSchema = defineSchema({
+  features: docCustomSchemaField.multiRelation(true, "features"),
+})
+
+const dirRef = client.directory("pages", pageSchema)
+const pageRef = dirRef.mdFile("dashboard")
+
+// 関連ドキュメントの参照を取得
+const featureRefs = await pageRef.relations("features")
+for (const featureRef of featureRefs) {
+  const feature = await featureRef.read()
+  console.log(feature.content().title)
+}
+```
+
+## Directory Operations
+
+```typescript
+const dirRef = client.directory("articles")
+
+// 一覧取得
+const fileNames = await dirRef.fileNames()
+const dirNames = await dirRef.directoryNames()
+
+// 参照取得
+const files = await dirRef.files()
+const mdFiles = await dirRef.mdFiles()
+const subdirs = await dirRef.directories()
+
+// 全ファイル読み取り
+const entities = await dirRef.readMdFiles()
+
+// インデックスファイル読み取り
+const indexEntity = await dirRef.readIndexFile()
+
+// サブディレクトリ
+const subDirRef = dirRef.directory("tutorials")
+
+// 新規ファイル作成
+const newFileRef = await dirRef.createMdFile("new-article.md")
+```
+
+## File Tree
+
+ドキュメントの階層ツリー構造を生成。
+
+```typescript
+const tree = await client.fileTree()
+
+const dirTree = await client.directoryTree()
+
+// ツリーノードの型
+type DocTreeFileNode = {
+  type: "file"
+  name: string
+  path: string
+  icon: string
+  title: string
+}
+
+type DocTreeDirectoryNode = {
+  type: "directory"
+  name: string
+  path: string
+  icon: string
+  title: string
+  children: DocTreeNode[]
+}
+
+type DocTreeNode = DocTreeFileNode | DocTreeDirectoryNode
+```
+
+## File Systems
+
+### Node.js File System
+
+ローカルファイル操作用:
+
+```typescript
+import { DocFileSystemNode } from "@interactive-inc/docs-client/file-system-node"
+
+const fileSystem = new DocFileSystemNode({ basePath: "./docs" })
+```
+
+Read/Write を個別に指定する場合:
+
+```typescript
+import {
+  DocFileSystemNodeRead,
+  DocFileSystemNodeWrite,
+} from "@interactive-inc/docs-client/file-system-node"
+import { DocFileSystem } from "@interactive-inc/docs-client/file-system"
+
+const reader = new DocFileSystemNodeRead({ basePath: "./docs" })
+const writer = new DocFileSystemNodeWrite({ basePath: "./docs", reader })
+
+const fileSystem = new DocFileSystem({ basePath: "./docs", reader, writer })
+```
+
+### GitHub File System (Octokit)
+
+GitHub リポジトリからの読み取り:
+
+```typescript
+import { DocFileSystemOctokitRead } from "@interactive-inc/docs-client/file-system-octokit"
+import { DocFileSystemNodeWrite } from "@interactive-inc/docs-client/file-system-node"
+import { DocFileSystem } from "@interactive-inc/docs-client/file-system"
+
+const reader = new DocFileSystemOctokitRead({
+  token: process.env.GITHUB_TOKEN,
+  owner: "your-org",
+  repo: "your-repo",
+  basePath: "docs",
+  branch: "main",
+})
+
+const writer = new DocFileSystemNodeWrite({
+  basePath: "/tmp/docs-output",
+})
+
+const fileSystem = new DocFileSystem({
+  basePath: "docs",
+  reader,
+  writer,
+})
+```
+
+### JSON File System
+
+インメモリ操作用:
+
+```typescript
+import { DocFileSystemJson } from "@interactive-inc/docs-client/file-system-json"
+
+const fileSystem = new DocFileSystemJson({
+  basePath: "docs",
+  data: {
+    "index.md": "# Home\n\nWelcome!",
+    "articles/hello.md": "# Hello\n\nContent here.",
+  },
+})
+```
+
+### Mock File System
+
+テスト用:
+
+```typescript
+import { DocFileSystemMock } from "@interactive-inc/docs-client/file-system-mock"
+
+const fileSystem = new DocFileSystemMock({ basePath: "docs" })
+```
+
+## License
+
+MIT

package/build/{doc-file-system-DEmPPJPE.d.ts → doc-file-system-z2sEMkq0.d.ts}

@@ -1,9 +1,9 @@
-import { D as DocFileSystemInterface, a as DocPathSystem } from './doc-file-system.interface-C5vpYrOL.js';
+import { D as DocFileSystemInterface, a as DocPathSystem } from './doc-file-system.interface-CmQywbuP.js';
 
 /**
  * Read-only file system interface for document operations
  */
-interface DocFileSystemReadInterface {
+type DocFileSystemReadInterface = {
     /**
      * Read file content at the specified path
      */
@@ -68,12 +68,12 @@ interface DocFileSystemReadInterface {
      * Get file creation time
      */
     getFileCreatedTime(relativePath: string): Promise<Date | Error>;
-}
+};
 
 /**
  * Write-only file system interface for document operations
  */
-interface DocFileSystemWriteInterface {
+type DocFileSystemWriteInterface = {
     /**
      * Write content to file at the specified path (creates directory if needed)
      */
@@ -98,7 +98,7 @@ interface DocFileSystemWriteInterface {
      * Move file
      */
     moveFile(sourcePath: string, destinationPath: string): Promise<Error | null>;
-}
+};
 
 type Props = {
     basePath: string;

package/build/{doc-file-system.interface-C5vpYrOL.d.ts → doc-file-system.interface-CmQywbuP.d.ts}

@@ -3,6 +3,7 @@
  */
 declare class DocPathSystem {
     readonly separator = "/";
+    constructor();
     /**
      * Join paths
      */
@@ -41,7 +42,7 @@ declare class DocPathSystem {
  * Interface for DocFileSystem class
  * Defines all public methods available in DocFileSystem
  */
-interface DocFileSystemInterface {
+type DocFileSystemInterface = {
     /**
      * Read file content at the specified path
      */
@@ -130,6 +131,6 @@ interface DocFileSystemInterface {
      * Get file creation time
      */
     getFileCreatedTime(relativePath: string): Promise<Date | Error>;
-}
+};
 
 export { type DocFileSystemInterface as D, DocPathSystem as a };

package/build/file-system-json.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { a as DocPathSystem } from './doc-file-system.interface-C5vpYrOL.js';
-import { D as DocFileSystem, a as DocFileSystemReadInterface, b as DocFileSystemWriteInterface } from './doc-file-system-DEmPPJPE.js';
+import { a as DocPathSystem } from './doc-file-system.interface-CmQywbuP.js';
+import { D as DocFileSystem, a as DocFileSystemReadInterface, b as DocFileSystemWriteInterface } from './doc-file-system-z2sEMkq0.js';
 
 declare const zJsonDocumentData$2: z.ZodRecord<z.ZodString, z.ZodString>;
 type JsonDocumentData$2 = z.infer<typeof zJsonDocumentData$2>;
@@ -49,8 +49,52 @@ declare class DocFileSystemJson extends DocFileSystem {
 
 declare const zJsonDocumentData$1: z.ZodRecord<z.ZodString, z.ZodString>;
 type JsonDocumentData$1 = z.infer<typeof zJsonDocumentData$1>;
+type Props$2 = {
+    data?: JsonDocumentData$1 | unknown;
+};
+/**
+ * JSON ファイルシステムの可変データストア。reader と writer が同一インスタンスを共有し、
+ * writer の変更が reader に即時反映される単一の真実の源となる
+ */
+declare class DocFileSystemJsonStore {
+    private documents;
+    constructor(props?: Props$2);
+    /**
+     * 指定パスのドキュメント内容を取得する
+     */
+    get(path: string): string | undefined;
+    /**
+     * 指定パスにドキュメント内容を書き込む
+     */
+    set(path: string, content: string): void;
+    /**
+     * 指定パスを削除する。存在すれば true を返す
+     */
+    delete(path: string): boolean;
+    /**
+     * 指定パスが存在するかを返す
+     */
+    has(path: string): boolean;
+    /**
+     * 全ドキュメントのパス一覧を返す
+     */
+    keys(): string[];
+    /**
+     * データ全体を入れ替える
+     */
+    replace(data: JsonDocumentData$1 | unknown): Error | null;
+    /**
+     * 全データを削除する
+     */
+    clear(): void;
+    /**
+     * 現在のデータの読み取り専用コピーを返す
+     */
+    toData(): JsonDocumentData$1;
+}
+
 type Props$1 = {
-    data: JsonDocumentData$1 | unknown;
+    store: DocFileSystemJsonStore;
     basePath?: string;
     pathSystem?: DocPathSystem;
 };
@@ -58,7 +102,7 @@ type Props$1 = {
  * JSON-based read-only file system implementation
  */
 declare class DocFileSystemJsonRead implements DocFileSystemReadInterface {
-    private readonly data;
+    private readonly store;
     private readonly basePath;
     private readonly pathSystem;
     constructor(props: Props$1);
@@ -133,7 +177,7 @@ declare class DocFileSystemJsonRead implements DocFileSystemReadInterface {
     /**
      * Get the raw JSON data
      */
-    getRawData(): JsonDocumentData$1;
+    getRawData(): Record<string, string>;
     /**
      * Normalize path by removing leading/trailing slashes
      */
@@ -151,8 +195,7 @@ declare class DocFileSystemJsonRead implements DocFileSystemReadInterface {
 declare const zJsonDocumentData: z.ZodRecord<z.ZodString, z.ZodString>;
 type JsonDocumentData = z.infer<typeof zJsonDocumentData>;
 type Props = {
-    data?: JsonDocumentData | unknown;
-    basePath?: string;
+    store: DocFileSystemJsonStore;
     pathSystem?: DocPathSystem;
     reader?: DocFileSystemReadInterface;
     onDataChange?: (data: JsonDocumentData) => void;
@@ -161,12 +204,11 @@ type Props = {
  * JSON-based write-only file system implementation
  */
 declare class DocFileSystemJsonWrite implements DocFileSystemWriteInterface {
-    private data;
-    private readonly basePath;
+    private readonly store;
     private readonly pathSystem;
     private readonly reader?;
     private readonly onDataChange?;
-    constructor(props?: Props);
+    constructor(props: Props);
     /**
      * Write content to JSON data
      */