@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.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
@@ -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
+ }
@@ -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 ConsoleFormat, type ConsoleLine, type ConsoleTime } from './console.ts';
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
- /** fields whose values are hidden, in the store and on the console, at any depth, the case ignored */
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
- hides: ((key: string) => boolean) | undefined;
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.records.logger(stream)` in its place keeps them too.
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.records.logger('api')
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.records.logger(stream)` and their `with`. */
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 {}, and a field
97
- * hides names hidden at any depth.
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, hides: ((key: string) => boolean) | undefined): string[];
135
+ export declare function encodeFields(fields: Fields, redact: Redactor | undefined, replace?: (key: string, value: unknown) => unknown): string[];
100
136
  export {};