@h-ai/vecdb 0.1.0-alpha.66 → 0.1.0-alpha.68

package/dist/index.d.ts

@@ -5,21 +5,21 @@ import { HaiResult } from '@h-ai/core';
 /**
  * @h-ai/vecdb — 向量数据库配置 Schema
  *
- * 本文件定义向量数据库模块的错误码常量、Zod Schema 和配置类型。
+ * 本文件定义向量数据库模块的 Zod Schema 和配置类型；错误码见 vecdb-types。
  * 支持 LanceDB（默认）、pgvector、Qdrant、Chroma 四种后端。
  * @module vecdb-config
  */
 
 /**
- * 向量数据库类型枚举
+ * 向量数据库类型
+ * @example
+ * ```ts
+ * import type { VecdbType } from '@h-ai/vecdb'
  *
- * 支持的向量数据库类型：
- * - `lancedb` — LanceDB 嵌入式向量数据库（默认）
- * - `pgvector` — PostgreSQL + pgvector 扩展
- * - `qdrant` — Qdrant 向量搜索引擎
- * - `chroma` — Chroma 向量数据库（支持嵌入式自动拉起本地服务）
+ * const value: VecdbType = 'qdrant'
+ * void value
+ * ```
  */
-/** 向量数据库类型 */
 type VecdbType = 'lancedb' | 'pgvector' | 'qdrant' | 'chroma';
 /**
  * 距离度量类型
@@ -27,14 +27,40 @@ type VecdbType = 'lancedb' | 'pgvector' | 'qdrant' | 'chroma';
  * - `cosine` — 余弦相似度（默认，适用于文本嵌入）
  * - `euclidean` — 欧氏距离（L2）
  * - `dot` — 内积（点积）
+ * @example
+ * ```ts
+ * import { DistanceMetricSchema } from '@h-ai/vecdb'
+ *
+ * const value = DistanceMetricSchema.parse('cosine')
+ * void value
+ * ```
  */
 declare const DistanceMetricSchema: z.ZodDefault<z.ZodEnum<{
     cosine: "cosine";
     euclidean: "euclidean";
     dot: "dot";
 }>>;
-/** 距离度量类型 */
+/**
+ * 距离度量类型
+ * @example
+ * ```ts
+ * import type { DistanceMetric } from '@h-ai/vecdb'
+ *
+ * const value: DistanceMetric = 'cosine'
+ * void value
+ * ```
+ */
 type DistanceMetric = z.infer<typeof DistanceMetricSchema>;
+/**
+ * 操作日志配置；read/write 默认关闭，长度和级别由 Schema 校验。
+ * @example
+ * ```ts
+ * import { VecdbOperationLogConfigSchema } from '@h-ai/vecdb'
+ *
+ * const value = VecdbOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 500, level: 'debug' })
+ * void value
+ * ```
+ */
 declare const VecdbOperationLogConfigSchema: z.ZodObject<{
     read: z.ZodDefault<z.ZodBoolean>;
     write: z.ZodDefault<z.ZodBoolean>;
@@ -45,15 +71,21 @@ declare const VecdbOperationLogConfigSchema: z.ZodObject<{
         trace: "trace";
     }>>;
 }, z.core.$strip>;
-type VecdbOperationLogConfig = z.infer<typeof VecdbOperationLogConfigSchema>;
 /**
- * LanceDB 配置 Schema
- *
+ * 已解析的操作日志配置，单位和默认值与 Schema 保持一致。
  * @example
  * ```ts
- * { type: 'lancedb', path: './data/vecdb' }
+ * import { VecdbOperationLogConfigSchema, type VecdbOperationLogConfig } from '@h-ai/vecdb'
+ *
+ * const value: VecdbOperationLogConfig = VecdbOperationLogConfigSchema.parse({})
+ * void value
  * ```
  */
+type VecdbOperationLogConfig = z.infer<typeof VecdbOperationLogConfigSchema>;
+/**
+ * LanceDB 配置 Schema
+ *
+ */
 declare const LancedbConfigSchema: z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
         read: z.ZodDefault<z.ZodBoolean>;
