TypeScript SDK

The official TypeScript/JavaScript client for HX-SDP. Full type safety, browser and Node.js compatible.

Status: Coming Soon

The TypeScript SDK is under active development. This page documents the planned API surface. Star the repository to be notified on release.

Installation

npm install @holonomix/sdk
# or
yarn add @holonomix/sdk

Quick start

import { HolonomiXClient } from "@holonomix/sdk";

const hx = new HolonomiXClient({
  baseUrl: "https://gate.holonomx.com",
  apiKey: "hx_live_...",
});

// Store
const result = await hx.put("my-key", new Float64Array(4096), {
  metadata: { source: "sensor" },
});
console.log(`Compressed ${result.compressionRatio}x`);

// Retrieve
const info = await hx.get("my-key");
console.log(`${info.nCores} cores`);

// Top-K search
const top = await hx.queryTopK("my-key", { k: 5 });
for (const [key, score] of top.results) {
  console.log(`  ${key}: ${score.toFixed(4)}`);
}

Constructor

new HolonomiXClient(options: {
  baseUrl: string;         // HX-Gate or HX-Engine URL
  apiKey: string;          // Tenant API key
  namespace?: string;      // Default namespace (default: "default")
  timeout?: number;        // Request timeout in ms (default: 30000)
})

Methods

put(key, data, options?) → Promise<PutResult>

interface PutOptions {
  metadata?: Record<string, unknown>;
  namespace?: string;
}

interface PutResult {
  key: string;
  namespace: string;
  version: number;
  compressed: boolean;
  verdict: "exact" | "safe" | "weak" | "passthrough";
  compressionRatio: number;
  originalBytes: number;
  storedCoreBytes: number;
  nCores: number;
}

get(key, options?) → Promise<GetResult>

interface GetOptions {
  namespace?: string;
  version?: number;
}

interface GetResult {
  key: string;
  namespace: string;
  version: number;
  oracleVerdict: string;
  compressionRatio: number;
  nCores: number;
  ranks: number[];
  maxRank: number;
  totalCoreBytes: number;
  originalBytes: number;
  metadata: Record<string, unknown>;
  fingerprint: Record<string, number>;
  createdAt: number;
}

query(keyA, keyB, options?) → Promise<QueryResult>

interface QueryOptions {
  metric?: "cosine" | "euclidean" | "dot";
  namespace?: string;
}

interface QueryResult {
  keyA: string;
  keyB: string;
  metric: string;
  score: number;
}

queryTopK(queryKey, options?) → Promise<TopKResult>

interface TopKOptions {
  k?: number;
  metric?: "cosine" | "euclidean" | "dot";
  namespace?: string;
  filters?: Record<string, unknown>;
}

interface TopKResult {
  queryKey: string;
  metric: string;
  nCandidates: number;
  results: [string, number][];
}

queryVector(data, options?) → Promise<TopKResult>

await hx.queryVector(new Float64Array(1024), { k: 5, metric: "cosine" });

search(filters, options?) → Promise<SearchResult>

interface SearchResult {
  namespace: string;
  results: Array<{ key: string; metadata: Record<string, unknown> }>;
  count: number;
}

serve(key, options?) → Promise<ServeResult>

interface ServeOptions {
  namespace?: string;
  version?: number;
}

interface ServeResult {
  key: string;
  namespace: string;
  version: number;
  data: Float64Array;
}

Error handling

import { HolonomiXError } from "@holonomix/sdk";

try {
  await hx.get("nonexistent");
} catch (e) {
  if (e instanceof HolonomiXError) {
    console.error(e.statusCode, e.detail);
  }
}