@polymathbase/polybase-client 0.0.0-stage → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ihabshea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# Polybase local client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed HTTP client for a local Polybase console. This package contains compiled
+ES modules and TypeScript declarations. It does not contain the database engine
+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
+```
+
+Start `polybase-console /path/to/database 7340`, then:
+
+```js
+import {Client, hex, unhex} from '@polymathbase/polybase-client';
+
+const client = new Client('http://127.0.0.1:7340');
+const read = await client.readRevision('tasks/1');
+const receipt = await client.writeRevision(
+  read.revision, JSON.stringify({status: 'open'}),
+);
+const page = await client.page({
+  key_prefix: hex('tasks/'), predicate: 'json', value: '',
+  json: {op: 'eq', path: ['status'], value: 'open'},
+});
+console.log(receipt.position, page.explain);
+for (const row of page.rows) {
+  console.log(new TextDecoder().decode(unhex(row.value)));
+}
+```
+
+`readRevision` returns an opaque revision for a conditional `writeRevision`.
+An HTTP 409 reports a stale revision. A transport timeout or cancellation can
+leave a write's outcome uncertain: the server can still commit. The client never
+automatically retries writes. Reconcile application state before another write.
+
+Query pages have a captured position and an optional continuation cursor.
+Retain the query and use `client.page(query, page.next, limit)` while `next` is
+non-null. Keys and values in returned rows are lowercase hexadecimal bytes.
+Positions are decimal strings; use `bigint`, never a JavaScript `number`, for
+position arithmetic. Requests reject unsafe integer inputs before transport.
+
+`subscribe(query)` captures initial rows and a token. Persist those together,
+then consume `client.stream(session, savedToken, abortSignal)`. Apply each complete
+page of commit transitions and persist its token atomically before requesting
+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.
+
+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`.

package/dist/client.d.ts

