@interactive-inc/docs-client 0.0.14 → 0.0.16

package/build/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { zDocClientConfig, zDocCustomSchemaField, zDocFilePath, zDocMetaFieldRelation, zDocMetaFieldMultiRelation, zDocMetaFieldText, zDocMetaFieldNumber, zDocMetaFieldBoolean, zDocMetaFieldMultiText, zDocMetaFieldMultiNumber, zDocMetaFieldMultiBoolean, zDocFileUnknown, zDocFileIndexSchemaField, zDocSchemaFieldText, zDocSchemaFieldNumber, zDocSchemaFieldBoolean, zDocSchemaFieldRelation, zDocSchemaFieldSelectText, zDocSchemaFieldSelectNumber, zDocSchemaFieldMultiText, zDocSchemaFieldMultiNumber, zDocSchemaFieldMultiRelation, zDocSchemaFieldMultiSelectText, zDocSchemaFieldMultiSelectNumber, zDocRelation, zDocRelationFile, zDocMetaField, zDocMetaFieldSelectText, zDocMetaFieldSelectNumber, zDocMetaFieldMultiSelectText, zDocMetaFieldMultiSelectNumber, zDocMetaFieldTypeText, zDocMetaFieldTypeNumber, zDocMetaFieldTypeBoolean, zDocMetaFieldTypeSelectText, zDocMetaFieldTypeSelectNumber, zDocMetaFieldTypeRelation, zDocMetaFieldType, zDocCustomSchemaFieldText, zDocCustomSchemaFieldNumber, zDocCustomSchemaFieldBoolean, zDocCustomSchemaFieldRelation, zDocCustomSchemaFieldSelectText, zDocCustomSchemaFieldSelectNumber, zDocCustomSchemaFieldMultiText, zDocCustomSchemaFieldMultiNumber, zDocCustomSchemaFieldMultiRelation, zDocCustomSchemaFieldMultiSelectText, zDocCustomSchemaFieldMultiSelectNumber, zDocRelationField } from './models.js';
-export { zDocCustomSchema, zDocFile, zDocFileIndex, zDocFileIndexContent, zDocFileIndexMeta, zDocFileIndexMetaInput, zDocFileIndexSchema, zDocFileIndexSchemaInput, zDocFileMd, zDocFileMdContent, zDocFileMdContentInput, zDocFileMdInput, zDocFileMdMeta, zDocFileMdMetaInput, zDocMetaFieldTypeMultiNumber, zDocMetaFieldTypeMultiRelation, zDocMetaFieldTypeMultiSelectNumber, zDocMetaFieldTypeMultiSelectText, zDocMetaFieldTypeMultiText, zDocTreeDirectoryNode, zDocTreeFileNode, zDocTreeNode } from './models.js';
+import { zDocClientConfig, zDocFilePath, zDocMetaFieldRelation, zDocMetaFieldMultiRelation, zDocMetaFieldText, zDocMetaFieldNumber, zDocMetaFieldBoolean, zDocMetaFieldMultiText, zDocMetaFieldMultiNumber, zDocMetaFieldMultiBoolean, zDocFileUnknown, zDocFileIndexSchemaField, zDocSchemaFieldText, zDocSchemaFieldNumber, zDocSchemaFieldBoolean, zDocSchemaFieldRelation, zDocSchemaFieldSelectText, zDocSchemaFieldSelectNumber, zDocSchemaFieldMultiText, zDocSchemaFieldMultiNumber, zDocSchemaFieldMultiRelation, zDocSchemaFieldMultiSelectText, zDocSchemaFieldMultiSelectNumber, zDocRelation, zDocRelationFile, zDocMetaField, zDocMetaFieldSelectText, zDocMetaFieldSelectNumber, zDocMetaFieldMultiSelectText, zDocMetaFieldMultiSelectNumber, zDocMetaFieldTypeText, zDocMetaFieldTypeNumber, zDocMetaFieldTypeBoolean, zDocMetaFieldTypeSelectText, zDocMetaFieldTypeSelectNumber, zDocMetaFieldTypeRelation, zDocMetaFieldType, zDocRelationField } from './models.js';
+export { zDocCustomSchema, zDocCustomSchemaField, zDocCustomSchemaFieldBoolean, zDocCustomSchemaFieldMultiNumber, zDocCustomSchemaFieldMultiRelation, zDocCustomSchemaFieldMultiSelectNumber, zDocCustomSchemaFieldMultiSelectText, zDocCustomSchemaFieldMultiText, zDocCustomSchemaFieldNumber, zDocCustomSchemaFieldRelation, zDocCustomSchemaFieldSelectNumber, zDocCustomSchemaFieldSelectText, zDocCustomSchemaFieldText, zDocFile, zDocFileIndex, zDocFileIndexContent, zDocFileIndexMeta, zDocFileIndexMetaInput, zDocFileIndexSchema, zDocFileIndexSchemaInput, zDocFileMd, zDocFileMdContent, zDocFileMdContentInput, zDocFileMdInput, zDocFileMdMeta, zDocFileMdMetaInput, zDocMetaFieldTypeMultiNumber, zDocMetaFieldTypeMultiRelation, zDocMetaFieldTypeMultiSelectNumber, zDocMetaFieldTypeMultiSelectText, zDocMetaFieldTypeMultiText, zDocTreeDirectoryNode, zDocTreeFileNode, zDocTreeNode } from './models.js';
 
 /**
  * Path operations system
@@ -481,17 +481,50 @@ type DocMetaFieldTypeRelation = z.infer<typeof zDocMetaFieldTypeRelation>;
  * Schema field type
  */
 type DocMetaFieldType = z.infer<typeof zDocMetaFieldType>;
