@hajewski/latticedb 0.16.0 → 0.18.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/dist/ffi/index.js CHANGED
@@ -8,16 +8,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
8
8
  return (mod && mod.__esModule) ? mod : { "default": mod };
9
9
  };
10
10
  Object.defineProperty(exports, "__esModule", { value: true });
11
- exports.LatticeFFI = exports.LatticeQueryError = exports.LatticeError = exports.ELECTRON_ASAR_UNPACK_GLOB = exports.isElectronRuntime = exports.resolveLibraryPath = exports.getLibraryPath = exports.isLibraryAvailable = void 0;
11
+ exports.LatticeFFI = exports.LatticeQueryError = exports.LatticeChangesTrimmedError = exports.LatticeError = exports.QueryErrorStage = exports.LatticeErrorCode = exports.ELECTRON_ASAR_UNPACK_GLOB = exports.isElectronRuntime = exports.resolveLibraryPath = exports.getLibraryPath = exports.isLibraryAvailable = void 0;
12
+ exports.changefeedRetentionCode = changefeedRetentionCode;
12
13
  exports.getFFI = getFFI;
13
14
  const koffi_1 = __importDefault(require("koffi"));
14
15
  const bindings_1 = require("./bindings");
16
+ const types_1 = require("./types");
15
17
  var library_1 = require("./library");
16
18
  Object.defineProperty(exports, "isLibraryAvailable", { enumerable: true, get: function () { return library_1.isLibraryAvailable; } });
17
19
  Object.defineProperty(exports, "getLibraryPath", { enumerable: true, get: function () { return library_1.getLibraryPath; } });
18
20
  Object.defineProperty(exports, "resolveLibraryPath", { enumerable: true, get: function () { return library_1.resolveLibraryPath; } });
19
21
  Object.defineProperty(exports, "isElectronRuntime", { enumerable: true, get: function () { return library_1.isElectronRuntime; } });
20
22
  Object.defineProperty(exports, "ELECTRON_ASAR_UNPACK_GLOB", { enumerable: true, get: function () { return library_1.ELECTRON_ASAR_UNPACK_GLOB; } });
23
+ var types_2 = require("./types");
24
+ Object.defineProperty(exports, "LatticeErrorCode", { enumerable: true, get: function () { return types_2.LatticeErrorCode; } });
25
+ Object.defineProperty(exports, "QueryErrorStage", { enumerable: true, get: function () { return types_2.QueryErrorStage; } });
21
26
  /**
22
27
  * Error class for Lattice operations.
23
28
  */
@@ -30,6 +35,19 @@ class LatticeError extends Error {
30
35
  }
31
36
  }
32
37
  exports.LatticeError = LatticeError;
38
+ /**
39
+ * The changefeed no longer holds the events after the position read from:
40
+ * its retention policy, or a trim, dropped them, so the reader has missed
41
+ * changes. Reading from `afterSequence: 0n` starts at the oldest event held.
42
+ * Its code is `LatticeErrorCode.NotFound`.
43
+ */
44
+ class LatticeChangesTrimmedError extends LatticeError {
45
+ constructor(message) {
46
+ super(message, types_1.LatticeErrorCode.NotFound);
47
+ this.name = 'LatticeChangesTrimmedError';
48
+ }
49
+ }
50
+ exports.LatticeChangesTrimmedError = LatticeChangesTrimmedError;
33
51
  /**
34
52
  * Rich query execution error with stage-aware diagnostics.
35
53
  */
@@ -46,6 +64,137 @@ class LatticeQueryError extends LatticeError {
46
64
  }
47
65
  }
48
66
  exports.LatticeQueryError = LatticeQueryError;
