@tinyshed/tinystore 0.8.0 → 0.9.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 +1 -1
- package/dist/backup.d.ts +2 -0
- package/dist/backup.js +1 -0
- package/dist/blobs.d.ts +18 -1
- package/dist/blobs.js +52 -45
- package/dist/directory.d.ts +72 -0
- package/dist/directory.js +121 -0
- package/dist/index.d.ts +2 -1
- package/dist/jobs.d.ts +33 -9
- package/dist/jobs.js +137 -34
- package/dist/metrics.d.ts +5 -1
- package/dist/metrics.js +2 -0
- package/dist/query.d.ts +8 -1
- package/dist/query.js +25 -4
- package/dist/search.d.ts +6 -1
- package/dist/search.js +4 -2
- package/dist/sql.d.ts +26 -2
- package/dist/sql.js +18 -5
- package/dist/store.d.ts +9 -0
- package/dist/store.js +11 -0
- package/dist/wire/protocol.d.ts +200 -7
- package/dist/wire/protocol.js +602 -13
- package/package.json +8 -8
- package/src/backup.ts +3 -0
- package/src/blobs.ts +66 -45
- package/src/directory.ts +235 -0
- package/src/index.ts +9 -0
- package/src/jobs.ts +178 -41
- package/src/metrics.ts +7 -1
- package/src/query.ts +28 -6
- package/src/search.ts +10 -5
- package/src/sql.ts +35 -5
- package/src/store.ts +12 -0
- package/src/wire/protocol.ts +637 -13
package/dist/jobs.js
CHANGED
|
@@ -5,14 +5,33 @@
|
|
|
5
5
|
// queue's jobs and hands each over on one stream, the answers going back on
|
|
6
6
|
// it. A handle opens with its first call on a connection.
|
|
7
7
|
import { FailureLog, messageOf } from './background.js';
|
|
8
|
-
import { CancelledError, CorruptError, InvalidError, UnavailableError } from './errors.js';
|
|
8
|
+
import { CancelledError, CorruptError, errorOf, InvalidError, UnavailableError } from './errors.js';
|
|
9
9
|
import { checkName, handleOn, viaLink } from './handles.js';
|
|
10
10
|
import { rateOf } from './limits.js';
|
|
11
11
|
import { sayOwn } from './logger.js';
|
|
12
12
|
import { check } from './schema.js';
|
|
13
13
|
import { ConnectionLostError } from './session.js';
|
|
14
14
|
import { ms, unixMs } from './time.js';
|
|
15
|
-
import { JobsAnswer, JobsCall, JobsChanged, JobsHeld, JobsId, JobsJob, JobsKept, JobsList, JobsPage, JobsQueueOpen, JobsScheduleOpen, JobsStep, JobsTx, JobsWork, methods, } from './wire/protocol.js';
|
|
15
|
+
import { Handle, JobsAnswer, JobsCall, JobsChanged, JobsCounts, JobsHeld, JobsId, JobsJob, JobsKept, JobsList, JobsPage, JobsQueueOpen, JobsScheduleOpen, JobsStep, JobsTx, JobsWork, methods, } from './wire/protocol.js';
|
|
16
|
+
/**
|
|
17
|
+
* Where a job without an id lies, which a cancel names it by: kept on the job
|
|
18
|
+
* a page gave, out of sight, and not on a copy of it.
|
|
19
|
+
*/
|
|
20
|
+
const ROW = Symbol('tinystore.job.row');
|
|
21
|
+
/** What a cancel sends of a job: its id, or for one without, its row. */
|
|
22
|
+
function namedBy(job, describe) {
|
|
23
|
+
if (typeof job === 'string') {
|
|
24
|
+
return { id: job };
|
|
25
|
+
}
|
|
26
|
+
if (job.id !== undefined) {
|
|
27
|
+
return { id: job.id };
|
|
28
|
+
}
|
|
29
|
+
const row = job[ROW];
|
|
30
|
+
if (row === undefined) {
|
|
31
|
+
throw new InvalidError(`${describe}: a job without an id names no row: cancel the job a list gave, not a copy`);
|
|
32
|
+
}
|
|
33
|
+
return { row };
|
|
34
|
+
}
|
|
16
35
|
/** The handlers a client's worker runs at once at most, as the server bounds them. */
|
|
17
36
|
const mostHandlers = 1024;
|
|
18
37
|
/** The pause before a worker dials again after a failure, doubling up to the last. */
|
|
@@ -247,10 +266,81 @@ async function getJob(source, id) {
|
|
|
247
266
|
const found = JobsJob.decode(body);
|
|
248
267
|
return found.found === true ? jobOf(source, found) : undefined;
|
|
249
268
|
}
|
|
250
|
-
async function cancelJob(source,
|
|
251
|
-
const
|
|
269
|
+
async function cancelJob(source, job) {
|
|
270
|
+
const named = namedBy(job, source.describe);
|
|
271
|
+
const body = await callOf(source, methods['jobs.cancel'], handle => JobsId.encode({ handle, ...named }), 'write');
|
|
252
272
|
return JobsChanged.decode(body).changed === true;
|
|
253
273
|
}
|
|
274
|
+
/**
|
|
275
|
+
* A page of the queue's jobs. A walk's page has a job whose value no longer
|
|
276
|
+
* reads as its error in its place; any other page fails on it.
|
|
277
|
+
*/
|
|
278
|
+
async function pageOf(source, options, walk) {
|
|
279
|
+
const body = await callOf(source, methods['jobs.list'], handle => JobsList.encode({ handle, ...options, walk }), 'read');
|
|
280
|
+
const page = JobsPage.decode(body);
|
|
281
|
+
const jobs = [];
|
|
282
|
+
for (const found of page.jobs ?? []) {
|
|
283
|
+
if (found.failure !== undefined) {
|
|
284
|
+
const { code, message, what } = found.failure;
|
|
285
|
+
jobs.push(errorOf(code ?? 'internal', message ?? '', what ?? {}));
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
const job = jobOf(source, found);
|
|
289
|
+
jobs.push(walk ? await job.catch((err) => err) : await job);
|
|
290
|
+
}
|
|
291
|
+
return { jobs, next: page.next };
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* Every job a filter names, a page at a time. A job whose value no longer
|
|
295
|
+
* reads is its error in its place: `next()` rejects with it, and the call
|
|
296
|
+
* after goes on past it, as a `for await` that catches it and iterates the
|
|
297
|
+
* same walk again does.
|
|
298
|
+
*/
|
|
299
|
+
class Walk {
|
|
300
|
+
#source;
|
|
301
|
+
#options;
|
|
302
|
+
#jobs = [];
|
|
303
|
+
#after;
|
|
304
|
+
#ended = false;
|
|
305
|
+
constructor(source, options) {
|
|
306
|
+
this.#source = source;
|
|
307
|
+
this.#options = options;
|
|
308
|
+
}
|
|
309
|
+
async next() {
|
|
310
|
+
while (this.#jobs.length === 0 && !this.#ended) {
|
|
311
|
+
const page = await pageOf(this.#source, { ...this.#options, after: this.#after }, true);
|
|
312
|
+
this.#jobs = page.jobs;
|
|
313
|
+
this.#after = page.next;
|
|
314
|
+
this.#ended = page.next === undefined;
|
|
315
|
+
}
|
|
316
|
+
const job = this.#jobs.shift();
|
|
317
|
+
if (job === undefined) {
|
|
318
|
+
return { done: true, value: undefined };
|
|
319
|
+
}
|
|
320
|
+
if (job instanceof Error) {
|
|
321
|
+
throw job;
|
|
322
|
+
}
|
|
323
|
+
return { done: false, value: job };
|
|
324
|
+
}
|
|
325
|
+
async return() {
|
|
326
|
+
this.#end();
|
|
327
|
+
return { done: true, value: undefined };
|
|
328
|
+
}
|
|
329
|
+
async throw(err) {
|
|
330
|
+
this.#end();
|
|
331
|
+
throw err;
|
|
332
|
+
}
|
|
333
|
+
[Symbol.asyncIterator]() {
|
|
334
|
+
return this;
|
|
335
|
+
}
|
|
336
|
+
async [Symbol.asyncDispose]() {
|
|
337
|
+
this.#end();
|
|
338
|
+
}
|
|
339
|
+
#end() {
|
|
340
|
+
this.#jobs = [];
|
|
341
|
+
this.#ended = true;
|
|
342
|
+
}
|
|
343
|
+
}
|
|
254
344
|
/** A job as the server sent it, its value read as the queue reads one. */
|
|
255
345
|
async function jobOf(source, found) {
|
|
256
346
|
let value;
|
|
@@ -258,9 +348,10 @@ async function jobOf(source, found) {
|
|
|
258
348
|
value = await source.values.decode(found.value ?? 'null');
|
|
259
349
|
}
|
|
260
350
|
catch (err) {
|
|
261
|
-
|
|
351
|
+
const named = found.id === undefined ? 'a job without an id' : `id ${JSON.stringify(found.id)}`;
|
|
352
|
+
throw new CorruptError(`${source.describe}: ${named}: ${messageOf(err)}`);
|
|
262
353
|
}
|
|
263
|
-
|
|
354
|
+
const job = {
|
|
264
355
|
id: found.id,
|
|
265
356
|
value,
|
|
266
357
|
state: (found.state ?? 'waiting'),
|
|
@@ -278,6 +369,10 @@ async function jobOf(source, found) {
|
|
|
278
369
|
endedAt: new Date(found.endedAt ?? found.startedAt),
|
|
279
370
|
},
|
|
280
371
|
};
|
|
372
|
+
if (found.row !== undefined) {
|
|
373
|
+
Object.defineProperty(job, ROW, { value: found.row });
|
|
374
|
+
}
|
|
375
|
+
return job;
|
|
281
376
|
}
|
|
282
377
|
/**
|
|
283
378
|
* Follows the job under id over the server's watch, until the stream's last
|
|
@@ -394,12 +489,28 @@ export class Queue {
|
|
|
394
489
|
return (await this.#changed(methods['jobs.update'], fields)) === true;
|
|
395
490
|
}
|
|
396
491
|
/**
|
|
397
|
-
* Takes
|
|
398
|
-
*
|
|
492
|
+
* Takes a job, whatever its state, and says whether it was there: the job
|
|
493
|
+
* under an id, or a job a list gave, by its id or, for one without, by the
|
|
494
|
+
* row it was listed from. A job retried, run again for its repeat or
|
|
495
|
+
* cancelled since is in no row, and its cancel takes nothing, never another
|
|
496
|
+
* job. A running one's handler sees its signal abort, and what it returns
|
|
399
497
|
* then settles nothing; a repeating one stops.
|
|
498
|
+
*
|
|
499
|
+
* for await (const job of emails.all({ state: 'scheduled' })) if (job.value.to === bounced) await emails.cancel(job)
|
|
400
500
|
*/
|
|
401
|
-
cancel(
|
|
402
|
-
return cancelJob(this.#source,
|
|
501
|
+
cancel(job) {
|
|
502
|
+
return cancelJob(this.#source, job);
|
|
503
|
+
}
|
|
504
|
+
/** How many jobs the queue holds in each state, from one snapshot; it reads no value. */
|
|
505
|
+
async counts() {
|
|
506
|
+
const body = await callOf(this.#source, methods['jobs.counts'], handle => Handle.encode({ handle }), 'read');
|
|
507
|
+
const { scheduled, waiting, running, failed } = JobsCounts.decode(body);
|
|
508
|
+
return {
|
|
509
|
+
scheduled: scheduled ?? 0,
|
|
510
|
+
waiting: waiting ?? 0,
|
|
511
|
+
running: running ?? 0,
|
|
512
|
+
failed: failed ?? 0,
|
|
513
|
+
};
|
|
403
514
|
}
|
|
404
515
|
/**
|
|
405
516
|
* Where the job under id is: scheduled, waiting and how many jobs are
|
|
@@ -426,25 +537,16 @@ export class Queue {
|
|
|
426
537
|
* then those without as they run, then those without that failed.
|
|
427
538
|
*/
|
|
428
539
|
async list(options = {}) {
|
|
429
|
-
const
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
let after;
|
|
440
|
-
for (;;) {
|
|
441
|
-
const page = await this.list({ ...options, after });
|
|
442
|
-
yield* page.jobs;
|
|
443
|
-
if (page.next === undefined) {
|
|
444
|
-
return;
|
|
445
|
-
}
|
|
446
|
-
after = page.next;
|
|
447
|
-
}
|
|
540
|
+
const page = await pageOf(this.#source, options, false);
|
|
541
|
+
return { jobs: page.jobs, next: page.next };
|
|
542
|
+
}
|
|
543
|
+
/**
|
|
544
|
+
* Every job the options name, a page at a time, holding nothing between
|
|
545
|
+
* pages. A job whose value no longer reads is a CorruptError in its place,
|
|
546
|
+
* naming it, and iterating the same walk again goes on past it.
|
|
547
|
+
*/
|
|
548
|
+
all(options = {}) {
|
|
549
|
+
return new Walk(this.#source, options);
|
|
448
550
|
}
|
|
449
551
|
/**
|
|
450
552
|
* Runs handler on each job as it falls due, as many at once as the
|
|
@@ -495,8 +597,8 @@ export class TxQueue {
|
|
|
495
597
|
update(id, value, options = {}) {
|
|
496
598
|
return this.#queue.update(id, value, options);
|
|
497
599
|
}
|
|
498
|
-
cancel(
|
|
499
|
-
return this.#queue.cancel(
|
|
600
|
+
cancel(job) {
|
|
601
|
+
return this.#queue.cancel(job);
|
|
500
602
|
}
|
|
501
603
|
/** The job under id as the transaction sees it, its own writes among it. */
|
|
502
604
|
get(id) {
|
|
@@ -563,8 +665,9 @@ export class StoreTxQueue {
|
|
|
563
665
|
async update(id, value, options = {}) {
|
|
564
666
|
this.#write('jobs.update', { ...jobFields(options), id }, value);
|
|
565
667
|
}
|
|
566
|
-
/** Takes the job under id, whatever its state, with the commit. */
|
|
567
|
-
async cancel(
|
|
668
|
+
/** Takes the job under id, or a job a list gave, whatever its state, with the commit. */
|
|
669
|
+
async cancel(job) {
|
|
670
|
+
const id = namedBy(job, this.#source.describe);
|
|
568
671
|
this.#keep({ source: this.#source, method: methods['jobs.cancel'], id });
|
|
569
672
|
}
|
|
570
673
|
#write(method, fields, value) {
|
|
@@ -581,7 +684,7 @@ export async function commitJobs(link, ops) {
|
|
|
581
684
|
writes.push({
|
|
582
685
|
method: op.method,
|
|
583
686
|
call: op.call === undefined ? undefined : { ...op.call, handle },
|
|
584
|
-
id: op.id === undefined ? undefined : { handle,
|
|
687
|
+
id: op.id === undefined ? undefined : { handle, ...op.id },
|
|
585
688
|
});
|
|
586
689
|
}
|
|
587
690
|
await connection.session.call(methods['jobs.tx'], JobsTx.encode({ writes }));
|
package/dist/metrics.d.ts
CHANGED
|
@@ -96,6 +96,8 @@ export interface AggregateQuery<O extends Op = Op> extends Query {
|
|
|
96
96
|
without?: readonly string[] | undefined;
|
|
97
97
|
/** a timer's percentile also gives a point between its bounds, interpolated: an estimate */
|
|
98
98
|
estimate?: boolean | undefined;
|
|
99
|
+
/** a NaN sample counts in no bucket, which says how many it passed over in skipped; an infinity is still refused */
|
|
100
|
+
skipNaN?: boolean | undefined;
|
|
99
101
|
}
|
|
100
102
|
/** What every bucket of an aggregate says of itself. */
|
|
101
103
|
interface Spanned {
|
|
@@ -104,6 +106,8 @@ interface Spanned {
|
|
|
104
106
|
/** how many samples it comes from; a timer's, how many durations */
|
|
105
107
|
samples: number;
|
|
106
108
|
resets: number;
|
|
109
|
+
/** the NaN samples it passed over, with skipNaN */
|
|
110
|
+
skipped: number;
|
|
107
111
|
/** its value comes from less than its span: the range, the clock or retention cut it */
|
|
108
112
|
partial: boolean;
|
|
109
113
|
/** its first step began before the bucket before it: a whole bucket between had no samples */
|
|
@@ -131,7 +135,7 @@ export interface Aggregate<O extends Op = Op> {
|
|
|
131
135
|
name: string;
|
|
132
136
|
/** the labels by kept or without left */
|
|
133
137
|
labels: Labels;
|
|
134
|
-
/** a bucket without samples is left out */
|
|
138
|
+
/** a bucket without samples is left out, and so is one of NaN alone */
|
|
135
139
|
buckets: Bucket<O>[];
|
|
136
140
|
/** a page cut the group here: the page its next reads begins with the rest of its buckets */
|
|
137
141
|
more: boolean;
|
package/dist/metrics.js
CHANGED
|
@@ -367,6 +367,7 @@ function aggregateOf(query) {
|
|
|
367
367
|
by: query.by === undefined ? undefined : [...query.by],
|
|
368
368
|
without: query.without === undefined ? undefined : [...query.without],
|
|
369
369
|
estimate: query.estimate === true,
|
|
370
|
+
skipNan: query.skipNaN === true,
|
|
370
371
|
};
|
|
371
372
|
}
|
|
372
373
|
function pageOf(options) {
|
|
@@ -377,6 +378,7 @@ function bucketOf(bucket) {
|
|
|
377
378
|
at: new Date(bucket.at ?? 0),
|
|
378
379
|
samples: bucket.samples ?? 0,
|
|
379
380
|
resets: bucket.resets ?? 0,
|
|
381
|
+
skipped: bucket.skipped ?? 0,
|
|
380
382
|
partial: bucket.partial === true,
|
|
381
383
|
gap: bucket.gap === true,
|
|
382
384
|
};
|
package/dist/query.d.ts
CHANGED
|
@@ -123,7 +123,14 @@ export declare class Query<T = Row> implements Embeddable {
|
|
|
123
123
|
scalar<V = SqlValue>(): Promise<V>;
|
|
124
124
|
/** Every row the conditions match, without the order and the limit. */
|
|
125
125
|
count(): Promise<number>;
|
|
126
|
-
/**
|
|
126
|
+
/**
|
|
127
|
+
* The rows one at a time, as their parts arrive: for more than fits in
|
|
128
|
+
* memory. The server reads them from one snapshot of five seconds at
|
|
129
|
+
* most; ordered by columns by their names, a unique one last, as `list`
|
|
130
|
+
* is, it reads on past that after the last row it sent, and any other
|
|
131
|
+
* walk fails `limit` there. Inside a transaction it reads the rows `all`
|
|
132
|
+
* does.
|
|
133
|
+
*/
|
|
127
134
|
each(): AsyncGenerator<T>;
|
|
128
135
|
/**
|
|
129
136
|
* A page after the last row of the one before, by the query's order,
|
package/dist/query.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
var _a;
|
|
6
6
|
import { CorruptError, InvalidError } from './errors.js';
|
|
7
7
|
import { check } from './schema.js';
|
|
8
|
-
import { cellOf, checked, conditionOf, grouped, identOf, joinedWith, placeholders, Sql, } from './sql.js';
|
|
8
|
+
import { cellOf, checked, conditionOf, grouped, identOf, joinedWith, placeholders, Sql, walk, } from './sql.js';
|
|
9
9
|
/**
|
|
10
10
|
* A query on a table: a value, each call returning a new one, so that the
|
|
11
11
|
* first stays as it was. `all`, `one`, `scalar`, `count`, `each` and `list`
|
|
@@ -150,14 +150,21 @@ export class Query {
|
|
|
150
150
|
const answered = await this.#source.runner.rows(statement, 'scalar');
|
|
151
151
|
return Number(answered.rows[0]?.[0] ?? 0);
|
|
152
152
|
}
|
|
153
|
-
/**
|
|
153
|
+
/**
|
|
154
|
+
* The rows one at a time, as their parts arrive: for more than fits in
|
|
155
|
+
* memory. The server reads them from one snapshot of five seconds at
|
|
156
|
+
* most; ordered by columns by their names, a unique one last, as `list`
|
|
157
|
+
* is, it reads on past that after the last row it sent, and any other
|
|
158
|
+
* walk fails `limit` there. Inside a transaction it reads the rows `all`
|
|
159
|
+
* does.
|
|
160
|
+
*/
|
|
154
161
|
async *each() {
|
|
155
162
|
const runner = this.#source.runner;
|
|
156
|
-
if (runner
|
|
163
|
+
if (runner[walk] === undefined) {
|
|
157
164
|
yield* await this.all();
|
|
158
165
|
return;
|
|
159
166
|
}
|
|
160
|
-
for await (const row of runner
|
|
167
|
+
for await (const row of runner[walk](render(this.#parts), walkOrder(this.#parts.order))) {
|
|
161
168
|
yield (await this.#rows(Object.keys(row), [Object.values(row)]))[0];
|
|
162
169
|
}
|
|
163
170
|
}
|
|
@@ -692,6 +699,20 @@ function render(parts) {
|
|
|
692
699
|
}
|
|
693
700
|
return new Sql(text, values);
|
|
694
701
|
}
|
|
702
|
+
/**
|
|
703
|
+
* The columns a walk's rows are ordered by, as its rows name them, when each
|
|
704
|
+
* is a column by its name: the server reads on past one snapshot by them, as
|
|
705
|
+
* `list` pages by them.
|
|
706
|
+
*/
|
|
707
|
+
function walkOrder(order) {
|
|
708
|
+
if (order.length === 0 || order.some(each => each.column === undefined)) {
|
|
709
|
+
return undefined;
|
|
710
|
+
}
|
|
711
|
+
return order.map(each => ({
|
|
712
|
+
column: each.column.split('.').pop(),
|
|
713
|
+
descending: each.direction === 'desc',
|
|
714
|
+
}));
|
|
715
|
+
}
|
|
695
716
|
/**
|
|
696
717
|
* The condition that starts a page after a row's order values. SQLite orders
|
|
697
718
|
* a null before every value, first in ascending order and last in descending,
|
package/dist/search.d.ts
CHANGED
|
@@ -120,12 +120,17 @@ export interface Found<T> {
|
|
|
120
120
|
hits: Hit<T>[];
|
|
121
121
|
corrected?: string | undefined;
|
|
122
122
|
}
|
|
123
|
-
/**
|
|
123
|
+
/**
|
|
124
|
+
* Where an index stands: serving what it was opened with, read again beside it, or a rebuild that failed.
|
|
125
|
+
* `error` beside `ready` and `rebuilding` is the last maintenance pass's failure while the passes keep failing.
|
|
126
|
+
*/
|
|
124
127
|
export type IndexStatus = {
|
|
125
128
|
state: 'ready';
|
|
129
|
+
error?: string | undefined;
|
|
126
130
|
} | {
|
|
127
131
|
state: 'rebuilding';
|
|
128
132
|
done: number;
|
|
133
|
+
error?: string | undefined;
|
|
129
134
|
} | {
|
|
130
135
|
state: 'failed';
|
|
131
136
|
error: string;
|
package/dist/search.js
CHANGED
|
@@ -220,13 +220,15 @@ export async function listIndexes(link) {
|
|
|
220
220
|
});
|
|
221
221
|
}
|
|
222
222
|
function statusOf(status) {
|
|
223
|
+
// an empty error is none: the wire's field is a string
|
|
224
|
+
const error = status.error ? { error: status.error } : {};
|
|
223
225
|
switch (status.state) {
|
|
224
226
|
case 'rebuilding':
|
|
225
|
-
return { state: 'rebuilding', done: status.done ?? 0 };
|
|
227
|
+
return { state: 'rebuilding', done: status.done ?? 0, ...error };
|
|
226
228
|
case 'failed':
|
|
227
229
|
return { state: 'failed', error: status.error ?? '' };
|
|
228
230
|
default:
|
|
229
|
-
return { state: 'ready' };
|
|
231
|
+
return { state: 'ready', ...error };
|
|
230
232
|
}
|
|
231
233
|
}
|
|
232
234
|
function matchOf(found) {
|
package/dist/sql.d.ts
CHANGED
|
@@ -36,6 +36,14 @@ export interface DatabaseOptions {
|
|
|
36
36
|
* with it. A database open already keeps what it was opened with.
|
|
37
37
|
*/
|
|
38
38
|
durability?: Durability;
|
|
39
|
+
/**
|
|
40
|
+
* Whether backups take the database; `false` keeps its file and the
|
|
41
|
+
* bytes of its files in `local/` rather than `sql/`, where no backup
|
|
42
|
+
* looks, open or not, and no node copies it: each node that opens it
|
|
43
|
+
* writes its own. A name lives in one folder: one whose file lies in the
|
|
44
|
+
* other is InvalidError, naming both.
|
|
45
|
+
*/
|
|
46
|
+
backup?: boolean;
|
|
39
47
|
}
|
|
40
48
|
/** What a write changed: the rows, and SQLite's rowid of the row it inserted, 0 when none. */
|
|
41
49
|
export interface Done {
|
|
@@ -137,11 +145,19 @@ interface Answered {
|
|
|
137
145
|
rows: SqlValue[][];
|
|
138
146
|
}
|
|
139
147
|
type Want = 'all' | 'one' | 'scalar';
|
|
148
|
+
/** A column a walk's rows are ordered by, as the rows name it. */
|
|
149
|
+
export interface Ordered {
|
|
150
|
+
column: string;
|
|
151
|
+
descending: boolean;
|
|
152
|
+
}
|
|
153
|
+
/** The database's walk of a statement's rows, which its table's `each` reads; a transaction has none. */
|
|
154
|
+
export declare const walk: unique symbol;
|
|
140
155
|
/** What reads and writes a database: the database itself, or a transaction of it. */
|
|
141
156
|
export interface Runner {
|
|
142
157
|
readonly describe: string;
|
|
143
158
|
rows(statement: Sql, want: Want): Promise<Answered>;
|
|
144
159
|
exec(statement: Sql): Promise<Done>;
|
|
160
|
+
[walk]?<T = Row>(statement: Sql, order: readonly Ordered[] | undefined): AsyncGenerator<T>;
|
|
145
161
|
}
|
|
146
162
|
/** Whether the caller runs inside the function of a database's transaction. */
|
|
147
163
|
export declare function insideDatabaseTx(): boolean;
|
|
@@ -230,10 +246,18 @@ export declare class Database implements Runner, Home {
|
|
|
230
246
|
columns<T = Row>(...statement: Statement): Promise<Columns<T>>;
|
|
231
247
|
/**
|
|
232
248
|
* The rows a statement gives, one at a time as their parts arrive: an
|
|
233
|
-
* export that holds
|
|
234
|
-
* one snapshot,
|
|
249
|
+
* export that holds a part, not every row, however many there are. The
|
|
250
|
+
* server reads them a part at a time from one snapshot, which lasts five
|
|
251
|
+
* seconds at most: a walk that takes longer fails `limit`, and is read a
|
|
252
|
+
* page at a time with a table's `list`, or ordered by its key with a
|
|
253
|
+
* table's `each`, which reads on past it.
|
|
235
254
|
*/
|
|
236
255
|
each<T = Row>(...statement: Statement): AsyncGenerator<T>;
|
|
256
|
+
/**
|
|
257
|
+
* A statement's rows as the server reads them, `want: each`; ordered by
|
|
258
|
+
* `order`, a unique column last, the server reads on past one snapshot.
|
|
259
|
+
*/
|
|
260
|
+
[walk]<T = Row>(piece: Sql, order: readonly Ordered[] | undefined): AsyncGenerator<T>;
|
|
237
261
|
/**
|
|
238
262
|
* A table of the database, typed where it opens: its rows' inserts and
|
|
239
263
|
* upserts, and queries built without SQL text. It costs nothing until its
|
package/dist/sql.js
CHANGED
|
@@ -415,7 +415,8 @@ export async function openDatabase(link, workers, name, options = {}) {
|
|
|
415
415
|
checkName(name, 'database');
|
|
416
416
|
checkDurability(options.durability, `sql ${name}`);
|
|
417
417
|
const migrations = options.migrations === undefined ? undefined : await migrationFiles(options.migrations);
|
|
418
|
-
const
|
|
418
|
+
const backup = options.backup === false ? false : undefined;
|
|
419
|
+
const open = SqlOpen.encode({ name, migrations, durability: options.durability, backup });
|
|
419
420
|
const db = new Database(link, workers, name, open);
|
|
420
421
|
await link.run('read', connection => db.handle(connection));
|
|
421
422
|
return db;
|
|
@@ -523,6 +524,8 @@ function doneOf(done) {
|
|
|
523
524
|
const exact = rowid >= BigInt(Number.MIN_SAFE_INTEGER) && rowid <= BigInt(Number.MAX_SAFE_INTEGER);
|
|
524
525
|
return { changes: done.changes ?? 0, lastInsertRowid: exact ? Number(rowid) : rowid };
|
|
525
526
|
}
|
|
527
|
+
/** The database's walk of a statement's rows, which its table's `each` reads; a transaction has none. */
|
|
528
|
+
export const walk = Symbol('walk');
|
|
526
529
|
/** The reads every runner shares: all, one and scalar over its rows. */
|
|
527
530
|
async function all(runner, statement) {
|
|
528
531
|
const answered = await runner.rows(statement, 'all');
|
|
@@ -690,19 +693,29 @@ export class Database {
|
|
|
690
693
|
}
|
|
691
694
|
/**
|
|
692
695
|
* The rows a statement gives, one at a time as their parts arrive: an
|
|
693
|
-
* export that holds
|
|
694
|
-
* one snapshot,
|
|
696
|
+
* export that holds a part, not every row, however many there are. The
|
|
697
|
+
* server reads them a part at a time from one snapshot, which lasts five
|
|
698
|
+
* seconds at most: a walk that takes longer fails `limit`, and is read a
|
|
699
|
+
* page at a time with a table's `list`, or ordered by its key with a
|
|
700
|
+
* table's `each`, which reads on past it.
|
|
695
701
|
*/
|
|
696
702
|
async *each(...statement) {
|
|
703
|
+
yield* this[walk](statementOf(statement), undefined);
|
|
704
|
+
}
|
|
705
|
+
/**
|
|
706
|
+
* A statement's rows as the server reads them, `want: each`; ordered by
|
|
707
|
+
* `order`, a unique column last, the server reads on past one snapshot.
|
|
708
|
+
*/
|
|
709
|
+
async *[walk](piece, order) {
|
|
697
710
|
this.#refuseAround('a read');
|
|
698
|
-
const piece = statementOf(statement);
|
|
699
711
|
const connection = await this.#link.connection();
|
|
700
712
|
const handle = await this.handle(connection);
|
|
701
713
|
const body = SqlQuery.encode({
|
|
702
714
|
handle,
|
|
703
715
|
text: piece.text,
|
|
704
716
|
values: [...piece.values],
|
|
705
|
-
want: '
|
|
717
|
+
want: 'each',
|
|
718
|
+
order: order === undefined ? undefined : [...order],
|
|
706
719
|
});
|
|
707
720
|
const stream = await connection.session.open(methods['sql.query'], body, true);
|
|
708
721
|
try {
|
package/dist/store.d.ts
CHANGED
|
@@ -4,6 +4,7 @@ import { Channel } from './channels.ts';
|
|
|
4
4
|
import { Clock } from './clock.ts';
|
|
5
5
|
import { Config, type ConfigOptions, type Layer, type Value } from './config.ts';
|
|
6
6
|
import { type Durability, Link, type SelfMetrics } from './connection.ts';
|
|
7
|
+
import { type Directory, type DirectoryOptions } from './directory.ts';
|
|
7
8
|
import { type Queue, type QueueOptions, type Run, type Schedule, type ScheduleOptions, type ScheduleWhen } from './jobs.ts';
|
|
8
9
|
import { Bucket, type BucketOptions, Counters, type CountersOptions } from './kv.ts';
|
|
9
10
|
import { Quota, type Rate, RateLimit, type RateLimitOptions } from './limits.ts';
|
|
@@ -306,6 +307,14 @@ export declare class Store implements AsyncDisposable {
|
|
|
306
307
|
* const reports = store.files('reports', { ttl: '24h', maxFileSize: '2GiB' })
|
|
307
308
|
*/
|
|
308
309
|
files(name: string, options?: FilesOptions): Files;
|
|
310
|
+
/**
|
|
311
|
+
* A folder of the store's machine under a name, which the store lists and
|
|
312
|
+
* reads and never writes; over a token, the server's own by its name:
|
|
313
|
+
*
|
|
314
|
+
* const movies = store.directory('movies', { path: 'D:/Movies' })
|
|
315
|
+
* const photos = store.directory('photos', { path: '/mnt/photos', every: '15m', ignore: ['*.part', '.*'] })
|
|
316
|
+
*/
|
|
317
|
+
directory(name: string, options?: DirectoryOptions): Directory;
|
|
309
318
|
/**
|
|
310
319
|
* The application's database name, sql/<name>.db, once its migrations
|
|
311
320
|
* are applied and checked: a migration that fails, or one changed after
|
package/dist/store.js
CHANGED
|
@@ -7,6 +7,7 @@ import { Channel } from './channels.js';
|
|
|
7
7
|
import { Clock } from './clock.js';
|
|
8
8
|
import { Config } from './config.js';
|
|
9
9
|
import { asking, checkDurability, checkMaxSeries, embedded, Link, privateChild, remote, sidecar, } from './connection.js';
|
|
10
|
+
import { openDirectory } from './directory.js';
|
|
10
11
|
import { ClosedError, InvalidError } from './errors.js';
|
|
11
12
|
import { Instruments } from './instruments.js';
|
|
12
13
|
import { openQueue, openSchedule, } from './jobs.js';
|
|
@@ -247,6 +248,16 @@ export class Store {
|
|
|
247
248
|
files(name, options) {
|
|
248
249
|
return openFiles(this.#link, name, options);
|
|
249
250
|
}
|
|
251
|
+
/**
|
|
252
|
+
* A folder of the store's machine under a name, which the store lists and
|
|
253
|
+
* reads and never writes; over a token, the server's own by its name:
|
|
254
|
+
*
|
|
255
|
+
* const movies = store.directory('movies', { path: 'D:/Movies' })
|
|
256
|
+
* const photos = store.directory('photos', { path: '/mnt/photos', every: '15m', ignore: ['*.part', '.*'] })
|
|
257
|
+
*/
|
|
258
|
+
directory(name, options) {
|
|
259
|
+
return openDirectory(this.#link, name, options);
|
|
260
|
+
}
|
|
250
261
|
/**
|
|
251
262
|
* The application's database name, sql/<name>.db, once its migrations
|
|
252
263
|
* are applied and checked: a migration that fails, or one changed after
|