datalevin-node 0.10.17 → 1.0.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/kv.js CHANGED
@@ -1,9 +1,12 @@
1
- import { toEdnForm, toJava } from "./convert.js";
1
+ import { toEdnForm, toJava, toJs } from "./convert.js";
2
+ import { DatalevinError } from "./errors.js";
2
3
  import { _BINDINGS } from "./interop.js";
3
- import { callJavaMethod } from "./jvm.js";
4
+ import { callJavaMethod, javaBridgeModule } from "./jvm.js";
4
5
  import { ResourceWrapper } from "./resource.js";
5
6
  import { toJsResult } from "./result.js";
6
7
 
8
+ const NO_TIMEOUT_OPTION = Symbol("no-timeout-option");
9
+
7
10
  function slicePage(items, limit = null, offset = null) {
8
11
  const start = offset === null || offset === undefined ? 0 : Math.max(offset, 0);
9
12
  if (limit === null || limit === undefined) {
@@ -12,11 +15,243 @@ function slicePage(items, limit = null, offset = null) {
12
15
  return items.slice(start, start + Math.max(limit, 0));
13
16
  }
14
17
 
15
- export class KV extends ResourceWrapper {
18
+ function hasValue(value) {
19
+ return value !== null && value !== undefined;
20
+ }
21
+
22
+ function requireKType(kType, methodName) {
23
+ if (!hasValue(kType)) {
24
+ throw new TypeError(`kType is required for KV ${methodName}().`);
25
+ }
26
+ }
27
+
28
+ function requireVType(vType, methodName) {
29
+ if (!hasValue(vType)) {
30
+ throw new TypeError(`vType is required for KV ${methodName}().`);
31
+ }
32
+ }
33
+
34
+ function rejectVTypeWithoutKType(kType, vType, methodName) {
35
+ if (hasValue(vType) && !hasValue(kType)) {
36
+ throw new TypeError(`vType requires kType for KV ${methodName}().`);
37
+ }
38
+ }
39
+
40
+ async function envFlags(flags) {
41
+ const items = typeof flags === "string" ? [flags] : [...flags];
42
+ const result = new Set();
43
+ for (const flag of items) {
44
+ const text = String(flag);
45
+ result.add(await _BINDINGS.keyword(text.startsWith(":") ? text : `:${text}`));
46
+ }
47
+ return result;
48
+ }
49
+
50
+ function requireCallback(fn, methodName) {
51
+ if (typeof fn !== "function") {
52
+ throw new TypeError(`callback is required for KV ${methodName}().`);
53
+ }
54
+ }
55
+
56
+ function normalizeTimeoutMs(value, methodName) {
57
+ if (!hasValue(value)) {
58
+ return null;
59
+ }
60
+ const timeoutMs = Number(value);
61
+ if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
62
+ throw new TypeError(`timeoutMs for KV ${methodName}() must be a positive integer.`);
63
+ }
64
+ return timeoutMs;
65
+ }
66
+
67
+ function timeoutOption(options, methodName) {
68
+ if (!hasValue(options)) {
69
+ return NO_TIMEOUT_OPTION;
70
+ }
71
+ if (typeof options === "number") {
72
+ return normalizeTimeoutMs(options, methodName);
73
+ }
74
+ if (typeof options === "object") {
75
+ if (Object.prototype.hasOwnProperty.call(options, "timeoutMs")) {
76
+ return normalizeTimeoutMs(options.timeoutMs, methodName);
77
+ }
78
+ if (Object.prototype.hasOwnProperty.call(options, "timeout_ms")) {
79
+ return normalizeTimeoutMs(options.timeout_ms, methodName);
80
+ }
81
+ }
82
+ return NO_TIMEOUT_OPTION;
83
+ }
84
+
85
+ function withTransactionArgs(first, second) {
86
+ if (typeof first === "function") {
87
+ return { fn: first, timeoutOption: timeoutOption(second, "withTransaction") };
88
+ }
89
+ if (typeof second === "function") {
90
+ return { fn: second, timeoutOption: timeoutOption(first, "withTransaction") };
91
+ }
92
+ throw new TypeError("fn must be a function.");
93
+ }
94
+
95
+ async function resolveExplicitTransactionTimeout(option) {
96
+ if (option !== NO_TIMEOUT_OPTION) {
97
+ return option;
98
+ }
99
+ try {
100
+ return toJsResult(await _BINDINGS.coreInvoke("explicit-transaction-timeout", []));
101
+ } catch (error) {
102
+ if (/unbound fn: #'datalevin\.core\/explicit-transaction-timeout/.test(String(error?.message))) {
103
+ return null;
104
+ }
105
+ throw error;
106
+ }
107
+ }
108
+
109
+ function transactionTimeoutError(timeoutMs) {
110
+ return new DatalevinError(`Explicit transaction timed out after ${timeoutMs} ms`, {
111
+ typeName: "transaction/timeout",
112
+ data: { timeoutMs }
113
+ });
114
+ }
115
+
116
+ function requireRange(value, rangeName, methodName) {
117
+ if (!hasValue(value)) {
118
+ throw new TypeError(`${rangeName} is required for KV ${methodName}().`);
119
+ }
120
+ }
121
+
122
+ let interfaceProxyEventLoopDepth = 0;
123
+ let interfaceProxyEventLoopPrevious = false;
124
+
125
+ async function withInterfaceProxyEventLoop(fn) {
126
+ const bridge = await javaBridgeModule();
127
+ if (interfaceProxyEventLoopDepth === 0) {
128
+ interfaceProxyEventLoopPrevious = bridge.config.runEventLoopWhenInterfaceProxyIsActive;
129
+ bridge.config.runEventLoopWhenInterfaceProxyIsActive = true;
130
+ }
131
+ interfaceProxyEventLoopDepth += 1;
132
+ try {
133
+ return await fn();
134
+ } finally {
135
+ interfaceProxyEventLoopDepth -= 1;
136
+ if (interfaceProxyEventLoopDepth === 0) {
137
+ bridge.config.runEventLoopWhenInterfaceProxyIsActive = interfaceProxyEventLoopPrevious;
138
+ }
139
+ }
140
+ }
141
+
142
+ async function withJavaProxy(interfaceName, implementation, fn) {
143
+ const { newProxy } = await javaBridgeModule();
144
+ const proxy = newProxy(interfaceName, implementation);
145
+ try {
146
+ return await withInterfaceProxyEventLoop(() => fn(proxy));
147
+ } finally {
148
+ proxy.reset?.();
149
+ }
150
+ }
151
+
152
+ async function typedRangeArg(keyRange, kType) {
153
+ if (hasValue(kType)) {
154
+ return _BINDINGS.kvRange(keyRange, kType);
155
+ }
156
+ return toEdnForm(keyRange);
157
+ }
158
+
159
+ async function appendTypedArgs(args, { kType = null, vType = null, ignoreKey = null } = {}, methodName) {
160
+ rejectVTypeWithoutKType(kType, vType, methodName);
161
+ if (hasValue(ignoreKey) && (!hasValue(kType) || !hasValue(vType))) {
162
+ throw new TypeError(`ignoreKey requires kType and vType for KV ${methodName}().`);
163
+ }
164
+ if (hasValue(kType)) {
165
+ args.push(await _BINDINGS.kvType(kType));
166
+ }
167
+ if (hasValue(vType)) {
168
+ args.push(await _BINDINGS.kvType(vType));
169
+ }
170
+ if (hasValue(ignoreKey)) {
171
+ args.push(Boolean(ignoreKey));
172
+ }
173
+ }
174
+
175
+ async function byteArrayToBuffer(value) {
176
+ const converted = await toJs(value);
177
+ if (Buffer.isBuffer(converted)) {
178
+ return converted;
179
+ }
180
+ if (converted instanceof Uint8Array) {
181
+ return Buffer.from(converted.buffer, converted.byteOffset, converted.byteLength);
182
+ }
183
+ if (Array.isArray(converted)) {
184
+ return Buffer.from(converted.map((item) => Number(item) & 0xff));
185
+ }
186
+ return Buffer.from([]);
187
+ }
188
+
189
+ export class RawBuffer {
16
190
  constructor(handle) {
191
+ this._handle = handle;
192
+ }
193
+
194
+ rawHandle() {
195
+ return this._handle;
196
+ }
197
+
198
+ async bytes() {
199
+ return byteArrayToBuffer(await callJavaMethod(this.rawHandle(), "bytes"));
200
+ }
201
+
202
+ async read(valueType = ":data") {
203
+ if (!hasValue(valueType)) {
204
+ return toJsResult(await callJavaMethod(this.rawHandle(), "read"));
205
+ }
206
+ return toJsResult(await callJavaMethod(this.rawHandle(), "read", await toJava(valueType)));
207
+ }
208
+ }
209
+
210
+ export class RawKV {
211
+ constructor(handle) {
212
+ this._handle = handle;
213
+ }
214
+
215
+ rawHandle() {
216
+ return this._handle;
217
+ }
218
+
219
+ async key() {
220
+ return new RawBuffer(await callJavaMethod(this.rawHandle(), "key"));
221
+ }
222
+
223
+ async value() {
224
+ return new RawBuffer(await callJavaMethod(this.rawHandle(), "value"));
225
+ }
226
+
227
+ async keyBytes() {
228
+ return byteArrayToBuffer(await callJavaMethod(this.rawHandle(), "keyBytes"));
229
+ }
230
+
231
+ async valueBytes() {
232
+ return byteArrayToBuffer(await callJavaMethod(this.rawHandle(), "valueBytes"));
233
+ }
234
+
235
+ async readKey(valueType = ":data") {
236
+ if (!hasValue(valueType)) {
237
+ return toJsResult(await callJavaMethod(this.rawHandle(), "readKey"));
238
+ }
239
+ return toJsResult(await callJavaMethod(this.rawHandle(), "readKey", await toJava(valueType)));
240
+ }
241
+
242
+ async readValue(valueType = ":data") {
243
+ if (!hasValue(valueType)) {
244
+ return toJsResult(await callJavaMethod(this.rawHandle(), "readValue"));
245
+ }
246
+ return toJsResult(await callJavaMethod(this.rawHandle(), "readValue", await toJava(valueType)));
247
+ }
248
+ }
249
+
250
+ export class KV extends ResourceWrapper {
251
+ constructor(handle, { owned = true } = {}) {
17
252
  super(
18
253
  handle,
19
- (rawHandle) => _BINDINGS.closeKeyValue(rawHandle),
254
+ owned ? (rawHandle) => _BINDINGS.closeKeyValue(rawHandle) : async () => {},
20
255
  (rawHandle) => _BINDINGS.keyValueClosed(rawHandle),
21
256
  "kv"
22
257
  );
@@ -42,6 +277,68 @@ export class KV extends ResourceWrapper {
42
277
  await _BINDINGS.coreInvoke("open-list-dbi", args);
43
278
  }
44
279
 
280
+ async beginTransaction() {
281
+ return new KVTransaction(await _BINDINGS.keyValueBeginTransaction(this.rawHandle()));
282
+ }
283
+
284
+ async transaction() {
285
+ return this.beginTransaction();
286
+ }
287
+
288
+ async withTransaction(fnOrOptions, maybeFnOrOptions = null) {
289
+ const { fn, timeoutOption } = withTransactionArgs(fnOrOptions, maybeFnOrOptions);
290
+ const timeoutMs = await resolveExplicitTransactionTimeout(timeoutOption);
291
+ const tx = await this.beginTransaction();
292
+ let timeoutId = null;
293
+ try {
294
+ const body = Promise.resolve().then(() => fn(tx));
295
+ const result = hasValue(timeoutMs)
296
+ ? await Promise.race([
297
+ body,
298
+ new Promise((_, reject) => {
299
+ timeoutId = setTimeout(
300
+ () => reject(transactionTimeoutError(timeoutMs)),
301
+ timeoutMs
302
+ );
303
+ })
304
+ ])
305
+ : await body;
306
+ if (tx.active()) {
307
+ await tx.commit();
308
+ }
309
+ return result;
310
+ } catch (error) {
311
+ if (tx.active()) {
312
+ await tx.abort();
313
+ }
314
+ throw error;
315
+ } finally {
316
+ if (timeoutId !== null) {
317
+ clearTimeout(timeoutId);
318
+ }
319
+ }
320
+ }
321
+
322
+ async searchIndexWriter(opts = null) {
323
+ const { SearchIndexWriter } = await import("./search.js");
324
+ return new SearchIndexWriter(await _BINDINGS.searchIndexWriter(this.rawHandle(), opts));
325
+ }
326
+
327
+ async newSearchEngine(opts = null) {
328
+ const { SearchEngine } = await import("./search.js");
329
+ return new SearchEngine(await _BINDINGS.newSearchEngine(this.rawHandle(), opts));
330
+ }
331
+
332
+ async newVectorIndex(opts) {
333
+ const { VectorIndex } = await import("./vector.js");
334
+ return new VectorIndex(await _BINDINGS.newVectorIndex(this.rawHandle(), opts));
335
+ }
336
+
337
+ async reIndex(opts = null) {
338
+ this._handle = await _BINDINGS.keyValueReIndex(this.rawHandle(), opts);
339
+ return this;
340
+ }
341
+
45
342
  async listDbis() {
46
343
  return toJsResult(await _BINDINGS.coreInvoke("list-dbis", [this.rawHandle()]));
47
344
  }
@@ -50,6 +347,72 @@ export class KV extends ResourceWrapper {
50
347
  return toJsResult(await _BINDINGS.coreInvoke("entries", [this.rawHandle(), dbiName]));
51
348
  }
52
349
 
350
+ async stat(dbiName = null) {
351
+ const args = [this.rawHandle()];
352
+ if (hasValue(dbiName)) {
353
+ args.push(dbiName);
354
+ }
355
+ return toJsResult(await _BINDINGS.coreInvoke("stat", args));
356
+ }
357
+
358
+ async copy(dest, { compact = null } = {}) {
359
+ const args = [this.rawHandle(), dest];
360
+ if (hasValue(compact)) {
361
+ args.push(Boolean(compact));
362
+ }
363
+ return toJsResult(await _BINDINGS.coreInvoke("copy", args));
364
+ }
365
+
366
+ async sync(force = null) {
367
+ const args = [this.rawHandle()];
368
+ if (hasValue(force)) {
369
+ args.push(force);
370
+ }
371
+ return toJsResult(await _BINDINGS.coreInvoke("sync", args));
372
+ }
373
+
374
+ async setEnvFlags(flags, onOff) {
375
+ return toJsResult(
376
+ await _BINDINGS.coreInvoke("set-env-flags", [this.rawHandle(), await envFlags(flags), onOff ? true : null])
377
+ );
378
+ }
379
+
380
+ async getEnvFlags() {
381
+ return toJsResult(await _BINDINGS.coreInvoke("get-env-flags", [this.rawHandle()]));
382
+ }
383
+
384
+ async txLogWatermarks() {
385
+ return toJsResult(await _BINDINGS.coreInvoke("txlog-watermarks", [this.rawHandle()]));
386
+ }
387
+
388
+ async openTxLog(fromLsn, { uptoLsn = null, limit = null } = {}) {
389
+ const args = [this.rawHandle(), fromLsn];
390
+ if (hasValue(uptoLsn)) {
391
+ args.push(uptoLsn);
392
+ }
393
+ const rows = await toJsResult(await _BINDINGS.coreInvoke("open-tx-log", args));
394
+ if (!hasValue(limit)) {
395
+ return rows;
396
+ }
397
+ return rows.slice(0, Math.max(limit, 0));
398
+ }
399
+
400
+ async createSnapshot() {
401
+ return toJsResult(await _BINDINGS.coreInvoke("create-snapshot!", [this.rawHandle()]));
402
+ }
403
+
404
+ async listSnapshots() {
405
+ return toJsResult(await _BINDINGS.coreInvoke("list-snapshots", [this.rawHandle()]));
406
+ }
407
+
408
+ async gcTxLogSegments({ retainFloorLsn = null } = {}) {
409
+ const args = [this.rawHandle()];
410
+ if (hasValue(retainFloorLsn)) {
411
+ args.push(retainFloorLsn);
412
+ }
413
+ return toJsResult(await _BINDINGS.coreInvoke("gc-txlog-segments!", args));
414
+ }
415
+
53
416
  async transact(txs, { dbiName = null, kType = null, vType = null } = {}) {
54
417
  if (dbiName === null && (kType !== null || vType !== null)) {
55
418
  throw new TypeError("kType and vType require dbiName for KV transact().");
@@ -98,6 +461,76 @@ export class KV extends ResourceWrapper {
98
461
  );
99
462
  }
100
463
 
464
+ async getRank(dbiName, key, { kType = null } = {}) {
465
+ const args = [this.rawHandle(), dbiName, await toJava(key)];
466
+ if (hasValue(kType)) {
467
+ args.push(await _BINDINGS.kvType(kType));
468
+ }
469
+ return toJsResult(await _BINDINGS.coreInvoke("get-rank", args));
470
+ }
471
+
472
+ async getByRank(dbiName, rank, { kType = null, vType = null, ignoreKey = null } = {}) {
473
+ const args = [this.rawHandle(), dbiName, rank];
474
+ rejectVTypeWithoutKType(kType, vType, "getByRank");
475
+ if (hasValue(kType) && hasValue(vType)) {
476
+ return toJsResult(
477
+ await _BINDINGS.kvGetByRank(
478
+ this.rawHandle(),
479
+ dbiName,
480
+ rank,
481
+ kType,
482
+ vType,
483
+ hasValue(ignoreKey) ? Boolean(ignoreKey) : true
484
+ )
485
+ );
486
+ }
487
+ await appendTypedArgs(args, { kType, vType, ignoreKey }, "getByRank");
488
+ return toJsResult(await _BINDINGS.coreInvoke("get-by-rank", args));
489
+ }
490
+
491
+ async getEntryByRank(dbiName, rank, { kType = null, vType = null } = {}) {
492
+ requireKType(kType, "getEntryByRank");
493
+ requireVType(vType, "getEntryByRank");
494
+ return toJsResult(await _BINDINGS.kvGetEntryByRank(this.rawHandle(), dbiName, rank, kType, vType));
495
+ }
496
+
497
+ async sampleKv(dbiName, n, { kType = null, vType = null, ignoreKey = null } = {}) {
498
+ const args = [this.rawHandle(), dbiName, n];
499
+ rejectVTypeWithoutKType(kType, vType, "sampleKv");
500
+ if (hasValue(kType) && hasValue(vType)) {
501
+ return toJsResult(
502
+ await _BINDINGS.kvSample(
503
+ this.rawHandle(),
504
+ dbiName,
505
+ n,
506
+ kType,
507
+ vType,
508
+ hasValue(ignoreKey) ? Boolean(ignoreKey) : true
509
+ )
510
+ );
511
+ }
512
+ await appendTypedArgs(args, { kType, vType, ignoreKey }, "sampleKv");
513
+ return toJsResult(await _BINDINGS.coreInvoke("sample-kv", args));
514
+ }
515
+
516
+ async getFirst(dbiName, keyRange, { kType = null, vType = null, ignoreKey = null } = {}) {
517
+ if (keyRange === null || keyRange === undefined) {
518
+ throw new TypeError("keyRange is required for KV getFirst().");
519
+ }
520
+ const args = [this.rawHandle(), dbiName, await typedRangeArg(keyRange, kType)];
521
+ await appendTypedArgs(args, { kType, vType, ignoreKey }, "getFirst");
522
+ return toJsResult(await _BINDINGS.coreInvoke("get-first", args));
523
+ }
524
+
525
+ async getFirstN(dbiName, n, keyRange, { kType = null, vType = null, ignoreKey = null } = {}) {
526
+ if (keyRange === null || keyRange === undefined) {
527
+ throw new TypeError("keyRange is required for KV getFirstN().");
528
+ }
529
+ const args = [this.rawHandle(), dbiName, n, await typedRangeArg(keyRange, kType)];
530
+ await appendTypedArgs(args, { kType, vType, ignoreKey }, "getFirstN");
531
+ return toJsResult(await _BINDINGS.coreInvoke("get-first-n", args));
532
+ }
533
+
101
534
  async getRange(
102
535
  dbiName,
103
536
  keyRange,
@@ -123,6 +556,631 @@ export class KV extends ResourceWrapper {
123
556
  return slicePage(await toJsResult(await _BINDINGS.coreInvoke("get-range", args)), limit, offset);
124
557
  }
125
558
 
559
+ async keyRange(dbiName, keyRange, { kType = null, limit = null, offset = null } = {}) {
560
+ if (keyRange === null || keyRange === undefined) {
561
+ throw new TypeError("keyRange is required for KV keyRange().");
562
+ }
563
+
564
+ const args = [this.rawHandle(), dbiName, await toEdnForm(keyRange)];
565
+ if (hasValue(kType)) {
566
+ args.push(await _BINDINGS.kvType(kType));
567
+ }
568
+ return slicePage(await toJsResult(await _BINDINGS.coreInvoke("key-range", args)), limit, offset);
569
+ }
570
+
571
+ async keyRangeCount(dbiName, keyRange, { kType = null } = {}) {
572
+ if (keyRange === null || keyRange === undefined) {
573
+ throw new TypeError("keyRange is required for KV keyRangeCount().");
574
+ }
575
+
576
+ const args = [this.rawHandle(), dbiName, await toEdnForm(keyRange)];
577
+ if (hasValue(kType)) {
578
+ args.push(await _BINDINGS.kvType(kType));
579
+ }
580
+ return toJsResult(await _BINDINGS.coreInvoke("key-range-count", args));
581
+ }
582
+
583
+ async visit(dbiName, visitor, keyRange, { kType = null, vType = null } = {}) {
584
+ requireRange(keyRange, "keyRange", "visit");
585
+ requireCallback(visitor, "visit");
586
+ requireKType(kType, "visit");
587
+ requireVType(vType, "visit");
588
+ const normalizedRange = await toEdnForm(keyRange);
589
+ await withJavaProxy(
590
+ "java.util.function.BiConsumer",
591
+ {
592
+ accept: async (key, value) => {
593
+ await visitor(await toJs(key), await toJs(value));
594
+ }
595
+ },
596
+ async (proxy) => _BINDINGS.kvVisit(
597
+ this.rawHandle(),
598
+ dbiName,
599
+ proxy,
600
+ normalizedRange,
601
+ kType,
602
+ vType
603
+ )
604
+ );
605
+ }
606
+
607
+ async visitRaw(dbiName, visitor, keyRange, { kType = null, vType = null } = {}) {
608
+ requireRange(keyRange, "keyRange", "visitRaw");
609
+ requireCallback(visitor, "visitRaw");
610
+ requireKType(kType, "visitRaw");
611
+ requireVType(vType, "visitRaw");
612
+ const normalizedRange = await toEdnForm(keyRange);
613
+ await withJavaProxy(
614
+ "java.util.function.Consumer",
615
+ {
616
+ accept: async (value) => {
617
+ await visitor(new RawKV(value));
618
+ }
619
+ },
620
+ async (proxy) => _BINDINGS.kvVisitRaw(
621
+ this.rawHandle(),
622
+ dbiName,
623
+ proxy,
624
+ normalizedRange,
625
+ kType,
626
+ vType
627
+ )
628
+ );
629
+ }
630
+
631
+ async visitKeyRange(dbiName, visitor, keyRange, { kType = null } = {}) {
632
+ requireRange(keyRange, "keyRange", "visitKeyRange");
633
+ requireCallback(visitor, "visitKeyRange");
634
+ requireKType(kType, "visitKeyRange");
635
+ const normalizedRange = await toEdnForm(keyRange);
636
+ await withJavaProxy(
637
+ "java.util.function.Consumer",
638
+ {
639
+ accept: async (key) => {
640
+ await visitor(await toJs(key));
641
+ }
642
+ },
643
+ async (proxy) => _BINDINGS.kvVisitKeyRange(
644
+ this.rawHandle(),
645
+ dbiName,
646
+ proxy,
647
+ normalizedRange,
648
+ kType
649
+ )
650
+ );
651
+ }
652
+
653
+ async visitKeyRangeRaw(dbiName, visitor, keyRange, { kType = null } = {}) {
654
+ requireRange(keyRange, "keyRange", "visitKeyRangeRaw");
655
+ requireCallback(visitor, "visitKeyRangeRaw");
656
+ requireKType(kType, "visitKeyRangeRaw");
657
+ const normalizedRange = await toEdnForm(keyRange);
658
+ await withJavaProxy(
659
+ "java.util.function.Consumer",
660
+ {
661
+ accept: async (value) => {
662
+ await visitor(new RawBuffer(value));
663
+ }
664
+ },
665
+ async (proxy) => _BINDINGS.kvVisitKeyRangeRaw(
666
+ this.rawHandle(),
667
+ dbiName,
668
+ proxy,
669
+ normalizedRange,
670
+ kType
671
+ )
672
+ );
673
+ }
674
+
675
+ async rangeCount(dbiName, keyRange, { kType = null } = {}) {
676
+ if (keyRange === null || keyRange === undefined) {
677
+ throw new TypeError("keyRange is required for KV rangeCount().");
678
+ }
679
+
680
+ const args = [this.rawHandle(), dbiName, await toEdnForm(keyRange)];
681
+ if (hasValue(kType)) {
682
+ args.push(await _BINDINGS.kvType(kType));
683
+ }
684
+ return toJsResult(await _BINDINGS.coreInvoke("range-count", args));
685
+ }
686
+
687
+ async putListItems(listName, key, values, { kType = null, vType = null } = {}) {
688
+ requireKType(kType, "putListItems");
689
+ requireVType(vType, "putListItems");
690
+ await _BINDINGS.coreInvoke("put-list-items", [
691
+ this.rawHandle(),
692
+ listName,
693
+ await toJava(key),
694
+ await toJava(values),
695
+ await _BINDINGS.kvType(kType),
696
+ await _BINDINGS.kvType(vType)
697
+ ]);
698
+ }
699
+
700
+ async delListItems(listName, key, { kType = null, values = null, vType = null } = {}) {
701
+ requireKType(kType, "delListItems");
702
+ const args = [this.rawHandle(), listName, await toJava(key)];
703
+ if (hasValue(values)) {
704
+ requireVType(vType, "delListItems");
705
+ args.push(await toJava(values), await _BINDINGS.kvType(kType), await _BINDINGS.kvType(vType));
706
+ } else {
707
+ if (hasValue(vType)) {
708
+ throw new TypeError("vType requires values for KV delListItems().");
709
+ }
710
+ args.push(await _BINDINGS.kvType(kType));
711
+ }
712
+ await _BINDINGS.coreInvoke("del-list-items", args);
713
+ }
714
+
715
+ async getList(listName, key, { kType = null, vType = null, limit = null, offset = null } = {}) {
716
+ requireKType(kType, "getList");
717
+ requireVType(vType, "getList");
718
+ const items = await toJsResult(
719
+ await _BINDINGS.coreInvoke("get-list", [
720
+ this.rawHandle(),
721
+ listName,
722
+ await toJava(key),
723
+ await _BINDINGS.kvType(kType),
724
+ await _BINDINGS.kvType(vType)
725
+ ])
726
+ );
727
+ return slicePage(items, limit, offset);
728
+ }
729
+
730
+ async listCount(listName, key, { kType = null } = {}) {
731
+ requireKType(kType, "listCount");
732
+ return toJsResult(
733
+ await _BINDINGS.coreInvoke("list-count", [
734
+ this.rawHandle(),
735
+ listName,
736
+ await toJava(key),
737
+ await _BINDINGS.kvType(kType)
738
+ ])
739
+ );
740
+ }
741
+
742
+ async inList(listName, key, value, { kType = null, vType = null } = {}) {
743
+ requireKType(kType, "inList");
744
+ requireVType(vType, "inList");
745
+ return Boolean(
746
+ await toJsResult(
747
+ await _BINDINGS.coreInvoke("in-list?", [
748
+ this.rawHandle(),
749
+ listName,
750
+ await toJava(key),
751
+ await toJava(value),
752
+ await _BINDINGS.kvType(kType),
753
+ await _BINDINGS.kvType(vType)
754
+ ])
755
+ )
756
+ );
757
+ }
758
+
759
+ async visitList(listName, visitor, key, { kType = null, vType = null } = {}) {
760
+ requireCallback(visitor, "visitList");
761
+ requireKType(kType, "visitList");
762
+ requireVType(vType, "visitList");
763
+ await withJavaProxy(
764
+ "java.util.function.Consumer",
765
+ {
766
+ accept: async (value) => {
767
+ await visitor(await toJs(value));
768
+ }
769
+ },
770
+ async (proxy) => _BINDINGS.kvVisitList(
771
+ this.rawHandle(),
772
+ listName,
773
+ proxy,
774
+ await toJava(key),
775
+ kType,
776
+ vType
777
+ )
778
+ );
779
+ }
780
+
781
+ async visitListRaw(listName, visitor, key, { kType = null } = {}) {
782
+ requireCallback(visitor, "visitListRaw");
783
+ requireKType(kType, "visitListRaw");
784
+ await withJavaProxy(
785
+ "java.util.function.Consumer",
786
+ {
787
+ accept: async (value) => {
788
+ await visitor(new RawBuffer(value));
789
+ }
790
+ },
791
+ async (proxy) => _BINDINGS.kvVisitListRaw(
792
+ this.rawHandle(),
793
+ listName,
794
+ proxy,
795
+ await toJava(key),
796
+ kType
797
+ )
798
+ );
799
+ }
800
+
801
+ async visitListRange(listName, visitor, kRange, { kType = null, vRange = null, vType = null } = {}) {
802
+ requireRange(kRange, "kRange", "visitListRange");
803
+ requireRange(vRange, "vRange", "visitListRange");
804
+ requireCallback(visitor, "visitListRange");
805
+ requireKType(kType, "visitListRange");
806
+ requireVType(vType, "visitListRange");
807
+ const normalizedKRange = await toEdnForm(kRange);
808
+ const normalizedVRange = await toEdnForm(vRange);
809
+ await withJavaProxy(
810
+ "java.util.function.BiConsumer",
811
+ {
812
+ accept: async (key, value) => {
813
+ await visitor(await toJs(key), await toJs(value));
814
+ }
815
+ },
816
+ async (proxy) => _BINDINGS.kvVisitListRange(
817
+ this.rawHandle(),
818
+ listName,
819
+ proxy,
820
+ normalizedKRange,
821
+ kType,
822
+ normalizedVRange,
823
+ vType
824
+ )
825
+ );
826
+ }
827
+
828
+ async visitListRangeRaw(listName, visitor, kRange, { kType = null, vRange = null, vType = null } = {}) {
829
+ requireRange(kRange, "kRange", "visitListRangeRaw");
830
+ requireRange(vRange, "vRange", "visitListRangeRaw");
831
+ requireCallback(visitor, "visitListRangeRaw");
832
+ requireKType(kType, "visitListRangeRaw");
833
+ requireVType(vType, "visitListRangeRaw");
834
+ const normalizedKRange = await toEdnForm(kRange);
835
+ const normalizedVRange = await toEdnForm(vRange);
836
+ await withJavaProxy(
837
+ "java.util.function.Consumer",
838
+ {
839
+ accept: async (value) => {
840
+ await visitor(new RawKV(value));
841
+ }
842
+ },
843
+ async (proxy) => _BINDINGS.kvVisitListRangeRaw(
844
+ this.rawHandle(),
845
+ listName,
846
+ proxy,
847
+ normalizedKRange,
848
+ kType,
849
+ normalizedVRange,
850
+ vType
851
+ )
852
+ );
853
+ }
854
+
855
+ async listRangeFilter(
856
+ listName,
857
+ predicate,
858
+ kRange,
859
+ { kType = null, vRange = null, vType = null, limit = null, offset = null } = {}
860
+ ) {
861
+ requireRange(kRange, "kRange", "listRangeFilter");
862
+ requireRange(vRange, "vRange", "listRangeFilter");
863
+ requireCallback(predicate, "listRangeFilter");
864
+ requireKType(kType, "listRangeFilter");
865
+ requireVType(vType, "listRangeFilter");
866
+ const normalizedKRange = await toEdnForm(kRange);
867
+ const normalizedVRange = await toEdnForm(vRange);
868
+ const items = await toJsResult(await withJavaProxy(
869
+ "java.util.function.BiPredicate",
870
+ {
871
+ test: async (key, value) => Boolean(await predicate(await toJs(key), await toJs(value)))
872
+ },
873
+ async (proxy) => _BINDINGS.kvListRangeFilter(
874
+ this.rawHandle(),
875
+ listName,
876
+ proxy,
877
+ normalizedKRange,
878
+ kType,
879
+ normalizedVRange,
880
+ vType
881
+ )
882
+ ));
883
+ return slicePage(items, limit, offset);
884
+ }
885
+
886
+ async listRangeFilterRaw(
887
+ listName,
888
+ predicate,
889
+ kRange,
890
+ { kType = null, vRange = null, vType = null, limit = null, offset = null } = {}
891
+ ) {
892
+ requireRange(kRange, "kRange", "listRangeFilterRaw");
893
+ requireRange(vRange, "vRange", "listRangeFilterRaw");
894
+ requireCallback(predicate, "listRangeFilterRaw");
895
+ requireKType(kType, "listRangeFilterRaw");
896
+ requireVType(vType, "listRangeFilterRaw");
897
+ const normalizedKRange = await toEdnForm(kRange);
898
+ const normalizedVRange = await toEdnForm(vRange);
899
+ const items = await toJsResult(await withJavaProxy(
900
+ "java.util.function.Predicate",
901
+ {
902
+ test: async (value) => Boolean(await predicate(new RawKV(value)))
903
+ },
904
+ async (proxy) => _BINDINGS.kvListRangeFilterRaw(
905
+ this.rawHandle(),
906
+ listName,
907
+ proxy,
908
+ normalizedKRange,
909
+ kType,
910
+ normalizedVRange,
911
+ vType
912
+ )
913
+ ));
914
+ return slicePage(items, limit, offset);
915
+ }
916
+
917
+ async listRangeFilterCount(
918
+ listName,
919
+ predicate,
920
+ kRange,
921
+ { kType = null, vRange = null, vType = null } = {}
922
+ ) {
923
+ requireRange(kRange, "kRange", "listRangeFilterCount");
924
+ requireRange(vRange, "vRange", "listRangeFilterCount");
925
+ requireCallback(predicate, "listRangeFilterCount");
926
+ requireKType(kType, "listRangeFilterCount");
927
+ requireVType(vType, "listRangeFilterCount");
928
+ const normalizedKRange = await toEdnForm(kRange);
929
+ const normalizedVRange = await toEdnForm(vRange);
930
+ return toJsResult(await withJavaProxy(
931
+ "java.util.function.BiPredicate",
932
+ {
933
+ test: async (key, value) => Boolean(await predicate(await toJs(key), await toJs(value)))
934
+ },
935
+ async (proxy) => _BINDINGS.kvListRangeFilterCount(
936
+ this.rawHandle(),
937
+ listName,
938
+ proxy,
939
+ normalizedKRange,
940
+ kType,
941
+ normalizedVRange,
942
+ vType
943
+ )
944
+ ));
945
+ }
946
+
947
+ async listRangeFilterCountRaw(
948
+ listName,
949
+ predicate,
950
+ kRange,
951
+ { kType = null, vRange = null, vType = null } = {}
952
+ ) {
953
+ requireRange(kRange, "kRange", "listRangeFilterCountRaw");
954
+ requireRange(vRange, "vRange", "listRangeFilterCountRaw");
955
+ requireCallback(predicate, "listRangeFilterCountRaw");
956
+ requireKType(kType, "listRangeFilterCountRaw");
957
+ requireVType(vType, "listRangeFilterCountRaw");
958
+ const normalizedKRange = await toEdnForm(kRange);
959
+ const normalizedVRange = await toEdnForm(vRange);
960
+ return toJsResult(await withJavaProxy(
961
+ "java.util.function.Predicate",
962
+ {
963
+ test: async (value) => Boolean(await predicate(new RawKV(value)))
964
+ },
965
+ async (proxy) => _BINDINGS.kvListRangeFilterCountRaw(
966
+ this.rawHandle(),
967
+ listName,
968
+ proxy,
969
+ normalizedKRange,
970
+ kType,
971
+ normalizedVRange,
972
+ vType
973
+ )
974
+ ));
975
+ }
976
+
977
+ async listRangeKeep(
978
+ listName,
979
+ fn,
980
+ kRange,
981
+ { kType = null, vRange = null, vType = null, limit = null, offset = null } = {}
982
+ ) {
983
+ requireRange(kRange, "kRange", "listRangeKeep");
984
+ requireRange(vRange, "vRange", "listRangeKeep");
985
+ requireCallback(fn, "listRangeKeep");
986
+ requireKType(kType, "listRangeKeep");
987
+ requireVType(vType, "listRangeKeep");
988
+ const normalizedKRange = await toEdnForm(kRange);
989
+ const normalizedVRange = await toEdnForm(vRange);
990
+ const items = await toJsResult(await withJavaProxy(
991
+ "java.util.function.BiFunction",
992
+ {
993
+ apply: async (key, value) => {
994
+ const result = await fn(await toJs(key), await toJs(value));
995
+ return toJava(result === undefined ? null : result);
996
+ }
997
+ },
998
+ async (proxy) => _BINDINGS.kvListRangeKeep(
999
+ this.rawHandle(),
1000
+ listName,
1001
+ proxy,
1002
+ normalizedKRange,
1003
+ kType,
1004
+ normalizedVRange,
1005
+ vType
1006
+ )
1007
+ ));
1008
+ return slicePage(items, limit, offset);
1009
+ }
1010
+
1011
+ async listRangeKeepRaw(
1012
+ listName,
1013
+ fn,
1014
+ kRange,
1015
+ { kType = null, vRange = null, vType = null, limit = null, offset = null } = {}
1016
+ ) {
1017
+ requireRange(kRange, "kRange", "listRangeKeepRaw");
1018
+ requireRange(vRange, "vRange", "listRangeKeepRaw");
1019
+ requireCallback(fn, "listRangeKeepRaw");
1020
+ requireKType(kType, "listRangeKeepRaw");
1021
+ requireVType(vType, "listRangeKeepRaw");
1022
+ const normalizedKRange = await toEdnForm(kRange);
1023
+ const normalizedVRange = await toEdnForm(vRange);
1024
+ const items = await toJsResult(await withJavaProxy(
1025
+ "java.util.function.Function",
1026
+ {
1027
+ apply: async (value) => {
1028
+ const result = await fn(new RawKV(value));
1029
+ return toJava(result === undefined ? null : result);
1030
+ }
1031
+ },
1032
+ async (proxy) => _BINDINGS.kvListRangeKeepRaw(
1033
+ this.rawHandle(),
1034
+ listName,
1035
+ proxy,
1036
+ normalizedKRange,
1037
+ kType,
1038
+ normalizedVRange,
1039
+ vType
1040
+ )
1041
+ ));
1042
+ return slicePage(items, limit, offset);
1043
+ }
1044
+
1045
+ async listRangeSome(listName, fn, kRange, { kType = null, vRange = null, vType = null } = {}) {
1046
+ requireRange(kRange, "kRange", "listRangeSome");
1047
+ requireRange(vRange, "vRange", "listRangeSome");
1048
+ requireCallback(fn, "listRangeSome");
1049
+ requireKType(kType, "listRangeSome");
1050
+ requireVType(vType, "listRangeSome");
1051
+ const normalizedKRange = await toEdnForm(kRange);
1052
+ const normalizedVRange = await toEdnForm(vRange);
1053
+ return toJsResult(await withJavaProxy(
1054
+ "java.util.function.BiFunction",
1055
+ {
1056
+ apply: async (key, value) => {
1057
+ const result = await fn(await toJs(key), await toJs(value));
1058
+ return toJava(result === undefined ? null : result);
1059
+ }
1060
+ },
1061
+ async (proxy) => _BINDINGS.kvListRangeSome(
1062
+ this.rawHandle(),
1063
+ listName,
1064
+ proxy,
1065
+ normalizedKRange,
1066
+ kType,
1067
+ normalizedVRange,
1068
+ vType
1069
+ )
1070
+ ));
1071
+ }
1072
+
1073
+ async listRangeSomeRaw(listName, fn, kRange, { kType = null, vRange = null, vType = null } = {}) {
1074
+ requireRange(kRange, "kRange", "listRangeSomeRaw");
1075
+ requireRange(vRange, "vRange", "listRangeSomeRaw");
1076
+ requireCallback(fn, "listRangeSomeRaw");
1077
+ requireKType(kType, "listRangeSomeRaw");
1078
+ requireVType(vType, "listRangeSomeRaw");
1079
+ const normalizedKRange = await toEdnForm(kRange);
1080
+ const normalizedVRange = await toEdnForm(vRange);
1081
+ return toJsResult(await withJavaProxy(
1082
+ "java.util.function.Function",
1083
+ {
1084
+ apply: async (value) => {
1085
+ const result = await fn(new RawKV(value));
1086
+ return toJava(result === undefined ? null : result);
1087
+ }
1088
+ },
1089
+ async (proxy) => _BINDINGS.kvListRangeSomeRaw(
1090
+ this.rawHandle(),
1091
+ listName,
1092
+ proxy,
1093
+ normalizedKRange,
1094
+ kType,
1095
+ normalizedVRange,
1096
+ vType
1097
+ )
1098
+ ));
1099
+ }
1100
+
1101
+ async listRange(
1102
+ listName,
1103
+ kRange,
1104
+ { kType = null, vRange = null, vType = null, limit = null, offset = null } = {}
1105
+ ) {
1106
+ requireRange(kRange, "kRange", "listRange");
1107
+ requireRange(vRange, "vRange", "listRange");
1108
+ requireKType(kType, "listRange");
1109
+ requireVType(vType, "listRange");
1110
+ const items = await toJsResult(
1111
+ await _BINDINGS.coreInvoke("list-range", [
1112
+ this.rawHandle(),
1113
+ listName,
1114
+ await _BINDINGS.kvRange(kRange, kType),
1115
+ await _BINDINGS.kvType(kType),
1116
+ await _BINDINGS.kvRange(vRange, vType),
1117
+ await _BINDINGS.kvType(vType)
1118
+ ])
1119
+ );
1120
+ return slicePage(items, limit, offset);
1121
+ }
1122
+
1123
+ async listRangeCount(listName, kRange, { kType = null } = {}) {
1124
+ requireRange(kRange, "kRange", "listRangeCount");
1125
+ requireKType(kType, "listRangeCount");
1126
+ return toJsResult(
1127
+ await _BINDINGS.coreInvoke("list-range-count", [
1128
+ this.rawHandle(),
1129
+ listName,
1130
+ await _BINDINGS.kvRange(kRange, kType),
1131
+ await _BINDINGS.kvType(kType)
1132
+ ])
1133
+ );
1134
+ }
1135
+
1136
+ async listRangeFirst(listName, kRange, { kType = null, vRange = null, vType = null } = {}) {
1137
+ requireRange(kRange, "kRange", "listRangeFirst");
1138
+ requireRange(vRange, "vRange", "listRangeFirst");
1139
+ requireKType(kType, "listRangeFirst");
1140
+ requireVType(vType, "listRangeFirst");
1141
+ return toJsResult(
1142
+ await _BINDINGS.coreInvoke("list-range-first", [
1143
+ this.rawHandle(),
1144
+ listName,
1145
+ await _BINDINGS.kvRange(kRange, kType),
1146
+ await _BINDINGS.kvType(kType),
1147
+ await _BINDINGS.kvRange(vRange, vType),
1148
+ await _BINDINGS.kvType(vType)
1149
+ ])
1150
+ );
1151
+ }
1152
+
1153
+ async listRangeFirstN(listName, n, kRange, { kType = null, vRange = null, vType = null } = {}) {
1154
+ requireRange(kRange, "kRange", "listRangeFirstN");
1155
+ requireRange(vRange, "vRange", "listRangeFirstN");
1156
+ requireKType(kType, "listRangeFirstN");
1157
+ requireVType(vType, "listRangeFirstN");
1158
+ return toJsResult(
1159
+ await _BINDINGS.coreInvoke("list-range-first-n", [
1160
+ this.rawHandle(),
1161
+ listName,
1162
+ n,
1163
+ await _BINDINGS.kvRange(kRange, kType),
1164
+ await _BINDINGS.kvType(kType),
1165
+ await _BINDINGS.kvRange(vRange, vType),
1166
+ await _BINDINGS.kvType(vType)
1167
+ ])
1168
+ );
1169
+ }
1170
+
1171
+ async keyRangeListCount(listName, kRange, { kType = null } = {}) {
1172
+ requireRange(kRange, "kRange", "keyRangeListCount");
1173
+ requireKType(kType, "keyRangeListCount");
1174
+ return toJsResult(
1175
+ await _BINDINGS.coreInvoke("key-range-list-count", [
1176
+ this.rawHandle(),
1177
+ listName,
1178
+ await _BINDINGS.kvRange(kRange, kType),
1179
+ await _BINDINGS.kvType(kType)
1180
+ ])
1181
+ );
1182
+ }
1183
+
126
1184
  async clearDbi(dbiName) {
127
1185
  await _BINDINGS.coreInvoke("clear-dbi", [this.rawHandle(), dbiName]);
128
1186
  }
@@ -131,3 +1189,43 @@ export class KV extends ResourceWrapper {
131
1189
  await _BINDINGS.coreInvoke("drop-dbi", [this.rawHandle(), dbiName]);
132
1190
  }
133
1191
  }
1192
+
1193
+ export class KVTransaction extends KV {
1194
+ constructor(handle) {
1195
+ super(handle, { owned: false });
1196
+ }
1197
+
1198
+ active() {
1199
+ return !this._closed;
1200
+ }
1201
+
1202
+ async commit() {
1203
+ this.#requireActive();
1204
+ try {
1205
+ return toJsResult(await _BINDINGS.keyValueCommitTransaction(this.rawHandle()));
1206
+ } finally {
1207
+ this._closed = true;
1208
+ }
1209
+ }
1210
+
1211
+ async abort() {
1212
+ this.#requireActive();
1213
+ try {
1214
+ return toJsResult(await _BINDINGS.keyValueAbortTransaction(this.rawHandle()));
1215
+ } finally {
1216
+ this._closed = true;
1217
+ }
1218
+ }
1219
+
1220
+ async close() {
1221
+ if (!this._closed) {
1222
+ await this.abort();
1223
+ }
1224
+ }
1225
+
1226
+ #requireActive() {
1227
+ if (this._closed) {
1228
+ throw new Error("KV transaction is closed.");
1229
+ }
1230
+ }
1231
+ }