mushroomdb-client 0.7.2 → 0.8.1
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 +145 -2
- package/dist/client.d.ts +239 -4
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +343 -4
- package/dist/client.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/types.d.ts +339 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/dist/ws.d.ts +51 -2
- package/dist/ws.d.ts.map +1 -1
- package/dist/ws.js +123 -0
- package/dist/ws.js.map +1 -1
- package/package.json +1 -1
- package/src/client.ts +456 -4
- package/src/index.ts +18 -0
- package/src/types.ts +334 -0
- package/src/ws.ts +165 -2
package/README.md
CHANGED
|
@@ -153,6 +153,16 @@ acquires the write lock automatically. Returns `{ columns: string[], rows: CellV
|
|
|
153
153
|
`opts.params` — bound parameters; values must be JSON scalars
|
|
154
154
|
(`string | number | boolean`).
|
|
155
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
|
+
|
|
156
166
|
### `client.ingest(req) → Promise<IngestReport>`
|
|
157
167
|
|
|
158
168
|
Bulk-ingest nodes and optional edges. `req.label`, `req.rows` are required.
|
|
@@ -211,6 +221,139 @@ All config fields are optional; server defaults apply.
|
|
|
211
221
|
|
|
212
222
|
Open a WebSocket subscription. Returns a handle with `close(): Promise<void>`.
|
|
213
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
|
+
|
|
214
357
|
---
|
|
215
358
|
|
|
216
359
|
## Error handling
|
|
@@ -273,8 +416,8 @@ await client.query("CREATE (n:Widget {id: 'w1', name: 'Sprocket'})");
|
|
|
273
416
|
|
|
274
417
|
| Feature | Browser | Node 18+ |
|
|
275
418
|
|---------|---------|----------|
|
|
276
|
-
| `query`, `ingest`, `stats`, `suggest`, `algo`, `explain`, `createRule`, `renameNode`, `upsertEdge`, `node`, `neighborhood` | Yes (uses `fetch`) | Yes |
|
|
277
|
-
| `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 |
|
|
278
421
|
|
|
279
422
|
---
|
|
280
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
|
package/dist/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,aAAa,EAEb,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,aAAa,EAEb,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,UAAU,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,cAAc,EACd,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,OAAO,EACP,aAAa,EACb,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,EACL,aAAa,EACb,eAAe,EACf,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEpE,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C;;;;OAIG;IACH,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,EAIhD;IAMD,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,YAAY;IAgBpB;;;;;;;;OAQG;YACW,SAAS;IAiCvB;;;;;;;;;;OAUG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAWrE;IAED;;;;;;;;OAQG;IACG,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAKtD;IAED;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,CAE5B;IAED;;;;;;;;OAQG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,CAEtC;IAED;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACzE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAczE;;;;OAIG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAG1D;IAED;;;;;OAKG;IACG,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5C;IAED;;;;;;;;OAQG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9D;IAED;;;;;;;;;;;OAWG;IACG,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC,CAa5D;IAED;;;;;OAKG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyBhD;IAED;;;;;OAKG;IACG,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,YAAY,CAAC,CAWvB;IAED;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAEpC;IAED;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,CAEtC;IAED;;;;;;;;;OASG;IACG,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAKtE;IAED;;;;;;;;;;;OAWG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,YAAY,EAAE,SAAS,CAAC,EACtD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAU3B;IAED;;;;;;;;OAQG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3C;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,SAAS,CACb,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAChD,OAAO,CAAC,eAAe,CAAC,CAiC1B;IAED;;;;;;;;OAQG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAKzD;IAED;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAGlE;IAED;;;;;;;;;;;;;;OAcG;IACG,SAAS,CACb,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,OAAO,CAAC,eAAe,CAAC,CAU1B;IAED;;;;;;;;;OASG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKtE;IAED;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvE;IAED;;;;;;;;;;OAUG;IACG,WAAW,CACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,YAAY,EAAE,SAAS,GACpC,OAAO,CAAC,IAAI,CAAC,CAUf;IAED;;;;;;;;OAQG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9D;IAED;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAKhD;IAMD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CACP,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,YAAY,EAAE,OAAO,KAAK,IAAI,GACrD,OAAO,CAAC,eAAe,CAAC,CAM1B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CACH,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GACtC,OAAO,CAAC,WAAW,CAAC,CAMtB;CACF;AAED,YAAY,EACV,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,aAAa,GACd,CAAC"}
|