mushroomdb-client 0.7.1 → 0.8.0

package/src/client.ts

@@ -15,12 +15,21 @@
 import {
   MushroomError,
   type AlgoReport,
+  type BackupReport,
+  type CreateNodeResult,
   type DegreeConfig,
   type DegreeReport,
+  type EdgeHistoryResult,
   type Explanation,
+  type FindSimilarOptions,
+  type FindSimilarResult,
+  type HealthReport,
   type IngestReport,
   type IngestRequest,
+  type MetricsReport,
   type Neighborhood,
+  type NodeEdgesResult,
+  type NodeHistoryResult,
   type NodeInfo,
   type PageRankConfig,
   type PageRankReport,
@@ -28,40 +37,62 @@ import {
   type RuleDef,
   type Stats,
   type SuggestReport,
+  type WasLinkedResult,
   type WccConfig,
   type WccReport,
 } from "./types.js";
 import {
   subscribe as wsSubscribe,
+  watch as wsWatch,
+  type MutationEvent,
   type SubscribeHandle,
   type SubscribeOptions,
+  type WatchHandle,
+  type WatchOptions,
   type WsConstructor,
 } from "./ws.js";
 
 export type {
   AlgoDir,
   AlgoReport,
+  BackupReport,
   CellValue,
+  CreateNodeResult,
   DegreeConfig,
   DegreeReport,
+  EdgeHistoryEntry,
+  EdgeHistoryResult,
+  EdgeInfo,
   Explanation,
+  FindSimilarOptions,
+  FindSimilarResult,
+  HealthReport,
+  HistoryChange,
+  HistoryEntry,
   IngestEdge,
   IngestOptions,
   IngestReport,
   IngestRequest,
+  MetricsReport,
   Neighborhood,
+  NodeEdgesResult,
+  NodeHistoryResult,
   NodeInfo,
+  NodeKeyOrStub,
   PageRankConfig,
   PageRankReport,
   PredicateKind,
   PredicateSummary,
+  PropPredicate,
   QueryResult,
   RuleDef,
   RulePredicate,
   RuleStats,
   RuleSuggestion,
+  SlowQueryEntry,
   Stats,
   SuggestReport,
+  WasLinkedResult,
   WccConfig,
   WccReport,
 } from "./types.js";
@@ -83,6 +114,25 @@ export type QueryParams = Record<string, string | number | boolean>;
 export interface QueryOptions {
   /** Bound parameters. Values must be JSON scalars (string | number | boolean). */
   params?: QueryParams;
+  /**
+   * Time-travel: run the query against the graph as it existed at this WAL
+   * commit index (read-only). Valid values are `0` to `commit_seq − 1`
+   * inclusive; passing `commit_seq` itself yields a range error. Obtain a
+   * commit index from the `commit` field of a `nodeHistory`/`edgeHistory`
+   * entry, or compute `(await client.metrics()).commit_seq - 1` for the most
+   * recent committed state.
+   */
+  as_of?: number;
+  /**
+   * Node-key allow-list: restrict visible nodes to these keys. The query sees
+   * only nodes whose key is in this set. Makes the query read-only.
+   */
+  mask?: string[];
+  /**
+   * Namespace to restrict results to. Intersects with `mask` and any role.
+   * Makes the query read-only.
+   */
+  namespace?: string;
 }
 
 /**
@@ -127,8 +177,41 @@ export class MushroomClient {
     return this.token ? { Authorization: `Bearer ${this.token}` } : {};
   }
 
+  /**
+   * Validate a single URL path segment (a node key, edge type, or property
+   * field name that will be percent-encoded into a URL path).
+   *
+   * Rejects `.` and `..` because fetch normalises those path segments away
+   * (`/node/./edges` becomes `/node/edges`, silently querying the wrong route).
+   * Encoding them as `%2E` / `%2E%2E` does not help — fetch normalises those
+   * too. Also catches lone-surrogate strings, which would throw a raw
+   * `URIError` from `encodeURIComponent`; re-throws as {@link MushroomError}.
+   *
+   * @throws {@link MushroomError}
+   */
+  private checkPathSeg(seg: string): void {
+    if (seg === "." || seg === "..") {
+      throw new MushroomError(
+        `"${seg}" is not a valid path segment — fetch normalises it away`,
+      );
+    }
+    try {
+      encodeURIComponent(seg);
+    } catch {
+      // encodeURIComponent throws URIError for lone Unicode surrogates.
+      throw new MushroomError(
+        "key or field name contains an invalid Unicode character (lone surrogate)",
+      );
+    }
+  }
+
   /**
    * Execute a fetch and decode the JSON body.
+   *
+   * Reads the response as text first so that an empty or plain-text error body
+   * (e.g. HTTP 404 with `content-length: 0`, or a 408/413/415 plain-text body)
+   * produces `MushroomError("HTTP <status>")` instead of a raw `SyntaxError`.
+   *
    * Throws {@link MushroomError} on non-2xx responses.
    */
   private async fetchJson<T>(
@@ -144,8 +227,14 @@ export class MushroomClient {
         ...(init?.headers ?? {}),
       },
     });
