@wiscale/velesdb-sdk 1.6.0 → 1.7.0

package/README.md

@@ -2,9 +2,9 @@
 
 Official TypeScript SDK for [VelesDB](https://github.com/cyberlife-coder/VelesDB) -- the local-first vector database for AI and RAG. Sub-millisecond semantic search in Browser and Node.js.
 
-**v1.6.0** | Node.js >= 18 | Browser (WASM) | MIT License
+**v1.7.0** | Node.js >= 18 | Browser (WASM) | MIT License
 
-## What's New in v1.6.0
+## What's New in v1.7.0
 
 - **Agent Memory API** -- semantic, episodic, and procedural memory for AI agents (REST only)
 - **Graph collections** -- dedicated `createGraphCollection()` for knowledge graphs (REST only)

package/dist/index.d.mts

@@ -98,13 +98,13 @@ interface PqTrainOptions {
     opq?: boolean;
 }
 /** Fusion strategy for multi-query search */
-type FusionStrategy$1 = 'rrf' | 'average' | 'maximum' | 'weighted';
+type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted';
 /** Multi-query search options */
 interface MultiQuerySearchOptions {
     /** Number of results to return (default: 10) */
     k?: number;
     /** Fusion strategy (default: 'rrf') */
-    fusion?: FusionStrategy$1;
+    fusion?: FusionStrategy;
     /** Fusion parameters */
     fusionParams?: {
         /** RRF k parameter (default: 60) */
@@ -143,19 +143,12 @@ interface GraphEdge {
     /** Edge properties */
     properties?: Record<string, unknown>;
 }
-/** Request to add an edge to the graph */
-interface AddEdgeRequest {
-    /** Unique edge ID */
-    id: number;
-    /** Source node ID */
-    source: number;
-    /** Target node ID */
-    target: number;
-    /** Edge label (relationship type) */
-    label: string;
-    /** Edge properties (optional) */
-    properties?: Record<string, unknown>;
-}
+/**
+ * Request to add an edge to the graph.
+ * Structurally identical to GraphEdge — kept as a named alias for
+ * semantic clarity (input vs stored model).
+ */
+type AddEdgeRequest = GraphEdge;
 /** Response containing edges */
 interface EdgesResponse {
     /** List of edges */
@@ -740,6 +733,15 @@ declare class VelesDB {
      * ```
      */
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
+    /**
+     * Explain the execution plan for a VelesQL query without running it
+     *
+     * @param queryString - VelesQL query string to explain
+     * @param params - Optional query parameters (vectors, scalars)
+     * @returns Explain response with the query execution plan
+     */
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     /**
      * Multi-query fusion search combining results from multiple query vectors
      *
@@ -767,8 +769,6 @@ declare class VelesDB {
      * });
      * ```
      */
-    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
-    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     /**
      * Train Product Quantization on a collection
@@ -1154,10 +1154,9 @@ declare class RestBackend implements IVelesDBBackend {
  *
  * @packageDocumentation
  */
+
 /** Direction for relationship traversal */
 type RelDirection = 'outgoing' | 'incoming' | 'both';
-/** Fusion strategy for hybrid queries */
-type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted';
 /** Options for relationship patterns */
 interface RelOptions {
     direction?: RelDirection;
@@ -1325,4 +1324,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };

package/dist/index.d.ts

@@ -98,13 +98,13 @@ interface PqTrainOptions {
     opq?: boolean;
 }
 /** Fusion strategy for multi-query search */
-type FusionStrategy$1 = 'rrf' | 'average' | 'maximum' | 'weighted';
+type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted';
 /** Multi-query search options */
 interface MultiQuerySearchOptions {
     /** Number of results to return (default: 10) */
     k?: number;
     /** Fusion strategy (default: 'rrf') */
-    fusion?: FusionStrategy$1;
+    fusion?: FusionStrategy;
     /** Fusion parameters */
     fusionParams?: {
         /** RRF k parameter (default: 60) */
@@ -143,19 +143,12 @@ interface GraphEdge {
     /** Edge properties */
     properties?: Record<string, unknown>;
 }
-/** Request to add an edge to the graph */
-interface AddEdgeRequest {
-    /** Unique edge ID */
-    id: number;
-    /** Source node ID */
-    source: number;
-    /** Target node ID */
-    target: number;
-    /** Edge label (relationship type) */
-    label: string;
-    /** Edge properties (optional) */
-    properties?: Record<string, unknown>;
-}
+/**
+ * Request to add an edge to the graph.
+ * Structurally identical to GraphEdge — kept as a named alias for
+ * semantic clarity (input vs stored model).
+ */
+type AddEdgeRequest = GraphEdge;
 /** Response containing edges */
 interface EdgesResponse {
     /** List of edges */
@@ -740,6 +733,15 @@ declare class VelesDB {
      * ```
      */
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
+    /**
+     * Explain the execution plan for a VelesQL query without running it
+     *
+     * @param queryString - VelesQL query string to explain
+     * @param params - Optional query parameters (vectors, scalars)
+     * @returns Explain response with the query execution plan
+     */
+    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
+    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     /**
      * Multi-query fusion search combining results from multiple query vectors
      *
@@ -767,8 +769,6 @@ declare class VelesDB {
      * });
      * ```
      */
-    queryExplain(queryString: string, params?: Record<string, unknown>): Promise<ExplainResponse>;
-    collectionSanity(collection: string): Promise<CollectionSanityResponse>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
     /**
      * Train Product Quantization on a collection
@@ -1154,10 +1154,9 @@ declare class RestBackend implements IVelesDBBackend {
  *
  * @packageDocumentation
  */
+
 /** Direction for relationship traversal */
 type RelDirection = 'outgoing' | 'incoming' | 'both';
-/** Fusion strategy for hybrid queries */
-type FusionStrategy = 'rrf' | 'average' | 'maximum' | 'weighted';
 /** Options for relationship patterns */
 interface RelOptions {
     direction?: RelDirection;
@@ -1325,4 +1324,4 @@ declare class VelesQLBuilder {
  */
 declare function velesql(): VelesQLBuilder;
 
-export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy$1 as FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };
+export { type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregationQueryResponse, type BackendType, BackpressureError, type Collection, type CollectionConfig, type CollectionConfigResponse, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, ConnectionError, type CreateIndexOptions, type DegreeResponse, type DistanceMetric, type EdgesResponse, type EpisodicEvent, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GraphCollectionConfig, type GraphEdge, type GraphSchemaMode, type HnswParams, type IVelesDBBackend, type IndexInfo, type IndexType, type MultiQuerySearchOptions, type NearVectorOptions, NotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, type RelDirection, type RelOptions, RestBackend, type RestPointId, type SearchOptions, type SearchResult, type SemanticEntry, type SparseVector, type StorageMode, type TraversalResultItem, type TraversalStats, type TraverseRequest, type TraverseResponse, ValidationError, type VectorDocument, VelesDB, type VelesDBConfig, VelesDBError, VelesQLBuilder, WasmBackend, velesql };

package/dist/index.js

@@ -1659,6 +1659,24 @@ var AgentMemoryClient = class {
 };
 
 // src/client.ts
+function requireNonEmptyString(value, label) {
+  if (!value || typeof value !== "string") {
+    throw new ValidationError(`${label} must be a non-empty string`);
+  }
+}
+function requireVector(value, label) {
+  if (!value || !Array.isArray(value) && !(value instanceof Float32Array)) {
+    throw new ValidationError(`${label} must be an array or Float32Array`);
+  }
+}
+function validateDocsBatch(docs, validateDoc) {
+  if (!Array.isArray(docs)) {
+    throw new ValidationError("Documents must be an array");
+  }
+  for (const doc of docs) {
+    validateDoc(doc);
+  }
+}
 var VelesDB = class {
   /**
    * Create a new VelesDB client
@@ -1723,9 +1741,7 @@ var VelesDB = class {
    */
   async createCollection(name, config) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     const isMetadataOnly = config.collectionType === "metadata_only";
     if (!isMetadataOnly && (!config.dimension || config.dimension <= 0)) {
       throw new ValidationError("Dimension must be a positive integer for vector collections");
@@ -1747,9 +1763,7 @@ var VelesDB = class {
    */
   async createMetadataCollection(name) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     await this.backend.createCollection(name, { collectionType: "metadata_only" });
   }
   /**
@@ -1799,29 +1813,15 @@ var VelesDB = class {
    */
   async insertBatch(collection, docs) {
     this.ensureInitialized();
-    if (!Array.isArray(docs)) {
-      throw new ValidationError("Documents must be an array");
-    }
-    for (const doc of docs) {
-      this.validateDocument(doc);
-    }
+    validateDocsBatch(docs, (doc) => this.validateDocument(doc));
     await this.backend.insertBatch(collection, docs);
   }
   validateDocument(doc) {
     if (doc.id === void 0 || doc.id === null) {
       throw new ValidationError("Document ID is required");
     }
-    if (!doc.vector) {
-      throw new ValidationError("Document vector is required");
-    }
-    if (!Array.isArray(doc.vector) && !(doc.vector instanceof Float32Array)) {
-      throw new ValidationError("Vector must be an array or Float32Array");
-    }
-    if (this.config.backend === "rest" && (typeof doc.id !== "number" || !Number.isInteger(doc.id) || doc.id < 0 || doc.id > Number.MAX_SAFE_INTEGER)) {
-      throw new ValidationError(
-        `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
-      );
-    }
+    requireVector(doc.vector, "Vector");
+    this.validateRestPointId(doc.id);
   }
   validateRestPointId(id) {
     if (this.config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER)) {
@@ -1840,9 +1840,7 @@ var VelesDB = class {
    */
   async search(collection, query2, options) {
     this.ensureInitialized();
-    if (!query2 || !Array.isArray(query2) && !(query2 instanceof Float32Array)) {
-      throw new ValidationError("Query must be an array or Float32Array");
-    }
+    requireVector(query2, "Query");
     return this.backend.search(collection, query2, options);
   }
   /**
@@ -1858,9 +1856,7 @@ var VelesDB = class {
       throw new ValidationError("Searches must be an array");
     }
     for (const s of searches) {
-      if (!s.vector || !Array.isArray(s.vector) && !(s.vector instanceof Float32Array)) {
-        throw new ValidationError("Each search must have a vector (array or Float32Array)");
-      }
+      requireVector(s.vector, "Each search vector");
     }
     return this.backend.searchBatch(collection, searches);
   }
@@ -1898,9 +1894,7 @@ var VelesDB = class {
    */
   async textSearch(collection, query2, options) {
     this.ensureInitialized();
-    if (!query2 || typeof query2 !== "string") {
-      throw new ValidationError("Query must be a non-empty string");
-    }
+    requireNonEmptyString(query2, "Query");
     return this.backend.textSearch(collection, query2, options);
   }
   /**
@@ -1914,12 +1908,8 @@ var VelesDB = class {
    */
   async hybridSearch(collection, vector, textQuery, options) {
     this.ensureInitialized();
-    if (!vector || !Array.isArray(vector) && !(vector instanceof Float32Array)) {
-      throw new ValidationError("Vector must be an array or Float32Array");
-    }
-    if (!textQuery || typeof textQuery !== "string") {
-      throw new ValidationError("Text query must be a non-empty string");
-    }
+    requireVector(vector, "Vector");
+    requireNonEmptyString(textQuery, "Text query");
     return this.backend.hybridSearch(collection, vector, textQuery, options);
   }
   /**
@@ -1946,24 +1936,37 @@ var VelesDB = class {
    */
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
-    if (!collection || typeof collection !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
-    if (!queryString || typeof queryString !== "string") {
-      throw new ValidationError("Query string must be a non-empty string");
-    }
+    requireNonEmptyString(collection, "Collection name");
+    requireNonEmptyString(queryString, "Query string");
     return this.backend.query(collection, queryString, params, options);
   }
+  /**
+   * Explain the execution plan for a VelesQL query without running it
+   *
+   * @param queryString - VelesQL query string to explain
+   * @param params - Optional query parameters (vectors, scalars)
+   * @returns Explain response with the query execution plan
+   */
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    requireNonEmptyString(queryString, "Query string");
+    return this.backend.queryExplain(queryString, params);
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    requireNonEmptyString(collection, "Collection name");
+    return this.backend.collectionSanity(collection);
+  }
   /**
    * Multi-query fusion search combining results from multiple query vectors
-   * 
+   *
    * Ideal for RAG pipelines using Multiple Query Generation (MQG).
-   * 
+   *
    * @param collection - Collection name
    * @param vectors - Array of query vectors
    * @param options - Search options (k, fusion strategy, fusionParams, filter)
    * @returns Fused search results
-   * 
+   *
    * @example
    * ```typescript
    * // RRF fusion (default)
@@ -1972,7 +1975,7 @@ var VelesDB = class {
    *   fusion: 'rrf',
    *   fusionParams: { k: 60 }
    * });
-   * 
+   *
    * // Weighted fusion
    * const results = await db.multiQuerySearch('docs', [emb1, emb2], {
    *   k: 10,
@@ -1981,29 +1984,13 @@ var VelesDB = class {
    * });
    * ```
    */
-  async queryExplain(queryString, params) {
-    this.ensureInitialized();
-    if (!queryString || typeof queryString !== "string") {
-      throw new ValidationError("Query string must be a non-empty string");
-    }
-    return this.backend.queryExplain(queryString, params);
-  }
-  async collectionSanity(collection) {
-    this.ensureInitialized();
-    if (!collection || typeof collection !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
-    return this.backend.collectionSanity(collection);
-  }
   async multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
     if (!Array.isArray(vectors) || vectors.length === 0) {
       throw new ValidationError("Vectors must be a non-empty array");
     }
     for (const v of vectors) {
-      if (!Array.isArray(v) && !(v instanceof Float32Array)) {
-        throw new ValidationError("Each vector must be an array or Float32Array");
-      }
+      requireVector(v, "Each vector");
     }
     return this.backend.multiQuerySearch(collection, vectors, options);
   }
@@ -2029,12 +2016,7 @@ var VelesDB = class {
    */
   async streamInsert(collection, docs) {
     this.ensureInitialized();
-    if (!Array.isArray(docs)) {
-      throw new ValidationError("Documents must be an array");
-    }
-    for (const doc of docs) {
-      this.validateDocument(doc);
-    }
+    validateDocsBatch(docs, (doc) => this.validateDocument(doc));
     await this.backend.streamInsert(collection, docs);
   }
   /**
@@ -2244,9 +2226,7 @@ var VelesDB = class {
    */
   async createGraphCollection(name, config) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     await this.backend.createGraphCollection(name, config);
   }
   /**

package/dist/index.mjs

@@ -1613,6 +1613,24 @@ var AgentMemoryClient = class {
 };
 
 // src/client.ts
+function requireNonEmptyString(value, label) {
+  if (!value || typeof value !== "string") {
+    throw new ValidationError(`${label} must be a non-empty string`);
+  }
+}
+function requireVector(value, label) {
+  if (!value || !Array.isArray(value) && !(value instanceof Float32Array)) {
+    throw new ValidationError(`${label} must be an array or Float32Array`);
+  }
+}
+function validateDocsBatch(docs, validateDoc) {
+  if (!Array.isArray(docs)) {
+    throw new ValidationError("Documents must be an array");
+  }
+  for (const doc of docs) {
+    validateDoc(doc);
+  }
+}
 var VelesDB = class {
   /**
    * Create a new VelesDB client
@@ -1677,9 +1695,7 @@ var VelesDB = class {
    */
   async createCollection(name, config) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     const isMetadataOnly = config.collectionType === "metadata_only";
     if (!isMetadataOnly && (!config.dimension || config.dimension <= 0)) {
       throw new ValidationError("Dimension must be a positive integer for vector collections");
@@ -1701,9 +1717,7 @@ var VelesDB = class {
    */
   async createMetadataCollection(name) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     await this.backend.createCollection(name, { collectionType: "metadata_only" });
   }
   /**
@@ -1753,29 +1767,15 @@ var VelesDB = class {
    */
   async insertBatch(collection, docs) {
     this.ensureInitialized();
-    if (!Array.isArray(docs)) {
-      throw new ValidationError("Documents must be an array");
-    }
-    for (const doc of docs) {
-      this.validateDocument(doc);
-    }
+    validateDocsBatch(docs, (doc) => this.validateDocument(doc));
     await this.backend.insertBatch(collection, docs);
   }
   validateDocument(doc) {
     if (doc.id === void 0 || doc.id === null) {
       throw new ValidationError("Document ID is required");
     }
-    if (!doc.vector) {
-      throw new ValidationError("Document vector is required");
-    }
-    if (!Array.isArray(doc.vector) && !(doc.vector instanceof Float32Array)) {
-      throw new ValidationError("Vector must be an array or Float32Array");
-    }
-    if (this.config.backend === "rest" && (typeof doc.id !== "number" || !Number.isInteger(doc.id) || doc.id < 0 || doc.id > Number.MAX_SAFE_INTEGER)) {
-      throw new ValidationError(
-        `REST backend requires numeric u64-compatible document IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER})`
-      );
-    }
+    requireVector(doc.vector, "Vector");
+    this.validateRestPointId(doc.id);
   }
   validateRestPointId(id) {
     if (this.config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || id > Number.MAX_SAFE_INTEGER)) {
@@ -1794,9 +1794,7 @@ var VelesDB = class {
    */
   async search(collection, query2, options) {
     this.ensureInitialized();
-    if (!query2 || !Array.isArray(query2) && !(query2 instanceof Float32Array)) {
-      throw new ValidationError("Query must be an array or Float32Array");
-    }
+    requireVector(query2, "Query");
     return this.backend.search(collection, query2, options);
   }
   /**
@@ -1812,9 +1810,7 @@ var VelesDB = class {
       throw new ValidationError("Searches must be an array");
     }
     for (const s of searches) {
-      if (!s.vector || !Array.isArray(s.vector) && !(s.vector instanceof Float32Array)) {
-        throw new ValidationError("Each search must have a vector (array or Float32Array)");
-      }
+      requireVector(s.vector, "Each search vector");
     }
     return this.backend.searchBatch(collection, searches);
   }
@@ -1852,9 +1848,7 @@ var VelesDB = class {
    */
   async textSearch(collection, query2, options) {
     this.ensureInitialized();
-    if (!query2 || typeof query2 !== "string") {
-      throw new ValidationError("Query must be a non-empty string");
-    }
+    requireNonEmptyString(query2, "Query");
     return this.backend.textSearch(collection, query2, options);
   }
   /**
@@ -1868,12 +1862,8 @@ var VelesDB = class {
    */
   async hybridSearch(collection, vector, textQuery, options) {
     this.ensureInitialized();
-    if (!vector || !Array.isArray(vector) && !(vector instanceof Float32Array)) {
-      throw new ValidationError("Vector must be an array or Float32Array");
-    }
-    if (!textQuery || typeof textQuery !== "string") {
-      throw new ValidationError("Text query must be a non-empty string");
-    }
+    requireVector(vector, "Vector");
+    requireNonEmptyString(textQuery, "Text query");
     return this.backend.hybridSearch(collection, vector, textQuery, options);
   }
   /**
@@ -1900,24 +1890,37 @@ var VelesDB = class {
    */
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
-    if (!collection || typeof collection !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
-    if (!queryString || typeof queryString !== "string") {
-      throw new ValidationError("Query string must be a non-empty string");
-    }
+    requireNonEmptyString(collection, "Collection name");
+    requireNonEmptyString(queryString, "Query string");
     return this.backend.query(collection, queryString, params, options);
   }
+  /**
+   * Explain the execution plan for a VelesQL query without running it
+   *
+   * @param queryString - VelesQL query string to explain
+   * @param params - Optional query parameters (vectors, scalars)
+   * @returns Explain response with the query execution plan
+   */
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    requireNonEmptyString(queryString, "Query string");
+    return this.backend.queryExplain(queryString, params);
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    requireNonEmptyString(collection, "Collection name");
+    return this.backend.collectionSanity(collection);
+  }
   /**
    * Multi-query fusion search combining results from multiple query vectors
-   * 
+   *
    * Ideal for RAG pipelines using Multiple Query Generation (MQG).
-   * 
+   *
    * @param collection - Collection name
    * @param vectors - Array of query vectors
    * @param options - Search options (k, fusion strategy, fusionParams, filter)
    * @returns Fused search results
-   * 
+   *
    * @example
    * ```typescript
    * // RRF fusion (default)
@@ -1926,7 +1929,7 @@ var VelesDB = class {
    *   fusion: 'rrf',
    *   fusionParams: { k: 60 }
    * });
-   * 
+   *
    * // Weighted fusion
    * const results = await db.multiQuerySearch('docs', [emb1, emb2], {
    *   k: 10,
@@ -1935,29 +1938,13 @@ var VelesDB = class {
    * });
    * ```
    */
-  async queryExplain(queryString, params) {
-    this.ensureInitialized();
-    if (!queryString || typeof queryString !== "string") {
-      throw new ValidationError("Query string must be a non-empty string");
-    }
-    return this.backend.queryExplain(queryString, params);
-  }
-  async collectionSanity(collection) {
-    this.ensureInitialized();
-    if (!collection || typeof collection !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
-    return this.backend.collectionSanity(collection);
-  }
   async multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
     if (!Array.isArray(vectors) || vectors.length === 0) {
       throw new ValidationError("Vectors must be a non-empty array");
     }
     for (const v of vectors) {
-      if (!Array.isArray(v) && !(v instanceof Float32Array)) {
-        throw new ValidationError("Each vector must be an array or Float32Array");
-      }
+      requireVector(v, "Each vector");
     }
     return this.backend.multiQuerySearch(collection, vectors, options);
   }
@@ -1983,12 +1970,7 @@ var VelesDB = class {
    */
   async streamInsert(collection, docs) {
     this.ensureInitialized();
-    if (!Array.isArray(docs)) {
-      throw new ValidationError("Documents must be an array");
-    }
-    for (const doc of docs) {
-      this.validateDocument(doc);
-    }
+    validateDocsBatch(docs, (doc) => this.validateDocument(doc));
     await this.backend.streamInsert(collection, docs);
   }
   /**
@@ -2198,9 +2180,7 @@ var VelesDB = class {
    */
   async createGraphCollection(name, config) {
     this.ensureInitialized();
-    if (!name || typeof name !== "string") {
-      throw new ValidationError("Collection name must be a non-empty string");
-    }
+    requireNonEmptyString(name, "Collection name");
     await this.backend.createGraphCollection(name, config);
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "VelesDB TypeScript SDK: The Local Vector Database for AI & RAG. Microsecond semantic search in Browser & Node.js.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",