@interactive-inc/docs-client 0.0.8 → 0.0.10

package/PRODUCT.md

@@ -0,0 +1,108 @@
+# docs-client
+
+ドキュメント管理システムのクライアントライブラリ。Markdownファイルを構造化された形式で管理し、フロントマターによるメタデータ管理、スキーマベースのバリデーション、ファイル間のリレーション機能を提供するゆ🥹
+
+## 主要機能
+
+### ドキュメント管理
+
+- Markdownファイルの読み書き
+- フロントマター（YAML形式）の解析と生成
+- ファイルのアーカイブと復元
+- 階層的なディレクトリ構造の管理
+
+### スキーマシステム
+
+- index.mdファイルでのスキーマ定義
+- Zodを使用した型安全なスキーマバリデーション
+- デフォルト値の自動適用
+- 動的なスキーマ生成（Zodスキーマ未定義時）
+
+### リレーション機能
+
+- ファイル間の参照関係を定義
+- 単一リレーション（relation）と複数リレーション（multi-relation）
+- スキーマベースの型安全な参照
+
+### ファイルツリー
+
+- ディレクトリ構造の再帰的探索
+- ファイルツリーとディレクトリツリーの生成
+- アーカイブディレクトリの特別扱い
+
+## アーキテクチャ
+
+### エンティティ（entities/）
+
+- **DocFileMdEntity** - Markdownファイルの表現
+- **DocDirectoryEntity** - ディレクトリの表現
+- **DocTreeFileNode/DocTreeDirectoryNode** - ツリー構造のノード
+
+### 値オブジェクト（values/）
+
+- **DocFileContentMdValue** - Markdownコンテンツ（フロントマター + 本文）
+- **DocFrontMatterIndexValue** - index.mdのフロントマター
+- **DocFrontMatterMdValue** - 通常のMarkdownファイルのフロントマター
+- **DocSchemaValue** - スキーマ定義と検証機能
+- **DocSchemaFieldValue** - スキーマフィールドの定義
+- **DocSchemaBuilder** - 動的スキーマ生成
+
+### リファレンス（references/）
+
+- **DocFileIndexReference** - index.mdファイルの参照
+- **DocFileMdReference** - Markdownファイルの参照
+- **DocDirectoryReference** - ディレクトリの参照
+
+### システム
+
+- **DocFileTreeSystem** - ファイルツリーの構築
+- **DocClient** - クライアントAPI
+- **DocEngine** - ドキュメント処理エンジンのクライアント側統合
+
+## 使用例
+
+```typescript
+// クライアントの初期化
+const client = new DocClient(cwd)
+
+// Markdownファイルの読み込み
+const fileRef = client.mdFile("products/example.md")
+const entity = await fileRef.read()
+
+// スキーマの取得と検証
+const indexRef = client.indexFile("products")
+const indexEntity = await indexRef.read()
+const schema = indexEntity.content.frontMatter.schema()
+
+// リレーションの取得
+const categoryRef = await fileRef.relation("category")
+
+// ファイルツリーの構築
+const fileTree = await client.fileTree("products")
+```
+
+## 特徴
+
+### 型安全性
+
+- TypeScriptのジェネリクスを活用
+- Zodスキーマによる実行時検証
+- 型推論による開発体験の向上
+
+### 不変性
+
+- すべての値オブジェクトは不変
+- Object.freeze()による状態の固定
+- Fluent APIによる操作
+
+### 拡張性
+
+- 依存性注入（DI）パターン
+- 明確な責任分離
+- カスタムスキーマフィールドの追加が容易
+
+## 依存関係
+
+- **@packages/server** - サーバー側のドキュメント処理エンジン
+- **zod** - スキーマ定義とバリデーション
+- **TypeScript** - 型安全性の保証

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import { z } from 'zod/v4';
-import { zDocFileMd, zDocFileContentMd, zDocFileMdFrontMatter, zDocSchema, zDocSchemaFieldText, zDocSchemaField, zDocSchemaFieldMultiText, zDocSchemaFieldNumber, zDocSchemaFieldMultiNumber, zDocSchemaFieldBoolean, zDocSchemaFieldMultiBoolean, zDocSchemaFieldSelectText, zDocSchemaFieldMultiSelectText, zDocSchemaFieldSelectNumber, zDocSchemaFieldMultiSelectNumber, zDocSchemaFieldRelation, zDocSchemaFieldMultiRelation, zDocRelationFile, zDocFilePath, zDocFileUnknown, zDocFileIndex, zDocFileContentIndex, zDocFileIndexFrontMatter, zDocRelation, zDocSchemaFieldType, zDocFile, zDocRelationField } from './models.js';
+import { z } from 'zod';
+import { zDocFileMd, zDocFileContentMd, zDocFileMdFrontMatter, zDocSchema, zDocSchemaFieldText, zDocSchemaField, zDocSchemaFieldMultiText, zDocSchemaFieldNumber, zDocSchemaFieldMultiNumber, zDocSchemaFieldBoolean, zDocSchemaFieldMultiBoolean, zDocSchemaFieldSelectText, zDocSchemaFieldMultiSelectText, zDocSchemaFieldSelectNumber, zDocSchemaFieldMultiSelectNumber, zDocSchemaFieldRelation, zDocSchemaFieldMultiRelation, zDocRelationFile, zDocFilePath, zDocFileUnknown, zDocFileIndex, zDocFileContentIndex, zDocFileIndexFrontMatter, zDocRelation, zDocSchemaFieldType, zDocSchemaFieldMinimal, zDocSchemaMinimal, zDocFile, zDocRelationField } from './models.js';
 export { zDocTreeDirectoryNode, zDocTreeFileNode, zDocTreeNode } from './models.js';
 
 /**
@@ -143,6 +143,13 @@ declare class DocFileSystem {
     getFileCreatedTime(relativePath: string): Promise<Date>;
 }
 
+/**
+ * FrontMatterのスキーマ型
+ * - ZodRecord: 動的なキーを持つ場合（デフォルト）
+ * - ZodObject: 固定されたキーを持つ場合（型安全）
+ */
+type FrontMatterSchema = z.ZodTypeAny;
+
 /**
  * スキーマフィールドで使用可能な型
  */
