mushroomdb-client 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,11 +3,20 @@
3
3
  TypeScript client for the [mushroomdb](https://github.com/MatthewSherlin/mushroomdb) graph database.
4
4
  Wraps the HTTP and WebSocket API exposed by `mushroomdb serve`.
5
5
 
6
+ The methods at a glance, and the routes the client leaves to `fetch`, are on the
7
+ [documentation site](https://matthewsherlin.github.io/mushroomdb/docs/typescript.html).
8
+
6
9
  > Published to npm as [`mushroomdb-client`](https://www.npmjs.com/package/mushroomdb-client) on every release. Installing from the repo path (see below) is for working against an unreleased server.
7
10
 
8
11
  ---
9
12
 
10
- ## Installation (from repo)
13
+ ## Installation
14
+
15
+ ```sh
16
+ npm install mushroomdb-client
17
+ ```
18
+
19
+ To use a checkout instead, while working on the client itself:
11
20
 
12
21
  ```sh
13
22
  npm install /path/to/graph-db/clients/typescript
@@ -144,6 +153,16 @@ acquires the write lock automatically. Returns `{ columns: string[], rows: CellV
144
153
  `opts.params` — bound parameters; values must be JSON scalars
145
154
  (`string | number | boolean`).
146
155
 
156
+ `opts.as_of` — time-travel: run the query on the graph as it was at this WAL
157
+ commit index (0 to `commit_seq − 1` inclusive, read-only). Obtain a commit
158
+ index from the `commit` field of a `nodeHistory`/`edgeHistory` entry.
159
+
160
+ `opts.mask` — node-key allow-list: restrict visible nodes to these keys.
161
+ Makes the query read-only.
162
+
163
+ `opts.namespace` — restrict results to this namespace, intersecting with
164
+ `mask` and any role. Makes the query read-only.
165
+
147
166
  ### `client.ingest(req) → Promise<IngestReport>`
148
167
 
149
168
  Bulk-ingest nodes and optional edges. `req.label`, `req.rows` are required.
@@ -167,6 +186,16 @@ Wires `GET /explain?a=&b=`. Returns rule-derived edges between two node keys.
167
186
 
168
187
  Wires `POST /rules` with a `RuleDef` JSON body.
169
188
 
189
+ ### `client.renameNode(oldKey, newKey) → Promise<void>`
190
+
191
+ Wires `POST /nodes/{key}/rename`. Changes a node's key. Throws when the old key does not exist
192
+ (the server answers 404) or the new one is taken (409).
193
+
194
+ ### `client.upsertEdge(edgeType, src, dst, placeholderLabel) → Promise<{ nodes_created, edge_inserted }>`
195
+
196
+ Wires `POST /edges/upsert`. Creates the edge, and creates whichever endpoint is missing as a node
197
+ of `placeholderLabel`.
198
+
170
199
  ### `client.node(key) → Promise<NodeInfo | null>`
171
200
 
172
201
  Wires `GET /node/{key}`. Returns `null` for an unknown key (HTTP 404).
@@ -192,6 +221,139 @@ All config fields are optional; server defaults apply.
192
221
 
193
222
  Open a WebSocket subscription. Returns a handle with `close(): Promise<void>`.
194
223
 
224
+ ### `client.health() → Promise<HealthReport>`
225
+
226
+ Wires `GET /health`. Returns `{ ok, nodes?, edges?, addr? }`. Full node/edge counts are
227
+ only included when the client carries a valid full-access token.
228
+
229
+ ### `client.metrics() → Promise<MetricsReport>`
230
+
231
+ Wires `GET /metrics`. Returns live runtime counters — node/edge counts, WAL size, RSS,
232
+ uptime — and a configurable slow-query log. Requires full-access auth.
233
+
234
+ ### `client.findSimilar(opts) → Promise<FindSimilarResult>`
235
+
236
+ Wires `POST /find_similar`. Approximate nearest-neighbour search over a vector property.
237
+ `opts.field` and `opts.vector` are required; `opts.k`, `opts.min`, `opts.label`, `opts.mask`,
238
+ `opts.exact` are optional. Returns `{ hits: [key, score][] }`.
239
+
240
+ `opts.where` — a `PropPredicate` applied after the search:
241
+ ```ts
242
+ // equality
243
+ { field: 'status', eq: 'published' }
244
+ // set membership
245
+ { field: 'status', in: ['draft', 'review'] }
246
+ ```
247
+
248
+ ### `client.createNode(label, key, props?, namespace?) → Promise<CreateNodeResult>`
249
+
250
+ Wires `POST /nodes`. Inserts a node with the given label and key. This is an
251
+ **insert**, not an upsert — a duplicate key throws `MushroomError`. Optional
252
+ `props` map sets initial properties. Optional `namespace` scopes the node.
253
+ Returns `{ ok, nodes, edges }`.
254
+
255
+ ### `client.deleteNode(key) → Promise<void>`
256
+
257
+ Wires `DELETE /node/{key}`. Throws `MushroomError` when the node does not exist.
258
+
259
+ ### `client.nodeEdges(key, opts?) → Promise<NodeEdgesResult>`
260
+
261
+ Wires `GET /node/{key}/edges`. Returns `{ edges: [{ edge_type, src_key, dst_key, derived }] }`.
262
+ Throws `MushroomError` (404) when the key does not exist.
263
+
264
+ `opts.mask` — node-key allow-list (non-empty string array; no key that is empty, has
265
+ surrounding whitespace or contains a comma). Only edges whose **other** endpoint is in the
266
+ list are returned; `key` itself need not be. A list or key the server could not read as
267
+ written throws `MushroomError`.
268
+
269
+ `opts.stub_hidden` — when `true` **and** `mask` is set, edges to masked-out
270
+ endpoints are included; those endpoints appear as
271
+ `{ key: string; restricted: true }` rather than a plain string. Without `mask`
272
+ this option is silently ignored by the server.
273
+
274
+ ### `client.nodeHistory(key) → Promise<NodeHistoryResult>`
275
+
276
+ Wires `GET /node/{key}/history`. Returns a per-commit change log: insertions, property
277
+ changes and edge events. Throws `MushroomError` (404) when the key does not exist.
278
+
279
+ ### `client.edgeHistory(a, b) → Promise<EdgeHistoryResult>`
280
+
281
+ Wires `GET /history/edge?a=&b=`. Returns every commit where an edge between the two nodes
282
+ was added or retracted.
283
+
284
+ ### `client.wasLinked(a, b, edgeType, atCommit) → Promise<WasLinkedResult>`
285
+
286
+ Wires `GET /history/was_linked`. Returns `{ a, b, edge_type, at_commit, linked }` — whether
287
+ the named edge existed at the given commit index.
288
+
289
+ `atCommit` accepts an integer commit index **or** an RFC 3339 date string
290
+ (`"2026-01-15T00:00:00Z"`); the server resolves the date to the nearest commit at
291
+ or before that instant.
292
+
293
+ ### `client.createEdge(type, src, dst) → Promise<void>`
294
+
295
+ Wires `POST /edges`. Inserts an explicit (non-derived) edge. Both endpoint nodes must already
296
+ exist; the call throws `MushroomError` if either is missing.
297
+
298
+ ### `client.deleteEdge(type, src, dst) → Promise<void>`
299
+
300
+ Wires `DELETE /edges/{etype}/{src}/{dst}`. Returns silently when the edge does
301
+ not exist (idempotent). Throws `MushroomError` only when an endpoint node is
302
+ missing.
303
+
304
+ ### `client.setNodeProp(key, field, value) → Promise<void>`
305
+
306
+ Wires `PUT /node/{key}/prop/{field}`. Sets or overwrites one property. `value`
307
+ must be JSON-serialisable; scalars (`string | number | boolean`), arrays, and
308
+ objects are all accepted. `null` is rejected by the server.
309
+
310
+ ### `client.removeNodeProp(key, field) → Promise<void>`
311
+
312
+ Wires `DELETE /node/{key}/prop/{field}`. Removes the named property from the node.
313
+
314
+ ### `client.backup(dest) → Promise<BackupReport>`
315
+
316
+ Wires `POST /backup`. Copies the store to `dest` (a server-side path) and verifies it.
317
+ Returns `{ files, bytes, verified }`. Throws `MushroomError` when verification fails.
318
+
319
+ ### `client.watch(opts, onEvent) → Promise<WatchHandle>`
320
+
321
+ Open a `GET /watch` WebSocket and stream raw `MutationEvent`s. The server sends every
322
+ committed mutation — node inserts/deletes, property changes, edge inserts/deletes, rule
323
+ lifecycle and ingest events — as an externally-tagged JSON frame.
324
+
325
+ Returns a handle with `close(): Promise<void>`. A server older than 0.8 does not answer a
326
+ close on `/watch`, so `close()` resolves within 3 s whether or not the handshake completes.
327
+
328
+ `opts.onClose` — called once when the WebSocket closes, whether via `handle.close()` or
329
+ because the server dropped the connection. Use it as a signal to reconnect.
330
+
331
+ Against a server older than 0.8, the `ws` package's socket is force-closed when the 3 s
332
+ bound passes. The standard `WebSocket` has no force-close: `close()` still resolves and
333
+ `onClose` still fires, but the socket can keep a Node process alive until the runtime's
334
+ own close timeout.
335
+
336
+ ```ts
337
+ import WS from 'ws'; // Node < 21
338
+ import type { WsConstructor, MutationEvent } from 'mushroomdb-client';
339
+
340
+ const handle = await client.watch(
341
+ { wsConstructor: WS as unknown as WsConstructor },
342
+ (ev: MutationEvent) => {
343
+ if ('node_inserted' in ev) {
344
+ console.log('new node:', ev.node_inserted.key);
345
+ }
346
+ },
347
+ );
348
+
349
+ // ... do work ...
350
+
351
+ await handle.close();
352
+ ```
353
+
354
+ A `{ lagged: N }` frame means the broadcast channel overflowed and `N` events were dropped;
355
+ re-read any state your consumer depends on to recover.
356
+
195
357
  ---
196
358
 
197
359
  ## Error handling
@@ -254,8 +416,8 @@ await client.query("CREATE (n:Widget {id: 'w1', name: 'Sprocket'})");
254
416
 
255
417
  | Feature | Browser | Node 18+ |
256
418
  |---------|---------|----------|
257
- | `query`, `ingest`, `stats`, `suggest`, `algo`, `explain`, `createRule`, `node`, `neighborhood` | Yes (uses `fetch`) | Yes |
258
- | `subscribe` | Yes (uses global `WebSocket`) | Requires `wsConstructor` option + `ws` package |
419
+ | `query`, `ingest`, `stats`, `suggest`, `algo`, `explain`, `createRule`, `renameNode`, `upsertEdge`, `node`, `neighborhood`, `health`, `metrics`, `findSimilar`, `createNode`, `deleteNode`, `nodeEdges`, `nodeHistory`, `edgeHistory`, `wasLinked`, `createEdge`, `deleteEdge`, `setNodeProp`, `removeNodeProp`, `backup` | Yes (uses `fetch`) | Yes |
420
+ | `subscribe`, `watch` | Yes (uses global `WebSocket`) | Requires `wsConstructor` option + `ws` package |
259
421
 
260
422
  ---
261
423
 
package/dist/client.d.ts CHANGED
@@ -11,9 +11,9 @@
11
11
  * console.log(result.columns, result.rows);
12
12
  * ```
13
13
  */
14
- import { MushroomError, type DegreeConfig, type DegreeReport, type Explanation, type IngestReport, type IngestRequest, type Neighborhood, type NodeInfo, type PageRankConfig, type PageRankReport, type QueryResult, type RuleDef, type Stats, type SuggestReport, type WccConfig, type WccReport } from "./types.js";
15
- import { type SubscribeHandle, type SubscribeOptions, type WsConstructor } from "./ws.js";
16
- export type { AlgoDir, AlgoReport, CellValue, DegreeConfig, DegreeReport, Explanation, IngestEdge, IngestOptions, IngestReport, IngestRequest, Neighborhood, NodeInfo, PageRankConfig, PageRankReport, PredicateKind, PredicateSummary, QueryResult, RuleDef, RulePredicate, RuleStats, RuleSuggestion, Stats, SuggestReport, WccConfig, WccReport, } from "./types.js";
14
+ import { MushroomError, 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, type QueryResult, type RuleDef, type Stats, type SuggestReport, type WasLinkedResult, type WccConfig, type WccReport } from "./types.js";
15
+ import { type MutationEvent, type SubscribeHandle, type SubscribeOptions, type WatchHandle, type WatchOptions, type WsConstructor } from "./ws.js";
16
+ 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";
17
17
  export { MushroomError };
18
18
  /** Optional constructor flags for {@link MushroomClient}. */
19
19
  export interface ClientOptions {
@@ -29,6 +29,25 @@ export type QueryParams = Record<string, string | number | boolean>;
29
29
  export interface QueryOptions {
30
30
  /** Bound parameters. Values must be JSON scalars (string | number | boolean). */
31
31
  params?: QueryParams;
32
+ /**
33
+ * Time-travel: run the query against the graph as it existed at this WAL
34
+ * commit index (read-only). Valid values are `0` to `commit_seq − 1`
35
+ * inclusive; passing `commit_seq` itself yields a range error. Obtain a
36
+ * commit index from the `commit` field of a `nodeHistory`/`edgeHistory`
37
+ * entry, or compute `(await client.metrics()).commit_seq - 1` for the most
38
+ * recent committed state.
39
+ */
40
+ as_of?: number;
41
+ /**
42
+ * Node-key allow-list: restrict visible nodes to these keys. The query sees
43
+ * only nodes whose key is in this set. Makes the query read-only.
44
+ */
45
+ mask?: string[];
46
+ /**
47
+ * Namespace to restrict results to. Intersects with `mask` and any role.
48
+ * Makes the query read-only.
49
+ */
50
+ namespace?: string;
32
51
  }
33
52
  /**
34
53
  * HTTP + WebSocket client for mushroomdb.
@@ -53,8 +72,26 @@ export declare class MushroomClient {
53
72
  private url;
54
73
  private wsUrl;
55
74
  private authHeaders;
75
+ /**
76
+ * Validate a single URL path segment (a node key, edge type, or property
77
+ * field name that will be percent-encoded into a URL path).
78
+ *
79
+ * Rejects `.` and `..` because fetch normalises those path segments away
80
+ * (`/node/./edges` becomes `/node/edges`, silently querying the wrong route).
81
+ * Encoding them as `%2E` / `%2E%2E` does not help — fetch normalises those
82
+ * too. Also catches lone-surrogate strings, which would throw a raw
83
+ * `URIError` from `encodeURIComponent`; re-throws as {@link MushroomError}.
84
+ *
85
+ * @throws {@link MushroomError}
86
+ */
87
+ private checkPathSeg;
56
88
  /**
57
89
  * Execute a fetch and decode the JSON body.
90
+ *
91
+ * Reads the response as text first so that an empty or plain-text error body
92
+ * (e.g. HTTP 404 with `content-length: 0`, or a 408/413/415 plain-text body)
93
+ * produces `MushroomError("HTTP <status>")` instead of a raw `SyntaxError`.
94
+ *
58
95
  * Throws {@link MushroomError} on non-2xx responses.
59
96
  */
60
97
  private fetchJson;
@@ -170,6 +207,177 @@ export declare class MushroomClient {
170
207
  neighborhood(key: string, opts?: {
171
208
  depth?: number;
172
209
  }): Promise<Neighborhood>;
210
+ /**
211
+ * Get server liveness.
212
+ *
213
+ * Wraps `GET /health`. An unauthenticated caller receives only `{ ok: true }`.
214
+ * A full-access token also receives `nodes`, `edges` and `addr`.
215
+ */
216
+ health(): Promise<HealthReport>;
217
+ /**
218
+ * Get server-wide runtime metrics.
219
+ *
220
+ * Wraps `GET /metrics`. Returns node/edge counts, WAL size, RSS, uptime
221
+ * and a slow-query ring buffer. Requires a full-access token; role-bound
222
+ * tokens receive 403.
223
+ */
224
+ metrics(): Promise<MetricsReport>;
225
+ /**
226
+ * Vector kNN search.
227
+ *
228
+ * Wraps `POST /find_similar`. Returns up to `k` nodes whose stored value for
229
+ * `field` has cosine similarity ≥ `min` to the query `vector`. Results are
230
+ * sorted by similarity descending.
231
+ *
232
+ * @param opts Query options — `field` and `vector` are required.
233
+ * @returns `{ hits: [node_key, similarity][] }`
234
+ */
235
+ findSimilar(opts: FindSimilarOptions): Promise<FindSimilarResult>;
236
+ /**
237
+ * Create a new node.
238
+ *
239
+ * Wraps `POST /nodes`. This is an **insert**, not an upsert. If a node with
240
+ * the same `key` already exists the server responds with 400
241
+ * "duplicate node key: <key>" and this method throws {@link MushroomError}.
242
+ *
243
+ * @param label Node label.
244
+ * @param key Node key — must be unique in the store.
245
+ * @param props Optional property map. Null values are silently dropped.
246
+ * @param namespace Optional namespace to assign the node to.
247
+ */
248
+ createNode(label: string, key: string, props?: Record<string, import("./types.js").CellValue>, namespace?: string): Promise<CreateNodeResult>;
249
+ /**
250
+ * Delete a node by key.
251
+ *
252
+ * Wraps `DELETE /node/{key}`. The dense id is freed; all edges attached to
253
+ * this node are also removed. Throws {@link MushroomError} when the key does
254
+ * not exist.
255
+ *
256
+ * @param key The node key to delete.
257
+ */
258
+ deleteNode(key: string): Promise<void>;
259
+ /**
260
+ * List all edges attached to a node.
261
+ *
262
+ * Wraps `GET /node/{key}/edges`. Returns both asserted and derived edges in
263
+ * both directions. Throws {@link MushroomError} (404) when the key does not
264
+ * exist.
265
+ *
266
+ * @param key The node key.
267
+ * @param opts Optional filters:
268
+ * - `mask` — node-key allow-list; only edges whose **other** endpoint is
269
+ * in the list are returned (`key` itself need not be). Must be non-empty
270
+ * (an empty array throws {@link MushroomError}). A key must not contain
271
+ * a comma, be empty, or have surrounding whitespace: the server splits
272
+ * on commas and trims (use a `query()` with `mask` for such keys).
273
+ * - `stub_hidden` — when `true` and `mask` is set, edges to masked-out
274
+ * endpoints are **included** rather than omitted; those endpoints are
275
+ * returned as `{ key: string; restricted: true }` stubs rather than
276
+ * plain key strings. Without a mask this option is silently ignored by
277
+ * the server. Note that `as_of` (time-travel) does not compose with
278
+ * `stub_hidden`; the server rejects that combination.
279
+ */
280
+ nodeEdges(key: string, opts?: {
281
+ mask?: string[];
282
+ stub_hidden?: boolean;
283
+ }): Promise<NodeEdgesResult>;
284
+ /**
285
+ * Get WAL change history for a node.
286
+ *
287
+ * Wraps `GET /node/{key}/history`. Returns the sequence of WAL entries that
288
+ * touched this node, oldest first. Throws {@link MushroomError} (404) when
289
+ * the key does not exist.
290
+ *
291
+ * @param key The node key.
292
+ */
293
+ nodeHistory(key: string): Promise<NodeHistoryResult>;
294
+ /**
295
+ * Get edge lifecycle between two nodes.
296
+ *
297
+ * Wraps `GET /history/edge?a=&b=`. Returns every time an edge was added or
298
+ * retracted between `a` and `b` (in either direction, any edge type).
299
+ *
300
+ * @param a Key of the first node.
301
+ * @param b Key of the second node.
302
+ */
303
+ edgeHistory(a: string, b: string): Promise<EdgeHistoryResult>;
304
+ /**
305
+ * Point-in-time edge check.
306
+ *
307
+ * Wraps `GET /history/was_linked?a=&b=&edge_type=&at_commit=`. Returns
308
+ * whether any edge of `edgeType` existed between `a` and `b` at the given
309
+ * WAL commit index. Throws {@link MushroomError} (400) when `atCommit` is
310
+ * outside the visible horizon.
311
+ *
312
+ * @param a Key of the first node.
313
+ * @param b Key of the second node.
314
+ * @param edgeType The edge type to check.
315
+ * @param atCommit WAL commit index (integer) or an RFC 3339 date string
316
+ * (e.g. `"2026-01-01T00:00:00Z"`); the server resolves the
317
+ * date to the nearest commit at or before that time.
318
+ */
319
+ wasLinked(a: string, b: string, edgeType: string, atCommit: number | string): Promise<WasLinkedResult>;
320
+ /**
321
+ * Create an explicit edge.
322
+ *
323
+ * Wraps `POST /edges`. Both endpoint nodes must already exist; use
324
+ * {@link upsertEdge} to auto-create missing endpoints.
325
+ *
326
+ * @param type Edge type string.
327
+ * @param src Source node key.
328
+ * @param dst Destination node key.
329
+ */
330
+ createEdge(type: string, src: string, dst: string): Promise<void>;
331
+ /**
332
+ * Delete an explicit edge.
333
+ *
334
+ * Wraps `DELETE /edges/{etype}/{src}/{dst}`. Returns silently when the edge
335
+ * does not exist (idempotent — the server answers 200). Throws
336
+ * {@link MushroomError} only when an endpoint node is missing
337
+ * (400 "node key not found: <key>").
338
+ *
339
+ * @param etype Edge type string.
340
+ * @param src Source node key.
341
+ * @param dst Destination node key.
342
+ */
343
+ deleteEdge(etype: string, src: string, dst: string): Promise<void>;
344
+ /**
345
+ * Set a property on a node.
346
+ *
347
+ * Wraps `PUT /node/{key}/prop/{field}`. Creates the property if absent,
348
+ * replaces its value if present. The value must be a non-null scalar, array
349
+ * or object; a null value is rejected with 400.
350
+ *
351
+ * @param key Node key.
352
+ * @param field Property field name.
353
+ * @param value New property value (non-null).
354
+ */
355
+ setNodeProp(key: string, field: string, value: import("./types.js").CellValue): Promise<void>;
356
+ /**
357
+ * Remove a property from a node.
358
+ *
359
+ * Wraps `DELETE /node/{key}/prop/{field}`. Succeeds even when the property
360
+ * does not exist (the server is idempotent on prop removal).
361
+ *
362
+ * @param key Node key.
363
+ * @param field Property field name to remove.
364
+ */
365
+ removeNodeProp(key: string, field: string): Promise<void>;
366
+ /**
367
+ * Trigger a consistent backup of the database.
368
+ *
369
+ * Wraps `POST /backup`. The server holds a read lock for the duration of
370
+ * the file copies. `dest` is a path relative to the backup root
371
+ * (`MUSHROOMDB_BACKUP_DIR`, or the server's working directory); `..`
372
+ * segments are rejected. Requires a full-access token.
373
+ *
374
+ * When `verified` is false in the response, the server answered 500 and
375
+ * throws {@link MushroomError}; the backup was written but the post-copy
376
+ * verification failed.
377
+ *
378
+ * @param dest Destination directory name or relative path.
379
+ */
380
+ backup(dest: string): Promise<BackupReport>;
173
381
  /**
174
382
  * Subscribe to post-commit events over WebSocket (`GET /subscribe`).
175
383
  *
@@ -197,6 +405,33 @@ export declare class MushroomClient {
197
405
  * ```
198
406
  */
199
407
  subscribe(opts: SubscribeOptions, onEvent: (event: import("./types.js").DbEvent) => void): Promise<SubscribeHandle>;
408
+ /**
409
+ * Subscribe to the raw mutation event stream over WebSocket (`GET /watch`).
410
+ *
411
+ * The server sends `{"subscribed":true}` immediately after the upgrade; no
412
+ * client subscribe message is required. After that, {@link MutationEvent}
413
+ * frames arrive for every write to the store.
414
+ *
415
+ * Unlike `/subscribe`, the `/watch` stream carries every mutation (nodes,
416
+ * edges, rules, batches, ingests) without filtering.
417
+ *
418
+ * **No auto-reconnect in v1.** Reconnect manually when the connection drops.
419
+ *
420
+ * **Always await `handle.close()`** to avoid dangling handles in tests.
421
+ *
422
+ * **Node.js < 21**: pass `wsConstructor` — see {@link WatchOptions}.
423
+ *
424
+ * @example
425
+ * ```ts
426
+ * import WS from 'ws';
427
+ * const handle = await client.watch(
428
+ * { wsConstructor: WS as WsConstructor },
429
+ * (ev) => console.log(ev),
430
+ * );
431
+ * await handle.close();
432
+ * ```
433
+ */
434
+ watch(opts: WatchOptions, onEvent: (event: MutationEvent) => void): Promise<WatchHandle>;
200
435
  }
201
- export type { SubscribeHandle, SubscribeOptions, WsConstructor };
436
+ export type { MutationEvent, SubscribeHandle, SubscribeOptions, WatchHandle, WatchOptions, WsConstructor, };
202
437
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}