hermes-client-typescript 1.8.96 → 1.8.98

package/README.md

@@ -1,6 +1,7 @@
-# hermes-client-typescript
+# Hermes TypeScript client
 
-TypeScript client for [Hermes](https://github.com/SpaceFrontiers/hermes) search server.
+Typed Node.js client for the
+[Hermes](https://github.com/SpaceFrontiers/hermes) gRPC search server.
 
 ## Installation
 
@@ -8,7 +9,7 @@ TypeScript client for [Hermes](https://github.com/SpaceFrontiers/hermes) search
 pnpm add hermes-client-typescript
 ```
 
-## Usage
+## Quick start
 
 ```typescript
 import { HermesClient } from "hermes-client-typescript";
@@ -16,109 +17,204 @@ import { HermesClient } from "hermes-client-typescript";
 const client = new HermesClient("localhost:50051");
 client.connect();
 
-// Create index
-await client.createIndex(
-  "articles",
-  `
-  index articles {
-    field title: text [indexed, stored]
-    field body: text [indexed, stored]
+try {
+  await client.createIndex(
+    "articles",
+    `
+      index articles {
+        field title: text<simple> [indexed, stored]
+        field body: text<simple> [indexed, stored]
+      }
+    `,
+  );
+
+  const [indexedCount, errorCount, errors] = await client.indexDocuments(
+    "articles",
+    [
+      { title: "Hello", body: "First article" },
+      { title: "Hermes", body: "Fast search" },
+    ],
+  );
+  if (errorCount) throw new Error(JSON.stringify(errors));
+  console.log(`Indexed ${indexedCount} documents`);
+
+  await client.commit("articles");
+
+  const results = await client.search("articles", {
+    query: { match: { field: "title", text: "hello" } },
+    fieldsToLoad: ["title", "body"],
+  });
+
+  for (const hit of results.hits) {
+    console.log(hit.address, hit.score, hit.fields);
   }
-`,
-);
 
-// Index documents
-await client.indexDocuments("articles", [
-  { title: "Hello", body: "World" },
-  { title: "Foo", body: "Bar" },
-]);
-await client.commit("articles");
-
-// Search
-const results = await client.search("articles", {
-  term: ["title", "hello"],
-});
-for (const hit of results.hits) {
-  console.log(hit.docId, hit.score, hit.fields);
+  if (results.hits.length > 0) {
+    const document = await client.getDocument(
+      "articles",
+      results.hits[0].address,
+    );
+    console.log(document?.fields);
+  }
+} finally {
+  client.close();
 }
+```
 
-// Clean up
-client.close();
+Call `connect()` before the first RPC and `close()` when the client is no
+longer needed.
+
+## Index management
+
+```typescript
+await client.createIndex("articles", schema);
+const names = await client.listIndexes();
+const info = await client.getIndexInfo("articles");
+
+await client.forceMerge("articles");
+await client.reorder("articles");
+await client.retrainVectorIndex("articles");
+await client.deleteIndex("articles");
 ```
 
-## API
+Newly indexed documents become searchable after `commit()`.
 
-### Index Management
+### Batch and streaming indexing
 
-- `createIndex(indexName, schema)` — Create a new index with SDL or JSON schema
-- `deleteIndex(indexName)` — Delete an index
-- `listIndexes()` — List all index names
-- `getIndexInfo(indexName)` — Get index metadata (doc count, segments, schema)
+```typescript
+const [indexed, errorCount, errors] = await client.indexDocuments("articles", [
+  { title: "One", tags: ["search", "typescript"] },
+  { title: "Two", tags: ["grpc"] },
+]);
 
-### Document Indexing
+async function* documents() {
+  for (let number = 0; number < 10_000; number += 1) {
+    yield { title: `Document ${number}` };
+  }
+}
 
-- `indexDocuments(indexName, docs)` — Batch index documents, returns `[indexedCount, errorCount, errors]`
-- `indexDocument(indexName, doc)` — Index a single document
-- `indexDocumentsStream(indexName, asyncIterable)` — Stream documents for indexing
-- `commit(indexName)` — Commit pending changes, returns total doc count
-- `forceMerge(indexName)` — Force merge segments
+const streamed = await client.indexDocumentsStream("articles", documents());
+```
 
-### Search
+Repeated arrays become repeated field entries. Flat numeric arrays are dense
+vectors. Sparse vectors use arrays of `[dimension, weight]` pairs inside an
+outer repeated-value array—for example, `[[[1, 0.5], [8, 0.25]]]` for one
+sparse vector. The outer array is required because `[[1, 0.5], [8, 0.25]]` is
+the legacy shape for two dense vectors.
 
-- `search(indexName, options)` — Search with term, boolean, sparse/dense vector queries
-- `getDocument(indexName, docId)` — Get document by ID
+## Searching
 
-### Search Options
+`search()` accepts a `SearchRequest`. Its `query` is a discriminated union, so
+exactly one query variant is selected:
 
 ```typescript
-await client.search("docs", {
-  // Term query
-  term: ["field", "value"],
-
-  // Boolean query
-  boolean: {
-    must: [["title", "hello"]],
-    should: [["body", "world"]],
+// Exact term
+await client.search("articles", {
+  query: { term: { field: "title", term: "hermes" } },
+});
+
+// Recursive Boolean query
+await client.search("articles", {
+  query: {
+    boolean: {
+      must: [{ match: { field: "body", text: "fast search" } }],
+      mustNot: [{ term: { field: "title", term: "draft" } }],
+    },
   },
+});
 
-  // Sparse vector (pre-tokenized)
-  sparseVector: ["embedding", [1, 5, 10], [0.5, 0.3, 0.2]],
+// Dense retrieval with reranking
+await client.search("articles", {
+  query: {
+    denseVector: {
+      field: "embedding",
+      vector: [0.1, 0.2, 0.3],
+      nprobe: 16,
+    },
+  },
+  reranker: {
+    field: "embedding",
+    vector: [0.1, 0.2, 0.3],
+  },
+  candidateLimit: 20,
+  limit: 10,
+  fieldsToLoad: ["title"],
+});
 
-  // Sparse text (server-side tokenization)
-  sparseText: ["embedding", "what is machine learning?"],
+// Hybrid union fusion
+await client.search("articles", {
+  query: {
+    fusion: {
+      method: "rrf",
+      rrfK: 60,
+      queries: [
+        {
+          query: {
+            sparseVector: {
+              field: "sparseEmbedding",
+              indices: [1, 5],
+              values: [0.8, 0.2],
+            },
+          },
+        },
+        {
+          query: {
+            denseVector: {
+              field: "embedding",
+              vector: [0.1, 0.2, 0.3],
+            },
+          },
+        },
+      ],
+    },
+  },
+});
+```
 
-  // Dense vector
-  denseVector: ["embedding", [0.1, 0.2, 0.3]],
+Supported variants are `term`, `match`, `boolean`, `sparseVector`,
+`denseVector`, `binaryDenseVector`, `boost`, `range`, `prefix`, `all`, and
+`fusion`.
 
-  // Options
-  limit: 10,
-  offset: 0,
-  fieldsToLoad: ["title", "body"],
-  combiner: "sum", // "sum" | "max" | "avg"
+`getDocument()` takes the full address returned by a search hit:
 
-  // L2 reranker; candidateLimit is the shared first-stage pool.
-  reranker: ["embedding", [0.1, 0.2]],
-  candidateLimit: 20,
+```typescript
+const document = await client.getDocument("articles", hit.address);
+```
+
+It returns `null` when the server responds with gRPC `NOT_FOUND`.
+
+## Deadlines
+
+Every RPC accepts an optional trailing deadline in milliseconds. A per-call
+value overrides the client default:
+
+```typescript
+const client = new HermesClient("localhost:50051", {
+  defaultTimeoutMs: 5_000,
 });
+
+await client.search("articles", { query: { all: {} } }, 500);
+await client.forceMerge("articles", 3_600_000);
 ```
 
+Expired calls reject with a gRPC `DEADLINE_EXCEEDED` error.
+
 ## Development
 
 ```bash
-pnpm install
-pnpm run generate  # regenerate proto stubs
-pnpm run build     # compile TypeScript
+pnpm install --frozen-lockfile
+pnpm check
 ```
 
-## Timeouts / deadlines
+`pnpm check` compiles the strict TypeScript sources and runs the pure converter
+unit tests. After changing `hermes-proto/hermes.proto`, regenerate and check in
+the generated source:
 
-Every RPC accepts an optional trailing `timeoutMs` which sets a real gRPC
-deadline (propagated to the server via `grpc-timeout`); a client-wide default
-can be set in the constructor. On expiry the call rejects with
-`DEADLINE_EXCEEDED`.
-
-```ts
-const client = new HermesClient("localhost:50051", { defaultTimeoutMs: 5000 });
-await client.search("articles", { query: { ... } }, 500); // per-call override
-await client.forceMerge("articles", 3_600_000); // long op, long deadline
+```bash
+pnpm generate
+pnpm check
 ```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -1,31 +1,31 @@
 /**
  * Async Hermes client implementation.
  *
- * All search types mirror the proto API structure exactly.
- * See types.ts for Query, Reranker, SearchRequest definitions.
+ * Search types mirror the protobuf API. Serialization details live in
+ * converters.ts so this class remains focused on connection and RPC lifecycle.
  */
-import type { DocAddress, Document, SearchResponse, IndexInfo, SearchRequest } from "./types";
+import type { DocAddress, Document, IndexInfo, SearchRequest, SearchResponse } from "./types";
 export interface HermesClientOptions {
     /**
      * Default per-RPC deadline in milliseconds, applied to every call unless
-     * overridden by the call's `timeoutMs` argument. Undefined = no deadline.
-     * On expiry the call rejects with a gRPC DEADLINE_EXCEEDED error.
+     * overridden by the call's `timeoutMs` argument. Undefined means no
+     * deadline. Expired calls reject with gRPC DEADLINE_EXCEEDED.
      */
     defaultTimeoutMs?: number;
 }
 export declare class HermesClient {
-    private address;
+    private readonly address;
+    private readonly defaultTimeoutMs?;
     private channel;
     private indexClient;
     private searchClient;
-    private defaultTimeoutMs?;
     constructor(address?: string, options?: HermesClientOptions);
-    /** Per-call options with the effective deadline (call override > default). */
-    private callOptions;
     /** Connect to the server. */
     connect(): void;
     /** Close the connection. */
     close(): void;
+    /** Per-call options with the effective deadline (call override > default). */
+    private callOptions;
     private ensureConnected;
     /** Create a new index. */
     createIndex(indexName: string, schema: string, timeoutMs?: number): Promise<boolean>;
@@ -35,58 +35,31 @@ export declare class HermesClient {
     listIndexes(timeoutMs?: number): Promise<string[]>;
     /** Get information about an index. */
     getIndexInfo(indexName: string, timeoutMs?: number): Promise<IndexInfo>;
-    /** Index multiple documents in batch. Returns [indexedCount, errorCount, errors]. */
-    indexDocuments(indexName: string, documents: Record<string, any>[], timeoutMs?: number): Promise<[number, number, Array<{
+    /** Index multiple documents. Returns [indexedCount, errorCount, errors]. */
+    indexDocuments(indexName: string, documents: Record<string, unknown>[], timeoutMs?: number): Promise<[number, number, Array<{
         index: number;
         error: string;
     }>]>;
     /** Index a single document. */
-    indexDocument(indexName: string, document: Record<string, any>, timeoutMs?: number): Promise<void>;
+    indexDocument(indexName: string, document: Record<string, unknown>, timeoutMs?: number): Promise<void>;
     /** Stream documents for indexing. Returns number of indexed documents. */
-    indexDocumentsStream(indexName: string, documents: AsyncIterable<Record<string, any>>, timeoutMs?: number): Promise<number>;
+    indexDocumentsStream(indexName: string, documents: AsyncIterable<Record<string, unknown>>, timeoutMs?: number): Promise<number>;
     /** Commit pending changes. Returns total number of documents. */
     commit(indexName: string, timeoutMs?: number): Promise<number>;
     /** Force merge all segments. Returns number of segments after merge. */
     forceMerge(indexName: string, timeoutMs?: number): Promise<number>;
     /** Retrain vector index centroids/codebooks from current data. */
     retrainVectorIndex(indexName: string, timeoutMs?: number): Promise<boolean>;
-    /** Reorder BMP blocks by SimHash similarity for better pruning. Returns number of segments. */
+    /** Reorder BMP blocks by SimHash similarity. */
     reorder(indexName: string, timeoutMs?: number): Promise<number>;
     /**
      * Search for documents.
      *
      * @example
-     * // Term query
-     * await client.search("articles", {
-     *   query: { term: { field: "title", term: "hello" } },
-     * });
-     *
-     * // Match query (full-text, tokenized server-side)
      * await client.search("articles", {
-     *   query: { match: { field: "title", text: "what is hemoglobin" } },
-     * });
-     *
-     * // Sparse vector query with server-side tokenization + pruning
-     * await client.search("docs", {
-     *   query: { sparseVector: { field: "embedding", text: "machine learning", pruning: 0.5 } },
+     *   query: { match: { field: "title", text: "search engine" } },
      *   fieldsToLoad: ["title"],
      * });
-     *
-     * // Dense vector query
-     * await client.search("docs", {
-     *   query: { denseVector: { field: "embedding", vector: [0.1, 0.2, ...], nprobe: 10 } },
-     *   reranker: { field: "embedding", vector: [0.1, 0.2, ...] },
-     *   limit: 50,
-     *   candidateLimit: 100,
-     * });
-     *
-     * // Boolean query
-     * await client.search("articles", {
-     *   query: { boolean: {
-     *     must: [{ match: { field: "title", text: "hello" } }],
-     *     should: [{ match: { field: "body", text: "world" } }],
-     *   }},
-     * });
      */
     search(indexName: string, request: SearchRequest, timeoutMs?: number): Promise<SearchResponse>;
     /** Get a document by address. Returns null if not found. */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}