@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.7

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.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/dist/jobs.d.ts CHANGED
@@ -1,304 +1,400 @@
1
- import { type Link } from './connection.ts';
1
+ import type { Link } from './connection.ts';
2
+ import { type Home, type Open, type Via } from './handles.ts';
3
+ import { type Rate } from './limits.ts';
2
4
  import { type StandardSchemaV1 } from './schema.ts';
3
- import type { Database, SqlBatch } from './sql.ts';
5
+ import { type Stream } from './session.ts';
4
6
  import { type Duration, type Time } from './time.ts';
5
- import { JobsHeld, JobsOutcome } from './wire/messages.ts';
7
+ import type { Read, Written } from './wire/codec.ts';
8
+ import { JobsAnswer, JobsCall, JobsHeld } from './wire/protocol.ts';
9
+ /** How many jobs of a queue run at once: in all, across every worker of the store, and in each group. */
10
+ export interface Concurrency {
11
+ total?: number | undefined;
12
+ /** at most this many jobs of one group at once: one customer's backlog holds back no other */
13
+ group?: number | undefined;
14
+ }
15
+ /** The wait before a retry: initial, doubling each time up to max, a tenth longer or shorter at random. */
16
+ export interface Backoff {
17
+ initial: Duration;
18
+ max: Duration;
19
+ }
6
20
  export interface QueueOptions {
7
- /** how long a claim holds a job before it is given back: 30 s */
8
- lease?: Duration;
9
- /** the attempts after which a job fails for good: 10 */
10
- maxAttempts?: number;
11
- /** a retry's wait, doubling from first to most: a second to an hour */
12
- backoff?: {
13
- first?: Duration;
14
- most?: Duration;
15
- };
16
- /** the jobs a queue holds before it refuses the next with LimitError: ten million */
17
- maxWaiting?: number;
18
- /** how long a failed job is kept for Get and Scan: seven days */
19
- keepFailed?: Duration;
20
- /** remembers a done job's key this long, so that enqueuing it again adds nothing */
21
- keepDone?: Duration;
22
- /** the jobs that may run at once, across every worker of the store: no bound */
23
- maxRunning?: number;
24
- /**
25
- * keeps the queue in this database's file instead of jobs.db, so that a
26
- * batch of the database commits a job with its rows: `queue.withTx(tx)`
27
- */
28
- in?: Database;
21
+ /** runs a job gets before it fails for good, the first counted: 10 */
22
+ attempts?: number | undefined;
23
+ /** 1s doubling up to 1h */
24
+ backoff?: Backoff | undefined;
25
+ /** how long one run may take before its signal aborts: a minute */
26
+ timeout?: Duration | undefined;
27
+ /** jobs running at once across every worker of the store: 8, or { total: 8, group: 2 }; one a worker unless given */
28
+ concurrency?: number | Concurrency | undefined;
29
+ /** jobs started in any span: '30/s' */
30
+ rate?: Rate | undefined;
31
+ /** how long a done job's id stays taken, so that an add of it adds nothing */
32
+ dedupe?: Duration | undefined;
33
+ /** how long a failed job stays, to be found and started again: a week */
34
+ keep?: Duration | undefined;
35
+ /** jobs that may wait; an add past it is LimitError: ten million */
36
+ maxWaiting?: number | undefined;
29
37
  }
