@graphrefly/graphrefly 0.1.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/LICENSE +21 -0
- package/README.md +234 -0
- package/dist/chunk-5X3LAO3B.js +1571 -0
- package/dist/chunk-5X3LAO3B.js.map +1 -0
- package/dist/chunk-6W5SGIGB.js +1793 -0
- package/dist/chunk-6W5SGIGB.js.map +1 -0
- package/dist/chunk-CP6MNKAA.js +97 -0
- package/dist/chunk-CP6MNKAA.js.map +1 -0
- package/dist/chunk-HP7OKEOE.js +107 -0
- package/dist/chunk-HP7OKEOE.js.map +1 -0
- package/dist/chunk-KWXPDASV.js +781 -0
- package/dist/chunk-KWXPDASV.js.map +1 -0
- package/dist/chunk-O3PI7W45.js +68 -0
- package/dist/chunk-O3PI7W45.js.map +1 -0
- package/dist/chunk-QW7H3ICI.js +1372 -0
- package/dist/chunk-QW7H3ICI.js.map +1 -0
- package/dist/chunk-VPS7L64N.js +4785 -0
- package/dist/chunk-VPS7L64N.js.map +1 -0
- package/dist/chunk-Z4Y4FMQN.js +1097 -0
- package/dist/chunk-Z4Y4FMQN.js.map +1 -0
- package/dist/compat/nestjs/index.cjs +4883 -0
- package/dist/compat/nestjs/index.cjs.map +1 -0
- package/dist/compat/nestjs/index.d.cts +7 -0
- package/dist/compat/nestjs/index.d.ts +7 -0
- package/dist/compat/nestjs/index.js +84 -0
- package/dist/compat/nestjs/index.js.map +1 -0
- package/dist/core/index.cjs +1632 -0
- package/dist/core/index.cjs.map +1 -0
- package/dist/core/index.d.cts +2 -0
- package/dist/core/index.d.ts +2 -0
- package/dist/core/index.js +90 -0
- package/dist/core/index.js.map +1 -0
- package/dist/extra/index.cjs +6885 -0
- package/dist/extra/index.cjs.map +1 -0
- package/dist/extra/index.d.cts +5 -0
- package/dist/extra/index.d.ts +5 -0
- package/dist/extra/index.js +290 -0
- package/dist/extra/index.js.map +1 -0
- package/dist/graph/index.cjs +3225 -0
- package/dist/graph/index.cjs.map +1 -0
- package/dist/graph/index.d.cts +3 -0
- package/dist/graph/index.d.ts +3 -0
- package/dist/graph/index.js +25 -0
- package/dist/graph/index.js.map +1 -0
- package/dist/graph-CL_ZDAj9.d.cts +605 -0
- package/dist/graph-D18qmsNm.d.ts +605 -0
- package/dist/index-B6SsZs2h.d.cts +3463 -0
- package/dist/index-B7eOdgEx.d.ts +449 -0
- package/dist/index-BHUvlQ3v.d.ts +3463 -0
- package/dist/index-BtK55IE2.d.ts +231 -0
- package/dist/index-BvhgZRHK.d.cts +231 -0
- package/dist/index-Bvy_6CaN.d.ts +452 -0
- package/dist/index-C3BMRmmp.d.cts +449 -0
- package/dist/index-C5mqLhMX.d.cts +452 -0
- package/dist/index-CP_QvbWu.d.ts +940 -0
- package/dist/index-D_geH2Bm.d.cts +940 -0
- package/dist/index.cjs +14843 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1517 -0
- package/dist/index.d.ts +1517 -0
- package/dist/index.js +3649 -0
- package/dist/index.js.map +1 -0
- package/dist/meta-BsF6Sag9.d.cts +607 -0
- package/dist/meta-BsF6Sag9.d.ts +607 -0
- package/dist/patterns/reactive-layout/index.cjs +4143 -0
- package/dist/patterns/reactive-layout/index.cjs.map +1 -0
- package/dist/patterns/reactive-layout/index.d.cts +3 -0
- package/dist/patterns/reactive-layout/index.d.ts +3 -0
- package/dist/patterns/reactive-layout/index.js +38 -0
- package/dist/patterns/reactive-layout/index.js.map +1 -0
- package/dist/reactive-log-BfvfNWQh.d.cts +137 -0
- package/dist/reactive-log-ohLmTXoZ.d.ts +137 -0
- package/package.json +256 -0
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
import { q as GraphPersistSnapshot, A as AutoCheckpointAdapter, D as DescribeFilter, d as GRAPH_META_SEGMENT, G as Graph, e as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, f as GraphCheckpointRecord, g as GraphDescribeOutput, h as GraphDiagramDirection, i as GraphDiagramOptions, j as GraphDiffChange, k as GraphDiffResult, l as GraphDumpOptions, m as GraphFactoryContext, n as GraphNodeFactory, o as GraphObserveAll, p as GraphObserveOne, a as GraphOptions, r as GraphSpyHandle, s as GraphSpyOptions, t as GraphSpyTheme, u as GraphSpyThemeName, O as ObserveEvent, v as ObserveOptions, w as ObserveResult, R as ReachableDirection, x as ReachableOptions, T as TraceEntry, y as reachable } from './graph-D18qmsNm.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* GraphCodec — pluggable serialization for graph snapshots (Phase 8.6).
|
|
5
|
+
*
|
|
6
|
+
* Design reference: `archive/docs/SESSION-serialization-memory-footprint.md`
|
|
7
|
+
*
|
|
8
|
+
* The codec interface decouples snapshot format from graph internals.
|
|
9
|
+
* Default is JSON (current behavior). DAG-CBOR and compressed variants
|
|
10
|
+
* ship as optional codecs. FlatBuffers/Arrow for advanced tiers.
|
|
11
|
+
*
|
|
12
|
+
* Tiered representation:
|
|
13
|
+
* HOT — JS objects (live propagation, no codec involved)
|
|
14
|
+
* WARM — DAG-CBOR in-memory buffer (lazy hydration, delta checkpoints)
|
|
15
|
+
* COLD — Arrow/Parquet (bulk storage, ML pipelines, archival)
|
|
16
|
+
* PEEK — FlatBuffers (zero-copy read from dormant graph)
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Encode/decode graph snapshots to/from binary.
|
|
21
|
+
*
|
|
22
|
+
* Implementations must be deterministic: `encode(x)` always produces the
|
|
23
|
+
* same bytes for the same input. This is critical for CID computation (V1)
|
|
24
|
+
* and snapshot hash-comparison.
|
|
25
|
+
*/
|
|
26
|
+
interface GraphCodec {
|
|
27
|
+
/** MIME-like content type identifier (e.g. "application/dag-cbor+zstd"). */
|
|
28
|
+
readonly contentType: string;
|
|
29
|
+
/** Human-readable name for diagnostics. */
|
|
30
|
+
readonly name: string;
|
|
31
|
+
/** Encode a snapshot to binary. */
|
|
32
|
+
encode(snapshot: GraphPersistSnapshot): Uint8Array;
|
|
33
|
+
/**
|
|
34
|
+
* Decode binary back to a snapshot.
|
|
35
|
+
*
|
|
36
|
+
* For lazy codecs, this may return a proxy that decodes nodes on access
|
|
37
|
+
* (see {@link LazyGraphCodec}).
|
|
38
|
+
*/
|
|
39
|
+
decode(buffer: Uint8Array): GraphPersistSnapshot;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Extended codec that supports lazy (on-demand) node decoding.
|
|
43
|
+
*
|
|
44
|
+
* `decodeLazy` returns a snapshot where `nodes` is a Proxy — individual
|
|
45
|
+
* nodes are decoded only when accessed. This enables near-zero cold-start
|
|
46
|
+
* for large graphs (decode envelope + topology, skip node values until read).
|
|
47
|
+
*/
|
|
48
|
+
interface LazyGraphCodec extends GraphCodec {
|
|
49
|
+
/** Decode envelope and topology; defer node value decoding to access time. */
|
|
50
|
+
decodeLazy(buffer: Uint8Array): GraphPersistSnapshot;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* A delta checkpoint: only the nodes that changed since last checkpoint.
|
|
54
|
+
*
|
|
55
|
+
* Append-only: each delta is identified by `seq` (monotonic). A full
|
|
56
|
+
* snapshot is taken every `compactEvery` deltas for WAL compaction.
|
|
57
|
+
*/
|
|
58
|
+
interface DeltaCheckpoint {
|
|
59
|
+
/** Monotonic sequence number. */
|
|
60
|
+
seq: number;
|
|
61
|
+
/** Graph name. */
|
|
62
|
+
name: string;
|
|
63
|
+
/** Base snapshot seq this delta applies to (0 = initial full snapshot). */
|
|
64
|
+
baseSec: number;
|
|
65
|
+
/** Only nodes with version > lastCheckpoint. Keyed by node name. */
|
|
66
|
+
nodes: Record<string, {
|
|
67
|
+
/** V0 version at time of checkpoint. */
|
|
68
|
+
version: number;
|
|
69
|
+
/** Serialized node value (codec-dependent). */
|
|
70
|
+
value: unknown;
|
|
71
|
+
/** Meta snapshot (only if materialized). */
|
|
72
|
+
meta?: Record<string, unknown>;
|
|
73
|
+
}>;
|
|
74
|
+
/** Nodes removed since last checkpoint. */
|
|
75
|
+
removed: string[];
|
|
76
|
+
/** Edges added since last checkpoint. */
|
|
77
|
+
edgesAdded: ReadonlyArray<{
|
|
78
|
+
from: string;
|
|
79
|
+
to: string;
|
|
80
|
+
}>;
|
|
81
|
+
/** Edges removed since last checkpoint. */
|
|
82
|
+
edgesRemoved: ReadonlyArray<{
|
|
83
|
+
from: string;
|
|
84
|
+
to: string;
|
|
85
|
+
}>;
|
|
86
|
+
/** Timestamp (wall-clock ns) of this checkpoint. */
|
|
87
|
+
timestampNs: bigint;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* WAL entry: either a full snapshot or a delta.
|
|
91
|
+
*/
|
|
92
|
+
type WALEntry = {
|
|
93
|
+
type: "full";
|
|
94
|
+
snapshot: GraphPersistSnapshot;
|
|
95
|
+
seq: number;
|
|
96
|
+
} | {
|
|
97
|
+
type: "delta";
|
|
98
|
+
delta: DeltaCheckpoint;
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* Policy for evicting dormant subgraphs to reduce memory.
|
|
102
|
+
*
|
|
103
|
+
* When a subgraph hasn't propagated for `idleTimeoutMs`, it is serialized
|
|
104
|
+
* using the graph's codec and JS objects are released. Re-hydrated on next
|
|
105
|
+
* access (read, propagation, describe).
|
|
106
|
+
*/
|
|
107
|
+
interface EvictionPolicy {
|
|
108
|
+
/** Milliseconds of inactivity before eviction. */
|
|
109
|
+
idleTimeoutMs: number;
|
|
110
|
+
/** Codec to use for serializing evicted subgraphs (default: graph's codec). */
|
|
111
|
+
codec?: GraphCodec;
|
|
112
|
+
}
|
|
113
|
+
/** Metadata about an evicted subgraph, exposed via describe(). */
|
|
114
|
+
interface EvictedSubgraphInfo {
|
|
115
|
+
/** True if currently evicted (serialized, JS objects released). */
|
|
116
|
+
evicted: true;
|
|
117
|
+
/** Wall-clock ns of last propagation before eviction. */
|
|
118
|
+
lastActiveNs: bigint;
|
|
119
|
+
/** Size of serialized buffer in bytes. */
|
|
120
|
+
serializedBytes: number;
|
|
121
|
+
/** Codec used for serialization. */
|
|
122
|
+
codecName: string;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Default JSON codec. Wraps `JSON.stringify`/`JSON.parse` with deterministic
|
|
126
|
+
* key ordering (matching current `snapshot()` behavior).
|
|
127
|
+
*/
|
|
128
|
+
declare const JsonCodec: GraphCodec;
|
|
129
|
+
/**
|
|
130
|
+
* Create a DAG-CBOR codec.
|
|
131
|
+
*
|
|
132
|
+
* Requires `@ipld/dag-cbor` as a peer dependency. ~40-50% smaller than JSON,
|
|
133
|
+
* deterministic encoding (required for V1 CID), CID links as native type.
|
|
134
|
+
*
|
|
135
|
+
* @example
|
|
136
|
+
* ```ts
|
|
137
|
+
* import * as dagCbor from "@ipld/dag-cbor";
|
|
138
|
+
* const codec = createDagCborCodec(dagCbor);
|
|
139
|
+
* const bytes = codec.encode(graph.snapshot());
|
|
140
|
+
* ```
|
|
141
|
+
*/
|
|
142
|
+
declare function createDagCborCodec(dagCbor: {
|
|
143
|
+
encode: (value: unknown) => Uint8Array;
|
|
144
|
+
decode: (bytes: Uint8Array) => unknown;
|
|
145
|
+
}): GraphCodec;
|
|
146
|
+
/**
|
|
147
|
+
* Create a DAG-CBOR + zstd codec. ~80-90% smaller than JSON.
|
|
148
|
+
*
|
|
149
|
+
* Requires `@ipld/dag-cbor` and a zstd implementation (e.g. `fzstd` for
|
|
150
|
+
* browser, `node:zlib` for Node.js).
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```ts
|
|
154
|
+
* import * as dagCbor from "@ipld/dag-cbor";
|
|
155
|
+
* import { compressSync, decompressSync } from "fzstd";
|
|
156
|
+
* const codec = createDagCborZstdCodec(dagCbor, { compressSync, decompressSync });
|
|
157
|
+
* ```
|
|
158
|
+
*/
|
|
159
|
+
declare function createDagCborZstdCodec(dagCbor: {
|
|
160
|
+
encode: (value: unknown) => Uint8Array;
|
|
161
|
+
decode: (bytes: Uint8Array) => unknown;
|
|
162
|
+
}, zstd: {
|
|
163
|
+
compressSync: (data: Uint8Array) => Uint8Array;
|
|
164
|
+
decompressSync: (data: Uint8Array) => Uint8Array;
|
|
165
|
+
}): GraphCodec;
|
|
166
|
+
/**
|
|
167
|
+
* Negotiate a common codec between two peers.
|
|
168
|
+
*
|
|
169
|
+
* Each peer advertises its supported codecs (ordered by preference).
|
|
170
|
+
* Returns the first codec supported by both, or null if none.
|
|
171
|
+
*/
|
|
172
|
+
declare function negotiateCodec(localPreference: readonly GraphCodec[], remoteContentTypes: readonly string[]): GraphCodec | null;
|
|
173
|
+
/**
|
|
174
|
+
* Reconstruct a snapshot from a WAL (full snapshot + sequence of deltas).
|
|
175
|
+
*
|
|
176
|
+
* Applies deltas in order on top of the base snapshot. Validates that
|
|
177
|
+
* delta `baseSec` chains correctly.
|
|
178
|
+
*/
|
|
179
|
+
declare function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot;
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* Graph container: registry, wiring, introspection (Phase 1).
|
|
183
|
+
*/
|
|
184
|
+
|
|
185
|
+
declare const index_AutoCheckpointAdapter: typeof AutoCheckpointAdapter;
|
|
186
|
+
type index_DeltaCheckpoint = DeltaCheckpoint;
|
|
187
|
+
declare const index_DescribeFilter: typeof DescribeFilter;
|
|
188
|
+
type index_EvictedSubgraphInfo = EvictedSubgraphInfo;
|
|
189
|
+
type index_EvictionPolicy = EvictionPolicy;
|
|
190
|
+
declare const index_GRAPH_META_SEGMENT: typeof GRAPH_META_SEGMENT;
|
|
191
|
+
declare const index_Graph: typeof Graph;
|
|
192
|
+
declare const index_GraphActorOptions: typeof GraphActorOptions;
|
|
193
|
+
declare const index_GraphAutoCheckpointHandle: typeof GraphAutoCheckpointHandle;
|
|
194
|
+
declare const index_GraphAutoCheckpointOptions: typeof GraphAutoCheckpointOptions;
|
|
195
|
+
declare const index_GraphCheckpointRecord: typeof GraphCheckpointRecord;
|
|
196
|
+
type index_GraphCodec = GraphCodec;
|
|
197
|
+
declare const index_GraphDescribeOutput: typeof GraphDescribeOutput;
|
|
198
|
+
declare const index_GraphDiagramDirection: typeof GraphDiagramDirection;
|
|
199
|
+
declare const index_GraphDiagramOptions: typeof GraphDiagramOptions;
|
|
200
|
+
declare const index_GraphDiffChange: typeof GraphDiffChange;
|
|
201
|
+
declare const index_GraphDiffResult: typeof GraphDiffResult;
|
|
202
|
+
declare const index_GraphDumpOptions: typeof GraphDumpOptions;
|
|
203
|
+
declare const index_GraphFactoryContext: typeof GraphFactoryContext;
|
|
204
|
+
declare const index_GraphNodeFactory: typeof GraphNodeFactory;
|
|
205
|
+
declare const index_GraphObserveAll: typeof GraphObserveAll;
|
|
206
|
+
declare const index_GraphObserveOne: typeof GraphObserveOne;
|
|
207
|
+
declare const index_GraphOptions: typeof GraphOptions;
|
|
208
|
+
declare const index_GraphPersistSnapshot: typeof GraphPersistSnapshot;
|
|
209
|
+
declare const index_GraphSpyHandle: typeof GraphSpyHandle;
|
|
210
|
+
declare const index_GraphSpyOptions: typeof GraphSpyOptions;
|
|
211
|
+
declare const index_GraphSpyTheme: typeof GraphSpyTheme;
|
|
212
|
+
declare const index_GraphSpyThemeName: typeof GraphSpyThemeName;
|
|
213
|
+
declare const index_JsonCodec: typeof JsonCodec;
|
|
214
|
+
type index_LazyGraphCodec = LazyGraphCodec;
|
|
215
|
+
declare const index_ObserveEvent: typeof ObserveEvent;
|
|
216
|
+
declare const index_ObserveOptions: typeof ObserveOptions;
|
|
217
|
+
declare const index_ObserveResult: typeof ObserveResult;
|
|
218
|
+
declare const index_ReachableDirection: typeof ReachableDirection;
|
|
219
|
+
declare const index_ReachableOptions: typeof ReachableOptions;
|
|
220
|
+
declare const index_TraceEntry: typeof TraceEntry;
|
|
221
|
+
type index_WALEntry = WALEntry;
|
|
222
|
+
declare const index_createDagCborCodec: typeof createDagCborCodec;
|
|
223
|
+
declare const index_createDagCborZstdCodec: typeof createDagCborZstdCodec;
|
|
224
|
+
declare const index_negotiateCodec: typeof negotiateCodec;
|
|
225
|
+
declare const index_reachable: typeof reachable;
|
|
226
|
+
declare const index_replayWAL: typeof replayWAL;
|
|
227
|
+
declare namespace index {
|
|
228
|
+
export { index_AutoCheckpointAdapter as AutoCheckpointAdapter, type index_DeltaCheckpoint as DeltaCheckpoint, index_DescribeFilter as DescribeFilter, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAutoCheckpointHandle as GraphAutoCheckpointHandle, index_GraphAutoCheckpointOptions as GraphAutoCheckpointOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiagramOptions as GraphDiagramOptions, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphDumpOptions as GraphDumpOptions, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphSpyHandle as GraphSpyHandle, index_GraphSpyOptions as GraphSpyOptions, index_GraphSpyTheme as GraphSpyTheme, index_GraphSpyThemeName as GraphSpyThemeName, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, index_TraceEntry as TraceEntry, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_negotiateCodec as negotiateCodec, index_reachable as reachable, index_replayWAL as replayWAL };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
export { type DeltaCheckpoint as D, type EvictedSubgraphInfo as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, type WALEntry as W, type EvictionPolicy as a, createDagCborZstdCodec as b, createDagCborCodec as c, index as i, negotiateCodec as n, replayWAL as r };
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
import { q as GraphPersistSnapshot, A as AutoCheckpointAdapter, D as DescribeFilter, d as GRAPH_META_SEGMENT, G as Graph, e as GraphActorOptions, b as GraphAutoCheckpointHandle, c as GraphAutoCheckpointOptions, f as GraphCheckpointRecord, g as GraphDescribeOutput, h as GraphDiagramDirection, i as GraphDiagramOptions, j as GraphDiffChange, k as GraphDiffResult, l as GraphDumpOptions, m as GraphFactoryContext, n as GraphNodeFactory, o as GraphObserveAll, p as GraphObserveOne, a as GraphOptions, r as GraphSpyHandle, s as GraphSpyOptions, t as GraphSpyTheme, u as GraphSpyThemeName, O as ObserveEvent, v as ObserveOptions, w as ObserveResult, R as ReachableDirection, x as ReachableOptions, T as TraceEntry, y as reachable } from './graph-CL_ZDAj9.cjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* GraphCodec — pluggable serialization for graph snapshots (Phase 8.6).
|
|
5
|
+
*
|
|
6
|
+
* Design reference: `archive/docs/SESSION-serialization-memory-footprint.md`
|
|
7
|
+
*
|
|
8
|
+
* The codec interface decouples snapshot format from graph internals.
|
|
9
|
+
* Default is JSON (current behavior). DAG-CBOR and compressed variants
|
|
10
|
+
* ship as optional codecs. FlatBuffers/Arrow for advanced tiers.
|
|
11
|
+
*
|
|
12
|
+
* Tiered representation:
|
|
13
|
+
* HOT — JS objects (live propagation, no codec involved)
|
|
14
|
+
* WARM — DAG-CBOR in-memory buffer (lazy hydration, delta checkpoints)
|
|
15
|
+
* COLD — Arrow/Parquet (bulk storage, ML pipelines, archival)
|
|
16
|
+
* PEEK — FlatBuffers (zero-copy read from dormant graph)
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Encode/decode graph snapshots to/from binary.
|
|
21
|
+
*
|
|
22
|
+
* Implementations must be deterministic: `encode(x)` always produces the
|
|
23
|
+
* same bytes for the same input. This is critical for CID computation (V1)
|
|
24
|
+
* and snapshot hash-comparison.
|
|
25
|
+
*/
|
|
26
|
+
interface GraphCodec {
|
|
27
|
+
/** MIME-like content type identifier (e.g. "application/dag-cbor+zstd"). */
|
|
28
|
+
readonly contentType: string;
|
|
29
|
+
/** Human-readable name for diagnostics. */
|
|
30
|
+
readonly name: string;
|
|
31
|
+
/** Encode a snapshot to binary. */
|
|
32
|
+
encode(snapshot: GraphPersistSnapshot): Uint8Array;
|
|
33
|
+
/**
|
|
34
|
+
* Decode binary back to a snapshot.
|
|
35
|
+
*
|
|
36
|
+
* For lazy codecs, this may return a proxy that decodes nodes on access
|
|
37
|
+
* (see {@link LazyGraphCodec}).
|
|
38
|
+
*/
|
|
39
|
+
decode(buffer: Uint8Array): GraphPersistSnapshot;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Extended codec that supports lazy (on-demand) node decoding.
|
|
43
|
+
*
|
|
44
|
+
* `decodeLazy` returns a snapshot where `nodes` is a Proxy — individual
|
|
45
|
+
* nodes are decoded only when accessed. This enables near-zero cold-start
|
|
46
|
+
* for large graphs (decode envelope + topology, skip node values until read).
|
|
47
|
+
*/
|
|
48
|
+
interface LazyGraphCodec extends GraphCodec {
|
|
49
|
+
/** Decode envelope and topology; defer node value decoding to access time. */
|
|
50
|
+
decodeLazy(buffer: Uint8Array): GraphPersistSnapshot;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* A delta checkpoint: only the nodes that changed since last checkpoint.
|
|
54
|
+
*
|
|
55
|
+
* Append-only: each delta is identified by `seq` (monotonic). A full
|
|
56
|
+
* snapshot is taken every `compactEvery` deltas for WAL compaction.
|
|
57
|
+
*/
|
|
58
|
+
interface DeltaCheckpoint {
|
|
59
|
+
/** Monotonic sequence number. */
|
|
60
|
+
seq: number;
|
|
61
|
+
/** Graph name. */
|
|
62
|
+
name: string;
|
|
63
|
+
/** Base snapshot seq this delta applies to (0 = initial full snapshot). */
|
|
64
|
+
baseSec: number;
|
|
65
|
+
/** Only nodes with version > lastCheckpoint. Keyed by node name. */
|
|
66
|
+
nodes: Record<string, {
|
|
67
|
+
/** V0 version at time of checkpoint. */
|
|
68
|
+
version: number;
|
|
69
|
+
/** Serialized node value (codec-dependent). */
|
|
70
|
+
value: unknown;
|
|
71
|
+
/** Meta snapshot (only if materialized). */
|
|
72
|
+
meta?: Record<string, unknown>;
|
|
73
|
+
}>;
|
|
74
|
+
/** Nodes removed since last checkpoint. */
|
|
75
|
+
removed: string[];
|
|
76
|
+
/** Edges added since last checkpoint. */
|
|
77
|
+
edgesAdded: ReadonlyArray<{
|
|
78
|
+
from: string;
|
|
79
|
+
to: string;
|
|
80
|
+
}>;
|
|
81
|
+
/** Edges removed since last checkpoint. */
|
|
82
|
+
edgesRemoved: ReadonlyArray<{
|
|
83
|
+
from: string;
|
|
84
|
+
to: string;
|
|
85
|
+
}>;
|
|
86
|
+
/** Timestamp (wall-clock ns) of this checkpoint. */
|
|
87
|
+
timestampNs: bigint;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* WAL entry: either a full snapshot or a delta.
|
|
91
|
+
*/
|
|
92
|
+
type WALEntry = {
|
|
93
|
+
type: "full";
|
|
94
|
+
snapshot: GraphPersistSnapshot;
|
|
95
|
+
seq: number;
|
|
96
|
+
} | {
|
|
97
|
+
type: "delta";
|
|
98
|
+
delta: DeltaCheckpoint;
|
|
99
|
+
};
|
|
100
|
+
/**
|
|
101
|
+
* Policy for evicting dormant subgraphs to reduce memory.
|
|
102
|
+
*
|
|
103
|
+
* When a subgraph hasn't propagated for `idleTimeoutMs`, it is serialized
|
|
104
|
+
* using the graph's codec and JS objects are released. Re-hydrated on next
|
|
105
|
+
* access (read, propagation, describe).
|
|
106
|
+
*/
|
|
107
|
+
interface EvictionPolicy {
|
|
108
|
+
/** Milliseconds of inactivity before eviction. */
|
|
109
|
+
idleTimeoutMs: number;
|
|
110
|
+
/** Codec to use for serializing evicted subgraphs (default: graph's codec). */
|
|
111
|
+
codec?: GraphCodec;
|
|
112
|
+
}
|
|
113
|
+
/** Metadata about an evicted subgraph, exposed via describe(). */
|
|
114
|
+
interface EvictedSubgraphInfo {
|
|
115
|
+
/** True if currently evicted (serialized, JS objects released). */
|
|
116
|
+
evicted: true;
|
|
117
|
+
/** Wall-clock ns of last propagation before eviction. */
|
|
118
|
+
lastActiveNs: bigint;
|
|
119
|
+
/** Size of serialized buffer in bytes. */
|
|
120
|
+
serializedBytes: number;
|
|
121
|
+
/** Codec used for serialization. */
|
|
122
|
+
codecName: string;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Default JSON codec. Wraps `JSON.stringify`/`JSON.parse` with deterministic
|
|
126
|
+
* key ordering (matching current `snapshot()` behavior).
|
|
127
|
+
*/
|
|
128
|
+
declare const JsonCodec: GraphCodec;
|
|
129
|
+
/**
|
|
130
|
+
* Create a DAG-CBOR codec.
|
|
131
|
+
*
|
|
132
|
+
* Requires `@ipld/dag-cbor` as a peer dependency. ~40-50% smaller than JSON,
|
|
133
|
+
* deterministic encoding (required for V1 CID), CID links as native type.
|
|
134
|
+
*
|
|
135
|
+
* @example
|
|
136
|
+
* ```ts
|
|
137
|
+
* import * as dagCbor from "@ipld/dag-cbor";
|
|
138
|
+
* const codec = createDagCborCodec(dagCbor);
|
|
139
|
+
* const bytes = codec.encode(graph.snapshot());
|
|
140
|
+
* ```
|
|
141
|
+
*/
|
|
142
|
+
declare function createDagCborCodec(dagCbor: {
|
|
143
|
+
encode: (value: unknown) => Uint8Array;
|
|
144
|
+
decode: (bytes: Uint8Array) => unknown;
|
|
145
|
+
}): GraphCodec;
|
|
146
|
+
/**
|
|
147
|
+
* Create a DAG-CBOR + zstd codec. ~80-90% smaller than JSON.
|
|
148
|
+
*
|
|
149
|
+
* Requires `@ipld/dag-cbor` and a zstd implementation (e.g. `fzstd` for
|
|
150
|
+
* browser, `node:zlib` for Node.js).
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```ts
|
|
154
|
+
* import * as dagCbor from "@ipld/dag-cbor";
|
|
155
|
+
* import { compressSync, decompressSync } from "fzstd";
|
|
156
|
+
* const codec = createDagCborZstdCodec(dagCbor, { compressSync, decompressSync });
|
|
157
|
+
* ```
|
|
158
|
+
*/
|
|
159
|
+
declare function createDagCborZstdCodec(dagCbor: {
|
|
160
|
+
encode: (value: unknown) => Uint8Array;
|
|
161
|
+
decode: (bytes: Uint8Array) => unknown;
|
|
162
|
+
}, zstd: {
|
|
163
|
+
compressSync: (data: Uint8Array) => Uint8Array;
|
|
164
|
+
decompressSync: (data: Uint8Array) => Uint8Array;
|
|
165
|
+
}): GraphCodec;
|
|
166
|
+
/**
|
|
167
|
+
* Negotiate a common codec between two peers.
|
|
168
|
+
*
|
|
169
|
+
* Each peer advertises its supported codecs (ordered by preference).
|
|
170
|
+
* Returns the first codec supported by both, or null if none.
|
|
171
|
+
*/
|
|
172
|
+
declare function negotiateCodec(localPreference: readonly GraphCodec[], remoteContentTypes: readonly string[]): GraphCodec | null;
|
|
173
|
+
/**
|
|
174
|
+
* Reconstruct a snapshot from a WAL (full snapshot + sequence of deltas).
|
|
175
|
+
*
|
|
176
|
+
* Applies deltas in order on top of the base snapshot. Validates that
|
|
177
|
+
* delta `baseSec` chains correctly.
|
|
178
|
+
*/
|
|
179
|
+
declare function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot;
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* Graph container: registry, wiring, introspection (Phase 1).
|
|
183
|
+
*/
|
|
184
|
+
|
|
185
|
+
declare const index_AutoCheckpointAdapter: typeof AutoCheckpointAdapter;
|
|
186
|
+
type index_DeltaCheckpoint = DeltaCheckpoint;
|
|
187
|
+
declare const index_DescribeFilter: typeof DescribeFilter;
|
|
188
|
+
type index_EvictedSubgraphInfo = EvictedSubgraphInfo;
|
|
189
|
+
type index_EvictionPolicy = EvictionPolicy;
|
|
190
|
+
declare const index_GRAPH_META_SEGMENT: typeof GRAPH_META_SEGMENT;
|
|
191
|
+
declare const index_Graph: typeof Graph;
|
|
192
|
+
declare const index_GraphActorOptions: typeof GraphActorOptions;
|
|
193
|
+
declare const index_GraphAutoCheckpointHandle: typeof GraphAutoCheckpointHandle;
|
|
194
|
+
declare const index_GraphAutoCheckpointOptions: typeof GraphAutoCheckpointOptions;
|
|
195
|
+
declare const index_GraphCheckpointRecord: typeof GraphCheckpointRecord;
|
|
196
|
+
type index_GraphCodec = GraphCodec;
|
|
197
|
+
declare const index_GraphDescribeOutput: typeof GraphDescribeOutput;
|
|
198
|
+
declare const index_GraphDiagramDirection: typeof GraphDiagramDirection;
|
|
199
|
+
declare const index_GraphDiagramOptions: typeof GraphDiagramOptions;
|
|
200
|
+
declare const index_GraphDiffChange: typeof GraphDiffChange;
|
|
201
|
+
declare const index_GraphDiffResult: typeof GraphDiffResult;
|
|
202
|
+
declare const index_GraphDumpOptions: typeof GraphDumpOptions;
|
|
203
|
+
declare const index_GraphFactoryContext: typeof GraphFactoryContext;
|
|
204
|
+
declare const index_GraphNodeFactory: typeof GraphNodeFactory;
|
|
205
|
+
declare const index_GraphObserveAll: typeof GraphObserveAll;
|
|
206
|
+
declare const index_GraphObserveOne: typeof GraphObserveOne;
|
|
207
|
+
declare const index_GraphOptions: typeof GraphOptions;
|
|
208
|
+
declare const index_GraphPersistSnapshot: typeof GraphPersistSnapshot;
|
|
209
|
+
declare const index_GraphSpyHandle: typeof GraphSpyHandle;
|
|
210
|
+
declare const index_GraphSpyOptions: typeof GraphSpyOptions;
|
|
211
|
+
declare const index_GraphSpyTheme: typeof GraphSpyTheme;
|
|
212
|
+
declare const index_GraphSpyThemeName: typeof GraphSpyThemeName;
|
|
213
|
+
declare const index_JsonCodec: typeof JsonCodec;
|
|
214
|
+
type index_LazyGraphCodec = LazyGraphCodec;
|
|
215
|
+
declare const index_ObserveEvent: typeof ObserveEvent;
|
|
216
|
+
declare const index_ObserveOptions: typeof ObserveOptions;
|
|
217
|
+
declare const index_ObserveResult: typeof ObserveResult;
|
|
218
|
+
declare const index_ReachableDirection: typeof ReachableDirection;
|
|
219
|
+
declare const index_ReachableOptions: typeof ReachableOptions;
|
|
220
|
+
declare const index_TraceEntry: typeof TraceEntry;
|
|
221
|
+
type index_WALEntry = WALEntry;
|
|
222
|
+
declare const index_createDagCborCodec: typeof createDagCborCodec;
|
|
223
|
+
declare const index_createDagCborZstdCodec: typeof createDagCborZstdCodec;
|
|
224
|
+
declare const index_negotiateCodec: typeof negotiateCodec;
|
|
225
|
+
declare const index_reachable: typeof reachable;
|
|
226
|
+
declare const index_replayWAL: typeof replayWAL;
|
|
227
|
+
declare namespace index {
|
|
228
|
+
export { index_AutoCheckpointAdapter as AutoCheckpointAdapter, type index_DeltaCheckpoint as DeltaCheckpoint, index_DescribeFilter as DescribeFilter, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAutoCheckpointHandle as GraphAutoCheckpointHandle, index_GraphAutoCheckpointOptions as GraphAutoCheckpointOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiagramOptions as GraphDiagramOptions, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphDumpOptions as GraphDumpOptions, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphSpyHandle as GraphSpyHandle, index_GraphSpyOptions as GraphSpyOptions, index_GraphSpyTheme as GraphSpyTheme, index_GraphSpyThemeName as GraphSpyThemeName, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, index_TraceEntry as TraceEntry, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_negotiateCodec as negotiateCodec, index_reachable as reachable, index_replayWAL as replayWAL };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
export { type DeltaCheckpoint as D, type EvictedSubgraphInfo as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, type WALEntry as W, type EvictionPolicy as a, createDagCborZstdCodec as b, createDagCborCodec as c, index as i, negotiateCodec as n, replayWAL as r };
|