@tinyshed/tinystore 0.1.0-rc.5 → 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/limits.d.ts
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { Link } from './connection.ts';
|
|
2
|
+
import { type Unit } from './time.ts';
|
|
3
|
+
import type { Key } from './wire/codec.ts';
|
|
4
|
+
/**
|
|
5
|
+
* How many pass a span: '100/s', '5/10s', '1000/h', '300/7d', a span of one
|
|
6
|
+
* unit leaving out its 1. The type checks it as it is written.
|
|
7
|
+
*/
|
|
8
|
+
export type Rate = `${number}/${Unit}` | `${number}/${number}${Unit}`;
|
|
9
|
+
export interface RateLimitOptions {
|
|
10
|
+
/** how many requests a key passes a span */
|
|
11
|
+
rate: Rate;
|
|
12
|
+
/** how many may pass at once before the rate holds the next; the rate's count when absent */
|
|
13
|
+
burst?: number | undefined;
|
|
14
|
+
}
|
|
15
|
+
/** One window of a quota as a key stands in it. */
|
|
16
|
+
export interface WindowUse {
|
|
17
|
+
used: number;
|
|
18
|
+
limit: number;
|
|
19
|
+
left: number;
|
|
20
|
+
/** when the window resets; undefined for one not started */
|
|
21
|
+
resetsAt: Date | undefined;
|
|
22
|
+
}
|
|
23
|
+
/** What a rate limit or a quota answers a request. */
|
|
24
|
+
export interface Allowance<W extends string = never> {
|
|
25
|
+
ok: boolean;
|
|
26
|
+
/** how many more would pass now */
|
|
27
|
+
left: number;
|
|
28
|
+
/** when a refused request may try again; undefined when it passed */
|
|
29
|
+
retryAt: Date | undefined;
|
|
30
|
+
/** a quota's windows by name; none for a rate limit */
|
|
31
|
+
windows: Record<W, WindowUse>;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* A rate's count and span in milliseconds: a span of one unit may leave out
|
|
35
|
+
* its 1.
|
|
36
|
+
*
|
|
37
|
+
* '100/s' → 100 a 1000 ms, '5/10s' → 5 a 10000 ms
|
|
38
|
+
*/
|
|
39
|
+
export declare function rateOf(rate: string): {
|
|
40
|
+
count: number;
|
|
41
|
+
per: number;
|
|
42
|
+
};
|
|
43
|
+
/** A rate of requests a key: open it with `store.rateLimit(name, { rate })`. */
|
|
44
|
+
export declare class RateLimit {
|
|
45
|
+
#private;
|
|
46
|
+
readonly name: string;
|
|
47
|
+
/** Rate limits come from `store.rateLimit` and their `under`. */
|
|
48
|
+
constructor(link: Link, name: string, open: Uint8Array, under: readonly string[]);
|
|
49
|
+
/** The rate limit of a branch, each key apart from the same key elsewhere. */
|
|
50
|
+
under(...owners: Key[]): RateLimit;
|
|
51
|
+
/** Asks for n requests of key, one unless given: all pass or none; more than the burst is InvalidError. */
|
|
52
|
+
allow(key: Key, n?: number): Promise<Allowance>;
|
|
53
|
+
/** The answer one request would get, using nothing. */
|
|
54
|
+
peek(key: Key): Promise<Allowance>;
|
|
55
|
+
/** Forgets key, so that its next request starts afresh. */
|
|
56
|
+
reset(key: Key): Promise<void>;
|
|
57
|
+
}
|
|
58
|
+
/** Uses by key in named windows: open it with `store.quota(name, { daily: '100/1d' })`. */
|
|
59
|
+
export declare class Quota<W extends string = string> {
|
|
60
|
+
#private;
|
|
61
|
+
readonly name: string;
|
|
62
|
+
/** Quotas come from `store.quota` and their `under`. */
|
|
63
|
+
constructor(link: Link, name: string, open: Uint8Array, under: readonly string[]);
|
|
64
|
+
under(...owners: Key[]): Quota<W>;
|
|
65
|
+
/**
|
|
66
|
+
* Uses n of key's every window, one unless given, or none when one has no
|
|
67
|
+
* room; more than a window's limit is InvalidError.
|
|
68
|
+
*
|
|
69
|
+
* const { ok, retryAt, windows } = await ai.allow(user.id)
|
|
70
|
+
*/
|
|
71
|
+
allow(key: Key, n?: number): Promise<Allowance<W>>;
|
|
72
|
+
peek(key: Key): Promise<Allowance<W>>;
|
|
73
|
+
reset(key: Key): Promise<void>;
|
|
74
|
+
/** Gives n uses back to every window of key, one unless given. */
|
|
75
|
+
refund(key: Key, n?: number): Promise<void>;
|
|
76
|
+
}
|
|
77
|
+
/** A rate limit's open: its name and rate, checked before anything leaves. */
|
|
78
|
+
export declare function rateLimitOpen(name: string, options: RateLimitOptions): Uint8Array;
|
|
79
|
+
/** A quota's open: its windows by name, in the order they were given. */
|
|
80
|
+
export declare function quotaOpen(name: string, windows: Record<string, Rate>): Uint8Array;
|
package/dist/limits.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
// May this request pass: a rate limit lets a smooth rate of requests a key
|
|
2
|
+
// through, the generic cell rate algorithm with its times in the core's memory;
|
|
3
|
+
// a quota counts uses in windows that reset, all of them or none in one
|
|
4
|
+
// durable write. Both answer rather than throw, with one Allowance.
|
|
5
|
+
import { InvalidError } from './errors.js';
|
|
6
|
+
import { checkName } from './handles.js';
|
|
7
|
+
import { callOn, keyText } from './kv.js';
|
|
8
|
+
import { dateOf, ms } from './time.js';
|
|
9
|
+
import { KvAllowance, KvQuotaOpen, KvRateLimitOpen } from './wire/protocol.js';
|
|
10
|
+
/**
|
|
11
|
+
* A rate's count and span in milliseconds: a span of one unit may leave out
|
|
12
|
+
* its 1.
|
|
13
|
+
*
|
|
14
|
+
* '100/s' → 100 a 1000 ms, '5/10s' → 5 a 10000 ms
|
|
15
|
+
*/
|
|
16
|
+
export function rateOf(rate) {
|
|
17
|
+
const parts = /^(\d+)\/(\d*)([a-z]+)$/.exec(rate);
|
|
18
|
+
if (parts === null) {
|
|
19
|
+
throw new InvalidError(`the rate ${JSON.stringify(rate)}; write it as 100/s, 5/10s or 1000/h`);
|
|
20
|
+
}
|
|
21
|
+
const [, count, span, unit] = parts;
|
|
22
|
+
return { count: Number(count), per: ms(`${span === '' ? '1' : span}${unit}`) };
|
|
23
|
+
}
|
|
24
|
+
/** A rate of requests a key: open it with `store.rateLimit(name, { rate })`. */
|
|
25
|
+
export class RateLimit {
|
|
26
|
+
name;
|
|
27
|
+
#link;
|
|
28
|
+
#open;
|
|
29
|
+
#under;
|
|
30
|
+
/** Rate limits come from `store.rateLimit` and their `under`. */
|
|
31
|
+
constructor(link, name, open, under) {
|
|
32
|
+
this.#link = link;
|
|
33
|
+
this.name = name;
|
|
34
|
+
this.#open = open;
|
|
35
|
+
this.#under = under;
|
|
36
|
+
}
|
|
37
|
+
/** The rate limit of a branch, each key apart from the same key elsewhere. */
|
|
38
|
+
under(...owners) {
|
|
39
|
+
return new RateLimit(this.#link, this.name, this.#open, [
|
|
40
|
+
...this.#under,
|
|
41
|
+
...owners.map(keyText),
|
|
42
|
+
]);
|
|
43
|
+
}
|
|
44
|
+
/** Asks for n requests of key, one unless given: all pass or none; more than the burst is InvalidError. */
|
|
45
|
+
async allow(key, n = 1) {
|
|
46
|
+
return allowanceOf(await this.#call('kv.allow', key, n, 'write'));
|
|
47
|
+
}
|
|
48
|
+
/** The answer one request would get, using nothing. */
|
|
49
|
+
async peek(key) {
|
|
50
|
+
return allowanceOf(await this.#call('kv.peek', key, undefined, 'read'));
|
|
51
|
+
}
|
|
52
|
+
/** Forgets key, so that its next request starts afresh. */
|
|
53
|
+
async reset(key) {
|
|
54
|
+
await this.#call('kv.reset', key, undefined, 'write');
|
|
55
|
+
}
|
|
56
|
+
#call(method, key, n, idempotence) {
|
|
57
|
+
const fields = { key, n: n === 1 ? undefined : n };
|
|
58
|
+
return callOn(this.#link, 'kv.rateLimit.open', this.#open, this.#under, method, fields, idempotence);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
/** Uses by key in named windows: open it with `store.quota(name, { daily: '100/1d' })`. */
|
|
62
|
+
export class Quota {
|
|
63
|
+
name;
|
|
64
|
+
#link;
|
|
65
|
+
#open;
|
|
66
|
+
#under;
|
|
67
|
+
/** Quotas come from `store.quota` and their `under`. */
|
|
68
|
+
constructor(link, name, open, under) {
|
|
69
|
+
this.#link = link;
|
|
70
|
+
this.name = name;
|
|
71
|
+
this.#open = open;
|
|
72
|
+
this.#under = under;
|
|
73
|
+
}
|
|
74
|
+
under(...owners) {
|
|
75
|
+
return new Quota(this.#link, this.name, this.#open, [...this.#under, ...owners.map(keyText)]);
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Uses n of key's every window, one unless given, or none when one has no
|
|
79
|
+
* room; more than a window's limit is InvalidError.
|
|
80
|
+
*
|
|
81
|
+
* const { ok, retryAt, windows } = await ai.allow(user.id)
|
|
82
|
+
*/
|
|
83
|
+
async allow(key, n = 1) {
|
|
84
|
+
return allowanceOf(await this.#call('kv.allow', key, n, 'write'));
|
|
85
|
+
}
|
|
86
|
+
async peek(key) {
|
|
87
|
+
return allowanceOf(await this.#call('kv.peek', key, undefined, 'read'));
|
|
88
|
+
}
|
|
89
|
+
async reset(key) {
|
|
90
|
+
await this.#call('kv.reset', key, undefined, 'write');
|
|
91
|
+
}
|
|
92
|
+
/** Gives n uses back to every window of key, one unless given. */
|
|
93
|
+
async refund(key, n = 1) {
|
|
94
|
+
await this.#call('kv.refund', key, n, 'write');
|
|
95
|
+
}
|
|
96
|
+
#call(method, key, n, idempotence) {
|
|
97
|
+
const fields = { key, n: n === 1 ? undefined : n };
|
|
98
|
+
return callOn(this.#link, 'kv.quota.open', this.#open, this.#under, method, fields, idempotence);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
/** A rate limit's open: its name and rate, checked before anything leaves. */
|
|
102
|
+
export function rateLimitOpen(name, options) {
|
|
103
|
+
checkName(name, 'rate limit');
|
|
104
|
+
const { count, per } = rateOf(options.rate);
|
|
105
|
+
if (count < 1 || per < 1) {
|
|
106
|
+
throw new InvalidError(`kv rate limit ${name}: a rate of ${options.rate}`);
|
|
107
|
+
}
|
|
108
|
+
if (options.burst !== undefined && (!Number.isInteger(options.burst) || options.burst < 1)) {
|
|
109
|
+
throw new InvalidError(`kv rate limit ${name}: a burst of ${options.burst}`);
|
|
110
|
+
}
|
|
111
|
+
return KvRateLimitOpen.encode({ name, rate: count, per, burst: options.burst });
|
|
112
|
+
}
|
|
113
|
+
/** A quota's open: its windows by name, in the order they were given. */
|
|
114
|
+
export function quotaOpen(name, windows) {
|
|
115
|
+
checkName(name, 'quota');
|
|
116
|
+
const named = Object.entries(windows).map(([window, rate]) => {
|
|
117
|
+
const { count, per } = rateOf(rate);
|
|
118
|
+
return { name: window, limit: count, per };
|
|
119
|
+
});
|
|
120
|
+
return KvQuotaOpen.encode({ name, windows: named });
|
|
121
|
+
}
|
|
122
|
+
function allowanceOf(body) {
|
|
123
|
+
const answer = KvAllowance.decode(body);
|
|
124
|
+
const windows = {};
|
|
125
|
+
for (const window of answer.windows ?? []) {
|
|
126
|
+
windows[(window.name ?? '')] = {
|
|
127
|
+
used: window.used ?? 0,
|
|
128
|
+
limit: window.limit ?? 0,
|
|
129
|
+
left: window.left ?? 0,
|
|
130
|
+
resetsAt: dateOf(window.resetsAt),
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
return {
|
|
134
|
+
ok: answer.ok === true,
|
|
135
|
+
left: answer.left ?? 0,
|
|
136
|
+
retryAt: dateOf(answer.retryAt),
|
|
137
|
+
windows,
|
|
138
|
+
};
|
|
139
|
+
}
|
package/dist/locks.d.ts
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { Link } from './connection.ts';
|
|
2
|
+
import { type Duration } from './time.ts';
|
|
3
|
+
import type { Key } from './wire/codec.ts';
|
|
4
|
+
export interface LockOptions {
|
|
5
|
+
/** how long a lease lasts from its last renewal: 10 s unless said, 1 s to 1 hour */
|
|
6
|
+
ttl?: Duration | undefined;
|
|
7
|
+
/** how long a lease lasts from its grant, however it is renewed: past it the next in line holds the key */
|
|
8
|
+
maxHold?: Duration | undefined;
|
|
9
|
+
}
|
|
10
|
+
export interface SemaphoreOptions extends LockOptions {
|
|
11
|
+
/** how many may hold a key at once, 1 to 1000 */
|
|
12
|
+
limit: number;
|
|
13
|
+
}
|
|
14
|
+
export interface HoldOptions {
|
|
15
|
+
/** how long the hold waits in line: 10 s unless said, then InUseError */
|
|
16
|
+
wait?: Duration | undefined;
|
|
17
|
+
}
|
|
18
|
+
/** What tryHold gives: the function's value, or that the key was held. */
|
|
19
|
+
export type Tried<T> = {
|
|
20
|
+
acquired: true;
|
|
21
|
+
value: T;
|
|
22
|
+
} | {
|
|
23
|
+
acquired: false;
|
|
24
|
+
};
|
|
25
|
+
/** A holding of a lock's key, given to the function that holds it. */
|
|
26
|
+
export interface Lease {
|
|
27
|
+
/** grows with every lease the store gives: hand it to whatever must refuse a late holder */
|
|
28
|
+
readonly fence: bigint;
|
|
29
|
+
/** aborts when the lease is lost: run out, revoked at maxHold, or its store closed */
|
|
30
|
+
readonly signal: AbortSignal;
|
|
31
|
+
}
|
|
32
|
+
/** A holding of a semaphore's key: one of its limit. */
|
|
33
|
+
export interface Permit {
|
|
34
|
+
readonly signal: AbortSignal;
|
|
35
|
+
}
|
|
36
|
+
/** Keys held one holder at a time: open them with `store.lock(name)`. */
|
|
37
|
+
export declare class Lock {
|
|
38
|
+
#private;
|
|
39
|
+
readonly name: string;
|
|
40
|
+
/** A lock comes from `store.lock`. */
|
|
41
|
+
constructor(link: Link, name: string, options: LockOptions | undefined);
|
|
42
|
+
/**
|
|
43
|
+
* Waits for key, holds it while fn runs and lets it go, giving what fn
|
|
44
|
+
* gives. A key still held after the wait is InUseError; a lease lost
|
|
45
|
+
* while fn ran is LostError, though fn succeeded.
|
|
46
|
+
*
|
|
47
|
+
* await invoices.hold(invoice.id, lease => charge(invoice, { fence: lease.fence, signal: lease.signal }))
|
|
48
|
+
*/
|
|
49
|
+
hold<T>(key: Key, fn: (lease: Lease) => T | Promise<T>, options?: HoldOptions): Promise<T>;
|
|
50
|
+
/** Holds key while fn runs if nobody holds it, and says it was held without waiting if somebody does. */
|
|
51
|
+
tryHold<T>(key: Key, fn: (lease: Lease) => T | Promise<T>): Promise<Tried<T>>;
|
|
52
|
+
}
|
|
53
|
+
/** Keys held by up to their limit at a time: open them with `store.semaphore(name, { limit })`. */
|
|
54
|
+
export declare class Semaphore {
|
|
55
|
+
#private;
|
|
56
|
+
readonly name: string;
|
|
57
|
+
readonly limit: number;
|
|
58
|
+
/** A semaphore comes from `store.semaphore`. */
|
|
59
|
+
constructor(link: Link, name: string, options: SemaphoreOptions);
|
|
60
|
+
hold<T>(key: Key, fn: (permit: Permit) => T | Promise<T>, options?: HoldOptions): Promise<T>;
|
|
61
|
+
tryHold<T>(key: Key, fn: (permit: Permit) => T | Promise<T>): Promise<Tried<T>>;
|
|
62
|
+
}
|
package/dist/locks.js
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
// Locks and semaphores, as docs/guides/locks/README.md has them: a key that one holder
|
|
2
|
+
// at a time, or `limit`, may hold while a function runs, across every
|
|
3
|
+
// program of a store. The store keeps them in its process's memory; a holder
|
|
4
|
+
// here renews its lease at a third of its ttl from this program, so that a
|
|
5
|
+
// program that froze stops renewing and loses the key.
|
|
6
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
7
|
+
import { currentSignal } from './cancel.js';
|
|
8
|
+
import { ClosedError, InUseError, InvalidError, LostError } from './errors.js';
|
|
9
|
+
import { checkName } from './handles.js';
|
|
10
|
+
import { keyText } from './kv.js';
|
|
11
|
+
import { ConnectionLostError } from './session.js';
|
|
12
|
+
import { insideDatabaseTx } from './sql.js';
|
|
13
|
+
import { ms } from './time.js';
|
|
14
|
+
import { insideStoreTx } from './tx.js';
|
|
15
|
+
import { LocksHeld, LocksHold, LocksLease, LocksRenew, methods } from './wire/protocol.js';
|
|
16
|
+
/** How long a lease lasts between renewals, and a hold waits, unless said. */
|
|
17
|
+
const defaultTtl = 10_000;
|
|
18
|
+
const defaultWait = 10_000;
|
|
19
|
+
/** Keys held one holder at a time: open them with `store.lock(name)`. */
|
|
20
|
+
export class Lock {
|
|
21
|
+
name;
|
|
22
|
+
#keys;
|
|
23
|
+
/** A lock comes from `store.lock`. */
|
|
24
|
+
constructor(link, name, options) {
|
|
25
|
+
checkName(name, 'lock');
|
|
26
|
+
this.name = name;
|
|
27
|
+
this.#keys = new Keys(link, 'lock', name, 1, options);
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Waits for key, holds it while fn runs and lets it go, giving what fn
|
|
31
|
+
* gives. A key still held after the wait is InUseError; a lease lost
|
|
32
|
+
* while fn ran is LostError, though fn succeeded.
|
|
33
|
+
*
|
|
34
|
+
* await invoices.hold(invoice.id, lease => charge(invoice, { fence: lease.fence, signal: lease.signal }))
|
|
35
|
+
*/
|
|
36
|
+
async hold(key, fn, options) {
|
|
37
|
+
return held(await this.#keys.hold(key, fn, waitOf(options), leaseOf), this.#keys.place(key));
|
|
38
|
+
}
|
|
39
|
+
/** Holds key while fn runs if nobody holds it, and says it was held without waiting if somebody does. */
|
|
40
|
+
tryHold(key, fn) {
|
|
41
|
+
return this.#keys.hold(key, fn, 0, leaseOf);
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
/** Keys held by up to their limit at a time: open them with `store.semaphore(name, { limit })`. */
|
|
45
|
+
export class Semaphore {
|
|
46
|
+
name;
|
|
47
|
+
limit;
|
|
48
|
+
#keys;
|
|
49
|
+
/** A semaphore comes from `store.semaphore`. */
|
|
50
|
+
constructor(link, name, options) {
|
|
51
|
+
checkName(name, 'semaphore');
|
|
52
|
+
if (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1000) {
|
|
53
|
+
throw new InvalidError(`semaphore ${name}: a limit of ${options.limit}, not 1 to 1000`);
|
|
54
|
+
}
|
|
55
|
+
this.name = name;
|
|
56
|
+
this.limit = options.limit;
|
|
57
|
+
this.#keys = new Keys(link, 'semaphore', name, options.limit, options);
|
|
58
|
+
}
|
|
59
|
+
async hold(key, fn, options) {
|
|
60
|
+
return held(await this.#keys.hold(key, fn, waitOf(options), permitOf), this.#keys.place(key));
|
|
61
|
+
}
|
|
62
|
+
tryHold(key, fn) {
|
|
63
|
+
return this.#keys.hold(key, fn, 0, permitOf);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
function waitOf(options) {
|
|
67
|
+
return ms(options?.wait ?? defaultWait);
|
|
68
|
+
}
|
|
69
|
+
/** What hold gives: fn's value, a hold told not to wait finding the key held. */
|
|
70
|
+
function held(tried, place) {
|
|
71
|
+
if (!tried.acquired) {
|
|
72
|
+
throw new InUseError(`${place}: held, and the hold would not wait`);
|
|
73
|
+
}
|
|
74
|
+
return tried.value;
|
|
75
|
+
}
|
|
76
|
+
const leaseOf = (holding) => ({ fence: holding.fence, signal: holding.signal });
|
|
77
|
+
const permitOf = (holding) => ({ signal: holding.signal });
|
|
78
|
+
// The keys the caller holds or waits for, as its async context carries them,
|
|
79
|
+
// each with the link of the store it is of.
|
|
80
|
+
const holding = new AsyncLocalStorage();
|
|
81
|
+
/** What a lock and a semaphore share: asking for a key, and the lease once given. */
|
|
82
|
+
class Keys {
|
|
83
|
+
#link;
|
|
84
|
+
#kind;
|
|
85
|
+
#name;
|
|
86
|
+
#limit;
|
|
87
|
+
#ttl;
|
|
88
|
+
#maxHold;
|
|
89
|
+
constructor(link, kind, name, limit, options) {
|
|
90
|
+
this.#link = link;
|
|
91
|
+
this.#kind = kind;
|
|
92
|
+
this.#name = name;
|
|
93
|
+
this.#limit = limit;
|
|
94
|
+
this.#ttl = ms(options?.ttl ?? defaultTtl);
|
|
95
|
+
this.#maxHold = options?.maxHold === undefined ? undefined : ms(options.maxHold);
|
|
96
|
+
}
|
|
97
|
+
/** The key as an error names it: `lock invoices: key "42"`. */
|
|
98
|
+
place(key) {
|
|
99
|
+
return `${this.#kind} ${this.#name}: key ${JSON.stringify(keyText(key))}`;
|
|
100
|
+
}
|
|
101
|
+
async hold(key, fn, wait, viewOf) {
|
|
102
|
+
const place = this.place(key);
|
|
103
|
+
this.#refuse(place);
|
|
104
|
+
const answer = await this.#ask(keyText(key), wait);
|
|
105
|
+
if (answer.acquired !== true) {
|
|
106
|
+
return { acquired: false };
|
|
107
|
+
}
|
|
108
|
+
const lease = new Holding(this.#link, place, answer, this.#ttl);
|
|
109
|
+
try {
|
|
110
|
+
const inside = [...(holding.getStore() ?? []), [this.#link, place]];
|
|
111
|
+
const value = await holding.run(inside, () => fn(viewOf(lease)));
|
|
112
|
+
lease.check();
|
|
113
|
+
return { acquired: true, value };
|
|
114
|
+
}
|
|
115
|
+
finally {
|
|
116
|
+
await lease.end();
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Refuses a hold that would wait for what its caller holds: a database's
|
|
121
|
+
* writer, which a transaction keeps while the key is waited for, or the
|
|
122
|
+
* same key.
|
|
123
|
+
*/
|
|
124
|
+
#refuse(place) {
|
|
125
|
+
if (insideStoreTx() || insideDatabaseTx()) {
|
|
126
|
+
throw new InvalidError(`${place}: a hold inside a transaction would keep its writer while the key is waited for: hold first`);
|
|
127
|
+
}
|
|
128
|
+
if (holding.getStore()?.some(([link, held]) => link === this.#link && held === place)) {
|
|
129
|
+
throw new InvalidError(`${place}: a hold of a key inside its own hold would wait for itself`);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
// A connection lost on the way asks again with the same request, which the
|
|
133
|
+
// store answers with the lease it gave, or with the ask's place in line.
|
|
134
|
+
async #ask(key, wait) {
|
|
135
|
+
const body = LocksHold.encode({
|
|
136
|
+
kind: this.#kind,
|
|
137
|
+
name: this.#name,
|
|
138
|
+
key,
|
|
139
|
+
limit: this.#limit,
|
|
140
|
+
ttl: this.#ttl,
|
|
141
|
+
maxHold: this.#maxHold,
|
|
142
|
+
wait,
|
|
143
|
+
request: crypto.getRandomValues(new Uint8Array(16)),
|
|
144
|
+
});
|
|
145
|
+
const answer = await this.#link.run('read', connection => connection.session.call(methods['locks.hold'], body, currentSignal()));
|
|
146
|
+
return LocksHeld.decode(answer);
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* A lease this program holds: renewed at a third of its ttl, and counted lost
|
|
151
|
+
* at its own deadline, the time it sent the last renewal that succeeded plus
|
|
152
|
+
* its ttl, less a margin, or at maxHold.
|
|
153
|
+
*/
|
|
154
|
+
class Holding {
|
|
155
|
+
fence;
|
|
156
|
+
#link;
|
|
157
|
+
#place;
|
|
158
|
+
#lease;
|
|
159
|
+
#ttl;
|
|
160
|
+
#lost = new AbortController();
|
|
161
|
+
#renewing;
|
|
162
|
+
#runningOut;
|
|
163
|
+
#revoking;
|
|
164
|
+
constructor(link, place, answer, ttl) {
|
|
165
|
+
this.#link = link;
|
|
166
|
+
this.#place = place;
|
|
167
|
+
this.#lease = answer.lease ?? new Uint8Array(0);
|
|
168
|
+
this.#ttl = ttl;
|
|
169
|
+
this.fence = answer.fence === undefined || answer.fence === '' ? 0n : BigInt(answer.fence);
|
|
170
|
+
this.#renewing = unref(setInterval(() => void this.#renew(), Math.max(1, Math.floor(ttl / 3))));
|
|
171
|
+
this.#runOutAt(performance.now() + ttl);
|
|
172
|
+
const revokeIn = answer.revokeIn;
|
|
173
|
+
this.#revoking =
|
|
174
|
+
revokeIn === undefined
|
|
175
|
+
? undefined
|
|
176
|
+
: unref(setTimeout(() => this.#lose('it was revoked at its maxHold'), revokeIn));
|
|
177
|
+
}
|
|
178
|
+
get signal() {
|
|
179
|
+
return this.#lost.signal;
|
|
180
|
+
}
|
|
181
|
+
/** Throws why the lease was lost, if it was. */
|
|
182
|
+
check() {
|
|
183
|
+
if (this.#lost.signal.aborted) {
|
|
184
|
+
throw this.#lost.signal.reason;
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
/** Stops renewing and lets the key go; a lease lost already lets nothing go. */
|
|
188
|
+
async end() {
|
|
189
|
+
this.#stop();
|
|
190
|
+
const body = LocksLease.encode({ lease: this.#lease });
|
|
191
|
+
await this.#link
|
|
192
|
+
.run('read', connection => connection.session.call(methods['locks.release'], body))
|
|
193
|
+
.catch(() => { });
|
|
194
|
+
}
|
|
195
|
+
async #renew() {
|
|
196
|
+
const sent = performance.now();
|
|
197
|
+
const body = LocksRenew.encode({ lease: this.#lease, ttl: this.#ttl });
|
|
198
|
+
try {
|
|
199
|
+
await this.#link.run('read', connection => connection.session.call(methods['locks.renew'], body));
|
|
200
|
+
this.#runOutAt(sent + this.#ttl);
|
|
201
|
+
}
|
|
202
|
+
catch (err) {
|
|
203
|
+
if (err instanceof LostError) {
|
|
204
|
+
this.#lose('it ran out before it was renewed');
|
|
205
|
+
}
|
|
206
|
+
else if (err instanceof ClosedError && !(err instanceof ConnectionLostError)) {
|
|
207
|
+
this.#lose('its store closed', err);
|
|
208
|
+
}
|
|
209
|
+
// any other failure keeps renewing until the lease's own deadline
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
#runOutAt(deadline) {
|
|
213
|
+
if (this.#runningOut !== undefined) {
|
|
214
|
+
clearTimeout(this.#runningOut);
|
|
215
|
+
}
|
|
216
|
+
const margin = Math.min(1000, this.#ttl / 10);
|
|
217
|
+
const left = Math.max(0, deadline - margin - performance.now());
|
|
218
|
+
this.#runningOut = unref(setTimeout(() => this.#lose('it was not renewed in time'), left));
|
|
219
|
+
}
|
|
220
|
+
#lose(why, cause) {
|
|
221
|
+
this.#stop();
|
|
222
|
+
if (!this.#lost.signal.aborted) {
|
|
223
|
+
this.#lost.abort(cause ?? new LostError(`${this.#place}: the lease was lost: ${why}`));
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
#stop() {
|
|
227
|
+
clearInterval(this.#renewing);
|
|
228
|
+
clearTimeout(this.#runningOut);
|
|
229
|
+
clearTimeout(this.#revoking);
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
/** A timer that keeps no program running by itself. */
|
|
233
|
+
function unref(timer) {
|
|
234
|
+
;
|
|
235
|
+
timer.unref?.();
|
|
236
|
+
return timer;
|
|
237
|
+
}
|
package/dist/logger.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { DropNotice, FailureLog, type Say } from './background.ts';
|
|
2
|
-
import { type
|
|
2
|
+
import { type EnvLayer, type Setting } from './config.ts';
|
|
3
|
+
import { type ConsoleFormat, type ConsoleLine, type ConsoleTime, type Redactor } from './console.ts';
|
|
3
4
|
import type { Fields, Level } from './records.ts';
|
|
4
5
|
export interface LoggerOptions {
|
|
5
6
|
/** the lines held between writes; past it a line is dropped and counted: 1024 */
|
|
@@ -14,8 +15,25 @@ export interface LoggerOptions {
|
|
|
14
15
|
hideStream?: boolean;
|
|
15
16
|
/** where the console lines go: process.stderr when absent */
|
|
16
17
|
to?: ConsoleOut;
|
|
17
|
-
/**
|
|
18
|
+
/**
|
|
19
|
+
* secrets whose fields are hidden, in the store and on the console, at any
|
|
20
|
+
* depth: a key hides its value when some of its words in a row, written
|
|
21
|
+
* together, are a name's, so 'api key' hides api_key and apiKey; `secrets`
|
|
22
|
+
* holds the usual ones
|
|
23
|
+
*/
|
|
18
24
|
redact?: readonly string[];
|
|
25
|
+
/** leaves a URL's password in a value as it is, which is otherwise hidden */
|
|
26
|
+
keepUrlPasswords?: boolean;
|
|
27
|
+
/** changes each field's value before it is hidden, kept and shown */
|
|
28
|
+
replace?: (key: string, value: unknown) => unknown;
|
|
29
|
+
/**
|
|
30
|
+
* where LOG_LEVEL, LOG_FORMAT and LOG_TIME are read, which win over the
|
|
31
|
+
* options: `env('APP')` reads APP_LOG_LEVEL and the rest, and false
|
|
32
|
+
* reads nothing; the bare names when absent
|
|
33
|
+
*/
|
|
34
|
+
env?: EnvLayer | false;
|
|
35
|
+
/** adds where each line was logged: source={"function":…,"file":…,"line":…} */
|
|
36
|
+
source?: boolean;
|
|
19
37
|
}
|
|
20
38
|
/** Where console lines go: process.stdout, a file's stream, or any other writer. */
|
|
21
39
|
export interface ConsoleOut {
|
|
@@ -29,7 +47,9 @@ interface Shared {
|
|
|
29
47
|
stream: string;
|
|
30
48
|
most: number;
|
|
31
49
|
least: number;
|
|
32
|
-
|
|
50
|
+
redact: Redactor | undefined;
|
|
51
|
+
replace: ((key: string, value: unknown) => unknown) | undefined;
|
|
52
|
+
source: boolean;
|
|
33
53
|
print: ((line: ConsoleLine) => void) | undefined;
|
|
34
54
|
waiting: ConsoleLine[];
|
|
35
55
|
timer: ReturnType<typeof setInterval> | undefined;
|
|
@@ -42,7 +62,7 @@ interface Shared {
|
|
|
42
62
|
/**
|
|
43
63
|
* A logger of the console alone, for a program that wants the logger and not
|
|
44
64
|
* the records: its lines are written as a store's logger writes them, and
|
|
45
|
-
* `store.
|
|
65
|
+
* `store.logger(stream)` in its place keeps them too.
|
|
46
66
|
*
|
|
47
67
|
* ```ts
|
|
48
68
|
* const log = logger('app', { redact: ['password'] })
|
|
@@ -54,6 +74,22 @@ export declare function logger(stream: string, options?: LoggerOptions): Logger;
|
|
|
54
74
|
export declare function newLogger(append: ((lines: ConsoleLine[]) => Promise<void>) | undefined, stream: string, options?: LoggerOptions, out?: ConsoleOut & {
|
|
55
75
|
utc?: boolean;
|
|
56
76
|
}): Logger;
|
|
77
|
+
/**
|
|
78
|
+
* What a store's logger declares its config `log` with: the code's options
|
|
79
|
+
* as the defaults, trace for a logger told no level, and the variables it
|
|
80
|
+
* read as the layer over them; and how it takes the level each value gives.
|
|
81
|
+
*/
|
|
82
|
+
export interface LogConfig {
|
|
83
|
+
readonly layers: readonly [LogDeclaration, ...EnvLayer[]];
|
|
84
|
+
take(level: string): void;
|
|
85
|
+
}
|
|
86
|
+
type LogDeclaration = {
|
|
87
|
+
level: Setting<string, true>;
|
|
88
|
+
format: Setting<string>;
|
|
89
|
+
time: Setting<string>;
|
|
90
|
+
};
|
|
91
|
+
/** A store's logger of one stream, and what it declares its config `log` with. */
|
|
92
|
+
export declare function newStoreLogger(append: (lines: ConsoleLine[]) => Promise<void>, stream: string, options?: LoggerOptions): [Logger, LogConfig];
|
|
57
93
|
/** TinyStore's own lines, on the console of a logger of stream tinystore made when first needed. */
|
|
58
94
|
export declare const sayOwn: Say;
|
|
59
95
|
/**
|
|
@@ -63,7 +99,7 @@ export declare const sayOwn: Say;
|
|
|
63
99
|
* its context, who is speaking.
|
|
64
100
|
*
|
|
65
101
|
* ```ts
|
|
66
|
-
* const log = store.
|
|
102
|
+
* const log = store.logger('api')
|
|
67
103
|
* log.info('server started', { port: 3000 })
|
|
68
104
|
* log.with({ requestId }).warn('slow request', { ms: 1200 })
|
|
69
105
|
* log.event('user.created', { userId: 42 }) // a record named for the event
|
|
@@ -71,7 +107,7 @@ export declare const sayOwn: Say;
|
|
|
71
107
|
*/
|
|
72
108
|
export declare class Logger {
|
|
73
109
|
#private;
|
|
74
|
-
/** Loggers come from `logger(stream)`, `store.
|
|
110
|
+
/** Loggers come from `logger(stream)`, `store.logger(stream)` and their `with`. */
|
|
75
111
|
constructor(shared: Shared, context: string[]);
|
|
76
112
|
/**
|
|
77
113
|
* The lines dropped since the logger began: a full buffer, or a write that
|
|
@@ -93,8 +129,8 @@ export declare class Logger {
|
|
|
93
129
|
}
|
|
94
130
|
/**
|
|
95
131
|
* Fields as key, JSON pairs, as a console writes them and the store keeps
|
|
96
|
-
* them: an Error's value its stack, which JSON would write as {},
|
|
97
|
-
*
|
|
132
|
+
* them: an Error's value its stack, which JSON would write as {}, a secret's
|
|
133
|
+
* value hidden at any depth, and a URL's password unless kept.
|
|
98
134
|
*/
|
|
99
|
-
export declare function encodeFields(fields: Fields,
|
|
135
|
+
export declare function encodeFields(fields: Fields, redact: Redactor | undefined, replace?: (key: string, value: unknown) => unknown): string[];
|
|
100
136
|
export {};
|