@wiscale/velesdb-sdk 1.4.1 → 1.5.1

package/dist/index.mjs

@@ -25,6 +25,12 @@ var NotFoundError = class extends VelesDBError {
     this.name = "NotFoundError";
   }
 };
+var BackpressureError = class extends VelesDBError {
+  constructor(message = "Server backpressure: too many requests") {
+    super(message, "BACKPRESSURE");
+    this.name = "BackpressureError";
+  }
+};
 
 // src/backends/wasm.ts
 var WasmBackend = class {
@@ -56,6 +62,33 @@ var WasmBackend = class {
       throw new ConnectionError("WASM backend not initialized");
     }
   }
+  normalizeIdString(id) {
+    const trimmed = id.trim();
+    return /^\d+$/.test(trimmed) ? trimmed : null;
+  }
+  canonicalPayloadKeyFromResultId(id) {
+    if (typeof id === "bigint") {
+      return id.toString();
+    }
+    if (typeof id === "number") {
+      return String(Math.trunc(id));
+    }
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      return normalized.replace(/^0+(?=\d)/, "");
+    }
+    return String(this.toNumericId(id));
+  }
+  canonicalPayloadKey(id) {
+    if (typeof id === "number") {
+      return String(Math.trunc(id));
+    }
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      return normalized.replace(/^0+(?=\d)/, "");
+    }
+    return String(this.toNumericId(id));
+  }
   async createCollection(name, config) {
     this.ensureInitialized();
     if (this.collections.has(name)) {
@@ -121,9 +154,13 @@ var WasmBackend = class {
         "DIMENSION_MISMATCH"
       );
     }
-    collection.store.insert(BigInt(id), vector);
     if (doc.payload) {
-      collection.payloads.set(String(doc.id), doc.payload);
+      collection.store.insert_with_payload(BigInt(id), vector, doc.payload);
+    } else {
+      collection.store.insert(BigInt(id), vector);
+    }
+    if (doc.payload) {
+      collection.payloads.set(this.canonicalPayloadKey(doc.id), doc.payload);
     }
   }
   async insertBatch(collectionName, docs) {
@@ -142,14 +179,22 @@ var WasmBackend = class {
       }
     }
     collection.store.reserve(docs.length);
-    const batch = docs.map((doc) => [
-      BigInt(this.toNumericId(doc.id)),
-      Array.isArray(doc.vector) ? doc.vector : Array.from(doc.vector)
-    ]);
-    collection.store.insert_batch(batch);
+    const batch = [];
+    for (const doc of docs) {
+      const id = BigInt(this.toNumericId(doc.id));
+      const vector = doc.vector instanceof Float32Array ? doc.vector : new Float32Array(doc.vector);
+      if (doc.payload) {
+        collection.store.insert_with_payload(id, vector, doc.payload);
+      } else {
+        batch.push([id, Array.from(vector)]);
+      }
+    }
+    if (batch.length > 0) {
+      collection.store.insert_batch(batch);
+    }
     for (const doc of docs) {
       if (doc.payload) {
-        collection.payloads.set(String(doc.id), doc.payload);
+        collection.payloads.set(this.canonicalPayloadKey(doc.id), doc.payload);
       }
     }
   }
@@ -167,12 +212,43 @@ var WasmBackend = class {
       );
     }
     const k = options?.k ?? 10;
+    if (options?.sparseVector) {
+      const { indices, values } = this.sparseVectorToArrays(options.sparseVector);
+      if (queryVector.length > 0 && collection.config.dimension && collection.config.dimension > 0) {
+        const denseResults = collection.store.search(queryVector, k);
+        const sparseResults = collection.store.sparse_search(
+          new Uint32Array(indices),
+          new Float32Array(values),
+          k
+        );
+        const sparseArray = sparseResults;
+        const denseForFuse = denseResults.map(([id, score]) => [Number(id), score]);
+        const sparseForFuse = sparseArray.map((r) => [Number(r.doc_id), r.score]);
+        const fused = this.wasmModule.hybrid_search_fuse(denseForFuse, sparseForFuse, 60);
+        return fused.slice(0, k).map((r) => ({
+          id: String(r.doc_id),
+          score: r.score,
+          payload: collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.doc_id))
+        }));
+      } else {
+        const sparseResults = collection.store.sparse_search(
+          new Uint32Array(indices),
+          new Float32Array(values),
+          k
+        );
+        return sparseResults.map((r) => ({
+          id: String(r.doc_id),
+          score: r.score,
+          payload: collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.doc_id))
+        }));
+      }
+    }
     if (options?.filter) {
       const results = collection.store.search_with_filter(queryVector, k, options.filter);
       return results.map((r) => ({
         id: String(r.id),
         score: r.score,
-        payload: r.payload || collection.payloads.get(String(r.id))
+        payload: r.payload || collection.payloads.get(this.canonicalPayloadKeyFromResultId(r.id))
       }));
     }
     const rawResults = collection.store.search(queryVector, k);
