@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/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, id) {
251
- const body = await callOf(source, methods['jobs.cancel'], handle => JobsId.encode({ handle, id }), 'write');
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
- throw new CorruptError(`${source.describe}: id ${JSON.stringify(found.id ?? '')}: ${messageOf(err)}`);
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
- return {
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 the job under id, whatever its state, and says whether there was
398
- * one. A running one's handler sees its signal abort, and what it returns
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(id) {
402
- return cancelJob(this.#source, id);
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 body = await callOf(this.#source, methods['jobs.list'], handle => JobsList.encode({ handle, ...options }), 'read');
430
- const page = JobsPage.decode(body);
431
- const jobs = [];
432
- for (const found of page.jobs ?? []) {
433
- jobs.push(await jobOf(this.#source, found));
434
- }
435
- return { jobs, next: page.next };
436
- }
437
- /** Every job the options name, a page at a time, holding nothing between pages. */
438
- async *all(options = {}) {
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(id) {
499
- return this.#queue.cancel(id);
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(id) {
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, id: op.id },
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
- /** The rows one at a time, as their parts arrive. */
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
- /** The rows one at a time, as their parts arrive. */
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.each === undefined) {
163
+ if (runner[walk] === undefined) {
157
164
  yield* await this.all();
158
165
  return;
159
166
  }
160
- for await (const row of runner.each(render(this.#parts))) {
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
- /** Where an index stands: serving what it was opened with, read again beside it, or a rebuild that failed. */
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 one part, not every row. The server reads them from
234
- * one snapshot, at most 64 MiB.
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 open = SqlOpen.encode({ name, migrations, durability: options.durability });
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 one part, not every row. The server reads them from
694
- * one snapshot, at most 64 MiB.
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: 'all',
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