chloedb 0.0.1 → 0.3.5

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/index.js CHANGED
@@ -1,4 +1,594 @@
1
- throw new Error(
2
- "chloedb 0.0.1 is a placeholder that holds the name for Strata (https://github.com/chloetech-ai/strata). " +
3
- "Install a release from GitHub instead; see https://github.com/chloetech-ai/strata/blob/main/docs/chloedb/javascript.md"
4
- );
1
+ // ChloeDB from JavaScript: the database in this process.
2
+ //
3
+ // `Database` opens a ChloeDB file (or a directory of segment files) in this
4
+ // process, with no server, as a SQLite library opens a SQLite file: Node,
5
+ // Bun and Deno load the native addon (chloedb.node) that runs it. `Client`
6
+ // (client.js) talks to a running chloedb-server over HTTP instead, from any
7
+ // JavaScript runtime with fetch. Both answer queries with the same
8
+ // `Result` and write rows the same way, so code can move from one to the
9
+ // other:
10
+ //
11
+ // import { open } from "chloedb";
12
+ //
13
+ // const db = await open("books.chloedb", { schema: {
14
+ // table: "books", key: "id",
15
+ // fields: [
16
+ // { name: "id", type: "keyword" },
17
+ // { name: "title", type: "text" },
18
+ // { name: "year", type: "int" },
19
+ // ],
20
+ // } });
21
+ // await db.upsert([{ id: "b1", title: "The river and the dragon", year: 1999 }]);
22
+ // for (const row of await db.search("dragon")) console.log(row.id, row.title);
23
+ // (await db.query("SELECT year, COUNT(*) FROM books GROUP BY year")).rows;
24
+ // await db.close();
25
+ //
26
+ // Every call runs on a worker thread and answers a promise: queries and
27
+ // writes leave the event loop free, and many run at once.
28
+
29
+ import { Buffer } from "node:buffer";
30
+ import { createRequire } from "node:module";
31
+ import { existsSync, readFileSync } from "node:fs";
32
+ import { dirname, join } from "node:path";
33
+ import process from "node:process";
34
+ import { fileURLToPath } from "node:url";
35
+
36
+ import { Nearby } from "./nearby.js";
37
+ import { ChloeDBError, Result, Searchable, decode, encode, given, makeError, orderedSchema, pickTable, resultOrWritten } from "./common.js";
38
+
39
+ export { ChloeDBError, StrataError, Result, errorCode, BadRequestError, UnauthorizedError, NotFoundError, ConflictError, PartialWriteError, BusyError, OverloadedError, DeadlineError, UnavailableError } from "./common.js";
40
+ export { Client, Session, connect } from "./client.js";
41
+ export { Nearby, NearbyResult } from "./nearby.js";
42
+
43
+ const here = dirname(fileURLToPath(import.meta.url));
44
+
45
+ /** This machine as the platform packages are named: linux-x64-gnu,
46
+ * darwin-arm64 (scripts/pack.mjs). */
47
+ function platformName() {
48
+ if (process.platform !== "linux") return `${process.platform}-${process.arch}`;
49
+ let glibc = false;
50
+ try {
51
+ glibc = Boolean(process.report?.getReport?.()?.header?.glibcVersionRuntime);
52
+ } catch {
53
+ glibc = false;
54
+ }
55
+ return `linux-${process.arch}-${glibc ? "gnu" : "musl"}`;
56
+ }
57
+
58
+ /** The native addon: `$CHLOEDB_NODE_ADDON` (or `$STRATA_NODE_ADDON`), else
59
+ * chloedb.node beside this file (`npm run build` makes it, and a release's
60
+ * tarball has it), else the one of this platform's package,
61
+ * `@chloedb/<platform>`, which `npm install chloedb` from npm's registry
62
+ * installs beside it. */
63
+ function load() {
64
+ const require = createRequire(import.meta.url);
65
+ const given = process.env.CHLOEDB_NODE_ADDON || process.env.STRATA_NODE_ADDON;
66
+ const beside = join(here, "chloedb.node");
67
+ if (given || existsSync(beside)) {
68
+ const path = given || beside;
69
+ if (!existsSync(path)) throw new ChloeDBError(`the ChloeDB addon ${path} is missing`);
70
+ return require(path);
71
+ }
72
+ const platform = platformName();
73
+ let found;
74
+ try {
75
+ found = require.resolve(`@chloedb/${platform}/chloedb.node`);
76
+ } catch {
77
+ throw new ChloeDBError(
78
+ `the ChloeDB addon is not installed: no ${beside}, and no package @chloedb/${platform} ` +
79
+ `(npm installs the one of a platform with a prebuilt addon: linux-x64-gnu, linux-arm64-gnu, darwin-arm64, darwin-x64; ` +
80
+ `elsewhere, run \`npm run build\` in chloedb-js, which needs Rust and a C compiler). chloedb/client works without it.`,
81
+ );
82
+ }
83
+ return require(found);
84
+ }
85
+
86
+ const native = load();
87
+
88
+ /** A native error (a failed call) as a ChloeDBError. */
89
+ function failed(e) {
90
+ if (e instanceof ChloeDBError) return e;
91
+ return makeError(e?.message ?? String(e), { cause: e });
92
+ }
93
+
94
+ async function callStatic(op, args) {
95
+ try {
96
+ return decode(await native.callStatic(op, encode(given(args))));
97
+ } catch (e) {
98
+ throw failed(e);
99
+ }
100
+ }
101
+
102
+ async function opened(op, args, limits = {}) {
103
+ let db;
104
+ try {
105
+ db = new Database(await native.NativeDatabase.open(op, encode(given(args))));
106
+ } catch (e) {
107
+ throw failed(e);
108
+ }
109
+ if (limits.timeoutMs != null || limits.memory != null) db.setLimits(limits);
110
+ return db;
111
+ }
112
+
113
+ /** A query's `timeoutMs` and `memory` as the native call takes them. */
114
+ function limitArgs({ timeoutMs, memory } = {}) {
115
+ for (const [k, v] of [["timeoutMs", timeoutMs], ["memory", memory]]) {
116
+ if (v != null && !(Number.isInteger(v) && v >= 0)) throw new RangeError(`${k} is a whole number, at least 0`);
117
+ }
118
+ return { timeout_ms: timeoutMs ?? undefined, memory: memory ?? undefined };
119
+ }
120
+
121
+ /** A schema given as an object, JSON text or the path of a JSON file, as
122
+ * JSON text. */
123
+ function schemaJson(schema) {
124
+ if (schema == null) return undefined;
125
+ if (typeof schema === "object") return encode(schema);
126
+ const text = String(schema);
127
+ if (/^\s*[{[]/.test(text)) return text;
128
+ return readFileSync(text, "utf8");
129
+ }
130
+
131
+ function paths(p) {
132
+ return p instanceof URL ? fileURLToPath(p) : p == null ? p : String(p);
133
+ }
134
+
135
+ function names(tables) {
136
+ return tables == null ? undefined : typeof tables === "string" ? [tables] : [...tables];
137
+ }
138
+
139
+ function isRow(o) {
140
+ return o !== null && typeof o === "object" && !Array.isArray(o) && !(Symbol.iterator in o);
141
+ }
142
+
143
+ /** Rows to write as `{rows, places, vectors}`: the rows without their
144
+ * Float32Array and Float64Array values, which travel apart, read from
145
+ * their bytes, each placed by [row, field]. */
146
+ function splitVectors(rows) {
147
+ const list = isRow(rows) ? [rows] : Array.isArray(rows) ? rows : [...rows];
148
+ let places;
149
+ let vectors;
150
+ const out = list.map((r, i) => {
151
+ if (!isRow(r)) return r;
152
+ let copy;
153
+ for (const k of Object.keys(r)) {
154
+ const v = r[k];
155
+ if (v instanceof Float32Array || v instanceof Float64Array) {
156
+ copy ??= { ...r };
157
+ delete copy[k];
158
+ (places ??= []).push([i, k]);
159
+ (vectors ??= []).push(v instanceof Float32Array ? v : Float32Array.from(v));
160
+ }
161
+ }
162
+ return copy ?? r;
163
+ });
164
+ return { rows: out, places, vectors };
165
+ }
166
+
167
+ function base64(bytes) {
168
+ if (bytes == null) return undefined;
169
+ if (typeof bytes === "string") return bytes;
170
+ const u8 = bytes instanceof Uint8Array ? bytes : ArrayBuffer.isView(bytes) ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength) : new Uint8Array(bytes);
171
+ return Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength).toString("base64");
172
+ }
173
+
174
+ /**
175
+ * A ChloeDB database opened in this process.
176
+ *
177
+ * Create one with `Database.create` (or `open` with a schema), open an
178
+ * existing one with `Database.open`. Only one process may have a database
179
+ * open: to share one, serve it with chloedb-server and use `Client`.
180
+ */
181
+ export class Database extends Searchable {
182
+ #n;
183
+ #tag = 0;
184
+
185
+ /** @internal Use `Database.create`, `Database.open` or `open`. */
186
+ constructor(nativeDb) {
187
+ super();
188
+ this.#n = nativeDb;
189
+ /** What the import that made it, or the last import into it, did
190
+ * (`fromSqlite`, `importSqlite`, `fromParquet`, `importParquet`). */
191
+ this.lastImport = nativeDb.lastImport == null ? null : decode(nativeDb.lastImport);
192
+ }
193
+
194
+ /**
195
+ * Creates a database at `path` with `schema` (an object, JSON text, or
196
+ * the path of a JSON file; the short form or the long one). `directory`
197
+ * keeps it as a directory of segment files instead of one file. `models`
198
+ * is where embedded fields' models are (default $CHLOEDB_MODELS or
199
+ * ~/.local/share/chloedb/models). `threads` is how many cores vector
200
+ * indexes build on and each query searches segments on (default: every
201
+ * core). `timeoutMs` and `memory` limit its queries (see `setLimits`).
202
+ */
203
+ static create(path, schema, { directory = false, models, threads, timeoutMs, memory } = {}) {
204
+ return opened("create", { path: paths(path), schema: schemaJson(schema), directory, models: paths(models), threads }, { timeoutMs, memory });
205
+ }
206
+
207
+ /** Opens the database at `path`; `models`, `threads`, `timeoutMs` and
208
+ * `memory` as `create` takes them. `readOnly` opens it to read while
209
+ * another process writes it. */
210
+ static open(path, { models, threads, readOnly = false, timeoutMs, memory } = {}) {
211
+ return opened("open", { path: paths(path), models: paths(models), threads, read_only: readOnly }, { timeoutMs, memory });
212
+ }
213
+
214
+ /**
215
+ * Limits every query of this database from now on, unless a query gives
216
+ * its own (`query(sql, params, { timeoutMs, memory })`): a deadline of
217
+ * `timeoutMs` milliseconds (none or 0: none, the default), past which a
218
+ * query stops and rejects with DeadlineError; and a memory budget of
219
+ * `memory` bytes that its queries share (0: none; none, the default: the
220
+ * budget every database of the process shares, a quarter of the
221
+ * machine's memory or $CHLOEDB_QUERY_MEMORY_MB MiB), past which a query
222
+ * stops and rejects with a ChloeDBError of code "memory".
223
+ */
224
+ setLimits({ timeoutMs, memory } = {}) {
225
+ const a = limitArgs({ timeoutMs, memory });
226
+ this.#n.setLimits(a.timeout_ms, a.memory);
227
+ }
228
+
229
+ /** The deadline every query gets unless it gives its own, in ms (null:
230
+ * none). */
231
+ get timeoutMs() {
232
+ return this.#n.timeoutMs ?? null;
233
+ }
234
+
235
+ /** The memory budget its queries share, in bytes (null: none). */
236
+ get memory() {
237
+ return this.#n.memory ?? null;
238
+ }
239
+
240
+ /** Stops the queries of this database running now: each rejects with
241
+ * DeadlineError within a few thousand rows. Returns how many there
242
+ * were; queries that start after it run. */
243
+ interrupt() {
244
+ return this.#n.interrupt();
245
+ }
246
+
247
+ /** A query's call: `timeoutMs` and `memory`, and `signal` (an
248
+ * AbortSignal) to stop it. */
249
+ async #query(op, args, { timeoutMs, memory, signal } = {}) {
250
+ const a = { ...args, ...limitArgs({ timeoutMs, memory }) };
251
+ if (signal == null) return this.#call(op, a);
252
+ signal.throwIfAborted();
253
+ const tag = ++this.#tag;
254
+ const stop = () => this.#n.interrupt(tag);
255
+ signal.addEventListener("abort", stop, { once: true });
256
+ try {
257
+ return await this.#call(op, { ...a, tag });
258
+ } catch (e) {
259
+ // Stopped by its signal: rejected with the signal's reason, as an
260
+ // aborted fetch is.
261
+ if (signal.aborted && e?.code === "timeout") throw signal.reason;
262
+ throw e;
263
+ } finally {
264
+ signal.removeEventListener("abort", stop);
265
+ }
266
+ }
267
+
268
+ /** @internal Queries run in this process (`search` takes `memory`). */
269
+ get _local() {
270
+ return true;
271
+ }
272
+
273
+ async #call(op, args = {}, vectors) {
274
+ try {
275
+ return decode(await this.#n.call(op, encode(given(args)), vectors));
276
+ } catch (e) {
277
+ throw failed(e);
278
+ }
279
+ }
280
+
281
+ /** The first table's schema, or `table`'s, in its short form: {table,
282
+ * key, fields}. */
283
+ async schema(table) {
284
+ return orderedSchema(await this.#call("schema", { table }));
285
+ }
286
+
287
+ /** Every table's schema in its short form, the first first. */
288
+ async tables() {
289
+ return (await this.#call("tables")).map(orderedSchema);
290
+ }
291
+
292
+ /** Live rows, in every table. */
293
+ async count() {
294
+ return this.#call("count");
295
+ }
296
+
297
+ /**
298
+ * Adds a column to the first table or `table`, as `ALTER TABLE ... ADD
299
+ * COLUMN` does: `options` are the field's, in the short form of a schema
300
+ * (`default`, `not_null`, `indexed`, `embed` and `model`, ...).
301
+ */
302
+ async addColumn(name, type, { table, ...options } = {}) {
303
+ await this.#call("alter", { alters: [{ add: { name, type, ...options } }], table });
304
+ }
305
+
306
+ /** Drops a column of the first table or `table`, with its values. */
307
+ async dropColumn(name, { table } = {}) {
308
+ await this.#call("alter", { alters: [{ drop: name }], table });
309
+ }
310
+
311
+ /** Renames a column of the first table or `table`, keeping its values. */
312
+ async renameColumn(from, to, { table } = {}) {
313
+ await this.#call("alter", { alters: [{ rename: [from, to] }], table });
314
+ }
315
+
316
+ /** Embedded fields whose model did not open, with the reason: rows
317
+ * written here must bring those fields' vectors. */
318
+ get embedErrors() {
319
+ return JSON.parse(this.#n.embedErrors);
320
+ }
321
+
322
+ /** @internal The embedded vector fields of `table` whose model is open. */
323
+ async _embedded(table) {
324
+ const broken = this.embedErrors;
325
+ const s = await this.schema(table);
326
+ return s.fields.filter((f) => f.embed && !(f.name in broken)).map((f) => f.name);
327
+ }
328
+
329
+ /** Runs a SELECT. `params` binds its `:name` placeholders.
330
+ * `timeoutMs` is its deadline, as a `Client`'s query takes it: past it
331
+ * the query stops and rejects with DeadlineError (none or 0: the
332
+ * database's, see `setLimits`). `memory` is a budget of its own in bytes,
333
+ * past which it rejects with a ChloeDBError of code "memory" (0: none;
334
+ * none: the database's). `signal`, an AbortSignal, stops it when it
335
+ * aborts: it rejects with the signal's reason, as an aborted fetch
336
+ * does. */
337
+ async query(sql, params, { timeoutMs, memory, signal } = {}) {
338
+ return new Result(await this.#query("query", { sql, params }, { timeoutMs, memory, signal }));
339
+ }
340
+
341
+ /** Runs any statement: a SELECT's `Result`, or the number of rows an
342
+ * INSERT, UPDATE or DELETE wrote. `timeoutMs`, `memory` and `signal`
343
+ * limit a SELECT as `query` takes them; a write is not cut short. */
344
+ async sql(sql, params, { timeoutMs, memory, signal } = {}) {
345
+ return resultOrWritten(await this.#query("sql", { sql, params }, { timeoutMs, memory, signal }));
346
+ }
347
+
348
+ /** @internal */
349
+ async _queryLogged(sql, params, log) {
350
+ return new Result(await this.#call("query_logged", { sql, params, log }));
351
+ }
352
+
353
+ /** @internal */
354
+ async _exportRankLog(opts) {
355
+ return this.#call("export_rank_log", { export: opts });
356
+ }
357
+
358
+ /** The plan of a SELECT, INSERT, UPDATE or DELETE, without running it:
359
+ * the plan IR as JSON, which `run` takes. */
360
+ async plan(sql, params) {
361
+ return this.#call("plan", { sql, params });
362
+ }
363
+
364
+ /** Runs a plan (as `plan` or a server's /v1/explain gives it): a read's
365
+ * `Result`, or the number of rows a write wrote; a read limited by
366
+ * `timeoutMs`, `memory` and `signal` as `query` takes them. */
367
+ async run(plan, { timeoutMs, memory, signal } = {}) {
368
+ return resultOrWritten(await this.#query("run", { plan }, { timeoutMs, memory, signal }));
369
+ }
370
+
371
+ /** Inserts a row or rows, whose keys must be new, into the first table or
372
+ * `table`; all or none are written. Returns how many. A vector may be a
373
+ * Float32Array (read from its bytes), a Float64Array or an array. */
374
+ async insert(rows, { table } = {}) {
375
+ const { rows: r, places, vectors } = splitVectors(rows);
376
+ return this.#call("insert", { rows: r, table, vectors: places }, vectors);
377
+ }
378
+
379
+ /** Inserts a row or rows, replacing the rows that have their keys, in
380
+ * transactions of 10,000 rows. Returns how many. */
381
+ async upsert(rows, { table } = {}) {
382
+ const { rows: r, places, vectors } = splitVectors(rows);
383
+ return this.#call("upsert", { rows: r, table, vectors: places }, vectors);
384
+ }
385
+
386
+ /** The row with this primary key in the first table or `table`, read
387
+ * without SQL: an object of the columns `SELECT *` answers, or null when
388
+ * no live row has the key (or its `expire_by` time has passed). */
389
+ async get(key, { table } = {}) {
390
+ return (await this.#call("get_many", { keys: [key], table }))[0];
391
+ }
392
+
393
+ /** `get` of several keys at once, in their order. */
394
+ async getMany(keys, { table } = {}) {
395
+ return this.#call("get_many", { keys: [...keys], table });
396
+ }
397
+
398
+ /** Deletes the rows with this key or these keys; returns how many there
399
+ * were. */
400
+ async delete(keys, { table } = {}) {
401
+ const list = typeof keys === "string" || typeof keys === "number" || typeof keys === "bigint" ? [keys] : [...keys];
402
+ return this.#call("delete", { keys: list, table });
403
+ }
404
+
405
+ /** Deletes the rows whose `expire_by` time has passed, in every table with
406
+ * one; returns how many. Reads leave them out already. */
407
+ async expire() {
408
+ return this.#call("expire");
409
+ }
410
+
411
+ /** Write operations as `Client.write` and /v1/write take them ({op:
412
+ * "insert", doc: {...}}, {op: "add", key, field: "n", value: 1}, ...),
413
+ * in one transaction. Returns the rows written. */
414
+ async write(ops) {
415
+ return this.#call("write", { ops: [...ops] });
416
+ }
417
+
418
+ /** Loads a JSON Lines, JSON (an array), CSV or TSV file, in `format` or
419
+ * the one its extension names, into the first table or `table`. Into an
420
+ * empty table the rows are bulk-loaded in one commit; otherwise they are
421
+ * upserted. Returns {rows, bulk, skippedFields}: the columns the schema
422
+ * lacks. */
423
+ async importFile(path, { format, table } = {}) {
424
+ const r = await this.#call("import_file", { path: paths(path), format, table });
425
+ return { rows: r.rows, bulk: r.bulk, skippedFields: r.skipped_fields };
426
+ }
427
+
428
+ /** Imports the tables of a SQLite database file (all, or `tables`), each
429
+ * into the table of its name, created from the SQLite table or from the
430
+ * schema `schemas` gives for it (see `planSqlite`). Returns {tables,
431
+ * skipped}. */
432
+ async importSqlite(path, { tables, schemas, blobsBase64 = false } = {}) {
433
+ this.lastImport = await this.#call("import_sqlite", { path: paths(path), tables: names(tables), schemas: schemas == null ? undefined : schemaJson(schemas), blobs_base64: blobsBase64 });
434
+ return this.lastImport;
435
+ }
436
+
437
+ /** Writes the tables (all, or `tables`) to a new SQLite file, from one
438
+ * snapshot, with B-tree `indexes`, an FTS5 index over the text (`fts`)
439
+ * and the ChloeDB `schemas`, which an import restores. Returns {tables}. */
440
+ async exportSqlite(path, { tables, fts = true, indexes = true, schemas = true } = {}) {
441
+ return this.#call("export_sqlite", { path: paths(path), tables: names(tables), fts, indexes, schemas });
442
+ }
443
+
444
+ /** Imports a Parquet file or a directory of them (Spark's, DuckDB's), or
445
+ * an `s3://` URL, into one table (see chloedb-py's `import_parquet`).
446
+ * Returns {table, rows, files, created, bulk, skipped, notes}. */
447
+ async importParquet(path, { table, schema, key, blobsBase64 = false } = {}) {
448
+ this.lastImport = await this.#call("import_parquet", { path: paths(path), table, schema: schemaJson(schema), key, blobs_base64: blobsBase64 });
449
+ return this.lastImport;
450
+ }
451
+
452
+ /** What `importParquet` would make of a Parquet file or directory into
453
+ * this database, without writing. */
454
+ async planParquet(path, { table, schema, key, blobsBase64 = false } = {}) {
455
+ return this.#call("plan_parquet", { parquet_path: paths(path), table, schema: schemaJson(schema), key, blobs_base64: blobsBase64 });
456
+ }
457
+
458
+ /** Writes the tables (all, or `tables`) to Parquet, from one snapshot: to
459
+ * the file `path` when it ends in .parquet (one table), else to a new
460
+ * directory of `<table>.parquet` files; `path` may be an `s3://` URL.
461
+ * Returns {tables: [{table, file, rows, bytes, notes}]}. */
462
+ async exportParquet(path, { tables, schemas = true } = {}) {
463
+ return this.#call("export_parquet", { path: paths(path), tables: names(tables), schemas });
464
+ }
465
+
466
+ /** The query vector of `text` by an embedded field's model (of the first
467
+ * table, or of `table`), or of `image` or `audio`, the bytes of an image
468
+ * or sound file (a Uint8Array), by a model of that. */
469
+ async embed(text, { field, table, image, audio } = {}) {
470
+ return this.#call("embed", { text, field, table, image: base64(image), audio: base64(audio) });
471
+ }
472
+
473
+ /** The vectors of `text`'s tokens as a query, by the model of
474
+ * multi-vector field `field` (a ColBERT model), as `maxsim` takes them. */
475
+ async embedTokens(text, field, { table } = {}) {
476
+ return this.#call("embed_tokens", { text, field, table });
477
+ }
478
+
479
+ /** The codes that can follow each prefix of semantic-ID field `field`
480
+ * ("" for the first number) among the rows SQL condition `where`
481
+ * matches, or all rows: {prefix: {code: rows}}. */
482
+ async sidNext(prefixes, { field, where, params, table } = {}) {
483
+ const got = await this.#call("sid_next", { prefixes: [...prefixes], field, where, params, table });
484
+ return Object.fromEntries(Object.entries(got).map(([p, cs]) => [p, Object.fromEntries(cs)]));
485
+ }
486
+
487
+ /** Trains a semantic-ID codebook on the vectors of `field` of the first
488
+ * table or `table`, saves it as `name` under `models`, and returns its
489
+ * SHA-256. */
490
+ async trainCodebook(field, name, { table, models, levels, k, iterations, sample, seed, balanced } = {}) {
491
+ return this.#call("train_codebook", { field, name, table, models: paths(models), levels, k, iterations, sample, seed, balanced });
492
+ }
493
+
494
+ /** Readies a table that is done changing for queries: writes the rows
495
+ * still in memory into segments, merges its segments into as few as it
496
+ * can (one, up to 2,000,000 rows; a query visits each), drops deleted
497
+ * rows, and returns the space this frees to the file system. */
498
+ async optimize() {
499
+ await this.#call("optimize");
500
+ }
501
+
502
+ /** Returns the space merges freed to the file system (they reuse it
503
+ * otherwise): the number of bytes the file shrank by. */
504
+ async vacuum() {
505
+ return this.#call("vacuum");
506
+ }
507
+
508
+ /** Opened `readOnly`: reads what the writer committed since the last
509
+ * query, now (each query does so by itself); whether anything changed.
510
+ * False for the writer. */
511
+ async refresh() {
512
+ return this.#call("refresh");
513
+ }
514
+
515
+ /** Merges small segments, returns the space merges freed to the file
516
+ * system when it is an eighth of the file or more, and closes the
517
+ * database. Calls after it fail. */
518
+ async close() {
519
+ await this.#call("close");
520
+ }
521
+
522
+ get closed() {
523
+ return this.#n.closed;
524
+ }
525
+
526
+ async [Symbol.asyncDispose]() {
527
+ await this.close();
528
+ }
529
+ }
530
+
531
+ /**
532
+ * Opens the database at `path`, creating it with `schema` if it does not
533
+ * exist; `directory`, `models` and `threads` as `Database.create` takes
534
+ * them.
535
+ */
536
+ export async function open(path, { schema, directory = false, models, threads, readOnly = false, timeoutMs, memory } = {}) {
537
+ if (existsSync(paths(path)) || readOnly) return Database.open(path, { models, threads, readOnly, timeoutMs, memory });
538
+ if (schema == null) throw new ChloeDBError(`${paths(path)} does not exist: pass a schema to create it`);
539
+ return Database.create(path, schema, { directory, models, threads, timeoutMs, memory });
540
+ }
541
+
542
+ /** Creates a database at `path` from the tables of a SQLite database file
543
+ * (all, or `tables`), with schemas made from the SQLite tables or given in
544
+ * `schemas` (see `planSqlite`). What the import did is its `lastImport`. */
545
+ export function fromSqlite(sqlitePath, path, { tables, schemas, blobsBase64 = false, directory = false, models, threads } = {}) {
546
+ return opened("from_sqlite", { sqlite_path: paths(sqlitePath), path: paths(path), tables: names(tables), schemas: schemas == null ? undefined : schemaJson(schemas), blobs_base64: blobsBase64, directory, models: paths(models), threads });
547
+ }
548
+
549
+ /** What `fromSqlite` would make of a SQLite file, without writing: {tables,
550
+ * skipped}, each table the schema of the ChloeDB table it becomes. Edit the
551
+ * plan and pass it to `fromSqlite` as `schemas`. */
552
+ export function planSqlite(sqlitePath, { tables, schemas, blobsBase64 = false } = {}) {
553
+ return callStatic("plan_sqlite", { sqlite_path: paths(sqlitePath), tables: names(tables), schemas: schemas == null ? undefined : schemaJson(schemas), blobs_base64: blobsBase64 });
554
+ }
555
+
556
+ /** Creates a database at `path` from a Parquet file or directory (or an
557
+ * `s3://` URL), its one table made from the columns, kept by an export, or
558
+ * given as `schema` (see `planParquet`). What the import did is its
559
+ * `lastImport`. */
560
+ export function fromParquet(parquetPath, path, { table, schema, key, blobsBase64 = false, directory = false, models, threads } = {}) {
561
+ return opened("from_parquet", { parquet_path: paths(parquetPath), path: paths(path), table, schema: schemaJson(schema), key, blobs_base64: blobsBase64, directory, models: paths(models), threads });
562
+ }
563
+
564
+ /** What `fromParquet` would make of a Parquet file or directory, without
565
+ * writing: the table's schema, the files and rows, the columns read and
566
+ * what is skipped. Edit it and pass it back as `schema`. */
567
+ export function planParquet(parquetPath, { table, schema, key, blobsBase64 = false } = {}) {
568
+ return callStatic("plan_parquet", { parquet_path: paths(parquetPath), table, schema: schemaJson(schema), key, blobs_base64: blobsBase64 });
569
+ }
570
+
571
+ /** Copies the database at `path`, written by a version of ChloeDB from
572
+ * before field ids, into this version's format in its place, keeping the
573
+ * old one as `<path>.before-field-ids`. Returns null when it needs no
574
+ * upgrade, else {old, tables, rows}. */
575
+ export function upgrade(path) {
576
+ return callStatic("upgrade", { path: paths(path) });
577
+ }
578
+
579
+ /** Trains a semantic-ID codebook on `vectors` (arrays or Float32Arrays),
580
+ * saves it as `name` under `models`, and returns its SHA-256. */
581
+ export function trainCodebook(vectors, name, { models, levels, k, iterations, sample, seed, balanced } = {}) {
582
+ return callStatic("train_codebook", { vectors: [...vectors], name, models: paths(models), levels, k, iterations, sample, seed, balanced });
583
+ }
584
+
585
+ /** The addon's version. */
586
+ /** A device's slice of `table` on the chloedb-server at `url`, kept in
587
+ * directory `dir`: its manifest fetched and its database opened (see
588
+ * nearby.js). Searches near the user answer on the device when they can
589
+ * prove the answer is the server's, else ask the server. */
590
+ export function openNearby(url, table, dir, options = {}) {
591
+ return new Nearby(native, url, table, dir, options).load();
592
+ }
593
+
594
+ export const version = native.version();