@@ -182,7 +258,7 @@ var WasmBackend = class {
         id: stringId,
         score
       };
-      const payload = collection.payloads.get(stringId);
+      const payload = collection.payloads.get(this.canonicalPayloadKeyFromResultId(id));
       if (payload) {
         result.payload = payload;
       }
@@ -206,7 +282,7 @@ var WasmBackend = class {
     const numericId = this.toNumericId(id);
     const removed = collection.store.remove(BigInt(numericId));
     if (removed) {
-      collection.payloads.delete(String(id));
+      collection.payloads.delete(this.canonicalPayloadKey(id));
     }
     return removed;
   }
@@ -216,38 +292,140 @@ var WasmBackend = class {
     if (!collection) {
       throw new NotFoundError(`Collection '${collectionName}'`);
     }
-    const payload = collection.payloads.get(String(id));
-    if (!payload) {
+    const numericId = this.toNumericId(id);
+    const point = collection.store.get(BigInt(numericId));
+    if (!point) {
       return null;
     }
+    const payload = point.payload ?? collection.payloads.get(this.canonicalPayloadKey(numericId));
     return {
-      id,
-      vector: [],
-      // Not available in current WASM impl
+      id: String(point.id),
+      vector: Array.isArray(point.vector) ? point.vector : Array.from(point.vector),
       payload
     };
   }
   async textSearch(_collection, _query, _options) {
-    throw new VelesDBError(
-      "Text search is not supported in WASM backend. Use REST backend for BM25 search.",
-      "NOT_SUPPORTED"
-    );
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const k = _options?.k ?? 10;
+    const field = void 0;
+    const raw = collection.store.text_search(_query, k, field);
+    return raw.map((r) => {
+      if (Array.isArray(r)) {
+        const key2 = this.canonicalPayloadKeyFromResultId(r[0]);
+        return { id: String(r[0]), score: r[1], payload: collection.payloads.get(key2) };
+      }
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return { id: String(r.id), score: r.score, payload: r.payload ?? collection.payloads.get(key) };
+    });
   }
   async hybridSearch(_collection, _vector, _textQuery, _options) {
-    throw new VelesDBError(
-      "Hybrid search is not supported in WASM backend. Use REST backend for hybrid search.",
-      "NOT_SUPPORTED"
-    );
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const queryVector = _vector instanceof Float32Array ? _vector : new Float32Array(_vector);
+    const k = _options?.k ?? 10;
+    const vectorWeight = _options?.vectorWeight ?? 0.5;
+    const raw = collection.store.hybrid_search(queryVector, _textQuery, k, vectorWeight);
+    return raw.map((r) => {
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return {
+        id: String(r.id),
+        score: r.score,
+        payload: r.payload ?? collection.payloads.get(key)
+      };
+    });
   }
   async query(_collection, _queryString, _params, _options) {
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    const paramsVector = _params?.q;
+    if (!Array.isArray(paramsVector) && !(paramsVector instanceof Float32Array)) {
+      throw new VelesDBError(
+        "WASM query() expects params.q to contain the query embedding vector.",
+        "BAD_REQUEST"
+      );
+    }
+    const requestedK = _params?.k;
+    const k = typeof requestedK === "number" && Number.isInteger(requestedK) && requestedK > 0 ? requestedK : 10;
+    const raw = collection.store.query(
+      paramsVector instanceof Float32Array ? paramsVector : new Float32Array(paramsVector),
+      k
+    );
+    return {
+      results: raw.map((r) => ({
+        nodeId: r.nodeId ?? r.node_id,
+        vectorScore: r.vectorScore ?? r.vector_score ?? null,
+        graphScore: r.graphScore ?? r.graph_score ?? null,
+        fusedScore: r.fusedScore ?? r.fused_score ?? 0,
+        bindings: r.bindings ?? {},
+        columnData: r.columnData ?? r.column_data ?? null
+      })),
+      stats: {
+        executionTimeMs: 0,
+        strategy: "wasm-query",
+        scannedNodes: raw.length
+      }
+    };
+  }
+  async multiQuerySearch(_collection, _vectors, _options) {
+    this.ensureInitialized();
+    const collection = this.collections.get(_collection);
+    if (!collection) {
+      throw new NotFoundError(`Collection '${_collection}'`);
+    }
+    if (_vectors.length === 0) {
+      return [];
+    }
+    const numVectors = _vectors.length;
+    const dimension = collection.config.dimension ?? 0;
+    const flat = new Float32Array(numVectors * dimension);
+    _vectors.forEach((vector, idx) => {
+      const src = vector instanceof Float32Array ? vector : new Float32Array(vector);
+      flat.set(src, idx * dimension);
+    });
+    const strategy = _options?.fusion ?? "rrf";
+    if (strategy === "weighted") {
+      throw new VelesDBError(
+        "Fusion strategy 'weighted' is not supported in WASM backend.",
+        "NOT_SUPPORTED"
+      );
+    }
+    const raw = collection.store.multi_query_search(
+      flat,
+      numVectors,
+      _options?.k ?? 10,
+      strategy,
+      _options?.fusionParams?.k ?? 60
+    );
+    return raw.map((r) => {
+      if (Array.isArray(r)) {
+        const key2 = this.canonicalPayloadKeyFromResultId(r[0]);
+        return { id: String(r[0]), score: r[1], payload: collection.payloads.get(key2) };
+      }
+      const key = this.canonicalPayloadKeyFromResultId(r.id);
+      return { id: String(r.id), score: r.score, payload: r.payload ?? collection.payloads.get(key) };
+    });
+  }
+  async queryExplain(_queryString, _params) {
+    this.ensureInitialized();
     throw new VelesDBError(
-      "VelesQL queries are not supported in WASM backend. Use REST backend for query support.",
+      "Query explain is not supported in WASM backend. Use REST backend for EXPLAIN support.",
       "NOT_SUPPORTED"
     );
   }
-  async multiQuerySearch(_collection, _vectors, _options) {
+  async collectionSanity(_collection) {
+    this.ensureInitialized();
     throw new VelesDBError(
-      "Multi-query fusion is not supported in WASM backend. Use REST backend for MQF search.",
+      "Collection sanity endpoint is not supported in WASM backend. Use REST backend for diagnostics.",
       "NOT_SUPPORTED"
     );
   }
@@ -273,13 +451,25 @@ var WasmBackend = class {
     this.collections.clear();
     this._initialized = false;
   }
+  sparseVectorToArrays(sv) {
+    const indices = [];
+    const values = [];
+    for (const [k, v] of Object.entries(sv)) {
+      indices.push(Number(k));
+      values.push(v);
+    }
+    return { indices, values };
+  }
   toNumericId(id) {
     if (typeof id === "number") {
       return id;
     }
-    const parsed = parseInt(id, 10);
-    if (!isNaN(parsed)) {
-      return parsed;
+    const normalized = this.normalizeIdString(id);
+    if (normalized !== null) {
+      const parsed = Number(normalized);
+      if (Number.isSafeInteger(parsed)) {
+        return parsed;
+      }
     }
     let hash = 0;
     for (let i = 0; i < id.length; i++) {
@@ -343,6 +533,23 @@ var WasmBackend = class {
       "NOT_SUPPORTED"
     );
   }
+  // ========================================================================
+  // Sparse / PQ / Streaming (v1.5)
+  // ========================================================================
+  async trainPq(_collection, _options) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "PQ training is not available in WASM mode. Use REST backend for PQ training.",
+      "NOT_SUPPORTED"
+    );
+  }
+  async streamInsert(_collection, _docs) {
+    this.ensureInitialized();
+    throw new VelesDBError(
+      "Streaming insert is not available in WASM mode. Use REST backend for streaming.",
+      "NOT_SUPPORTED"
+    );
+  }
 };
 
 // src/backends/rest.ts
@@ -405,8 +612,10 @@ var RestBackend = class {
       return {};
     }
     const payload = data;
-    const code = typeof payload.code === "string" ? payload.code : void 0;
-    const messageField = payload.message ?? payload.error;
+    const nestedError = payload.error && typeof payload.error === "object" ? payload.error : void 0;
+    const codeField = nestedError?.code ?? payload.code;
+    const code = typeof codeField === "string" ? codeField : void 0;
+    const messageField = nestedError?.message ?? payload.message ?? payload.error;
     const message = typeof messageField === "string" ? messageField : void 0;
     return { code, message };
   }
