hyperspace-sdk-ts 2.0.0

package/README.md

@@ -0,0 +1,117 @@
+# HyperspaceDB TypeScript SDK
+
+Official TypeScript client for HyperspaceDB gRPC API.
+
+Use this SDK for:
+- collection lifecycle management
+- vector insert and search
+- high-throughput batched search (`searchBatch`)
+- bulk insertion (`batchInsert`)
+- advanced filtering and hybrid search
+- multi-tenant authentication headers (`x-api-key`, `x-hyperspace-user-id`)
+
+## Requirements
+
+- Node.js 18+
+- Running HyperspaceDB server (default gRPC endpoint: `localhost:50051`)
+
+## Installation
+
+```bash
+npm install hyperspace-sdk-ts
+```
+
+## Quick Start
+
+```ts
+import { HyperspaceClient } from "hyperspace-sdk-ts";
+
+async function main() {
+  const client = new HyperspaceClient("localhost:50051", "I_LOVE_HYPERSPACEDB");
+  const collection = "docs_ts";
+
+  await client.deleteCollection(collection).catch(() => {});
+  await client.createCollection(collection, 3, "cosine");
+
+  await client.insert(1, [0.1, 0.2, 0.3], { source: "demo" }, collection);
+  await client.insert(2, [0.2, 0.1, 0.4], { source: "demo" }, collection);
+
+  const results = await client.search([0.1, 0.2, 0.3], 5, collection);
+  console.log(results);
+
+  client.close();
+}
+
+main().catch(console.error);
+```
+
+## API Overview
+
+### `new HyperspaceClient(host?, apiKey?, userId?)`
+
+- `host`: gRPC endpoint, default `localhost:50051`
+- `apiKey`: optional API key
+- `userId`: optional tenant/user ID
+
+### `createCollection(name, dimension, metric)`
+
+Create a new collection.
+
+- `metric`: `"l2" | "cosine" | "poincare"`
+
+### `deleteCollection(name)`
+
+Delete collection and all its data.
+
+### `insert(id, vector, meta?, collection?, durability?)`
+
+Insert one vector. Accepts `number[]`, `Float32Array`, `Float64Array`.
+
+### `batchInsert(items, collection?, durability?)`
+
+Efficient bulk insertion.
+```ts
+await client.batchInsert([
+  { id: 10, vector: [0.1, 0.1, 0.1], metadata: { tag: "a" } },
+  { id: 11, vector: [0.2, 0.2, 0.2], metadata: { tag: "b" } }
+], "my_collection");
+```
+
+### `search(vector, topK, collection?, options?)`
+
+Run nearest-neighbor search. 
+Options include `filters`, `hybridQuery`, and `hybridAlpha`.
+
+```ts
+const results = await client.search(vector, 10, "coll", {
+  filters: [
+    { match: { key: "category", value: "electronics" } },
+    { range: { key: "price", gte: 100, lte: 500 } }
+  ],
+  hybridQuery: "latest smartphone",
+  hybridAlpha: 0.5
+});
+```
+
+### `searchBatch(vectors, topK, collection?)`
+
+Run multiple searches in one gRPC request to reduce RPC overhead.
+
+### `getDigest(collection?)`
+
+Retrieve collection stats and logical clock.
+
+### `close()`
+
+Close underlying gRPC channel.
+
+## Performance Notes
+
+- Prefer `searchBatch` and `batchInsert` for throughput-heavy services.
+- Reuse one client instance per process or worker.
+
+## Error Handling
+
+All methods reject on transport/protocol errors. Targets gRPC data plane operations.
+For control plane endpoints (`/api/*`), use regular HTTP requests to the server's HTTP port.
+

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+import { DurabilityLevel } from './proto/hyperspace_pb';
+export { DurabilityLevel };
+export interface Filter {
+    match?: {
+        key: string;
+        value: string;
+    };
+    range?: {
+        key: string;
+        gte?: number;
+        lte?: number;
+    };
+}
+export interface SearchResult {
+    id: number;
+    distance: number;
+    metadata: {
+        [key: string]: string;
+    };
+}
+export declare class HyperspaceClient {
+    private client;
+    private metadata;
+    private static toVectorList;
+    constructor(host?: string, apiKey?: string, userId?: string);
+    createCollection(name: string, dimension: number, metric: string): Promise<boolean>;
+    deleteCollection(name: string): Promise<boolean>;
+    insert(id: number, vector: number[] | Float32Array | Float64Array, meta?: {
+        [key: string]: string;
+    }, collection?: string, durability?: DurabilityLevel): Promise<boolean>;
+    batchInsert(items: {
+        id: number;
+        vector: number[] | Float32Array | Float64Array;
+        metadata?: {
+            [key: string]: string;
+        };
+    }[], collection?: string, durability?: DurabilityLevel): Promise<boolean>;
+    search(vector: number[] | Float32Array | Float64Array, topK: number, collection?: string, options?: {
+        filters?: Filter[];
+        hybridQuery?: string;
+        hybridAlpha?: number;
+    }): Promise<SearchResult[]>;
+    searchBatch(vectors: Array<number[] | Float32Array | Float64Array>, topK: number, collection?: string): Promise<SearchResult[][]>;
+    getDigest(collection?: string): Promise<{
+        logicalClock: number;
+        stateHash: number;
+        count: number;
+    }>;
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,241 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperspaceClient = exports.DurabilityLevel = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const hyperspace_grpc_pb_1 = require("./proto/hyperspace_grpc_pb");
+const hyperspace_pb_1 = require("./proto/hyperspace_pb");
+Object.defineProperty(exports, "DurabilityLevel", { enumerable: true, get: function () { return hyperspace_pb_1.DurabilityLevel; } });
+const hyperspace_pb = __importStar(require("./proto/hyperspace_pb")); // New, for direct access to types
+class HyperspaceClient {
+    static toVectorList(vector) {
+        if (Array.isArray(vector)) {
+            return vector;
+        }
+        return Array.from(vector);
+    }
+    constructor(host = 'localhost:50051', apiKey, userId) {
+        const options = {
+            'grpc.max_send_message_length': 64 * 1024 * 1024,
+            'grpc.max_receive_message_length': 64 * 1024 * 1024,
+            'grpc.keepalive_time_ms': 10000,
+            'grpc.keepalive_timeout_ms': 5000,
+            'grpc.keepalive_permit_without_calls': 1,
+            'grpc.http2.min_time_between_pings_ms': 10000,
+            'grpc.http2.min_ping_interval_without_data_ms': 5000,
+        };
+        this.client = new hyperspace_grpc_pb_1.DatabaseClient(host, grpc.credentials.createInsecure(), options);
+        this.metadata = new grpc.Metadata();
+        if (apiKey) {
+            this.metadata.add('x-api-key', apiKey);
+        }
+        if (userId) {
+            this.metadata.add('x-hyperspace-user-id', userId);
+        }
+    }
+    // ... (create/delete unchanged) ...
+    createCollection(name, dimension, metric) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.CreateCollectionRequest();
+            req.setName(name);
+            req.setDimension(dimension);
+            req.setMetric(metric);
+            this.client.createCollection(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(true);
+            });
+        });
+    }
+    deleteCollection(name) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.DeleteCollectionRequest();
+            req.setName(name);
+            this.client.deleteCollection(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(true);
+            });
+        });
+    }
+    insert(id, vector, meta, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.InsertRequest();
+            req.setId(id);
+            req.setVectorList(HyperspaceClient.toVectorList(vector));
+            if (meta) {
+                const map = req.getMetadataMap();
+                for (const k in meta)
+                    map.set(k, meta[k]);
+            }
+            req.setCollection(collection);
+            req.setOriginNodeId('');
+            req.setLogicalClock(0);
+            req.setDurability(durability);
+            this.client.insert(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(resp.getSuccess());
+            });
+        });
+    }
+    batchInsert(items, collection = '', durability = hyperspace_pb_1.DurabilityLevel.DEFAULT_LEVEL) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.BatchInsertRequest();
+            req.setCollection(collection);
+            req.setDurability(durability);
+            const vectors = items.map(item => {
+                const v = new hyperspace_pb_1.VectorData();
+                v.setId(item.id);
+                v.setVectorList(HyperspaceClient.toVectorList(item.vector));
+                if (item.metadata) {
+                    const map = v.getMetadataMap();
+                    for (const k in item.metadata)
+                        map.set(k, item.metadata[k]);
+                }
+                return v;
+            });
+            req.setVectorsList(vectors);
+            this.client.batchInsert(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(resp.getSuccess());
+            });
+        });
+    }
+    search(vector, topK, collection = '', options) {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.SearchRequest();
+            req.setVectorList(HyperspaceClient.toVectorList(vector));
+            req.setTopK(topK);
+            req.setCollection(collection);
+            if (options === null || options === void 0 ? void 0 : options.filters) {
+                const protoFilters = options.filters.map(f => {
+                    const pf = new hyperspace_pb.Filter();
+                    if (f.match) {
+                        const m = new hyperspace_pb.Match();
+                        m.setKey(f.match.key);
+                        m.setValue(f.match.value);
+                        pf.setMatch(m);
+                    }
+                    else if (f.range) {
+                        const r = new hyperspace_pb.Range();
+                        r.setKey(f.range.key);
+                        if (f.range.gte !== undefined)
+                            r.setGte(f.range.gte);
+                        if (f.range.lte !== undefined)
+                            r.setLte(f.range.lte);
+                        pf.setRange(r);
+                    }
+                    return pf;
+                });
+                req.setFiltersList(protoFilters);
+            }
+            if (options === null || options === void 0 ? void 0 : options.hybridQuery)
+                req.setHybridQuery(options.hybridQuery);
+            if ((options === null || options === void 0 ? void 0 : options.hybridAlpha) !== undefined)
+                req.setHybridAlpha(options.hybridAlpha);
+            this.client.search(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                const results = resp.getResultsList().map(r => {
+                    const metaMap = r.getMetadataMap();
+                    const meta = {};
+                    if (metaMap.getLength() > 0) {
+                        metaMap.forEach((entry, key) => {
+                            meta[key] = entry;
+                        });
+                    }
+                    return {
+                        id: r.getId(),
+                        distance: r.getDistance(),
+                        metadata: meta
+                    };
+                });
+                resolve(results);
+            });
+        });
+    }
+    searchBatch(vectors, topK, collection = '') {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb_1.BatchSearchRequest();
+            req.setSearchesList(vectors.map((vector) => {
+                const s = new hyperspace_pb_1.SearchRequest();
+                s.setVectorList(HyperspaceClient.toVectorList(vector));
+                s.setTopK(topK);
+                s.setCollection(collection);
+                return s;
+            }));
+            this.client.searchBatch(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                const batch = resp.getResponsesList().map((searchResp) => searchResp.getResultsList().map((r) => {
+                    const metaMap = r.getMetadataMap();
+                    const meta = {};
+                    if (metaMap.getLength() > 0) {
+                        metaMap.forEach((entry, key) => {
+                            meta[key] = entry;
+                        });
+                    }
+                    return {
+                        id: r.getId(),
+                        distance: r.getDistance(),
+                        metadata: meta
+                    };
+                }));
+                resolve(batch);
+            });
+        });
+    }
+    getDigest(collection = '') {
+        return new Promise((resolve, reject) => {
+            const req = new hyperspace_pb.DigestRequest();
+            req.setCollection(collection);
+            this.client.getDigest(req, this.metadata, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    logicalClock: resp.getLogicalClock(),
+                    stateHash: resp.getStateHash(),
+                    count: resp.getCount()
+                });
+            });
+        });
+    }
+    close() {
+        this.client.close();
+    }
+}
+exports.HyperspaceClient = HyperspaceClient;