@anvailabs/proximadb-client 0.3.0

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * ProximaDB TypeScript SDK
+ *
+ * A modern, async-first TypeScript client for ProximaDB vector database.
+ *
+ * @example
+ * ```typescript
+ * import { connect, FilterBuilder } from "@proximadb/client";
+ *
+ * // Connect to ProximaDB
+ * const client = connect("http://localhost:5678");
+ *
+ * // Create a collection
+ * await client.createCollection("embeddings")
+ *   .dimension(768)
+ *   .engine(StorageEngine.Sst)
+ *   .execute();
+ *
+ * // Insert vectors
+ * await client.collection("embeddings")
+ *   .insert()
+ *   .id("vec_1")
+ *   .vector([0.1, 0.2, ...])
+ *   .meta("category", "tech")
+ *   .execute();
+ *
+ * // Search with filters
+ * const results = await client.collection("embeddings")
+ *   .search()
+ *   .vector(queryVector)
+ *   .topK(10)
+ *   .filterEq("category", "tech")
+ *   .execute();
+ *
+ * // Graph operations
+ * await client.createGraph("knowledge").execute();
+ * await client.graph("knowledge")
+ *   .addNode()
+ *   .id("person_1")
+ *   .label("Person")
+ *   .property("name", "Alice")
+ *   .execute();
+ * ```
+ *
+ * Copyright 2025 ProximaDB Contributors
+ * Licensed under the Apache License, Version 2.0
+ */
+
+// ============================================================================
+// VERSION
+// ============================================================================
+
+export const VERSION = "1.0.0";
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+// Enums (runtime values)
+export {
+  DistanceMetric,
+  StorageEngine,
+  IndexType,
+  FilterOp,
+  LogicalOp,
+  SearchMode,
+  TraversalDirection,
+  ErrorCode,
+  ProximaDBError,
+} from "./types";
+
+// Type-only exports (interfaces and types)
+export type {
+  ProximaRecord,
+  VectorRecord,
+  SearchResult,
+  CollectionConfig,
+  CollectionStats,
+  CollectionInfo,
+  HealthStatus,
+  Metadata,
+  MetadataValue,
+  JsonValue,
+  Filter,
+  FilterCondition,
+  FilterGroup,
+  FilterNode,
+  GraphNode,
+  GraphEdge,
+  TraversalResult,
+  GraphInfo,
+  ClientConfig,
+  SearchOptions,
+  InsertOptions,
+  UpdateOptions,
+  DeleteResult,
+  OperationMetrics,
+  SearchResultBatch,
+  SearchResultIterator,
+  ProbeResponse,
+  ColumnDefinition,
+  SchemaDefinition,
+  SchemaResponse,
+  UpdateSchemaRequest,
+  UpdateSchemaResponse,
+  QueryLanguage,
+  QueryRequest,
+  ExplainQueryRequest,
+  QueryResponse,
+} from "./types";
+
+// ============================================================================
+// CLIENT
+// ============================================================================
+
+export {
+  ProximaDBClient,
+  ClientBuilder,
+  connect,
+  connectRest,
+} from "./client";
+
+// ============================================================================
+// COLLECTION
+// ============================================================================
+
+export {
+  CollectionHandle,
+  CollectionBuilder,
+  InsertBuilder,
+  BatchInsertBuilder,
+  UpdateBuilder,
+} from "./collection";
+
+// ============================================================================
+// SEARCH
+// ============================================================================
+
+export {
+  SearchBuilder,
+  createSearchBuilder,
+} from "./search";
+
+// ============================================================================
+// FILTER
+// ============================================================================
+
+export {
+  FilterBuilder,
+  // Convenience functions
+  eq,
+  ne,
+  gt,
+  lt,
+  inList,
+  range,
+  andFilters,
+  orFilters,
+  filterToExpression,
+} from "./filter";
+
+// ============================================================================
+// GRAPH
+// ============================================================================
+
+export {
+  GraphHandle,
+  GraphBuilder,
+  NodeBuilder,
+  EdgeBuilder,
+  TraversalBuilder,
+  // Convenience functions
+  createNode,
+  node,
+  createEdge,
+  edge,
+} from "./graph";
+
+// ============================================================================
+// DEFAULT EXPORT
+// ============================================================================
+
+import { ProximaDBClient } from "./client";
+export default ProximaDBClient;