@@ -436,6 +645,19 @@ var RestBackend = class {
     }
     return 0;
   }
+  parseRestPointId(id) {
+    if (typeof id !== "number" || !Number.isFinite(id) || id < 0 || !Number.isInteger(id) || id > Number.MAX_SAFE_INTEGER) {
+      throw new ValidationError(
+        `REST backend requires numeric u64-compatible IDs in JS safe integer range (0..${Number.MAX_SAFE_INTEGER}). Received: ${String(id)}`
+      );
+    }
+    return id;
+  }
+  isLikelyAggregationQuery(query) {
+    return /\bGROUP\s+BY\b|\bHAVING\b|\bCOUNT\s*\(|\bSUM\s*\(|\bAVG\s*\(|\bMIN\s*\(|\bMAX\s*\(/i.test(
+      query
+    );
+  }
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -524,13 +746,14 @@ var RestBackend = class {
   }
   async insert(collection, doc) {
     this.ensureInitialized();
+    const restId = this.parseRestPointId(doc.id);
     const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
     const response = await this.request(
       "POST",
       `/collections/${encodeURIComponent(collection)}/points`,
       {
         points: [{
-          id: doc.id,
+          id: restId,
           vector,
           payload: doc.payload
         }]
@@ -546,7 +769,7 @@ var RestBackend = class {
   async insertBatch(collection, docs) {
     this.ensureInitialized();
     const vectors = docs.map((doc) => ({
-      id: doc.id,
+      id: this.parseRestPointId(doc.id),
       vector: doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector,
       payload: doc.payload
     }));
@@ -562,18 +785,29 @@ var RestBackend = class {
       throw new VelesDBError(response.error.message, response.error.code);
     }
   }
+  sparseVectorToRestFormat(sv) {
+    const result = {};
+    for (const [k, v] of Object.entries(sv)) {
+      result[String(k)] = v;
+    }
+    return result;
+  }
   async search(collection, query, options) {
     this.ensureInitialized();
     const queryVector = query instanceof Float32Array ? Array.from(query) : query;
+    const body = {
+      vector: queryVector,
+      top_k: options?.k ?? 10,
+      filter: options?.filter,
+      include_vectors: options?.includeVectors ?? false
+    };
+    if (options?.sparseVector) {
+      body.sparse_vector = this.sparseVectorToRestFormat(options.sparseVector);
+    }
     const response = await this.request(
       "POST",
       `/collections/${encodeURIComponent(collection)}/search`,
-      {
-        vector: queryVector,
-        k: options?.k ?? 10,
-        filter: options?.filter,
-        include_vectors: options?.includeVectors ?? false
-      }
+      body
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -581,7 +815,7 @@ var RestBackend = class {
       }
       throw new VelesDBError(response.error.message, response.error.code);
     }
-    return response.data ?? [];
+    return response.data?.results ?? [];
   }
   async searchBatch(collection, searches) {
     this.ensureInitialized();
@@ -605,9 +839,10 @@ var RestBackend = class {
   }
   async delete(collection, id) {
     this.ensureInitialized();
+    const restId = this.parseRestPointId(id);
     const response = await this.request(
       "DELETE",
-      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(id))}`
+      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(restId))}`
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -619,9 +854,10 @@ var RestBackend = class {
   }
   async get(collection, id) {
     this.ensureInitialized();
+    const restId = this.parseRestPointId(id);
     const response = await this.request(
       "GET",
-      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(id))}`
+      `/collections/${encodeURIComponent(collection)}/points/${encodeURIComponent(String(restId))}`
     );
     if (response.error) {
       if (response.error.code === "NOT_FOUND") {
@@ -672,14 +908,18 @@ var RestBackend = class {
     }
     return response.data?.results ?? [];
   }
-  async query(collection, queryString, params, _options) {
+  async query(collection, queryString, params, options) {
     this.ensureInitialized();
+    const endpoint = this.isLikelyAggregationQuery(queryString) ? "/aggregate" : "/query";
     const response = await this.request(
       "POST",
-      "/query",
+      endpoint,
       {
         query: queryString,
-        params: params ?? {}
+        params: params ?? {},
+        collection,
+        timeout_ms: options?.timeoutMs,
+        stream: options?.stream ?? false
       }
     );
     if (response.error) {
@@ -689,6 +929,16 @@ var RestBackend = class {
       throw new VelesDBError(response.error.message, response.error.code);
     }
     const rawData = response.data;
+    if (rawData && Object.prototype.hasOwnProperty.call(rawData, "result")) {
+      return {
+        result: rawData.result,
+        stats: {
+          executionTimeMs: rawData.timing_ms ?? 0,
+          strategy: "aggregation",
+          scannedNodes: 0
+        }
+      };
+    }
     return {
       results: (rawData?.results ?? []).map((r) => ({
         // Server returns `id` (u64), map to nodeId with precision handling
@@ -710,6 +960,82 @@ var RestBackend = class {
       }
     };
   }
+  async queryExplain(queryString, params) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "POST",
+      "/query/explain",
+      {
+        query: queryString,
+        params: params ?? {}
+      }
+    );
+    if (response.error) {
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    const data = response.data;
+    return {
+      query: data.query,
+      queryType: data.query_type,
+      collection: data.collection,
+      plan: data.plan.map((step) => ({
+        step: step.step,
+        operation: step.operation,
+        description: step.description,
+        estimatedRows: step.estimated_rows
+      })),
+      estimatedCost: {
+        usesIndex: data.estimated_cost.uses_index,
+        indexName: data.estimated_cost.index_name,
+        selectivity: data.estimated_cost.selectivity,
+        complexity: data.estimated_cost.complexity
+      },
+      features: {
+        hasVectorSearch: data.features.has_vector_search,
+        hasFilter: data.features.has_filter,
+        hasOrderBy: data.features.has_order_by,
+        hasGroupBy: data.features.has_group_by,
+        hasAggregation: data.features.has_aggregation,
+        hasJoin: data.features.has_join,
+        hasFusion: data.features.has_fusion,
+        limit: data.features.limit,
+        offset: data.features.offset
+      }
+    };
+  }
+  async collectionSanity(collection) {
+    this.ensureInitialized();
+    const response = await this.request(
+      "GET",
+      `/collections/${encodeURIComponent(collection)}/sanity`
+    );
+    if (response.error) {
+      if (response.error.code === "NOT_FOUND") {
+        throw new NotFoundError(`Collection '${collection}'`);
+      }
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    const data = response.data;
+    return {
+      collection: data.collection,
+      dimension: data.dimension,
+      metric: data.metric,
+      pointCount: data.point_count,
+      isEmpty: data.is_empty,
+      checks: {
+        hasVectors: data.checks.has_vectors,
+        searchReady: data.checks.search_ready,
+        dimensionConfigured: data.checks.dimension_configured
+      },
+      diagnostics: {
+        searchRequestsTotal: data.diagnostics.search_requests_total,
+        dimensionMismatchTotal: data.diagnostics.dimension_mismatch_total,
+        emptySearchResultsTotal: data.diagnostics.empty_search_results_total,
+        filterParseErrorsTotal: data.diagnostics.filter_parse_errors_total
+      },
+      hints: data.hints ?? []
+    };
+  }
   async multiQuerySearch(collection, vectors, options) {
     this.ensureInitialized();
     const formattedVectors = vectors.map(
@@ -723,6 +1049,9 @@ var RestBackend = class {
         top_k: options?.k ?? 10,
         strategy: options?.fusion ?? "rrf",
         rrf_k: options?.fusionParams?.k ?? 60,
+        avg_weight: options?.fusionParams?.avgWeight,
+        max_weight: options?.fusionParams?.maxWeight,
+        hit_weight: options?.fusionParams?.hitWeight,
         filter: options?.filter
       }
     );
@@ -761,6 +1090,81 @@ var RestBackend = class {
       throw new VelesDBError(response.error.message, response.error.code);
     }
   }
+  // ========================================================================
+  // Sparse / PQ / Streaming (v1.5)
+  // ========================================================================
+  async trainPq(collection, options) {
+    this.ensureInitialized();
+    const m = options?.m ?? 8;
+    const k = options?.k ?? 256;
+    const withClause = options?.opq ? `WITH (m=${m}, k=${k}, opq=true)` : `WITH (m=${m}, k=${k})`;
+    const queryString = `TRAIN QUANTIZER ON ${collection} ${withClause}`;
+    const response = await this.request(
+      "POST",
+      "/query",
+      { query: queryString }
+    );
+    if (response.error) {
+      throw new VelesDBError(response.error.message, response.error.code);
+    }
+    return response.data?.message ?? "PQ training initiated";
+  }
+  async streamInsert(collection, docs) {
+    this.ensureInitialized();
+    for (const doc of docs) {
+      const restId = this.parseRestPointId(doc.id);
+      const vector = doc.vector instanceof Float32Array ? Array.from(doc.vector) : doc.vector;
+      const body = {
+        id: restId,
+        vector,
+        payload: doc.payload
+      };
+      if (doc.sparseVector) {
+        body.sparse_vector = this.sparseVectorToRestFormat(doc.sparseVector);
+      }
+      const url = `${this.baseUrl}/collections/${encodeURIComponent(collection)}/stream/insert`;
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (this.apiKey) {
+        headers["Authorization"] = `Bearer ${this.apiKey}`;
+      }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.status === 429) {
+          throw new BackpressureError();
+        }
+        if (!response.ok && response.status !== 202) {
+          const data = await response.json().catch(() => ({}));
+          const errorPayload = this.extractErrorPayload(data);
+          throw new VelesDBError(
+            errorPayload.message ?? `HTTP ${response.status}`,
+            errorPayload.code ?? this.mapStatusToErrorCode(response.status)
+          );
+        }
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof BackpressureError || error instanceof VelesDBError) {
+          throw error;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new ConnectionError("Request timeout");
+        }
+        throw new ConnectionError(
+          `Stream insert failed: ${error instanceof Error ? error.message : "Unknown error"}`,
+          error instanceof Error ? error : void 0
+        );
+      }
+    }
+  }
   async close() {
     this._initialized = false;
   }
@@ -1077,6 +1481,18 @@ var VelesDB = class {
     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})`
+      );
+    }
+  }
+  validateRestPointId(id) {
+    if (this.config.backend === "rest" && (typeof id !== "number" || !Number.isInteger(id) || id < 0 || 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})`
+      );
+    }
   }
   /**
    * Search for similar vectors
@@ -1121,6 +1537,7 @@ var VelesDB = class {
    */
   async delete(collection, id) {
     this.ensureInitialized();
+    this.validateRestPointId(id);
     return this.backend.delete(collection, id);
   }
   /**
@@ -1132,6 +1549,7 @@ var VelesDB = class {
    */
   async get(collection, id) {
     this.ensureInitialized();
+    this.validateRestPointId(id);
     return this.backend.get(collection, id);
   }
   /**
@@ -1227,6 +1645,20 @@ 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) {
@@ -1239,9 +1671,39 @@ var VelesDB = class {
     }
     return this.backend.multiQuerySearch(collection, vectors, options);
   }
+  /**
+   * Train Product Quantization on a collection
+   *
+   * @param collection - Collection name
+   * @param options - PQ training options (m, k, opq)
+   * @returns Server response message
+   */
+  async trainPq(collection, options) {
+    this.ensureInitialized();
+    return this.backend.trainPq(collection, options);
+  }
+  /**
+   * Stream-insert documents with backpressure support
+   *
+   * Sends documents sequentially to respect server backpressure.
+   * Throws BackpressureError on 429 responses.
+   *
+   * @param collection - Collection name
+   * @param docs - Documents to insert
+   */
+  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);
+    }
+    await this.backend.streamInsert(collection, docs);
+  }
   /**
    * Check if a collection is empty
-   * 
+   *
    * @param collection - Collection name
    * @returns true if empty, false otherwise
    */
@@ -1739,6 +2201,7 @@ function velesql() {
   return new VelesQLBuilder();
 }
 export {
+  BackpressureError,
   ConnectionError,
   NotFoundError,
   RestBackend,