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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
@@ -0,0 +1,819 @@
1
+ // A program's instruments, as docs/guides/metrics/README.md has them: counters, gauges,
2
+ // a gauge read from a function, timers and histograms, each set of labels a
3
+ // series of its own. A call changes a number here and never waits. What
4
+ // changed goes to the store's totals on a stream of its own, a batch a
5
+ // second, each numbered in this run's session, so that the store counts it
6
+ // once: a batch whose answer a lost connection took goes again on the next,
7
+ // and a store that started again is sent nothing it may have counted.
8
+ import { randomBytes } from 'node:crypto';
9
+ import { FailureLog, messageOf } from './background.js';
10
+ import { InvalidError, OutcomeUnknownError, UnavailableError } from './errors.js';
11
+ import { sayOwn } from './logger.js';
12
+ import { ConnectionLostError } from './session.js';
13
+ import { ms } from './time.js';
14
+ import { MetricsAck, MetricsBatch, MetricsSession, methods } from './wire/protocol.js';
15
+ /** The sets of labels an instrument holds; past them it counts into the series of __overflow. */
16
+ const mostSets = 2000;
17
+ const sendEvery = 1000;
18
+ /** How often a gauge's function is read. */
19
+ const readEvery = 15_000;
20
+ /** Batches sent and not yet answered, past which changes gather for the next. */
21
+ const mostUnanswered = 16;
22
+ /** The changes a batch carries at most. */
23
+ const mostChanges = 1000;
24
+ /** How long a counter's or a timer's set of labels stays without a call. */
25
+ const idle = 3_600_000;
26
+ /** The bounds a timer or a histogram takes at most. */
27
+ const mostBounds = 128;
28
+ /**
29
+ * The instruments of a store's handle, and what sends their changes. A store
30
+ * has one; `store.metrics` makes its instruments through it.
31
+ */
32
+ export class Instruments {
33
+ #link;
34
+ #session = randomBytes(16);
35
+ #declared = new Map();
36
+ #byId = new Map();
37
+ #pending = new Map();
38
+ #unanswered = [];
39
+ #answered = 0;
40
+ #next = 1;
41
+ #ids = 0;
42
+ #opened;
43
+ #opening;
44
+ /** the sends in turn, so that batches leave in their order */
45
+ #pumping = Promise.resolve();
46
+ #sending;
47
+ #reading;
48
+ #stopped = false;
49
+ /** What the store refused, or a restart lost, since a flush last failed with it */
50
+ #unreported;
51
+ #failures = new FailureLog('metrics instruments', sayOwn);
52
+ constructor(link) {
53
+ this.#link = link;
54
+ }
55
+ /**
56
+ * An instrument of name, made the first time, read by functions when
57
+ * `read` says so; another form or other options than it has are refused.
58
+ */
59
+ declare(name, form, options, read = false) {
60
+ const told = toldOf(name, form, options);
61
+ const held = this.#declared.get(name);
62
+ if (held !== undefined) {
63
+ if (held.form !== form || !sameOptions(held, told) || read !== (held.reads !== undefined)) {
64
+ throw new InvalidError(`metrics ${name}: another instrument or other options than it has while the store is open`);
65
+ }
66
+ return held;
67
+ }
68
+ const declared = {
69
+ ...told,
70
+ id: ++this.#ids,
71
+ name,
72
+ form,
73
+ sets: new Map(),
74
+ overflow: undefined,
75
+ refused: false,
76
+ reads: read ? new Map() : undefined,
77
+ };
78
+ this.#declared.set(name, declared);
79
+ this.#byId.set(declared.id, declared);
80
+ this.#start();
81
+ return declared;
82
+ }
83
+ /**
84
+ * A gauge of name whose set of labels `read` gives every 15 seconds; each
85
+ * set has a function of its own, made once while the store is open.
86
+ */
87
+ reader(name, labels, options, read) {
88
+ const declared = this.declare(name, 'gauge', options, true);
89
+ const key = keyOf(labels);
90
+ if (declared.reads?.has(key)) {
91
+ throw new InvalidError(`metrics ${name}: a function reads its gauge of ${JSON.stringify(labels)} already while the store is open`);
92
+ }
93
+ declared.reads?.set(key, { labels, read, reading: false, failed: undefined });
94
+ }
95
+ /** The set of labels of an instrument, made the first time; past the sets it holds, its __overflow. */
96
+ setOf(instrument, labels) {
97
+ const key = keyOf(labels);
98
+ const held = instrument.sets.get(key);
99
+ if (held !== undefined) {
100
+ return held;
101
+ }
102
+ if (instrument.sets.size >= mostSets) {
103
+ instrument.overflow ??= this.#labelled(instrument, {}, true);
104
+ return instrument.overflow;
105
+ }
106
+ const set = this.#labelled(instrument, labels, false);
107
+ instrument.sets.set(key, set);
108
+ return set;
109
+ }
110
+ #labelled(instrument, labels, overflow) {
111
+ return { id: ++this.#ids, instrument, labels, overflow, touched: Date.now(), value: undefined };
112
+ }
113
+ /** What calls changed of a set since the last batch, if any. */
114
+ pending(set) {
115
+ return this.#pending.get(set);
116
+ }
117
+ /** What a call changes of a set, kept for the next batch. */
118
+ change(set) {
119
+ set.touched = Date.now();
120
+ let change = this.#pending.get(set);
121
+ if (change === undefined) {
122
+ change = blank(set.instrument);
123
+ this.#pending.set(set, change);
124
+ }
125
+ return change;
126
+ }
127
+ /**
128
+ * Sends what changed now and has the store write its totals; resolves
129
+ * once it has, and says whether there was anything to send it with. One
130
+ * the store cannot be reached for fails as a call does, and what it
131
+ * carried goes once the store can be. What the store refused since the
132
+ * flush before, and what a store that started again may have lost, fail
133
+ * it, each once.
134
+ */
135
+ async flush() {
136
+ if (this.#declared.size === 0) {
137
+ return false;
138
+ }
139
+ await this.#readGauges();
140
+ const done = new Promise((resolve, reject) => {
141
+ const batches = this.#batches(true);
142
+ batches.at(-1)?.waiters.push({ resolve, reject });
143
+ });
144
+ void this.#pump();
145
+ await done;
146
+ return true;
147
+ }
148
+ /** Stops the timers, sends what is left, and ends the stream; the store's close calls it. */
149
+ async stop() {
150
+ if (this.#stopped) {
151
+ return;
152
+ }
153
+ this.#stopped = true;
154
+ clearInterval(this.#sending);
155
+ clearInterval(this.#reading);
156
+ if (this.#declared.size === 0) {
157
+ return;
158
+ }
159
+ try {
160
+ await this.flush();
161
+ }
162
+ catch (err) {
163
+ this.#failures.failed(err);
164
+ }
165
+ await this.#opened?.stream.send(new Uint8Array(0), true).catch(() => { });
166
+ }
167
+ #start() {
168
+ if (this.#sending !== undefined || this.#stopped) {
169
+ return;
170
+ }
171
+ this.#sending = setInterval(() => this.#tick(), sendEvery);
172
+ this.#sending.unref?.();
173
+ this.#reading = setInterval(() => void this.#readGauges(), readEvery);
174
+ this.#reading.unref?.();
175
+ }
176
+ #tick() {
177
+ const now = Date.now();
178
+ for (const instrument of this.#declared.values()) {
179
+ if (instrument.form === 'gauge') {
180
+ continue;
181
+ }
182
+ for (const [key, set] of instrument.sets) {
183
+ if (now - set.touched >= idle && !this.#pending.has(set)) {
184
+ instrument.sets.delete(key);
185
+ }
186
+ }
187
+ }
188
+ if (this.#pending.size > 0 && this.#unanswered.length < mostUnanswered) {
189
+ this.#batches(false);
190
+ }
191
+ void this.#pump();
192
+ }
193
+ /** What waits, as batches of mostChanges changes each; with flush, the last asks the store to write. */
194
+ #batches(flush) {
195
+ const made = [];
196
+ const pending = [...this.#pending];
197
+ this.#pending = new Map();
198
+ for (let from = 0; from < pending.length || (flush && made.length === 0); from += mostChanges) {
199
+ const changes = new Map(pending.slice(from, from + mostChanges));
200
+ const last = from + mostChanges >= pending.length;
201
+ made.push({
202
+ number: this.#next++,
203
+ changes,
204
+ flush: flush && last,
205
+ waiters: [],
206
+ sentOn: undefined,
207
+ });
208
+ }
209
+ this.#unanswered.push(...made);
210
+ return made;
211
+ }
212
+ /** Sends every unanswered batch that has not gone on the stream open now, in order, a send at a time. */
213
+ #pump() {
214
+ this.#pumping = this.#pumping.then(() => this.#sendWaiting());
215
+ return this.#pumping;
216
+ }
217
+ // a connection lost on the way is dialled again, as a call's is; a store
218
+ // that cannot be dialled is tried again at the next tick, not at once
219
+ async #sendWaiting() {
220
+ for (let tries = 0; !this.#sentAll(); tries++) {
221
+ try {
222
+ await this.#sendOn(await this.#stream());
223
+ this.#failures.succeeded();
224
+ return;
225
+ }
226
+ catch (err) {
227
+ if (tries < 2 && err instanceof ConnectionLostError) {
228
+ continue;
229
+ }
230
+ this.#failures.failed(err);
231
+ this.#fail(err);
232
+ return;
233
+ }
234
+ }
235
+ }
236
+ #sentAll() {
237
+ return this.#unanswered.every(batch => batch.sentOn !== undefined && batch.sentOn === this.#opened);
238
+ }
239
+ async #sendOn(opened) {
240
+ for (const batch of this.#unanswered) {
241
+ if (batch.sentOn !== opened) {
242
+ batch.sentOn = opened;
243
+ await opened.stream.send(encode(batch, opened), false);
244
+ }
245
+ }
246
+ }
247
+ /** Every flush waiting fails with err; the batches wait for the next send. */
248
+ #fail(err) {
249
+ for (const batch of this.#unanswered) {
250
+ for (const waiter of batch.waiters.splice(0)) {
251
+ waiter.reject(errorOf(err));
252
+ }
253
+ }
254
+ }
255
+ /**
256
+ * The store refused the batch it was to apply next and would refuse it
257
+ * again: it is dropped, said once, and those after it are numbered on.
258
+ */
259
+ #drop(err) {
260
+ const dropped = this.#unanswered.shift();
261
+ if (dropped === undefined) {
262
+ return;
263
+ }
264
+ const error = messageOf(err);
265
+ sayOwn('warn', 'metrics instruments dropped a batch the store refused', {
266
+ changes: dropped.changes.size,
267
+ error,
268
+ });
269
+ this.#failWith(dropped.waiters, errorOf(err));
270
+ this.#renumber();
271
+ }
272
+ /** Fails the flushes that wait with err, or the next flush when none does. */
273
+ #failWith(waiters, err) {
274
+ if (waiters.length === 0) {
275
+ this.#unreported ??= err;
276
+ }
277
+ for (const waiter of waiters.splice(0)) {
278
+ waiter.reject(err);
279
+ }
280
+ }
281
+ /** The stream open now, or one opened and resumed: the store says what it applied of the session. */
282
+ #stream() {
283
+ if (this.#opened !== undefined && !this.#opened.stream.finished) {
284
+ return Promise.resolve(this.#opened);
285
+ }
286
+ this.#opening ??= this.#open().finally(() => {
287
+ this.#opening = undefined;
288
+ });
289
+ return this.#opening;
290
+ }
291
+ async #open() {
292
+ const connection = await this.#link.connection();
293
+ const body = MetricsSession.encode({ id: this.#session, after: this.#answered });
294
+ const stream = await connection.session.open(methods['metrics.instruments'], body, false);
295
+ const head = await stream.next();
296
+ const opened = { stream, instruments: new Set(), sets: new Set() };
297
+ this.#resume(MetricsAck.decode(head.body));
298
+ this.#opened = opened;
299
+ void this.#listen(opened);
300
+ return opened;
301
+ }
302
+ /**
303
+ * Takes up where the store is: a batch it applied is done; one sent that
304
+ * it may have applied, when it knows no session, is dropped rather than
305
+ * counted twice, and those never sent are numbered on. Every gauge's value
306
+ * goes again, since a gauge left with the last connection.
307
+ */
308
+ #resume(ack) {
309
+ const applied = ack.applied ?? 0;
310
+ if (ack.known === true) {
311
+ this.#answer(ack);
312
+ }
313
+ else {
314
+ const lost = this.#unanswered.filter(batch => batch.sentOn !== undefined);
315
+ this.#unanswered = this.#unanswered.filter(batch => batch.sentOn === undefined);
316
+ if (lost.length > 0) {
317
+ const changes = lost.reduce((n, batch) => n + batch.changes.size, 0);
318
+ sayOwn('warn', 'metrics instruments dropped what a store that started again may have counted', {
319
+ batches: lost.length,
320
+ changes,
321
+ });
322
+ }
323
+ if (lost.length > 0) {
324
+ const unknown = new OutcomeUnknownError(`the store started again: ${lost.length} batches of instruments it may have counted before it stopped are dropped rather than counted twice`);
325
+ this.#failWith(lost.flatMap(batch => batch.waiters), unknown);
326
+ }
327
+ this.#answered = applied;
328
+ this.#renumber();
329
+ }
330
+ for (const instrument of this.#declared.values()) {
331
+ for (const set of instrument.form === 'gauge' ? instrument.sets.values() : []) {
332
+ if (set.value !== undefined) {
333
+ this.change(set).value = set.value;
334
+ }
335
+ }
336
+ }
337
+ }
338
+ /** Numbers what waits after the last batch the store answered. */
339
+ #renumber() {
340
+ this.#next = this.#answered + 1;
341
+ for (const batch of this.#unanswered) {
342
+ batch.number = this.#next++;
343
+ }
344
+ }
345
+ /**
346
+ * Reads the store's answers on a stream until it ends. What it had not
347
+ * answered goes again at once on another, but for a batch it refused.
348
+ */
349
+ async #listen(opened) {
350
+ try {
351
+ for (;;) {
352
+ const event = await opened.stream.next();
353
+ opened.stream.consumed(event.body.length);
354
+ this.#answer(MetricsAck.decode(event.body));
355
+ if (event.end) {
356
+ return;
357
+ }
358
+ }
359
+ }
360
+ catch (err) {
361
+ if (!this.#stopped) {
362
+ this.#failures.failed(err);
363
+ }
364
+ if (err instanceof InvalidError && !this.#stopped) {
365
+ this.#drop(err);
366
+ }
367
+ }
368
+ finally {
369
+ if (this.#opened === opened) {
370
+ this.#opened = undefined;
371
+ }
372
+ if (!this.#stopped && this.#unanswered.length > 0) {
373
+ void this.#pump();
374
+ }
375
+ }
376
+ }
377
+ /** An answer: the instruments the store refused, then the batches it applied. */
378
+ #answer(ack) {
379
+ for (const refused of ack.refused ?? []) {
380
+ const instrument = this.#byId.get(refused.instrument ?? 0);
381
+ if (instrument !== undefined && !instrument.refused) {
382
+ instrument.refused = true;
383
+ const error = refused.error ?? '';
384
+ sayOwn('warn', 'metrics instrument refused', { instrument: instrument.name, error });
385
+ this.#unreported ??= new InvalidError(`metrics ${instrument.name}: the store refused it: ${error}`);
386
+ }
387
+ }
388
+ const applied = ack.applied ?? 0;
389
+ this.#answered = Math.max(this.#answered, applied);
390
+ this.#settle(applied);
391
+ }
392
+ /** The batches the store applied, each done: a flush waiting resolves, or fails with what it was not told yet. */
393
+ #settle(applied) {
394
+ while ((this.#unanswered[0]?.number ?? Infinity) <= applied) {
395
+ const done = this.#unanswered.shift();
396
+ for (const waiter of done?.waiters ?? []) {
397
+ const failed = this.#unreported;
398
+ this.#unreported = undefined;
399
+ if (failed === undefined) {
400
+ waiter.resolve();
401
+ }
402
+ else {
403
+ waiter.reject(failed);
404
+ }
405
+ }
406
+ }
407
+ }
408
+ /** Calls each gauge's function whose last call ended; a value it gives is sent with the next batch. */
409
+ async #readGauges() {
410
+ const reads = [];
411
+ for (const instrument of this.#declared.values()) {
412
+ for (const gauge of instrument.refused ? [] : (instrument.reads?.values() ?? [])) {
413
+ if (!gauge.reading) {
414
+ reads.push(this.#readGauge(instrument, gauge));
415
+ }
416
+ }
417
+ }
418
+ await Promise.all(reads);
419
+ }
420
+ async #readGauge(instrument, gauge) {
421
+ gauge.reading = true;
422
+ try {
423
+ const value = await gauge.read();
424
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
425
+ throw new InvalidError(`a gauge's function gave ${String(value)}, where a finite number is`);
426
+ }
427
+ const set = this.setOf(instrument, gauge.labels);
428
+ set.value = value;
429
+ this.change(set).value = value;
430
+ gauge.failed = undefined;
431
+ }
432
+ catch (err) {
433
+ const error = messageOf(err);
434
+ if (error !== gauge.failed) {
435
+ const labels = JSON.stringify(gauge.labels);
436
+ sayOwn('warn', 'metrics gauge read failed', { instrument: instrument.name, labels, error });
437
+ gauge.failed = error;
438
+ }
439
+ }
440
+ finally {
441
+ gauge.reading = false;
442
+ }
443
+ }
444
+ }
445
+ function errorOf(err) {
446
+ return err instanceof Error ? err : new UnavailableError(String(err));
447
+ }
448
+ /** A change of nothing yet, with room for an instrument's buckets. */
449
+ function blank(instrument) {
450
+ const buckets = instrument.bounds === undefined ? undefined : new Array(instrument.bounds.length + 1).fill(0);
451
+ const bins = instrument.exponential ? new Map() : undefined;
452
+ return { add: undefined, value: undefined, count: 0, sum: 0, longest: 0, buckets, bins };
453
+ }
454
+ /** A batch's bytes for a stream: the instruments and sets it names that the stream has not declared. */
455
+ function encode(batch, opened) {
456
+ const instruments = [];
457
+ const sets = [];
458
+ const changes = [];
459
+ for (const [set, change] of batch.changes) {
460
+ const instrument = set.instrument;
461
+ if (instrument.refused) {
462
+ continue;
463
+ }
464
+ if (!opened.instruments.has(instrument.id)) {
465
+ opened.instruments.add(instrument.id);
466
+ instruments.push({
467
+ number: instrument.id,
468
+ name: instrument.name,
469
+ form: instrument.form,
470
+ unit: instrument.unit,
471
+ help: instrument.help,
472
+ keep: instrument.keep,
473
+ bounds: instrument.bounds,
474
+ exponential: instrument.exponential,
475
+ });
476
+ }
477
+ if (!opened.sets.has(set.id)) {
478
+ opened.sets.add(set.id);
479
+ sets.push({
480
+ number: set.id,
481
+ instrument: instrument.id,
482
+ labels: set.labels,
483
+ overflow: set.overflow,
484
+ });
485
+ }
486
+ changes.push({
487
+ set: set.id,
488
+ add: change.add,
489
+ value: change.value,
490
+ count: change.count,
491
+ sum: change.sum,
492
+ longest: change.longest,
493
+ buckets: change.buckets,
494
+ bins: change.bins === undefined ? undefined : Object.fromEntries(change.bins),
495
+ });
496
+ }
497
+ return MetricsBatch.encode({
498
+ number: batch.number,
499
+ instruments,
500
+ sets,
501
+ changes,
502
+ flush: batch.flush,
503
+ });
504
+ }
505
+ /** What an instrument was told, checked. */
506
+ function toldOf(name, form, options) {
507
+ checkName(name);
508
+ if (options.unit !== undefined && bytes(options.unit) > 32) {
509
+ throw new InvalidError(`metrics ${name}: a unit of 32 bytes at most`);
510
+ }
511
+ if (options.help !== undefined && bytes(options.help) > 1024) {
512
+ throw new InvalidError(`metrics ${name}: a help of 1024 bytes at most`);
513
+ }
514
+ const keep = options.keep === undefined ? undefined : ms(options.keep);
515
+ if (keep === 0) {
516
+ throw new InvalidError(`metrics ${name}: keep 0, where a name keeps its samples 1ms at least`);
517
+ }
518
+ const buckets = options.buckets;
519
+ if (buckets !== undefined && form !== 'timer' && form !== 'histogram') {
520
+ throw new InvalidError(`metrics ${name}: buckets are a timer's or a histogram's`);
521
+ }
522
+ if (buckets === 'exponential') {
523
+ return { unit: options.unit, help: options.help, keep, bounds: undefined, exponential: true };
524
+ }
525
+ return {
526
+ unit: options.unit,
527
+ help: options.help,
528
+ keep,
529
+ bounds: buckets === undefined ? undefined : checkedBounds(name, buckets),
530
+ exponential: false,
531
+ };
532
+ }
533
+ function checkedBounds(name, bounds) {
534
+ if (bounds.length === 0 || bounds.length > mostBounds) {
535
+ throw new InvalidError(`metrics ${name}: 1 to ${mostBounds} bounds`);
536
+ }
537
+ bounds.forEach((bound, i) => {
538
+ if (!(Number.isFinite(bound) && bound >= 0) || (i > 0 && !(bound > bounds[i - 1]))) {
539
+ throw new InvalidError(`metrics ${name}: bounds of 0 or more, each above the one before`);
540
+ }
541
+ });
542
+ return [...bounds];
543
+ }
544
+ function sameOptions(held, told) {
545
+ return (held.unit === told.unit &&
546
+ held.help === told.help &&
547
+ held.keep === told.keep &&
548
+ held.exponential === told.exponential &&
549
+ JSON.stringify(held.bounds) === JSON.stringify(told.bounds));
550
+ }
551
+ function checkName(name) {
552
+ if (name === '' || !name.isWellFormed() || bytes(name) > 4096) {
553
+ throw new InvalidError(`metrics name ${JSON.stringify(name)}: 1 to 4096 bytes of UTF-8`);
554
+ }
555
+ }
556
+ const encoder = new TextEncoder();
557
+ function bytes(text) {
558
+ return encoder.encode(text).length;
559
+ }
560
+ /** Labels as an instrument keeps them: text, a number or a boolean as its text, none of the store's own. */
561
+ export function labelsOf(given, timed) {
562
+ const labels = {};
563
+ for (const [label, value] of Object.entries(given)) {
564
+ if (label === '' || bytes(label) > 256) {
565
+ throw new InvalidError(`label ${JSON.stringify(label)}: a name of 1 to 256 bytes`);
566
+ }
567
+ if (label.startsWith('__')) {
568
+ throw new InvalidError(`label ${label}: a name beginning with __ is the store's own`);
569
+ }
570
+ if (timed && label === 'le') {
571
+ throw new InvalidError(`label le: a timer's _bucket series give it`);
572
+ }
573
+ if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
574
+ throw new InvalidError(`label ${label}: a value of text, a number or a boolean, where ${String(value)} is`);
575
+ }
576
+ const text = String(value);
577
+ if (bytes(text) > 4096) {
578
+ throw new InvalidError(`label ${label}: a value of 4096 bytes at most`);
579
+ }
580
+ labels[label] = text;
581
+ }
582
+ return labels;
583
+ }
584
+ function keyOf(labels) {
585
+ return JSON.stringify(Object.entries(labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
586
+ }
587
+ /**
588
+ * What a send would carry of a set, refused at the call that would take it
589
+ * past the largest number, which the store would refuse with nobody told.
590
+ */
591
+ function sums(declared, sum) {
592
+ if (!Number.isFinite(sum)) {
593
+ throw new InvalidError(`metrics ${declared.name}: a sum past the largest number a send carries`);
594
+ }
595
+ }
596
+ /** A finite number an instrument takes, or invalid at once where the program made it. */
597
+ function finite(name, what, value) {
598
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
599
+ throw new InvalidError(`metrics ${name}: ${what} ${String(value)}, where a finite number is`);
600
+ }
601
+ return value;
602
+ }
603
+ /** A total that only goes up, which the store keeps: processes counting into one series count into one total. */
604
+ export class Counter {
605
+ #instruments;
606
+ #declared;
607
+ #labels;
608
+ constructor(instruments, declared, labels) {
609
+ this.#instruments = instruments;
610
+ this.#declared = declared;
611
+ this.#labels = labels;
612
+ }
613
+ /** The same counter with more labels, a series of its own; the same labels in any order are one. */
614
+ with(labels) {
615
+ return new Counter(this.#instruments, this.#declared, {
616
+ ...this.#labels,
617
+ ...labelsOf(labels, false),
618
+ });
619
+ }
620
+ inc() {
621
+ this.add(1);
622
+ }
623
+ /** Adds n, a finite number of 0 or more; add(0) makes the set of labels known with a total of zero. */
624
+ add(n) {
625
+ if (finite(this.#declared.name, 'a counter adds', n) < 0) {
626
+ throw new InvalidError(`metrics ${this.#declared.name}: a counter adds ${n}; it only grows`);
627
+ }
628
+ if (this.#declared.refused) {
629
+ return;
630
+ }
631
+ const set = this.#instruments.setOf(this.#declared, this.#labels);
632
+ const added = (this.#instruments.pending(set)?.add ?? 0) + n;
633
+ sums(this.#declared, added);
634
+ this.#instruments.change(set).add = added;
635
+ }
636
+ }
637
+ /** A value that goes up and down, written while this program is connected. */
638
+ export class Gauge {
639
+ #instruments;
640
+ #declared;
641
+ #labels;
642
+ constructor(instruments, declared, labels) {
643
+ this.#instruments = instruments;
644
+ this.#declared = declared;
645
+ this.#labels = labels;
646
+ }
647
+ with(labels) {
648
+ return new Gauge(this.#instruments, this.#declared, {
649
+ ...this.#labels,
650
+ ...labelsOf(labels, false),
651
+ });
652
+ }
653
+ set(value) {
654
+ this.#to(finite(this.#declared.name, 'a gauge set to', value));
655
+ }
656
+ /** Moves it by n, from zero when it was never set. */
657
+ add(n) {
658
+ finite(this.#declared.name, 'a gauge moved by', n);
659
+ const set = this.#instruments.setOf(this.#declared, this.#labels);
660
+ this.#to(finite(this.#declared.name, 'a gauge moved to', (set.value ?? 0) + n));
661
+ }
662
+ inc() {
663
+ this.add(1);
664
+ }
665
+ dec() {
666
+ this.add(-1);
667
+ }
668
+ #to(value) {
669
+ if (this.#declared.refused) {
670
+ return;
671
+ }
672
+ const set = this.#instruments.setOf(this.#declared, this.#labels);
673
+ set.value = value;
674
+ this.#instruments.change(set).value = value;
675
+ }
676
+ }
677
+ /** Counts a duration or a value into a timer's or a histogram's change: its count, sum, longest and bucket. */
678
+ function measured(instruments, declared, labels, value) {
679
+ if (declared.refused) {
680
+ return;
681
+ }
682
+ const set = instruments.setOf(declared, labels);
683
+ sums(declared, (instruments.pending(set)?.sum ?? 0) + value);
684
+ const change = instruments.change(set);
685
+ change.count++;
686
+ change.sum += value;
687
+ change.longest = change.count === 1 ? value : Math.max(change.longest, value);
688
+ if (change.buckets !== undefined && declared.bounds !== undefined) {
689
+ const bucket = declared.bounds.findIndex(bound => value <= bound);
690
+ change.buckets[bucket < 0 ? declared.bounds.length : bucket] += 1;
691
+ }
692
+ if (change.bins !== undefined) {
693
+ const bin = binOf(value);
694
+ change.bins.set(bin, (change.bins.get(bin) ?? 0) + 1);
695
+ }
696
+ }
697
+ /** How many things took how long: their count, sum and longest in milliseconds, and their spread over its buckets. */
698
+ export class Timer {
699
+ #instruments;
700
+ #declared;
701
+ #labels;
702
+ constructor(instruments, declared, labels) {
703
+ this.#instruments = instruments;
704
+ this.#declared = declared;
705
+ this.#labels = labels;
706
+ }
707
+ with(labels) {
708
+ return new Timer(this.#instruments, this.#declared, {
709
+ ...this.#labels,
710
+ ...labelsOf(labels, true),
711
+ });
712
+ }
713
+ /** Records a duration measured elsewhere: milliseconds, as performance.now() counts them, or text such as '250ms'. */
714
+ record(duration) {
715
+ const millis = typeof duration === 'number'
716
+ ? finite(this.#declared.name, 'a duration of', duration)
717
+ : ms(duration);
718
+ if (millis < 0) {
719
+ throw new InvalidError(`metrics ${this.#declared.name}: a duration of ${millis}; a duration is never negative`);
720
+ }
721
+ measured(this.#instruments, this.#declared, this.#labels, millis);
722
+ }
723
+ /**
724
+ * Runs fn, awaits what it returns, returns or throws what it does, and
725
+ * records how long it took either way.
726
+ *
727
+ * const user = await latency.with({ route: '/users' }).measure(() => users.get(id))
728
+ */
729
+ async measure(fn) {
730
+ const started = performance.now();
731
+ try {
732
+ return await fn();
733
+ }
734
+ finally {
735
+ this.record(performance.now() - started);
736
+ }
737
+ }
738
+ /** A timing that records when it stops, for a span that is no one function. */
739
+ start() {
740
+ return new Timing(this);
741
+ }
742
+ }
743
+ /** A span a timer measures from its start; stop records it, once. */
744
+ export class Timing {
745
+ #timer;
746
+ #started = performance.now();
747
+ #stopped = false;
748
+ constructor(timer) {
749
+ this.#timer = timer;
750
+ }
751
+ /** Records how long since the timing started, the first time it is called; its milliseconds. */
752
+ stop() {
753
+ const took = performance.now() - this.#started;
754
+ if (!this.#stopped) {
755
+ this.#stopped = true;
756
+ this.#timer.record(took);
757
+ }
758
+ return took;
759
+ }
760
+ }
761
+ /** A timer of numbers that are not durations: a response's size in bytes. */
762
+ export class Histogram {
763
+ #instruments;
764
+ #declared;
765
+ #labels;
766
+ constructor(instruments, declared, labels) {
767
+ this.#instruments = instruments;
768
+ this.#declared = declared;
769
+ this.#labels = labels;
770
+ }
771
+ with(labels) {
772
+ return new Histogram(this.#instruments, this.#declared, {
773
+ ...this.#labels,
774
+ ...labelsOf(labels, true),
775
+ });
776
+ }
777
+ /** Records a value of 0 or more. */
778
+ record(value) {
779
+ if (finite(this.#declared.name, 'a value of', value) < 0) {
780
+ throw new InvalidError(`metrics ${this.#declared.name}: a value of ${value}; the lowest bucket starts at 0`);
781
+ }
782
+ measured(this.#instruments, this.#declared, this.#labels, value);
783
+ }
784
+ }
785
+ /** Upper bounds from start, each factor times the one before: exponentialBuckets(1, 2, 14) is 1, 2, 4 … 8192. */
786
+ export function exponentialBuckets(start, factor, count) {
787
+ if (!(start > 0 && factor > 1 && Number.isInteger(count) && count >= 1 && count <= mostBounds)) {
788
+ throw new InvalidError(`exponentialBuckets(${start}, ${factor}, ${count}): a start above 0, a factor above 1, 1 to ${mostBounds} bounds`);
789
+ }
790
+ const bounds = [start];
791
+ while (bounds.length < count) {
792
+ bounds.push(bounds.at(-1) * factor);
793
+ }
794
+ return bounds;
795
+ }
796
+ /**
797
+ * The fractions of Prometheus' native grid for schema 3, 2^(j/8 − 1), as its
798
+ * table writes them: three a unit in the last place below the nearest float,
799
+ * so that a value on a bound falls where Prometheus and the store put it.
800
+ */
801
+ const fractions = [
802
+ 0.5, 0.5452538663326288, 0.5946035575013605, 0.6484197773255048, 0.7071067811865475,
803
+ 0.7711054127039704, 0.8408964152537144, 0.9170040432046711,
804
+ ];
805
+ const halves = new DataView(new ArrayBuffer(8));
806
+ /** The interval of the store's grid a value of 0 or more falls in, by its label: '3:13', or 'zero'. */
807
+ export function binOf(value) {
808
+ if (value === 0) {
809
+ return 'zero';
810
+ }
811
+ // a subnormal falls in the lowest interval, whose bound is the least normal float
812
+ halves.setFloat64(0, Math.max(value, 2.2250738585072014e-308));
813
+ const high = halves.getUint32(0);
814
+ const exponent = ((high >>> 20) & 0x7ff) - 1022;
815
+ halves.setUint32(0, (high & ~(0x7ff << 20)) | (1022 << 20));
816
+ const fraction = halves.getFloat64(0);
817
+ const within = fractions.findIndex(bound => bound >= fraction);
818
+ return `3:${(within < 0 ? 8 : within) + (exponent - 1) * 8}`;
819
+ }