@@ -73,27 +105,24 @@ declare const LancedbConfigSchema: z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>;
-/** LanceDB 配置类型 */
-type LancedbConfig = z.infer<typeof LancedbConfigSchema>;
 /**
- * pgvector 配置 Schema
- *
+ * LanceDB 配置类型
  * @example
  * ```ts
- * // 使用连接字符串
- * { type: 'pgvector', url: 'postgres://user:pass@localhost:5432/mydb' }
- *
- * // 使用分开的字段
- * {
- *     type: 'pgvector',
- *     host: 'localhost',
- *     port: 5432,
- *     database: 'mydb',
- *     user: 'admin',
- *     password: 'secret'
+ * import { VecdbConfigSchema, type LancedbConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'lancedb', path: './data/vecdb' })
+ * if (parsed.type === 'lancedb') {
+ *   const config: LancedbConfig = parsed
+ *   void config
  * }
  * ```
  */
+type LancedbConfig = z.infer<typeof LancedbConfigSchema>;
+/**
+ * pgvector 配置 Schema
+ *
+ */
 declare const PgvectorConfigSchema: z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
         read: z.ZodDefault<z.ZodBoolean>;
@@ -123,16 +152,24 @@ declare const PgvectorConfigSchema: z.ZodObject<{
     }>>>;
     tablePrefix: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
-/** pgvector 配置类型 */
-type PgvectorConfig = z.infer<typeof PgvectorConfigSchema>;
 /**
- * Qdrant 配置 Schema
- *
+ * pgvector 配置类型
  * @example
  * ```ts
- * { type: 'qdrant', url: 'http://localhost:6333' }
+ * import { VecdbConfigSchema, type PgvectorConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'pgvector', host: 'db', database: 'shop' })
+ * if (parsed.type === 'pgvector') {
+ *   const config: PgvectorConfig = parsed
+ *   void config
+ * }
  * ```
  */
+type PgvectorConfig = z.infer<typeof PgvectorConfigSchema>;
+/**
+ * Qdrant 配置 Schema
+ *
+ */
 declare const QdrantConfigSchema: z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
         read: z.ZodDefault<z.ZodBoolean>;
@@ -153,7 +190,19 @@ declare const QdrantConfigSchema: z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>;
-/** Qdrant 配置类型 */
+/**
+ * Qdrant 配置类型
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type QdrantConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'qdrant', url: 'http://localhost:6333' })
+ * if (parsed.type === 'qdrant') {
+ *   const config: QdrantConfig = parsed
+ *   void config
+ * }
+ * ```
+ */
 type QdrantConfig = z.infer<typeof QdrantConfigSchema>;
 /**
  * Chroma 配置 Schema
@@ -163,14 +212,6 @@ type QdrantConfig = z.infer<typeof QdrantConfigSchema>;
  *   （持久化到 `path`），close 时关闭；数据落地本地目录，无需手动启动服务。
  * - **直连**：提供 `url`（或已运行的 host:port）时，直接连接已有 Chroma 服务，不拉起进程。
  *
- * @example
- * ```ts
- * // 嵌入式（自动拉起本地服务）
- * { type: 'chroma', path: './data/chroma' }
- *
- * // 直连已有服务
- * { type: 'chroma', url: 'http://localhost:8000' }
- * ```
  */
 declare const ChromaConfigSchema: z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
@@ -197,12 +238,31 @@ declare const ChromaConfigSchema: z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>;
-/** Chroma 配置类型 */
+/**
+ * Chroma 配置类型
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type ChromaConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'chroma', url: 'http://localhost:8000' })
+ * if (parsed.type === 'chroma') {
+ *   const config: ChromaConfig = parsed
+ *   void config
+ * }
+ * ```
+ */
 type ChromaConfig = z.infer<typeof ChromaConfigSchema>;
 /**
  * 统一向量数据库配置 Schema（判别联合体）
  *
  * 根据 `type` 字段区分不同向量数据库类型的配置。
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema } from '@h-ai/vecdb'
+ *
+ * const value = VecdbConfigSchema.parse({ type: 'qdrant', url: 'http://localhost:6333' })
+ * void value
+ * ```
  */
 declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
@@ -294,18 +354,43 @@ declare const VecdbConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         dot: "dot";
     }>>>;
 }, z.core.$strip>], "type">;