67
+ const U64_MAX = (BigInt(1) << BigInt(64)) - BigInt(1);
68
+ // Longest suffix first, so "ms" is not read as "s".
69
+ const DURATION_UNITS = [
70
+ ['ms', BigInt(1)],
71
+ ['s', BigInt(1000)],
72
+ ['m', BigInt(60_000)],
73
+ ['h', BigInt(3_600_000)],
74
+ ['d', BigInt(86_400_000)],
75
+ ];
76
+ /** Turn a policy such as `'last:1000'` into the C API's mode and value. */
77
+ function changefeedRetentionCode(policy) {
78
+ if (policy === undefined) {
79
+ return [0 /* LatticeChangefeedRetention.Default */, BigInt(0)];
80
+ }
81
+ if (typeof policy === 'string') {
82
+ const lowered = policy.toLowerCase();
83
+ if (lowered === 'all') {
84
+ return [1 /* LatticeChangefeedRetention.All */, BigInt(0)];
85
+ }
86
+ if (lowered === 'off') {
87
+ return [4 /* LatticeChangefeedRetention.Off */, BigInt(0)];
88
+ }
89
+ if (policy.startsWith('last:')) {
90
+ const digits = policy.slice(5);
91
+ if (/^[0-9]+$/.test(digits)) {
92
+ const n = BigInt(digits);
93
+ if (n > BigInt(0) && n <= U64_MAX) {
94
+ return [2 /* LatticeChangefeedRetention.Last */, n];
95
+ }
96
+ }
97
+ }
98
+ else if (policy.startsWith('age:')) {
99
+ const text = policy.slice(4);
100
+ for (const [suffix, ms] of DURATION_UNITS) {
101
+ const number = text.slice(0, text.length - suffix.length);
102
+ if (text.endsWith(suffix) && /^[0-9]+$/.test(number)) {
103
+ const value = BigInt(number) * ms;
104
+ if (value > BigInt(0) && value <= U64_MAX) {
105
+ return [3 /* LatticeChangefeedRetention.Age */, value];
106
+ }
107
+ break;
108
+ }
109
+ }
110
+ }
111
+ }
112
+ throw new TypeError("changefeedRetention must be 'all', 'off', 'last:<events>' or 'age:<duration>' " +
113
+ `(such as 'age:7d', 'age:12h', 'age:500ms'), not ${String(policy)}`);
114
+ }
115
+ function changefeedRetentionText(mode, value) {
116
+ switch (mode) {
117
+ case 4 /* LatticeChangefeedRetention.Off */:
118
+ return 'off';
119
+ case 2 /* LatticeChangefeedRetention.Last */:
120
+ return `last:${value}`;
121
+ case 3 /* LatticeChangefeedRetention.Age */: {
122
+ for (const [suffix, ms] of DURATION_UNITS.slice(1).reverse()) {
123
+ if (value % ms === BigInt(0)) {
124
+ return `age:${value / ms}${suffix}`;
125
+ }
126
+ }
127
+ return `age:${value}ms`;
128
+ }
129
+ default:
130
+ return 'all';
131
+ }
132
+ }
133
+ function syncModeCode(mode) {
134
+ switch (mode) {
135
+ case undefined:
136
+ return 0 /* LatticeSyncMode.Default */;
137
+ case 'full':
138
+ return 1 /* LatticeSyncMode.Full */;
139
+ case 'normal':
140
+ return 2 /* LatticeSyncMode.Normal */;
141
+ default:
142
+ throw new TypeError(`syncMode must be 'full' or 'normal', not ${String(mode)}`);
143
+ }
144
+ }
145
+ function fullFsyncCode(fullFsync) {
146
+ if (fullFsync === undefined) {
147
+ return 0 /* LatticeFullFsync.Default */;
148
+ }
149
+ return fullFsync ? 2 /* LatticeFullFsync.On */ : 1 /* LatticeFullFsync.Off */;
150
+ }
151
+ function vectorMetricCode(metric) {
152
+ switch (metric) {
153
+ case undefined:
154
+ return 0 /* LatticeVectorMetric.Default */;
155
+ case 'cosine':
156
+ return 1 /* LatticeVectorMetric.Cosine */;
157
+ case 'euclidean':
158
+ return 2 /* LatticeVectorMetric.Euclidean */;
159
+ case 'dot_product':
160
+ return 3 /* LatticeVectorMetric.DotProduct */;
161
+ default:
162
+ throw new TypeError(`vectorMetric must be 'cosine', 'euclidean' or 'dot_product', not ${String(metric)}`);
163
+ }
164
+ }
165
+ function checkpointModeCode(mode) {
166
+ switch (mode) {
167
+ case 'passive':
168
+ return 0 /* LatticeCheckpointMode.Passive */;
169
+ case 'full':
170
+ return 1 /* LatticeCheckpointMode.Full */;
171
+ case 'truncate':
172
+ return 2 /* LatticeCheckpointMode.Truncate */;
173
+ default:
174
+ throw new TypeError(`checkpoint mode must be 'passive', 'full' or 'truncate', not ${String(mode)}`);
175
+ }
176
+ }
177
+ /** A count of frames or milliseconds: a non-negative safe integer. */
178
+ function checkpointSetting(name, value) {
179
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
180
+ throw new RangeError(`${name} must be a non-negative integer, not ${String(value)}`);
181
+ }
182
+ return BigInt(value);
183
+ }
184
+ /**
185
+ * Copy `len` bytes of native memory into a new Uint8Array.
186
+ *
187
+ * koffi.view (koffi 2.11+) copies in one block; decoding to `number[]` first
188
+ * builds one JS number per byte, which for a serialized database is millions
189
+ * of them.
190
+ */
191
+ function copyNativeBytes(ptr, len) {
192
+ const view = koffi_1.default.view;
193
+ if (typeof view === 'function') {
194
+ return new Uint8Array(view(ptr, len).slice(0));
195
+ }
196
+ return Uint8Array.from(koffi_1.default.decode(ptr, 'uint8_t', len));
197
+ }
49
198
  /**
50
199
  * High-level FFI wrapper class.
51
200
  */
