@tinyshed/tinystore 0.7.1 → 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 CHANGED
@@ -13,7 +13,7 @@ one. Every call, by engine, is in docs/reference/bun.md.
13
13
 
14
14
  <!-- /landing:headline -->
15
15
 
16
- > **Version 0.3.** Until `1.0`, a minor release may still change the API,
16
+ > **Version 0.9.** Until `1.0`, a minor release may still change the API,
17
17
  > and its notes say what changed.
18
18
 
19
19
  The SDK starts a small `tinystore` server next to your program, called the
package/dist/backup.d.ts CHANGED
@@ -25,6 +25,8 @@ export interface Backup {
25
25
  * hold: they open with that key alone, kept apart
26
26
  */
27
27
  keyLeftOut: boolean;
28
+ /** the databases opened with `backup: false`, by name, of which it holds nothing */
29
+ excluded: string[];
28
30
  }
29
31
  /**
30
32
  * Writes a backup of the store `link` reaches to `path`, beside it first:
package/dist/backup.js CHANGED
@@ -40,6 +40,7 @@ export async function backup(link, path, options) {
40
40
  files: Number(backed.files ?? 0),
41
41
  bytes: Number(backed.bytes ?? 0),
42
42
  keyLeftOut: backed.keyLeftOut === true,
43
+ excluded: backed.excluded ?? [],
43
44
  };
44
45
  }
45
46
  catch (err) {
package/dist/blobs.d.ts CHANGED
@@ -1,7 +1,8 @@
1
- import { type Link } from './connection.ts';
1
+ import { type Connection, type Link } from './connection.ts';
2
2
  import { type Home, type Open, type Via } from './handles.ts';
3
3
  import { type Stream } from './session.ts';
4
4
  import { type Duration } from './time.ts';
5
+ import { BlobsInfo } from './wire/protocol.ts';
5
6
  /** A size in bytes: a number, or text in binary units, 64KiB or 2GiB; '2GB' does not compile. */
6
7
  export type Size = number | `${number}${'KiB' | 'MiB' | 'GiB' | 'TiB'}`;
