datalevin-node 1.0.2 → 1.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/src/form.js ADDED
@@ -0,0 +1,408 @@
1
+ function tokenText(value, prefix) {
2
+ if (typeof value !== "string") {
3
+ throw new TypeError(`Datalevin token names must be strings, got ${typeof value}.`);
4
+ }
5
+ const text = prefix && value.startsWith(prefix) ? value.slice(prefix.length) : value;
6
+ if (text.length === 0) {
7
+ throw new TypeError("Datalevin token names must not be empty.");
8
+ }
9
+ if (/\s/.test(text)) {
10
+ throw new TypeError(`Datalevin token names must not contain whitespace: ${JSON.stringify(value)}.`);
11
+ }
12
+ return text;
13
+ }
14
+
15
+ function tokenPool() {
16
+ const references = new Map();
17
+ const finalizer = new FinalizationRegistry(({ name, reference }) => {
18
+ if (references.get(name) === reference) {
19
+ references.delete(name);
20
+ }
21
+ });
22
+
23
+ return {
24
+ get(name) {
25
+ const value = references.get(name)?.deref();
26
+ if (value === undefined) {
27
+ references.delete(name);
28
+ }
29
+ return value;
30
+ },
31
+ set(name, value) {
32
+ const reference = new WeakRef(value);
33
+ references.set(name, reference);
34
+ finalizer.register(value, { name, reference });
35
+ }
36
+ };
37
+ }
38
+
39
+ const KEYWORDS = tokenPool();
40
+ const DATALOG_SYMBOLS = tokenPool();
41
+ const UUIDS = tokenPool();
42
+ const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
43
+
44
+ export class Keyword {
45
+ constructor(name) {
46
+ const text = tokenText(name, ":");
47
+ const existing = KEYWORDS.get(text);
48
+ if (existing !== undefined) {
49
+ return existing;
50
+ }
51
+ this.name = text;
52
+ Object.freeze(this);
53
+ KEYWORDS.set(text, this);
54
+ }
55
+
56
+ toString() {
57
+ return `:${this.name}`;
58
+ }
59
+ }
60
+
61
+ export class DatalogSymbol {
62
+ constructor(name) {
63
+ const text = tokenText(name, "");
64
+ const existing = DATALOG_SYMBOLS.get(text);
65
+ if (existing !== undefined) {
66
+ return existing;
67
+ }
68
+ this.name = text;
69
+ Object.freeze(this);
70
+ DATALOG_SYMBOLS.set(text, this);
71
+ }
72
+
73
+ toString() {
74
+ return this.name;
75
+ }
76
+ }
77
+
78
+ export class Uuid {
79
+ constructor(value) {
80
+ if (value instanceof Uuid) {
81
+ return value;
82
+ }
83
+ if (typeof value !== "string") {
84
+ throw new TypeError(`Datalevin UUID values must be strings, got ${typeof value}.`);
85
+ }
86
+ const text = value.toLowerCase();
87
+ if (!UUID_PATTERN.test(text)) {
88
+ throw new TypeError(`Invalid UUID value: ${JSON.stringify(value)}.`);
89
+ }
90
+ const existing = UUIDS.get(text);
91
+ if (existing !== undefined) {
92
+ return existing;
93
+ }
94
+ this.value = text;
95
+ Object.freeze(this);
96
+ UUIDS.set(text, this);
97
+ }
98
+
99
+ toString() {
100
+ return this.value;
101
+ }
102
+
103
+ toJSON() {
104
+ return this.value;
105
+ }
106
+ }
107
+
108
+ export function uuid(value) {
109
+ return value instanceof Uuid ? value : new Uuid(value);
110
+ }
111
+
112
+ export class Form {
113
+ toForm() {
114
+ throw new TypeError(`${this.constructor.name}.toForm() is not implemented.`);
115
+ }
116
+ }
117
+
118
+ export class EdnList extends Form {
119
+ constructor(...items) {
120
+ super();
121
+ this.items = immutableSnapshot(items);
122
+ Object.freeze(this);
123
+ }
124
+
125
+ get length() {
126
+ return this.items.length;
127
+ }
128
+
129
+ at(index) {
130
+ return this.items.at(index);
131
+ }
132
+
133
+ [Symbol.iterator]() {
134
+ return this.items[Symbol.iterator]();
135
+ }
136
+
137
+ toForm() {
138
+ return this;
139
+ }
140
+
141
+ asData() {
142
+ return formData(this);
143
+ }
144
+ }
145
+
146
+ export function ednList(...items) {
147
+ return new EdnList(...items);
148
+ }
149
+
150
+ export function quote(value) {
151
+ return new EdnList(new DatalogSymbol("quote"), value);
152
+ }
153
+
154
+ const IMMUTABLE_SNAPSHOTS = new WeakSet();
155
+ const DATE_MUTATORS = [
156
+ "setDate",
157
+ "setFullYear",
158
+ "setHours",
159
+ "setMilliseconds",
160
+ "setMinutes",
161
+ "setMonth",
162
+ "setSeconds",
163
+ "setTime",
164
+ "setUTCDate",
165
+ "setUTCFullYear",
166
+ "setUTCHours",
167
+ "setUTCMilliseconds",
168
+ "setUTCMinutes",
169
+ "setUTCMonth",
170
+ "setUTCSeconds",
171
+ "setYear"
172
+ ];
173
+ const BYTE_MUTATORS = new Set(["copyWithin", "fill", "reverse", "set", "sort"]);
174
+
175
+ function mutationError() {
176
+ throw new TypeError("Datalevin form snapshots are immutable.");
177
+ }
178
+
179
+ function readonlyMap(entries) {
180
+ const target = new Map(entries);
181
+ Object.freeze(target);
182
+ let result;
183
+ result = new Proxy(target, {
184
+ get(current, property) {
185
+ if (property === "set" || property === "delete" || property === "clear") {
186
+ return mutationError;
187
+ }
188
+ if (property === "valueOf") {
189
+ return () => result;
190
+ }
191
+ if (property === "forEach") {
192
+ return (callback, thisArg) => current.forEach(
193
+ (item, key) => callback.call(thisArg, item, key, result)
194
+ );
195
+ }
196
+ const item = Reflect.get(current, property, current);
197
+ return typeof item === "function" ? item.bind(current) : item;
198
+ },
199
+ set: mutationError,
200
+ defineProperty: mutationError,
201
+ deleteProperty: mutationError,
202
+ setPrototypeOf: mutationError
203
+ });
204
+ IMMUTABLE_SNAPSHOTS.add(result);
205
+ return result;
206
+ }
207
+
208
+ function readonlySet(items) {
209
+ const target = new Set(items);
210
+ Object.freeze(target);
211
+ let result;
212
+ result = new Proxy(target, {
213
+ get(current, property) {
214
+ if (property === "add" || property === "delete" || property === "clear") {
215
+ return mutationError;
216
+ }
217
+ if (property === "valueOf") {
218
+ return () => result;
219
+ }
220
+ if (property === "forEach") {
221
+ return (callback, thisArg) => current.forEach(
222
+ (item) => callback.call(thisArg, item, item, result)
223
+ );
224
+ }
225
+ const item = Reflect.get(current, property, current);
226
+ return typeof item === "function" ? item.bind(current) : item;
227
+ },
228
+ set: mutationError,
229
+ defineProperty: mutationError,
230
+ deleteProperty: mutationError,
231
+ setPrototypeOf: mutationError
232
+ });
233
+ IMMUTABLE_SNAPSHOTS.add(result);
234
+ return result;
235
+ }
236
+
237
+ function readonlyDate(value) {
238
+ const target = new Date(value.getTime());
239
+ Object.freeze(target);
240
+ const result = new Proxy(target, {
241
+ get(current, property) {
242
+ if (DATE_MUTATORS.includes(property)) {
243
+ return mutationError;
244
+ }
245
+ const item = Reflect.get(current, property, current);
246
+ return typeof item === "function" ? item.bind(current) : item;
247
+ },
248
+ set: mutationError,
249
+ defineProperty: mutationError,
250
+ deleteProperty: mutationError,
251
+ setPrototypeOf: mutationError
252
+ });
253
+ IMMUTABLE_SNAPSHOTS.add(result);
254
+ return result;
255
+ }
256
+
257
+ function readonlyBytes(value) {
258
+ const target = Uint8Array.from(value);
259
+ let result;
260
+ result = new Proxy(target, {
261
+ get(current, property) {
262
+ if (property === "buffer") {
263
+ return current.buffer.slice(
264
+ current.byteOffset,
265
+ current.byteOffset + current.byteLength
266
+ );
267
+ }
268
+ if (property === "subarray") {
269
+ return (...args) => Uint8Array.from(current.subarray(...args));
270
+ }
271
+ if (property === "valueOf") {
272
+ return () => result;
273
+ }
274
+ if (BYTE_MUTATORS.has(property)) {
275
+ return mutationError;
276
+ }
277
+ const item = Reflect.get(current, property, current);
278
+ return typeof item === "function" ? item.bind(current) : item;
279
+ },
280
+ set: mutationError,
281
+ defineProperty: mutationError,
282
+ deleteProperty: mutationError,
283
+ setPrototypeOf: mutationError
284
+ });
285
+ IMMUTABLE_SNAPSHOTS.add(result);
286
+ return result;
287
+ }
288
+
289
+ function plainObject(value) {
290
+ if (value === null || typeof value !== "object") {
291
+ return false;
292
+ }
293
+ const prototype = Object.getPrototypeOf(value);
294
+ return prototype === Object.prototype || prototype === null;
295
+ }
296
+
297
+ function withContainer(value, active, build) {
298
+ if (active.has(value)) {
299
+ throw new TypeError("Datalevin forms cannot contain cyclic containers.");
300
+ }
301
+ active.add(value);
302
+ try {
303
+ return build();
304
+ } finally {
305
+ active.delete(value);
306
+ }
307
+ }
308
+
309
+ export function immutableSnapshot(value, active = new Set()) {
310
+ if (
311
+ value === null
312
+ || (typeof value !== "object" && typeof value !== "function")
313
+ || value instanceof Keyword
314
+ || value instanceof DatalogSymbol
315
+ || value instanceof Uuid
316
+ || value instanceof Form
317
+ || IMMUTABLE_SNAPSHOTS.has(value)
318
+ ) {
319
+ return value;
320
+ }
321
+
322
+ if (value instanceof Date) {
323
+ return readonlyDate(value);
324
+ }
325
+ if (value instanceof Uint8Array) {
326
+ return readonlyBytes(value);
327
+ }
328
+ if (Array.isArray(value)) {
329
+ return withContainer(value, active, () => {
330
+ const result = value.map((item) => immutableSnapshot(item, active));
331
+ IMMUTABLE_SNAPSHOTS.add(result);
332
+ return Object.freeze(result);
333
+ });
334
+ }
335
+ if (value instanceof Map) {
336
+ return withContainer(value, active, () => readonlyMap(
337
+ Array.from(
338
+ value,
339
+ ([key, item]) => [
340
+ immutableSnapshot(key, active),
341
+ immutableSnapshot(item, active)
342
+ ]
343
+ )
344
+ ));
345
+ }
346
+ if (value instanceof Set) {
347
+ return withContainer(value, active, () => readonlySet(
348
+ Array.from(value, (item) => immutableSnapshot(item, active))
349
+ ));
350
+ }
351
+ if (plainObject(value)) {
352
+ return withContainer(value, active, () => {
353
+ const result = Object.create(Object.getPrototypeOf(value));
354
+ for (const [key, item] of Object.entries(value)) {
355
+ Object.defineProperty(result, key, {
356
+ configurable: false,
357
+ enumerable: true,
358
+ value: immutableSnapshot(item, active),
359
+ writable: false
360
+ });
361
+ }
362
+ IMMUTABLE_SNAPSHOTS.add(result);
363
+ return Object.freeze(result);
364
+ });
365
+ }
366
+
367
+ // Backend handles and other non-structural host objects are atomic values.
368
+ return value;
369
+ }
370
+
371
+ export class RawForm extends Form {
372
+ constructor(value) {
373
+ super();
374
+ this.value = immutableSnapshot(value);
375
+ Object.freeze(this);
376
+ }
377
+
378
+ toForm() {
379
+ return this.value;
380
+ }
381
+ }
382
+
383
+ export function formData(value) {
384
+ if (value instanceof EdnList) {
385
+ return new EdnList(...Array.from(value, formData));
386
+ }
387
+ if (value instanceof Form) {
388
+ return formData(value.toForm());
389
+ }
390
+ if (value instanceof Keyword || value instanceof DatalogSymbol) {
391
+ return value.toString();
392
+ }
393
+ if (value instanceof Map) {
394
+ return new Map(Array.from(value, ([key, item]) => [formData(key), formData(item)]));
395
+ }
396
+ if (value instanceof Set) {
397
+ return new Set(Array.from(value, formData));
398
+ }
399
+ if (Array.isArray(value)) {
400
+ return value.map(formData);
401
+ }
402
+ if (plainObject(value)) {
403
+ return Object.fromEntries(
404
+ Object.entries(value).map(([key, item]) => [key, formData(item)])
405
+ );
406
+ }
407
+ return value;
408
+ }
package/src/index.js CHANGED
@@ -64,6 +64,26 @@ export {
64
64
  writeEdn
65
65
  } from "./interop.js";