-/** 向量数据库配置类型（判别联合体） */
+/**
+ * 向量数据库配置类型（判别联合体）
+ * @example
+ * ```ts
+ * import { VecdbConfigSchema, type VecdbConfig } from '@h-ai/vecdb'
+ *
+ * const parsed = VecdbConfigSchema.parse({ type: 'qdrant', url: 'http://localhost:6333' })
+ * const config: VecdbConfig = parsed
+ * void config
+ * ```
+ */
 type VecdbConfig = z.infer<typeof VecdbConfigSchema>;
 /**
  * 向量数据库配置输入类型（用于 init 等入口）
  *
  * 说明：Zod 的 default 会让输入端字段可省略，但输出端字段为必填。
  * 因此对外 API（如 vecdb.init）更适合接收 VecdbConfigInput。
+ * @example
+ * ```ts
+ * import type { VecdbConfigInput } from '@h-ai/vecdb'
+ *
+ * const value: VecdbConfigInput = { type: 'qdrant', url: 'http://localhost:6333' }
+ * void value
+ * ```
  */
 type VecdbConfigInput = z.input<typeof VecdbConfigSchema>;
 
 /**
  * Vecdb 模块标准错误定义对象。
+ * @example
+ * ```ts
+ * import { HaiVecdbError } from '@h-ai/vecdb'
+ * import { err } from '@h-ai/core'
+ *
+ * const result = err(HaiVecdbError.COLLECTION_NOT_FOUND, 'Collection missing')
+ * if (!result.success) void result.error.code
+ * ```
  */
 declare const HaiVecdbError: {
     readonly CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
@@ -327,15 +412,12 @@ declare const HaiVecdbError: {
  * 向量文档接口
  *
  * 表示一条存入向量数据库的记录，包含向量、文本内容和元数据。
- *
  * @example
  * ```ts
- * const doc: VectorDocument = {
- *   id: 'doc-001',
- *   vector: [0.1, 0.2, 0.3, ...],
- *   content: '这是文档内容',
- *   metadata: { source: 'wiki', page: 1 },
- * }
+ * import type { VectorDocument } from '@h-ai/vecdb'
+ *
+ * const value: VectorDocument = { id: 'doc_1', vector: [0.1, 0.2, 0.3], content: 'Example text', metadata: { tenant: 'shop' } }
+ * void value
  * ```
  */
 interface VectorDocument {
@@ -350,20 +432,24 @@ interface VectorDocument {
 }
 /**
  * 向量搜索选项
- *
  * @example
  * ```ts
- * const options: VectorSearchOptions = {
- *   topK: 10,
- *   filter: { source: 'wiki' },
- *   minScore: 0.7,
- * }
+ * import type { VectorSearchOptions } from '@h-ai/vecdb'
+ *
+ * const value: VectorSearchOptions = { topK: 5, filter: { tenant: 'shop' }, minScore: 0.7 }
+ * void value
  * ```
  */
 interface VectorSearchOptions {
     /** 返回的最大结果数（默认 10） */
     topK?: number;
-    /** 元数据过滤条件（键值对，精确匹配） */
+    /**
+     * 元数据过滤，具体能力以 Provider 为准。
+     * LanceDB：顶层字面量键的 AND 精确匹配，仅支持 string、有限 number、boolean、null；
+     * 类型严格区分，null 不匹配缺失字段；空对象不筛选，不支持对象/数组/undefined。
+     * 条件在 topK 前执行，不支持的值返回 CONFIG_ERROR。其它后端不保证相同 null/复杂值语义。
+     * @example { tenant: 'acme', active: true, page: 1, removedAt: null }
+     */
     filter?: Record<string, unknown>;
     /** 最低相似度阈值（0-1，低于此值的结果将被过滤） */
     minScore?: number;
@@ -372,15 +458,12 @@ interface VectorSearchOptions {
  * 向量搜索结果
  *
  * 包含匹配的文档和相似度得分。
- *
  * @example
  * ```ts
- * const result: VectorSearchResult = {
- *   id: 'doc-001',
- *   score: 0.95,
- *   content: '匹配的文档内容',
- *   metadata: { source: 'wiki' },
- * }
+ * import type { VectorSearchResult } from '@h-ai/vecdb'
+ *
+ * const value: VectorSearchResult = { id: 'doc_1', score: 0.95, content: 'Example text', metadata: { tenant: 'shop' } }
+ * void value
  * ```
  */
 interface VectorSearchResult {
@@ -399,15 +482,12 @@ interface VectorSearchResult {
  * 集合信息接口
  *
  * 描述一个向量集合的元信息。
- *
  * @example
  * ```ts
- * const info: CollectionInfo = {
- *   name: 'docs',
- *   dimension: 1536,
- *   metric: 'cosine',
- *   count: 42,
- * }
+ * import type { CollectionInfo } from '@h-ai/vecdb'
+ *
+ * const value: CollectionInfo = { name: 'docs', dimension: 3, metric: 'cosine', count: 1 }
+ * void value
  * ```
  */
 interface CollectionInfo {
@@ -424,14 +504,15 @@ interface CollectionInfo {
  * 集合管理操作接口
  *
  * 通过 `vecdb.collection` 访问，管理向量集合的创建、删除和查询。
- *
  * @example
  * ```ts
- * // 创建集合
- * await vecdb.collection.create('my-docs', { dimension: 1536 })
+ * import type { CollectionOperations } from '@h-ai/vecdb'
  *
- * // 列出集合
- * const result = await vecdb.collection.list()
+ * async function read(operations: CollectionOperations) {
+ *   const result = await operations.list()
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
  * ```
  */
 interface CollectionOperations {
@@ -473,13 +554,12 @@ interface CollectionOperations {
 }
 /**
  * 集合创建选项
- *
  * @example
  * ```ts
- * const options: CollectionCreateOptions = {
- *   dimension: 1536,
- *   metric: 'cosine',
- * }
+ * import type { CollectionCreateOptions } from '@h-ai/vecdb'
+ *
+ * const value: CollectionCreateOptions = { dimension: 3, metric: 'cosine' }
+ * void value
  * ```
  */
 interface CollectionCreateOptions {
@@ -492,17 +572,15 @@ interface CollectionCreateOptions {
  * 向量操作接口
  *
  * 通过 `vecdb.vector` 访问，管理向量文档的增删改查和搜索。
- *
  * @example
  * ```ts
- * // 插入向量
- * await vecdb.vector.insert('my-docs', [
- *   { id: 'doc-1', vector: [...], content: '文档1' },
- *   { id: 'doc-2', vector: [...], content: '文档2' },
- * ])
- *
- * // 搜索向量
- * const result = await vecdb.vector.search('my-docs', queryVector, { topK: 5 })
+ * import type { VectorOperations } from '@h-ai/vecdb'
+ *
+ * async function read(operations: VectorOperations) {
+ *   const result = await operations.search('docs', [0.1, 0.2, 0.3], { topK: 5 })
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
  * ```
  */
 interface VectorOperations {
@@ -511,15 +589,19 @@ interface VectorOperations {
      *
      * @param collection - 集合名称
      * @param documents - 文档列表
-     * @returns 成功返回 ok(undefined)
+     * @returns 成功返回 ok(undefined)；LanceDB 已有 ID 保留不覆盖，同批重复 ID 返回 CONFIG_ERROR。
+     * Qdrant 成功前等待服务端应用写入。
+     * @example await vecdb.vector.insert('docs', [{ id: 'doc-1', vector: [1, 0] }])
      */
     insert: (collection: string, documents: VectorDocument[]) => Promise<HaiResult<void>>;
     /**
-     * 更新向量文档（按 id 匹配，整体替换）
+     * 插入或更新向量文档（按 id 匹配，整体替换）
      *
      * @param collection - 集合名称
-     * @param documents - 待更新的文档（id 必须已存在）
-     * @returns 成功返回 ok(undefined)
+     * @param documents - 待写入文档；已有 ID 更新，不存在的 ID 插入
+     * @returns 成功返回 ok(undefined)；LanceDB 缺少原子主键能力或同批重复 ID 返回 CONFIG_ERROR。
+     * Qdrant 成功前等待服务端应用写入。
+     * @example await vecdb.vector.upsert('docs', [{ id: 'doc-1', vector: [1, 0], content: 'updated' }])
      */
     upsert: (collection: string, documents: VectorDocument[]) => Promise<HaiResult<void>>;
     /**
@@ -528,6 +610,7 @@ interface VectorOperations {
      * @param collection - 集合名称
      * @param ids - 文档 ID 列表
      * @returns 成功返回 ok(undefined)
+     * Qdrant 成功前等待服务端应用删除。
      */
     delete: (collection: string, ids: string[]) => Promise<HaiResult<void>>;
     /**
@@ -537,6 +620,7 @@ interface VectorOperations {
      * @param vector - 查询向量
      * @param options - 搜索选项
      * @returns 搜索结果列表（按相似度降序排列）
+     * @example await vecdb.vector.search('docs', [1, 0], { topK: 5, filter: { tenant: 'acme', active: true } })
      */
     search: (collection: string, vector: number[], options?: VectorSearchOptions) => Promise<HaiResult<VectorSearchResult[]>>;
     /**
@@ -544,30 +628,26 @@ interface VectorOperations {
      *
      * @param collection - 集合名称
      * @returns 文档数量
+     * Qdrant 使用精确 count，不依赖集合信息的近似统计。
      */
     count: (collection: string) => Promise<HaiResult<number>>;
 }
 /**
  * 向量数据库服务接口（通过 `vecdb` 对象访问）
- *
  * @example
  * ```ts
  * import { vecdb } from '@h-ai/vecdb'
  *
- * // 初始化（LanceDB）
- * await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
- *
- * // 创建集合
- * await vecdb.collection.create('docs', { dimension: 1536 })
- *
- * // 插入向量
- * await vecdb.vector.insert('docs', [{ id: '1', vector: [...], content: '...' }])
- *
- * // 搜索
- * const result = await vecdb.vector.search('docs', queryVector, { topK: 5 })
- *
- * // 关闭
- * await vecdb.close()
+ * const initialized = await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await vecdb.collection.list()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await vecdb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 interface VecdbFunctions {
@@ -595,17 +675,24 @@ interface VecdbFunctions {
  * 向量库原始连接信息
  *
  * 由 `vecdb.rawConnection` 暴露，字段按后端类型填充。包含凭证，仅供同进程内集成使用。
+ * @example
+ * ```ts
+ * import type { VecdbConnection } from '@h-ai/vecdb'
+ *
+ * const value: VecdbConnection = { type: 'qdrant', url: 'http://localhost:6333' }
+ * void value
+ * ```
  */
 interface VecdbConnection {
     /** 后端类型 */
     type: VecdbConfig['type'];
-    /** 服务 URL（qdrant） */
+    /** 服务 URL（qdrant、chroma；Chroma 内嵌模式含实际本地端口） */
     url?: string;
-    /** API Key（qdrant） */
+    /** API Key / Bearer token（qdrant、chroma） */
     apiKey?: string;
-    /** 主机（pgvector） */
+    /** 主机（pgvector、chroma） */
     host?: string;
-    /** 端口（pgvector） */
+    /** 端口（pgvector、chroma） */
     port?: number;
     /** 数据库名（pgvector） */
     database?: string;
@@ -615,7 +702,7 @@ interface VecdbConnection {
     password?: string;
     /** 连接串（pgvector） */
     connectionString?: string;
-    /** 本地路径（lancedb） */
+    /** 本地持久化路径（lancedb 或内嵌 chroma） */
     path?: string;
 }
 
@@ -636,27 +723,20 @@ interface VecdbConnection {
  * - `vecdb.vector` - 向量操作（插入/搜索/删除）
  * - `vecdb.config` - 当前配置
  * - `vecdb.isInitialized` - 初始化状态
- *
  * @example
  * ```ts
  * import { vecdb } from '@h-ai/vecdb'
  *
- * // 初始化（LanceDB）
- * await vecdb.init({ type: 'lancedb', path: './data/vecdb' })
- *
- * // 集合操作
- * await vecdb.collection.create('docs', { dimension: 1536 })
- *
- * // 向量操作
- * await vecdb.vector.insert('docs', [
- *   { id: '1', vector: [...], content: '文档内容' },
- * ])
- *
- * // 搜索
- * const result = await vecdb.vector.search('docs', queryVector, { topK: 5 })
- *
- * // 关闭
- * await vecdb.close()
+ * const initialized = await vecdb.init({ type: 'qdrant', url: 'http://localhost:6333' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await vecdb.collection.list()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await vecdb.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 declare const vecdb: VecdbFunctions;