@wiscale/velesdb-sdk 1.14.4 → 1.15.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.14.4** | Node.js >= 18 | Browser (WASM) | MIT License
+**v1.15.0** | Node.js >= 18 | Browser (WASM) | MIT License
 
 ## What's New in v1.14.2
 
@@ -430,6 +430,37 @@ const results = await db.multiQuerySearch('docs', [emb1, emb2], {
 
 > **Note:** WASM supports `rrf`, `average`, `maximum`. The `weighted` and `relative_score` strategies are REST-only.
 
+#### Named sparse indexes — `sparseIndexName` vs `sparseSearchNamed()`
+
+A collection can carry multiple sparse indexes (e.g. `splade_v2`, `bm25_titles`). The TypeScript SDK exposes two distinct APIs depending on whether you want a dense + sparse hybrid query or a pure sparse query against a named index.
+
+| API | Shape | Use when |
+|---|---|---|
+| `db.search(coll, denseVec, { sparseVector, sparseIndexName })` | dense + sparse hybrid against the named sparse index | You already have a dense embedding and want to combine it with a specific named sparse index in a single search call. The dense vector drives the primary candidate set; the named sparse index re-ranks. |
+| `db.sparseSearchNamed(coll, sparseVec, indexName, options?)` | pure sparse against a named index | You have only a sparse vector (e.g. SPLADE expansion, lexical query) and want to query a specific named sparse index directly. No dense component. |
+
+```typescript
+// Hybrid: dense + sparse via the splade_v2 named index
+const hybrid = await db.search('docs', denseEmbedding, {
+  k: 10,
+  sparseVector: { 42: 0.8, 99: 0.3 },
+  sparseIndexName: 'splade_v2',
+});
+
+// Pure sparse against the same named index
+const sparseOnly = await db.sparseSearchNamed(
+  'docs',
+  { 42: 0.8, 99: 0.3 },
+  'splade_v2',
+  { k: 10 },
+);
+```
+
+When the collection has only one (default) sparse index, omit `sparseIndexName` on `db.search()`; the server picks the default. For named indexes, both APIs require the explicit name.
+
+> **Note:** Both APIs are REST-only when a named index is required.
+> The WASM backend has no concept of named sparse indexes — `sparseIndexName` is silently ignored on `db.search()` (the collection's single sparse index is used), and `db.sparseSearchNamed()` throws `wasmNotSupported`. Tracked as a follow-up to either surface a `wasmNotSupported` throw on `sparseIndexName` or implement named-sparse support in WASM.
+
 ---
 
 ### Collection Utilities

package/dist/index.d.mts

@@ -376,6 +376,30 @@ declare const f: {
  * @packageDocumentation
  */
 
+/**
+ * Options for `db.sparseSearchNamed()` — **pure sparse** query against a
+ * named sparse index (issue #380).
+ *
+ * Use this when you have only a sparse vector and want to query a specific
+ * named sparse index directly. The query carries no dense component.
+ *
+ * For **dense + sparse hybrid** against a named index, use
+ * `db.search(..., { sparseVector, sparseIndexName })` instead
+ * (see {@link SearchOptions.sparseIndexName}).
+ *
+ * **Backend support:** REST only. The WASM backend has no concept of named
+ * sparse indexes; this method throws `wasmNotSupported` on WASM.
+ */
+interface SparseSearchNamedOptions {
+    /** Number of results to return (default: 10) */
+    k?: number;
+    /** Filter expression */
+    filter?: FilterInput;
+    /** Optional dense vector to combine with sparse for hybrid named search */
+    vector?: number[] | Float32Array;
+    /** Search quality preset */
+    quality?: SearchQuality;
+}
 /** Search options */
 interface SearchOptions {
     /** Number of results to return (default: 10) */
@@ -386,6 +410,18 @@ interface SearchOptions {
     includeVectors?: boolean;
     /** Optional sparse vector for hybrid sparse+dense search */
     sparseVector?: SparseVector;
+    /**
+     * Named sparse index to combine with the dense query for **hybrid** search
+     * (when the collection has multiple sparse indexes). When omitted, the
+     * default sparse index is used.
+     *
+     * For a **pure sparse** query against a named index (no dense vector),
+     * call `db.sparseSearchNamed()` instead — see {@link SparseSearchNamedOptions}.
+     *
+     * **Backend support:** REST only. The WASM backend silently ignores this
+     * field and uses the collection's single sparse index regardless.
+     */
+    sparseIndexName?: string;
     /** Search quality preset (default: 'balanced'). */
     quality?: SearchQuality;
 }
@@ -1152,6 +1188,17 @@ interface IVelesDBBackend {
     traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /**
+     * Search a named sparse index (issue #380).
+     *
+     * Sends `sparse_vectors: { [indexName]: query }` and `sparse_index: indexName`
+     * to the `/search` endpoint. When `options.vector` is provided, the request
+     * also includes a dense vector for hybrid sparse+dense search against the
+     * named index.
+     *
+     * WASM backend: not supported (throws `VelesDB-WASM-NOT-SUPPORTED`).
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     /** Train Product Quantization on a collection */
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
     /** Stream-insert documents with backpressure support */
@@ -1322,6 +1369,13 @@ declare class VelesDB {
         filter?: FilterInput;
     }): Promise<SearchResult[]>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    /**
+     * Pure sparse search against a named sparse index.
+     *
+     * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+     * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(queryString: string, params?: Record<string, unknown>, options?: {
         analyze?: boolean;
@@ -1454,16 +1508,9 @@ declare class WasmBackend implements IVelesDBBackend {
     getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
 }
 
-/**
- * REST Backend for VelesDB
- *
- * Connects to VelesDB server via REST API.
- * This is the composition root that delegates to focused backend modules.
- * HTTP infrastructure lives in rest-http.ts.
- */
-
 /**
  * REST Backend
  *
@@ -1521,6 +1568,7 @@ declare class RestBackend implements IVelesDBBackend {
         id: number;
         score: number;
     }>>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(q: string, p?: Record<string, unknown>, o?: {
         analyze?: boolean;
@@ -1998,4 +2046,4 @@ type VelesErrorCode = (typeof VELES_ERROR_CODES)[number];
  */
 declare function parseVelesError(code: string | null | undefined, message: string): VelesError;
 
-export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };

package/dist/index.d.ts

@@ -376,6 +376,30 @@ declare const f: {
  * @packageDocumentation
  */
 
+/**
+ * Options for `db.sparseSearchNamed()` — **pure sparse** query against a
+ * named sparse index (issue #380).
+ *
+ * Use this when you have only a sparse vector and want to query a specific
+ * named sparse index directly. The query carries no dense component.
+ *
+ * For **dense + sparse hybrid** against a named index, use
+ * `db.search(..., { sparseVector, sparseIndexName })` instead
+ * (see {@link SearchOptions.sparseIndexName}).
+ *
+ * **Backend support:** REST only. The WASM backend has no concept of named
+ * sparse indexes; this method throws `wasmNotSupported` on WASM.
+ */
+interface SparseSearchNamedOptions {
+    /** Number of results to return (default: 10) */
+    k?: number;
+    /** Filter expression */
+    filter?: FilterInput;
+    /** Optional dense vector to combine with sparse for hybrid named search */
+    vector?: number[] | Float32Array;
+    /** Search quality preset */
+    quality?: SearchQuality;
+}
 /** Search options */
 interface SearchOptions {
     /** Number of results to return (default: 10) */
@@ -386,6 +410,18 @@ interface SearchOptions {
     includeVectors?: boolean;
     /** Optional sparse vector for hybrid sparse+dense search */
     sparseVector?: SparseVector;
+    /**
+     * Named sparse index to combine with the dense query for **hybrid** search
+     * (when the collection has multiple sparse indexes). When omitted, the
+     * default sparse index is used.
+     *
+     * For a **pure sparse** query against a named index (no dense vector),
+     * call `db.sparseSearchNamed()` instead — see {@link SparseSearchNamedOptions}.
+     *
+     * **Backend support:** REST only. The WASM backend silently ignores this
+     * field and uses the collection's single sparse index regardless.
+     */
+    sparseIndexName?: string;
     /** Search quality preset (default: 'balanced'). */
     quality?: SearchQuality;
 }
@@ -1152,6 +1188,17 @@ interface IVelesDBBackend {
     traverseParallel(collection: string, request: TraverseParallelRequest): Promise<TraverseResponse>;
     /** Get the in-degree and out-degree of a node */
     getNodeDegree(collection: string, nodeId: number): Promise<DegreeResponse>;
+    /**
+     * Search a named sparse index (issue #380).
+     *
+     * Sends `sparse_vectors: { [indexName]: query }` and `sparse_index: indexName`
+     * to the `/search` endpoint. When `options.vector` is provided, the request
+     * also includes a dense vector for hybrid sparse+dense search against the
+     * named index.
+     *
+     * WASM backend: not supported (throws `VelesDB-WASM-NOT-SUPPORTED`).
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     /** Train Product Quantization on a collection */
     trainPq(collection: string, options?: PqTrainOptions): Promise<string>;
     /** Stream-insert documents with backpressure support */
@@ -1322,6 +1369,13 @@ declare class VelesDB {
         filter?: FilterInput;
     }): Promise<SearchResult[]>;
     multiQuerySearch(collection: string, vectors: Array<number[] | Float32Array>, options?: MultiQuerySearchOptions): Promise<SearchResult[]>;
+    /**
+     * Pure sparse search against a named sparse index.
+     *
+     * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+     * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+     */
+    sparseSearchNamed(collection: string, query: SparseVector, indexName: string, options?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(collection: string, queryString: string, params?: Record<string, unknown>, options?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(queryString: string, params?: Record<string, unknown>, options?: {
         analyze?: boolean;
@@ -1454,16 +1508,9 @@ declare class WasmBackend implements IVelesDBBackend {
     getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
 }
 
-/**
- * REST Backend for VelesDB
- *
- * Connects to VelesDB server via REST API.
- * This is the composition root that delegates to focused backend modules.
- * HTTP infrastructure lives in rest-http.ts.
- */
-
 /**
  * REST Backend
  *
@@ -1521,6 +1568,7 @@ declare class RestBackend implements IVelesDBBackend {
         id: number;
         score: number;
     }>>;
+    sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
     query(c: string, q: string, p?: Record<string, unknown>, o?: QueryOptions): Promise<QueryApiResponse>;
     queryExplain(q: string, p?: Record<string, unknown>, o?: {
         analyze?: boolean;
@@ -1998,4 +2046,4 @@ type VelesErrorCode = (typeof VELES_ERROR_CODES)[number];
  */
 declare function parseVelesError(code: string | null | undefined, message: string): VelesError;
 
-export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };

package/dist/index.js

@@ -957,6 +957,9 @@ async function wasmMatchProceduralPatterns(_collection, _embedding, _k) {
 }
 
 // src/backends/wasm-wave4-stubs.ts
+function wasmSparseSearchNamed(_c, _q, _idx, _o) {
+  return Promise.resolve(wasmNotSupported("Named sparse index search"));
+}
 function wasmRebuildIndex(_c) {
   return Promise.resolve(wasmNotSupported("Index rebuild"));
 }
@@ -1404,6 +1407,10 @@ var WasmBackend = class {
     this.ensureInitialized();
     return wasmGraphSearch(c, r);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return wasmSparseSearchNamed(c, q, idx, o);
+  }
 };
 
 // src/backends/crud-backend.ts
@@ -1977,6 +1984,9 @@ async function search(transport, collection, query3, options) {
   if (options?.sparseVector) {
     body.sparse_vector = transport.sparseToRest(options.sparseVector);
   }
+  if (options?.sparseIndexName) {
+    body.sparse_index = options.sparseIndexName;
+  }
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/search`,
@@ -2042,12 +2052,33 @@ async function multiQuerySearch(transport, collection, vectors, options) {
       avg_weight: options?.fusionParams?.avgWeight,
       max_weight: options?.fusionParams?.maxWeight,
       hit_weight: options?.fusionParams?.hitWeight,
+      dense_weight: options?.fusionParams?.denseWeight,
+      sparse_weight: options?.fusionParams?.sparseWeight,
       filter: options?.filter
     }
   );
   throwOnError(response, `Collection '${collection}'`);
   return response.data?.results ?? [];
 }
+async function sparseSearchNamed(transport, collection, query3, indexName, options) {
+  const body = {
+    sparse_vectors: { [indexName]: transport.sparseToRest(query3) },
+    sparse_index: indexName,
+    top_k: options?.k ?? 10,
+    filter: options?.filter,
+    ...searchQualityToMode(options?.quality)
+  };
+  if (options?.vector) {
+    body.vector = Array.from(options.vector);
+  }
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search`,
+    body
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
 async function searchIds(transport, collection, query3, options) {
   const queryVector = toNumberArray(query3);
   const response = await transport.requestJson(
@@ -2735,6 +2766,10 @@ var RestBackend = class {
     this.ensureInitialized();
     return searchIds(buildSearchTransport(this.httpConfig), c, q, o);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return sparseSearchNamed(buildSearchTransport(this.httpConfig), c, q, idx, o);
+  }
   // Query
   async query(c, q, p, o) {
     this.ensureInitialized();
@@ -2941,6 +2976,11 @@ function hybridSearch2(backend, collection, vector, textQuery, options) {
   requireNonEmptyString(textQuery, "Text query");
   return backend.hybridSearch(collection, vector, textQuery, options);
 }
+function sparseSearchNamed2(backend, collection, query3, indexName, options) {
+  requireNonEmptyString(collection, "Collection name");
+  requireNonEmptyString(indexName, "Index name");
+  return backend.sparseSearchNamed(collection, query3, indexName, options);
+}
 function multiQuerySearch2(backend, collection, vectors, options) {
   if (!Array.isArray(vectors) || vectors.length === 0) {
     throw new ValidationError("Vectors must be a non-empty array");
@@ -3217,6 +3257,16 @@ var VelesDB = class {
     this.ensureInitialized();
     return multiQuerySearch2(this.backend, collection, vectors, options);
   }
+  /**
+   * Pure sparse search against a named sparse index.
+   *
+   * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+   * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+   */
+  async sparseSearchNamed(collection, query3, indexName, options) {
+    this.ensureInitialized();
+    return sparseSearchNamed2(this.backend, collection, query3, indexName, options);
+  }
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
     return query2(this.backend, collection, queryString, params, options);

package/dist/index.mjs

@@ -819,6 +819,9 @@ async function wasmMatchProceduralPatterns(_collection, _embedding, _k) {
 }
 
 // src/backends/wasm-wave4-stubs.ts
+function wasmSparseSearchNamed(_c, _q, _idx, _o) {
+  return Promise.resolve(wasmNotSupported("Named sparse index search"));
+}
 function wasmRebuildIndex(_c) {
   return Promise.resolve(wasmNotSupported("Index rebuild"));
 }
@@ -1266,6 +1269,10 @@ var WasmBackend = class {
     this.ensureInitialized();
     return wasmGraphSearch(c, r);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return wasmSparseSearchNamed(c, q, idx, o);
+  }
 };
 
 // src/backends/crud-backend.ts
@@ -1839,6 +1846,9 @@ async function search(transport, collection, query3, options) {
   if (options?.sparseVector) {
     body.sparse_vector = transport.sparseToRest(options.sparseVector);
   }
+  if (options?.sparseIndexName) {
+    body.sparse_index = options.sparseIndexName;
+  }
   const response = await transport.requestJson(
     "POST",
     `${collectionPath(collection)}/search`,
@@ -1904,12 +1914,33 @@ async function multiQuerySearch(transport, collection, vectors, options) {
       avg_weight: options?.fusionParams?.avgWeight,
       max_weight: options?.fusionParams?.maxWeight,
       hit_weight: options?.fusionParams?.hitWeight,
+      dense_weight: options?.fusionParams?.denseWeight,
+      sparse_weight: options?.fusionParams?.sparseWeight,
       filter: options?.filter
     }
   );
   throwOnError(response, `Collection '${collection}'`);
   return response.data?.results ?? [];
 }
+async function sparseSearchNamed(transport, collection, query3, indexName, options) {
+  const body = {
+    sparse_vectors: { [indexName]: transport.sparseToRest(query3) },
+    sparse_index: indexName,
+    top_k: options?.k ?? 10,
+    filter: options?.filter,
+    ...searchQualityToMode(options?.quality)
+  };
+  if (options?.vector) {
+    body.vector = Array.from(options.vector);
+  }
+  const response = await transport.requestJson(
+    "POST",
+    `${collectionPath(collection)}/search`,
+    body
+  );
+  throwOnError(response, `Collection '${collection}'`);
+  return response.data?.results ?? [];
+}
 async function searchIds(transport, collection, query3, options) {
   const queryVector = toNumberArray(query3);
   const response = await transport.requestJson(
@@ -2597,6 +2628,10 @@ var RestBackend = class {
     this.ensureInitialized();
     return searchIds(buildSearchTransport(this.httpConfig), c, q, o);
   }
+  async sparseSearchNamed(c, q, idx, o) {
+    this.ensureInitialized();
+    return sparseSearchNamed(buildSearchTransport(this.httpConfig), c, q, idx, o);
+  }
   // Query
   async query(c, q, p, o) {
     this.ensureInitialized();
@@ -2803,6 +2838,11 @@ function hybridSearch2(backend, collection, vector, textQuery, options) {
   requireNonEmptyString(textQuery, "Text query");
   return backend.hybridSearch(collection, vector, textQuery, options);
 }
+function sparseSearchNamed2(backend, collection, query3, indexName, options) {
+  requireNonEmptyString(collection, "Collection name");
+  requireNonEmptyString(indexName, "Index name");
+  return backend.sparseSearchNamed(collection, query3, indexName, options);
+}
 function multiQuerySearch2(backend, collection, vectors, options) {
   if (!Array.isArray(vectors) || vectors.length === 0) {
     throw new ValidationError("Vectors must be a non-empty array");
@@ -3079,6 +3119,16 @@ var VelesDB = class {
     this.ensureInitialized();
     return multiQuerySearch2(this.backend, collection, vectors, options);
   }
+  /**
+   * Pure sparse search against a named sparse index.
+   *
+   * @see {@link SparseSearchNamedOptions} for the full pure-sparse vs hybrid comparison.
+   * @see {@link VelesDB.search} for dense + sparse hybrid against a named index.
+   */
+  async sparseSearchNamed(collection, query3, indexName, options) {
+    this.ensureInitialized();
+    return sparseSearchNamed2(this.backend, collection, query3, indexName, options);
+  }
   async query(collection, queryString, params, options) {
     this.ensureInitialized();
     return query2(this.backend, collection, queryString, params, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wiscale/velesdb-sdk",
-  "version": "1.14.4",
+  "version": "1.15.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",
@@ -22,8 +22,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "format": "prettier --write src",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
@@ -54,15 +54,17 @@
     "url": "https://github.com/cyberlife-coder/VelesDB/issues"
   },
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
     "@types/node": "^25.6.0",
-    "@typescript-eslint/eslint-plugin": "^6.0.0",
-    "@typescript-eslint/parser": "^6.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
     "@vitest/coverage-v8": "^4.0.16",
-    "eslint": "^8.0.0",
-    "eslint-config-prettier": "^9.0.0",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.0.0",
     "vitest": "^4.0.16"
   },
   "dependencies": {