@@ -0,0 +1,187 @@
+/** Local loopback client. Writes are never automatically retried. */
+export type Scalar = null | boolean | number | string;
+export type JsonPredicate = {
+    op: "eq" | "ne" | "lt" | "le" | "gt" | "ge";
+    path: string[];
+    value: Scalar;
+} | {
+    op: "exists";
+    path: string[];
+    present: boolean;
+} | {
+    op: "type";
+    path: string[];
+    kind: "null" | "boolean" | "number" | "string" | "array" | "object";
+} | {
+    op: "prefix";
+    path: string[];
+    value: string;
+} | {
+    op: "all" | "any";
+    predicates: JsonPredicate[];
+} | {
+    op: "not";
+    predicate: JsonPredicate;
+};
+export type Query = {
+    key_prefix: string;
+    predicate: "any" | "equals" | "prefix";
+    value: string;
+} | {
+    key_prefix: string;
+    predicate: "json";
+    value: "";
+    json: JsonPredicate;
+};
+export interface Row {
+    key: string;
+    value: string;
+}
+export interface OptimizerAlternative {
+    strategy: "scan" | "index_lookup" | "index_intersection" | "index_union";
+    index_names: string[];
+    estimated_candidates: number;
+    estimated_work: number;
+}
+export interface OptimizerExplain {
+    strategy: OptimizerAlternative["strategy"] | "retained_history_scan";
+    initial_strategy: OptimizerAlternative["strategy"] | "retained_history_scan";
+    index_names: string[];
+    alternatives: OptimizerAlternative[];
+    estimated_work: number;
+    estimated_range_rows: number;
+    statistics_epoch: number | null;
+    total_live_records: number;
+    statistics_rows: number;
+    definition_coverage: {
+        name: string;
+        prefix: number[];
+        records: number;
+    }[];
+    term_cardinalities: {
+        index_name: string;
+        path: string[];
+        value: Scalar;
+        cardinality: number;
+    }[];
+    actual_work: {
+        posting_steps: number;
+        canonical_lookups: number;
+        predicate_evaluations: number;
+        scan_rows: number;
+        restarts: number;
+    };
+    phase_timings_micros: {
+        planning: number;
+        index_execution: number;
+        scan_execution: number;
+    };
+    replan_reason: string | null;
+    calibration: {
+        enabled: boolean;
+        samples: number;
+        lookup_weight_units: number;
+    };
+}
+export interface QueryExplain {
+    plan: string;
+    position: string;
+    scanned_records: number;
+    scanned_rows: number;
+    matched_rows: number;
+    returned_rows: number;
+    elapsed_micros: number;
+    execution_plan: {
+        kind: "scan";
+    } | {
+        kind: "index_lookup";
+        index_name: string;
+    };
+    index_name: string | null;
+    fallback_reason: string | null;
+    candidate_count: number;
+    planning_rows: number;
+    index_build_rows: number;
+    index_build_micros: number;
+    total_rows_examined: number;
+    /** Added in 0.8.2; absent in responses from older servers. Estimated work is not elapsed time. */
+    optimizer?: OptimizerExplain;
+}
+export interface Page {
+    position: string;
+    rows: Row[];
+    next: string | null;
+    explain: QueryExplain;
+}
+export interface Session {
+    id: string;
+    instance: string;
+    token: string;
+    position: string;
+    rows: Row[];
+}
+export interface Change {
+    key: string;
+    before: string | null;
+    after: string | null;
+}
+export interface StreamPage {
+    commits: {
+        position: string;
+        changes: Change[];
+    }[];
+    token: string;
+    position: string;
+    head: string;
+    floor: string;
+}
+export interface RevisionRead {
+    value: string | null;
+    revision: string;
+    position: string;
+}
+export interface Receipt {
+    position: string;
+    durable: boolean;
+    wrote: boolean;
+}
+export declare class ApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare const hex: (value: Uint8Array | string) => string;
+export declare function unhex(value: string): Uint8Array;
+export declare class Client {
+    readonly base: string;
+    constructor(base?: string);
+    call<T>(route: string, body: unknown, signal?: AbortSignal): Promise<T>;
+    page(query: Query, cursor?: string | null, limit?: number, forceScan?: boolean): Promise<Page>;
+    readRevision(key: Uint8Array | string): Promise<RevisionRead>;
+    writeRevision(revision: string, value: Uint8Array | string | null): Promise<Receipt>;
+    subscribe(query: Query): Promise<Session>;
+    resume(token: string): Promise<{
+        id: string;
+        instance: string;
+    }>;
+    poll(session: Pick<Session, "id" | "instance">, token: string, signal?: AbortSignal): Promise<StreamPage>;
+    unsubscribe(session: Pick<Session, "id" | "instance">, token: string): Promise<unknown>;
+    snapshotAt(position: bigint): Promise<{
+        position: string;
+        rows: Row[];
+    }>;
+    backup(directory: string): Promise<unknown>;
+    verifyBackup(directory: string): Promise<unknown>;
+    createIndex(name: string, prefix: Uint8Array | string, path: string[]): Promise<unknown>;
+    indexes(): Promise<unknown>;
+    searchIndex(name: string, value: Scalar): Promise<{
+        position: string;
+        indexed: boolean;
+        rows: Row[];
+    }>;
+    dropIndex(name: string): Promise<unknown>;
+    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. */
+    stream(session: Pick<Session, "id" | "instance">, appliedToken: string, signal?: AbortSignal): AsyncGenerator<StreamPage>;
+}

package/dist/client.js

