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 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
- { ":db/id": -1, ":name": "Ada" },
36
- { ":db/id": -2, ":name": "Bob" }
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("[:find [?name ...] :where [?e :name ?name]]");
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
- Use ordinary JavaScript data as the canonical style:
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 entity maps are objects, and transaction forms are arrays
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 `keyword()` when the stored value itself must be a keyword
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
- ## UDF Example
505
+ ## Composing UDFs
198
506
 
199
- Use `createUdfRegistry()` and `udfDescriptor()` for runtime UDFs. Pass the
200
- registry in connection runtime options, then call the descriptor from query with
201
- Datalevin's `udf` function. Fulltext analyzers use the same route with
202
- `registry.analyzerUdf()` or `registry.queryAnalyzerUdf()` and descriptors in
203
- `searchDomain({ analyzer, queryAnalyzer })`. Analyzer functions return
204
- `[term, position, offset]` triples.
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, udfDescriptor } from "datalevin-node";
517
+ import { UdfDescriptor, connect, createUdfRegistry, q } from "datalevin-node";
208
518
 
209
519
  const registry = await createUdfRegistry();
210
- await registry.queryUdf(":math/inc", (value) => Number(value) + 1);
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 value = await conn.query(
219
- "[:find ?v . :in $ ?desc ?n :where [(udf ?desc ?n) ?v]]",
220
- descriptor,
221
- 41
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
- udfDescriptor
666
+ UdfDescriptor
241
667
  } from "datalevin-node";
242
668
 
243
669
  const registry = await createUdfRegistry();
244
- const analyzer = udfDescriptor(":text/hashtags", { kind: ":analyzer" });
245
- const queryAnalyzer = udfDescriptor(":text/plain-query", { kind: ":query-analyzer" });
670
+ const analyzer = UdfDescriptor.analyzer("text/hashtags");
671
+ const queryAnalyzer = UdfDescriptor.queryAnalyzer("text/plain-query");
246
672
 
247
- await registry.analyzerUdf(":text/hashtags", (text) => {
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.queryAnalyzerUdf(":text/plain-query", (text) => (
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
 
@@ -0,0 +1,4 @@
1
+ [diffend] Oversized file quarantined before diffing.
2
+ name: package/jars/datalevin-runtime-1.2.10.jar
3
+ size: 41127521 bytes
4
+ sha256: 61e97d4cd17f42f8e53332cbbdb2ced56ea91c895d7fceb858debd4c8fea3b15
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "datalevin-node",
3
- "version": "1.0.2",
3
+ "version": "1.2.10",
4
4
  "description": "Node.js bindings for Datalevin over the JVM interop bridge",
5
5
  "type": "module",
6
6
  "repository": {
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 toQueryInput(value));
171
+ normalizedInputs.push(await convertInput(value));
170
172
  }
171
173
  return toJsResult(
172
174
  await _BINDINGS.clientInvoke("query-system", [