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/client.js ADDED
@@ -0,0 +1,619 @@
1
+ // A client of a running chloedb-server, over its HTTP JSON API, with the
2
+ // same methods as `Database` (index.js) where the server offers them.
3
+ //
4
+ // It needs only `fetch`, so it runs in Node 18 and later, Bun, Deno,
5
+ // browsers and edge workers, with no native code: `import { connect } from
6
+ // "chloedb/client"`. In a browser, the server answers pages of its own
7
+ // origin (a page it serves, or one behind the same reverse proxy): it
8
+ // sends no CORS headers, and refuses writes from other origins.
9
+
10
+ import { ChloeDBError, Result, Searchable, decode, encode, given, makeError, orderedSchema } from "./common.js";
11
+
12
+ export { ChloeDBError, StrataError, Result, errorCode, BadRequestError, UnauthorizedError, NotFoundError, ConflictError, PartialWriteError, BusyError, OverloadedError, DeadlineError, UnavailableError } from "./common.js";
13
+
14
+ /** A write's answer as `writeResult` gives it: {written, seqNo?, seqNos?,
15
+ * skipped?}. */
16
+ function written(a) {
17
+ const out = { written: Number(a?.written ?? 0) };
18
+ if (a?.seq_no != null) out.seqNo = Number(a.seq_no);
19
+ if (Array.isArray(a?.seq_nos)) out.seqNos = a.seq_nos.map(Number);
20
+ if (a?.skipped != null) out.skipped = Number(a.skipped);
21
+ return out;
22
+ }
23
+
24
+ function later(a, b) {
25
+ return a == null ? b : b == null ? a : Math.max(a, b);
26
+ }
27
+
28
+ /** Per shard, the later of two lists of sequence numbers. */
29
+ function laterEach(a, b) {
30
+ if (a == null || b == null) return a ?? b ?? undefined;
31
+ return Array.from({ length: Math.max(a.length, b.length) }, (_, i) => Math.max(a[i] ?? 0, b[i] ?? 0));
32
+ }
33
+
34
+ /** A read's `min_seq_no` and `min_seq_nos` as the server takes them; 0s
35
+ * ask for nothing and are left out. */
36
+ function afterBody(minSeqNo, minSeqNos) {
37
+ const out = {};
38
+ if (minSeqNo) out.min_seq_no = Number(minSeqNo);
39
+ if (minSeqNos && [...minSeqNos].some(Boolean)) out.min_seq_nos = [...minSeqNos].map(Number);
40
+ return out;
41
+ }
42
+
43
+ /** Whether a statement is a read (SELECT, WITH, EXPLAIN, ...), by its
44
+ * first word: a server refuses `min_seq_no` on a write. */
45
+ function reads(sql) {
46
+ const m = /^(?:\s|\(|--[^\n]*|\/\*[\s\S]*?\*\/)*([A-Za-z]+)/.exec(String(sql));
47
+ return Boolean(m) && ["select", "with", "explain", "values", "show", "describe"].includes(m[1].toLowerCase());
48
+ }
49
+
50
+ /** Rows a write request carries. */
51
+ export const WRITE_BATCH = 1000;
52
+ /** Keys a read by key sends in one request (the server takes 10,000). */
53
+ export const GET_BATCH = 10_000;
54
+
55
+ const FORMATS = { ".jsonl": "jsonl", ".ndjson": "jsonl", ".json": "json", ".csv": "csv", ".tsv": "tsv", ".tab": "tsv", ".sqlite": "sqlite", ".db": "sqlite", ".parquet": "parquet" };
56
+ // The content type an import is sent with: a server refuses text/plain.
57
+ const CONTENT_TYPES = {
58
+ jsonl: "application/x-ndjson",
59
+ json: "application/json",
60
+ csv: "text/csv",
61
+ tsv: "text/tab-separated-values",
62
+ sqlite: "application/vnd.sqlite3",
63
+ parquet: "application/vnd.apache.parquet",
64
+ };
65
+
66
+ function env(name) {
67
+ try {
68
+ return globalThis.process?.env?.[name] ?? globalThis.Deno?.env?.get(name);
69
+ } catch {
70
+ return undefined; // Deno without --allow-env
71
+ }
72
+ }
73
+
74
+ // node:fs, loaded only when a path is given: a page never needs it.
75
+ let fsp;
76
+ async function fs() {
77
+ const name = "node:fs/promises";
78
+ return (fsp ??= await import(/* @vite-ignore */ /* webpackIgnore: true */ name));
79
+ }
80
+
81
+ function extension(path) {
82
+ const m = /\.[^./\\]+$/.exec(String(path));
83
+ return m ? m[0].toLowerCase() : "";
84
+ }
85
+
86
+ /** A file's bytes: a path (read with node:fs), or the bytes themselves
87
+ * (a Uint8Array, an ArrayBuffer, a Blob). */
88
+ async function bytesOf(data) {
89
+ if (typeof data === "string" || data instanceof URL) return (await fs()).readFile(data);
90
+ if (data instanceof Uint8Array || data instanceof ArrayBuffer) return data;
91
+ if (ArrayBuffer.isView(data)) return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
92
+ if (typeof Blob !== "undefined" && data instanceof Blob) return data;
93
+ throw new ChloeDBError("a file is a path, a Uint8Array, an ArrayBuffer or a Blob");
94
+ }
95
+
96
+ /** Writes `bytes` to `path`, which must not exist. */
97
+ async function writeNew(path, bytes) {
98
+ const f = await fs();
99
+ const part = `${path}.part`;
100
+ try {
101
+ await f.writeFile(part, bytes, { flag: "wx" });
102
+ try {
103
+ await f.access(path);
104
+ throw new ChloeDBError(`${path} exists`);
105
+ } catch (e) {
106
+ if (e instanceof ChloeDBError) throw e;
107
+ }
108
+ await f.rename(part, path);
109
+ } finally {
110
+ await f.rm(part, { force: true });
111
+ }
112
+ }
113
+
114
+ function query(o) {
115
+ const q = new URLSearchParams();
116
+ for (const [k, v] of Object.entries(o)) {
117
+ if (v === undefined || v === null) continue;
118
+ q.set(k, typeof v === "boolean" ? String(v) : Array.isArray(v) ? v.join(",") : String(v));
119
+ }
120
+ const s = q.toString();
121
+ return s ? `?${s}` : "";
122
+ }
123
+
124
+ function names(tables) {
125
+ return tables == null ? undefined : typeof tables === "string" ? tables : [...tables].join(",");
126
+ }
127
+
128
+ function rowsOf(rows) {
129
+ return rows !== null && typeof rows === "object" && !Array.isArray(rows) && !(Symbol.iterator in rows) ? [rows] : [...rows];
130
+ }
131
+
132
+ /** The milliseconds a 429's `Retry-After` says to wait (a second when it
133
+ * says none), at most 10 s. */
134
+ function retryAfter(v) {
135
+ const s = Number(v ?? 1);
136
+ return Number.isFinite(s) ? Math.min(Math.max(s, 0), 10) * 1000 : 1000;
137
+ }
138
+
139
+ /**
140
+ * A chloedb-server at `url` ("http://host:7700"). `token` is the server's
141
+ * --token or an API key, if it needs one ($CHLOEDB_TOKEN, or $STRATA_TOKEN, by default).
142
+ * Errors the server reports reject with `ChloeDBError` (its `status` and
143
+ * `answer` set); one it cannot be reached rejects with fetch's error.
144
+ *
145
+ * A request the server refuses for its load (429: behind on flushing its
146
+ * writes, its write queue full, too many queries running) did nothing, and
147
+ * is sent again after the `Retry-After` it gives, for up to `retryFor`
148
+ * milliseconds (0: never). A write that failed partway is not, unless it
149
+ * has an idempotency key.
150
+ */
151
+ export class Client extends Searchable {
152
+ #schema;
153
+
154
+ constructor(url = "http://127.0.0.1:7700", { token, timeout = 30_000, retryFor = 10_000, fetch: f } = {}) {
155
+ super();
156
+ this.url = String(url).replace(/\/+$/, "");
157
+ this.token = token ?? env("CHLOEDB_TOKEN") ?? env("STRATA_TOKEN");
158
+ /** Milliseconds a request may take (0 for no limit). */
159
+ this.timeout = timeout;
160
+ /** Milliseconds a request refused with 429 is sent again for. */
161
+ this.retryFor = retryFor;
162
+ this.fetch = f ?? globalThis.fetch.bind(globalThis);
163
+ }
164
+
165
+ /** The answer of a request: its JSON, or with `as` "text" its text, or
166
+ * "response" the Response itself. */
167
+ async _call(method, path, body, { data, headers = {}, as = "json" } = {}) {
168
+ const h = { ...headers };
169
+ if (body !== undefined) {
170
+ data = encode(body);
171
+ h["content-type"] = "application/json";
172
+ }
173
+ if (this.token) h.authorization = `Bearer ${this.token}`;
174
+ // A stream is read once: an import of one is not sent again.
175
+ const again = data === undefined || typeof data === "string" || data instanceof Uint8Array;
176
+ const keyed = Boolean(body && typeof body === "object" && body.idempotency_key);
177
+ const giveUp = Date.now() + (this.retryFor || 0);
178
+ let r;
179
+ for (;;) {
180
+ const init = { method, headers: h, body: data };
181
+ if (this.timeout) init.signal = AbortSignal.timeout(this.timeout);
182
+ if (data !== undefined && typeof data?.getReader === "function") init.duplex = "half";
183
+ r = await this.fetch(this.url + path, init);
184
+ if (r.ok) break;
185
+ const raw = await r.text();
186
+ let answer;
187
+ let msg = raw || r.statusText;
188
+ try {
189
+ answer = decode(raw);
190
+ if (answer && typeof answer === "object" && answer.error) msg = answer.error;
191
+ } catch {
192
+ answer = undefined;
193
+ }
194
+ const partial = answer?.partial === true;
195
+ const wait = retryAfter(r.headers.get("retry-after"));
196
+ if (r.status === 429 && this.retryFor > 0 && again && (keyed || !partial) && Date.now() + wait <= giveUp) {
197
+ await new Promise((ok) => setTimeout(ok, wait));
198
+ continue;
199
+ }
200
+ throw makeError(`${msg} (HTTP ${r.status})`, { status: r.status, answer });
201
+ }
202
+ if (as === "response") return r;
203
+ const text = await r.text();
204
+ return as === "text" ? text : decode(text);
205
+ }
206
+
207
+ /** /v1/schema's answer: the first table's (kept), or `table`'s alone,
208
+ * which never reads the first table (a key limited to other tables may
209
+ * not). */
210
+ async #schemaAnswer(table) {
211
+ if (table != null) return this._call("GET", `/v1/schema?table=${encodeURIComponent(table)}`);
212
+ return (this.#schema ??= await this._call("GET", "/v1/schema"));
213
+ }
214
+
215
+ /** The first table's schema, or `table`'s, in its short form: {table,
216
+ * key, fields}. */
217
+ async schema(table) {
218
+ return orderedSchema((await this.#schemaAnswer(table)).short);
219
+ }
220
+
221
+ /** Every table's schema in its short form, the first first. */
222
+ async tables() {
223
+ return (await this._call("GET", "/v1/tables")).tables.map((t) => orderedSchema(t.short));
224
+ }
225
+
226
+ /** @internal */
227
+ async _embedded(table) {
228
+ const first = table == null ? undefined : this.#schema;
229
+ const a = first && first.table.toLowerCase() === String(table).toLowerCase() ? first : await this.#schemaAnswer(table);
230
+ return (a.embeddings ?? []).filter((e) => e.loaded).map((e) => e.field);
231
+ }
232
+
233
+ /** {status, docs, segments, role, ...}, also when the status is "down" or
234
+ * "failing" (which the server answers with 503). */
235
+ async health() {
236
+ try {
237
+ return await this._call("GET", "/v1/health");
238
+ } catch (e) {
239
+ if (e instanceof ChloeDBError && e.status === 503 && e.answer?.status) return e.answer;
240
+ throw e;
241
+ }
242
+ }
243
+
244
+ async stats() {
245
+ return this._call("GET", "/v1/stats");
246
+ }
247
+
248
+ /** Live rows, as the server's health counts them. */
249
+ async count() {
250
+ return Number((await this.health()).docs);
251
+ }
252
+
253
+ // Reads that see a write. A read takes `minSeqNo` (a server's write
254
+ // answered it) and `minSeqNos` (a coordinator's, one per shard): the copy
255
+ // that answers holds those writes. A `Session` adds its own writes'
256
+ // numbers to every read (`_after`) and keeps them from every write's
257
+ // answer (`_note`); a plain Client sends only what it is given.
258
+
259
+ /** @internal */
260
+ _after(minSeqNo, minSeqNos) {
261
+ return afterBody(minSeqNo, minSeqNos);
262
+ }
263
+
264
+ /** @internal */
265
+ _note(answer) {
266
+ return answer;
267
+ }
268
+
269
+ /** A `Session` on this client's server, with its options: its reads see
270
+ * its own writes, through a coordinator or from a replica too. */
271
+ session() {
272
+ return new Session(this.url, { token: this.token, timeout: this.timeout, retryFor: this.retryFor, fetch: this.fetch });
273
+ }
274
+
275
+ /** Runs a SELECT; `timeoutMs` bounds it on the server; with `minSeqNo`
276
+ * or `minSeqNos` the copy that answers holds those writes. */
277
+ async query(sql, params, { timeoutMs, minSeqNo, minSeqNos } = {}) {
278
+ return new Result(await this._call("POST", "/v1/query", given({ sql, params, timeout_ms: timeoutMs, ...this._after(minSeqNo, minSeqNos) })));
279
+ }
280
+
281
+ /** Runs any statement: a SELECT's `Result`, or the number of rows an
282
+ * INSERT, UPDATE or DELETE wrote. */
283
+ async sql(sql, params, { idempotencyKey, minSeqNo, minSeqNos } = {}) {
284
+ const after = reads(sql) ? this._after(minSeqNo, minSeqNos) : afterBody(minSeqNo, minSeqNos);
285
+ const a = await this._call("POST", "/v1/sql", given({ sql, params, idempotency_key: idempotencyKey, ...after }));
286
+ return a && "rows" in a ? new Result(a) : this._note(written(a)).written;
287
+ }
288
+
289
+ /** @internal */
290
+ async _queryLogged(sql, params, log) {
291
+ return new Result(await this._call("POST", "/v1/query", given({ sql, params, log })));
292
+ }
293
+
294
+ /** @internal NDJSON, a record a line; a failure partway is the last line. */
295
+ async _exportRankLog(opts) {
296
+ const text = await this._call("POST", "/v1/rank_log/export", opts, { as: "text" });
297
+ const out = text.split("\n").filter((l) => l.trim()).map(decode);
298
+ const last = out.at(-1);
299
+ if (last && "error" in last && !("request" in last)) {
300
+ throw makeError(`${last.error} (HTTP ${last.status ?? 500})`, { status: last.status ?? 500, answer: last });
301
+ }
302
+ return out;
303
+ }
304
+
305
+ /** Runs the query and returns its plan: the plan IR ("ir") and its lines
306
+ * ("tree"), the executor's plan ("plan") and the bound query
307
+ * ("logical"). */
308
+ async explain(sql, params) {
309
+ return this._call("POST", "/v1/explain", given({ sql, params }));
310
+ }
311
+
312
+ /** Runs a plan (the "ir" of `explain`, or `Database.plan`'s): a read's
313
+ * `Result`, or the number of rows a write wrote. */
314
+ async run(plan, { minSeqNo, minSeqNos } = {}) {
315
+ const write = ["insert", "update", "delete"].includes(plan?.root?.node);
316
+ const a = await this._call("POST", "/v1/plan", { plan, ...(write ? afterBody(minSeqNo, minSeqNos) : this._after(minSeqNo, minSeqNos)) });
317
+ return a && "rows" in a ? new Result(a) : this._note(written(a)).written;
318
+ }
319
+
320
+ /** The query vector of `text` by an embedded field's model, or of `image`
321
+ * or `audio` (the bytes of a file), on the server. */
322
+ async embed(text, { field, table, image, audio } = {}) {
323
+ return (await this._call("POST", "/v1/embed", given({ text, field, table, image: await base64(image), audio: await base64(audio) }))).vector;
324
+ }
325
+
326
+ /** The vectors of `text`'s tokens as a query, by the model of
327
+ * multi-vector field `field` (ColBERT), on the server. */
328
+ async embedTokens(text, field, { table } = {}) {
329
+ return (await this._call("POST", "/v1/embed", given({ text, field, table }))).vectors;
330
+ }
331
+
332
+ /** The codes that can follow each prefix of semantic-ID field `field`
333
+ * among the rows `where` matches, summed over the shards on a
334
+ * coordinator: {prefix: {code: rows}}. */
335
+ async sidNext(prefixes, { field, where, params, table, minSeqNo, minSeqNos } = {}) {
336
+ const got = await this._call("POST", "/v1/sid/next", given({ field, prefixes: [...prefixes], where, params, table, ...this._after(minSeqNo, minSeqNos) }));
337
+ return Object.fromEntries(got.next.map((n) => [n.prefix, Object.fromEntries(n.next.map((c) => [c.code, c.count]))]));
338
+ }
339
+
340
+ /** Write operations as /v1/write takes them ({op: "insert", doc}, {op:
341
+ * "delete", key}, ...), in one request. Returns the rows written. */
342
+ async write(ops, options = {}) {
343
+ return (await this.writeResult(ops, options)).written;
344
+ }
345
+
346
+ /** `write`, answering {written, seqNo?, seqNos?, skipped?}: `seqNo` is a
347
+ * server's number for the write (with --seq-no), `seqNos` a
348
+ * coordinator's, one per shard; pass them to a read as `minSeqNo` /
349
+ * `minSeqNos` to read the write from any copy. */
350
+ async writeResult(ops, { idempotencyKey } = {}) {
351
+ return this._note(written(await this._call("POST", "/v1/write", given({ ops: [...ops], idempotency_key: idempotencyKey }))));
352
+ }
353
+
354
+ async #ops(op, rows, table) {
355
+ let n = 0;
356
+ for (let i = 0; i < rows.length; i += WRITE_BATCH) {
357
+ n += await this.write(rows.slice(i, i + WRITE_BATCH).map((doc) => given({ op, table, doc })));
358
+ }
359
+ return n;
360
+ }
361
+
362
+ /** Inserts a row or rows, whose keys must be new, into the first table or
363
+ * `table`, 1,000 rows a request. Returns how many. */
364
+ async insert(rows, { table } = {}) {
365
+ return this.#ops("insert", rowsOf(rows), table);
366
+ }
367
+
368
+ /** Inserts a row or rows, replacing the rows that have their keys, 1,000
369
+ * rows a request. Returns how many. */
370
+ async upsert(rows, { table } = {}) {
371
+ return this.#ops("upsert", rowsOf(rows), table);
372
+ }
373
+
374
+ /** Deletes the rows with this key or these keys. Through a coordinator,
375
+ * `routing` gives the `shard_by` value of a table placed by a column. */
376
+ async delete(keys, { table, routing } = {}) {
377
+ const list = typeof keys === "string" || typeof keys === "number" || typeof keys === "bigint" ? [keys] : [...keys];
378
+ let n = 0;
379
+ for (let i = 0; i < list.length; i += WRITE_BATCH) {
380
+ n += await this.write(list.slice(i, i + WRITE_BATCH).map((key) => given({ op: "delete", table, routing, key })));
381
+ }
382
+ return n;
383
+ }
384
+
385
+ async #table(table) {
386
+ return table ?? (await this.schema()).table;
387
+ }
388
+
389
+ async #kvPath(key, table) {
390
+ return `/v1/kv/${encodeURIComponent(await this.#table(table))}/${encodeURIComponent(String(key))}`;
391
+ }
392
+
393
+ /** The row with this primary key in the first table or `table`, read
394
+ * without SQL: an object of the columns `SELECT *` answers, or null. A
395
+ * coordinator asks the key's shard. */
396
+ async get(key, { table, minSeqNo, minSeqNos } = {}) {
397
+ const after = this._after(minSeqNo, minSeqNos);
398
+ try {
399
+ return (await this._call("GET", (await this.#kvPath(key, table)) + query(after))).row;
400
+ } catch (e) {
401
+ if (e instanceof ChloeDBError && e.status === 404 && e.answer?.found === false) return null;
402
+ throw e;
403
+ }
404
+ }
405
+
406
+ /**
407
+ * `get` of several keys, 10,000 a request, in their order; with
408
+ * `columns`, each row of those columns alone (a ranker's features, say),
409
+ * which reads no other.
410
+ */
411
+ async getMany(keys, { table, columns, minSeqNo, minSeqNos } = {}) {
412
+ const list = [...keys];
413
+ const body = { table: await this.#table(table), ...this._after(minSeqNo, minSeqNos) };
414
+ if (columns !== undefined) body.columns = [...columns];
415
+ const out = [];
416
+ for (let i = 0; i < list.length; i += GET_BATCH) {
417
+ out.push(...(await this._call("POST", "/v1/kv/get", { ...body, keys: list.slice(i, i + GET_BATCH) })).rows);
418
+ }
419
+ return out;
420
+ }
421
+
422
+ /** Writes `row` as the row with this key, in place of any that has it;
423
+ * with `ifSeqNo`, only while that row's sequence number is that. Returns
424
+ * the rows written. */
425
+ async put(key, row, { table, ifSeqNo } = {}) {
426
+ const path = (await this.#kvPath(key, table)) + query({ if_seq_no: ifSeqNo });
427
+ return this._note(written(await this._call("PUT", path, { ...row }))).written;
428
+ }
429
+
430
+ /**
431
+ * Writes `events` (an iterable or async iterable) through /v1/stream as
432
+ * they come, in batches the server makes: each an operation, or one
433
+ * event's operations as {ops: [...], source: {name, offset, ts}}, which a
434
+ * batch never splits. Offsets a source has reached already are skipped,
435
+ * so a replay applies each event once. Returns the last answer, {done,
436
+ * lines, written, skipped, batches}.
437
+ */
438
+ async stream(events) {
439
+ const enc = new TextEncoder();
440
+ const it = (events[Symbol.asyncIterator] ?? events[Symbol.iterator]).call(events);
441
+ const body = new ReadableStream({
442
+ async pull(c) {
443
+ const chunk = [];
444
+ while (chunk.length < 256) {
445
+ const { value, done } = await it.next();
446
+ if (done) break;
447
+ chunk.push(encode(value));
448
+ }
449
+ if (chunk.length) c.enqueue(enc.encode(chunk.join("\n") + "\n"));
450
+ else c.close();
451
+ },
452
+ });
453
+ const text = await this._call("POST", "/v1/stream", undefined, { data: body, headers: { "content-type": "application/x-ndjson" }, as: "text" });
454
+ let last = {};
455
+ for (const line of text.split("\n")) {
456
+ if (!line.trim()) continue;
457
+ try {
458
+ last = decode(line);
459
+ } catch {
460
+ last = {}; // cut short
461
+ break;
462
+ }
463
+ }
464
+ if ("error" in last || !last.done) {
465
+ throw makeError(`${last.error ?? "the stream ended early"} (HTTP ${last.status ?? 500})`, { status: last.status ?? 500, answer: last });
466
+ }
467
+ return last;
468
+ }
469
+
470
+ /** The offset of the last event written from stream source `name`, or
471
+ * null for a source not written from: resume from the next. */
472
+ async source(name) {
473
+ return (await this._call("GET", "/v1/sources/" + encodeURIComponent(name).replace(/%2F/g, "/"))).offset;
474
+ }
475
+
476
+ /** Every stream source written from: [{name, offset, updated}]. */
477
+ async sources() {
478
+ return (await this._call("GET", "/v1/sources")).sources;
479
+ }
480
+
481
+ async #upload(data, format, q) {
482
+ const body = await bytesOf(data);
483
+ return this._call("POST", "/v1/import" + query({ format, ...q }), undefined, { data: body, headers: { "content-type": CONTENT_TYPES[format] ?? "application/octet-stream" } });
484
+ }
485
+
486
+ /** Uploads a JSON Lines, JSON (an array), CSV or TSV file (a path, or its
487
+ * bytes; up to the server's 256 MB), in `format` or the one its
488
+ * extension names, into the first table or `table`; its rows are
489
+ * upserted. Returns {rows, bulk, skippedFields}. */
490
+ async importFile(file, { format, table } = {}) {
491
+ format ??= FORMATS[extension(file)];
492
+ if (!format) throw new ChloeDBError(`name the format of ${typeof file === "string" ? file : "the file"}: jsonl, json, csv or tsv`);
493
+ const r = await this.#upload(file, format, { table });
494
+ return { rows: r.written, bulk: false, skippedFields: r.skipped_fields ?? [] };
495
+ }
496
+
497
+ /** Uploads a SQLite database file and imports its tables (all, or
498
+ * `tables`), each into the table of its name; rows are upserted by key.
499
+ * Returns {tables, skipped, written}. */
500
+ async importSqlite(file, { tables, blobsBase64 = false } = {}) {
501
+ return this.#upload(file, "sqlite", { tables: names(tables), blobs_base64: blobsBase64 });
502
+ }
503
+
504
+ /** What `importSqlite` would do, writing nothing. */
505
+ async planSqlite(file, { tables, blobsBase64 = false } = {}) {
506
+ return this.#upload(file, "sqlite", { tables: names(tables), blobs_base64: blobsBase64, plan: true });
507
+ }
508
+
509
+ /** Uploads a Parquet file and imports its rows into `table` (by default,
510
+ * the table an export kept in the file), keyed by `key` when it creates
511
+ * one. Returns {table, rows, created, skipped, notes, written}. */
512
+ async importParquet(file, { table, key, blobsBase64 = false } = {}) {
513
+ return this.#upload(file, "parquet", { table, key, blobs_base64: blobsBase64 });
514
+ }
515
+
516
+ /** What `importParquet` would do, writing nothing. */
517
+ async planParquet(file, { table, key, blobsBase64 = false } = {}) {
518
+ return this.#upload(file, "parquet", { table, key, blobs_base64: blobsBase64, plan: true });
519
+ }
520
+
521
+ async #download(path, q) {
522
+ const r = await this._call("GET", "/v1/export" + query(q), undefined, { as: "response" });
523
+ const data = new Uint8Array(await r.arrayBuffer());
524
+ const tables = (r.headers.get("x-chloedb-tables") ?? r.headers.get("x-strata-tables") ?? "").split(",").filter(Boolean);
525
+ if (path == null) return { tables, data };
526
+ await writeNew(path instanceof URL ? path : String(path), data);
527
+ return { tables };
528
+ }
529
+
530
+ /** Downloads the server's tables (all, or `tables`) as a SQLite file: to
531
+ * `path`, which must not exist, or, when `path` is null, as `data` (a
532
+ * Uint8Array). Returns {tables, data?}. */
533
+ async exportSqlite(path, { tables, fts = true, indexes = true, schemas = true } = {}) {
534
+ return this.#download(path, { tables: names(tables), fts: fts ? undefined : false, indexes: indexes ? undefined : false, schemas: schemas ? undefined : false });
535
+ }
536
+
537
+ /** Downloads one of the server's tables (`table`, which a server of one
538
+ * table may leave out) as a Parquet file, to `path` or as `data`, as
539
+ * `exportSqlite` does. Returns {tables, data?}. */
540
+ async exportParquet(path, { table, schemas = true } = {}) {
541
+ return this.#download(path, { format: "parquet", tables: table, schemas: schemas ? undefined : false });
542
+ }
543
+
544
+ /** Asks the server's agent a question about the data: {answer, steps,
545
+ * ...}. Needs an Anthropic API key, the server's or `apiKey`. */
546
+ async ask(question, { model, effort, apiKey, maxSteps } = {}) {
547
+ return this._call("POST", "/v1/agent", given({ question, model, effort, api_key: apiKey, max_steps: maxSteps }));
548
+ }
549
+
550
+ async close() {}
551
+
552
+ async [Symbol.asyncDispose]() {}
553
+ }
554
+
555
+ async function base64(bytes) {
556
+ if (bytes == null) return undefined;
557
+ if (typeof bytes === "string") return bytes;
558
+ let u8;
559
+ if (typeof Blob !== "undefined" && bytes instanceof Blob) u8 = new Uint8Array(await bytes.arrayBuffer());
560
+ else if (bytes instanceof ArrayBuffer) u8 = new Uint8Array(bytes);
561
+ else u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
562
+ if (typeof Uint8Array.prototype.toBase64 === "function") return u8.toBase64();
563
+ let s = "";
564
+ for (let i = 0; i < u8.length; i += 0x8000) s += String.fromCharCode.apply(null, u8.subarray(i, i + 0x8000));
565
+ return btoa(s);
566
+ }
567
+
568
+ /**
569
+ * A `Client` whose reads see its own writes, from any copy: it keeps the
570
+ * latest sequence numbers its writes answered (`seqNo` from a server,
571
+ * `seqNos` from a coordinator, per shard) and sends them with every read
572
+ * (`query`, `search`, `get`, `getMany`, a SELECT by `sql`, a read plan by
573
+ * `run`, `sidNext`), so a replica or a coordinator answers with a version
574
+ * that holds them:
575
+ *
576
+ * const s = connect("http://coordinator:7700").session();
577
+ * await s.upsert({ id: "u1", name: "Ada" });
578
+ * await s.get("u1"); // sees the upsert, whichever copy answers
579
+ *
580
+ * The servers must number their writes (--seq-no); without it a write
581
+ * answers no number and a session reads as a plain client does. Numbers a
582
+ * read is given are sent with the session's, the later of each.
583
+ * `observe(answer)` adds another client's write to what its reads see.
584
+ */
585
+ export class Session extends Client {
586
+ /** The latest number a server's write answered this session, if any. */
587
+ seqNo = undefined;
588
+ /** The latest numbers a coordinator's writes answered, per shard. */
589
+ seqNos = undefined;
590
+
591
+ /** Makes later reads see this write: `writeResult`'s answer ({seqNo} or
592
+ * {seqNos}), or a server's ({seq_no} or {seq_nos}). */
593
+ observe(answer) {
594
+ const n = answer?.seqNo ?? answer?.seq_no;
595
+ const ns = answer?.seqNos ?? answer?.seq_nos;
596
+ this.seqNo = later(this.seqNo, n == null ? undefined : Number(n));
597
+ this.seqNos = laterEach(this.seqNos, ns == null ? undefined : [...ns].map(Number));
598
+ }
599
+
600
+ /** @internal */
601
+ _note(answer) {
602
+ this.observe(answer);
603
+ return answer;
604
+ }
605
+
606
+ /** @internal */
607
+ _after(minSeqNo, minSeqNos) {
608
+ return afterBody(later(this.seqNo, minSeqNo ?? undefined), laterEach(this.seqNos, minSeqNos == null ? undefined : [...minSeqNos]));
609
+ }
610
+
611
+ session() {
612
+ return this;
613
+ }
614
+ }
615
+
616
+ /** A `Client` of the chloedb-server at `url`. */
617
+ export function connect(url = "http://127.0.0.1:7700", options = {}) {
618
+ return new Client(url, options);
619
+ }