@@ -55,6 +204,11 @@ class LatticeFFI {
55
204
  static VALUE_SIZE = koffi_1.default.sizeof('lattice_value');
56
205
  static MAP_ENTRY_SIZE = koffi_1.default.sizeof('lattice_map_entry');
57
206
  static MAP_ENTRY_VALUE_OFFSET = koffi_1.default.offsetof('lattice_map_entry', 'value');
207
+ static CHECKPOINT_STATS_SIZE = koffi_1.default.sizeof('lattice_checkpoint_stats');
208
+ static CHECKPOINT_PAGES_OFFSET = koffi_1.default.offsetof('lattice_checkpoint_stats', 'pages_flushed');
209
+ static CHECKPOINT_DURATION_OFFSET = koffi_1.default.offsetof('lattice_checkpoint_stats', 'duration_ns');
210
+ static CHECKPOINT_LSN_OFFSET = koffi_1.default.offsetof('lattice_checkpoint_stats', 'checkpoint_lsn');
211
+ static CHECKPOINT_TRUNCATED_OFFSET = koffi_1.default.offsetof('lattice_checkpoint_stats', 'wal_truncated');
58
212
  constructor() {
59
213
  this.bindings = (0, bindings_1.getBindings)();
60
214
  }
@@ -62,30 +216,30 @@ class LatticeFFI {
62
216
  * Check an error code and throw if not OK.
63
217
  */
64
218
  checkError(code) {
65
- if (code !== 0 /* LatticeErrorCode.Ok */) {
219
+ if (code !== types_1.LatticeErrorCode.Ok) {
66
220
  const message = this.bindings.lattice_error_message(code);
67
221
  throw new LatticeError(message, code);
68
222
  }
69
223
  }
70
224
  normalizeQueryStage(stage) {
71
225
  switch (stage) {
72
- case 1 /* QueryErrorStage.Parse */:
73
- return 1 /* QueryErrorStage.Parse */;
74
- case 2 /* QueryErrorStage.Semantic */:
75
- return 2 /* QueryErrorStage.Semantic */;
76
- case 3 /* QueryErrorStage.Plan */:
77
- return 3 /* QueryErrorStage.Plan */;
78
- case 4 /* QueryErrorStage.Execution */:
79
- return 4 /* QueryErrorStage.Execution */;
226
+ case types_1.QueryErrorStage.Parse:
227
+ return types_1.QueryErrorStage.Parse;
228
+ case types_1.QueryErrorStage.Semantic:
229
+ return types_1.QueryErrorStage.Semantic;
230
+ case types_1.QueryErrorStage.Plan:
231
+ return types_1.QueryErrorStage.Plan;
232
+ case types_1.QueryErrorStage.Execution:
233
+ return types_1.QueryErrorStage.Execution;
80
234
  default:
81
- return 0 /* QueryErrorStage.None */;
235
+ return types_1.QueryErrorStage.None;
82
236
  }
83
237
  }
84
238
  /**
85
239
  * Check an error code for query execution and include detailed diagnostics.
86
240
  */
87
241
  checkQueryError(code, query) {
88
- if (code === 0 /* LatticeErrorCode.Ok */) {
242
+ if (code === types_1.LatticeErrorCode.Ok) {
89
243
  return;
90
244
  }
91
245
  const stage = this.normalizeQueryStage(this.bindings.lattice_query_last_error_stage(query));
@@ -99,7 +253,7 @@ class LatticeFFI {
99
253
  length: this.bindings.lattice_query_last_error_length(query),
100
254
  };
101
255
  }
102
- if (stage !== 0 /* QueryErrorStage.None */ || detailMessage !== undefined) {
256
+ if (stage !== types_1.QueryErrorStage.None || detailMessage !== undefined) {
103
257
  const fallbackMessage = this.bindings.lattice_error_message(code);
104
258
  throw new LatticeQueryError(detailMessage ?? fallbackMessage, code, stage, detailCode, location);
105
259
  }
@@ -121,19 +275,33 @@ class LatticeFFI {
121
275
  const enableWal = options.enableWal ?? true;
122
276
  const enableAdjacencyCache = options.enableAdjacencyCache ?? false;
123
277
  const lock = options.lock ?? true;
278
+ const syncMode = syncModeCode(options.syncMode);
279
+ const fullFsync = fullFsyncCode(options.fullFsync);
280
+ const vectorMetric = vectorMetricCode(options.vectorMetric);
281
+ const vectorM = options.vectorM ?? 0;
282
+ const vectorEfConstruction = options.vectorEfConstruction ?? 0;
283
+ const [changefeedRetention, changefeedRetentionValue] = changefeedRetentionCode(options.changefeedRetention);
284
+ if (changefeedRetention && !this.bindings.lattice_changefeed_status) {
285
+ throw new LatticeError('the native library is too old to support changefeedRetention', types_1.LatticeErrorCode.Unsupported);
286
+ }
287
+ if (!this.bindings.lattice_open_v5 &&
288
+ (syncMode || fullFsync || vectorMetric || vectorM || vectorEfConstruction)) {
289
+ throw new LatticeError('lattice_open_v5 is required for syncMode, fullFsync, vectorMetric, vectorM ' +
290
+ 'and vectorEfConstruction', types_1.LatticeErrorCode.Unsupported);
291
+ }
124
292
  if (!this.bindings.lattice_open_v4 && !lock) {
125
- throw new LatticeError('lattice_open_v4 is required to disable the file lock', -14 /* LatticeErrorCode.Unsupported */);
293
+ throw new LatticeError('lattice_open_v4 is required to disable the file lock', types_1.LatticeErrorCode.Unsupported);
126
294
  }
127
295
  if (!this.bindings.lattice_open_v2 && !enableWal) {
128
- throw new LatticeError('lattice_open_v2 is required to disable WAL', -14 /* LatticeErrorCode.Unsupported */);
296
+ throw new LatticeError('lattice_open_v2 is required to disable WAL', types_1.LatticeErrorCode.Unsupported);
129
297
  }
130
298
  if (!this.bindings.lattice_open_v3 && enableAdjacencyCache) {
131
- throw new LatticeError('lattice_open_v3 is required to enable the adjacency cache', -14 /* LatticeErrorCode.Unsupported */);
299
+ throw new LatticeError('lattice_open_v3 is required to enable the adjacency cache', types_1.LatticeErrorCode.Unsupported);
132
300
  }
133
301
  const baseOpts = {
134
302
  create: options.create ?? false,
135
303
  read_only: options.readOnly ?? false,
136
- cache_size_mb: options.cacheSizeMb ?? 100,
304
+ cache_size_mb: options.cacheSizeMb ?? 0,
137
305
  page_size: options.pageSize ?? 4096,
138
306
  enable_vector: options.enableVectors ?? options.enableVector ?? false,
139
307
  vector_dimensions: options.vectorDimensions ?? 128,
@@ -156,14 +324,27 @@ class LatticeFFI {
156
324
  enable_adjacency_cache: enableAdjacencyCache,
157
325
  lock,
158
326
  };
327
+ const v5Opts = {
328
+ ...v4Opts,
329
+ struct_size: koffi_1.default.sizeof('lattice_open_options_v5'),
330
+ sync_mode: syncMode,
331
+ full_fsync: fullFsync,
332
+ vector_metric: vectorMetric,
333
+ vector_m: vectorM,
334
+ vector_ef_construction: vectorEfConstruction,
335
+ changefeed_retention: changefeedRetention,
336
+ changefeed_retention_value: changefeedRetentionValue,
337
+ };
159
338
  const dbOut = [null];
160
- const err = this.bindings.lattice_open_v4
161
- ? this.bindings.lattice_open_v4(path, v4Opts, dbOut)
162
- : this.bindings.lattice_open_v3
163
- ? this.bindings.lattice_open_v3(path, v3Opts, dbOut)
164
- : this.bindings.lattice_open_v2
165
- ? this.bindings.lattice_open_v2(path, v2Opts, dbOut)
166
- : this.bindings.lattice_open(path, baseOpts, dbOut);
339
+ const err = this.bindings.lattice_open_v5
340
+ ? this.bindings.lattice_open_v5(path, v5Opts, dbOut)
341
+ : this.bindings.lattice_open_v4
342
+ ? this.bindings.lattice_open_v4(path, v4Opts, dbOut)
343
+ : this.bindings.lattice_open_v3
344
+ ? this.bindings.lattice_open_v3(path, v3Opts, dbOut)
345
+ : this.bindings.lattice_open_v2
346
+ ? this.bindings.lattice_open_v2(path, v2Opts, dbOut)
347
+ : this.bindings.lattice_open(path, baseOpts, dbOut);
167
348
  this.checkError(err);
168
349
  return dbOut[0];
169
350
  }
@@ -172,7 +353,7 @@ class LatticeFFI {
172
353
  */
173
354
  serialize(db) {
174
355
  if (!this.bindings.lattice_serialize || !this.bindings.lattice_free_bytes) {
175
- throw new LatticeError('the native library is too old to support serialize', -14 /* LatticeErrorCode.Unsupported */);
356
+ throw new LatticeError('the native library is too old to support serialize', types_1.LatticeErrorCode.Unsupported);
176
357
  }
177
358
  const bytesOut = [null];
178
359
  const lenOut = [0];
@@ -185,8 +366,7 @@ class LatticeFFI {
185
366
  try {
186
367
  // Copied out before the native buffer is released, so what the caller
187
368
  // holds does not depend on memory this function is about to free.
188
- const decoded = koffi_1.default.decode(ptr, 'uint8_t', len);
189
- return Uint8Array.from(decoded);
369
+ return copyNativeBytes(ptr, len);
190
370
  }
191
371
  finally {
192
372
  this.bindings.lattice_free_bytes(ptr, len);
@@ -194,19 +374,32 @@ class LatticeFFI {
194
374
  }
195
375
  /**
196
376
  * Open a database from bytes produced by `serialize`.
377
+ *
378
+ * Uses the v5 entry point when the library has it, so the sync and vector
379
+ * index options reach the database as they do for `open`; otherwise the v4
380
+ * one, which cannot carry them.
197
381
  */
198
382
  deserialize(bytes, options = {}, copy = true) {
199
383
  const entry = copy
200
384
  ? this.bindings.lattice_deserialize
201
385
  : this.bindings.lattice_deserialize_borrowed;
202
- if (!entry) {
203
- throw new LatticeError('the native library is too old to support deserialize', -14 /* LatticeErrorCode.Unsupported */);
386
+ const entryV5 = copy
387
+ ? this.bindings.lattice_deserialize_v5
388
+ : this.bindings.lattice_deserialize_borrowed_v5;
389
+ if (!entry && !entryV5) {
390
+ throw new LatticeError('the native library is too old to support deserialize', types_1.LatticeErrorCode.Unsupported);
204
391
  }
205
- const opts = {
392
+ const syncMode = syncModeCode(options.syncMode);
393
+ const fullFsync = fullFsyncCode(options.fullFsync);
394
+ const vectorMetric = vectorMetricCode(options.vectorMetric);
395
+ const vectorM = options.vectorM ?? 0;
396
+ const vectorEfConstruction = options.vectorEfConstruction ?? 0;
397
+ const [changefeedRetention, changefeedRetentionValue] = changefeedRetentionCode(options.changefeedRetention);
398
+ const v4Opts = {
206
399
  struct_size: koffi_1.default.sizeof('lattice_open_options_v4'),
207
400
  create: false,
208
401
  read_only: false,
209
- cache_size_mb: options.cacheSizeMb ?? 100,
402
+ cache_size_mb: options.cacheSizeMb ?? 0,
210
403
  page_size: options.pageSize ?? 4096,
211
404
  enable_vector: options.enableVectors ?? options.enableVector ?? false,
212
405
  vector_dimensions: options.vectorDimensions ?? 128,
@@ -215,7 +408,32 @@ class LatticeFFI {
215
408
  lock: options.lock ?? true,
216
409
  };
217
410
  const dbOut = [null];
218
- this.checkError(entry(bytes, bytes.length, opts, dbOut));
411
+ if (entryV5) {
412
+ const v5Opts = {
413
+ ...v4Opts,
414
+ struct_size: koffi_1.default.sizeof('lattice_open_options_v5'),
415
+ sync_mode: syncMode,
416
+ full_fsync: fullFsync,
417
+ vector_metric: vectorMetric,
418
+ vector_m: vectorM,
419
+ vector_ef_construction: vectorEfConstruction,
420
+ changefeed_retention: changefeedRetention,
421
+ changefeed_retention_value: changefeedRetentionValue,
422
+ };
423
+ this.checkError(entryV5(bytes, bytes.length, v5Opts, dbOut));
424
+ return dbOut[0];
425
+ }
426
+ if (syncMode ||
427
+ fullFsync ||
428
+ vectorMetric ||
429
+ vectorM ||
430
+ vectorEfConstruction ||
431
+ changefeedRetention) {
432
+ throw new LatticeError('lattice_deserialize_v5 is required for syncMode, fullFsync, vectorMetric, ' +
433
+ 'vectorM, vectorEfConstruction and changefeedRetention', types_1.LatticeErrorCode.Unsupported);
434
+ }
435
+ // entryV5 is absent here, so the check above guarantees entry.
436
+ this.checkError(entry(bytes, bytes.length, v4Opts, dbOut));
219
437
  return dbOut[0];
220
438
  }
221
439
  /**
@@ -225,6 +443,34 @@ class LatticeFFI {
225
443
  const err = this.bindings.lattice_close(db);
226
444
  this.checkError(err);
227
445
  }
446
+ /**
447
+ * Checkpoint now. The mode is checked before the library is called.
448
+ */
449
+ checkpoint(db, mode) {
450
+ const modeCode = checkpointModeCode(mode);
451
+ if (!this.bindings.lattice_checkpoint) {
452
+ throw new LatticeError('the native library is too old to support checkpoint', types_1.LatticeErrorCode.Unsupported);
453
+ }
454
+ const statsOut = Buffer.alloc(LatticeFFI.CHECKPOINT_STATS_SIZE);
455
+ this.checkError(this.bindings.lattice_checkpoint(db, modeCode, statsOut));
456
+ return {
457
+ pagesFlushed: statsOut.readUInt32LE(LatticeFFI.CHECKPOINT_PAGES_OFFSET),
458
+ durationNs: statsOut.readBigUInt64LE(LatticeFFI.CHECKPOINT_DURATION_OFFSET),
459
+ checkpointLsn: statsOut.readBigUInt64LE(LatticeFFI.CHECKPOINT_LSN_OFFSET),
460
+ walTruncated: statsOut.readUInt8(LatticeFFI.CHECKPOINT_TRUNCATED_OFFSET) !== 0,
461
+ };
462
+ }
463
+ /**
464
+ * Set when commits checkpoint from now on; 0 frames switches them off.
465
+ */
466
+ setAutoCheckpoint(db, maxWalFrames, minIntervalMs) {
467
+ const frames = checkpointSetting('maxWalFrames', maxWalFrames);
468
+ const interval = checkpointSetting('minIntervalMs', minIntervalMs);
469
+ if (!this.bindings.lattice_set_auto_checkpoint) {
470
+ throw new LatticeError('the native library is too old to support setAutoCheckpoint', types_1.LatticeErrorCode.Unsupported);
471
+ }
472
+ this.checkError(this.bindings.lattice_set_auto_checkpoint(db, frames, interval));
473
+ }
228
474
  // ============================================================
229
475
  // Transaction operations
230
476
  // ============================================================
@@ -279,12 +525,22 @@ class LatticeFFI {
279
525
  this.checkError(err);
280
526
  }
281
527
  /**
282
- * Delete a node.
528
+ * Delete a node. Fails with HasRelationships while the node has any.
283
529
  */
284
530
  deleteNode(txn, nodeId) {
285
531
  const err = this.bindings.lattice_node_delete(txn, nodeId);
286
532
  this.checkError(err);
287
533
  }
534
+ /**
535
+ * Delete a node and every relationship it has.
536
+ */
537
+ detachDeleteNode(txn, nodeId) {
538
+ if (!this.bindings.lattice_node_detach_delete) {
539
+ throw new LatticeError('lattice_node_detach_delete is required to delete a node with its relationships', types_1.LatticeErrorCode.Unsupported);
540
+ }
541
+ const err = this.bindings.lattice_node_detach_delete(txn, nodeId);
542
+ this.checkError(err);
543
+ }
288
544
  /**
289
545
  * Check if a node exists.
290
546
  */
@@ -414,6 +670,39 @@ class LatticeFFI {
414
670
  const err = this.bindings.lattice_node_set_vector(txn, nodeId, key, vector, vector.length);
415
671
  this.checkError(err);
416
672
  }
673
+ /**
674
+ * Get a node's vector, or null when it has none.
675
+ */
676
+ getVector(txn, nodeId, key) {
677
+ if (!this.bindings.lattice_node_get_vector || !this.bindings.lattice_free_vector) {
678
+ throw new LatticeError('lattice_node_get_vector is required to read a node\'s vector', types_1.LatticeErrorCode.Unsupported);
679
+ }
680
+ const vectorOut = [null];
681
+ const dimsOut = Buffer.alloc(4);
682
+ const err = this.bindings.lattice_node_get_vector(txn, nodeId, key, vectorOut, dimsOut);
683
+ this.checkError(err);
684
+ const ptr = vectorOut[0];
685
+ const dims = dimsOut.readUInt32LE();
686
+ if (!ptr || dims === 0)
687
+ return null;
688
+ try {
689
+ const floats = koffi_1.default.decode(ptr, 'float', dims);
690
+ return new Float32Array(floats);
691
+ }
692
+ finally {
693
+ this.bindings.lattice_free_vector(ptr, dims);
694
+ }
695
+ }
696
+ /**
697
+ * Remove a node's vector. Removing a vector the node does not have does nothing.
698
+ */
699
+ removeVector(txn, nodeId, key) {
700
+ if (!this.bindings.lattice_node_remove_vector) {
701
+ throw new LatticeError('lattice_node_remove_vector is required to remove a node\'s vector', types_1.LatticeErrorCode.Unsupported);
702
+ }
703
+ const err = this.bindings.lattice_node_remove_vector(txn, nodeId, key);
704
+ this.checkError(err);
705
+ }
417
706
  /**
418
707
  * Batch insert multiple nodes with vectors.
419
708
  */
@@ -435,7 +724,7 @@ class LatticeFFI {
435
724
  this.checkError(err);
436
725
  const created = countOut.readUInt32LE();
437
726
  if (created < count) {
438
- throw new LatticeError(`Batch insert partially failed: ${created}/${count} nodes created. Transaction should be rolled back.`, -1 /* LatticeErrorCode.Error */);
727
+ throw new LatticeError(`Batch insert partially failed: ${created}/${count} nodes created. Transaction should be rolled back.`, types_1.LatticeErrorCode.Error);
439
728
  }
440
729
  const ids = [];
441
730
  for (let i = 0; i < created; i++) {
@@ -462,6 +751,9 @@ class LatticeFFI {
462
751
  let ownsNativeValue = false;
463
752
  try {
464
753
  const err = this.bindings.lattice_node_get_property(txn, nodeId, key, valueOut);
754
+ if (err === types_1.LatticeErrorCode.NotFound) {
755
+ return null;
756
+ }
465
757
  this.checkError(err);
466
758
  ownsNativeValue = true;
467
759
  return this.nativeValueToJs(valueOut);
@@ -489,12 +781,71 @@ class LatticeFFI {
489
781
  this.checkError(err);
490
782
  return sequenceOut.readBigUInt64LE();
491
783
  }
784
+ /**
785
+ * The changefeed's retention policy, the oldest event it holds and the
786
+ * last sequence it handed out.
787
+ */
788
+ changefeedStatus(db) {
789
+ if (!this.bindings.lattice_changefeed_status) {
790
+ throw new LatticeError("the native library is too old to report the changefeed's status", types_1.LatticeErrorCode.Unsupported);
791
+ }
792
+ const mode = Buffer.alloc(1);
793
+ const value = Buffer.alloc(8);
794
+ const oldest = Buffer.alloc(8);
795
+ const last = Buffer.alloc(8);
796
+ this.checkError(this.bindings.lattice_changefeed_status(db, mode, value, oldest, last));
797
+ const oldestSequence = oldest.readBigUInt64LE();
798
+ return {
799
+ retention: changefeedRetentionText(mode.readUInt8(0), value.readBigUInt64LE()),
800
+ oldestSequence: oldestSequence === BigInt(0) ? null : oldestSequence,
801
+ lastSequence: last.readBigUInt64LE(),
802
+ };
803
+ }
804
+ /**
805
+ * Apply the changefeed's retention policy in full now. Returns the number
806
+ * of events dropped.
807
+ */
808
+ trimChangefeed(db) {
809
+ if (!this.bindings.lattice_changefeed_trim) {
810
+ throw new LatticeError('the native library is too old to trim the changefeed', types_1.LatticeErrorCode.Unsupported);
811
+ }
812
+ const removed = Buffer.alloc(8);
813
+ this.checkError(this.bindings.lattice_changefeed_trim(db, removed));
814
+ return removed.readBigUInt64LE();
815
+ }
492
816
  readStream(db, stream, afterSequence = BigInt(0), limit = 100, timeoutMs = 0) {
493
817
  const streamBuf = Buffer.from(stream, 'utf8');
494
818
  const batchOut = [null];
495
819
  const err = this.bindings.lattice_stream_read(db, streamBuf, streamBuf.length, afterSequence, limit, timeoutMs, batchOut);
496
820
  this.checkError(err);
497
- const batch = batchOut[0];
821
+ return this.takeStreamBatch(batchOut[0]);
822
+ }
823
+ /**
824
+ * Read a stream on a koffi worker thread, so a wait of `timeoutMs` does not
825
+ * block the event loop. Blocking it would also block the commit the reader
826
+ * is waiting for whenever that commit comes from this same thread.
827
+ */
828
+ readStreamAsync(db, stream, afterSequence = BigInt(0), limit = 100, timeoutMs = 0) {
829
+ const streamBuf = Buffer.from(stream, 'utf8');
830
+ const batchOut = [null];
831
+ return new Promise((resolve, reject) => {
832
+ this.bindings.lattice_stream_read.async(db, streamBuf, streamBuf.length, afterSequence, limit, timeoutMs, batchOut, (callErr, err) => {
833
+ if (callErr) {
834
+ reject(callErr);
835
+ return;
836
+ }
837
+ try {
838
+ this.checkError(err);
839
+ resolve(this.takeStreamBatch(batchOut[0]));
840
+ }
841
+ catch (decodeErr) {
842
+ reject(decodeErr);
843
+ }
844
+ });
845
+ });
846
+ }
847
+ /** Decode a stream batch into records and free it. */
848
+ takeStreamBatch(batch) {
498
849
  if (!batch) {
499
850
  return [];
500
851
  }
@@ -720,8 +1071,7 @@ class LatticeFFI {
720
1071
  const len = this.decodeSize(value, dataOffset + 8);
721
1072
  if (!ptr || len === 0)
722
1073
  return new Uint8Array(0);
723
- const bytes = koffi_1.default.decode(ptr, 'uint8_t', len);
724
- return Uint8Array.from(bytes);
1074
+ return copyNativeBytes(ptr, len);
725
1075
  }
726
1076
  case 6 /* LatticeValueType.Vector */: {
727
1077
  const ptr = this.decodePointer(value, dataOffset);
@@ -766,7 +1116,7 @@ class LatticeFFI {
766
1116
  return result;
767
1117
  }
768
1118
  default:
769
- throw new LatticeError(`Unsupported native value type: ${type}`, -14 /* LatticeErrorCode.Unsupported */);
1119
+ throw new LatticeError(`Unsupported native value type: ${type}`, types_1.LatticeErrorCode.Unsupported);
770
1120
  }
771
1121
  }
772
1122
  /**
@@ -804,8 +1154,7 @@ class LatticeFFI {
804
1154
  const len = Number(bv.len);
805
1155
  if (!bv.ptr || len === 0)
806
1156
  return new Uint8Array(0);
807
- const bytes = koffi_1.default.decode(bv.ptr, 'uint8_t', len);
808
- return Uint8Array.from(bytes);
1157
+ return copyNativeBytes(bv.ptr, len);
809
1158
  }
810
1159
  case 6 /* LatticeValueType.Vector */: {
811
1160
  const vv = data.vector_val;
@@ -837,7 +1186,7 @@ class LatticeFFI {
837
1186
  return result;
838
1187
  }
839
1188
  default:
840
- throw new LatticeError(`Unsupported native value type: ${type}`, -14 /* LatticeErrorCode.Unsupported */);
1189
+ throw new LatticeError(`Unsupported native value type: ${type}`, types_1.LatticeErrorCode.Unsupported);
841
1190
  }
842
1191
  }
843
1192
  // ============================================================
@@ -1028,7 +1377,7 @@ class LatticeFFI {
1028
1377
  let ownsNativeValue = false;
1029
1378
  try {
1030
1379
  const err = this.bindings.lattice_edge_get_property(txn, edgeId, key, valueOut);
1031
- if (err === -4 /* LatticeErrorCode.NotFound */) {
1380
+ if (err === types_1.LatticeErrorCode.NotFound) {
1032
1381
  return null;
1033
1382
  }
1034
1383
  this.checkError(err);
@@ -1110,10 +1459,16 @@ class LatticeFFI {
1110
1459
  const edgeTypeLenOut = Buffer.alloc(4);
1111
1460
  const err = this.bindings.lattice_edge_result_get(result, index, sourceOut, targetOut, edgeTypeOut, edgeTypeLenOut);
1112
1461
  this.checkError(err);
1462
+ // The type is a (pointer, length) pair. Libraries before 0.17.0 did not
1463
+ // NUL-terminate it, so it is read by its length rather than as a C string.
1464
+ const edgeTypeLen = edgeTypeLenOut.readUInt32LE();
1465
+ const edgeType = edgeTypeOut[0] && edgeTypeLen > 0
1466
+ ? Buffer.from(koffi_1.default.decode(edgeTypeOut[0], 'uint8_t', edgeTypeLen)).toString('utf8')
1467
+ : '';
1113
1468
  return {
1114
1469
  source: sourceOut.readBigUInt64LE(),
1115
1470
  target: targetOut.readBigUInt64LE(),
1116
- edgeType: edgeTypeOut[0],
1471
+ edgeType,
1117
1472
  };
1118
1473
  }
1119
1474
  /**