@@ -0,0 +1,109 @@
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body) { super(`Polybase HTTP ${status}: ${JSON.stringify(body)}`); this.status = status; this.body = body; }
+}
+export const hex = (value) => [...(typeof value === "string" ? new TextEncoder().encode(value) : value)].map(b => b.toString(16).padStart(2, "0")).join("");
+export function unhex(value) {
+    if (!/^(?:[0-9a-f]{2})*$/.test(value))
+        throw new Error("invalid hex");
+    return Uint8Array.from(value.match(/../g) || [], b => Number.parseInt(b, 16));
+}
+function safeNumbers(value, depth = 0) {
+    if (depth > 64)
+        throw new Error("request nesting exceeds 64");
+    if (typeof value === "number" && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))
+        throw new Error("unsafe JSON number; use strings for exact large integers");
+    if (value && typeof value === "object")
+        for (const child of Object.values(value))
+            safeNumbers(child, depth + 1);
+}
+export class Client {
+    base;
+    constructor(base = "http://127.0.0.1:7340") {
+        if (!/^http:\/\/127\.0\.0\.1:[1-9][0-9]*$/.test(base) || Number(new URL(base).port) > 65535)
+            throw new Error("use an IPv4 loopback origin with an explicit port");
+        this.base = base;
+    }
+    async call(route, body, signal) {
+        if (!/^[a-z-]+$/.test(route))
+            throw new Error("invalid route");
+        safeNumbers(body);
+        const payload = JSON.stringify(body);
+        if (new TextEncoder().encode(payload).length > 128 * 1024)
+            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)
+            throw new Error("missing response body");
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > 8 * 1024 * 1024)
+                    throw new Error("response exceeds 8 MiB");
+                chunks.push(value);
+            }
+        }
+        finally {
+            await reader.cancel();
+            reader.releaseLock();
+        }
+        const all = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            all.set(chunk, offset);
+            offset += chunk.length;
+        }
+        const result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(all));
+        if (!response.ok)
+            throw new ApiError(response.status, result);
+        return result;
+    }
+    page(query, cursor = null, limit = 128, forceScan = false) { return this.call("query-page", { query, cursor, limit, ...(forceScan ? { force_scan: true } : {}) }); }
+    readRevision(key) { return this.call("read-revision", { key: hex(key) }); }
+    writeRevision(revision, value) { return this.call("write-revision", { revision, value: value === null ? null : hex(value) }); }
+    subscribe(query) { return this.call("query", query); }
+    resume(token) { return this.call("resume", { token }); }
+    poll(session, token, signal) { return this.call("poll", { id: session.id, instance: session.instance, token }, signal); }
+    unsubscribe(session, token) { return this.call("unsubscribe", { id: session.id, instance: session.instance, token }); }
+    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 }); }
+    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 }); }
+    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. */
+    async *stream(session, appliedToken, signal) {
+        let token = appliedToken;
+        try {
+            while (!signal?.aborted) {
+                const page = await this.poll(session, token, signal);
+                if (BigInt(page.position) < BigInt(tokenPosition(token)))
+                    throw new Error("stream cursor regressed");
+                if (page.token !== token) {
+                    yield page;
+                    token = page.token;
+                }
+                else
+                    await new Promise(resolve => { const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", done); resolve(); }; const timer = setTimeout(done, 25); signal?.addEventListener("abort", done, { once: true }); });
+            }
+        }
+        finally {
+            await this.unsubscribe(session, token).catch(() => { });
+        }
+    }
+}
+function tokenPosition(token) {
+    const bytes = unhex(token);
+    if (bytes.length < 36 || new TextDecoder().decode(bytes.subarray(0, 8)) !== "ENDBTOK1")
+        throw new Error("invalid local cursor");
+    return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getBigUint64(24, true);
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@polymathbase/polybase-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.2",
+  "description": "Typed loopback HTTP client for the local Polybase database",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "files": ["dist/client.js", "dist/client.d.ts", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "author": "ihabshea",
+  "homepage": "https://base.polymathlabs.xyz/docs",
+  "keywords": ["polybase", "database", "client", "local"],
+  "publishConfig": {"access": "public", "registry": "https://registry.npmjs.org/"},
+  "engines": {"node": ">=24"},
+  "scripts": {
+    "test": "node --test client.test.mjs",
+    "check": "tsc --noEmit --strict --target ES2022 --module nodenext --lib ES2022,DOM client.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {"typescript": "5.9.3"}
+}