@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/README.md +186 -29
- package/dist/database.d.ts +124 -7
- package/dist/database.d.ts.map +1 -1
- package/dist/database.js +117 -5
- package/dist/database.js.map +1 -1
- package/dist/embedding.d.ts +1 -1
- package/dist/embedding.js +1 -1
- package/dist/ffi/bindings.d.ts +11 -1
- package/dist/ffi/bindings.d.ts.map +1 -1
- package/dist/ffi/bindings.js +70 -1
- package/dist/ffi/bindings.js.map +1 -1
- package/dist/ffi/index.d.ts +92 -3
- package/dist/ffi/index.d.ts.map +1 -1
- package/dist/ffi/index.js +365 -43
- package/dist/ffi/index.js.map +1 -1
- package/dist/ffi/library.d.ts.map +1 -1
- package/dist/ffi/library.js +8 -4
- package/dist/ffi/library.js.map +1 -1
- package/dist/ffi/types.d.ts +52 -4
- package/dist/ffi/types.d.ts.map +1 -1
- package/dist/ffi/types.js +46 -0
- package/dist/ffi/types.js.map +1 -1
- package/dist/index.d.ts +6 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -5
- package/dist/index.js.map +1 -1
- package/dist/transaction.d.ts +18 -3
- package/dist/transaction.d.ts.map +1 -1
- package/dist/transaction.js +36 -4
- package/dist/transaction.js.map +1 -1
- package/dist/types.d.ts +29 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/lib/darwin-arm64/liblattice.dylib +0 -0
- package/lib/darwin-x64/liblattice.dylib +0 -0
- package/lib/linux-arm64/liblattice.so +0 -0
- package/lib/linux-x64/liblattice.so +0 -0
- package/lib/win32-arm64/lattice.dll +0 -0
- package/lib/win32-x64/lattice.dll +0 -0
- package/package.json +1 -1
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 !==
|
|
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
|
|
73
|
-
return
|
|
74
|
-
case
|
|
75
|
-
return
|
|
76
|
-
case
|
|
77
|
-
return
|
|
78
|
-
case
|
|
79
|
-
return
|
|
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
|
|
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 ===
|
|
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 !==
|
|
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',
|
|
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',
|
|
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',
|
|
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 ??
|
|
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.
|
|
161
|
-
? this.bindings.
|
|
162
|
-
: this.bindings.
|
|
163
|
-
? this.bindings.
|
|
164
|
-
: this.bindings.
|
|
165
|
-
? this.bindings.
|
|
166
|
-
: this.bindings.
|
|
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',
|
|
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
|
-
|
|
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
|
-
|
|
203
|
-
|
|
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
|
|
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 ??
|
|
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
|
-
|
|
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.`,
|
|
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
|
-
|
|
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
|
-
|
|
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}`,
|
|
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
|
-
|
|
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}`,
|
|
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 ===
|
|
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
|
|
1438
|
+
edgeType,
|
|
1117
1439
|
};
|
|
1118
1440
|
}
|
|
1119
1441
|
/**
|