-type DocCustomSchemaFieldText = z.infer<typeof zDocCustomSchemaFieldText>;
-type DocCustomSchemaFieldNumber = z.infer<typeof zDocCustomSchemaFieldNumber>;
-type DocCustomSchemaFieldBoolean = z.infer<typeof zDocCustomSchemaFieldBoolean>;
-type DocCustomSchemaFieldRelation = z.infer<typeof zDocCustomSchemaFieldRelation>;
-type DocCustomSchemaFieldSelectText = z.infer<typeof zDocCustomSchemaFieldSelectText>;
-type DocCustomSchemaFieldSelectNumber = z.infer<typeof zDocCustomSchemaFieldSelectNumber>;
-type DocCustomSchemaFieldMultiText = z.infer<typeof zDocCustomSchemaFieldMultiText>;
-type DocCustomSchemaFieldMultiNumber = z.infer<typeof zDocCustomSchemaFieldMultiNumber>;
-type DocCustomSchemaFieldMultiRelation = z.infer<typeof zDocCustomSchemaFieldMultiRelation>;
-type DocCustomSchemaFieldMultiSelectText = z.infer<typeof zDocCustomSchemaFieldMultiSelectText>;
-type DocCustomSchemaFieldMultiSelectNumber = z.infer<typeof zDocCustomSchemaFieldMultiSelectNumber>;
+type DocCustomSchemaFieldText = {
+    type: "text";
+    required: boolean;
+};
+type DocCustomSchemaFieldNumber = {
+    type: "number";
+    required: boolean;
+};
+type DocCustomSchemaFieldBoolean = {
+    type: "boolean";
+    required: boolean;
+};
+type DocCustomSchemaFieldRelation = {
+    type: "relation";
+    required: boolean;
+};
+type DocCustomSchemaFieldSelectText = {
+    type: "select-text";
+    required: boolean;
+};
+type DocCustomSchemaFieldSelectNumber = {
+    type: "select-number";
+    required: boolean;
+};
+type DocCustomSchemaFieldMultiText = {
+    type: "multi-text";
+    required: boolean;
+};
+type DocCustomSchemaFieldMultiNumber = {
+    type: "multi-number";
+    required: boolean;
+};
+type DocCustomSchemaFieldMultiRelation = {
+    type: "multi-relation";
+    required: boolean;
+};
+type DocCustomSchemaFieldMultiSelectText = {
+    type: "multi-select-text";
+    required: boolean;
+};
+type DocCustomSchemaFieldMultiSelectNumber = {
+    type: "multi-select-number";
+    required: boolean;
+};
 /**
  * Schema field type
  */
@@ -504,7 +537,11 @@ type DocFileIndexSchema<T extends RecordKey> = Record<T, DocFileIndexSchemaField
  * Schema field to override
  * ex: { xxx: { type: "text", required: true } }
  */
