@hajewski/latticedb 0.16.0 → 0.17.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
  */
@@ -435,7 +691,7 @@ class LatticeFFI {
435
691
  this.checkError(err);
436
692
  const created = countOut.readUInt32LE();
437
693
  if (created < count) {
438
- throw new LatticeError(`Batch insert partially failed: ${created}/${count} nodes created. Transaction should be rolled back.`, -1 /* LatticeErrorCode.Error */);
694
+ throw new LatticeError(`Batch insert partially failed: ${created}/${count} nodes created. Transaction should be rolled back.`, types_1.LatticeErrorCode.Error);
439
695
  }
440
696
  const ids = [];
441
697
  for (let i = 0; i < created; i++) {
@@ -462,6 +718,9 @@ class LatticeFFI {
462
718
  let ownsNativeValue = false;
463
719
  try {
464
720
  const err = this.bindings.lattice_node_get_property(txn, nodeId, key, valueOut);
721
+ if (err === types_1.LatticeErrorCode.NotFound) {
722
+ return null;
723
+ }
465
724
  this.checkError(err);
466
725
  ownsNativeValue = true;
467
726
  return this.nativeValueToJs(valueOut);
@@ -489,12 +748,71 @@ class LatticeFFI {
489
748
  this.checkError(err);
490
749
  return sequenceOut.readBigUInt64LE();
491
750
  }
751
+ /**
752
+ * The changefeed's retention policy, the oldest event it holds and the
753
+ * last sequence it handed out.
754
+ */
755
+ changefeedStatus(db) {
756
+ if (!this.bindings.lattice_changefeed_status) {
757
+ throw new LatticeError("the native library is too old to report the changefeed's status", types_1.LatticeErrorCode.Unsupported);
758
+ }
759
+ const mode = Buffer.alloc(1);
760
+ const value = Buffer.alloc(8);
761
+ const oldest = Buffer.alloc(8);
762
+ const last = Buffer.alloc(8);
763
+ this.checkError(this.bindings.lattice_changefeed_status(db, mode, value, oldest, last));
764
+ const oldestSequence = oldest.readBigUInt64LE();
765
+ return {
766
+ retention: changefeedRetentionText(mode.readUInt8(0), value.readBigUInt64LE()),
767
+ oldestSequence: oldestSequence === BigInt(0) ? null : oldestSequence,
768
+ lastSequence: last.readBigUInt64LE(),
769
+ };
770
+ }
771
+ /**
772
+ * Apply the changefeed's retention policy in full now. Returns the number
773
+ * of events dropped.
774
+ */
775
+ trimChangefeed(db) {
776
+ if (!this.bindings.lattice_changefeed_trim) {
777
+ throw new LatticeError('the native library is too old to trim the changefeed', types_1.LatticeErrorCode.Unsupported);
778
+ }
779
+ const removed = Buffer.alloc(8);
780
+ this.checkError(this.bindings.lattice_changefeed_trim(db, removed));
781
+ return removed.readBigUInt64LE();
782
+ }
492
783
  readStream(db, stream, afterSequence = BigInt(0), limit = 100, timeoutMs = 0) {
493
784
  const streamBuf = Buffer.from(stream, 'utf8');
494
785
  const batchOut = [null];
495
786
  const err = this.bindings.lattice_stream_read(db, streamBuf, streamBuf.length, afterSequence, limit, timeoutMs, batchOut);
496
787
  this.checkError(err);
497
- const batch = batchOut[0];
788
+ return this.takeStreamBatch(batchOut[0]);
789
+ }
790
+ /**
791
+ * Read a stream on a koffi worker thread, so a wait of `timeoutMs` does not
792
+ * block the event loop. Blocking it would also block the commit the reader
793
+ * is waiting for whenever that commit comes from this same thread.
794
+ */
795
+ readStreamAsync(db, stream, afterSequence = BigInt(0), limit = 100, timeoutMs = 0) {
796
+ const streamBuf = Buffer.from(stream, 'utf8');
797
+ const batchOut = [null];
798
+ return new Promise((resolve, reject) => {
799
+ this.bindings.lattice_stream_read.async(db, streamBuf, streamBuf.length, afterSequence, limit, timeoutMs, batchOut, (callErr, err) => {
800
+ if (callErr) {
801
+ reject(callErr);
802
+ return;
803
+ }
804
+ try {
805
+ this.checkError(err);
806
+ resolve(this.takeStreamBatch(batchOut[0]));
807
+ }
808
+ catch (decodeErr) {
809
+ reject(decodeErr);
810
+ }
811
+ });
812
+ });
813
+ }
814
+ /** Decode a stream batch into records and free it. */
815
+ takeStreamBatch(batch) {
498
816
  if (!batch) {
499
817
  return [];
500
818
  }
@@ -720,8 +1038,7 @@ class LatticeFFI {
720
1038
  const len = this.decodeSize(value, dataOffset + 8);
721
1039
  if (!ptr || len === 0)
722
1040
  return new Uint8Array(0);
723
- const bytes = koffi_1.default.decode(ptr, 'uint8_t', len);
724
- return Uint8Array.from(bytes);
1041
+ return copyNativeBytes(ptr, len);
725
1042
  }
726
1043
  case 6 /* LatticeValueType.Vector */: {
727
1044
  const ptr = this.decodePointer(value, dataOffset);
@@ -766,7 +1083,7 @@ class LatticeFFI {
766
1083
  return result;
767
1084
  }
768
1085
  default:
769
- throw new LatticeError(`Unsupported native value type: ${type}`, -14 /* LatticeErrorCode.Unsupported */);
1086
+ throw new LatticeError(`Unsupported native value type: ${type}`, types_1.LatticeErrorCode.Unsupported);
770
1087
  }
771
1088
  }
772
1089
  /**
@@ -804,8 +1121,7 @@ class LatticeFFI {
804
1121
  const len = Number(bv.len);
805
1122
  if (!bv.ptr || len === 0)
806
1123
  return new Uint8Array(0);
807
- const bytes = koffi_1.default.decode(bv.ptr, 'uint8_t', len);
808
- return Uint8Array.from(bytes);
1124
+ return copyNativeBytes(bv.ptr, len);
809
1125
  }
810
1126
  case 6 /* LatticeValueType.Vector */: {
811
1127
  const vv = data.vector_val;
@@ -837,7 +1153,7 @@ class LatticeFFI {
837
1153
  return result;
838
1154
  }
839
1155
  default:
840
- throw new LatticeError(`Unsupported native value type: ${type}`, -14 /* LatticeErrorCode.Unsupported */);
1156
+ throw new LatticeError(`Unsupported native value type: ${type}`, types_1.LatticeErrorCode.Unsupported);
841
1157
  }
842
1158
  }
843
1159
  // ============================================================
@@ -1028,7 +1344,7 @@ class LatticeFFI {
1028
1344
  let ownsNativeValue = false;
1029
1345
  try {
1030
1346
  const err = this.bindings.lattice_edge_get_property(txn, edgeId, key, valueOut);
1031
- if (err === -4 /* LatticeErrorCode.NotFound */) {
1347
+ if (err === types_1.LatticeErrorCode.NotFound) {
1032
1348
  return null;
1033
1349
  }
1034
1350
  this.checkError(err);
@@ -1110,10 +1426,16 @@ class LatticeFFI {
1110
1426
  const edgeTypeLenOut = Buffer.alloc(4);
1111
1427
  const err = this.bindings.lattice_edge_result_get(result, index, sourceOut, targetOut, edgeTypeOut, edgeTypeLenOut);
1112
1428
  this.checkError(err);
1429
+ // The type is a (pointer, length) pair. Libraries before 0.17.0 did not
1430
+ // NUL-terminate it, so it is read by its length rather than as a C string.
1431
+ const edgeTypeLen = edgeTypeLenOut.readUInt32LE();
1432
+ const edgeType = edgeTypeOut[0] && edgeTypeLen > 0
1433
+ ? Buffer.from(koffi_1.default.decode(edgeTypeOut[0], 'uint8_t', edgeTypeLen)).toString('utf8')
1434
+ : '';
1113
1435
  return {
1114
1436
  source: sourceOut.readBigUInt64LE(),
1115
1437
  target: targetOut.readBigUInt64LE(),
1116
- edgeType: edgeTypeOut[0],
1438
+ edgeType,
1117
1439
  };
1118
1440
  }
1119
1441
  /**