@@ -208,6 +215,14 @@ type DocSchemaField = z.infer<typeof zDocSchemaField>;
  * スキーマ定義の型
  */
 type DocSchemaRecord = z.infer<typeof zDocSchema>;
+/**
+ * 最小限のスキーマフィールドの型
+ */
+type DocSchemaFieldMinimal = z.infer<typeof zDocSchemaFieldMinimal>;
+/**
+ * 最小限のスキーマ定義の型
+ */
+type DocSchemaMinimal = z.infer<typeof zDocSchemaMinimal>;
 /**
  * リレーション型フィールドのUnion型
  */
@@ -408,6 +423,20 @@ declare class DocFileRelationReference {
     isEmpty(): Promise<boolean>;
 }
 
+/**
+ * 動的にZodスキーマを生成するビルダー
+ */
+declare class DocSchemaBuilder {
+    /**
+     * 動的にZodスキーマを生成
+     */
+    createDynamicSchema(value: unknown): z.ZodTypeAny;
+    /**
+     * フィールドタイプに応じたZodスキーマを生成
+     */
+    private createFieldSchema;
+}
+
 /**
  * リレーション複数型スキーマフィールド
  */
@@ -708,25 +737,34 @@ type DocSchemaFieldRelationTypes = DocSchemaFieldRelationSingleValue | DocSchema
 type DocSchemaFieldValue = DocSchemaFieldTextTypes | DocSchemaFieldNumberTypes | DocSchemaFieldBooleanTypes | DocSchemaFieldSelectTypes | DocSchemaFieldRelationTypes;
 
 /**
- * スキーマとリレーション
+ * 型安全なスキーマ値オブジェクト
+ * @template T - Zodスキーマの型（オプショナル）
  */