-type DocCustomSchemaField = z.infer<typeof zDocCustomSchemaField>;
+type DocCustomSchemaField = DocCustomSchemaFieldText | DocCustomSchemaFieldNumber | DocCustomSchemaFieldBoolean | DocCustomSchemaFieldRelation | DocCustomSchemaFieldSelectText | DocCustomSchemaFieldSelectNumber | DocCustomSchemaFieldMultiText | DocCustomSchemaFieldMultiNumber | DocCustomSchemaFieldMultiRelation | DocCustomSchemaFieldMultiSelectText | DocCustomSchemaFieldMultiSelectNumber;
+/**
+ * Type literal for field types
+ */
+type DocFieldTypeLiteral = "text" | "number" | "boolean" | "relation" | "multi-text" | "multi-number" | "multi-relation" | "select-text" | "select-number" | "multi-select-text" | "multi-select-number";
 /**
  * Minimal schema definition type
  */
@@ -566,7 +603,7 @@ type MultiRelationKeys<T extends DocCustomSchema> = {
 /**
  * Markdown file type (excluding index.md)
  */
-type DocFileMd<T extends DocCustomSchema = DocCustomSchema> = {
+type DocFileMd<T extends DocCustomSchema> = {
     type: "markdown";
     path: DocFilePath;
     isArchived: boolean;
@@ -671,12 +708,12 @@ type OptionalKeys<T extends DocCustomSchema> = {
 type SchemaToValueType<T extends DocCustomSchema> = {
     [K in RequiredKeys<T>]: BaseFieldValueType<ExtractFieldType<T[K]>>;
 } & {
-    [K in OptionalKeys<T>]?: BaseFieldValueType<ExtractFieldType<T[K]>>;
+    [K in OptionalKeys<T>]?: BaseFieldValueType<ExtractFieldType<T[K]>> | null;
 };
 /**
  * Helper type for type-safe property access
  */
-type GetValueType<T extends DocCustomSchema, K extends keyof T> = K extends RequiredKeys<T> ? BaseFieldValueType<ExtractFieldType<T[K]>> : BaseFieldValueType<ExtractFieldType<T[K]>> | undefined;
+type GetValueType<T extends DocCustomSchema, K extends keyof T> = K extends RequiredKeys<T> ? BaseFieldValueType<ExtractFieldType<T[K]>> : BaseFieldValueType<ExtractFieldType<T[K]>> | undefined | null;
 /**
  * Type definitions for DocFileIndexSchema
  */
@@ -687,6 +724,10 @@ type GetIndexFieldType<Schema extends DocFileIndexSchema<RecordKey>, K extends k
 type GetIndexFieldValueType<Schema extends DocFileIndexSchema<RecordKey>, K extends keyof Schema> = Schema[K] extends {
     type: infer Type;
 } ? Type extends "text" ? DocSchemaFieldTextValue<K> : Type extends "number" ? DocSchemaFieldNumberValue<K> : Type extends "boolean" ? DocSchemaFieldBooleanValue<K> : Type extends "relation" ? DocSchemaFieldRelationValue<K> : Type extends "select-text" ? DocSchemaFieldSelectTextValue<K> : Type extends "select-number" ? DocSchemaFieldSelectNumberValue<K> : Type extends "multi-text" ? DocSchemaFieldMultiTextValue<K> : Type extends "multi-number" ? DocSchemaFieldMultiNumberValue<K> : Type extends "multi-relation" ? DocSchemaFieldMultiRelationValue<K> : Type extends "multi-select-text" ? DocSchemaFieldMultiSelectTextValue<K> : Type extends "multi-select-number" ? DocSchemaFieldMultiSelectNumberValue<K> : never : never;
+/**
+ * Infers DocFileMd type from the result of defineSchema
+ */
+type InferDocFileMd<T> = T extends DocCustomSchema ? DocFileMd<T> : never;
 
 /**
  * Relation file
@@ -866,6 +907,11 @@ declare class DocFileIndexMetaValue<T extends DocCustomSchema> {
      * Update schema field
      */
     withSchema(value: DocFileIndexSchema<keyof T>): DocFileIndexMetaValue<T>;
+    /**
+     * Return a new instance with an unknown schema
+     * Allows accepting Record<string, unknown> schemas from external sources
+     */
+    withUnknownSchema(draft: Record<string, unknown>): DocFileIndexMetaValue<DocCustomSchema>;
     /**
      * Output in JSON format
      */
@@ -1076,6 +1122,11 @@ declare class DocFileMdMetaValue<T extends DocCustomSchema> {
      * Return a new instance with a single property updated
      */
     withProperty<K extends keyof T>(key: K, value: BaseFieldValueType<ExtractFieldType<T[K]>>): DocFileMdMetaValue<T>;
+    /**
+     * Return a new instance with an unknown schema
+     * Allows accepting Record<string, unknown> schemas from external sources
+     */
+    withUnknownSchema(draft: Record<string, unknown>): DocFileMdMetaValue<DocCustomSchema>;
     schemaField<K extends keyof T>(key: K): T[K];
     field<K extends keyof T>(key: K): FieldValueType<ExtractFieldType<T[K]>, ExtractRequired<T[K]>>;
     relation(key: keyof T): DocMetaFieldRelation;
@@ -1714,4 +1765,150 @@ declare class DocFileSystemDebug extends DocFileSystem {
 
 type DocFileEntity<T extends DocCustomSchema> = DocFileMdEntity<T> | DocFileIndexEntity<T> | DocFileUnknownEntity;
 
-export { type BaseFieldValueType, DocClient, type DocClientConfig, type DocCustomSchema, type DocCustomSchemaField, type DocCustomSchemaFieldBoolean, type DocCustomSchemaFieldMultiNumber, type DocCustomSchemaFieldMultiRelation, type DocCustomSchemaFieldMultiSelectNumber, type DocCustomSchemaFieldMultiSelectText, type DocCustomSchemaFieldMultiText, type DocCustomSchemaFieldNumber, type DocCustomSchemaFieldRelation, type DocCustomSchemaFieldSelectNumber, type DocCustomSchemaFieldSelectText, type DocCustomSchemaFieldText, type DocDirectory, DocDirectoryReference, type DocFile, type DocFileEntity, type DocFileIndex, type DocFileIndexContent, DocFileIndexEntity, type DocFileIndexMeta, DocFileIndexReference, type DocFileIndexSchema, type DocFileIndexSchemaField, type DocFileMd, type DocFileMdContent, DocFileMdEntity, type DocFileMdMeta, DocFileMdReference, type DocFilePath, DocFileRelationReference, DocFileSystem, DocFileSystemDebug, type DocFileUnknown, DocFileUnknownEntity, DocFileUnknownReference, DocMarkdownSystem, type DocMetaField, type DocMetaFieldBoolean, type DocMetaFieldMultiBoolean, type DocMetaFieldMultiNumber, type DocMetaFieldMultiRelation, type DocMetaFieldMultiSelectNumber, type DocMetaFieldMultiSelectText, type DocMetaFieldMultiText, type DocMetaFieldNumber, type DocMetaFieldRelation, type DocMetaFieldSelectNumber, type DocMetaFieldSelectText, type DocMetaFieldText, type DocMetaFieldType, type DocMetaFieldTypeBoolean, type DocMetaFieldTypeNumber, type DocMetaFieldTypeRelation, type DocMetaFieldTypeSelectNumber, type DocMetaFieldTypeSelectText, type DocMetaFieldTypeText, DocPathSystem, type DocRelation, type DocRelationField, type DocRelationFile, type DocSchemaFieldBoolean, type DocSchemaFieldMultiNumber, type DocSchemaFieldMultiRelation, type DocSchemaFieldMultiSelectNumber, type DocSchemaFieldMultiSelectText, type DocSchemaFieldMultiText, type DocSchemaFieldNumber, type DocSchemaFieldRelation, type DocSchemaFieldSelectNumber, type DocSchemaFieldSelectText, type DocSchemaFieldText, type DocSchemaRelationFieldUnion, type DocTreeDirectoryNode, type DocTreeFileNode, type DocTreeNode, type Equals, type ExtractFieldType, type ExtractIndexFieldType, type ExtractRequired, type FieldValueType, DocFileTreeSystem as FileTreeSystem, type GetIndexFieldType, type GetIndexFieldValueType, type GetValueType, type MultiRelationKeys, type OptionalKeys, type RecordKey, type RelationKeys, type RequiredKeys, type SchemaToValueType, zDocClientConfig, zDocCustomSchemaField, zDocCustomSchemaFieldBoolean, zDocCustomSchemaFieldMultiNumber, zDocCustomSchemaFieldMultiRelation, zDocCustomSchemaFieldMultiSelectNumber, zDocCustomSchemaFieldMultiSelectText, zDocCustomSchemaFieldMultiText, zDocCustomSchemaFieldNumber, zDocCustomSchemaFieldRelation, zDocCustomSchemaFieldSelectNumber, zDocCustomSchemaFieldSelectText, zDocCustomSchemaFieldText, zDocFileIndexSchemaField, zDocFilePath, zDocFileUnknown, zDocMetaField, zDocMetaFieldBoolean, zDocMetaFieldMultiBoolean, zDocMetaFieldMultiNumber, zDocMetaFieldMultiRelation, zDocMetaFieldMultiSelectNumber, zDocMetaFieldMultiSelectText, zDocMetaFieldMultiText, zDocMetaFieldNumber, zDocMetaFieldRelation, zDocMetaFieldSelectNumber, zDocMetaFieldSelectText, zDocMetaFieldText, zDocMetaFieldType, zDocMetaFieldTypeBoolean, zDocMetaFieldTypeNumber, zDocMetaFieldTypeRelation, zDocMetaFieldTypeSelectNumber, zDocMetaFieldTypeSelectText, zDocMetaFieldTypeText, zDocRelation, zDocRelationField, zDocRelationFile, zDocSchemaFieldBoolean, zDocSchemaFieldMultiNumber, zDocSchemaFieldMultiRelation, zDocSchemaFieldMultiSelectNumber, zDocSchemaFieldMultiSelectText, zDocSchemaFieldMultiText, zDocSchemaFieldNumber, zDocSchemaFieldRelation, zDocSchemaFieldSelectNumber, zDocSchemaFieldSelectText, zDocSchemaFieldText };
+/**
+ * Schema builder
+ * Build schemas in a chain style
+ *
+ * @example
+ * const schema = new SchemaBuilder()
+ *   .text("title", true)
+ *   .multiRelation("features", true)
+ *   .selectText("priority", false)
+ *   .build()
+ */
+declare class SchemaBuilder<T extends DocCustomSchema> {
+    private schema;
+    constructor(schema?: T);
+    text<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "text";
+        required: boolean;
+    }>>;
+    number<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "number";
+        required: boolean;
+    }>>;
+    boolean<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "boolean";
+        required: boolean;
+    }>>;
+    relation<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "relation";
+        required: boolean;
+    }>>;
+    multiRelation<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "multi-relation";
+        required: boolean;
+    }>>;
+    selectText<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "select-text";
+        required: boolean;
+    }>>;
+    selectNumber<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "select-number";
+        required: boolean;
+    }>>;
+    multiText<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "multi-text";
+        required: boolean;
+    }>>;
+    multiNumber<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "multi-number";
+        required: boolean;
+    }>>;
+    multiSelectText<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "multi-select-text";
+        required: boolean;
+    }>>;
+    multiSelectNumber<K extends string>(key: K, required: boolean): SchemaBuilder<T & Record<K, {
+        type: "multi-select-number";
+        required: boolean;
+    }>>;
+    build(): T;
+}
+
+/**
+ * Function that only performs type checking (does nothing at runtime)
+ */
+declare function expectType<T>(_value: T): void;
+/**
+ * Type-level assertion
+ * Compiles only when Equals<T, U> is true
+ */
+declare function assertType<_T extends true>(): void;
+/**
+ * Default configuration for tests
+ */
+declare const defaultTestConfig: {
+    defaultIndexIcon: string;
+    indexFileName: string;
+    archiveDirectoryName: string;
+    defaultDirectoryName: string;
+    indexMetaIncludes: never[];
+    directoryExcludes: string[];
+};
+/**
+ * Helper function for defining schemas
+ * Enables type completion while defining schemas
+ *
+ * @example
+ * const mySchema = defineSchema({
+ *   title: { type: "text", required: true },
+ *   priority: { type: "select-text", required: false },
+ *   features: { type: "multi-relation", required: true }
+ * })
+ *
+ * type MyDoc = InferDocFileMd<typeof mySchema>
+ */
+declare function defineSchema<T extends DocCustomSchema>(schema: T): T;
+/**
+ * Helper functions for field definitions
+ * Use when finer control is needed
+ */
+declare const docCustomSchemaField: {
+    readonly text: (required: boolean) => {
+        type: "text";
+        required: boolean;
+    };
+    readonly number: (required: boolean) => {
+        type: "number";
+        required: boolean;
+    };
+    readonly boolean: (required: boolean) => {
+        type: "boolean";
+        required: boolean;
+    };
+    readonly relation: (required: boolean) => {
+        type: "relation";
+        required: boolean;
+    };
+    readonly multiRelation: (required: boolean) => {
+        type: "multi-relation";
+        required: boolean;
+    };
+    readonly selectText: (required: boolean) => {
+        type: "select-text";
+        required: boolean;
+    };
+    readonly selectNumber: (required: boolean) => {
+        type: "select-number";
+        required: boolean;
+    };
+    readonly multiText: (required: boolean) => {
+        type: "multi-text";
+        required: boolean;
+    };
+    readonly multiNumber: (required: boolean) => {
+        type: "multi-number";
+        required: boolean;
+    };
+    readonly multiSelectText: (required: boolean) => {
+        type: "multi-select-text";
+        required: boolean;
+    };
+    readonly multiSelectNumber: (required: boolean) => {
+        type: "multi-select-number";
+        required: boolean;
+    };
+};
+
+export { type BaseFieldValueType, DocClient, type DocClientConfig, type DocCustomSchema, type DocCustomSchemaField, type DocCustomSchemaFieldBoolean, type DocCustomSchemaFieldMultiNumber, type DocCustomSchemaFieldMultiRelation, type DocCustomSchemaFieldMultiSelectNumber, type DocCustomSchemaFieldMultiSelectText, type DocCustomSchemaFieldMultiText, type DocCustomSchemaFieldNumber, type DocCustomSchemaFieldRelation, type DocCustomSchemaFieldSelectNumber, type DocCustomSchemaFieldSelectText, type DocCustomSchemaFieldText, type DocDirectory, DocDirectoryReference, type DocFieldTypeLiteral, type DocFile, type DocFileEntity, type DocFileIndex, type DocFileIndexContent, DocFileIndexEntity, type DocFileIndexMeta, DocFileIndexReference, type DocFileIndexSchema, type DocFileIndexSchemaField, type DocFileMd, type DocFileMdContent, DocFileMdEntity, type DocFileMdMeta, DocFileMdReference, type DocFilePath, DocFileRelationReference, DocFileSystem, DocFileSystemDebug, type DocFileUnknown, DocFileUnknownEntity, DocFileUnknownReference, DocMarkdownSystem, type DocMetaField, type DocMetaFieldBoolean, type DocMetaFieldMultiBoolean, type DocMetaFieldMultiNumber, type DocMetaFieldMultiRelation, type DocMetaFieldMultiSelectNumber, type DocMetaFieldMultiSelectText, type DocMetaFieldMultiText, type DocMetaFieldNumber, type DocMetaFieldRelation, type DocMetaFieldSelectNumber, type DocMetaFieldSelectText, type DocMetaFieldText, type DocMetaFieldType, type DocMetaFieldTypeBoolean, type DocMetaFieldTypeNumber, type DocMetaFieldTypeRelation, type DocMetaFieldTypeSelectNumber, type DocMetaFieldTypeSelectText, type DocMetaFieldTypeText, DocPathSystem, type DocRelation, type DocRelationField, type DocRelationFile, type DocSchemaFieldBoolean, type DocSchemaFieldMultiNumber, type DocSchemaFieldMultiRelation, type DocSchemaFieldMultiSelectNumber, type DocSchemaFieldMultiSelectText, type DocSchemaFieldMultiText, type DocSchemaFieldNumber, type DocSchemaFieldRelation, type DocSchemaFieldSelectNumber, type DocSchemaFieldSelectText, type DocSchemaFieldText, type DocSchemaRelationFieldUnion, type DocTreeDirectoryNode, type DocTreeFileNode, type DocTreeNode, type Equals, type ExtractFieldType, type ExtractIndexFieldType, type ExtractRequired, type FieldValueType, DocFileTreeSystem as FileTreeSystem, type GetIndexFieldType, type GetIndexFieldValueType, type GetValueType, type InferDocFileMd, type MultiRelationKeys, type OptionalKeys, type RecordKey, type RelationKeys, type RequiredKeys, SchemaBuilder, type SchemaToValueType, assertType, defaultTestConfig, defineSchema, docCustomSchemaField, expectType, zDocClientConfig, zDocFileIndexSchemaField, zDocFilePath, zDocFileUnknown, zDocMetaField, zDocMetaFieldBoolean, zDocMetaFieldMultiBoolean, zDocMetaFieldMultiNumber, zDocMetaFieldMultiRelation, zDocMetaFieldMultiSelectNumber, zDocMetaFieldMultiSelectText, zDocMetaFieldMultiText, zDocMetaFieldNumber, zDocMetaFieldRelation, zDocMetaFieldSelectNumber, zDocMetaFieldSelectText, zDocMetaFieldText, zDocMetaFieldType, zDocMetaFieldTypeBoolean, zDocMetaFieldTypeNumber, zDocMetaFieldTypeRelation, zDocMetaFieldTypeSelectNumber, zDocMetaFieldTypeSelectText, zDocMetaFieldTypeText, zDocRelation, zDocRelationField, zDocRelationFile, zDocSchemaFieldBoolean, zDocSchemaFieldMultiNumber, zDocSchemaFieldMultiRelation, zDocSchemaFieldMultiSelectNumber, zDocSchemaFieldMultiSelectText, zDocSchemaFieldMultiText, zDocSchemaFieldNumber, zDocSchemaFieldRelation, zDocSchemaFieldSelectNumber, zDocSchemaFieldSelectText, zDocSchemaFieldText };