package/src/search.ts

@@ -0,0 +1,401 @@
+/**
+ * ProximaDB TypeScript SDK - Search Builder
+ *
+ * Provides a fluent API for building and executing vector similarity searches.
+ *
+ * Copyright 2025 ProximaDB Contributors
+ * Licensed under the Apache License, Version 2.0
+ */
+
+import type {
+  Filter,
+  SearchResult,
+  JsonValue,
+  SearchResultIterator,
+} from "./types";
+import { SearchMode } from "./types";
+import { FilterBuilder, filterToExpression } from "./filter";
+
+/**
+ * Internal search request structure
+ */
+interface SearchRequest {
+  vector: number[];
+  top_k: number;
+  filter?: string;
+  searchMode?: string;
+  include_vector: boolean;
+  include_text: boolean;
+  timeoutMs?: number;
+}
+
+/**
+ * HTTP client interface for search operations
+ */
+export interface SearchHttpClient {
+  post<T>(url: string, body: unknown): Promise<T>;
+  url(): string;
+  /**
+   * Typed transport for vector search (TD-126 Phase 4). Routes through the
+   * generated REST client (POST /api/v2/collections/{collection_id}/search).
+   */
+  searchRecordsRequest(
+    collectionId: string,
+    body: Record<string, unknown>,
+  ): Promise<unknown>;
+}
+
+/**
+ * Builder for search queries with fluent API
+ */
+export class SearchBuilder {
+  private client: SearchHttpClient;
+  private collectionName: string;
+  private queryVector: number[] | null = null;
+  private k: number = 10;
+  private filterExpr: string | null = null;
+  private filterBuilder: FilterBuilder | null = null;
+  private searchMode: SearchMode = SearchMode.Exact;
+  private nprobeValue: number | null = null;
+  private adaptiveThreshold: number | null = null;
+  private includeVectorsFlag: boolean = false;
+  private minScoreValue: number | null = null;
+  private timeoutMsValue: number | null = null;
+
+  constructor(client: SearchHttpClient, collection: string) {
+    this.client = client;
+    this.collectionName = collection;
+  }
+
+  /**
+   * Set the query vector
+   */
+  vector(vec: number[]): SearchBuilder {
+    this.queryVector = vec;
+    return this;
+  }
+
+  /**
+   * Set the number of results to return
+   */
+  topK(k: number): SearchBuilder {
+    this.k = k;
+    return this;
+  }
+
+  /**
+   * Alias for topK
+   */
+  limit(k: number): SearchBuilder {
+    return this.topK(k);
+  }
+
+  /**
+   * Set a filter expression string
+   */
+  filter(filterStr: string): SearchBuilder {
+    this.filterExpr = filterStr;
+    return this;
+  }
+
+  /**
+   * Apply a pre-built filter
+   */
+  withFilter(filterObj: Filter): SearchBuilder {
+    this.filterExpr = filterToExpression(filterObj);
+    return this;
+  }
+
+  /**
+   * Set the search mode
+   */
+  mode(searchMode: SearchMode): SearchBuilder {
+    this.searchMode = searchMode;
+    return this;
+  }
+
+  /**
+   * Use exact search (100% recall)
+   */
+  exact(): SearchBuilder {
+    this.searchMode = SearchMode.Exact;
+    return this;
+  }
+
+  /**
+   * Use approximate search for faster results
+   */
+  approximate(): SearchBuilder {
+    this.searchMode = SearchMode.Approximate;
+    return this;
+  }
+
+  /**
+   * Use approximate search with specific nprobe value
+   */
+  approximateWithNprobe(nprobe: number): SearchBuilder {
+    this.searchMode = SearchMode.Approximate;
+    this.nprobeValue = nprobe;
+    return this;
+  }
+
+  /**
+   * Use adaptive search mode
+   */
+  adaptive(threshold: number): SearchBuilder {
+    this.searchMode = SearchMode.Adaptive;
+    this.adaptiveThreshold = threshold;
+    return this;
+  }
+
+  /**
+   * Include vectors in results
+   */
+  includeVectors(include: boolean = true): SearchBuilder {
+    this.includeVectorsFlag = include;
+    return this;
+  }
+
+  /**
+   * Include metadata in results
+   */
+  includeMetadata(_include: boolean = true): SearchBuilder {
+    return this;
+  }
+
+  /**
+   * Set minimum score threshold
+   */
+  minScore(score: number): SearchBuilder {
+    this.minScoreValue = score;
+    return this;
+  }
+
+  /**
+   * Set request timeout in milliseconds
+   */
+  timeoutMs(timeout: number): SearchBuilder {
+    this.timeoutMsValue = timeout;
+    return this;
+  }
+
+  /**
+   * Set timeout in seconds (convenience method)
+   */
+  timeoutSecs(secs: number): SearchBuilder {
+    this.timeoutMsValue = secs * 1000;
+    return this;
+  }
+
+  // =========================================================================
+  // Inline filter methods for convenience
+  // =========================================================================
+
+  /**
+   * Add an equality filter condition
+   */
+  filterEq(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.eq(field, value);
+    return this;
+  }
+
+  /**
+   * Add a not-equal filter condition
+   */
+  filterNe(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.ne(field, value);
+    return this;
+  }
+
+  /**
+   * Add a greater-than filter condition
+   */
+  filterGt(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.gt(field, value);
+    return this;
+  }
+
+  /**
+   * Add a greater-than-or-equal filter condition
+   */
+  filterGte(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.gte(field, value);
+    return this;
+  }
+
+  /**
+   * Add a less-than filter condition
+   */
+  filterLt(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.lt(field, value);
+    return this;
+  }
+
+  /**
+   * Add a less-than-or-equal filter condition
+   */
+  filterLte(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.lte(field, value);
+    return this;
+  }
+
+  /**
+   * Add a range filter condition (inclusive)
+   */
+  filterRange(field: string, min: JsonValue, max: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.range(field, min, max);
+    return this;
+  }
+
+  /**
+   * Add an IN filter condition
+   */
+  filterIn(field: string, values: JsonValue[]): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.inList(field, values);
+    return this;
+  }
+
+  /**
+   * Add a contains filter condition
+   */
+  filterContains(field: string, value: JsonValue): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.contains(field, value);
+    return this;
+  }
+
+  /**
+   * Add an exists filter condition
+   */
+  filterExists(field: string): SearchBuilder {
+    this.ensureFilterBuilder();
+    this.filterBuilder = this.filterBuilder!.exists(field);
+    return this;
+  }
+
+  private ensureFilterBuilder(): void {
+    if (this.filterBuilder === null) {
+      this.filterBuilder = FilterBuilder.new();
+    }
+  }
+
+  private buildFilter(): string | undefined {
+    if (this.filterBuilder !== null) {
+      return this.filterBuilder.toExpression();
+    }
+    return this.filterExpr ?? undefined;
+  }
+
+  private buildSearchModeString(): string {
+    switch (this.searchMode) {
+      case SearchMode.Exact:
+        return "exact";
+      case SearchMode.Approximate:
+        if (this.nprobeValue !== null) {
+          return "approximate:" + this.nprobeValue;
+        }
+        return "approximate";
+      case SearchMode.Adaptive:
+        if (this.adaptiveThreshold !== null) {
+          return "adaptive:" + this.adaptiveThreshold;
+        }
+        return "adaptive:10000";
+      default:
+        return "exact";
+    }
+  }
+
+  /**
+   * Execute the search query
+   */
+  async execute(): Promise<SearchResult[]> {
+    if (this.queryVector === null) {
+      throw new Error("Query vector is required");
+    }
+
+    if (this.k <= 0 || this.k > 10000) {
+      throw new Error("topK must be between 1 and 10000");
+    }
+
+    const request: SearchRequest = {
+      vector: this.queryVector,
+      top_k: this.k,
+      filter: this.buildFilter(),
+      searchMode: this.buildSearchModeString(),
+      include_vector: this.includeVectorsFlag,
+      include_text: false,
+      timeoutMs: this.timeoutMsValue ?? undefined,
+    };
+
+    const response = (await this.client.searchRecordsRequest(
+      this.collectionName,
+      request as unknown as Record<string, unknown>,
+    )) as { results: SearchResult[] };
+
+    let results = response.results;
+
+    // Apply min_score filter if set
+    if (this.minScoreValue !== null) {
+      results = results.filter((r) => r.score >= this.minScoreValue!);
+    }
+
+    return results;
+  }
+
+  /**
+   * Execute the search and return a streaming iterator
+   */
+  async *stream(): AsyncGenerator<SearchResult, void, unknown> {
+    const results = await this.execute();
+    for (const result of results) {
+      yield result;
+    }
+  }
+
+  /**
+   * Create an async iterator for streaming results
+   */
+  async iterate(): Promise<SearchResultIterator> {
+    const results = await this.execute();
+    let index = 0;
+    const total = results.length;
+
+    const iterator: SearchResultIterator = {
+      [Symbol.asyncIterator](): AsyncIterableIterator<SearchResult> {
+        return iterator;
+      },
+      async next(): Promise<IteratorResult<SearchResult>> {
+        if (index < results.length) {
+          return { value: results[index++]!, done: false };
+        }
+        return { value: undefined as unknown as SearchResult, done: true };
+      },
+      getTotal(): number {
+        return total;
+      },
+      isComplete(): boolean {
+        return index >= results.length;
+      },
+    };
+
+    return iterator;
+  }
+}
+
+/**
+ * Create a new search builder
+ */
+export function createSearchBuilder(
+  client: SearchHttpClient,
+  collection: string
+): SearchBuilder {
+  return new SearchBuilder(client, collection);
+}