-declare class DocSchemaValue {
+declare class DocSchemaValue<T extends z.ZodTypeAny = z.ZodTypeAny> {
     readonly value: DocSchemaRecord;
-    constructor(value: DocSchemaRecord);
+    private readonly zodSchema;
+    constructor(value: unknown, zodSchema?: T, schemaBuilder?: DocSchemaBuilder);
     /**
      * フィールド名の一覧を取得
+     * Zodスキーマを使用している場合は自動的に型安全
      */
     get fieldNames(): string[];
     /**
      * 指定されたフィールド名のフィールドを取得
+     * Zodスキーマを使用している場合は型安全
      */
+    field<K extends keyof z.infer<T> & string>(name: K): DocSchemaFieldValue | null;
     field(name: string): DocSchemaFieldValue | null;
+    /**
+     * すべてのフィールドを取得
+     * 注意: 型安全性のため、個別にfield()メソッドを使用することを推奨
+     */
     get fields(): DocSchemaFieldValue[];
     get relationFields(): (DocSchemaFieldRelationSingleValue | DocSchemaFieldRelationMultipleValue)[];
     /**
      * 空のスキーマエンティティを作成
      */
-    static empty(): DocSchemaValue;
+    static empty<T extends z.ZodTypeAny = z.ZodTypeAny>(zodSchema?: T, dynamicBuilder?: DocSchemaBuilder): DocSchemaValue<T>;
     /**
      * スキーマからリレーションパスを抽出
      */
@@ -783,6 +821,10 @@ declare class DocSchemaValue {
      * スキーマベースでFrontMatterを補完する
      */
     getCompleteFrontMatter(rawFrontMatter: unknown): DocFileMdFrontMatter;
+    /**
+     * 型安全にFrontMatterを補完する（Zodスキーマを使用している場合）
+     */
+    getTypedCompleteFrontMatter(rawFrontMatter: Partial<z.infer<T>>): z.infer<T>;
     /**
      * スキーマからデフォルトFrontMatterを生成
      */
@@ -800,6 +842,10 @@ declare class DocSchemaValue {
      */
     private isNullOrUndefined;
     toJson(): DocSchemaRecord;
+    /**
+     * スキーマを正規化（エラーを出すように変更）
+     */
+    private static normalizeSchema;
 }
 
 /**
@@ -811,11 +857,11 @@ declare class DocFrontMatterIndexValue {
     /**
      * アイコンを取得
      */
-    get icon(): string | null;
+    icon(): string;
     /**
      * スキーマを取得
      */
-    get schema(): DocSchemaValue;
+    schema<T extends z.ZodTypeAny = z.ZodTypeAny>(zodSchema?: T): DocSchemaValue<T>;
     /**
      * iconフィールドを更新
      */
@@ -1023,23 +1069,25 @@ declare class DocFileIndexReference {
 /**
  * FrontMatter
  */
-declare class DocFrontMatterMdValue {
+declare class DocFrontMatterMdValue<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter> {
+    private readonly zodSchema;
+    constructor(value: DocFileMdFrontMatter, zodSchema: T);
     readonly value: DocFileMdFrontMatter;
-    constructor(value: DocFileMdFrontMatter);
     toJson(): DocFileMdFrontMatter;
     toYaml(): string;
+    schema<U extends z.ZodTypeAny = z.ZodTypeAny>(zodSchema?: U): DocSchemaValue<U>;
     /**
      * Markdownテキストから生成
      */
-    static from(markdownText: string): DocFrontMatterMdValue;
+    static from<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(markdownText: string, zodSchema: T): DocFrontMatterMdValue<T>;
     /**
      * 空のFrontMatterを生成
      */
-    static empty(): DocFrontMatterMdValue;
+    static empty<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(zodSchema: T): DocFrontMatterMdValue<T>;
     /**
      * データから直接生成
      */
-    static fromData(data: unknown): DocFrontMatterMdValue;
+    static fromData<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(data: unknown, zodSchema: T): DocFrontMatterMdValue<T>;
     /**
      * スキーマフィールドに基づいてデフォルト値を生成する
      */
@@ -1049,13 +1097,8 @@ declare class DocFrontMatterMdValue {
     }): unknown;
     /**
      * 単一のプロパティを更新した新しいインスタンスを返す
-     * スキーマに基づいて型を検証し、スキーマのフィールドのみを含む新しいインスタンスを生成
      */
-    withProperty(key: string, value: unknown, schema: DocSchemaValue): DocFrontMatterMdValue;
-    /**
-     * フィールド値の検証
-     */
-    private validateFieldValue;
+    withProperty(key: string, value: unknown): DocFrontMatterMdValue<T>;
     /**
      * テキスト型のプロパティを取得
      */
@@ -1096,14 +1139,24 @@ declare class DocFrontMatterMdValue {
      * すべてのキーを取得
      */
     get keys(): string[];
+    /**
+     * フィールドアクセス（Zodスキーマで型安全）
+     */
+    field<K extends keyof z.infer<T> & string>(key: K): T extends z.ZodTypeAny ? z.infer<T>[K] | null : unknown;
+    field(key: string): unknown;
+    /**
+     * 型安全な値の取得
+     */
+    get typedValue(): z.infer<T> | null;
 }
 
 /**
  * Markdownコンテンツ情報の値オブジェクト
  */
-declare class DocFileContentMdValue {
+declare class DocFileContentMdValue<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter> {
     readonly value: DocFileContentMd;
-    constructor(value: DocFileContentMd);
+    private readonly zodSchema;
+    constructor(value: DocFileContentMd, zodSchema: T);
     /**
      * コンテンツ本文（frontMatterを含まない）
      */
@@ -1117,29 +1170,33 @@ declare class DocFileContentMdValue {
      */
     get description(): string;
     /**
-     * FrontMatter
+     * FrontMatter（コンストラクタのZodスキーマまたは引数のスキーマを使用）
      */
-    get frontMatter(): DocFrontMatterMdValue;
+    frontMatter<U extends FrontMatterSchema = T>(zodSchema?: U): DocFrontMatterMdValue<U extends FrontMatterSchema ? U : T>;
     /**
      * タイトルを更新
      */
-    withTitle(title: string): DocFileContentMdValue;
+    withTitle(title: string): DocFileContentMdValue<T>;
     /**
      * 説明を更新
      */
-    withDescription(description: string, defaultTitle?: string): DocFileContentMdValue;
+    withDescription(description: string, defaultTitle?: string): DocFileContentMdValue<T>;
     /**
      * コンテンツを更新
      */
-    withContent(content: string): DocFileContentMdValue;
+    withContent(content: string): DocFileContentMdValue<T>;
     /**
      * FrontMatterを更新
      */
-    withFrontMatter(frontMatter: DocFrontMatterMdValue): DocFileContentMdValue;
+    withFrontMatter<U extends FrontMatterSchema>(frontMatter: DocFrontMatterMdValue<U>, zodSchema: U): DocFileContentMdValue<U>;
+    /**
+     * FrontMatterの特定のプロパティを更新
+     */
+    withFrontMatterProperty(key: string, value: unknown): DocFileContentMdValue<T>;
     /**
      * Markdownテキストから生成
      */
-    static fromMarkdown(markdown: string): DocFileContentMdValue;
+    static fromMarkdown<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(markdown: string, zodSchema?: T): DocFileContentMdValue<T>;
     /**
      * 完全なMarkdownテキストを生成
      */
@@ -1151,7 +1208,7 @@ declare class DocFileContentMdValue {
     /**
      * 空のコンテンツを生成
      */
-    static empty(title: string): DocFileContentMdValue;
+    static empty<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(title: string, zodSchema: T): DocFileContentMdValue<T>;
     /**
      * JSON形式で出力
      */
@@ -1267,7 +1324,7 @@ declare class DocFileMdReference {
     /**
      * 同じディレクトリのindex.mdを取得する
      */
-    getDirectoryIndex(): Promise<DocFileMdEntity | null>;
+    getDirectoryIndex(): Promise<DocFileIndexReference | null>;
     /**
      * 複数のリレーションを取得する
      */
@@ -1276,6 +1333,14 @@ declare class DocFileMdReference {
      * スキーマに基づいて複数のリレーションを取得する
      */
     multiRelation(key: string): Promise<DocFileMdReference[]>;
+    /**
+     * FrontMatterを型安全に読み込む
+     */
+    readFrontMatter<T extends z.ZodTypeAny = z.ZodTypeAny>(zodSchema?: T): Promise<DocFrontMatterMdValue<T> | Error>;
+    /**
+     * FrontMatterを型安全に更新
+     */
+    updateFrontMatter<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(key: string, value: unknown, zodSchema?: T): Promise<undefined | Error>;
 }
 
 /**
@@ -1404,10 +1469,24 @@ declare class DocDirectoryReference {
     mdFilesGenerator(): AsyncGenerator<DocFileMdReference, void, unknown>;
     files(): Promise<(DocFileMdReference | DocFileUnknownReference)[]>;
     mdFiles(): Promise<DocFileMdReference[]>;
+    /**
+     * Markdownファイルの参照とFrontMatterを型安全に取得
+     */
+    mdFilesWithFrontMatter<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(zodSchema: T): Promise<{
+        reference: DocFileMdReference;
+        frontMatter: DocFrontMatterMdValue<T> | Error;
+    }[]>;
     file(fileName: string): DocFileMdReference | DocFileUnknownReference;
     mdFile(fileName: string): DocFileMdReference;
     readFiles(): Promise<(DocFileMdEntity | DocFileUnknownEntity)[]>;
     readMdFiles(): Promise<DocFileMdEntity[]>;
+    /**
+     * Zodスキーマを使って型安全にMarkdownファイルのFrontMatterを読み込む
+     */
+    readMdFilesWithSchema<T extends FrontMatterSchema = typeof zDocFileMdFrontMatter>(zodSchema: T): Promise<{
+        entity: DocFileMdEntity;
+        frontMatter: DocFrontMatterMdValue<T>;
+    }[]>;
     readUnknownFiles(): Promise<DocFileUnknownEntity[]>;
     /**
      * サブディレクトリ名の一覧を取得
@@ -1918,4 +1997,4 @@ declare class DocSchemaFieldFactory {
     private getTypeSpecificDefaults;
 }
 
-export { DocClient, DocContentMdValue, type DocDirectory, DocDirectoryPathValue, DocDirectoryReference, type DocFieldMultiBoolean, type DocFieldMultiNumber, type DocFieldMultiRelation, type DocFieldMultiText, type DocFile, type DocFileContentIndex, DocFileContentIndexValue, type DocFileContentMd, DocFileContentMdValue, type DocFileIndex, DocFileIndexEntity, type DocFileIndexFrontMatter, DocFileIndexReference, type DocFileMd, DocFileMdEntity, type DocFileMdFrontMatter, DocFileMdReference, type DocFileNode, type DocFilePath, DocFilePathValue, DocFileRelationReference, DocFileSystem, type DocFileUnknown, DocFileUnknownEntity, DocFileUnknownReference, DocFrontMatterIndexValue, DocFrontMatterMdValue, DocMarkdownSystem, DocPathSystem, type DocRelation, type DocRelationField, type DocRelationFile, DocRelationFileValue, DocRelationValue, type DocSchemaField, type DocSchemaFieldBoolean, DocSchemaFieldBooleanMultipleValue, DocSchemaFieldBooleanSingleValue, DocSchemaFieldFactory, type DocSchemaFieldMultiSelectNumber, type DocSchemaFieldMultiSelectText, type DocSchemaFieldNumber, DocSchemaFieldNumberMultipleValue, DocSchemaFieldNumberSingleValue, type DocSchemaFieldRelation, DocSchemaFieldRelationMultipleValue, DocSchemaFieldRelationSingleValue, type DocSchemaFieldSelectNumber, DocSchemaFieldSelectNumberMultipleValue, DocSchemaFieldSelectNumberSingleValue, type DocSchemaFieldSelectText, DocSchemaFieldSelectTextMultipleValue, DocSchemaFieldSelectTextSingleValue, type DocSchemaFieldText, DocSchemaFieldTextMultipleValue, DocSchemaFieldTextSingleValue, type DocSchemaFieldType, type DocSchemaFieldValue, type DocSchemaRecord, DocSchemaValue, type DocTreeDirectoryNode, DocTreeDirectoryNodeValue, type DocTreeFileNode, DocTreeFileNodeValue, type DocTreeNode, type FieldType, DocFileTreeSystem as FileTreeSystem, type RelationFieldTypes, zDocFile, zDocFileContentIndex, zDocFileContentMd, zDocFileIndex, zDocFileIndexFrontMatter, zDocFileMd, zDocFileMdFrontMatter, zDocFilePath, zDocFileUnknown, zDocRelation, zDocRelationField, zDocRelationFile, zDocSchema, zDocSchemaField, zDocSchemaFieldBoolean, zDocSchemaFieldMultiBoolean, zDocSchemaFieldMultiNumber, zDocSchemaFieldMultiRelation, zDocSchemaFieldMultiSelectNumber, zDocSchemaFieldMultiSelectText, zDocSchemaFieldMultiText, zDocSchemaFieldNumber, zDocSchemaFieldRelation, zDocSchemaFieldSelectNumber, zDocSchemaFieldSelectText, zDocSchemaFieldText, zDocSchemaFieldType };
+export { DocClient, DocContentMdValue, type DocDirectory, DocDirectoryPathValue, DocDirectoryReference, type DocFieldMultiBoolean, type DocFieldMultiNumber, type DocFieldMultiRelation, type DocFieldMultiText, type DocFile, type DocFileContentIndex, DocFileContentIndexValue, type DocFileContentMd, DocFileContentMdValue, type DocFileIndex, DocFileIndexEntity, type DocFileIndexFrontMatter, DocFileIndexReference, type DocFileMd, DocFileMdEntity, type DocFileMdFrontMatter, DocFileMdReference, type DocFileNode, type DocFilePath, DocFilePathValue, DocFileRelationReference, DocFileSystem, type DocFileUnknown, DocFileUnknownEntity, DocFileUnknownReference, DocFrontMatterIndexValue, DocFrontMatterMdValue, DocMarkdownSystem, DocPathSystem, type DocRelation, type DocRelationField, type DocRelationFile, DocRelationFileValue, DocRelationValue, type DocSchemaField, type DocSchemaFieldBoolean, DocSchemaFieldBooleanMultipleValue, DocSchemaFieldBooleanSingleValue, DocSchemaFieldFactory, type DocSchemaFieldMinimal, type DocSchemaFieldMultiSelectNumber, type DocSchemaFieldMultiSelectText, type DocSchemaFieldNumber, DocSchemaFieldNumberMultipleValue, DocSchemaFieldNumberSingleValue, type DocSchemaFieldRelation, DocSchemaFieldRelationMultipleValue, DocSchemaFieldRelationSingleValue, type DocSchemaFieldSelectNumber, DocSchemaFieldSelectNumberMultipleValue, DocSchemaFieldSelectNumberSingleValue, type DocSchemaFieldSelectText, DocSchemaFieldSelectTextMultipleValue, DocSchemaFieldSelectTextSingleValue, type DocSchemaFieldText, DocSchemaFieldTextMultipleValue, DocSchemaFieldTextSingleValue, type DocSchemaFieldType, type DocSchemaFieldValue, type DocSchemaMinimal, type DocSchemaRecord, DocSchemaValue, type DocTreeDirectoryNode, DocTreeDirectoryNodeValue, type DocTreeFileNode, DocTreeFileNodeValue, type DocTreeNode, type FieldType, DocFileTreeSystem as FileTreeSystem, type FrontMatterSchema, type RelationFieldTypes, zDocFile, zDocFileContentIndex, zDocFileContentMd, zDocFileIndex, zDocFileIndexFrontMatter, zDocFileMd, zDocFileMdFrontMatter, zDocFilePath, zDocFileUnknown, zDocRelation, zDocRelationField, zDocRelationFile, zDocSchema, zDocSchemaField, zDocSchemaFieldBoolean, zDocSchemaFieldMinimal, zDocSchemaFieldMultiBoolean, zDocSchemaFieldMultiNumber, zDocSchemaFieldMultiRelation, zDocSchemaFieldMultiSelectNumber, zDocSchemaFieldMultiSelectText, zDocSchemaFieldMultiText, zDocSchemaFieldNumber, zDocSchemaFieldRelation, zDocSchemaFieldSelectNumber, zDocSchemaFieldSelectText, zDocSchemaFieldText, zDocSchemaFieldType, zDocSchemaMinimal };