package/build/index.js

@@ -1269,6 +1269,24 @@ var DocFileMdMetaValue = class _DocFileMdMetaValue {
       this.customSchema
     );
   }
+  /**
+   * Return a new instance with an unknown schema
+   * Allows accepting Record<string, unknown> schemas from external sources
+   */
+  withUnknownSchema(draft) {
+    const typedSchema = draft;
+    const newValue = {};
+    for (const key in typedSchema) {
+      if (key in this.value) {
+        const unknownValue = this.value;
+        newValue[key] = unknownValue[key];
+      }
+    }
+    return new _DocFileMdMetaValue(
+      newValue,
+      typedSchema
+    );
+  }
   schemaField(key) {
     const field = this.customSchema[key];
     if (field === void 0) {
@@ -2854,6 +2872,23 @@ var DocFileIndexMetaValue = class _DocFileIndexMetaValue {
       this.additionalProperties
     );
   }
+  /**
+   * Return a new instance with an unknown schema
+   * Allows accepting Record<string, unknown> schemas from external sources
+   */
+  withUnknownSchema(draft) {
+    const typedSchema = draft;
+    return new _DocFileIndexMetaValue(
+      {
+        type: "index-meta",
+        icon: this.value.icon,
+        schema: typedSchema
+      },
+      {},
+      this.config,
+      this.additionalProperties
+    );
+  }
   /**
    * Output in JSON format
    */
@@ -5271,6 +5306,167 @@ var DocFileSystemDebug = class _DocFileSystemDebug extends DocFileSystem {
     }
   }
 };
