@realflow/core 0.2.0 → 0.2.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 +108 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# @realflow/core
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@realflow/core)
|
|
4
|
+
[](https://github.com/olbboy/realflow/blob/main/LICENSE)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
|
|
7
|
+
The **headless, zero-dependency engine** behind [RealFlow](https://github.com/olbboy/realflow) —
|
|
8
|
+
a reactive graph store, spatial index, edge-path math, auto-layouts, undo/redo,
|
|
9
|
+
graph algorithms and an AI-operations layer. No DOM, no React, no dependencies:
|
|
10
|
+
it runs in the browser, in Node.js, in a worker, or in a test.
|
|
11
|
+
|
|
12
|
+
`@realflow/core` is what powers [`@realflow/react`](https://www.npmjs.com/package/@realflow/react),
|
|
13
|
+
but you can use it on its own for **server-side validation**, CLI tooling, or any
|
|
14
|
+
place you need graph logic without a renderer.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @realflow/core
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## What's inside
|
|
21
|
+
|
|
22
|
+
- **Reactive store** (`FlowStore`) — fine-grained pub/sub where each node and
|
|
23
|
+
edge has its own topic (`node:<id>`, `edge:<id>`), so a change touches only
|
|
24
|
+
what subscribed to it.
|
|
25
|
+
- **Spatial hash index** — O(1)-ish viewport queries and culling for large graphs.
|
|
26
|
+
- **Edge geometry** — `bezier` / `smoothstep` / `step` / `straight`, plus
|
|
27
|
+
`orthogonal` routing that goes *around* nodes (Hanan-grid A*).
|
|
28
|
+
- **Auto-layout** — `layered` (Sugiyama, handles cycles), `tree`, `force`
|
|
29
|
+
(seeded/deterministic), `radial`, `grid`. Zero deps — no dagre, no elkjs.
|
|
30
|
+
Plus off-thread (`layoutInWorker`) and `incrementalLayout`.
|
|
31
|
+
- **Transactional history** — every mutation recorded with its inverse; group
|
|
32
|
+
with `transact(label, fn)`; drags coalesce into one entry.
|
|
33
|
+
- **Graph algorithms** — `topologicalSort`, `hasCycle`, `connectedComponents`,
|
|
34
|
+
`shortestPath`, `getAncestors`, `getDescendants`, `getIncomers`, `getOutgoers`.
|
|
35
|
+
- **AI operations** — a validated JSON operation format (`applyOperations`) that
|
|
36
|
+
never throws, an LLM tool schema (`operationSchema`, `OPERATIONS_PROMPT`), and
|
|
37
|
+
graph serializers (`describeGraph`, `toMermaid`).
|
|
38
|
+
- **Real-time collaboration** — transport-agnostic `Collab` (Lamport-clock LWW,
|
|
39
|
+
order-independent convergence) and `Presence`.
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import {
|
|
45
|
+
FlowStore, topologicalSort, hasCycle,
|
|
46
|
+
applyOperations, describeGraph, toMermaid,
|
|
47
|
+
} from '@realflow/core';
|
|
48
|
+
|
|
49
|
+
const store = new FlowStore({
|
|
50
|
+
nodes: [
|
|
51
|
+
{ id: 'fetch', position: { x: 0, y: 0 }, data: { label: 'Fetch' } },
|
|
52
|
+
{ id: 'parse', position: { x: 240, y: 0 }, data: { label: 'Parse' } },
|
|
53
|
+
],
|
|
54
|
+
edges: [{ id: 'e1', source: 'fetch', target: 'parse' }],
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
// Graph algorithms on the live store
|
|
58
|
+
topologicalSort(store); // ['fetch', 'parse']
|
|
59
|
+
hasCycle(store); // false
|
|
60
|
+
|
|
61
|
+
// Drive it with validated operations (great for LLM tool-calling / server-side).
|
|
62
|
+
// Never throws — invalid ops are collected as errors; one batch = one undo entry.
|
|
63
|
+
const { errors } = applyOperations(store, [
|
|
64
|
+
{ op: 'add_node', id: 'retry', label: 'Retry (3x)' },
|
|
65
|
+
{ op: 'connect', source: 'parse', target: 'retry' },
|
|
66
|
+
{ op: 'set_status', id: 'fetch', status: 'running', message: 'batch 4/12' },
|
|
67
|
+
]);
|
|
68
|
+
|
|
69
|
+
// Compact serializations for a model's context
|
|
70
|
+
describeGraph(store); // structured JSON
|
|
71
|
+
toMermaid(store); // Mermaid diagram source
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Server-side validation
|
|
75
|
+
|
|
76
|
+
Because the engine is dependency-free and never touches the DOM, you can validate
|
|
77
|
+
agent- or client-supplied graphs on the server with the exact logic the UI runs:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { FlowStore, applyOperations, hasCycle } from '@realflow/core';
|
|
81
|
+
|
|
82
|
+
export function validateGraph(snapshot, ops) {
|
|
83
|
+
const store = new FlowStore();
|
|
84
|
+
store.loadSnapshot(snapshot);
|
|
85
|
+
const { errors } = applyOperations(store, ops);
|
|
86
|
+
if (errors.length) return { ok: false, errors };
|
|
87
|
+
if (hasCycle(store)) return { ok: false, errors: ['graph must be acyclic'] };
|
|
88
|
+
return { ok: true, snapshot: store.toSnapshot() };
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Related packages
|
|
93
|
+
|
|
94
|
+
| Package | What it is |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| [`@realflow/react`](https://www.npmjs.com/package/@realflow/react) | React renderer built on this engine |
|
|
97
|
+
| [`@realflow/compat`](https://www.npmjs.com/package/@realflow/compat) | React Flow (xyflow) API compatibility adapter |
|
|
98
|
+
|
|
99
|
+
## Documentation
|
|
100
|
+
|
|
101
|
+
- [Core concepts & API](https://github.com/olbboy/realflow/blob/main/docs/api.md)
|
|
102
|
+
- [Auto-layout](https://github.com/olbboy/realflow/blob/main/docs/layout.md)
|
|
103
|
+
- [AI agent integration](https://github.com/olbboy/realflow/blob/main/docs/ai-integration.md)
|
|
104
|
+
- [Collaboration](https://github.com/olbboy/realflow/blob/main/docs/collaboration.md)
|
|
105
|
+
|
|
106
|
+
## License
|
|
107
|
+
|
|
108
|
+
[MIT](https://github.com/olbboy/realflow/blob/main/LICENSE) © RealFlow contributors.
|
package/package.json
CHANGED