@polymathbase/polybase-client 0.8.2 → 0.8.3

package/README.md

@@ -6,7 +6,7 @@ or a hosted service. Requires Node.js 24 or newer and a separately installed
 Polybase console; version 0.8.2 is the release qualification target.
 
 ```sh
-npm install @polymathbase/polybase-client@0.8.2
+npm install @polymathbase/polybase-client@0.8.3
 ```
 
 Start `polybase-console /path/to/database 7340`, then:
@@ -47,9 +47,25 @@ the next page. On restart call `resume(savedToken)` and explicitly continue from
 the last applied token. Delivery can repeat, tokens can expire, and the client
 does not silently take a new snapshot. Streaming uses polling on consumer demand.
 
+`search({kind: 'json', key_prefix: hex('tasks/'), path: ['status'], value: 'open'})`
+and `search({kind: 'text', key_prefix: hex('notes/'), text: 'quick fox'})` call
+`/api/search`: bounded current-head scalar equality or Unicode whole-word search,
+without a subscription. This differs from `searchIndex`, which calls
+`/api/index-search` for one named equality index, and from paginated typed queries.
+
+`createIndex(name, prefix, path)` encodes its prefix as a JSON byte array because
+the server's `index-create` route requires that format. Other key and
+`key_prefix` wire fields use lowercase hex. The client handles this conversion.
+
+Non-JSON HTTP errors retain their status in `ApiError.status` and response text
+in `ApiError.body` (invalid UTF-8 is replaced). JSON error bodies stay parsed;
+successful responses still require valid JSON.
+
 The client supports explicit IPv4 loopback HTTP origins only, a 128 KiB request
 bound, an 8 MiB response bound and a five-second request timeout. Keep the console
 on loopback. Query optimizer estimates describe work units, not measured latency.
 
 See the [Polybase documentation](https://base.polymathlabs.xyz/docs) for server
 installation, limits and protocol guarantees. Client terms are in `LICENSE`.
+The public [client source](https://github.com/ihabshea/polybase-downloads/tree/main/clients/typescript)
+and release tags allow comparison with the registry archive; the engine is private.

package/dist/client.d.ts

@@ -37,6 +37,22 @@ export interface Row {
     key: string;
     value: string;
 }
+/** A bounded current-head search, separate from named indexes and query pages. */
+export type SearchQuery = {
+    kind: "json";
+    key_prefix: string;
+    path: string[];
+    value: Scalar;
+} | {
+    kind: "text";
+    key_prefix: string;
+    text: string;
+};
+export interface SearchResult {
+    position: string;
+    indexed: boolean;
+    rows: Row[];
+}
 export interface OptimizerAlternative {
     strategy: "scan" | "index_lookup" | "index_intersection" | "index_union";
     index_names: string[];
@@ -172,6 +188,7 @@ export declare class Client {
     }>;
     backup(directory: string): Promise<unknown>;
     verifyBackup(directory: string): Promise<unknown>;
+    /** The index-create route requires prefix bytes as a JSON array, not hex. */
     createIndex(name: string, prefix: Uint8Array | string, path: string[]): Promise<unknown>;
     indexes(): Promise<unknown>;
     searchIndex(name: string, value: Scalar): Promise<{
@@ -180,6 +197,7 @@ export declare class Client {
         rows: Row[];
     }>;
     dropIndex(name: string): Promise<unknown>;
+    search(query: SearchQuery): Promise<SearchResult>;
     compactionAdvice(retainCommits: bigint): Promise<unknown>;
     /** Yield one complete page at a time. Persist rows and token before requesting another.
      * A cancellation after a write is not an abort. No transport retry or implicit resnapshot. */

package/dist/client.js

@@ -34,8 +34,11 @@ export class Client {
             throw new Error("request exceeds 128 KiB");
         const response = await fetch(`${this.base}/api/${route}`, { method: "POST", headers: { "Content-Type": "application/json", Origin: this.base }, body: payload, signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(5000)]) : AbortSignal.timeout(5000), redirect: "error" });
         const reader = response.body?.getReader();
-        if (!reader)
+        if (!reader) {
+            if (!response.ok)
+                throw new ApiError(response.status, "");
             throw new Error("missing response body");
+        }
         const chunks = [];
         let size = 0;
         try {
@@ -59,7 +62,16 @@ export class Client {
             all.set(chunk, offset);
             offset += chunk.length;
         }
-        const result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(all));
+        const text = new TextDecoder("utf-8", { fatal: response.ok }).decode(all);
+        let result;
+        try {
+            result = JSON.parse(text);
+        }
+        catch (error) {
+            if (response.ok)
+                throw error;
+            result = text;
+        }
         if (!response.ok)
             throw new ApiError(response.status, result);
         return result;
@@ -74,10 +86,12 @@ export class Client {
     snapshotAt(position) { return this.call("snapshot-at", { position: position.toString() }); }
     backup(directory) { return this.call("backup", { directory }); }
     verifyBackup(directory) { return this.call("verify-backup", { directory }); }
+    /** The index-create route requires prefix bytes as a JSON array, not hex. */
     createIndex(name, prefix, path) { return this.call("index-create", { name, prefix: Array.from(typeof prefix === "string" ? new TextEncoder().encode(prefix) : prefix), path }); }
     indexes() { return this.call("index-list", {}); }
     searchIndex(name, value) { return this.call("index-search", { name, value }); }
     dropIndex(name) { return this.call("index-drop", { name }); }
+    search(query) { return this.call("search", query); }
     compactionAdvice(retainCommits) { return this.call("compaction-advice", { retain_commits: retainCommits.toString() }); }
     /** Yield one complete page at a time. Persist rows and token before requesting another.
      * A cancellation after a write is not an abort. No transport retry or implicit resnapshot. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymathbase/polybase-client",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Typed loopback HTTP client for the local Polybase database",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,11 @@
   "sideEffects": false,
   "author": "ihabshea",
   "homepage": "https://base.polymathlabs.xyz/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ihabshea/polybase-downloads.git",
+    "directory": "clients/typescript"
+  },
   "keywords": ["polybase", "database", "client", "local"],
   "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/"},
   "engines": {"node": ">=24"},