@loradb/lora-node 0.35.1 → 0.36.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.
Files changed (57) hide show
  1. package/README.md +5 -0
  2. package/dist/types.d.ts +2 -1
  3. package/dist/types.d.ts.map +1 -1
  4. package/dist/types.js +1 -0
  5. package/dist/types.js.map +1 -1
  6. package/docs/README.md +86 -0
  7. package/docs/concepts/graph-model.md +270 -0
  8. package/docs/concepts/nodes.md +285 -0
  9. package/docs/concepts/properties.md +348 -0
  10. package/docs/concepts/relationships.md +325 -0
  11. package/docs/concepts/result-formats.md +183 -0
  12. package/docs/concepts/schema-free.md +183 -0
  13. package/docs/cookbook.md +1081 -0
  14. package/docs/data-types/lists-and-maps.md +406 -0
  15. package/docs/data-types/overview.md +210 -0
  16. package/docs/data-types/scalars.md +376 -0
  17. package/docs/data-types/spatial.md +291 -0
  18. package/docs/data-types/temporal.md +349 -0
  19. package/docs/data-types/vectors.md +563 -0
  20. package/docs/errors.md +183 -0
  21. package/docs/functions/aggregation.md +372 -0
  22. package/docs/functions/list.md +522 -0
  23. package/docs/functions/map.md +207 -0
  24. package/docs/functions/math.md +421 -0
  25. package/docs/functions/number.md +197 -0
  26. package/docs/functions/overview.md +545 -0
  27. package/docs/functions/spatial.md +384 -0
  28. package/docs/functions/string.md +502 -0
  29. package/docs/functions/temporal.md +590 -0
  30. package/docs/functions/utility.md +137 -0
  31. package/docs/functions/vectors.md +772 -0
  32. package/docs/getting-started/installation.md +204 -0
  33. package/docs/getting-started/node.md +582 -0
  34. package/docs/getting-started/tutorial.md +334 -0
  35. package/docs/index.md +203 -0
  36. package/docs/limitations.md +291 -0
  37. package/docs/performance.md +219 -0
  38. package/docs/queries/aggregation.md +520 -0
  39. package/docs/queries/cheat-sheet.md +302 -0
  40. package/docs/queries/constraints.md +239 -0
  41. package/docs/queries/create.md +331 -0
  42. package/docs/queries/examples.md +453 -0
  43. package/docs/queries/index.md +169 -0
  44. package/docs/queries/indexes.md +538 -0
  45. package/docs/queries/match.md +429 -0
  46. package/docs/queries/ordering.md +359 -0
  47. package/docs/queries/parameters.md +328 -0
  48. package/docs/queries/paths.md +462 -0
  49. package/docs/queries/return-with.md +500 -0
  50. package/docs/queries/set-delete.md +369 -0
  51. package/docs/queries/unwind-merge.md +358 -0
  52. package/docs/queries/where.md +416 -0
  53. package/docs/snapshot.md +545 -0
  54. package/docs/troubleshooting.md +1158 -0
  55. package/docs/wal.md +570 -0
  56. package/docs/why.md +273 -0
  57. package/package.json +13 -14
