@tinyshed/tinystore 0.1.0-rc.1

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 (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
@@ -0,0 +1,103 @@
1
+ /**
2
+ * What failed, as the server's error or the SDK's own says it. Each code is a
3
+ * class of its own, so a caller catches `ConflictError` as a Go program asks
4
+ * `errors.Is(err, tinystore.ErrConflict)`.
5
+ */
6
+ export type Code = 'invalid' | 'limit' | 'closed' | 'in_use' | 'conflict' | 'corrupt' | 'too_old' | 'too_new' | 'suspended' | 'outcome_unknown' | 'permission' | 'unimplemented' | 'cancelled' | 'unavailable' | 'internal' | 'protocol' | 'unauthenticated';
7
+ /**
8
+ * The item a failure is about, by the names the server gives: a bucket and a
9
+ * key, a queue and a key, a series' labels, a table and a constraint. A value
10
+ * whose bytes are not UTF-8, as a key of bytes may be, comes as its bytes.
11
+ */
12
+ export type What = Record<string, string | Uint8Array>;
13
+ export declare class TinystoreError extends Error {
14
+ readonly code: Code;
15
+ readonly what: What;
16
+ constructor(code: Code, message: string, what?: What);
17
+ }
18
+ /** The request cannot be done as asked. */
19
+ export declare class InvalidError extends TinystoreError {
20
+ constructor(message: string, what?: What);
21
+ }
22
+ /**
23
+ * A bound: memory, size or count. Later, or smaller, it may go through. A
24
+ * limit the store names says which, what the call would have taken of it,
25
+ * and the bound: `decoded samples`, 120000, 100000.
26
+ */
27
+ export declare class LimitError extends TinystoreError {
28
+ readonly limit: string | undefined;
29
+ readonly wanted: number | undefined;
30
+ readonly bound: number | undefined;
31
+ constructor(message: string, what?: What);
32
+ }
33
+ /** The store, the handle or the connection closed. */
34
+ export declare class ClosedError extends TinystoreError {
35
+ constructor(message: string, what?: What);
36
+ }
37
+ /** A name is taken. */
38
+ export declare class InUseError extends TinystoreError {
39
+ constructor(message: string, what?: What);
40
+ }
41
+ /** A condition or a version no longer holds: read again, then decide. */
42
+ export declare class ConflictError extends TinystoreError {
43
+ constructor(message: string, what?: What);
44
+ }
45
+ /** Stored bytes no longer read. */
46
+ export declare class CorruptError extends TinystoreError {
47
+ constructor(message: string, what?: What);
48
+ }
49
+ /** A time before its engine's window. */
50
+ export declare class TooOldError extends TinystoreError {
51
+ constructor(message: string, what?: What);
52
+ }
53
+ /** A time past its engine's window, ahead of the store's clock. */
54
+ export declare class TooNewError extends TinystoreError {
55
+ constructor(message: string, what?: What);
56
+ }
57
+ /** A metrics series in quarantine until its repair. */
58
+ export declare class SuspendedError extends TinystoreError {
59
+ constructor(message: string, what?: What);
60
+ }
61
+ /**
62
+ * A write whose commit may or may not have happened: the connection was lost
63
+ * while it was in flight, or the server's commit failed. Read what it wrote
64
+ * before writing again.
65
+ */
66
+ export declare class OutcomeUnknownError extends TinystoreError {
67
+ constructor(message: string, what?: What);
68
+ }
69
+ /** The connection's capability does not allow it: a data token changing a schema. */
70
+ export declare class PermissionDeniedError extends TinystoreError {
71
+ constructor(message: string, what?: What);
72
+ }
73
+ /** A method the server does not have. */
74
+ export declare class UnimplementedError extends TinystoreError {
75
+ constructor(message: string, what?: What);
76
+ }
77
+ /** The call was cancelled by its signal. */
78
+ export declare class CancelledError extends TinystoreError {
79
+ constructor(message: string, what?: What);
80
+ }
81
+ /** The server is closing; the call was not run and may be sent on another connection. */
82
+ export declare class UnavailableError extends TinystoreError {
83
+ constructor(message: string, what?: What);
84
+ }
85
+ /** A fault of the server's own. */
86
+ export declare class InternalError extends TinystoreError {
87
+ constructor(message: string, what?: What);
88
+ }
89
+ /** A frame or a message that breaks the protocol; the connection ends with it. */
90
+ export declare class ProtocolError extends TinystoreError {
91
+ constructor(message: string, what?: What);
92
+ }
93
+ /** A remote connection whose token the server does not know. */
94
+ export declare class UnauthenticatedError extends TinystoreError {
95
+ constructor(message: string, what?: What);
96
+ }
97
+ /** The codes this SDK knows, as `messages.json` lists the server's. */
98
+ export declare const codes: Code[];
99
+ /**
100
+ * The error a code names. A code this SDK does not know yet is an
101
+ * `InternalError` keeping the code in its message.
102
+ */
103
+ export declare function errorOf(code: string, message: string, what?: What): TinystoreError;
package/dist/errors.js ADDED
@@ -0,0 +1,158 @@
1
+ export class TinystoreError extends Error {
2
+ code;
3
+ what;
4
+ constructor(code, message, what = {}) {
5
+ super(message);
6
+ this.name = new.target.name;
7
+ this.code = code;
8
+ this.what = what;
9
+ }
10
+ }
11
+ /** The request cannot be done as asked. */
12
+ export class InvalidError extends TinystoreError {
13
+ constructor(message, what) {
14
+ super('invalid', message, what);
15
+ }
16
+ }
17
+ /**
18
+ * A bound: memory, size or count. Later, or smaller, it may go through. A
19
+ * limit the store names says which, what the call would have taken of it,
20
+ * and the bound: `decoded samples`, 120000, 100000.
21
+ */
22
+ export class LimitError extends TinystoreError {
23
+ limit;
24
+ wanted;
25
+ bound;
26
+ constructor(message, what) {
27
+ super('limit', message, what);
28
+ this.limit = typeof what?.limit === 'string' ? what.limit : undefined;
29
+ this.wanted = typeof what?.wanted === 'string' ? Number(what.wanted) : undefined;
30
+ this.bound = typeof what?.bound === 'string' ? Number(what.bound) : undefined;
31
+ }
32
+ }
33
+ /** The store, the handle or the connection closed. */
34
+ export class ClosedError extends TinystoreError {
35
+ constructor(message, what) {
36
+ super('closed', message, what);
37
+ }
38
+ }
39
+ /** A name is taken. */
40
+ export class InUseError extends TinystoreError {
41
+ constructor(message, what) {
42
+ super('in_use', message, what);
43
+ }
44
+ }
45
+ /** A condition or a version no longer holds: read again, then decide. */
46
+ export class ConflictError extends TinystoreError {
47
+ constructor(message, what) {
48
+ super('conflict', message, what);
49
+ }
50
+ }
51
+ /** Stored bytes no longer read. */
52
+ export class CorruptError extends TinystoreError {
53
+ constructor(message, what) {
54
+ super('corrupt', message, what);
55
+ }
56
+ }
57
+ /** A time before its engine's window. */
58
+ export class TooOldError extends TinystoreError {
59
+ constructor(message, what) {
60
+ super('too_old', message, what);
61
+ }
62
+ }
63
+ /** A time past its engine's window, ahead of the store's clock. */
64
+ export class TooNewError extends TinystoreError {
65
+ constructor(message, what) {
66
+ super('too_new', message, what);
67
+ }
68
+ }
69
+ /** A metrics series in quarantine until its repair. */
70
+ export class SuspendedError extends TinystoreError {
71
+ constructor(message, what) {
72
+ super('suspended', message, what);
73
+ }
74
+ }
75
+ /**
76
+ * A write whose commit may or may not have happened: the connection was lost
77
+ * while it was in flight, or the server's commit failed. Read what it wrote
78
+ * before writing again.
79
+ */
80
+ export class OutcomeUnknownError extends TinystoreError {
81
+ constructor(message, what) {
82
+ super('outcome_unknown', message, what);
83
+ }
84
+ }
85
+ /** The connection's capability does not allow it: a data token changing a schema. */
86
+ export class PermissionDeniedError extends TinystoreError {
87
+ constructor(message, what) {
88
+ super('permission', message, what);
89
+ }
90
+ }
91
+ /** A method the server does not have. */
92
+ export class UnimplementedError extends TinystoreError {
93
+ constructor(message, what) {
94
+ super('unimplemented', message, what);
95
+ }
96
+ }
97
+ /** The call was cancelled by its signal. */
98
+ export class CancelledError extends TinystoreError {
99
+ constructor(message, what) {
100
+ super('cancelled', message, what);
101
+ }
102
+ }
103
+ /** The server is closing; the call was not run and may be sent on another connection. */
104
+ export class UnavailableError extends TinystoreError {
105
+ constructor(message, what) {
106
+ super('unavailable', message, what);
107
+ }
108
+ }
109
+ /** A fault of the server's own. */
110
+ export class InternalError extends TinystoreError {
111
+ constructor(message, what) {
112
+ super('internal', message, what);
113
+ }
114
+ }
115
+ /** A frame or a message that breaks the protocol; the connection ends with it. */
116
+ export class ProtocolError extends TinystoreError {
117
+ constructor(message, what) {
118
+ super('protocol', message, what);
119
+ }
120
+ }
121
+ /** A remote connection whose token the server does not know. */
122
+ export class UnauthenticatedError extends TinystoreError {
123
+ constructor(message, what) {
124
+ super('unauthenticated', message, what);
125
+ }
126
+ }
127
+ const classes = {
128
+ invalid: InvalidError,
129
+ limit: LimitError,
130
+ closed: ClosedError,
131
+ in_use: InUseError,
132
+ conflict: ConflictError,
133
+ corrupt: CorruptError,
134
+ too_old: TooOldError,
135
+ too_new: TooNewError,
136
+ suspended: SuspendedError,
137
+ outcome_unknown: OutcomeUnknownError,
138
+ permission: PermissionDeniedError,
139
+ unimplemented: UnimplementedError,
140
+ cancelled: CancelledError,
141
+ unavailable: UnavailableError,
142
+ internal: InternalError,
143
+ protocol: ProtocolError,
144
+ unauthenticated: UnauthenticatedError,
145
+ };
146
+ /** The codes this SDK knows, as `messages.json` lists the server's. */
147
+ export const codes = Object.keys(classes);
148
+ /**
149
+ * The error a code names. A code this SDK does not know yet is an
150
+ * `InternalError` keeping the code in its message.
151
+ */
152
+ export function errorOf(code, message, what = {}) {
153
+ const known = classes[code];
154
+ if (known === undefined) {
155
+ return new InternalError(`${code}: ${message}`, what);
156
+ }
157
+ return new known(message, what);
158
+ }
@@ -0,0 +1,28 @@
1
+ import type { Connection } from './connection.ts';
2
+ import type { Key } from './wire/codec.ts';
3
+ /**
4
+ * The handle an open answers on a connection, opened once a connection: the
5
+ * open's own bytes name it, so a bucket opened twice with the same options
6
+ * shares its handle. An open that fails is tried again by the next call.
7
+ */
8
+ export declare function handleOn(connection: Connection, method: number, open: Uint8Array): Promise<number>;
9
+ /** A bucket's or a queue's name, as every engine takes it: [a-z0-9][a-z0-9_-]{0,63}. */
10
+ export declare function checkName(name: string, of: string): void;
11
+ /**
12
+ * What a batch's or a view's function returned, once the batch has settled: a
13
+ * promise its answer, an array or a tuple each element's as Promise.all gives
14
+ * them, and anything else itself.
15
+ */
16
+ export type Settled<T> = T extends PromiseLike<infer V> ? V : T extends readonly unknown[] ? {
17
+ -readonly [K in keyof T]: Awaited<T[K]>;
18
+ } : T;
19
+ /** Answers what a batch's function returned, once the batch's calls have settled. */
20
+ export declare function settle<T>(returned: T): Promise<Settled<T>>;
21
+ /** A page of a scan: its items, and where the next begins when more remain. */
22
+ export interface Page<T, After> {
23
+ items: T[];
24
+ /** the place the next page begins after; undefined once the scan has ended */
25
+ next: After | undefined;
26
+ }
27
+ /** A key's owners, each its text: an integer is its decimal spelling, as Go's Of takes it. */
28
+ export declare function ownerText(owner: Key): string | Uint8Array;
@@ -0,0 +1,37 @@
1
+ import { InvalidError } from './errors.js';
2
+ import { Handle } from './wire/messages.js';
3
+ /**
4
+ * The handle an open answers on a connection, opened once a connection: the
5
+ * open's own bytes name it, so a bucket opened twice with the same options
6
+ * shares its handle. An open that fails is tried again by the next call.
7
+ */
8
+ export function handleOn(connection, method, open) {
9
+ const key = `${method}:${Buffer.from(open).toString('base64')}`;
10
+ let opening = connection.handles.get(key);
11
+ if (opening === undefined) {
12
+ opening = connection.session.call(method, open).then(body => Handle.decode(body).handle ?? 0);
13
+ connection.handles.set(key, opening);
14
+ opening.catch(() => connection.handles.delete(key));
15
+ }
16
+ return opening;
17
+ }
18
+ /** A bucket's or a queue's name, as every engine takes it: [a-z0-9][a-z0-9_-]{0,63}. */
19
+ export function checkName(name, of) {
20
+ if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name)) {
21
+ throw new InvalidError(`the ${of} name ${JSON.stringify(name)}: a name is [a-z0-9][a-z0-9_-]{0,63}`);
22
+ }
23
+ }
24
+ /** Answers what a batch's function returned, once the batch's calls have settled. */
25
+ export async function settle(returned) {
26
+ return (Array.isArray(returned) ? await Promise.all(returned) : await returned);
27
+ }
28
+ /** A key's owners, each its text: an integer is its decimal spelling, as Go's Of takes it. */
29
+ export function ownerText(owner) {
30
+ if (typeof owner === 'number' || typeof owner === 'bigint') {
31
+ if (typeof owner === 'number' && !Number.isSafeInteger(owner)) {
32
+ throw new InvalidError(`the owner ${owner} is not an integer; an owner is text or an integer`);
33
+ }
34
+ return String(owner);
35
+ }
36
+ return owner;
37
+ }
@@ -0,0 +1,21 @@
1
+ export type { BlobBucket, BlobObject, Blobs, Body, Download, PutOptions } from './blobs.ts';
2
+ export { withSignal } from './cancel.ts';
3
+ export type { Clock } from './clock.ts';
4
+ export type { Config, ConfigOptions, DeepPartial, Source } from './config.ts';
5
+ export type { ConsoleFormat } from './console.ts';
6
+ export * from './errors.ts';
7
+ export type { Page } from './handles.ts';
8
+ export type { ClaimedJob, EnqueueOptions, Job, JobEntry, JobState, Jobs, Queue, QueueOptions, QueueTx, Repeat, WorkOptions, } from './jobs.ts';
9
+ export type { Batch, Bucket, BucketOptions, BucketTx, CounterOptions, Counters, Entry, Kind, Scanned, Tx, WriteOptions, } from './kv.ts';
10
+ export type { Allowance, Limiter, LimiterOptions, Rate } from './limiter.ts';
11
+ export { type Logger, type LoggerOptions, logger } from './logger.ts';
12
+ export { type Aggregate, type AggregateOp, type AggregateRange, type Bucket as MetricsBucket, Condition, type Counter, type Gauge, type Labels, type Metrics, noneOf, oneOf, type Plan, prefix, type Range, type Series, type SeriesInput, type SeriesKind, type Timer, } from './metrics.ts';
13
+ export type { Once, OnceOptions } from './once.ts';
14
+ export type { Quota, QuotaUsage, WindowUsage } from './quota.ts';
15
+ export { type Cursor, type Damage, type Fields, fields, type Level, type LinesWriter, type LogRecord, type RecordInput, type Records, type RecordsQuery, } from './records.ts';
16
+ export type { StandardSchemaV1 } from './schema.ts';
17
+ export type { Database, Done, Migrations, Row, SqlArg, SqlBatch, SqlOptions, SqlValue, Statement, } from './sql.ts';
18
+ export { type ConnectOptions, connect, type OpenOptions, open, type Status, Store, } from './store.ts';
19
+ export type { Duration, DurationText, Time } from './time.ts';
20
+ export { type Trace, withTrace } from './trace.ts';
21
+ export type { Key } from './wire/codec.ts';
package/dist/index.js ADDED
@@ -0,0 +1,7 @@
1
+ export { withSignal } from './cancel.js';
2
+ export * from './errors.js';
3
+ export { logger } from './logger.js';
4
+ export { Condition, noneOf, oneOf, prefix, } from './metrics.js';
5
+ export { fields, } from './records.js';
6
+ export { connect, open, Store, } from './store.js';
7
+ export { withTrace } from './trace.js';
package/dist/jobs.d.ts ADDED
@@ -0,0 +1,304 @@
1
+ import { type Link } from './connection.ts';
2
+ import { type StandardSchemaV1 } from './schema.ts';
3
+ import type { Database, SqlBatch } from './sql.ts';
4
+ import { type Duration, type Time } from './time.ts';
5
+ import { JobsHeld, JobsOutcome } from './wire/messages.ts';
6
+ 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;
29
+ }
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;
48
+ }
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
+ value: T;
54
+ /** the time it runs for */
55
+ at: Date;
56
+ /** its attempts, a running one included */
57
+ 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 */
60
+ ahead: number;
61
+ /** what a running job's handler last reported with job.progress */
62
+ 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 */
68
+ error: string | undefined;
69
+ /** a repeating job's cron text and zone */
70
+ repeat: string | undefined;
71
+ }
72
+ 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;
81
+ }
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
+ /**
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.
101
+ */
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>;
108
+ }
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 {
116
+ #private;
117
+ constructor(call: Call, job: number);
118
+ run<R>(name: string, fn: () => R | Promise<R>): Promise<R>;
119
+ }
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> {
126
+ #private;
127
+ readonly key: string;
128
+ readonly value: T;
129
+ /** the time it ran for */
130
+ readonly at: Date;
131
+ /** its attempts, this one included */
132
+ readonly attempt: number;
133
+ /**
134
+ * aborts when the job's timeout passes, its loop stops, or cancel takes it,
135
+ * whose reason is then a CancelledError: the handler should stop too
136
+ */
137
+ readonly signal: AbortSignal;
138
+ settlement: Settlement | undefined;
139
+ constructor(key: string, value: T, at: Date, attempt: number, signal: AbortSignal, reporter?: Reporter, steps?: Steps);
140
+ /**
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.
147
+ *
148
+ * const hits = await job.step('search', () => search(job.value.query))
149
+ */
150
+ step<R>(name: string, fn: () => R | Promise<R>): Promise<R>;
151
+ /**
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) })
156
+ */
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;
170
+ }
171
+ /** A job a claim leased, which its caller settles itself before the lease ends. */
172
+ export declare class ClaimedJob<T> {
173
+ #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>;
196
+ }
197
+ /** Encodes a queue's values as JSON, the text every language reads, and back. */
198
+ interface Values<T> {
199
+ encode(value: T): string;
200
+ decode(text: string): T | Promise<T>;
201
+ }
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>;
214
+ }
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>;
221
+ }
222
+ export declare class Queue<T> {
223
+ #private;
224
+ readonly name: string;
225
+ constructor(link: Link, name: string, open: Uint8Array, values: Values<T>, inDatabase: Database | undefined);
226
+ /**
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.
229
+ *
230
+ * await db.batch(tx => {
231
+ * tx.exec`update notes set body = ${body} where id = ${id}`
232
+ * index.withTx(tx).enqueue({ id })
233
+ * })
234
+ */
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>;
242
+ /**
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.
246
+ */
247
+ update(key: string, value: T, options?: Omit<EnqueueOptions, 'key'>): Promise<void>;
248
+ /**
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.
252
+ */
253
+ cancel(key: string): Promise<boolean>;
254
+ /**
255
+ * The job a key names, waiting, running or failed, or done while keepDone
256
+ * keeps its key; undefined when none is.
257
+ */
258
+ get(key: string): Promise<JobEntry<T> | undefined>;
259
+ /**
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.
265
+ *
266
+ * for await (const s of videos.watch(id)) send(s.state, s.ahead, s.progress)
267
+ */
268
+ watch(key: string): AsyncGenerator<JobEntry<T>>;
269
+ /**
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.
272
+ */
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>>;
288
+ /**
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.
291
+ */
292
+ claim(options?: {
293
+ lease?: Duration;
294
+ }): Promise<ClaimedJob<T> | undefined>;
295
+ /**
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.
301
+ */
302
+ work(handler: (job: Job<T>) => void | Promise<void>, options?: WorkOptions): Promise<void>;
303
+ }
304
+ export {};