mushroomdb-client 0.1.2

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * mushroomdb-client — TypeScript client for mushroomdb.
+ *
+ * Entry point re-exports everything callers need.
+ */
+export { MushroomClient, MushroomError } from "./client.js";
+export type { AlgoDir, AlgoReport, CellValue, ClientOptions, DegreeConfig, DegreeReport, Explanation, IngestEdge, IngestOptions, IngestReport, IngestRequest, Neighborhood, NodeInfo, PageRankConfig, PageRankReport, PredicateKind, PredicateSummary, QueryOptions, QueryParams, QueryResult, RuleDef, RulePredicate, RuleStats, RuleSuggestion, Stats, SuggestReport, WccConfig, WccReport, } from "./client.js";
+export type { DbEvent, SubscribeMessage, } from "./types.js";
+export type { SubscribeHandle, SubscribeOptions, WsConstructor, WsLike, } from "./ws.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,YAAY,EACV,OAAO,EACP,UAAU,EACV,SAAS,EACT,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,OAAO,EACP,aAAa,EACb,SAAS,EACT,cAAc,EACd,KAAK,EACL,aAAa,EACb,SAAS,EACT,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,OAAO,EACP,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,MAAM,GACP,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * mushroomdb-client — TypeScript client for mushroomdb.
+ *
+ * Entry point re-exports everything callers need.
+ */
+export { MushroomClient, MushroomError } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,406 @@
+/**
+ * TypeScript types for the mushroomdb HTTP + WebSocket API.
+ *
+ * Every type is annotated with the Rust struct / enum it mirrors.
+ */
+/**
+ * A single cell value in a query result row.
+ *
+ * Mirrors `core_storage::types::Value`:
+ *   Int(i64)        → number
+ *   Float(f64)      → number (NaN serializes as null per server behaviour)
+ *   Str(String)     → string
+ *   Bool(bool)      → boolean
+ *   List(Vec<Value>) → CellValue[]
+ *   null cell       → null
+ *
+ * **Precision warning (Int / i64):** JavaScript `number` (IEEE 754 double)
+ * safely represents integers only up to ±2^53 − 1 (~9×10^15). Rust `i64`
+ * reaches ±9.2×10^18. Integer node properties whose absolute value exceeds
+ * 2^53 will be silently corrupted when parsed as JS numbers. For such values
+ * use a string representation in the graph instead. A future release will
+ * offer a BigInt-aware parsing mode.
+ */
+export type CellValue = number | string | boolean | null | CellValue[];
+/**
+ * Wire shape of a successful `POST /query?format=json` response.
+ *
+ * Mirrors `crates/server/src/json.rs::result_set_json` output:
+ *   { columns: string[], rows: (scalar|null)[][] }
+ */
+export interface QueryResult {
+    columns: string[];
+    rows: CellValue[][];
+}
+/**
+ * Per-rule statistics.
+ *
+ * Mirrors `core_api::db::RuleStats`.
+ */
+export interface RuleStats {
+    name: string;
+    edges: number;
+    tripped: boolean;
+    fires: number;
+    approximate: boolean;
+}
+/**
+ * Database-wide counters returned by `GET /stats`.
+ *
+ * Mirrors `core_api::db::Stats`.
+ */
+export interface Stats {
+    nodes_live: number;
+    nodes_tombstoned: number;
+    edges: number;
+    rules: RuleStats[];
+}
+/**
+ * Options for `POST /ingest`.
+ *
+ * Mirrors `core_api::IngestOptions` (serialised by `crates/server/src/http.rs::ingest_options`).
+ */
+export interface IngestOptions {
+    /** Name of the field to use as the node key. Defaults to "key". */
+    key_field?: string;
+    /**
+     * Auto foreign-key detection mode.
+     *   false | "off"       → disabled
+     *   { suffix: string }  → detect fields ending with `suffix` (e.g. "_id")
+     */
+    auto_fk?: false | "off" | {
+        suffix: string;
+    };
+}
+/** An explicit edge to wire during ingest. */
+export interface IngestEdge {
+    edge_type: string;
+    src: string;
+    dst: string;
+}
+/** Body sent to `POST /ingest`. */
+export interface IngestRequest {
+    label: string;
+    rows: Record<string, unknown>[];
+    options?: IngestOptions;
+    edges?: IngestEdge[];
+}
+/** Response from `POST /ingest`. Shape is opaque; use `ok` to check success. */
+export type IngestReport = Record<string, unknown>;
+/**
+ * Wire `NodeInfo` from `GET /node/{key}`.
+ *
+ * `props` uses the same untagged Value JSON as `/query`. Unknown keys are
+ * HTTP 404; the client `node()` method maps that to `null`.
+ */
+export interface NodeInfo {
+    key: string;
+    label: string;
+    props: Record<string, CellValue>;
+}
+/**
+ * Predicate kind on an {@link Explanation}, matching HTTP snake_case JSON.
+ */
+export type PredicateKind = "key_match" | "field_equal" | "overlap" | "all" | "numeric_within" | "geo_radius" | "vector_similar";
+/**
+ * Wire `PredicateSummary`. Option fields are present-null, never omitted.
+ */
+export interface PredicateSummary {
+    kind: PredicateKind;
+    fields: string[];
+    min: number | null;
+    tolerance: number | null;
+    km: number | null;
+    parts: PredicateSummary[] | null;
+}
+/**
+ * One rule-derived edge between two nodes from `GET /explain?a=&b=`.
+ *
+ * Mirrors `core_api::db::Explanation`.
+ */
+export interface Explanation {
+    rule: string;
+    edge_type: string;
+    src_key: string;
+    dst_key: string;
+    weight: number | null;
+    predicate: PredicateSummary;
+}
+/**
+ * Wire neighborhood expansion from `GET /node/{key}/neighborhood`.
+ *
+ * Columns are `key`, `label`, `depth`.
+ */
+export interface Neighborhood {
+    columns: string[];
+    rows: CellValue[][];
+}
+/**
+ * Internally-tagged `Predicate` JSON accepted by `POST /rules`.
+ *
+ * Mirrors `core_rules::Predicate`.
+ */
+export type RulePredicate = {
+    KeyMatch: {
+        field: string;
+    };
+} | {
+    FieldEqual: {
+        field: string;
+    };
+} | {
+    Overlap: {
+        field: string;
+        min: number;
+    };
+} | {
+    NumericWithin: {
+        field: string;
+        tolerance: number;
+    };
+} | {
+    GeoRadius: {
+        field: string;
+        km: number;
+    };
+} | {
+    VectorSimilar: {
+        field: string;
+        min: number;
+    };
+} | {
+    All: RulePredicate[];
+} | {
+    Any: RulePredicate[];
+};
+/**
+ * Rule definition posted to `POST /rules`.
+ *
+ * Mirrors `core_rules::RuleDef`. Omit or `max_edges: null` → server fills
+ * scored top-k 32, or 1 if the predicate is KeyMatch-rooted. HTTP has no
+ * uncapped hatch (Rust/Python explicit `None` still uses the 1_000_000
+ * global first-N-by-id budget).
+ */
+export interface RuleDef {
+    name: string;
+    src_label: string;
+    dst_label: string;
+    predicate: RulePredicate;
+    edge_type: string;
+    weight_prop?: string | null;
+    /** Per-source top-k. Omit/`null` fills 32 (scored) or 1 (KeyMatch-rooted). */
+    max_edges?: number | null;
+    approximate?: boolean;
+}
+/**
+ * One rule suggestion returned by `GET /suggest`.
+ *
+ * Mirrors `core_rules::suggest::RuleSuggestion`.
+ */
+export interface RuleSuggestion {
+    /** The proposed rule definition (not yet created in the database). */
+    def: Record<string, unknown>;
+    /** Estimated edge count if the rule were applied. */
+    est_edges: number;
+    /** Up to 3 example (src_key, dst_key, score) triples drawn from sample evaluation. */
+    examples: [string, string, number][];
+    /** Human-readable explanation of why this rule was suggested. */
+    rationale: string;
+}
+/**
+ * Response from `GET /suggest`.
+ *
+ * Mirrors `core_rules::suggest::SuggestReport`.
+ */
+export interface SuggestReport {
+    suggestions: RuleSuggestion[];
+    /**
+     * true when the global time budget fired before all candidates were evaluated.
+     * Partial results are still returned.
+     */
+    truncated: boolean;
+}
+/**
+ * Edge direction for graph algorithms.
+ *
+ * Mirrors `core_api::algo::AlgoDir` (serialises as lowercase string).
+ */
+export type AlgoDir = "out" | "in" | "both";
+/**
+ * Config for `POST /algo/pagerank`.
+ *
+ * Mirrors `core_api::algo::PageRankConfig`. All fields are optional — the
+ * server applies defaults (damping=0.85, max_iters=50, tol=1e-6,
+ * edge_type=null, direction="out", budget_ms=5000).
+ */
+export interface PageRankConfig {
+    damping?: number;
+    max_iters?: number;
+    tol?: number;
+    edge_type?: string | null;
+    direction?: AlgoDir;
+    budget_ms?: number;
+}
+/**
+ * Result of `POST /algo/pagerank`.
+ *
+ * Mirrors `core_api::algo::PageRankReport`.
+ */
+export interface PageRankReport {
+    /** [node_key, score] pairs, sorted by score descending (ties: key asc). */
+    scores: [string, number][];
+    /** true when the algorithm converged before max_iters and before any budget fired. */
+    converged: boolean;
+}
+/**
+ * Config for `POST /algo/wcc`.
+ *
+ * Mirrors `core_api::algo::WccConfig`. Defaults: edge_type=null, budget_ms=5000.
+ */
+export interface WccConfig {
+    edge_type?: string | null;
+    budget_ms?: number;
+}
+/**
+ * Result of `POST /algo/wcc`.
+ *
+ * Mirrors `core_api::algo::WccReport`.
+ */
+export interface WccReport {
+    /** [node_key, component_id] pairs. component_id is the smallest key in the component. */
+    components: [string, string][];
+    truncated: boolean;
+}
+/**
+ * Config for `POST /algo/degree`.
+ *
+ * Mirrors `core_api::algo::DegreeConfig`. Defaults: edge_type=null, direction="both", budget_ms=5000.
+ */
+export interface DegreeConfig {
+    edge_type?: string | null;
+    direction?: AlgoDir;
+    budget_ms?: number;
+}
+/**
+ * Result of `POST /algo/degree`.
+ *
+ * Mirrors `core_api::algo::DegreeReport`.
+ */
+export interface DegreeReport {
+    /**
+     * [node_key, degree] pairs, sorted by degree descending (ties: key asc).
+     *
+     * **Precision warning:** Rust returns `u64` degrees. JS `number` (IEEE 754)
+     * safely represents values up to 2^53 − 1. Nodes with degree above ~9×10^15
+     * will silently lose precision. In practice graphs with that many edges per
+     * node do not exist, but be aware of the type constraint.
+     */
+    scores: [string, number][];
+    truncated: boolean;
+}
+/** Union of all algo configs. */
+export type AlgoConfig = {
+    algo: "pagerank";
+    config?: PageRankConfig;
+} | {
+    algo: "wcc";
+    config?: WccConfig;
+} | {
+    algo: "degree";
+    config?: DegreeConfig;
+};
+/** Union of all algo results. */
+export type AlgoReport = PageRankReport | WccReport | DegreeReport;
+/**
+ * A post-commit event delivered over the `/subscribe` WebSocket.
+ *
+ * Mirrors `core_api::subscription::DbEvent` — serialised as internally-tagged
+ * JSON with `"type"` as the discriminant.
+ *
+ * All variants except `lagged` carry `commit_seq: number` (Rust: `u64`).
+ * `lagged` means the subscriber's internal queue overflowed; the caller should
+ * re-read graph state to recover consistency for lossless consumers.
+ *
+ * **Precision warning (`commit_seq` / `missed`):** Both are Rust `u64` and map
+ * to JS `number` (IEEE 754 double, safe up to 2^53 − 1 ≈ 9×10^15). A
+ * long-lived server generating more than ~9×10^15 commits will silently
+ * corrupt these values. A future release will represent u64 fields as
+ * `string` or `bigint`. For now treat `commit_seq` as an opaque ordering key,
+ * not an exact integer.
+ */
+export type DbEvent = {
+    type: "edge_fired";
+    rule: string;
+    src_key: string;
+    dst_key: string;
+    edge_type: string;
+    weight?: number;
+    commit_seq: number;
+} | {
+    type: "edge_retracted";
+    rule: string;
+    src_key: string;
+    dst_key: string;
+    edge_type: string;
+    commit_seq: number;
+} | {
+    type: "node_inserted";
+    label: string;
+    key: string;
+    commit_seq: number;
+} | {
+    type: "node_deleted";
+    key: string;
+    commit_seq: number;
+} | {
+    type: "edge_inserted";
+    edge_type: string;
+    src: string;
+    dst: string;
+    commit_seq: number;
+} | {
+    type: "edge_deleted";
+    edge_type: string;
+    src: string;
+    dst: string;
+    commit_seq: number;
+} | {
+    type: "prop_set";
+    key: string;
+    field: string;
+    commit_seq: number;
+} | {
+    type: "prop_removed";
+    key: string;
+    field: string;
+    commit_seq: number;
+} | {
+    /**
+     * One or more events were dropped because the subscriber's queue was full
+     * (capacity 65,536). The caller must re-read graph state to recover
+     * consistency for lossless consumers.
+     */
+    type: "lagged";
+    missed: number;
+};
+/**
+ * Subscribe message sent to the server after the WebSocket upgrade.
+ *
+ * Mirrors `crates/server/src/subscribe.rs::SubscribeMsg`.
+ * All fields are optional. With no fields the client receives no events.
+ */
+export interface SubscribeMessage {
+    /** Rule names to subscribe to. Receive EdgeFired/EdgeRetracted for each. */
+    rules?: string[];
+    /** If true, also receive node/property write events. */
+    writes?: boolean;
+}
+/**
+ * Thrown by the client when the server returns an HTTP error or the
+ * WebSocket handshake fails.
+ */
+export declare class MushroomError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,21 @@
+/**
+ * TypeScript types for the mushroomdb HTTP + WebSocket API.
+ *
+ * Every type is annotated with the Rust struct / enum it mirrors.
+ */
+// ---------------------------------------------------------------------------
+// Client error
+// ---------------------------------------------------------------------------
+/**
+ * Thrown by the client when the server returns an HTTP error or the
+ * WebSocket handshake fails.
+ */
+export class MushroomError extends Error {
+    detail;
+    constructor(detail) {
+        super(detail);
+        this.detail = detail;
+        this.name = "MushroomError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0bH,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACV,MAAM;IAAlC,YAA4B,MAAc;QACxC,KAAK,CAAC,MAAM,CAAC,CAAC;sBADY,MAAM;QAEhC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF"}

package/dist/ws.d.ts

@@ -0,0 +1,92 @@
+/**
+ * WebSocket subscription over `GET /subscribe`.
+ *
+ * # Protocol (matches crates/server/src/subscribe.rs)
+ *
+ * 1. Connect to `ws[s]://<host>/subscribe`.
+ * 2. Server waits for one JSON subscribe message: `{rules?, writes?}`.
+ * 3. Server responds with `{"subscribed":true}`.
+ * 4. Server streams DbEvent JSON frames until the connection closes.
+ *
+ * # Reconnection
+ *
+ * Auto-reconnect is NOT implemented in v1. When the connection drops
+ * (network error, server restart), no further events are delivered. The
+ * caller is responsible for reconnecting if required.
+ *
+ * # Lagged events
+ *
+ * If the server's per-subscriber queue overflows, it emits a
+ * `{"type":"lagged","missed":N}` frame. This is passed to `onEvent` like any
+ * other event. For lossless consumers: on receiving a `lagged` event, re-read
+ * the affected graph state via a query.
+ *
+ * # Node.js usage
+ *
+ * The browser WebSocket global is not present in Node < 21. Pass the `ws`
+ * package's WebSocket class via `opts.wsConstructor`:
+ *
+ * ```ts
+ * import WS from 'ws';
+ * const handle = await subscribe(wsUrl, { writes: true, wsConstructor: WS as WsConstructor }, onEvent);
+ * ```
+ */
+import type { DbEvent, SubscribeMessage } from "./types.js";
+export type { DbEvent };
+/**
+ * Minimal WebSocket-like interface required by subscribe().
+ * Satisfied by both browser WebSocket and the `ws` npm package.
+ */
+export interface WsLike {
+    send(data: string): void;
+    close(): void;
+    set onopen(handler: ((ev: unknown) => void) | null);
+    set onmessage(handler: ((ev: {
+        data: unknown;
+    }) => void) | null);
+    set onclose(handler: ((ev: unknown) => void) | null);
+    set onerror(handler: ((ev: unknown) => void) | null);
+}
+/** Constructor type for both browser WebSocket and the `ws` package. */
+export type WsConstructor = new (url: string) => WsLike;
+/** Options for {@link subscribe}. */
+export interface SubscribeOptions extends SubscribeMessage {
+    /**
+     * Custom WebSocket constructor.
+     *
+     * **Node.js only** — required when `globalThis.WebSocket` is not available
+     * (Node < 21). Example:
+     *
+     * ```ts
+     * import WS from 'ws';
+     * { wsConstructor: WS as WsConstructor }
+     * ```
+     *
+     * In the browser the native `WebSocket` global is used automatically.
+     */
+    wsConstructor?: WsConstructor;
+}
+/** Handle returned by {@link subscribe}. */
+export interface SubscribeHandle {
+    /**
+     * Close the WebSocket connection.
+     *
+     * Returns a promise that resolves when the connection is fully closed.
+     * Always await this before ending a test or shutting down to avoid
+     * dangling handles that keep the event loop alive.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Open a `GET /subscribe` WebSocket and begin streaming {@link DbEvent}s.
+ *
+ * Resolves when the server acknowledges the subscribe message
+ * (`{"subscribed":true}`). Rejects on connection failure or if the server
+ * returns an error (e.g. unknown rule name).
+ *
+ * @param wsUrl   Full WebSocket URL, e.g. `ws://127.0.0.1:8080/subscribe`.
+ * @param opts    Subscribe options — rules, writes flag, optional wsConstructor.
+ * @param onEvent Callback invoked for each {@link DbEvent}, including `lagged`.
+ */
+export declare function subscribe(wsUrl: string, opts: SubscribeOptions, onEvent: (event: DbEvent) => void): Promise<SubscribeHandle>;
+//# sourceMappingURL=ws.d.ts.map

package/dist/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE5D,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE;IACpD,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE;IACjE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE;IACrD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE;CACtD;AAED,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAExD,qCAAqC;AACrC,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA0BD;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAChC,OAAO,CAAC,eAAe,CAAC,CA2E1B"}