package/docs/why.md ADDED
@@ -0,0 +1,273 @@
1
+ ---
2
+ title: "Why LoraDB"
3
+ description: "Why a local-first, in-memory property-graph engine in Rust that speaks a pragmatic subset of Cypher — built for systems that reason over connected, evolving context."
4
+ online: "https://loradb.com/docs/why"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Why LoraDB
9
+
10
+ Most systems end up modelling relationships. Users follow users,
11
+ agents reference entities, scenes contain objects, events depend on
12
+ other events. When the questions you care about are _"everything
13
+ reachable from here"_ or _"what connects these two"_, the shape of
14
+ your data is a graph — even when the store is a table.
15
+
16
+ LoraDB is a local-first, in-memory property-graph engine written in
17
+ Rust that speaks a pragmatic subset of Cypher. It's built for code
18
+ paths where the graph needs to live next to the code that uses it,
19
+ not behind a network boundary.
20
+
21
+ ## The problem with traditional approaches
22
+
23
+ ### Relational stores fight relational questions
24
+
25
+ SQL expresses relationships with foreign keys and join tables. That
26
+ works, until the query is "find everyone within three hops", "what's
27
+ the shortest dependency chain", or "summarise the neighbourhood of
28
+ this node". Expressing those in SQL means self-joins stacked on
29
+ self-joins; running them means the planner guessing how to traverse a
30
+ graph it doesn't know is a graph.
31
+
32
+ ### Document stores fight evolving relationships
33
+
34
+ Nesting works when ownership is strict and fan-out is small. Real
35
+ systems have bidirectional edges, many-to-many links, and entities
36
+ that migrate between documents. At that point every lookup becomes an
37
+ ad-hoc index or a second round-trip, and consistency moves into
38
+ application code.
39
+
40
+ ### Graph platforms are often disproportionate
41
+
42
+ Established graph databases solve real problems — clustering,
43
+ durability, multi-user isolation, huge graphs. They also come with a
44
+ service to deploy, a protocol to speak, and a TCO that only pays off
45
+ once the graph is big enough. For a service, agent, or pipeline that
46
+ wants a graph _data structure_ inside its own process, they're too
47
+ much.
48
+
49
+ ## Why relationships matter
50
+
51
+ A graph model turns three things into first-class primitives:
52
+
53
+ - **Edges** — typed, directed, property-bearing. Not a join column.
54
+ - **Patterns** — `(a)-[:KNOWS]->(b)-[:WORKS_AT]->(c)` is the query,
55
+ not an implementation detail.
56
+ - **Traversal** — "walk from here" is `O(degree)`, not a recursive
57
+ CTE.
58
+
59
+ Cypher is a language optimised for _describing_ relationships rather
60
+ than _computing_ joins. Once the model matches the question, the
61
+ queries get short, and short queries are easier to read, review, and
62
+ optimise.
63
+
64
+ ## Why modern systems need this
65
+
66
+ Agents, robots, and real-time pipelines all end up building the same
67
+ thing by accident: an in-memory structure of entities and relations
68
+ with typed keys and an evolving shape. LoraDB is that structure, on
69
+ purpose.
70
+
71
+ ### AI agents and LLM pipelines
72
+
73
+ An agent's context is a graph — tools, entities, observations,
74
+ decisions, and the links between them. Retrieval over that context is
75
+ a graph question:
76
+
77
+ ```cypher
78
+ MATCH (t:Task {id: $task})-[:DEPENDS_ON*1..3]->(e:Entity)
79
+ OPTIONAL MATCH (e)-[:OBSERVED_IN]->(s:Session)
80
+ RETURN e.id, e.summary, collect(DISTINCT s.id) AS sessions
81
+ ```
82
+
83
+ Vectors are great for similarity. Graphs are great for _structure_ —
84
+ what depends on what, what's been tried, what contradicts what. Most
85
+ agent systems end up needing both.
86
+
87
+ ### Context memory and retrieval
88
+
89
+ Memory that's only a list of chunks loses the relationships between
90
+ them. A graph keeps them: which fact supports which claim, which
91
+ document cites which, which entity was introduced by which turn. When
92
+ the model asks _"why do we believe X"_, that's a traversal.
93
+
94
+ ### Robotics and stateful systems
95
+
96
+ Scene graphs, task graphs, capability graphs — robotics is full of
97
+ them. LoraDB runs in the controller's process, so scene updates and
98
+ plan queries don't cross a network. Schemas can evolve as the robot
99
+ learns new object categories without a migration.
100
+
101
+ ### Event-driven architectures
102
+
103
+ Stream processors resolve entities, infer relationships, and emit
104
+ enrichments. Doing that in memory next to the handler avoids a hot
105
+ round-trip per event. Cypher makes the rules readable:
106
+
107
+ ```cypher
108
+ MATCH (u:User {id: $user})-[:PLACED]->(o:Order)-[:CONTAINS]->(p:Product)
109
+ WHERE o.placed_at >= temporal.now() - 'P7D'::DURATION
110
+ RETURN p.category, count(*) AS recent
111
+ ```
112
+
113
+ ### Real-time reasoning over relationships
114
+
115
+ Anywhere a decision has to look across multiple entities and their
116
+ links — fraud signals, access control, lineage, recommendations — a
117
+ graph query says what you mean in one expression.
118
+
119
+ ## What LoraDB enables
120
+
121
+ ### Model relationships naturally
122
+
123
+ Labels and types are first-class. The model is what you read in the
124
+ query:
125
+
126
+ ```cypher
127
+ CREATE (ada:Person {name: 'Ada'})
128
+ CREATE (grace:Person {name: 'Grace'})
129
+ CREATE (ada)-[:INFLUENCED {year: 1843}]->(grace)
130
+ ```
131
+
132
+ No join table, no enum column, no convention to remember.
133
+
134
+ ### Compose queries for reasoning and analysis
135
+
136
+ `WITH` pipes one stage's output into the next, so
137
+ non-trivial questions read top-to-bottom:
138
+
139
+ ```cypher
140
+ MATCH (u:User)-[:PLACED]->(o:Order {status: 'paid'})
141
+ WITH u, count(o) AS orders
142
+ WHERE orders > 1
143
+ RETURN u.email, orders ORDER BY orders DESC
144
+ ```
145
+
146
+ Filter, aggregate, filter again — one expression, no temp tables.
147
+
148
+ ### Keep evolving context cheap
149
+
150
+ LoraDB is schema-free. Adding a new label, a new relationship type,
151
+ or a new property means _writing_ it — there's no migration, no
152
+ `ALTER`, no restart. That fits systems that keep discovering new
153
+ categories of thing.
154
+
155
+ ### Run in-process
156
+
157
+ Opening a database is a function call:
158
+
159
+ ```rust
160
+ let mut db = Database::new();
161
+ db.execute("CREATE (:Person {name: 'Ada'})", None)?;
162
+ ```
163
+
164
+ Same story in [Node](./getting-started/node.md),
165
+ [Python](https://loradb.com/docs/getting-started/python), and
166
+ [WASM](https://loradb.com/docs/getting-started/wasm). There's also an
167
+ [HTTP server](https://loradb.com/docs/getting-started/server) when you'd rather reach it
168
+ over the wire, and a [browser playground](https://play.loradb.com)
169
+ when you'd rather try it before installing anything.
170
+
171
+ ### Stay small enough to understand
172
+
173
+ A small Rust codebase — parser, analyzer, compiler, optimizer,
174
+ executor, storage — readable end-to-end. If the database matters to
175
+ your product, you should be able to read it. That's a deliberate
176
+ constraint, not a marketing line.
177
+
178
+ ## Positioned against the alternatives
179
+
180
+ | | LoraDB | Managed graph DB | SQL + recursive CTEs | Document store |
181
+ |---|---|---|---|---|
182
+ | Deployment | A crate / binding | A service | Existing DB | Existing DB |
183
+ | Relationship model | First-class | First-class | Join tables | Nested or foreign-keyed |
184
+ | Query language | Pragmatic subset of Cypher | Full Cypher / GQL | SQL | Proprietary |
185
+ | Schema | Free | Typed / free | Strict | Free |
186
+ | Latency to query | Function call | Network hop | Network hop | Network hop |
187
+ | Scale | Single process | Horizontal | Horizontal | Horizontal |
188
+ | Fit for in-process / agent loops | Direct | Indirect | Indirect | Indirect |
189
+
190
+ LoraDB is **not** a replacement for a full graph platform when you
191
+ need durability, multi-tenant isolation, or horizontal scale. It's
192
+ the option that was missing in the other direction — the one you
193
+ reach for when the graph belongs _inside_ your process.
194
+
195
+ ## Concrete scenarios
196
+
197
+ - **Agent working memory.** An LLM agent stores tools, observations,
198
+ and entity references as nodes, with typed edges between them. The
199
+ retrieval step is a `MATCH` pattern, not a similarity score.
200
+ - **Robot scene graph.** Objects, rooms, and affordances as nodes;
201
+ "is-on", "can-grasp", "observed-from" as edges. Plan queries run in
202
+ the controller.
203
+ - **Streaming entity resolution.** Events flow in; LoraDB holds the
204
+ current graph of resolved entities; enrichers consult it via
205
+ Cypher and emit back.
206
+ - **Permission inference.** Users, groups, resources, and grants as a
207
+ graph. "Can user U read resource R?" is a reachability query, not
208
+ a recursive SQL.
209
+ - **Lineage and dependency analysis.** Pipelines, models, datasets —
210
+ walk upstream or downstream in one query, not one join per hop.
211
+
212
+ ## Where it's going
213
+
214
+ Near-term direction, not promises:
215
+
216
+ - **Persistence** — optional durable storage behind the same API.
217
+ - **Indexing** — hash and range indexes on property keys.
218
+ - **Query planner improvements** — better join ordering and cost
219
+ estimates.
220
+ - **Richer Cypher surface** — procedures,
221
+ `UNION`, list comprehensions.
222
+
223
+ See [**Limitations**](./limitations.md) for what's not yet supported,
224
+ and the [**docs**](./index.md) for what works today.
225
+
226
+ ## Common questions
227
+
228
+ #### Is LoraDB a drop-in replacement for Neo4j or Memgraph?
229
+
230
+ No. LoraDB supports a scoped subset of Cypher — enough for application-level graph workloads, not the full surface that hosted graph platforms offer. The trade-off is that LoraDB embeds in-process with no separate server, no network hop, and no operational tier to run.
231
+
232
+ #### Does LoraDB scale horizontally?
233
+
234
+ Not today. LoraDB is an embedded engine, not a distributed database. One LoraDB instance lives inside one host process. Horizontal scaling, sharding, and replication are out of scope for the current design; if your dataset does not fit in RAM on one machine, LoraDB is the wrong choice.
235
+
236
+ #### Is LoraDB ACID?
237
+
238
+ Writes serialize at commit through a single lane. Reads run lock-free against an Arc snapshot taken at the start of the query, so concurrent reads never block writes or each other. With WAL enabled, commits are durable; without WAL, durability is at the granularity of explicit snapshots.
239
+
240
+ #### Why an in-memory engine in 2026?
241
+
242
+ Because the workloads LoraDB targets — AI agents, robot scene graphs, permission inference, retrieval over knowledge graphs — touch every node they care about on every query. The working set is hot by definition. Pushing it through a disk-based planner means paying for storage abstractions you do not need.
243
+
244
+ #### Can LoraDB persist data?
245
+
246
+ Yes. Snapshots write the full graph to a single file with an atomic rename and ship on every binding. WAL-backed durability is available on every filesystem-backed surface (Rust, Node, Python, Go, Ruby, and the HTTP server) — commits append to a write-ahead log and replay on recover above the snapshot fence.
247
+
248
+ #### What query language does LoraDB use?
249
+
250
+ A pragmatic subset of Cypher. Read clauses (MATCH, OPTIONAL MATCH, WHERE, WITH, RETURN), write clauses (CREATE, MERGE, SET, DELETE, REMOVE), iteration (UNWIND), paths and variable-length traversals, aggregation, and most built-in functions are supported. See Limitations for what is out of scope.
251
+
252
+ ## See also
253
+
254
+ - [**What is LoraDB**](./index.md) — introduction, audiences, and quick start.
255
+ - [**Installation**](./getting-started/installation.md) — pick your
256
+ platform and get running.
257
+ - [**Ten-Minute Tour**](./getting-started/tutorial.md) — the case from
258
+ "why" to a working query.
259
+ - [**Graph Model**](./concepts/graph-model.md) — the data model in
260
+ four queries.
261
+ - [**Queries → Overview**](./queries/index.md) — the Cypher surface LoraDB
262
+ supports.
263
+ - [**Cookbook**](./cookbook.md) — scenario-driven recipes.
264
+ - [**Limitations**](./limitations.md) — what's not yet supported.
265
+
266
+ ### Background reading
267
+
268
+ - [**Why I started LoraDB**](https://loradb.com/blog/why-i-started-loradb) — the
269
+ original motivation.
270
+ - [**In-memory or it does not work**](https://loradb.com/blog/in-memory-or-it-does-not-work)
271
+ — why the engine starts in RAM.
272
+ - [**Vectors belong next to relationships**](https://loradb.com/blog/vectors-belong-next-to-relationships)
273
+ — why `VECTOR` lives as a first-class value type.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loradb/lora-node",
3
- "version": "0.35.1",
3
+ "version": "0.36.1",
4
4
  "description": "Node.js / TypeScript bindings for the Lora in-memory graph database",
5
5
  "license": "BUSL-1.1",
6
6
  "packageManager": "yarn@4.5.1",
@@ -40,6 +40,7 @@
40
40
  "dist/",
41
41
  "ts/native.js",
42
42
  "ts/native.d.ts",
43
+ "docs/",
43
44
  "README.md",
44
45
  "LICENSE"
45
46
  ],
@@ -72,15 +73,13 @@
72
73
  "scripts": {
73
74
  "sync:types": "node -e \"const fs=require('fs'); for (const f of ['types.ts','decode.ts']) fs.copyFileSync('../shared-ts/' + f, 'ts/' + f);\"",
74
75
  "verify:types": "node -e \"const fs=require('fs'); for (const f of ['types.ts','decode.ts']) { const a=fs.readFileSync('../shared-ts/' + f,'utf8'); const b=fs.readFileSync('ts/' + f,'utf8'); if (a!==b) { console.error('ts/' + f + ' is out of sync with shared-ts/' + f + ' — run yarn run sync:types'); process.exit(1);} } \"",
75
- "prebuild": "yarn run sync:types",
76
- "pretypecheck": "yarn run sync:types",
77
- "pretest": "yarn run sync:types",
78
76
  "build:native": "napi build --platform --release --js false",
79
77
  "build:native:debug": "napi build --platform --js false",
80
78
  "build:ts": "tsc -p tsconfig.json",
81
- "build": "yarn run build:native && yarn run build:ts",
82
- "typecheck": "tsc -p tsconfig.json --noEmit",
83
- "test": "vitest run",
79
+ "build": "yarn run sync:types && yarn run build:native && yarn run build:ts && yarn run docs:bundle",
80
+ "docs:bundle": "node ../../../scripts/bundle-package-docs.mjs",
81
+ "typecheck": "yarn run sync:types && tsc -p tsconfig.json --noEmit",
82
+ "test": "yarn run sync:types && vitest run",
84
83
  "test:watch": "vitest",
85
84
  "lint": "eslint ts test",
86
85
  "lint:fix": "eslint ts test --fix",
@@ -99,12 +98,12 @@
99
98
  "vitest": "^2.1.1"
100
99
  },
101
100
  "optionalDependencies": {
102
- "@loradb/lora-node-linux-x64-gnu": "0.35.1",
103
- "@loradb/lora-node-linux-arm64-gnu": "0.35.1",
104
- "@loradb/lora-node-linux-x64-musl": "0.35.1",
105
- "@loradb/lora-node-linux-arm64-musl": "0.35.1",
106
- "@loradb/lora-node-darwin-x64": "0.35.1",
107
- "@loradb/lora-node-darwin-arm64": "0.35.1",
108
- "@loradb/lora-node-win32-x64-msvc": "0.35.1"
101
+ "@loradb/lora-node-linux-x64-gnu": "0.36.1",
102
+ "@loradb/lora-node-linux-arm64-gnu": "0.36.1",
103
+ "@loradb/lora-node-linux-x64-musl": "0.36.1",
104
+ "@loradb/lora-node-linux-arm64-musl": "0.36.1",
105
+ "@loradb/lora-node-darwin-x64": "0.36.1",
106
+ "@loradb/lora-node-darwin-arm64": "0.36.1",
107
+ "@loradb/lora-node-win32-x64-msvc": "0.36.1"
109
108
  }
110
109
  }