30
- /** When a job runs again: cron text in a zone by its name, a daily time, or every so often. */
31
- export type Repeat = {
32
- cron: string;
33
- zone: string;
34
- } | {
35
- daily: string;
36
- zone: string;
37
- } | {
38
- every: Duration;
39
- };
40
- export interface EnqueueOptions {
41
- /** the job's time; one past runs now */
42
- at?: Time;
43
- after?: Duration;
44
- /** names one job: enqueuing it again adds nothing and can bring it forward, never back */
45
- key?: string;
46
- /** needs a key, since only a key stops it */
47
- repeat?: Repeat;
38
+ /** A job's time, group and repeat, as an add, a set and an update take them. */
39
+ export interface JobOptions {
40
+ /** runs at this time, one past now; not beside delay */
41
+ at?: Time | undefined;
42
+ /** runs this long from now */
43
+ delay?: Duration | undefined;
44
+ /** the group whose running jobs the queue's concurrency.group bounds */
45
+ group?: string | undefined;
46
+ /** repeats every span, each id at a phase of its own within it; needs an id */
47
+ every?: Duration | undefined;
48
+ /** repeats by five cron fields, or @daily and its kind, on timeZone's wall clock; needs an id */
49
+ cron?: string | undefined;
50
+ /** an IANA name, 'UTC' among them, which a cron needs: one given as undefined is InvalidError, never UTC */
51
+ timeZone?: string | undefined;
48
52
  }
49
- /** done while keepDone keeps its key; cancelled only a watcher sees */
50
- export type JobState = 'waiting' | 'running' | 'failed' | 'done' | 'cancelled';
51
- export interface JobEntry<T> {
52
- key: string;
53
+ export interface AddOptions extends JobOptions {
54
+ /** the job's id, 1 to 1024 bytes: what finds it again, and adds it once */
55
+ id?: string | undefined;
56
+ }
57
+ /** done while dedupe keeps its id; cancelled only a watcher sees */
58
+ export type JobState = 'scheduled' | 'waiting' | 'running' | 'done' | 'failed' | 'cancelled';
59
+ /** A job as its queue holds it. */
60
+ export interface Job<T> {
61
+ id: string | undefined;
53
62
  value: T;
54
- /** the time it runs for */
63
+ state: JobState;
64
+ /** when it runs next; for one done or failed, when its last run was for */
55
65
  at: Date;
56
66
  /** its attempts, a running one included */
57
67
  attempt: number;
58
- state: JobState;
59
- /** the jobs that run before a waiting one, up to 10,000; get and watch count it, scan leaves it 0 */
68
+ /** the jobs that run before a waiting one, up to 10,000 */
60
69
  ahead: number;
61
- /** what a running job's handler last reported with job.progress */
70
+ /** what its handler last reported of a running job */
62
71
  progress: unknown;
63
- /** when the last run a handler finished began: acknowledged, retried, failed or snoozed */
64
- ran: Date | undefined;
65
- /** how many milliseconds that run took */
66
- took: number | undefined;
67
- /** its last failure */
72
+ /** why its last run failed */
68
73
  error: string | undefined;
69
- /** a repeating job's cron text and zone */
74
+ group: string | undefined;
75
+ /** a repeating job's repeat as it keeps it: '@every 30s +6178ms', '10 3 * * * Europe/Berlin' */
70
76
  repeat: string | undefined;
77
+ /** when the last run a handler finished started and ended */
78
+ lastRun: {
79
+ startedAt: Date;
80
+ endedAt: Date;
81
+ } | undefined;
82
+ }
83
+ export interface ListOptions {
84
+ /** ids that start with it, in their byte order: end it with a separator, 'chat:4:' */
85
+ prefix?: string | undefined;
86
+ /** the jobs in this state alone; 'failed' with no prefix lists the last failed first */
87
+ state?: 'scheduled' | 'waiting' | 'running' | 'failed' | undefined;
88
+ /** where the page before ended: its next */
89
+ after?: string | undefined;
90
+ /** jobs a page holds at most: 100, 1000 at most */
91
+ limit?: number | undefined;
92
+ }
93
+ /** A page of a queue's jobs, and where the next starts when there is one. */
94
+ export interface JobPage<T> {
95
+ jobs: Job<T>[];
96
+ next: string | undefined;
71
97
  }
72
98
  export interface WorkOptions {
73
- /** the jobs in this process's hands at once: 1, the one order a queue promises */
74
- workers?: number;
75
- /** how long a job may be in the handler's hands, after which its attempt fails: a minute */
76
- timeout?: Duration;
77
- /** stops taking jobs: the ones in hand finish first, and work returns */
78
- signal?: AbortSignal;
79
- /** returns once no job is due and none runs, as a test wants it */
80
- untilIdle?: boolean;
99
+ /** the handlers this worker runs at once, under the queue's bound: its total, or one */
100
+ concurrency?: number | undefined;
81
101
  }
82
- type Settlement = {
83
- how: 'ack';
84
- } | {
85
- how: 'retry';
86
- error: string;
87
- at?: Time;
88
- after?: Duration;
89
- } | {
90
- how: 'fail';
91
- error: string;
92
- } | {
93
- how: 'snooze';
94
- at?: Time;
95
- after?: Duration;
96
- };
97
102
  /**
98
- * Sends what a handler reports of its job: the latest, one send at a time
99
- * and at most one each 100 ms, so that a handler reporting each chunk it
100
- * reads costs the connection ten frames a second.
103
+ * What runs a job: it gets the job's value and its run. Returning ends the
104
+ * job done, throwing runs it again after its backoff, and returning what
105
+ * run.retry, run.snooze or run.fail made ends it so.
101
106
  */
102
- declare class Reporter {
103
- #private;
104
- constructor(send: (text: string) => Promise<void>);
105
- report(text: string): void;
106
- /** Drops what waits and lets what is being sent finish, before the job's outcome follows it. */
107
- stop(): Promise<void>;
107
+ export type Handler<T> = (value: T, run: Run) => unknown;
108
+ /** When a schedule runs: every span, or by a cron on a time zone's wall clock. */
109
+ export type ScheduleWhen = {
110
+ every: Duration;
111
+ } | {
112
+ cron: string;
113
+ timeZone: string;
114
+ };
115
+ export interface ScheduleOptions {
116
+ /** runs a time gets before it fails, the first counted: 10; the schedule goes on */
117
+ attempts?: number | undefined;
118
+ backoff?: Backoff | undefined;
119
+ /** how long one run may take before its signal aborts: a minute */
120
+ timeout?: Duration | undefined;
108
121
  }
109
- /** Calls a method on the connection a job is held on, answering its body. */
110
- type Call = (method: number, body: Uint8Array) => Promise<Uint8Array>;
111
- /**
112
- * The steps of a held job's run, which the server keeps under the number the
113
- * job was held by: a step's kept answer, or the step run and its answer kept.
114
- */
115
- declare class Steps {
122
+ /** A run's answer as the stream carries it. */
123
+ type AnswerFields = Omit<Written<typeof JobsAnswer.fields>, 'run'>;
124
+ /** How a run ends otherwise than done, made by run.retry, run.snooze or run.fail: its handler returns it. */
125
+ export declare class Answer {
116
126
  #private;
117
- constructor(call: Call, job: number);
118
- run<R>(name: string, fn: () => R | Promise<R>): Promise<R>;
127
+ /** Answers come from a run. */
128
+ constructor(how: string);
129
+ toString(): string;
119
130
  }
120
- /**
121
- * A job in a work loop's handler. Returning acknowledges it and throwing
122
- * retries it, unless the handler said otherwise with retry, fail or snooze;
123
- * the last of those it calls is how the job settles.
124
- */
125
- export declare class Job<T> {
131
+ /** What a run is made of, which its worker gives it. */
132
+ interface RunParts {
133
+ held: Read<typeof JobsHeld.fields>;
134
+ signal: AbortSignal;
135
+ steps: Steps;
136
+ reporter: Reporter;
137
+ /** the answers the run made, which the worker reads what the handler returned against */
138
+ made: Map<Answer, AnswerFields>;
139
+ }
140
+ /** This call on a job: what it is, its signal, its steps and progress, and the answers its handler returns. */
141
+ export declare class Run {
126
142
  #private;
127
- readonly key: string;
128
- readonly value: T;
129
- /** the time it ran for */
143
+ /** the job's id, undefined for one added without */
144
+ readonly id: string | undefined;
145
+ /** when the run was due, which "thirty days ago" counts from even when it starts late */
130
146
  readonly at: Date;
131
- /** its attempts, this one included */
147
+ /** this run's number among the job's attempts, the first being 1 */
132
148
  readonly attempt: number;
149
+ readonly group: string | undefined;
133
150
  /**
134
- * aborts when the job's timeout passes, its loop stops, or cancel takes it,
151
+ * aborts when the run passes its timeout, or when a cancel takes the job,
135
152
  * whose reason is then a CancelledError: the handler should stop too
136
153
  */
137
154
  readonly signal: AbortSignal;
138
- settlement: Settlement | undefined;
139
- constructor(key: string, value: T, at: Date, attempt: number, signal: AbortSignal, reporter?: Reporter, steps?: Steps);
155
+ /** Runs come to a handler from its worker. */
156
+ constructor(parts: RunParts);
140
157
  /**
141
- * Runs fn once in the job's run and keeps what it answers, as JSON: an
142
- * attempt after a retry, a lost lease or a restart gets the kept answer
143
- * back without running fn again. A step whose attempt ends before its
144
- * answer is kept runs again, so what fn does outside the store should bear
145
- * doing twice. A name is the step's within the run, which a loop numbers:
146
- * 'model:1', 'tool:1', 'model:2'. An answer is at most 1 MiB of JSON.
158
+ * Runs fn once in the job's run and keeps its answer, as JSON, across the
159
+ * job's attempts: the attempt after a retry, a lost worker or a restart
160
+ * gets the answer back without running fn again. A step whose attempt
161
+ * ends before its answer is kept runs again, so what fn does outside the
162
+ * store should bear doing twice. A name is the step's within its job,
163
+ * numbered in a loop: 'model:1', 'tool:1'.
147
164
  *
148
- * const hits = await job.step('search', () => search(job.value.query))
165
+ * const found = await run.step('search', () => search(question.text))
149
166
  */
150
167
  step<R>(name: string, fn: () => R | Promise<R>): Promise<R>;
151
168
  /**
152
- * Reports how far the job got, any JSON within 4 KiB: get and watch show
153
- * the latest until the job is settled. It does not wait for the server.
154
- *
155
- * await transcode({ signal: job.signal, onProgress: p => job.progress(p) })
169
+ * Shows how far the job got, any JSON within 4 KiB, to get: the latest
170
+ * goes, ten a second at most, and nothing waits for the server.
156
171
  */
157
- progress(progress: unknown): void;
158
- /** Fails this attempt: the job runs again after its backoff, or at the time given. */
159
- retry(error?: unknown, when?: {
160
- at?: Time;
161
- after?: Duration;
162
- }): void;
163
- /** Fails the job for good, keeping it for keepFailed with its reason. */
164
- fail(error?: unknown): void;
165
- /** Moves the job to another time without counting the attempt. */
166
- snooze(when: {
167
- at?: Time;
168
- after?: Duration;
169
- }): void;
172
+ setProgress(progress: unknown): void;
173
+ /** Runs the job again after its backoff, or at the time given, the run counted as an attempt: return it. */
174
+ retry(when?: Duration | Date): Answer;
175
+ /** Runs the job again at the time given, the run not counted: return it. */
176
+ snooze(when: Duration | Date): Answer;
177
+ /** Fails the job for good now, its reason kept as its error: return it. */
178
+ fail(reason: string | Error): Answer;
179
+ }
180
+ /**
181
+ * Sends what a handler reports of its job: the latest, one send at a time
182
+ * and at most one each 100 ms, so that a handler reporting each chunk it
183
+ * reads costs the connection ten frames a second.
184
+ */
185
+ declare class Reporter {
186
+ #private;
187
+ constructor(send: (text: string) => Promise<void>);
188
+ report(text: string): void;
189
+ /** Drops what waits and lets what is being sent finish, before the run's answer follows it. */
190
+ stop(): Promise<void>;
170
191
  }
171
- /** A job a claim leased, which its caller settles itself before the lease ends. */
172
- export declare class ClaimedJob<T> {
192
+ /** Calls a method on the connection a job is held on, answering its body. */
193
+ type Call = (method: number, body: Uint8Array) => Promise<Uint8Array>;
194
+ /** The steps of a held job's run, which the server keeps under the run's number on its connection. */
195
+ declare class Steps {
173
196
  #private;
174
- readonly key: string;
175
- readonly value: T;
176
- readonly at: Date;
177
- readonly attempt: number;
178
- constructor(held: ReturnType<typeof JobsHeld.decode>, value: T, settle: (outcome: Parameters<typeof JobsOutcome.encode>[0]) => Promise<void>, call: Call);
179
- /** Runs fn once in the job's run and keeps its answer, as a work loop's job.step does. */
180
- step<R>(name: string, fn: () => R | Promise<R>): Promise<R>;
181
- /** The job is done. */
182
- ack(): Promise<void>;
183
- retry(error?: unknown, when?: {
184
- at?: Time;
185
- after?: Duration;
186
- }): Promise<void>;
187
- fail(error?: unknown): Promise<void>;
188
- snooze(when: {
189
- at?: Time;
190
- after?: Duration;
191
- }): Promise<void>;
192
- /** Holds the job this much longer from now. */
193
- extend(d: Duration): Promise<void>;
194
- /** Reports how far the job got, any JSON within 4 KiB, which get and watch show until it is settled. */
195
- progress(progress: unknown): Promise<void>;
197
+ constructor(call: Call, run: number, cancelled: AbortSignal);
198
+ run<R>(name: string, fn: () => R | Promise<R>): Promise<R>;
196
199
  }
197
- /** Encodes a queue's values as JSON, the text every language reads, and back. */
200
+ /** A queue's values: JSON, checked by its schema when it has one. */
198
201
  interface Values<T> {
199
202
  encode(value: T): string;
200
- decode(text: string): T | Promise<T>;
203
+ decode(text: string): Promise<T>;
201
204
  }
202
- export declare class Jobs {
203
- #private;
204
- constructor(link: Link);
205
- /** A queue of JSON values of type T. */
206
- queue<T = unknown>(name: string, options?: QueueOptions): Queue<T>;
207
- /** A queue whose values each claim checks, with zod's, valibot's or another Standard Schema. */
208
- queue<S extends StandardSchemaV1>(name: string, schema: S, options?: QueueOptions): Queue<StandardSchemaV1.InferOutput<S>>;
209
- /**
210
- * A schedule: a queue of one job under the schedule's name, which repeats
211
- * as it says. work runs it; cancel stops it.
212
- */
213
- schedule(name: string, repeat: Repeat, options?: QueueOptions): Queue<null>;
205
+ /** What a queue's or a schedule's calls and workers need of it. */
206
+ interface Source<T> {
207
+ link: Link;
208
+ /** 'jobs queue emails', which an error names */
209
+ describe: string;
210
+ openMethod: number;
211
+ open: Open;
212
+ /** the database whose file keeps the queue; the store's jobs.db when undefined */
213
+ home?: Home | undefined;
214
+ /** how its calls reach the server: the link's connection, or a database's transaction */
215
+ via: Via;
216
+ values: Values<T>;
217
+ /** a run's timeout, in milliseconds */
218
+ timeout: number;
219
+ /** the store's running workers, which its close stops */
220
+ workers: Set<Worker>;
214
221
  }
215
- /** A queue's enqueue inside a batch of the database it lives in. */
216
- export declare class QueueTx<T> {
217
- #private;
218
- constructor(tx: SqlBatch, open: Uint8Array, values: Values<T>);
219
- /** Adds a job to the batch; it settles once the batch has committed. */
220
- enqueue(value: T, options?: EnqueueOptions): Promise<void>;
222
+ /** What a database's transaction needs of a queue it takes in. */
223
+ export interface QueueParts {
224
+ readonly name: string;
225
+ readonly source: Source<unknown>;
221
226
  }
227
+ /** A queue of jobs of one type, run in the order of their time: open it with `store.queue(name)`. */
222
228
  export declare class Queue<T> {
223
229
  #private;
224
230
  readonly name: string;
225
- constructor(link: Link, name: string, open: Uint8Array, values: Values<T>, inDatabase: Database | undefined);
231
+ /** Queues come from `store.queue` and `db.queue`. */
232
+ constructor(source: Source<T>, name: string);
233
+ /**
234
+ * Adds a job unless its id is taken: by a job scheduled, waiting, running
235
+ * or failed, or done while the queue's dedupe keeps it. It returns once
236
+ * the job is on disk, and says whether it added one; a job without an id
237
+ * is always added.
238
+ *
239
+ * await reminders.add({ userId: 42, text: 'Call mom' }, { delay: '1h' })
240
+ */
241
+ add(value: T, options?: AddOptions): Promise<boolean>;
226
242
  /**
227
- * The queue's enqueue inside a batch of the database it lives in, which
228
- * it was opened `in`: the job commits with the batch's rows or not at all.
243
+ * Makes the id's job this value at this time, whatever it was: one waiting
244
+ * is made new, a failed one starts again, and a running one runs once more
245
+ * after this run, with this value.
229
246
  *
230
- * await db.batch(tx => {
231
- * tx.exec`update notes set body = ${body} where id = ${id}`
232
- * index.withTx(tx).enqueue({ id })
233
- * })
247
+ * await checks.set(`check:${check.id}`, check, { delay: '25h' })
234
248
  */
235
- withTx(tx: SqlBatch): QueueTx<T>;
236
- /** Adds a job; it returns once the job is in the file. */
237
- enqueue(value: T, options?: EnqueueOptions): Promise<void>;
238
- /** Adds jobs in one transaction, all or none: a refused one names itself as `call`. */
239
- enqueueAll(jobs: readonly ({
240
- value: T;
241
- } & EnqueueOptions)[]): Promise<void>;
249
+ set(id: string, value: T, options?: JobOptions): Promise<void>;
242
250
  /**
243
- * Changes a job that waits or failed: its value and, when the options
244
- * say, its time or repeat. A job a worker holds, done or absent is
245
- * ConflictError.
251
+ * Changes the id's job when it has not started: its value, and its time,
252
+ * group or repeat when the options give them. It says whether it did: a
253
+ * job that runs, ran or never was answers false.
246
254
  */
247
- update(key: string, value: T, options?: Omit<EnqueueOptions, 'key'>): Promise<void>;
255
+ update(id: string, value: T, options?: JobOptions): Promise<boolean>;
248
256
  /**
249
- * Removes the job under key, whether it waits, runs or failed, and says
250
- * whether there was one. A running job's handler sees job.signal abort,
251
- * and what it returns settles nothing.
257
+ * Takes the job under id, whatever its state, and says whether there was
258
+ * one. A running one's handler sees its signal abort, and what it returns
259
+ * then settles nothing; a repeating one stops.
252
260
  */
253
- cancel(key: string): Promise<boolean>;
261
+ cancel(id: string): Promise<boolean>;
254
262
  /**
255
- * The job a key names, waiting, running or failed, or done while keepDone
256
- * keeps its key; undefined when none is.
263
+ * Where the job under id is: scheduled, waiting and how many jobs are
264
+ * ahead of it, running and its progress, failed and why, or done while
265
+ * the queue's dedupe keeps its id; undefined for an id with no job.
257
266
  */
258
- get(key: string): Promise<JobEntry<T> | undefined>;
267
+ get(id: string): Promise<Job<T> | undefined>;
259
268
  /**
260
- * Yields the job under key as it is, then again each time its state,
261
- * place, attempt, time, progress or error changes, until it ends: done,
262
- * failed or cancelled, the last entry it yields. A key that names no job
263
- * yields nothing. Leaving the loop ends the watch; a connection lost is
264
- * connected again, and the watch goes on from the job as it is then.
269
+ * The job under id as it is, then again each time its state, place,
270
+ * attempt, time, progress or error changes; it ends with the job: done,
271
+ * failed, or cancelled, a state only a watcher sees. An id with no job
272
+ * yields nothing. A watch whose connection is lost watches again on the
273
+ * next; a job that ended meanwhile ends it without its last state.
265
274
  *
266
- * for await (const s of videos.watch(id)) send(s.state, s.ahead, s.progress)
275
+ * for await (const job of videos.watch(id)) send(job.state, job.ahead, job.progress)
267
276
  */
268
- watch(key: string): AsyncGenerator<JobEntry<T>>;
277
+ watch(id: string): AsyncGenerator<Job<T>>;
278
+ /** A page of the queue's jobs whose ids start with a prefix, or of its failed ones. */
279
+ list(options?: ListOptions): Promise<JobPage<T>>;
280
+ /** Every job the options name, a page at a time, holding nothing between pages. */
281
+ all(options?: Omit<ListOptions, 'after'>): AsyncGenerator<Job<T>>;
269
282
  /**
270
- * A page of the jobs under a prefix, in the byte order of their keys; with
271
- * state 'failed' and no prefix, the failed jobs, the last failed first.
283
+ * Runs handler on each job as it falls due, as many at once as the
284
+ * queue's concurrency lets, one when it sets none, and returns the running
285
+ * worker at once: stop it at shutdown, as store.close() does. A worker
286
+ * whose connection is lost reaches the store again, the jobs it held
287
+ * running again as a dead worker's would.
288
+ *
289
+ * const worker = reminders.work(async ({ userId, text }) => push(userId, text))
272
290
  */
273
- scan(query?: {
274
- prefix?: string;
275
- state?: 'failed';
276
- after?: string;
277
- limit?: number;
278
- }): Promise<{
279
- items: JobEntry<T>[];
280
- next: string | undefined;
281
- }>;
282
- /** Walks scan's pages, holding no snapshot between them. */
283
- all(query?: {
284
- prefix?: string;
285
- state?: 'failed';
286
- limit?: number;
287
- }): AsyncGenerator<JobEntry<T>>;
291
+ work(handler: Handler<T>, options?: WorkOptions): Worker;
288
292
  /**
289
- * Leases the next due job, or says there is none, without waiting. The
290
- * claim lives on this connection: settle it before its lease ends.
293
+ * Runs what is due when it starts and what falls due meanwhile, then says
294
+ * how many jobs ran; it never waits for a later job. Tests, scripts and
295
+ * commands use it.
291
296
  */
292
- claim(options?: {
293
- lease?: Duration;
294
- }): Promise<ClaimedJob<T> | undefined>;
297
+ runDue(handler: Handler<T>, options?: WorkOptions): Promise<number>;
298
+ }
299
+ /**
300
+ * A queue's calls inside a database's transaction, from `tx.with(queue)`: a
301
+ * job it adds is there only if the transaction commits, and the queue's
302
+ * workers find it once it has. A worker, a watch and a page work outside.
303
+ */
304
+ export declare class TxQueue<T> {
305
+ #private;
306
+ readonly name: string;
307
+ /** Comes from `tx.with(queue)`. */
308
+ constructor(queue: Queue<T>);
309
+ /** Adds a job unless its id is taken, as `queue.add` does, with the transaction. */
310
+ add(value: T, options?: AddOptions): Promise<boolean>;
311
+ set(id: string, value: T, options?: JobOptions): Promise<void>;
312
+ update(id: string, value: T, options?: JobOptions): Promise<boolean>;
313
+ cancel(id: string): Promise<boolean>;
314
+ /** The job under id as the transaction sees it, its own writes among it. */
315
+ get(id: string): Promise<Job<T> | undefined>;
316
+ }
317
+ /** A write the store's transaction keeps for its commit: its method, and its call or the id it cancels. */
318
+ export interface JobOp {
319
+ source: Source<unknown>;
320
+ method: number;
321
+ call?: Omit<Written<typeof JobsCall.fields>, 'handle'>;
322
+ id?: string;
323
+ }
324
+ /**
325
+ * A queue's writes inside the store's transaction, from `tx.with(queue)` in
326
+ * `store.tx`: each is kept for the commit, which makes them all or none, so
327
+ * what one did is known once the transaction has committed.
328
+ *
329
+ * await store.tx(async tx => {
330
+ * for (const member of members) await tx.with(pushes).add({ member, message }, { id: `${message}:${member}` })
331
+ * })
332
+ */
333
+ export declare class StoreTxQueue<T> {
334
+ #private;
335
+ readonly name: string;
336
+ /** Comes from `tx.with(queue)` in `store.tx`. */
337
+ constructor(parts: QueueParts, keep: (op: JobOp) => void);
338
+ /** Adds a job unless its id is taken, with the commit. */
339
+ add(value: T, options?: AddOptions): Promise<void>;
340
+ /** Makes the id's job this value at this time, whatever it was, with the commit. */
341
+ set(id: string, value: T, options?: JobOptions): Promise<void>;
342
+ /** Changes the id's job when it has not started, with the commit. */
343
+ update(id: string, value: T, options?: JobOptions): Promise<void>;
344
+ /** Takes the job under id, whatever its state, with the commit. */
345
+ cancel(id: string): Promise<void>;
346
+ }
347
+ /** Sends a transaction's writes of jobs as one jobs.tx: all of them are made, or none. */
348
+ export declare function commitJobs(link: Link, ops: readonly JobOp[]): Promise<void>;
349
+ /** A queue's parts, for a database's transaction that takes it in; undefined for anything else. */
350
+ export declare function queueParts(handle: object): QueueParts | undefined;
351
+ /** The queue's calls inside a transaction, going through its stream. */
352
+ export declare function queueVia(parts: QueueParts, via: Via): TxQueue<unknown>;
353
+ /** A repeat the code owns: one repeating job under its name, and the worker that runs it. */
354
+ export declare class Schedule {
355
+ #private;
356
+ readonly name: string;
357
+ /** Schedules come from `store.schedule`, started. */
358
+ constructor(source: Source<null>, name: string, handler: (run: Run) => unknown);
359
+ /** When it runs next and how its last run went: what a page of cron jobs shows. */
360
+ get(): Promise<Job<null> | undefined>;
361
+ /** Runs the schedule's job when it is due, as a queue's runDue does. */
362
+ runDue(): Promise<number>;
363
+ /** Stops the schedule's worker, as a worker's stop does. */
364
+ stop(): Promise<void>;
365
+ /** Removes the schedule's job, until the program opens it again. */
366
+ cancel(): Promise<boolean>;
367
+ }
368
+ /** What a queue's open sends, checked before anything leaves. */
369
+ /**
370
+ * A queue, its open checked before anything leaves; `home` is the database
371
+ * whose file keeps it, its open naming the database's handle on each
372
+ * connection.
373
+ */
374
+ export declare function openQueue<T>(link: Link, workers: Set<Worker>, name: string, options: QueueOptions & {
375
+ schema?: StandardSchemaV1 | undefined;
376
+ }, home?: Home): Queue<T>;
377
+ /** A schedule, its open checked before anything leaves, and its worker started. */
378
+ export declare function openSchedule(link: Link, workers: Set<Worker>, name: string, when: ScheduleWhen, handler: (run: Run) => unknown, options?: ScheduleOptions): Schedule;
379
+ /** A worker's state, which its loop and its stop share. */
380
+ interface Working {
381
+ stopping: boolean;
382
+ /** the stream the worker runs on now, which a stop is sent on */
383
+ stream: Stream | undefined;
384
+ /** wakes a loop pausing before it dials again */
385
+ wake: (() => void) | undefined;
386
+ }
387
+ /** A worker running a queue's handlers here while the server's loop claims their jobs. */
388
+ export declare class Worker implements AsyncDisposable {
389
+ #private;
390
+ /** Workers come from a queue's work and from store.schedule, running. */
391
+ constructor(run: (working: Working) => Promise<void>, workers: Set<Worker>);
295
392
  /**
296
- * Runs the queue's jobs as they come due, workers at once, until the
297
- * signal aborts: the server's own Work loop claims ahead and extends
298
- * leases, and nothing polls. A handler's return acknowledges its job and a
299
- * throw retries it. A connection lost takes the jobs in hand with it, as a
300
- * process that died would, and the loop connects again.
393
+ * Takes no job more and waits for the handlers under way, each bounded by
394
+ * its timeout: the server gives back the jobs it held for them, and ends
395
+ * the worker once their answers are written.
301
396
  */
302
- work(handler: (job: Job<T>) => void | Promise<void>, options?: WorkOptions): Promise<void>;
397
+ stop(): Promise<void>;
398
+ [Symbol.asyncDispose](): Promise<void>;
303
399
  }
304
400
  export {};