7
8
  export interface FilesOptions {
@@ -194,3 +195,19 @@ export declare class StoredFile extends FileBytes implements FileInfo {
194
195
  */
195
196
  slice(start?: number, end?: number): FileBytes;
196
197
  }
198
+ /** Where a read of a file's bytes stands, and the ETag it holds to; none holds to no version. */
199
+ export interface ReadAt {
200
+ folder: string[];
201
+ path: string;
202
+ ifMatch: string | undefined;
203
+ offset?: number | undefined;
204
+ length?: number | undefined;
205
+ }
206
+ /**
207
+ * A file's bytes as S3's GET reads them with a range and If-Match, on the
208
+ * handle `handle` opens on a connection; nothing is asked before the first read.
209
+ */
210
+ export declare function readStream(link: Link, handle: (connection: Connection) => Promise<number>, at: ReadAt): ReadableStream<Uint8Array>;
211
+ export declare function infoOf(info: ReturnType<typeof BlobsInfo.decode>): FileInfo;
212
+ /** A folder's segment as text, an integer its decimal spelling; the server refuses one that is not a segment. */
213
+ export declare function segmentOf(segment: string | number | bigint): string;
package/dist/blobs.js CHANGED
@@ -191,48 +191,8 @@ export class Files {
191
191
  * the whole file checked, a range not. Nothing is asked before the first read.
192
192
  */
193
193
  #read(path, ifMatch, offset, length) {
194
- let stream;
195
- const open = () => this.#link.run('read', async (connection) => {
196
- const read = BlobsRead.encode({
197
- handle: await this.#handle(connection),
198
- folder: this.#folder,
199
- path,
200
- ifMatch,
201
- offset,
202
- length,
203
- });
204
- const opened = await connection.session.open(methods['blobs.read'], read, true);
205
- return { opened, first: await opened.next() };
206
- });
207
- return new ReadableStream({
208
- async pull(controller) {
209
- try {
210
- if (stream === undefined) {
211
- // the RESPONSE's piece is no DATA, so it takes none of the credit
212
- const { opened, first } = await open();
213
- stream = opened;
214
- enqueue(controller, first.body);
215
- if (first.end) {
216
- controller.close();
217
- }
218
- return;
219
- }
220
- const event = await stream.next();
221
- if (event.end) {
222
- controller.close();
223
- return;
224
- }
225
- stream.consumed(event.body.length);
226
- enqueue(controller, event.body);
227
- }
228
- catch (err) {
229
- controller.error(err);
230
- }
231
- },
232
- cancel() {
233
- stream?.cancel();
234
- },
235
- });
194
+ const at = { folder: this.#folder, path, ifMatch, offset, length };
195
+ return readStream(this.#link, connection => this.#handle(connection), at);
236
196
  }
237
197
  async #move(method, from, to, ifMatch) {
238
198
  const answer = await this.#call(method, handle => BlobsMove.encode({ handle, folder: this.#folder, from, to, ifMatch }), 'write');
@@ -394,9 +354,15 @@ export class FileBytes {
394
354
  // a copy, which a Buffer's slice under Node is not
395
355
  return new Uint8Array(this.#held);
396
356
  }
397
- const whole = new Uint8Array(this.size);
357
+ let whole = new Uint8Array(this.size);
398
358
  let at = 0;
399
359
  for await (const piece of this.stream()) {
360
+ // a growing directory's file reads past the size its get gave
361
+ if (at + piece.length > whole.length) {
362
+ const grown = new Uint8Array(Math.max(at + piece.length, whole.length * 2));
363
+ grown.set(whole.subarray(0, at));
364
+ whole = grown;
365
+ }
400
366
  whole.set(piece, at);
401
367
  at += piece.length;
402
368
  }
@@ -455,6 +421,47 @@ export class StoredFile extends FileBytes {
455
421
  return new FileBytes(to - from, () => this.#read(from, to - from));
456
422
  }
457
423
  }
424
+ /**
425
+ * A file's bytes as S3's GET reads them with a range and If-Match, on the
426
+ * handle `handle` opens on a connection; nothing is asked before the first read.
427
+ */
428
+ export function readStream(link, handle, at) {
429
+ let stream;
430
+ const open = () => link.run('read', async (connection) => {
431
+ const read = BlobsRead.encode({ ...at, handle: await handle(connection) });
432
+ const opened = await connection.session.open(methods['blobs.read'], read, true);
433
+ return { opened, first: await opened.next() };
434
+ });
435
+ return new ReadableStream({
436
+ async pull(controller) {
437
+ try {
438
+ if (stream === undefined) {
439
+ // the RESPONSE's piece is no DATA, so it takes none of the credit
440
+ const { opened, first } = await open();
441
+ stream = opened;
442
+ enqueue(controller, first.body);
443
+ if (first.end) {
444
+ controller.close();
445
+ }
446
+ return;
447
+ }
448
+ const event = await stream.next();
449
+ if (event.end) {
450
+ controller.close();
451
+ return;
452
+ }
453
+ stream.consumed(event.body.length);
454
+ enqueue(controller, event.body);
455
+ }
456
+ catch (err) {
457
+ controller.error(err);
458
+ }
459
+ },
460
+ cancel() {
461
+ stream?.cancel();
462
+ },
463
+ });
464
+ }
458
465
  /** A place in bytes as Blob.slice reads one: negative from the end, and within the size. */
459
466
  function placeOf(place, size, absent) {
460
467
  if (place === undefined) {
@@ -614,7 +621,7 @@ function writtenOf(body) {
614
621
  const written = BlobsWritten.decode(body);
615
622
  return written.info === undefined ? undefined : infoOf(written.info);
616
623
  }
617
- function infoOf(info) {
624
+ export function infoOf(info) {
618
625
  return {
619
626
  path: info.path ?? '',
620
627
  size: info.size ?? 0,
@@ -626,7 +633,7 @@ function infoOf(info) {
626
633
  };
627
634
  }
628
635
  /** A folder's segment as text, an integer its decimal spelling; the server refuses one that is not a segment. */
629
- function segmentOf(segment) {
636
+ export function segmentOf(segment) {
630
637
  if (typeof segment === 'number' && !Number.isSafeInteger(segment)) {
631
638
  throw new InvalidError(`the folder segment ${segment}: a segment is text or an integer`);
632
639
  }
package/dist/console.d.ts CHANGED
@@ -35,9 +35,12 @@ export declare function jsonLine(line: ConsoleLine): string;
35
35
  /**
36
36
  * A line as a person reads it: the time of day, the level padded to five, the
37
37
  * stream, the message, the context's fields and the attributes', and the
38
- * trace's first eight digits. A value of several lines, a stack or a
39
- * traceback, follows the line, indented. A key or a string shows without its
40
- * quotes when it is one word with no '=', quote or backslash.
38
+ * trace's first eight digits. A message's further lines, and then a value of
39
+ * several lines, a stack or a traceback, follow the line, indented, so that
40
+ * none of them starts where a line does. A key or a string shows without its
41
+ * quotes when it is one word with no '=', quote or backslash. What a program
42
+ * logged shows no control character but a tab: the message, the event's name,
43
+ * a value below the line and a source each show it as its escape.
41
44
  */
42
45
  export declare function prettyLine(line: ConsoleLine, look: Look): string;
43
46
  /** A level as slog spells it: INFO, WARN+2, DEBUG-4. */
package/dist/console.js CHANGED
@@ -46,9 +46,12 @@ const cyan = '\x1b[36m';
46
46
  /**
47
47
  * A line as a person reads it: the time of day, the level padded to five, the
48
48
  * stream, the message, the context's fields and the attributes', and the
49
- * trace's first eight digits. A value of several lines, a stack or a
50
- * traceback, follows the line, indented. A key or a string shows without its
51
- * quotes when it is one word with no '=', quote or backslash.
49
+ * trace's first eight digits. A message's further lines, and then a value of
50
+ * several lines, a stack or a traceback, follow the line, indented, so that
51
+ * none of them starts where a line does. A key or a string shows without its
52
+ * quotes when it is one word with no '=', quote or backslash. What a program
53
+ * logged shows no control character but a tab: the message, the event's name,
54
+ * a value below the line and a source each show it as its escape.
52
55
  */
53
56
  export function prettyLine(line, look) {
54
57
  const paint = (hue, text) => (look.color ? hue + text + reset : text);
@@ -61,7 +64,7 @@ export function prettyLine(line, look) {
61
64
  out += `${separator}${paint(cyan, line.stream)}`;
62
65
  separator = ' ';
63
66
  }
64
- const message = prettyMessage(line);
67
+ const [message, further] = prettyMessage(line);
65
68
  if (message !== '') {
66
69
  out += `${separator}${message}`;
67
70
  separator = ' ';
@@ -85,17 +88,46 @@ export function prettyLine(line, look) {
85
88
  if (line.traceId !== undefined) {
86
89
  field('trace', line.traceId.slice(0, 8));
87
90
  }
91
+ for (const part of further) {
92
+ out += `\n ${escaped(part)}`;
93
+ }
88
94
  for (const [key, text] of below) {
89
- text
90
- .replace(/[\r\n]+$/, '')
91
- .split('\n')
92
- .forEach((part, i) => {
93
- const shown = part.replace(/\r$/, '');
94
- out += `\n ${paint(dim, i === 0 ? `${key}: ${shown}` : shown)}`;
95
+ linesOf(text).forEach((part, i) => {
96
+ out += `\n ${paint(dim, escaped(i === 0 ? `${key}: ${part}` : part))}`;
95
97
  });
96
98
  }
97
99
  return `${out}\n`;
98
100
  }
101
+ /**
102
+ * The lines of a text of several, without the line ends after the last, and
103
+ * each without the carriage return before its newline: "line one\r\nline
104
+ * two\r\n" is line one, line two.
105
+ */
106
+ function linesOf(text) {
107
+ const lines = text.replace(/[\r\n]+$/, '').split('\n');
108
+ return lines.map(part => part.replace(/\r$/, ''));
109
+ }
110
+ /**
111
+ * Text a program logged as a pretty line shows it: each control character but
112
+ * a tab, and DEL, as its JSON escape, so that none reaches the terminal as an
113
+ * escape sequence, a carriage return or a line of its own. The colours the
114
+ * console paints with are its own, never in this text.
115
+ *
116
+ * "\x1b[2J" → \u001b[2J "a\rb" → a\rb "\x7f" → \u007f
117
+ */
118
+ function escaped(text) {
119
+ let out = '';
120
+ for (const c of text) {
121
+ const code = c.codePointAt(0);
122
+ if ((code < 0x20 && c !== '\t') || code === 0x7f) {
123
+ out += code === 0x7f ? '\\u007f' : JSON.stringify(c).slice(1, -1);
124
+ }
125
+ else {
126
+ out += c;
127
+ }
128
+ }
129
+ return out;
130
+ }
99
131
  /** A level as slog spells it: INFO, WARN+2, DEBUG-4. */
100
132
  export function levelLabel(level) {
101
133
  const spell = (base, from) => {
@@ -120,12 +152,19 @@ function prettyLevel(level) {
120
152
  const hue = level < 0 ? blue : level < 4 ? green : level < 8 ? yellow : red;
121
153
  return [levelLabel(level), hue];
122
154
  }
155
+ /**
156
+ * A log line's message, or an event's name and the message it may carry, as
157
+ * the line shows them; and the further lines of a message of several, which
158
+ * go below the line as a value's do.
159
+ */
123
160
  function prettyMessage(line) {
124
- const body = line.msg ?? '';
161
+ const [first, ...further] = linesOf(line.msg ?? '');
162
+ const body = escaped(first ?? '');
125
163
  if (line.event === undefined) {
126
- return body;
164
+ return [body, further];
127
165
  }
128
- return body === '' ? line.event : `${line.event} ${body}`;
166
+ const event = escaped(line.event);
167
+ return [body === '' ? event : `${event} ${body}`, further];
129
168
  }
130
169
  /** How a field's JSON shows, and whether it is text of several lines, which goes under the line. */
131
170
  function prettyValue(key, json) {
@@ -205,7 +244,7 @@ function shortSource(json) {
205
244
  }
206
245
  const parts = source.file.split(/[\\/]+/).filter(part => part !== '');
207
246
  const line = typeof source.line === 'number' ? source.line : 0;
208
- return `${parts.slice(-2).join('/')}:${line}`;
247
+ return escaped(`${parts.slice(-2).join('/')}:${line}`);
209
248
  }
210
249
  /** The names `redact` takes to hide the usual secrets, as Go's console.Secrets and Python's SECRETS. */
211
250
  export const secrets = Object.freeze([
@@ -0,0 +1,72 @@
1
+ import { type FileInfo, type FileListOptions, type FilePage, StoredFile } from './blobs.ts';
2
+ import type { Link } from './connection.ts';
3
+ import { type Duration } from './time.ts';
4
+ export interface DirectoryOptions {
5
+ /** The folder on the store's machine; a server's own, by the name, when left out. */
6
+ path?: string | undefined;
7
+ /** A scan on the store's background work, a period apart: minutes, not seconds. */
8
+ every?: Duration | undefined;
9
+ /** Names a scan passes over, a file's or a folder's, `*` for any run of a name's characters. */
10
+ ignore?: string[] | undefined;
11
+ /** For files written while they are read: a read holds to no version and goes up to the size now. */
12
+ growing?: boolean | undefined;
13
+ }
14
+ /** What a scan found, and what the list holds once it ended. */
15
+ export interface Scan {
16
+ added: number;
17
+ changed: number;
18
+ removed: number;
19
+ /** what it met and could not list: a link, a folder it cannot read, another disk */
20
+ skipped: number;
21
+ count: number;
22
+ size: number;
23
+ }
24
+ export type Change = 'added' | 'changed' | 'removed';
25
+ /** A file's change since a cursor: its path in the directory, and what it carries now, none once removed. */
26
+ export interface FileChange {
27
+ path: string;
28
+ change: Change;
29
+ info: FileInfo | undefined;
30
+ }
31
+ /** A page of changes in the order the scans wrote them; `next` is always there. */
32
+ export interface DirectoryChanges {
33
+ items: FileChange[];
34
+ next: string;
35
+ }
36
+ export declare function openDirectory(link: Link, name: string, options?: DirectoryOptions): Directory;
37
+ /**
38
+ * A directory, or a folder of it: `get`, `head`, `list` and `usage` are a set
39
+ * of files' calls with a set of files' answers, answered from the list the
40
+ * last scan wrote but a get's bytes, which come from the disk.
41
+ */
42
+ export declare class Directory {
43
+ #private;
44
+ readonly name: string;
45
+ /** Directories come from `store.directory`. */
46
+ constructor(link: Link, name: string, open: Uint8Array, folder: string[], growing: boolean);
47
+ /** The folder of these segments, one each, whose paths are relative to it. */
48
+ folder(...segments: (string | number | bigint)[]): Directory;
49
+ /** Walks the folder and writes down what appeared, changed or went since the last scan. */
50
+ scan(): Promise<Scan>;
51
+ /** The changes past a cursor, a page's `next`, or from the first file the directory listed. */
52
+ changes(options?: {
53
+ after?: string | undefined;
54
+ }): Promise<DirectoryChanges>;
55
+ /**
56
+ * The file as a scan listed it and as the disk holds it now; undefined when
57
+ * no scan listed it, or it is gone since. A read of a file that moved since
58
+ * fails ConflictError, but in a growing directory, which reads up to the size now.
59
+ */
60
+ get(path: string): Promise<StoredFile | undefined>;
61
+ /** What the last scan wrote down of the file; it reads no disk. */
62
+ head(path: string): Promise<FileInfo | undefined>;
63
+ /** A page of the folder's files, in the byte order of their paths, as the last scan wrote them. */
64
+ list(options?: FileListOptions): Promise<FilePage>;
65
+ /** The files the last scan listed in the folder, and their bytes. */
66
+ usage(): Promise<{
67
+ count: number;
68
+ size: number;
69
+ }>;
70
+ /** Removes every file of the list, each told removed, and nothing on the disk. */
71
+ forget(): Promise<void>;
72
+ }
@@ -0,0 +1,121 @@
1
+ // A directory, as docs/guides/blobs/directories.md has it: a folder of the
2
+ // store's machine under a name, which the store lists and reads and never
3
+ // writes. A scan writes down what appeared, changed or went; changes keep a
4
+ // copy in step from a cursor; a read comes from the disk, held to the version
5
+ // its get opened, or in a growing directory to none.
6
+ import { infoOf, readStream, StoredFile, segmentOf, } from './blobs.js';
7
+ import { checkName, handleOn, viaLink } from './handles.js';
8
+ import { ms } from './time.js';
9
+ import { BlobsAt, BlobsChanges, BlobsDirectory, BlobsFolder, BlobsGot, BlobsHead, BlobsList, BlobsPage, BlobsScanned, BlobsSince, BlobsUsage, methods, } from './wire/protocol.js';
10
+ export function openDirectory(link, name, options) {
11
+ checkName(name, 'directory');
12
+ const open = BlobsDirectory.encode({
13
+ name,
14
+ path: options?.path,
15
+ every: options?.every === undefined ? undefined : ms(options.every),
16
+ ignore: options?.ignore ?? [],
17
+ growing: options?.growing === true,
18
+ });
19
+ return new Directory(link, name, open, [], options?.growing === true);
20
+ }
21
+ /**
22
+ * A directory, or a folder of it: `get`, `head`, `list` and `usage` are a set
23
+ * of files' calls with a set of files' answers, answered from the list the
24
+ * last scan wrote but a get's bytes, which come from the disk.
25
+ */
26
+ export class Directory {
27
+ name;
28
+ #link;
29
+ #via;
30
+ #open;
31
+ #folder;
32
+ #growing;
33
+ /** Directories come from `store.directory`. */
34
+ constructor(link, name, open, folder, growing) {
35
+ this.name = name;
36
+ this.#link = link;
37
+ this.#via = viaLink(link);
38
+ this.#open = open;
39
+ this.#folder = folder;
40
+ this.#growing = growing;
41
+ }
42
+ /** The folder of these segments, one each, whose paths are relative to it. */
43
+ folder(...segments) {
44
+ const folder = [...this.#folder, ...segments.map(segmentOf)];
45
+ return new Directory(this.#link, this.name, this.#open, folder, this.#growing);
46
+ }
47
+ /** Walks the folder and writes down what appeared, changed or went since the last scan. */
48
+ async scan() {
49
+ const answer = await this.#call('blobs.scan', handle => BlobsFolder.encode({ handle, folder: this.#folder }), 'write');
50
+ const scan = BlobsScanned.decode(answer);
51
+ return {
52
+ added: scan.added ?? 0,
53
+ changed: scan.changed ?? 0,
54
+ removed: scan.removed ?? 0,
55
+ skipped: scan.skipped ?? 0,
56
+ count: scan.count ?? 0,
57
+ size: scan.size ?? 0,
58
+ };
59
+ }
60
+ /** The changes past a cursor, a page's `next`, or from the first file the directory listed. */
61
+ async changes(options) {
62
+ const answer = await this.#call('blobs.changes', handle => BlobsSince.encode({ handle, after: options?.after }), 'read');
63
+ const page = BlobsChanges.decode(answer);
64
+ const items = (page.items ?? []).map(item => ({
65
+ path: item.path ?? '',
66
+ change: (item.change ?? 'added'),
67
+ info: item.info === undefined ? undefined : infoOf(item.info),
68
+ }));
69
+ return { items, next: page.next ?? '0' };
70
+ }
71
+ /**
72
+ * The file as a scan listed it and as the disk holds it now; undefined when
73
+ * no scan listed it, or it is gone since. A read of a file that moved since
74
+ * fails ConflictError, but in a growing directory, which reads up to the size now.
75
+ */
76
+ async get(path) {
77
+ const answer = await this.#call('blobs.get', handle => BlobsAt.encode({ handle, folder: this.#folder, path }), 'read');
78
+ const got = BlobsGot.view(answer);
79
+ if (got.info === undefined) {
80
+ return undefined;
81
+ }
82
+ const info = infoOf(got.info);
83
+ const bytes = got.bytes ?? new Uint8Array();
84
+ // a growing file's bytes come from the disk as it is when they are read
85
+ const whole = !this.#growing && bytes.length === info.size ? bytes : undefined;
86
+ const ifMatch = this.#growing ? undefined : info.etag;
87
+ const handle = (connection) => handleOn(connection, methods['blobs.directory'], this.#open);
88
+ return new StoredFile(info, whole, (offset, length) => readStream(this.#link, handle, { folder: this.#folder, path, ifMatch, offset, length }));
89
+ }
90
+ /** What the last scan wrote down of the file; it reads no disk. */
91
+ async head(path) {
92
+ const answer = await this.#call('blobs.head', handle => BlobsAt.encode({ handle, folder: this.#folder, path }), 'read');
93
+ const head = BlobsHead.decode(answer);
94
+ return head.info === undefined ? undefined : infoOf(head.info);
95
+ }
96
+ /** A page of the folder's files, in the byte order of their paths, as the last scan wrote them. */
97
+ async list(options) {
98
+ const answer = await this.#call('blobs.list', handle => BlobsList.encode({
99
+ handle,
100
+ folder: this.#folder,
101
+ prefix: options?.prefix ?? '',
102
+ after: options?.after,
103
+ limit: options?.limit,
104
+ }), 'read');
105
+ const page = BlobsPage.decode(answer);
106
+ return { files: (page.files ?? []).map(infoOf), next: page.next };
107
+ }
108
+ /** The files the last scan listed in the folder, and their bytes. */
109
+ async usage() {
110
+ const answer = await this.#call('blobs.usage', handle => BlobsFolder.encode({ handle, folder: this.#folder }), 'read');
111
+ const usage = BlobsUsage.decode(answer);
112
+ return { count: usage.count ?? 0, size: usage.size ?? 0 };
113
+ }
114
+ /** Removes every file of the list, each told removed, and nothing on the disk. */
115
+ async forget() {
116
+ await this.#call('blobs.forget', handle => BlobsFolder.encode({ handle, folder: this.#folder }), 'write');
117
+ }
118
+ #call(method, body, idempotence) {
119
+ return this.#via.call(methods['blobs.directory'], this.#open, methods[method], body, idempotence);
120
+ }
121
+ }
package/dist/index.d.ts CHANGED
@@ -6,9 +6,10 @@ export type { Clock } from './clock.ts';
6
6
  export { type Bounds, type Changes, type Chosen, type Config, type ConfigOptions, chosenBy, type DurationBounds, duration, type Entries, type EntriesOptions, type EnvLayer, type EnvOptions, type Explained, type ExplainGiven, type ExplainLine, type ExplainOrigin, entries, env, type FileLayer, file, int, type Layer, list, live, type Overlay, oneOf, optional, required, Secret, type Setting, secret, type UpdateOptions, type Value, type Vars, } from './config.ts';
7
7
  export type { Durability, SelfMetrics } from './connection.ts';
8
8
  export { type ConsoleFormat, type ConsoleTime, secrets } from './console.ts';
9
+ export type { Change, Directory, DirectoryChanges, DirectoryOptions, FileChange, Scan, } from './directory.ts';
9
10
  export * from './errors.ts';
10
11
  export type { Page } from './handles.ts';
11
- export type { Adding, AddOptions, Answer, Backoff, Concurrency, Handler, Job, JobOptions, JobPage, JobState, ListOptions, Queue, QueueOptions, Run, Schedule, ScheduleOptions, ScheduleWhen, StoreTxQueue, TxQueue, Worker, WorkOptions, } from './jobs.ts';
12
+ export type { Adding, AddOptions, Answer, Backoff, Concurrency, Handler, Job, JobCounts, JobOptions, JobPage, JobState, ListOptions, Queue, QueueOptions, Run, Schedule, ScheduleOptions, ScheduleWhen, StoreTxQueue, TxQueue, Worker, WorkOptions, } from './jobs.ts';
12
13
  export type { Bucket, BucketOptions, Counters, CountersOptions, Entry, Page as KvPage, ValueType, WriteOptions, } from './kv.ts';
13
14
  export type { Allowance, Quota, Rate, RateLimit, RateLimitOptions, WindowUse } from './limits.ts';
14
15
  export type { HoldOptions, Lease, Lock, LockOptions, Permit, Semaphore, SemaphoreOptions, Tried, } from './locks.ts';
package/dist/jobs.d.ts CHANGED
@@ -92,6 +92,16 @@ export interface ListOptions {
92
92
  /** jobs a page holds at most: 100, 1000 at most */
93
93
  limit?: number | undefined;
94
94
  }
95
+ /** How many jobs a queue holds in each state, from one snapshot; a done job has left it. */
96
+ export interface JobCounts {
97
+ /** due later */
98
+ scheduled: number;
99
+ /** due, and no handler runs it yet */
100
+ waiting: number;
101
+ running: number;
102
+ /** kept for the queue's keep */
103
+ failed: number;
104
+ }
95
105
  /** A page of a queue's jobs, and where the next starts when there is one. */
96
106
  export interface JobPage<T> {
97
107
  jobs: Job<T>[];
@@ -261,17 +271,25 @@ export declare class Queue<T> {
261
271
  */
262
272
  set(id: string, value: T, options?: JobOptions): Promise<void>;
263
273
  /**
264
- * Changes the id's job when it has not started: its value, and its time,
265
- * group or repeat when the options give them. It says whether it did: a
266
- * job that runs, ran or never was answers false.
274
+ * Changes the id's job when it is not running: its value, the steps kept
275
+ * for the old one dropped with it, and its time, group or repeat when the
276
+ * options give them. It says whether it did: a job that runs, is done or
277
+ * failed, or never was answers false.
267
278
  */
268
279
  update(id: string, value: T, options?: JobOptions): Promise<boolean>;
269
280
  /**
270
- * Takes the job under id, whatever its state, and says whether there was
271
- * one. A running one's handler sees its signal abort, and what it returns
281
+ * Takes a job, whatever its state, and says whether it was there: the job
282
+ * under an id, or a job a list gave, by its id or, for one without, by the
283
+ * row it was listed from. A job retried, run again for its repeat or
284
+ * cancelled since is in no row, and its cancel takes nothing, never another
285
+ * job. A running one's handler sees its signal abort, and what it returns
272
286
  * then settles nothing; a repeating one stops.
287
+ *
288
+ * for await (const job of emails.all({ state: 'scheduled' })) if (job.value.to === bounced) await emails.cancel(job)
273
289
  */
274
- cancel(id: string): Promise<boolean>;
290
+ cancel(job: Job<T> | string): Promise<boolean>;
291
+ /** How many jobs the queue holds in each state, from one snapshot; it reads no value. */
292
+ counts(): Promise<JobCounts>;
275
293
  /**
276
294
  * Where the job under id is: scheduled, waiting and how many jobs are
277
295
  * ahead of it, running and its progress, failed and why, or done while
@@ -288,9 +306,16 @@ export declare class Queue<T> {
288
306
  * for await (const job of videos.watch(id)) send(job.state, job.ahead, job.progress)
289
307
  */
290
308
  watch(id: string): AsyncGenerator<Job<T>>;
291
- /** A page of the queue's jobs whose ids start with a prefix, or of its failed ones. */
309
+ /**
310
+ * A page of the queue's jobs: with no prefix every job, those with ids by id,
311
+ * then those without as they run, then those without that failed.
312
+ */
292
313
  list(options?: ListOptions): Promise<JobPage<T>>;
293
- /** Every job the options name, a page at a time, holding nothing between pages. */
314
+ /**
315
+ * Every job the options name, a page at a time, holding nothing between
316
+ * pages. A job whose value no longer reads is a CorruptError in its place,
317
+ * naming it, and iterating the same walk again goes on past it.
318
+ */
294
319
  all(options?: Omit<ListOptions, 'after'>): AsyncGenerator<Job<T>>;
295
320
  /**
296
321
  * Runs handler on each job as it falls due, as many at once as the
@@ -323,7 +348,7 @@ export declare class TxQueue<T> {
323
348
  add(value: T, options?: AddOptions): Promise<boolean>;
324
349
  set(id: string, value: T, options?: JobOptions): Promise<void>;
325
350
  update(id: string, value: T, options?: JobOptions): Promise<boolean>;
326
- cancel(id: string): Promise<boolean>;
351
+ cancel(job: Job<T> | string): Promise<boolean>;
327
352
  /** The job under id as the transaction sees it, its own writes among it. */
328
353
  get(id: string): Promise<Job<T> | undefined>;
329
354
  }
@@ -348,12 +373,15 @@ export declare function addingIn(adding: Adding, home: Home): (connection: Conne
348
373
  method: number;
349
374
  body: Uint8Array;
350
375
  }>;
351
- /** A write the store's transaction keeps for its commit: its method, and its call or the id it cancels. */
376
+ /** A write the store's transaction keeps for its commit: its method, and its call or the job it cancels. */
352
377
  export interface JobOp {
353
378
  source: Source<unknown>;
354
379
  method: number;
355
380
  call?: Omit<Written<typeof JobsCall.fields>, 'handle'>;
356
- id?: string;
381
+ id?: {
382
+ id?: string;
383
+ row?: string;
384
+ };
357
385
  }
358
386
  /**
359
387
  * A queue's writes inside the store's transaction, from `tx.with(queue)` in
@@ -373,10 +401,10 @@ export declare class StoreTxQueue<T> {
373
401
  add(value: T, options?: AddOptions): Promise<void>;
374
402
  /** Makes the id's job this value at this time, whatever it was, with the commit. */
375
403
  set(id: string, value: T, options?: JobOptions): Promise<void>;
376
- /** Changes the id's job when it has not started, with the commit. */
404
+ /** Changes the id's job when it is not running, its old value's steps dropped, with the commit. */
377
405
  update(id: string, value: T, options?: JobOptions): Promise<void>;
378
- /** Takes the job under id, whatever its state, with the commit. */
379
- cancel(id: string): Promise<void>;
406
+ /** Takes the job under id, or a job a list gave, whatever its state, with the commit. */
407
+ cancel(job: Job<T> | string): Promise<void>;
380
408
  }
381
409
  /** Sends a transaction's writes of jobs as one jobs.tx: all of them are made, or none. */
382
410
  export declare function commitJobs(link: Link, ops: readonly JobOp[]): Promise<void>;