package/src/transport.ts

@@ -0,0 +1,52 @@
+/**
+ * ProximaDB TypeScript SDK - Generated REST transport seam (TD-126 Phase 4)
+ *
+ * This is the thin, hand-written ergonomic facade over the GENERATED REST
+ * transport. The wire contract — path templates, path/query parameter
+ * encoding, request/response JSON shapes — is generated from
+ * `docs/openapi/proximadb-openapi.yaml` into `src/generated/schema.ts`
+ * (openapi-typescript, pinned in package.json; regenerate with
+ * `npm run gen-sdk`). `openapi-fetch` turns those generated `paths` types into
+ * a typed runtime client.
+ *
+ * Generators don't do ergonomics; this layer is the value-add: it injects the
+ * facade's own `fetch` (which owns bearer auth, retries, and error mapping —
+ * see `client.ts`) into the typed client, so the generated wire plumbing and
+ * the hand-written transport policy compose without either reimplementing the
+ * other. This mirrors the merged Go pilot (TD-126 Phase 2), where the generated
+ * `genrest.Client` is driven through `RequestEditorFn`s + a custom `http.Client`.
+ *
+ * Copyright 2025 ProximaDB Contributors
+ * Licensed under the Apache License, Version 2.0
+ */
+
+import createClient from "openapi-fetch";
+import type { Client } from "openapi-fetch";
+import type { paths } from "./generated/schema";
+
+/**
+ * The typed REST client over the generated OpenAPI `paths`.
+ */
+export type GeneratedClient = Client<paths>;
+
+/**
+ * A fetch implementation matching the facade's transport policy. It is given a
+ * resolved `Request` (URL + method + body assembled by the generated client)
+ * and must return a native `Response`. The facade implements auth/retry/error
+ * mapping inside this function (see `ProximaDBClient`).
+ */
+export type TransportFetch = (input: Request) => Promise<Response>;
+
+/**
+ * Construct the generated typed REST client, routing every request the
+ * generated client issues through the facade's transport `fetch`.
+ */
+export function createTransport(
+  baseUrl: string,
+  fetchImpl: TransportFetch,
+): GeneratedClient {
+  return createClient<paths>({
+    baseUrl,
+    fetch: fetchImpl,
+  });
+}