datalevin-node 1.0.2 → 1.2.10
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 +470 -31
- package/jars/datalevin-runtime-1.2.10.jar +4 -0
- package/package.json +1 -1
- package/src/client.js +5 -3
- package/src/connection.js +87 -40
- package/src/convert.js +111 -7
- package/src/database.js +13 -0
- package/src/entity.js +4 -0
- package/src/form.js +408 -0
- package/src/index.js +38 -1
- package/src/interop.js +119 -7
- package/src/kv.js +27 -1
- package/src/native.js +172 -0
- package/src/prepared.js +88 -0
- package/src/query.js +1352 -0
- package/src/resource.js +2 -0
- package/src/transaction.js +312 -0
- package/src/udf-value.js +267 -0
- package/src/udf.js +128 -76
- package/jars/datalevin-runtime-1.0.2.jar +0 -4
package/README.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Node.js bindings for Datalevin over the JVM interop bridge.
|
|
4
4
|
|
|
5
|
+
Visit [datalevin.org](https://datalevin.org) for Datalevin documentation.
|
|
6
|
+
|
|
5
7
|
## Install
|
|
6
8
|
|
|
7
9
|
```bash
|
|
@@ -19,7 +21,14 @@ normal usage does not require building Datalevin from source.
|
|
|
19
21
|
## Quick Start
|
|
20
22
|
|
|
21
23
|
```js
|
|
22
|
-
import { connect } from "datalevin-node";
|
|
24
|
+
import { connect, q, tx } from "datalevin-node";
|
|
25
|
+
|
|
26
|
+
const entity = q.var("entity");
|
|
27
|
+
const name = q.var("name");
|
|
28
|
+
const allNames = q.query({
|
|
29
|
+
find: q.collection(name),
|
|
30
|
+
where: [q.datom(entity, "name", name)]
|
|
31
|
+
});
|
|
23
32
|
|
|
24
33
|
const conn = await connect("/tmp/dtlv-js", {
|
|
25
34
|
schema: {
|
|
@@ -31,12 +40,12 @@ const conn = await connect("/tmp/dtlv-js", {
|
|
|
31
40
|
});
|
|
32
41
|
|
|
33
42
|
try {
|
|
34
|
-
await conn.transact(
|
|
35
|
-
{
|
|
36
|
-
{
|
|
37
|
-
|
|
43
|
+
await conn.transact(tx.data(
|
|
44
|
+
tx.entity({ name: "Ada" }),
|
|
45
|
+
tx.entity({ name: "Bob" })
|
|
46
|
+
));
|
|
38
47
|
|
|
39
|
-
const names = await conn.query(
|
|
48
|
+
const names = await conn.query(allNames);
|
|
40
49
|
const ada = await conn.pull([":name"], 1);
|
|
41
50
|
|
|
42
51
|
console.log(names);
|
|
@@ -46,16 +55,315 @@ try {
|
|
|
46
55
|
}
|
|
47
56
|
```
|
|
48
57
|
|
|
58
|
+
The `q` and `tx` builders are synchronous, pure JavaScript values. Composing
|
|
59
|
+
them does not start the JVM; a connection lowers them to the active backend only
|
|
60
|
+
when `query()` or `transact()` is called.
|
|
61
|
+
|
|
62
|
+
Their contract is an immutable snapshot, not a mutable builder. Construction
|
|
63
|
+
recursively detaches arrays, plain objects, `Map`, `Set`, `Date`, and byte-array
|
|
64
|
+
values. Arrays and objects are frozen; collection and mutable scalar snapshots
|
|
65
|
+
reject mutation, including through values returned by `toForm()`. Mutating an
|
|
66
|
+
input container later therefore cannot change an existing form. Keyword,
|
|
67
|
+
Datalog-symbol, and UUID values are interned by normalized type and value, so
|
|
68
|
+
`q.kw("user/id") === q.kw(":user/id")` and repeated equivalent values occupy
|
|
69
|
+
one `Map` key. JavaScript compound objects still use the language's normal
|
|
70
|
+
identity comparison; the immutable snapshot, rather than structural `===`, is their
|
|
71
|
+
composition contract. Non-structural objects such as backend handles are
|
|
72
|
+
treated as atomic values.
|
|
73
|
+
|
|
74
|
+
## Prepared reads and acknowledgement-only writes
|
|
75
|
+
|
|
76
|
+
`Connection` and `Database` expose `preparePull(selector, opts = null)` and
|
|
77
|
+
`prepareQuery(query)`. `KV` and `KVTransaction` expose
|
|
78
|
+
`prepareGetValue(dbiName, { kType, vType, ignoreKey = true })`; omitted types
|
|
79
|
+
default to `data`. The same names are exported as top-level helpers with the
|
|
80
|
+
connection, database, or KV handle as their first argument.
|
|
81
|
+
|
|
82
|
+
```js
|
|
83
|
+
const readPerson = await conn.preparePull([":name", ":age"]);
|
|
84
|
+
const person = await readPerson.execute([":name", "Ada"]);
|
|
85
|
+
const lookup = await conn.prepareQuery(
|
|
86
|
+
"[:find ?age . :in $ ?name :where [?e :name ?name] [?e :age ?age]]"
|
|
87
|
+
);
|
|
88
|
+
const age = await lookup.execute(["Ada"]);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Prepared queries accept EDN or typed `q` forms. Execute with an array of the
|
|
92
|
+
remaining `:in` values, excluding the database, or `[]` when there are none.
|
|
93
|
+
Results and input conversion match ordinary queries, including dynamic
|
|
94
|
+
`:limit` and `:offset` bindings. `executePrepared(prepared, input)` is an
|
|
95
|
+
equivalent top-level helper.
|
|
96
|
+
|
|
97
|
+
A local prepared pull or KV read accepts `execute(view, input)`, also exposed
|
|
98
|
+
as `executePrepared(prepared, view, input)`, to read an explicit view. Prepared
|
|
99
|
+
queries and remote preparations do not accept explicit views. Use a KV
|
|
100
|
+
transaction's `prepareGetValue` for transaction-bound reads. Keep the owning
|
|
101
|
+
store open; prepared reads require no separate close. Transaction-bound reads
|
|
102
|
+
retain the transaction's lifetime and thread restrictions.
|
|
103
|
+
|
|
104
|
+
`conn.transactAck(txData, txMeta = null)` and `transactAck(conn, ...)` return
|
|
105
|
+
`":transacted"` on success. Validation and durability match `transact`, and
|
|
106
|
+
listeners still receive full reports.
|
|
107
|
+
|
|
108
|
+
Use `schemaAttr({ noIndex: true })` for `:db/noindex`. Reads by entity and pull
|
|
109
|
+
remain available; query conditions on that attribute require
|
|
110
|
+
`await conn.indexAttr(attr)` (or `indexAttr(conn, attr)`) to atomically backfill AVE.
|
|
111
|
+
|
|
112
|
+
## Atomic Updates and Database Notifications
|
|
113
|
+
|
|
114
|
+
`kv.update(dbiName, key, fn, { kType, vType, args })` and
|
|
115
|
+
`updateKv(kv, ...)` atomically replace one value and return `":transacted"`.
|
|
116
|
+
Types default to `":data"`. Embedded callbacks receive the old value (null for
|
|
117
|
+
a missing key), then any extra arguments. Use restricted Clojure function source
|
|
118
|
+
for remote updates:
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
await kv.update("counts", "visits", old => Number(old ?? 0) + 1);
|
|
122
|
+
await remoteKv.update("counts", "visits",
|
|
123
|
+
"(fn [old amount] (+ (long (or old 0)) (long amount)))",
|
|
124
|
+
{ kType: ":string", vType: ":long", args: [1] });
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
JVM long values arrive as `BigInt` in callbacks; use `BigInt` arithmetic or
|
|
128
|
+
convert small counters with `Number`, as in the example above.
|
|
129
|
+
|
|
130
|
+
Functions must be free of side effects because updates may retry. Invalid values
|
|
131
|
+
and callback exceptions abort the update; explicit transactions control commit.
|
|
132
|
+
|
|
133
|
+
`conn.listenDb(callback, key = null)` and `listenDb(conn, ...)` subscribe to
|
|
134
|
+
committed changes to a remote database, including writes from other clients.
|
|
135
|
+
Callbacks receive `{ ":type": ":db-changed", ":db-name": "app" }` and may await
|
|
136
|
+
queries on the connection to refresh data. Several commits may coalesce into one
|
|
137
|
+
event. Terminal failures deliver a `":subscription-error"` event with `":error"`.
|
|
138
|
+
Registering the same key replaces the callback. Call `conn.unlistenDb(key)` or
|
|
139
|
+
`unlistenDb(conn, key)` to stop a subscription; closing the connection stops all
|
|
140
|
+
its subscriptions. `conn.listen` continues to deliver transaction reports.
|
|
141
|
+
|
|
142
|
+
## Composing Queries
|
|
143
|
+
|
|
144
|
+
Use normal JavaScript control flow to assemble clauses. Variables, attributes,
|
|
145
|
+
symbols, and keyword values are explicit, so strings beginning with `?` or `:`
|
|
146
|
+
remain literal strings.
|
|
147
|
+
|
|
148
|
+
The same rule applies recursively to runtime inputs passed to a typed query.
|
|
149
|
+
Use `q.kw("active")` when an input is a keyword. EDN-string and native-array
|
|
150
|
+
queries keep the legacy `":active"` keyword shorthand for compatibility.
|
|
151
|
+
|
|
152
|
+
```js
|
|
153
|
+
const entity = q.var("entity");
|
|
154
|
+
const name = q.var("name");
|
|
155
|
+
const age = q.var("age");
|
|
156
|
+
const minimum = q.var("minimum");
|
|
157
|
+
|
|
158
|
+
const where = [
|
|
159
|
+
q.datom(entity, "person/name", name),
|
|
160
|
+
q.datom(entity, "person/age", age)
|
|
161
|
+
];
|
|
162
|
+
if (adultsOnly) {
|
|
163
|
+
where.push(q.predicate(">=", age, minimum));
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
const people = q.query({
|
|
167
|
+
find: q.collection(name),
|
|
168
|
+
inputs: adultsOnly ? [q.DB, minimum] : [],
|
|
169
|
+
where
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
const names = adultsOnly
|
|
173
|
+
? await conn.query(people, 18)
|
|
174
|
+
: await conn.query(people);
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Available helpers cover relation, collection, tuple, and scalar finds;
|
|
178
|
+
aggregates and pull expressions; database patterns, predicate,
|
|
179
|
+
function-binding, rule, and logical clauses; input bindings, joins, rules,
|
|
180
|
+
ordering, limits, offsets, and timeouts. `q.datom(e, a, v)` is the common
|
|
181
|
+
three-term form; use variable-arity `q.pattern(e, a)` for a presence pattern or
|
|
182
|
+
other supported database-pattern arity. `q.raw()` remains the structured escape
|
|
183
|
+
hatch for new syntax; its tokens must use `q.kw()` and `q.sym()` explicitly.
|
|
184
|
+
Relation queries return an Array of row Arrays. Without `orderBy`, row order is
|
|
185
|
+
unspecified.
|
|
186
|
+
|
|
187
|
+
Typed forms validate structural grammar when they are composed: keyed result
|
|
188
|
+
names must match a relation/tuple find, join variables must be non-empty and
|
|
189
|
+
distinct, ordering must reference distinct projected variables or valid column
|
|
190
|
+
indexes, and branches of one rule name must have matching required/free arity.
|
|
191
|
+
`q.and()` is a branch group for `q.or()` or `q.orJoin()` and is rejected as a
|
|
192
|
+
top-level `:where`, `not`, `not-join`, or rule-body clause. `q.rules(...)` exposes
|
|
193
|
+
the same `asData()` inspection helper as the other typed forms. `q.raw()`
|
|
194
|
+
deliberately bypasses these typed checks.
|
|
195
|
+
|
|
196
|
+
### Composing search clauses
|
|
197
|
+
|
|
198
|
+
Full-text, vector, and indexed-document searches have dedicated clauses and
|
|
199
|
+
position-aware option builders:
|
|
200
|
+
|
|
201
|
+
```js
|
|
202
|
+
const entity = q.var("entity");
|
|
203
|
+
const attribute = q.var("attribute");
|
|
204
|
+
const value = q.var("value");
|
|
205
|
+
const score = q.var("score");
|
|
206
|
+
const distance = q.var("distance");
|
|
207
|
+
|
|
208
|
+
const textClause = q.fulltext(
|
|
209
|
+
q.var("term"),
|
|
210
|
+
[entity, attribute, value, score],
|
|
211
|
+
{
|
|
212
|
+
attribute: "document/text",
|
|
213
|
+
options: q.fulltextOptions({ top: 5, display: "refs+scores" })
|
|
214
|
+
}
|
|
215
|
+
);
|
|
216
|
+
|
|
217
|
+
const vectorClause = q.vecNeighbors(
|
|
218
|
+
q.var("embedding"),
|
|
219
|
+
[entity, attribute, value, distance],
|
|
220
|
+
{
|
|
221
|
+
options: q.vectorSearchOptions({
|
|
222
|
+
domains: ["documents"], top: 10, display: "refs+dists"
|
|
223
|
+
})
|
|
224
|
+
}
|
|
225
|
+
);
|
|
226
|
+
|
|
227
|
+
const idocClause = q.idocMatch(
|
|
228
|
+
q.var("predicate"),
|
|
229
|
+
[entity, attribute, value],
|
|
230
|
+
{ options: q.idocMatchOptions({ domains: ["profiles"] }) }
|
|
231
|
+
);
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Pass either `attribute` or a domain list, as supported by the corresponding
|
|
235
|
+
index. Result Arrays are lowered to relation bindings; an explicit
|
|
236
|
+
`q.relationBinding(...)` is also accepted. Static `display` options validate
|
|
237
|
+
the result width while composing the query: full-text supports `refs`,
|
|
238
|
+
`refs+scores`, `texts`, `offsets`, and `texts+offsets`; vector search supports
|
|
239
|
+
`refs` and `refs+dists`. Use a `q.var()` as `options` when the option map is a
|
|
240
|
+
runtime query input. `source` selects a non-default source.
|
|
241
|
+
|
|
242
|
+
### Composing pull selectors
|
|
243
|
+
|
|
244
|
+
Pull selectors use position-aware forms so option values remain ordinary
|
|
245
|
+
JavaScript data:
|
|
246
|
+
|
|
247
|
+
```js
|
|
248
|
+
const person = q.selector(
|
|
249
|
+
"person/name",
|
|
250
|
+
q.pullAttr("person/nickname", { default: "none", as: "display" }),
|
|
251
|
+
q.pullAttr("person/age", { xform: "str" }),
|
|
252
|
+
q.pullNested("person/friend", q.selector("person/name")),
|
|
253
|
+
q.pullRecursive("person/manager", 2)
|
|
254
|
+
);
|
|
255
|
+
|
|
256
|
+
const result = await conn.pull(person, entityId);
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
`default` and `as` accept arbitrary values and preserve strings recursively.
|
|
260
|
+
A string `xform` is a symbol name; an explicit `q.sym()` is also accepted.
|
|
261
|
+
Omit the second argument to `pullRecursive` for unbounded `...` recursion.
|
|
262
|
+
Existing native-array selectors remain supported and are normalized by pull
|
|
263
|
+
grammar position rather than by their string contents.
|
|
264
|
+
|
|
265
|
+
## Composing Transactions
|
|
266
|
+
|
|
267
|
+
Transaction items compose the same way:
|
|
268
|
+
|
|
269
|
+
```js
|
|
270
|
+
const items = [tx.entity(-1, { "person/name": "Ada" })];
|
|
271
|
+
if (nickname !== null) {
|
|
272
|
+
items.push(tx.add(-1, "person/nickname", nickname));
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
const report = await conn.transact(tx.data(items));
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Use `tx.entity(attrs)` when Datalevin should allocate the entity id, and
|
|
279
|
+
`tx.entity(id, attrs)` when supplying an explicit id or temporary id.
|
|
280
|
+
`tx.entity(null, attrs)` remains accepted for compatibility but is unnecessary.
|
|
281
|
+
|
|
282
|
+
In addition to entity maps, `tx` provides `add`, `retract`,
|
|
283
|
+
`retractAttribute`, `retractEntity`, `compareAndSwap`/`cas`, `call`, `ensure`,
|
|
284
|
+
and `patchIdoc` operations. Context-sensitive transaction values also have
|
|
285
|
+
explicit builders:
|
|
286
|
+
|
|
287
|
+
```js
|
|
288
|
+
const eve = tx.lookupRef("user/handle", "eve");
|
|
289
|
+
|
|
290
|
+
const report = await conn.transact(tx.data(
|
|
291
|
+
tx.entity(-1, {
|
|
292
|
+
"user/handle": "alice",
|
|
293
|
+
"user/friend": eve,
|
|
294
|
+
"user/child": tx.entity(-2, { "user/handle": "child" })
|
|
295
|
+
}),
|
|
296
|
+
tx.patchIdoc(eve, "user/profile", [
|
|
297
|
+
tx.patchSet(["status"], "active"),
|
|
298
|
+
tx.patchUpdate(["visits"], "inc"),
|
|
299
|
+
tx.patchUnset(["obsolete"])
|
|
300
|
+
]),
|
|
301
|
+
tx.invoke("people/audit", eve)
|
|
302
|
+
));
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
`lookupRef` turns only its attribute into a keyword, so its lookup value stays
|
|
306
|
+
literal. The patch builders similarly type only `set`, `unset`, `update`, and
|
|
307
|
+
the update operation; paths, assigned values, and update arguments stay
|
|
308
|
+
ordinary JavaScript values. `invoke` emits the direct form for a transaction
|
|
309
|
+
function installed under a database ident, while `call` emits
|
|
310
|
+
`:db.fn/call`.
|
|
311
|
+
|
|
312
|
+
Wrap a nested entity object in `tx.entity(...)`, as above. A plain nested
|
|
313
|
+
object with ordinary string keys remains data; the builder does not recursively
|
|
314
|
+
convert it into an entity. More generally, values remain ordinary JavaScript
|
|
315
|
+
data; `q.kw()` and `q.sym()` add explicit Datalevin tokens where needed.
|
|
316
|
+
|
|
317
|
+
JavaScript has no built-in UUID scalar. The synchronous `uuid()` helper creates
|
|
318
|
+
an immutable UUID value without starting the JVM; it is validated,
|
|
319
|
+
canonicalized, and lowered only when used by an operation:
|
|
320
|
+
|
|
321
|
+
```js
|
|
322
|
+
import { tx, uuid } from "datalevin-node";
|
|
323
|
+
|
|
324
|
+
const id = uuid("550e8400-e29b-41d4-a716-446655440000");
|
|
325
|
+
await conn.transact(tx.data(tx.entity({ "record/id": id })));
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Repeated equivalent UUID values are interned. UUID results remain canonical
|
|
329
|
+
strings for compatibility; pass such a result through `uuid()` when using it
|
|
330
|
+
again in a typed input position.
|
|
331
|
+
|
|
332
|
+
### EDN lists and quoting
|
|
333
|
+
|
|
334
|
+
JavaScript Arrays represent EDN vectors. Use `q.ednList()` when EDN syntax
|
|
335
|
+
requires a list, such as an IDoc predicate, and `q.quote()` for the common
|
|
336
|
+
`(quote value)` form used by nested queries:
|
|
337
|
+
|
|
338
|
+
```js
|
|
339
|
+
const ageFilter = {
|
|
340
|
+
profile: { age: q.ednList(q.sym(">="), 30) }
|
|
341
|
+
};
|
|
342
|
+
|
|
343
|
+
const age = q.var("age");
|
|
344
|
+
const inner = q.query({
|
|
345
|
+
find: q.relation(q.aggregate("min", age)),
|
|
346
|
+
where: [q.datom(q.IGNORE, "person/age", age)]
|
|
347
|
+
});
|
|
348
|
+
const quotedInner = q.quote(inner);
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Both forms are immutable, backend-neutral values and do not start the JVM.
|
|
352
|
+
Their top-level aliases are `ednList()` and `quote()`. Ordinary strings inside
|
|
353
|
+
an EDN list remain strings; use `q.sym()` for an operator or other symbol. This
|
|
354
|
+
keeps these cases composable without `readEdn()`.
|
|
355
|
+
|
|
49
356
|
## Data Style
|
|
50
357
|
|
|
51
|
-
|
|
358
|
+
The existing EDN and native-form APIs remain supported alongside the builders:
|
|
52
359
|
|
|
53
360
|
- schemas are objects keyed by colon-prefixed attribute strings
|
|
54
|
-
- transaction
|
|
55
|
-
- query and pull forms may be EDN strings or JavaScript arrays
|
|
361
|
+
- transaction data may use `tx`, objects/arrays, or existing `tx*` helpers
|
|
362
|
+
- query and pull forms may be builder values, EDN strings, or JavaScript arrays
|
|
56
363
|
- colon-prefixed strings are converted to keywords in schema/query/form
|
|
57
|
-
positions
|
|
58
|
-
- use `
|
|
364
|
+
positions for the legacy native-form API
|
|
365
|
+
- use synchronous `q.kw()` in builder values, or `keyword()` with the legacy
|
|
366
|
+
API, when the stored value itself is a keyword
|
|
59
367
|
|
|
60
368
|
```js
|
|
61
369
|
import { keyword, readEdn, schemaAttr, txAdd, txEntity, writeEdn } from "datalevin-node";
|
|
@@ -194,37 +502,155 @@ const report = await conn.transactAsync([
|
|
|
194
502
|
]);
|
|
195
503
|
```
|
|
196
504
|
|
|
197
|
-
##
|
|
505
|
+
## Composing UDFs
|
|
198
506
|
|
|
199
|
-
Use
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
`
|
|
203
|
-
`
|
|
204
|
-
|
|
507
|
+
Use the immutable `UdfDescriptor` value with the typed API. It preserves
|
|
508
|
+
keyword types when nested in query inputs, transactions, schema attributes, or
|
|
509
|
+
search-domain options. `q.bindUdf()` binds a query-function result and
|
|
510
|
+
`q.udfPredicate()` creates a predicate clause. Transaction UDFs have explicit
|
|
511
|
+
`tx.callUdf()`, `tx.installUdf()`, and `tx.uninstallUdf()` helpers; an installed
|
|
512
|
+
descriptor can subsequently be called with `tx.invoke()`. Both transaction UDFs
|
|
513
|
+
and predicate UDFs used by `tx.ensure()` receive a `Database` as their first
|
|
514
|
+
callback argument.
|
|
205
515
|
|
|
206
516
|
```js
|
|
207
|
-
import { connect, createUdfRegistry,
|
|
517
|
+
import { UdfDescriptor, connect, createUdfRegistry, q } from "datalevin-node";
|
|
208
518
|
|
|
209
519
|
const registry = await createUdfRegistry();
|
|
210
|
-
|
|
520
|
+
const descriptor = UdfDescriptor.queryFn("math/inc");
|
|
521
|
+
await registry.register(descriptor, (value) => Number(value) + 1);
|
|
211
522
|
|
|
212
|
-
const descriptor = udfDescriptor(":math/inc");
|
|
213
523
|
const conn = await connect("/tmp/dtlv-js-udf", {
|
|
214
524
|
opts: { ":runtime-opts": { ":udf-registry": registry } }
|
|
215
525
|
});
|
|
216
526
|
|
|
217
527
|
try {
|
|
218
|
-
const
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
528
|
+
const descriptorInput = q.var("descriptor");
|
|
529
|
+
const number = q.var("number");
|
|
530
|
+
const value = q.var("value");
|
|
531
|
+
const increment = q.query({
|
|
532
|
+
find: q.scalar(value),
|
|
533
|
+
inputs: [q.DB, descriptorInput, number],
|
|
534
|
+
where: [q.bindUdf(descriptorInput, value, number)]
|
|
535
|
+
});
|
|
536
|
+
console.log(await conn.query(increment, descriptor, 41));
|
|
223
537
|
} finally {
|
|
224
538
|
await conn.close();
|
|
225
539
|
}
|
|
226
540
|
```
|
|
227
541
|
|
|
542
|
+
`udfDescriptor()` remains available and returns the original mutable
|
|
543
|
+
colon-string object for EDN-string and native-array compatibility code.
|
|
544
|
+
`UdfDescriptor` factories, bare IDs passed to a registry, and the
|
|
545
|
+
`queryUdf()`/`predicateUdf()`/`txUdf()`/analyzer registration conveniences
|
|
546
|
+
default to `:javascript`. The legacy helper retains its `:java` default. Both
|
|
547
|
+
forms are accepted by a registry, explicit `{ lang: "java" }` remains
|
|
548
|
+
available, and the typed UDF helpers normalize legacy descriptors when they are
|
|
549
|
+
used explicitly. Typed descriptors are interned by normalized language, kind,
|
|
550
|
+
id, and version, so equivalent descriptors also behave as one key in a
|
|
551
|
+
JavaScript `Map`.
|
|
552
|
+
|
|
553
|
+
## Ordered Custom Types
|
|
554
|
+
|
|
555
|
+
Register a database-wide type through `KV.registerType()` or
|
|
556
|
+
`Connection.registerType()`. Its order function returns an existing backing
|
|
557
|
+
type. Optional payload serializers return `Buffer` or `Uint8Array`, and
|
|
558
|
+
deserializers receive a `Buffer`. Nippy is the default payload codec.
|
|
559
|
+
|
|
560
|
+
```javascript
|
|
561
|
+
import { UdfDescriptor, createUdfRegistry, openKv } from "datalevin-node";
|
|
562
|
+
|
|
563
|
+
const registry = await createUdfRegistry();
|
|
564
|
+
await registry.orderUdf("task/order", task => task.rank);
|
|
565
|
+
await registry.serializerUdf("task/encode", task =>
|
|
566
|
+
Buffer.from(JSON.stringify(task, (_key, value) =>
|
|
567
|
+
typeof value === "bigint" ? Number(value) : value)));
|
|
568
|
+
await registry.deserializerUdf("task/decode", payload => {
|
|
569
|
+
const task = JSON.parse(payload.toString("utf8"));
|
|
570
|
+
return { ...task, rank: BigInt(task.rank) };
|
|
571
|
+
});
|
|
572
|
+
const definition = {
|
|
573
|
+
index: { type: ":long", "order-fn": UdfDescriptor.orderFn("task/order") },
|
|
574
|
+
payload: {
|
|
575
|
+
serialize: UdfDescriptor.serializer("task/encode"),
|
|
576
|
+
deserialize: UdfDescriptor.deserializer("task/decode")
|
|
577
|
+
}
|
|
578
|
+
};
|
|
579
|
+
const kv = await openKv("/tmp/datalevin-custom-example", {
|
|
580
|
+
":runtime-opts": { ":udf-registry": registry }
|
|
581
|
+
});
|
|
582
|
+
try {
|
|
583
|
+
await kv.registerType("app/task", definition);
|
|
584
|
+
await kv.openDbi("tasks", { ":key-type": ":app/task" });
|
|
585
|
+
const task = { rank: 2n, name: "Compile" };
|
|
586
|
+
await kv.transact([[":put", task, "queued"]], { dbiName: "tasks" });
|
|
587
|
+
console.log(await kv.getValue("tasks", task)); // queued
|
|
588
|
+
} finally {
|
|
589
|
+
await kv.close();
|
|
590
|
+
}
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
For Datalog, register through the connection and set an attribute's
|
|
594
|
+
`:db/valueType` to `:app/task`. Ordered list items use the DBI option
|
|
595
|
+
`{ ":value-type": ":app/task" }`. Registrations persist and are shared by both
|
|
596
|
+
APIs. Supply runtime bindings again when reopening. Remote stores execute
|
|
597
|
+
functions using bindings installed on the server.
|
|
598
|
+
|
|
599
|
+
For native JavaScript classes, bind the class before opening the local
|
|
600
|
+
environment. Ordinary KV and Datalog operations then accept and return instances:
|
|
601
|
+
|
|
602
|
+
```javascript
|
|
603
|
+
import { UdfDescriptor, createUdfRegistry, openKv } from "datalevin-node";
|
|
604
|
+
|
|
605
|
+
class Task {
|
|
606
|
+
constructor(rank, label) { this.rank = rank; this.label = label; }
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
const registry = await createUdfRegistry();
|
|
610
|
+
await registry.orderUdf("native/order", task => task.rank);
|
|
611
|
+
await registry.serializerUdf("native/encode", task =>
|
|
612
|
+
Buffer.from(JSON.stringify([task.rank.toString(), task.label])));
|
|
613
|
+
await registry.deserializerUdf("native/decode", payload => {
|
|
614
|
+
const [rank, label] = JSON.parse(payload.toString("utf8"));
|
|
615
|
+
return new Task(BigInt(rank), label);
|
|
616
|
+
});
|
|
617
|
+
const definition = {
|
|
618
|
+
index: { type: ":long", "order-fn": UdfDescriptor.orderFn("native/order") },
|
|
619
|
+
payload: { serialize: UdfDescriptor.serializer("native/encode"),
|
|
620
|
+
deserialize: UdfDescriptor.deserializer("native/decode") }
|
|
621
|
+
};
|
|
622
|
+
await registry.bindNativeType("app/task", Task, definition);
|
|
623
|
+
const kv = await openKv("/tmp/datalevin-js-native", {
|
|
624
|
+
":runtime-opts": { ":udf-registry": registry }
|
|
625
|
+
});
|
|
626
|
+
try {
|
|
627
|
+
await kv.registerType("app/task", definition);
|
|
628
|
+
await kv.openDbi("tasks", { ":key-type": ":app/task" });
|
|
629
|
+
await kv.transact([[":put", new Task(1n, "Compile"), "queued"]], { dbiName: "tasks" });
|
|
630
|
+
console.log(await kv.getValue("tasks", new Task(1n, "Compile"))); // queued
|
|
631
|
+
console.log(await kv.getRange("tasks", [":all"])); // [[Task { ... }, "queued"]]
|
|
632
|
+
} finally {
|
|
633
|
+
await kv.close();
|
|
634
|
+
}
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
Recreate the runtime class binding and UDF implementations on reopen. Serde
|
|
638
|
+
functions may be async. Exact matching defaults to `node:util.isDeepStrictEqual`
|
|
639
|
+
on decoded values, so equal instances may serialize to different bytes. For
|
|
640
|
+
classes with private fields, or a different value-equality rule, pass
|
|
641
|
+
`{ equals: (left, right) => /* boolean */ }` as the fourth argument to
|
|
642
|
+
`bindNativeType`. Equality may also be async and must remain stable and symmetric.
|
|
643
|
+
|
|
644
|
+
Native support covers local and remote operations, including query spilling to
|
|
645
|
+
disk. Remote handles use the caller registry in `:runtime-opts`; install matching
|
|
646
|
+
order/serde UDFs on the server through `datalevin.server/*server-runtime-opts-fn*`.
|
|
647
|
+
Only type names and payload bytes cross the network. The caller's deserializer
|
|
648
|
+
and equality function reconstruct returned values, including asynchronous hooks.
|
|
649
|
+
Untyped `:data` and eager helpers without a database handle remain unsupported.
|
|
650
|
+
Native values currently share a constant JVM hash,
|
|
651
|
+
so large hash joins and deduplication can be expensive. See the
|
|
652
|
+
[custom data guide](../../doc/custom-data.md#native-javascript-values).
|
|
653
|
+
|
|
228
654
|
## Fulltext Analyzer UDF Example
|
|
229
655
|
|
|
230
656
|
Use analyzer UDFs when a Datalog fulltext domain needs host-language tokenizing.
|
|
@@ -237,14 +663,14 @@ import {
|
|
|
237
663
|
createUdfRegistry,
|
|
238
664
|
schemaAttr,
|
|
239
665
|
searchDomain,
|
|
240
|
-
|
|
666
|
+
UdfDescriptor
|
|
241
667
|
} from "datalevin-node";
|
|
242
668
|
|
|
243
669
|
const registry = await createUdfRegistry();
|
|
244
|
-
const analyzer =
|
|
245
|
-
const queryAnalyzer =
|
|
670
|
+
const analyzer = UdfDescriptor.analyzer("text/hashtags");
|
|
671
|
+
const queryAnalyzer = UdfDescriptor.queryAnalyzer("text/plain-query");
|
|
246
672
|
|
|
247
|
-
await registry.
|
|
673
|
+
await registry.register(analyzer, (text) => {
|
|
248
674
|
const tokens = [];
|
|
249
675
|
const pattern = /#\w+/g;
|
|
250
676
|
const source = String(text);
|
|
@@ -255,7 +681,7 @@ await registry.analyzerUdf(":text/hashtags", (text) => {
|
|
|
255
681
|
return tokens;
|
|
256
682
|
});
|
|
257
683
|
|
|
258
|
-
await registry.
|
|
684
|
+
await registry.register(queryAnalyzer, (text) => (
|
|
259
685
|
String(text).trim().split(/\s+/).filter(Boolean)
|
|
260
686
|
.map((token, position) => [token, position, position])
|
|
261
687
|
));
|
|
@@ -337,6 +763,12 @@ Use `initDb()` and `fillDb()` when you already have Datom-shaped data and want
|
|
|
337
763
|
the fast bulk-load path. Datoms can be compact arrays in
|
|
338
764
|
`[entityId, attr, value]` shape, and `datom()` creates the same shape.
|
|
339
765
|
|
|
766
|
+
For a server database, pass its authenticated `dtlv://` URI as `dir` instead of
|
|
767
|
+
a local path. Both `fillDb(conn, datoms)` and `conn.fillDb(datoms)` support remote
|
|
768
|
+
connections. Remote loads preserve server WAL settings and commit in batches;
|
|
769
|
+
outside an explicit transaction, earlier batches remain committed if a later
|
|
770
|
+
batch fails. Use assigned entity IDs and trusted data matching the schema.
|
|
771
|
+
|
|
340
772
|
```js
|
|
341
773
|
import { datom, fillDb, initDb } from "datalevin-node";
|
|
342
774
|
|
|
@@ -577,6 +1009,13 @@ npm install
|
|
|
577
1009
|
npm test
|
|
578
1010
|
```
|
|
579
1011
|
|
|
1012
|
+
The test suite also executes every case selected by the active release in the
|
|
1013
|
+
sibling `dtlvtest` golden spec. It discovers `../dtlvtest` automatically; set
|
|
1014
|
+
`DTLVTEST_ROOT=/path/to/dtlvtest` for a checkout elsewhere. The conformance
|
|
1015
|
+
adapter reads `spec/manifest.edn`, preserves EDN keyword and symbol types, and
|
|
1016
|
+
lowers each dataset, transaction, and query through the typed JavaScript
|
|
1017
|
+
builders. The test is skipped only when no `dtlvtest` checkout is available.
|
|
1018
|
+
|
|
580
1019
|
`vendor-jar` builds a platform-specific runtime jar for the current build host
|
|
581
1020
|
by default. To keep the cross-platform native payloads, pass:
|
|
582
1021
|
|
package/package.json
CHANGED
package/src/client.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { toEdnForm, toQueryInput } from "./convert.js";
|
|
1
|
+
import { toEdnForm, toJava, toQueryInput } from "./convert.js";
|
|
2
|
+
import { Form } from "./form.js";
|
|
2
3
|
import { _BINDINGS } from "./interop.js";
|
|
3
4
|
import { classes } from "./jvm.js";
|
|
4
5
|
import { ResourceWrapper } from "./resource.js";
|
|
@@ -16,7 +17,7 @@ async function clientIdInput(value) {
|
|
|
16
17
|
const cls = await classes();
|
|
17
18
|
return cls.uuid.fromStringSync(value);
|
|
18
19
|
}
|
|
19
|
-
return value;
|
|
20
|
+
return toJava(value);
|
|
20
21
|
}
|
|
21
22
|
|
|
22
23
|
export class Client extends ResourceWrapper {
|
|
@@ -164,9 +165,10 @@ export class Client extends ResourceWrapper {
|
|
|
164
165
|
}
|
|
165
166
|
|
|
166
167
|
async querySystem(query, ...args) {
|
|
168
|
+
const convertInput = query instanceof Form ? toJava : toQueryInput;
|
|
167
169
|
const normalizedInputs = [];
|
|
168
170
|
for (const value of args) {
|
|
169
|
-
normalizedInputs.push(await
|
|
171
|
+
normalizedInputs.push(await convertInput(value));
|
|
170
172
|
}
|
|
171
173
|
return toJsResult(
|
|
172
174
|
await _BINDINGS.clientInvoke("query-system", [
|