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/src/kv.js CHANGED
@@ -4,6 +4,7 @@ import { _BINDINGS } from "./interop.js";
4
4
  import { callJavaMethod, javaBridgeModule } from "./jvm.js";
5
5
  import { ResourceWrapper } from "./resource.js";
6
6
  import { toJsResult } from "./result.js";
7
+ import { bindNativeCallback, nativeMethods } from "./native.js";
7
8
 
8
9
  const NO_TIMEOUT_OPTION = Symbol("no-timeout-option");
9
10
 
@@ -141,7 +142,9 @@ async function withInterfaceProxyEventLoop(fn) {
141
142
 
142
143
  async function withJavaProxy(interfaceName, implementation, fn) {
143
144
  const { newProxy } = await javaBridgeModule();
144
- const proxy = newProxy(interfaceName, implementation);
145
+ const methods = Object.fromEntries(Object.entries(implementation)
146
+ .map(([name, fn]) => [name, bindNativeCallback(fn)]));
147
+ const proxy = newProxy(interfaceName, methods);
145
148
  try {
146
149
  return await withInterfaceProxyEventLoop(() => fn(proxy));
147
150
  } finally {
@@ -261,6 +264,13 @@ export class KV extends ResourceWrapper {
261
264
  return toJsResult(await _BINDINGS.coreInvoke("dir", [this.rawHandle()]));
262
265
  }
263
266
 
267
+ /** Register an ordered type shared by this database's KV and Datalog APIs.
268
+ * Supply UDF descriptors and install bindings locally or on the server.
269
+ */
270
+ async registerType(typeName, definition) {
271
+ return toJs(await _BINDINGS.registerType(this.rawHandle(), typeName, definition));
272
+ }
273
+
264
274
  async openDbi(name, opts = null) {
265
275
  const args = [this.rawHandle(), name];
266
276
  if (opts !== null && opts !== undefined) {
@@ -413,6 +423,19 @@ export class KV extends ResourceWrapper {
413
423
  return toJsResult(await _BINDINGS.coreInvoke("gc-txlog-segments!", args));
414
424
  }
415
425
 
426
+ async prepareGetValue(dbiName, opts = {}) {
427
+ const { prepareGetValue } = await import("./prepared.js");
428
+ return prepareGetValue(this, dbiName, opts);
429
+ }
430
+
431
+ /** Atomically update a value; host callbacks are embedded-only, source also runs remotely. */
432
+ async update(dbiName, key, fn, { kType = ":data", vType = ":data", args = [] } = {}) {
433
+ if (typeof fn !== "function" && typeof fn !== "string") {
434
+ throw new TypeError("fn must be a function or restricted Clojure function source.");
435
+ }
436
+ return toJsResult(await _BINDINGS.keyValueUpdate(this.rawHandle(), dbiName, key, fn, kType, vType, args));
437
+ }
438
+
416
439
  async transact(txs, { dbiName = null, kType = null, vType = null } = {}) {
417
440
  if (dbiName === null && (kType !== null || vType !== null)) {
418
441
  throw new TypeError("kType and vType require dbiName for KV transact().");
@@ -1229,3 +1252,6 @@ export class KVTransaction extends KV {
1229
1252
  }
1230
1253
  }
1231
1254
  }
1255
+
1256
+ nativeMethods(KV);
1257
+ nativeMethods(KVTransaction);
package/src/native.js ADDED
@@ -0,0 +1,172 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { randomUUID } from "node:crypto";
3
+ import { isDeepStrictEqual } from "node:util";
4
+ import { javaBridgeModule } from "./jvm.js";
5
+ import { UdfDescriptor, descriptorData } from "./udf-value.js";
6
+
7
+ const scope = new AsyncLocalStorage();
8
+ const codecs = new Map();
9
+ const cleanup = new FinalizationRegistry((id) => codecs.delete(id));
10
+ const builtins = new Set([Object, Array, Map, Set, Date, RegExp, Buffer, Uint8Array,
11
+ String, Number, Boolean, Function, Promise, WeakMap, WeakSet]);
12
+
13
+ export function descriptorKey(descriptor) {
14
+ const d = descriptorData(descriptor);
15
+ return [d[":udf/lang"], d[":udf/kind"], d[":udf/id"], d[":udf/version"] ?? ""].join("\u0000");
16
+ }
17
+
18
+ export function currentNativeRegistry() {
19
+ const registry = scope.getStore() ?? null;
20
+ return registry?.ownerRef?.deref() ?? registry;
21
+ }
22
+
23
+ export function withNativeScope(registry, fn) {
24
+ return scope.run(registry, fn);
25
+ }
26
+
27
+ export function bindNativeCallback(fn) {
28
+ const registry = currentNativeRegistry();
29
+ return (...args) => withNativeScope(registry, () => fn(...args));
30
+ }
31
+
32
+ export function nativeMethods(cls) {
33
+ for (const [name, property] of Object.entries(Object.getOwnPropertyDescriptors(cls.prototype))) {
34
+ if (name === "constructor" || name.startsWith("_") || typeof property.value !== "function") continue;
35
+ const fn = property.value;
36
+ Object.defineProperty(cls.prototype, name, {
37
+ ...property,
38
+ value: function (...args) {
39
+ const registry = this._nativeRegistry ?? null;
40
+ return registry === currentNativeRegistry()
41
+ ? fn.apply(this, args)
42
+ : withNativeScope(registry, () => fn.apply(this, args));
43
+ }
44
+ });
45
+ }
46
+ }
47
+
48
+ function field(map, key) {
49
+ return map instanceof Map ? (map.get(key) ?? map.get(`:${key}`)) : (map?.[key] ?? map?.[`:${key}`]);
50
+ }
51
+
52
+ export function registryFromOpts(opts, dir = null) {
53
+ const registry = field(field(opts, "runtime-opts"), "udf-registry");
54
+ if (!registry?._nativeBindings) return null;
55
+ return registry;
56
+ }
57
+
58
+ export function currentNativeBindings() {
59
+ const registry = currentNativeRegistry();
60
+ return registry?._nativeBindings ?? registry;
61
+ }
62
+
63
+ export function nativeCodecFor(value) {
64
+ if (value === null || typeof value !== "object") return null;
65
+ return currentNativeBindings()?.types.get(Object.getPrototypeOf(value)) ?? null;
66
+ }
67
+
68
+ function valueCodec(value) {
69
+ const codec = codecs.get(value.codecIdSync())?.deref();
70
+ if (!codec) throw new Error(`Missing native type binding for ${value.typeNameSync()}`);
71
+ return codec;
72
+ }
73
+
74
+ export async function nativeToJs(value) {
75
+ return valueCodec(value).decode(value.payloadSync());
76
+ }
77
+
78
+ // This callback captures no registry or proxy owner. The registry retains the
79
+ // proxy; codecs and UDF callbacks retain only host state and a weak proxy ref.
80
+ async function nativeEquals(left, right) {
81
+ const codec = valueCodec(left);
82
+ const equal = await codec.equals(await nativeToJs(left), await nativeToJs(right));
83
+ if (typeof equal !== "boolean") throw new TypeError("Native equality must return a boolean");
84
+ return equal;
85
+ }
86
+
87
+ export async function createNativeEqualityProxy() {
88
+ const { newProxy } = await javaBridgeModule();
89
+ return newProxy("java.util.function.BiPredicate", { test: nativeEquals });
90
+ }
91
+
92
+ let nativeClassPromise;
93
+ async function nativeClass() {
94
+ nativeClassPromise ??= javaBridgeModule().then((bridge) => bridge.importClass("datalevin.NativeValue"));
95
+ return nativeClassPromise;
96
+ }
97
+
98
+ export class NativeCodec {
99
+ constructor(bindings, typeName, nativeType, definition, { equals = isDeepStrictEqual } = {}) {
100
+ if (typeof nativeType !== "function" || !nativeType.prototype || builtins.has(nativeType)) {
101
+ throw new TypeError("nativeType must be a custom JavaScript class");
102
+ }
103
+ if (typeof equals !== "function") throw new TypeError("equals must be a function");
104
+ const name = String(typeName).replace(/^:/, "");
105
+ if (!/^[^/\s]+\/[^\s]+$/.test(name)) throw new TypeError("Native type name must be a namespaced keyword");
106
+ const payload = field(definition, "payload");
107
+ if (!payload || typeof payload !== "object") {
108
+ throw new TypeError("Native types require serialize and deserialize UDF descriptors");
109
+ }
110
+ this.serialize = UdfDescriptor.from(field(payload, "serialize"), { defaultLang: "javascript" });
111
+ this.deserialize = UdfDescriptor.from(field(payload, "deserialize"), { defaultLang: "javascript" });
112
+ if (this.serialize.kind !== ":serializer" || this.deserialize.kind !== ":deserializer") {
113
+ throw new TypeError("Native types require serializer and deserializer UDF kinds");
114
+ }
115
+ this.bindings = bindings;
116
+ this.nativeType = nativeType;
117
+ this.typeName = `:${name}`;
118
+ this.equals = equals;
119
+ this.id = randomUUID();
120
+ }
121
+
122
+ sameBinding(other) {
123
+ return this.typeName === other.typeName && this.nativeType === other.nativeType
124
+ && this.equals === other.equals
125
+ && descriptorKey(this.serialize) === descriptorKey(other.serialize)
126
+ && descriptorKey(this.deserialize) === descriptorKey(other.deserialize);
127
+ }
128
+
129
+ install() {
130
+ codecs.set(this.id, new WeakRef(this));
131
+ cleanup.register(this, this.id);
132
+ }
133
+
134
+ function(descriptor) {
135
+ const fn = this.bindings.functions.get(descriptorKey(descriptor));
136
+ if (!fn) throw new Error(`Missing native type UDF binding: ${descriptor.udfId}`);
137
+ return fn;
138
+ }
139
+
140
+ accepts(value) {
141
+ return value !== null && typeof value === "object" && Object.getPrototypeOf(value) === this.nativeType.prototype;
142
+ }
143
+
144
+ checkValue(value) {
145
+ if (!this.accepts(value)) {
146
+ throw new TypeError(`Deserializer for ${this.typeName} must return ${this.nativeType.name}`);
147
+ }
148
+ }
149
+
150
+ async decode(payload) {
151
+ const value = await this.function(this.deserialize)(Buffer.from(payload));
152
+ this.checkValue(value);
153
+ return value;
154
+ }
155
+
156
+ async wrap(value) {
157
+ const payload = await this.function(this.serialize)(value);
158
+ if (!Buffer.isBuffer(payload) && !(payload instanceof Uint8Array)) {
159
+ throw new TypeError("Custom serializer must return a byte array (Buffer or Uint8Array)");
160
+ }
161
+ return this.wrapPayload(Buffer.from(payload));
162
+ }
163
+
164
+ async wrapPayload(payload) {
165
+ const equality = this.bindings.equalityProxyRef?.deref();
166
+ if (!equality) throw new Error(`Missing native equality binding for ${this.typeName}`);
167
+ const NativeValue = await nativeClass();
168
+ const bytes = Buffer.from(payload);
169
+ return new NativeValue(this.id, this.typeName,
170
+ Array.from(new Int8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)), equality);
171
+ }
172
+ }
@@ -0,0 +1,88 @@
1
+ import { toEdnForm, toJava, toJs, toQueryInput } from "./convert.js";
2
+ import { Form } from "./form.js";
3
+ import { _BINDINGS } from "./interop.js";
4
+ import { callJavaMethod } from "./jvm.js";
5
+ import { currentNativeRegistry, nativeMethods, withNativeScope } from "./native.js";
6
+
7
+ async function viewHandle(view) {
8
+ const { Connection } = await import("./connection.js");
9
+ return view instanceof Connection
10
+ ? _BINDINGS.connectionDb(view.rawHandle())
11
+ : view.rawHandle();
12
+ }
13
+
14
+ async function form(value) {
15
+ return typeof value === "string" ? value : toEdnForm(value);
16
+ }
17
+
18
+ /** Reusable read metadata. No close is needed; the owning store must stay open. */
19
+ export class PreparedRead {
20
+ constructor(handle, { query = false, typed = false } = {}) {
21
+ this._handle = handle;
22
+ this._query = query;
23
+ this._typed = typed;
24
+ this._nativeRegistry = currentNativeRegistry();
25
+ }
26
+
27
+ rawHandle() {
28
+ return this._handle;
29
+ }
30
+
31
+ /** Execute with input, or with an explicit local view followed by input. */
32
+ async execute(...args) {
33
+ if (args.length !== 1 && args.length !== 2) {
34
+ throw new TypeError("execute expects input or view, input");
35
+ }
36
+ let value = args.at(-1);
37
+ if (this._query) {
38
+ if (!Array.isArray(value)) throw new TypeError("Prepared query input must be an array");
39
+ const { Connection } = await import("./connection.js");
40
+ const convert = this._typed ? toJava : toQueryInput;
41
+ value = await Promise.all(value.map(input => input instanceof Connection
42
+ ? _BINDINGS.connectionDb(input.rawHandle()) : convert(input)));
43
+ }
44
+ const normalized = await toJava(value);
45
+ const result = args.length === 2
46
+ ? await callJavaMethod(this._handle, "executeBridge", await viewHandle(args[0]), normalized)
47
+ : await callJavaMethod(this._handle, "executeBridge", normalized);
48
+ return toJs(result);
49
+ }
50
+ }
51
+
52
+ nativeMethods(PreparedRead);
53
+
54
+ /** Prepare a pull from a Connection or Database, with optional pull options. */
55
+ export async function preparePull(database, selector, opts = null) {
56
+ return withNativeScope(database._nativeRegistry, async () => new PreparedRead(
57
+ await _BINDINGS.preparePull(await viewHandle(database), await form(selector), opts)
58
+ ));
59
+ }
60
+
61
+ /** Prepare a query; execute with an array of the remaining :in values. */
62
+ export async function prepareQuery(database, query) {
63
+ return withNativeScope(database._nativeRegistry, async () => new PreparedRead(
64
+ await _BINDINGS.prepareQuery(await viewHandle(database), await form(query)),
65
+ { query: true, typed: query instanceof Form }
66
+ ));
67
+ }
68
+
69
+ /** Prepare a KV point read. Types default to data; results default to values. */
70
+ export async function prepareGetValue(kv, dbiName, {
71
+ kType = null, vType = null, ignoreKey = true
72
+ } = {}) {
73
+ return withNativeScope(kv._nativeRegistry, async () => new PreparedRead(
74
+ await _BINDINGS.prepareGetValue(kv.rawHandle(), dbiName, kType, vType, ignoreKey)
75
+ ));
76
+ }
77
+
78
+ export async function executePrepared(prepared, ...args) {
79
+ return prepared.execute(...args);
80
+ }
81
+
82
+ export async function transactAck(conn, txData, txMeta = null) {
83
+ return conn.transactAck(txData, txMeta);
84
+ }
85
+
86
+ export async function indexAttr(conn, attr) {
87
+ return conn.indexAttr(attr);
88
+ }