+
+// lib/schema-builder.ts
+var SchemaBuilder = class _SchemaBuilder {
+  constructor(schema = {}) {
+    this.schema = schema;
+  }
+  text(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "text", required }
+    });
+  }
+  number(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "number", required }
+    });
+  }
+  boolean(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "boolean", required }
+    });
+  }
+  relation(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "relation", required }
+    });
+  }
+  multiRelation(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "multi-relation", required }
+    });
+  }
+  selectText(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "select-text", required }
+    });
+  }
+  selectNumber(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "select-number", required }
+    });
+  }
+  multiText(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "multi-text", required }
+    });
+  }
+  multiNumber(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "multi-number", required }
+    });
+  }
+  multiSelectText(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "multi-select-text", required }
+    });
+  }
+  multiSelectNumber(key, required) {
+    return new _SchemaBuilder({
+      ...this.schema,
+      [key]: { type: "multi-select-number", required }
+    });
+  }
+  build() {
+    return this.schema;
+  }
+};
+
+// lib/utils.ts
+function expectType(_value) {
+}
+function assertType() {
+}
+var defaultTestConfig = {
+  defaultIndexIcon: "\u{1F4C1}",
+  indexFileName: "index.md",
+  archiveDirectoryName: "_",
+  defaultDirectoryName: "Directory",
+  indexMetaIncludes: [],
+  directoryExcludes: [".vitepress"]
+};
+function defineSchema(schema) {
+  return schema;
+}
+var docCustomSchemaField = {
+  text(required) {
+    return {
+      type: "text",
+      required
+    };
+  },
+  number(required) {
+    return {
+      type: "number",
+      required
+    };
+  },
+  boolean(required) {
+    return {
+      type: "boolean",
+      required
+    };
+  },
+  relation(required) {
+    return {
+      type: "relation",
+      required
+    };
+  },
+  multiRelation(required) {
+    return {
+      type: "multi-relation",
+      required
+    };
+  },
+  selectText(required) {
+    return {
+      type: "select-text",
+      required
+    };
+  },
+  selectNumber(required) {
+    return {
+      type: "select-number",
+      required
+    };
+  },
+  multiText(required) {
+    return {
+      type: "multi-text",
+      required
+    };
+  },
+  multiNumber(required) {
+    return {
+      type: "multi-number",
+      required
+    };
+  },
+  multiSelectText(required) {
+    return {
+      type: "multi-select-text",
+      required
+    };
+  },
+  multiSelectNumber(required) {
+    return {
+      type: "multi-select-number",
+      required
+    };
+  }
+};
 export {
   DocClient,
   DocDirectoryReference,
@@ -5286,6 +5482,12 @@ export {
   DocMarkdownSystem,
   DocPathSystem,
   DocFileTreeSystem as FileTreeSystem,
+  SchemaBuilder,
+  assertType,
+  defaultTestConfig,
+  defineSchema,
+  docCustomSchemaField,
+  expectType,
   zDocClientConfig,
   zDocCustomSchema,
   zDocCustomSchemaField,

package/debug/debug.ts

@@ -1,17 +1,19 @@
 import { DocClient } from "@/doc-client"
 import { DocFileSystem } from "@/doc-file-system"
+import { SchemaBuilder } from "@/schema-builder"
+import { defineSchema, docCustomSchemaField } from "@/utils"
 
 const client = new DocClient({
   fileSystem: new DocFileSystem({ basePath: "../../docs" }),
 })
 
-const pagesRef = client.directory("docs-studio/pages", {
-  features: {
-    type: "multi-relation",
-    required: true,
-  },
+// Method 1: Using defineSchema (recommended)
+const pageSchema = defineSchema({
+  features: docCustomSchemaField.multiRelation(true),
 })
 
+const pagesRef = client.directory("docs-studio/pages", pageSchema)
+
 const mdFileRef = await pagesRef.mdFile("document-editor")
 
 const mdFile = await mdFileRef.read()
@@ -20,6 +22,8 @@ if (mdFile instanceof Error) {
   throw mdFile
 }
 
+const _features = mdFile.content.meta().field("features")
+
 mdFile.withContent(
   mdFile.content.withMetaProperty("features", [
     "edit-document-content",
@@ -28,13 +32,31 @@ mdFile.withContent(
   ]),
 )
 
-const relations = await mdFileRef.relations("features", {
-  "is-done": {
-    required: true,
-    type: "boolean",
-  },
+// Method 2: Using field helpers
+const featureSchema = defineSchema({
+  "is-done": docCustomSchemaField.boolean(true),
 })
 
+const relations = await mdFileRef.relations("features", featureSchema)
+
 const file = await relations[0].read()
 
 console.log("relations", file)
+
+// Method 3: Using SchemaBuilder
+const fooSchema = new SchemaBuilder()
+  .multiRelation("feature", true)
+  .text("priority", false)
+  .build()
+
+const fooRef = client.directory("docs-studio/files", fooSchema)
+
+const aaa = await fooRef.mdFile("a")
+
+const fooFile = await aaa.read()
+
+if (fooFile instanceof Error) {
+  throw fooFile
+}
+
+fooFile.content.meta().field("feature")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/docs-client",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "scripts": {
     "check": "tsgo --noEmit",