66
66
  export { interop } from "./raw.js";
67
+ export {
68
+ DatalogSymbol,
69
+ EdnList,
70
+ Keyword,
71
+ Uuid,
72
+ ednList,
73
+ quote,
74
+ uuid
75
+ } from "./form.js";
76
+ export {
77
+ FulltextOptions,
78
+ IdocMatchOptions,
79
+ PullAttr,
80
+ PullNested,
81
+ PullSelector,
82
+ Query,
83
+ VectorSearchOptions,
84
+ q
85
+ } from "./query.js";
86
+ export { LookupRef, PatchOp, TxData, tx } from "./transaction.js";
67
87
  export { KV, KVTransaction, RawBuffer, RawKV } from "./kv.js";
68
88
  export { LlamaEmbedder, LlamaGenerator } from "./llm.js";
69
89
  export {
@@ -81,5 +101,10 @@ export {
81
101
  prefixTokenFilter,
82
102
  unaccentTokenFilter
83
103
  } from "./search.js";
84
- export { UdfRegistry, createUdfRegistry, udfDescriptor } from "./udf.js";
104
+ export {
105
+ UdfDescriptor,
106
+ UdfRegistry,
107
+ createUdfRegistry,
108
+ udfDescriptor
109
+ } from "./udf.js";
85
110
  export { VectorIndex } from "./vector.js";
package/src/interop.js CHANGED
@@ -161,6 +161,22 @@ class InteropBindings {
161
161
  return callJavaMethod(cls.interop, "connectionDbBridge", handle);
162
162
  }
163
163
 
164
+ async connectionQuery(handle, query, inputs, { form = false } = {}) {
165
+ const cls = await classes();
166
+ const bridgeMethod = form
167
+ ? "connectionQueryFormBridge"
168
+ : "connectionQueryBridge";
169
+ if (typeof cls.interop[bridgeMethod] === "function") {
170
+ return callJavaMethod(cls.interop, bridgeMethod, handle, query, inputs);
171
+ }
172
+
173
+ // Compatibility for runtimes predating the in-JVM query bridge. Runtime
174
+ // builds that return SpillableSet require the bridge method above.
175
+ const method = form ? "queryForm" : "query";
176
+ const result = await callJavaMethod(handle, method, query, inputs);
177
+ return callJavaMethod(cls.interop, "bridgeResult", result);
178
+ }
179
+
164
180
  async connectionEntity(handle, eid) {
165
181
  const cls = await classes();
166
182
  return callJavaMethod(