+    const text = await resp.text();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const body: any = await resp.json();
+    let body: any;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = null;
+    }
     if (!resp.ok) {
       const detail: string =
         typeof body?.error === "string" ? body.error : `HTTP ${resp.status}`;
@@ -175,6 +264,9 @@ export class MushroomClient {
       body: JSON.stringify({
         cypher,
         ...(opts?.params ? { params: opts.params } : {}),
+        ...(opts?.as_of !== undefined ? { as_of: opts.as_of } : {}),
+        ...(opts?.mask ? { mask: opts.mask } : {}),
+        ...(opts?.namespace ? { namespace: opts.namespace } : {}),
       }),
     });
   }
@@ -282,6 +374,7 @@ export class MushroomClient {
    * @throws {@link MushroomError} on `KeyNotFound` (old key) or `DuplicateKey` (new key taken).
    */
   async renameNode(oldKey: string, newKey: string): Promise<void> {
+    this.checkPathSeg(oldKey);
     await this.fetchJson(`/nodes/${encodeURIComponent(oldKey)}/rename`, {
       method: "POST",
       body: JSON.stringify({ new_key: newKey }),
@@ -327,17 +420,24 @@ export class MushroomClient {
    * (unknown key). Other HTTP errors throw {@link MushroomError}.
    */
   async node(key: string): Promise<NodeInfo | null> {
+    this.checkPathSeg(key);
     const resp = await fetch(this.url(`/node/${encodeURIComponent(key)}`), {
       headers: {
         Accept: "application/json",
         ...this.authHeaders(),
       },
     });
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const body: any = await resp.json();
     if (resp.status === 404) {
       return null;
     }
+    const text = await resp.text();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let body: any;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = null;
+    }
     if (!resp.ok) {
       const detail: string =
         typeof body?.error === "string" ? body.error : `HTTP ${resp.status}`;
@@ -356,6 +456,7 @@ export class MushroomClient {
     key: string,
     opts?: { depth?: number },
   ): Promise<Neighborhood> {
+    this.checkPathSeg(key);
     const qs = new URLSearchParams();
     if (opts?.depth !== undefined) {
       qs.set("depth", String(opts.depth));
@@ -367,6 +468,313 @@ export class MushroomClient {
     return this.fetchJson<Neighborhood>(path);
   }
 
+  /**
+   * Get server liveness.
+   *
+   * Wraps `GET /health`. An unauthenticated caller receives only `{ ok: true }`.
+   * A full-access token also receives `nodes`, `edges` and `addr`.
+   */
+  async health(): Promise<HealthReport> {
+    return this.fetchJson<HealthReport>("/health");
+  }
+
+  /**
+   * Get server-wide runtime metrics.
+   *
+   * Wraps `GET /metrics`. Returns node/edge counts, WAL size, RSS, uptime
+   * and a slow-query ring buffer. Requires a full-access token; role-bound
+   * tokens receive 403.
+   */
+  async metrics(): Promise<MetricsReport> {
+    return this.fetchJson<MetricsReport>("/metrics");
+  }
+
+  /**
+   * Vector kNN search.
+   *
+   * Wraps `POST /find_similar`. Returns up to `k` nodes whose stored value for
+   * `field` has cosine similarity ≥ `min` to the query `vector`. Results are
+   * sorted by similarity descending.
+   *
+   * @param opts  Query options — `field` and `vector` are required.
+   * @returns     `{ hits: [node_key, similarity][] }`
+   */
+  async findSimilar(opts: FindSimilarOptions): Promise<FindSimilarResult> {
+    return this.fetchJson<FindSimilarResult>("/find_similar", {
+      method: "POST",
+      body: JSON.stringify(opts),
+    });
+  }
+
+  /**
+   * Create a new node.
+   *
+   * Wraps `POST /nodes`. This is an **insert**, not an upsert. If a node with
+   * the same `key` already exists the server responds with 400
+   * "duplicate node key: <key>" and this method throws {@link MushroomError}.
+   *
+   * @param label  Node label.
+   * @param key    Node key — must be unique in the store.
+   * @param props  Optional property map. Null values are silently dropped.
+   * @param namespace  Optional namespace to assign the node to.
+   */
+  async createNode(
+    label: string,
+    key: string,
+    props?: Record<string, import("./types.js").CellValue>,
+    namespace?: string,
+  ): Promise<CreateNodeResult> {
+    return this.fetchJson<CreateNodeResult>("/nodes", {
+      method: "POST",
+      body: JSON.stringify({
+        label,
+        key,
+        ...(props ? { props } : {}),
+        ...(namespace ? { namespace } : {}),
+      }),
+    });
+  }
+
+  /**
+   * Delete a node by key.
+   *
+   * Wraps `DELETE /node/{key}`. The dense id is freed; all edges attached to
+   * this node are also removed. Throws {@link MushroomError} when the key does
+   * not exist.
+   *
+   * @param key  The node key to delete.
+   */
+  async deleteNode(key: string): Promise<void> {
+    this.checkPathSeg(key);
+    await this.fetchJson(`/node/${encodeURIComponent(key)}`, { method: "DELETE" });
+  }
+
+  /**
+   * List all edges attached to a node.
+   *
+   * Wraps `GET /node/{key}/edges`. Returns both asserted and derived edges in
+   * both directions. Throws {@link MushroomError} (404) when the key does not
+   * exist.
+   *
+   * @param key   The node key.
+   * @param opts  Optional filters:
+   *   - `mask` — node-key allow-list; only edges whose **other** endpoint is
+   *     in the list are returned (`key` itself need not be). Must be non-empty
+   *     (an empty array throws {@link MushroomError}). A key must not contain
+   *     a comma, be empty, or have surrounding whitespace: the server splits
+   *     on commas and trims (use a `query()` with `mask` for such keys).
+   *   - `stub_hidden` — when `true` and `mask` is set, edges to masked-out
+   *     endpoints are **included** rather than omitted; those endpoints are
+   *     returned as `{ key: string; restricted: true }` stubs rather than
+   *     plain key strings. Without a mask this option is silently ignored by
+   *     the server. Note that `as_of` (time-travel) does not compose with
+   *     `stub_hidden`; the server rejects that combination.
+   */
+  async nodeEdges(
+    key: string,
+    opts?: { mask?: string[]; stub_hidden?: boolean },
+  ): Promise<NodeEdgesResult> {
+    this.checkPathSeg(key);
+    const qs = new URLSearchParams();
+    if (opts?.mask !== undefined) {
+      if (opts.mask.length === 0) {
+        throw new MushroomError(
+          "nodeEdges mask must not be empty — an empty allow-list is ambiguous; " +
+          "omit mask to return all edges, or use query() with mask:[] to hide all nodes",
+        );
+      }
+      for (const k of opts.mask) {
+        if (k === "" || k !== k.trim()) {
+          throw new MushroomError(
+            `nodeEdges mask key ${JSON.stringify(k)} is empty or has surrounding ` +
+            "whitespace — the server trims each key, so it would match nothing or " +
+            "remove the mask altogether",
+          );
+        }
+        if (k.includes(",")) {
+          throw new MushroomError(
+            `nodeEdges mask key "${k}" contains a comma — the server splits on commas ` +
+            "and cannot express a key with one; use query() with mask for such keys",
+          );
+        }
+      }
+      qs.set("mask", opts.mask.join(","));
+    }
+    if (opts?.stub_hidden !== undefined) {
+      qs.set("stub_hidden", String(opts.stub_hidden));
+    }
+    const query = qs.toString();
+    const path = `/node/${encodeURIComponent(key)}/edges${query ? `?${query}` : ""}`;
+    return this.fetchJson<NodeEdgesResult>(path);
+  }
+
+  /**
+   * Get WAL change history for a node.
+   *
+   * Wraps `GET /node/{key}/history`. Returns the sequence of WAL entries that
+   * touched this node, oldest first. Throws {@link MushroomError} (404) when
+   * the key does not exist.
+   *
+   * @param key  The node key.
+   */
+  async nodeHistory(key: string): Promise<NodeHistoryResult> {
+    this.checkPathSeg(key);
+    return this.fetchJson<NodeHistoryResult>(
+      `/node/${encodeURIComponent(key)}/history`,
+    );
+  }
+
+  /**
+   * Get edge lifecycle between two nodes.
+   *
+   * Wraps `GET /history/edge?a=&b=`. Returns every time an edge was added or
+   * retracted between `a` and `b` (in either direction, any edge type).
+   *
+   * @param a  Key of the first node.
+   * @param b  Key of the second node.
+   */
+  async edgeHistory(a: string, b: string): Promise<EdgeHistoryResult> {
+    const qs = new URLSearchParams({ a, b });
+    return this.fetchJson<EdgeHistoryResult>(`/history/edge?${qs.toString()}`);
+  }
+
+  /**
+   * Point-in-time edge check.
+   *
+   * Wraps `GET /history/was_linked?a=&b=&edge_type=&at_commit=`. Returns
+   * whether any edge of `edgeType` existed between `a` and `b` at the given
+   * WAL commit index. Throws {@link MushroomError} (400) when `atCommit` is
+   * outside the visible horizon.
+   *
+   * @param a         Key of the first node.
+   * @param b         Key of the second node.
+   * @param edgeType  The edge type to check.
+   * @param atCommit  WAL commit index (integer) or an RFC 3339 date string
+   *                  (e.g. `"2026-01-01T00:00:00Z"`); the server resolves the
+   *                  date to the nearest commit at or before that time.
+   */
+  async wasLinked(
+    a: string,
+    b: string,
+    edgeType: string,
+    atCommit: number | string,
+  ): Promise<WasLinkedResult> {
+    const qs = new URLSearchParams({
+      a,
+      b,
+      edge_type: edgeType,
+      at_commit: String(atCommit),
+    });
+    return this.fetchJson<WasLinkedResult>(
+      `/history/was_linked?${qs.toString()}`,
+    );
+  }
+
+  /**
+   * Create an explicit edge.
+   *
+   * Wraps `POST /edges`. Both endpoint nodes must already exist; use
+   * {@link upsertEdge} to auto-create missing endpoints.
+   *
+   * @param type  Edge type string.
+   * @param src   Source node key.
+   * @param dst   Destination node key.
+   */
+  async createEdge(type: string, src: string, dst: string): Promise<void> {
+    await this.fetchJson("/edges", {
+      method: "POST",
+      body: JSON.stringify({ type, src, dst }),
+    });
+  }
+
+  /**
+   * Delete an explicit edge.
+   *
+   * Wraps `DELETE /edges/{etype}/{src}/{dst}`. Returns silently when the edge
+   * does not exist (idempotent — the server answers 200). Throws
+   * {@link MushroomError} only when an endpoint node is missing
+   * (400 "node key not found: <key>").
+   *
+   * @param etype  Edge type string.
+   * @param src    Source node key.
+   * @param dst    Destination node key.
+   */
+  async deleteEdge(etype: string, src: string, dst: string): Promise<void> {
+    this.checkPathSeg(etype);
+    this.checkPathSeg(src);
+    this.checkPathSeg(dst);
+    await this.fetchJson(
+      `/edges/${encodeURIComponent(etype)}/${encodeURIComponent(src)}/${encodeURIComponent(dst)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  /**
+   * Set a property on a node.
+   *
+   * Wraps `PUT /node/{key}/prop/{field}`. Creates the property if absent,
+   * replaces its value if present. The value must be a non-null scalar, array
+   * or object; a null value is rejected with 400.
+   *
+   * @param key    Node key.
+   * @param field  Property field name.
+   * @param value  New property value (non-null).
+   */
+  async setNodeProp(
+    key: string,
+    field: string,
+    value: import("./types.js").CellValue,
+  ): Promise<void> {
+    this.checkPathSeg(key);
+    this.checkPathSeg(field);
+    await this.fetchJson(
+      `/node/${encodeURIComponent(key)}/prop/${encodeURIComponent(field)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify({ value }),
+      },
+    );
+  }
+
+  /**
+   * Remove a property from a node.
+   *
+   * Wraps `DELETE /node/{key}/prop/{field}`. Succeeds even when the property
+   * does not exist (the server is idempotent on prop removal).
+   *
+   * @param key    Node key.
+   * @param field  Property field name to remove.
+   */
+  async removeNodeProp(key: string, field: string): Promise<void> {
+    this.checkPathSeg(key);
+    this.checkPathSeg(field);
+    await this.fetchJson(
+      `/node/${encodeURIComponent(key)}/prop/${encodeURIComponent(field)}`,
+      { method: "DELETE" },
+    );
+  }
+
+  /**
+   * Trigger a consistent backup of the database.
+   *
+   * Wraps `POST /backup`. The server holds a read lock for the duration of
+   * the file copies. `dest` is a path relative to the backup root
+   * (`MUSHROOMDB_BACKUP_DIR`, or the server's working directory); `..`
+   * segments are rejected. Requires a full-access token.
+   *
+   * When `verified` is false in the response, the server answered 500 and
+   * throws {@link MushroomError}; the backup was written but the post-copy
+   * verification failed.
+   *
+   * @param dest  Destination directory name or relative path.
+   */
+  async backup(dest: string): Promise<BackupReport> {
+    return this.fetchJson<BackupReport>("/backup", {
+      method: "POST",
+      body: JSON.stringify({ dest }),
+    });
+  }
+
   // -------------------------------------------------------------------------
   // WebSocket
   // -------------------------------------------------------------------------
@@ -407,6 +815,50 @@ export class MushroomClient {
     }
     return wsSubscribe(url, opts, onEvent);
   }
+
+  /**
+   * Subscribe to the raw mutation event stream over WebSocket (`GET /watch`).
+   *
+   * The server sends `{"subscribed":true}` immediately after the upgrade; no
+   * client subscribe message is required. After that, {@link MutationEvent}
+   * frames arrive for every write to the store.
+   *
+   * Unlike `/subscribe`, the `/watch` stream carries every mutation (nodes,
+   * edges, rules, batches, ingests) without filtering.
+   *
+   * **No auto-reconnect in v1.** Reconnect manually when the connection drops.
+   *
+   * **Always await `handle.close()`** to avoid dangling handles in tests.
+   *
+   * **Node.js < 21**: pass `wsConstructor` — see {@link WatchOptions}.
+   *
+   * @example
+   * ```ts
+   * import WS from 'ws';
+   * const handle = await client.watch(
+   *   { wsConstructor: WS as WsConstructor },
+   *   (ev) => console.log(ev),
+   * );
+   * await handle.close();
+   * ```
+   */
+  watch(
+    opts: WatchOptions,
+    onEvent: (event: MutationEvent) => void,
+  ): Promise<WatchHandle> {
+    let url = this.wsUrl("/watch");
+    if (this.token) {
+      url += `?token=${encodeURIComponent(this.token)}`;
+    }
+    return wsWatch(url, opts, onEvent);
+  }
 }
 
-export type { SubscribeHandle, SubscribeOptions, WsConstructor };
+export type {
+  MutationEvent,
+  SubscribeHandle,
+  SubscribeOptions,
+  WatchHandle,
+  WatchOptions,
+  WsConstructor,
+};

package/src/index.ts

@@ -8,16 +8,30 @@ export { MushroomClient, MushroomError } from "./client.js";
 export type {
   AlgoDir,
   AlgoReport,
+  BackupReport,
   CellValue,
   ClientOptions,
+  CreateNodeResult,
   DegreeConfig,
   DegreeReport,
+  EdgeHistoryEntry,
+  EdgeHistoryResult,
+  EdgeInfo,
   Explanation,
+  FindSimilarOptions,
+  FindSimilarResult,
+  HealthReport,
+  HistoryChange,
+  HistoryEntry,
   IngestEdge,
   IngestOptions,
   IngestReport,
   IngestRequest,
+  MetricsReport,
+  MutationEvent,
   Neighborhood,
+  NodeEdgesResult,
+  NodeHistoryResult,
   NodeInfo,
   PageRankConfig,
   PageRankReport,
@@ -30,8 +44,10 @@ export type {
   RulePredicate,
   RuleStats,
   RuleSuggestion,
+  SlowQueryEntry,
   Stats,
   SuggestReport,
+  WasLinkedResult,
   WccConfig,
   WccReport,
 } from "./client.js";
@@ -42,6 +58,8 @@ export type {
 export type {
   SubscribeHandle,
   SubscribeOptions,
+  WatchHandle,
+  WatchOptions,
   WsConstructor,
   WsLike,
 } from "./ws.js";