@tinyshed/tinystore 0.1.0-rc.4 → 0.1.0-rc.6
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 +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
package/dist/jobs.d.ts
CHANGED
|
@@ -1,304 +1,400 @@
|
|
|
1
|
-
import {
|
|
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
|
|
5
|
+
import { type Stream } from './session.ts';
|
|
4
6
|
import { type Duration, type Time } from './time.ts';
|
|
5
|
-
import {
|
|
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
|
-
/**
|
|
8
|
-
|
|
9
|
-
/**
|
|
10
|
-
|
|
11
|
-
/**
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
/**
|
|
31
|
-
export
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
every
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
70
|
+
/** what its handler last reported of a running job */
|
|
62
71
|
progress: unknown;
|
|
63
|
-
/**
|
|
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
|
-
|
|
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
|
|
74
|
-
|
|
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
|
-
*
|
|
99
|
-
*
|
|
100
|
-
*
|
|
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
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
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
|
-
/**
|
|
110
|
-
type
|
|
111
|
-
/**
|
|
112
|
-
|
|
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
|
-
|
|
118
|
-
|
|
127
|
+
/** Answers come from a run. */
|
|
128
|
+
constructor(how: string);
|
|
129
|
+
toString(): string;
|
|
119
130
|
}
|
|
120
|
-
/**
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
128
|
-
readonly
|
|
129
|
-
/** the
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
|
|
139
|
-
constructor(
|
|
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
|
|
142
|
-
* attempt after a retry, a lost
|
|
143
|
-
* back without running fn again. A step whose attempt
|
|
144
|
-
* answer is kept runs again, so what fn does outside the
|
|
145
|
-
* doing twice. A name is the step's within
|
|
146
|
-
* 'model:1', 'tool:1'
|
|
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
|
|
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
|
-
*
|
|
153
|
-
*
|
|
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
|
-
|
|
158
|
-
/**
|
|
159
|
-
retry(
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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
|
-
/**
|
|
172
|
-
|
|
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
|
-
|
|
175
|
-
|
|
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
|
-
/**
|
|
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):
|
|
203
|
+
decode(text: string): Promise<T>;
|
|
201
204
|
}
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
/**
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
/**
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
/**
|
|
216
|
-
export
|
|
217
|
-
|
|
218
|
-
|
|
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
|
-
|
|
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
|
-
*
|
|
228
|
-
*
|
|
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
|
|
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
|
-
|
|
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
|
|
244
|
-
*
|
|
245
|
-
*
|
|
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(
|
|
255
|
+
update(id: string, value: T, options?: JobOptions): Promise<boolean>;
|
|
248
256
|
/**
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
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(
|
|
261
|
+
cancel(id: string): Promise<boolean>;
|
|
254
262
|
/**
|
|
255
|
-
*
|
|
256
|
-
*
|
|
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(
|
|
267
|
+
get(id: string): Promise<Job<T> | undefined>;
|
|
259
268
|
/**
|
|
260
|
-
*
|
|
261
|
-
*
|
|
262
|
-
* failed or cancelled,
|
|
263
|
-
* yields nothing.
|
|
264
|
-
*
|
|
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
|
|
275
|
+
* for await (const job of videos.watch(id)) send(job.state, job.ahead, job.progress)
|
|
267
276
|
*/
|
|
268
|
-
watch(
|
|
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
|
-
*
|
|
271
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
290
|
-
*
|
|
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
|
-
|
|
293
|
-
|
|
294
|
-
|
|
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
|
-
*
|
|
297
|
-
*
|
|
298
|
-
*
|
|
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
|
-
|
|
397
|
+
stop(): Promise<void>;
|
|
398
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
303
399
|
}
|
|
304
400
|
export {};
|