@tinyshed/tinystore 0.1.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +262 -0
- package/bin/tinystore.js +50 -0
- package/dist/background.d.ts +30 -0
- package/dist/background.js +93 -0
- package/dist/blobs.d.ts +98 -0
- package/dist/blobs.js +299 -0
- package/dist/cancel.d.ts +14 -0
- package/dist/cancel.js +22 -0
- package/dist/clock.d.ts +21 -0
- package/dist/clock.js +35 -0
- package/dist/config.d.ts +60 -0
- package/dist/config.js +417 -0
- package/dist/connection.d.ts +78 -0
- package/dist/connection.js +405 -0
- package/dist/console.d.ts +48 -0
- package/dist/console.js +195 -0
- package/dist/errors.d.ts +103 -0
- package/dist/errors.js +158 -0
- package/dist/handles.d.ts +28 -0
- package/dist/handles.js +37 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.js +7 -0
- package/dist/jobs.d.ts +304 -0
- package/dist/jobs.js +684 -0
- package/dist/kv.d.ts +283 -0
- package/dist/kv.js +815 -0
- package/dist/limiter.d.ts +45 -0
- package/dist/limiter.js +68 -0
- package/dist/logger.d.ts +96 -0
- package/dist/logger.js +243 -0
- package/dist/metrics.d.ts +249 -0
- package/dist/metrics.js +610 -0
- package/dist/once.d.ts +31 -0
- package/dist/once.js +116 -0
- package/dist/quota.d.ts +44 -0
- package/dist/quota.js +98 -0
- package/dist/records.d.ts +182 -0
- package/dist/records.js +346 -0
- package/dist/runtime/bun.d.ts +2 -0
- package/dist/runtime/bun.js +164 -0
- package/dist/runtime/node.d.ts +2 -0
- package/dist/runtime/node.js +157 -0
- package/dist/runtime/shared.d.ts +25 -0
- package/dist/runtime/shared.js +45 -0
- package/dist/runtime.d.ts +48 -0
- package/dist/runtime.js +4 -0
- package/dist/schema.d.ts +39 -0
- package/dist/schema.js +21 -0
- package/dist/session.d.ts +120 -0
- package/dist/session.js +546 -0
- package/dist/sql.d.ts +121 -0
- package/dist/sql.js +342 -0
- package/dist/store.d.ts +103 -0
- package/dist/store.js +153 -0
- package/dist/time.d.ts +35 -0
- package/dist/time.js +44 -0
- package/dist/trace.d.ts +18 -0
- package/dist/trace.js +22 -0
- package/dist/wire/codec.d.ts +90 -0
- package/dist/wire/codec.js +383 -0
- package/dist/wire/frame.d.ts +41 -0
- package/dist/wire/frame.js +102 -0
- package/dist/wire/messages.d.ts +1403 -0
- package/dist/wire/messages.js +472 -0
- package/dist/wire/msgpack.d.ts +93 -0
- package/dist/wire/msgpack.js +680 -0
- package/package.json +40 -0
- package/src/background.ts +108 -0
- package/src/blobs.ts +437 -0
- package/src/cancel.ts +26 -0
- package/src/clock.ts +45 -0
- package/src/config.ts +501 -0
- package/src/connection.ts +512 -0
- package/src/console.ts +228 -0
- package/src/errors.ts +211 -0
- package/src/handles.ts +68 -0
- package/src/index.ts +92 -0
- package/src/jobs.ts +963 -0
- package/src/kv.ts +1093 -0
- package/src/limiter.ts +99 -0
- package/src/logger.ts +326 -0
- package/src/metrics.ts +896 -0
- package/src/once.ts +142 -0
- package/src/quota.ts +137 -0
- package/src/records.ts +537 -0
- package/src/runtime/bun.ts +190 -0
- package/src/runtime/node.ts +177 -0
- package/src/runtime/shared.ts +61 -0
- package/src/runtime.ts +57 -0
- package/src/schema.ts +69 -0
- package/src/session.ts +665 -0
- package/src/sql.ts +478 -0
- package/src/store.ts +219 -0
- package/src/time.ts +87 -0
- package/src/trace.ts +32 -0
- package/src/wire/codec.ts +445 -0
- package/src/wire/frame.ts +139 -0
- package/src/wire/messages.ts +562 -0
- package/src/wire/msgpack.ts +712 -0
package/dist/once.js
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
// Answers a function gives once a key, as Go's kv.Once keeps them: a request
|
|
2
|
+
// sent again is answered as the first was rather than done twice. The server
|
|
3
|
+
// lets one call of a key run its function at a time, every client of the
|
|
4
|
+
// store included, and keeps what it returned.
|
|
5
|
+
import { currentSignal } from './cancel.js';
|
|
6
|
+
import { OutcomeUnknownError } from './errors.js';
|
|
7
|
+
import { handleOn, ownerText } from './handles.js';
|
|
8
|
+
import { LostError, watch } from './session.js';
|
|
9
|
+
import { KvCall, KvEntry, methods } from './wire/messages.js';
|
|
10
|
+
/** Answers kept once a key: open them with `store.kv.once(name)`. */
|
|
11
|
+
export class Once {
|
|
12
|
+
name;
|
|
13
|
+
#link;
|
|
14
|
+
#open;
|
|
15
|
+
#values;
|
|
16
|
+
#owners;
|
|
17
|
+
/** Answers come from `store.kv.once` and their `of`. */
|
|
18
|
+
constructor(link, name, open, values, owners) {
|
|
19
|
+
this.#link = link;
|
|
20
|
+
this.name = name;
|
|
21
|
+
this.#open = open;
|
|
22
|
+
this.#values = values;
|
|
23
|
+
this.#owners = owners;
|
|
24
|
+
}
|
|
25
|
+
/** The answers of a branch, each key apart from the same key elsewhere. */
|
|
26
|
+
of(...owners) {
|
|
27
|
+
return new Once(this.#link, this.name, this.#open, this.#values, [
|
|
28
|
+
...this.#owners,
|
|
29
|
+
...owners.map(ownerText),
|
|
30
|
+
]);
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* The answer kept under key, or fn's, which is kept. A call of a key
|
|
34
|
+
* another call is running waits for it and gets its answer; a throw of fn
|
|
35
|
+
* keeps nothing and is thrown, so the next call runs fn again. A
|
|
36
|
+
* connection lost after fn returned and before its answer was kept is
|
|
37
|
+
* OutcomeUnknownError.
|
|
38
|
+
*
|
|
39
|
+
* const receipt = await charges.run(requestId, () => pay.charge(order, requestId))
|
|
40
|
+
*/
|
|
41
|
+
async run(key, fn) {
|
|
42
|
+
const { stream, kept } = await this.#claim(key);
|
|
43
|
+
if (stream === undefined) {
|
|
44
|
+
return await this.#values.decode(kept ?? null);
|
|
45
|
+
}
|
|
46
|
+
let answer;
|
|
47
|
+
let body;
|
|
48
|
+
try {
|
|
49
|
+
answer = await fn();
|
|
50
|
+
body = KvEntry.encode({ found: true, value: await this.#values.encode(answer) });
|
|
51
|
+
}
|
|
52
|
+
catch (err) {
|
|
53
|
+
await end(stream, KvEntry.encode({})).catch(() => { });
|
|
54
|
+
throw err;
|
|
55
|
+
}
|
|
56
|
+
await end(stream, body);
|
|
57
|
+
return answer;
|
|
58
|
+
}
|
|
59
|
+
/** The answer kept under key, undefined when none is. */
|
|
60
|
+
async get(key) {
|
|
61
|
+
const e = await this.#call('kv.get', key, 'read');
|
|
62
|
+
return e.found === true ? await this.#values.decode(e.value ?? null) : undefined;
|
|
63
|
+
}
|
|
64
|
+
/** Forgets the answer kept under key, so that the next run runs again. */
|
|
65
|
+
async delete(key) {
|
|
66
|
+
await this.#call('kv.delete', key, 'write');
|
|
67
|
+
}
|
|
68
|
+
// asks for key's run: the answer kept under it, or the stream the server
|
|
69
|
+
// handed the run on, which a lost connection asks for again
|
|
70
|
+
async #claim(key) {
|
|
71
|
+
return this.#link.run('read', async (connection) => {
|
|
72
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
73
|
+
const ask = KvCall.encode({ handle, owners: this.#ownersField(), key });
|
|
74
|
+
const stream = await connection.session.open(methods['kv.run'], ask, false);
|
|
75
|
+
const unwatch = watch(currentSignal(), stream);
|
|
76
|
+
try {
|
|
77
|
+
const first = await stream.next();
|
|
78
|
+
if (first.end) {
|
|
79
|
+
return { kept: KvEntry.decode(first.body).value };
|
|
80
|
+
}
|
|
81
|
+
return { stream };
|
|
82
|
+
}
|
|
83
|
+
catch (err) {
|
|
84
|
+
stream.cancel();
|
|
85
|
+
throw err;
|
|
86
|
+
}
|
|
87
|
+
finally {
|
|
88
|
+
unwatch();
|
|
89
|
+
}
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
async #call(method, key, idempotence) {
|
|
93
|
+
return this.#link.run(idempotence, async (connection) => {
|
|
94
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
95
|
+
const body = KvCall.encode({ handle, owners: this.#ownersField(), key });
|
|
96
|
+
return KvEntry.decode(await connection.session.call(methods[method], body));
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
#ownersField() {
|
|
100
|
+
return this.#owners.length > 0 ? this.#owners : undefined;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
// sends what a run keeps as the stream's last DATA, and waits for the
|
|
104
|
+
// server's, which comes once it is kept
|
|
105
|
+
async function end(stream, body) {
|
|
106
|
+
try {
|
|
107
|
+
await stream.send(body, true);
|
|
108
|
+
await stream.next();
|
|
109
|
+
}
|
|
110
|
+
catch (err) {
|
|
111
|
+
if (err instanceof LostError) {
|
|
112
|
+
throw new OutcomeUnknownError(`the connection was lost before the answer was kept; the next run may run again: ${err.message}`);
|
|
113
|
+
}
|
|
114
|
+
throw err;
|
|
115
|
+
}
|
|
116
|
+
}
|
package/dist/quota.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { Link } from './connection.ts';
|
|
2
|
+
import { type Rate } from './limiter.ts';
|
|
3
|
+
import type { Key } from './wire/codec.ts';
|
|
4
|
+
/** One window of a key: what it used of its limit, and when it resets. */
|
|
5
|
+
export interface WindowUsage {
|
|
6
|
+
used: number;
|
|
7
|
+
limit: number;
|
|
8
|
+
left: number;
|
|
9
|
+
/** when the window ends and the next use starts another; undefined before it starts */
|
|
10
|
+
resetAt: Date | undefined;
|
|
11
|
+
}
|
|
12
|
+
/** What a quota answers a key: what a limiter answers, and each window by its name. */
|
|
13
|
+
export interface QuotaUsage<W extends string = string> {
|
|
14
|
+
ok: boolean;
|
|
15
|
+
/** how many more uses would pass now */
|
|
16
|
+
left: number;
|
|
17
|
+
/** milliseconds until a refused use would pass; 0 when ok */
|
|
18
|
+
retryAfter: number;
|
|
19
|
+
windows: Record<W, WindowUsage>;
|
|
20
|
+
}
|
|
21
|
+
/** A quota: open it with `store.kv.quota(name, { session: '100/5h', weekly: '300/7d' })`. */
|
|
22
|
+
export declare class Quota<W extends string = string> {
|
|
23
|
+
#private;
|
|
24
|
+
readonly name: string;
|
|
25
|
+
/** Quotas come from `store.kv.quota` and their `of`. */
|
|
26
|
+
constructor(link: Link, name: string, open: Uint8Array, owners: (string | Uint8Array)[]);
|
|
27
|
+
/** The quota of a branch, each key apart from the same key elsewhere. */
|
|
28
|
+
of(...owners: Key[]): Quota<W>;
|
|
29
|
+
/**
|
|
30
|
+
* Uses n of key's every window, one unless given, or none when one has no
|
|
31
|
+
* room for them; more than a window's limit is InvalidError.
|
|
32
|
+
*
|
|
33
|
+
* const { ok, retryAfter, windows } = await ai.allow(user.id)
|
|
34
|
+
*/
|
|
35
|
+
allow(key: Key, n?: number): Promise<QuotaUsage<W>>;
|
|
36
|
+
/** Key's windows without using them: ok says whether one more use would pass now. */
|
|
37
|
+
get(key: Key): Promise<QuotaUsage<W>>;
|
|
38
|
+
/** Gives n uses back, one unless given, to each of key's windows that has not reset since. */
|
|
39
|
+
refund(key: Key, n?: number): Promise<void>;
|
|
40
|
+
/** Forgets key's windows, so that its next use starts each anew. */
|
|
41
|
+
delete(key: Key): Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
/** A quota's open: its name and windows, checked before anything leaves. */
|
|
44
|
+
export declare function quotaOpen(name: string, windows: Record<string, Rate>): Uint8Array;
|
package/dist/quota.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
// A quota of uses by key, as Go's kv.Quota keeps one: several windows, each
|
|
2
|
+
// starting at a key's first use after the last ended, checked and counted
|
|
3
|
+
// together in one durable write, or not counted at all.
|
|
4
|
+
import { InvalidError } from './errors.js';
|
|
5
|
+
import { checkName, handleOn, ownerText } from './handles.js';
|
|
6
|
+
import { rateOf } from './limiter.js';
|
|
7
|
+
import { dateOf } from './time.js';
|
|
8
|
+
import { KvAllowance, KvBucket, KvCall, methods } from './wire/messages.js';
|
|
9
|
+
/** A quota: open it with `store.kv.quota(name, { session: '100/5h', weekly: '300/7d' })`. */
|
|
10
|
+
export class Quota {
|
|
11
|
+
name;
|
|
12
|
+
#link;
|
|
13
|
+
#open;
|
|
14
|
+
#owners;
|
|
15
|
+
/** Quotas come from `store.kv.quota` and their `of`. */
|
|
16
|
+
constructor(link, name, open, owners) {
|
|
17
|
+
this.#link = link;
|
|
18
|
+
this.name = name;
|
|
19
|
+
this.#open = open;
|
|
20
|
+
this.#owners = owners;
|
|
21
|
+
}
|
|
22
|
+
/** The quota of a branch, each key apart from the same key elsewhere. */
|
|
23
|
+
of(...owners) {
|
|
24
|
+
return new Quota(this.#link, this.name, this.#open, [...this.#owners, ...owners.map(ownerText)]);
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Uses n of key's every window, one unless given, or none when one has no
|
|
28
|
+
* room for them; more than a window's limit is InvalidError.
|
|
29
|
+
*
|
|
30
|
+
* const { ok, retryAfter, windows } = await ai.allow(user.id)
|
|
31
|
+
*/
|
|
32
|
+
async allow(key, n = 1) {
|
|
33
|
+
return usageOf(await this.#call('kv.allow', key, n, 'write'));
|
|
34
|
+
}
|
|
35
|
+
/** Key's windows without using them: ok says whether one more use would pass now. */
|
|
36
|
+
async get(key) {
|
|
37
|
+
return usageOf(await this.#call('kv.usage', key, 1, 'read'));
|
|
38
|
+
}
|
|
39
|
+
/** Gives n uses back, one unless given, to each of key's windows that has not reset since. */
|
|
40
|
+
async refund(key, n = 1) {
|
|
41
|
+
await this.#call('kv.refund', key, n, 'write');
|
|
42
|
+
}
|
|
43
|
+
/** Forgets key's windows, so that its next use starts each anew. */
|
|
44
|
+
async delete(key) {
|
|
45
|
+
await this.#call('kv.delete', key, 1, 'write');
|
|
46
|
+
}
|
|
47
|
+
async #call(method, key, n, idempotence) {
|
|
48
|
+
return this.#link.run(idempotence, async (connection) => {
|
|
49
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
50
|
+
const body = KvCall.encode({
|
|
51
|
+
handle,
|
|
52
|
+
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
53
|
+
key,
|
|
54
|
+
n: n === 1 ? undefined : n,
|
|
55
|
+
});
|
|
56
|
+
return await connection.session.call(methods[method], body);
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
function usageOf(body) {
|
|
61
|
+
const answer = KvAllowance.decode(body);
|
|
62
|
+
const windows = {};
|
|
63
|
+
for (const w of answer.windows ?? []) {
|
|
64
|
+
windows[(w.name ?? '')] = {
|
|
65
|
+
used: w.used ?? 0,
|
|
66
|
+
limit: w.limit ?? 0,
|
|
67
|
+
left: w.left ?? 0,
|
|
68
|
+
resetAt: dateOf(w.resetAt),
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
return {
|
|
72
|
+
ok: answer.ok === true,
|
|
73
|
+
left: answer.left ?? 0,
|
|
74
|
+
retryAfter: answer.retryAfter ?? 0,
|
|
75
|
+
windows,
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
/** A quota's open: its name and windows, checked before anything leaves. */
|
|
79
|
+
export function quotaOpen(name, windows) {
|
|
80
|
+
checkName(name, 'quota');
|
|
81
|
+
const spans = Object.entries(windows);
|
|
82
|
+
if (spans.length < 1 || spans.length > 8) {
|
|
83
|
+
throw new InvalidError(`quota ${name}: ${spans.length} windows, not one to eight`);
|
|
84
|
+
}
|
|
85
|
+
return KvBucket.encode({
|
|
86
|
+
name,
|
|
87
|
+
windows: spans.map(([window, rate]) => {
|
|
88
|
+
if (!/^[a-z][a-z0-9_]{0,31}$/.test(window)) {
|
|
89
|
+
throw new InvalidError(`quota ${name}: a window name is [a-z][a-z0-9_]{0,31}, not ${window}`);
|
|
90
|
+
}
|
|
91
|
+
const { count, per } = rateOf(rate);
|
|
92
|
+
if (count < 1 || per < 1) {
|
|
93
|
+
throw new InvalidError(`quota ${name}: a window of ${rate}`);
|
|
94
|
+
}
|
|
95
|
+
return { name: window, limit: count, per };
|
|
96
|
+
}),
|
|
97
|
+
});
|
|
98
|
+
}
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
import { type Link } from './connection.ts';
|
|
2
|
+
import type { Page } from './handles.ts';
|
|
3
|
+
import { type Logger, type LoggerOptions } from './logger.ts';
|
|
4
|
+
import { type Duration } from './time.ts';
|
|
5
|
+
/** slog's levels: -4 debug, 0 info, 4 warn, 8 error, or any other it may name. */
|
|
6
|
+
export type Level = 'debug' | 'info' | 'warn' | 'error' | number;
|
|
7
|
+
/**
|
|
8
|
+
* Fields: keys and values, each value written as JSON. An object's keys keep
|
|
9
|
+
* their order; an array of pairs may repeat a key.
|
|
10
|
+
*/
|
|
11
|
+
export type Fields = Record<string, unknown> | readonly (readonly [string, unknown])[];
|
|
12
|
+
/** A record to append: when, where, what, and its fields. */
|
|
13
|
+
export interface RecordInput {
|
|
14
|
+
/** its time: a Date, or unix nanoseconds as a bigint; now when absent */
|
|
15
|
+
at?: Date | bigint;
|
|
16
|
+
/** the namespace the application names: 'web', 'billing' */
|
|
17
|
+
stream: string;
|
|
18
|
+
/** the event: 'log' for a log line */
|
|
19
|
+
name: string;
|
|
20
|
+
level?: Level;
|
|
21
|
+
/** absent is none, which an empty body is not */
|
|
22
|
+
body?: string | Uint8Array;
|
|
23
|
+
/** sixteen bytes, or their 32 hex digits */
|
|
24
|
+
traceId?: Uint8Array | string | undefined;
|
|
25
|
+
/** eight bytes, or their 16 hex digits */
|
|
26
|
+
spanId?: Uint8Array | string | undefined;
|
|
27
|
+
/** who produced it */
|
|
28
|
+
context?: Fields;
|
|
29
|
+
/** what happened */
|
|
30
|
+
attrs?: Fields;
|
|
31
|
+
}
|
|
32
|
+
/** A record as it was kept: a field's value is the JSON it was written as, spelled as it was given. */
|
|
33
|
+
export interface LogRecord {
|
|
34
|
+
/** unix nanoseconds */
|
|
35
|
+
at: bigint;
|
|
36
|
+
stream: string;
|
|
37
|
+
name: string;
|
|
38
|
+
level: number | undefined;
|
|
39
|
+
body: string | Uint8Array | undefined;
|
|
40
|
+
traceId: Uint8Array | undefined;
|
|
41
|
+
spanId: Uint8Array | undefined;
|
|
42
|
+
context: [key: string, json: string | Uint8Array][];
|
|
43
|
+
attrs: [key: string, json: string | Uint8Array][];
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* A record's fields, its attrs or its context, as an object, each value read
|
|
47
|
+
* as JSON.parse reads the JSON it was kept as; the last of a repeated key is
|
|
48
|
+
* kept. The pairs keep what JSON.parse may not: 1.2300 as written, an integer
|
|
49
|
+
* past 2^53 whole.
|
|
50
|
+
*
|
|
51
|
+
* ```ts
|
|
52
|
+
* for await (const record of store.records.all({ since: '1h', streams: ['readers'] })) {
|
|
53
|
+
* const { page, from } = fields(record.attrs)
|
|
54
|
+
* }
|
|
55
|
+
* ```
|
|
56
|
+
*/
|
|
57
|
+
export declare function fields(pairs: LogRecord['attrs']): Record<string, unknown>;
|
|
58
|
+
/**
|
|
59
|
+
* The records in a range that meet every condition given.
|
|
60
|
+
*
|
|
61
|
+
* ```ts
|
|
62
|
+
* { since: '1h', minLevel: 'warn' } // the last hour's warnings
|
|
63
|
+
* { since: '1h', search: 'connection reset' } // whose text holds it, case ignored
|
|
64
|
+
* { from: start, to: end, streams: ['api'] }
|
|
65
|
+
* ```
|
|
66
|
+
*/
|
|
67
|
+
export interface RecordsQuery {
|
|
68
|
+
/** the span before now the range covers: '1h', '15m', or milliseconds; or from and to */
|
|
69
|
+
since?: Duration;
|
|
70
|
+
/** the range's start, included; open when absent */
|
|
71
|
+
from?: Date | bigint;
|
|
72
|
+
/** the range's end, excluded; open when absent */
|
|
73
|
+
to?: Date | bigint;
|
|
74
|
+
/** none or empty is every stream */
|
|
75
|
+
streams?: string[];
|
|
76
|
+
names?: string[];
|
|
77
|
+
/** a record without a level does not match */
|
|
78
|
+
minLevel?: Level;
|
|
79
|
+
traceId?: Uint8Array | string;
|
|
80
|
+
/** each a record must hold, by key and exact JSON spelling */
|
|
81
|
+
attrs?: Fields;
|
|
82
|
+
context?: Fields;
|
|
83
|
+
/**
|
|
84
|
+
* text a record's body or name holds, its case ignored: every record the
|
|
85
|
+
* rest of the query leaves is read for it, so a search over much text ends
|
|
86
|
+
* pages early at the budget, and next goes on
|
|
87
|
+
*/
|
|
88
|
+
search?: string;
|
|
89
|
+
/** newest first; oldest first when absent */
|
|
90
|
+
newest?: boolean;
|
|
91
|
+
/** the records a page holds: 1000, and 10000 at most */
|
|
92
|
+
limit?: number;
|
|
93
|
+
/** what one read may open, fetch and decode; each narrows the server's */
|
|
94
|
+
budget?: {
|
|
95
|
+
blocks?: number;
|
|
96
|
+
bytes?: number;
|
|
97
|
+
records?: number;
|
|
98
|
+
};
|
|
99
|
+
/** a page's next, which this page continues from; the rest of the query as it was */
|
|
100
|
+
after?: string | undefined;
|
|
101
|
+
}
|
|
102
|
+
/** Where a follower stands in the sealed segments: kept by the caller between follows. */
|
|
103
|
+
export interface Cursor {
|
|
104
|
+
segment: number;
|
|
105
|
+
row: number;
|
|
106
|
+
}
|
|
107
|
+
/** A row that no longer reads, which a drop removes. */
|
|
108
|
+
export interface Damage {
|
|
109
|
+
stream: string;
|
|
110
|
+
/** a sealed segment, dropped whole; or a head row */
|
|
111
|
+
segment: number | undefined;
|
|
112
|
+
headRow: number | undefined;
|
|
113
|
+
/** the times it held, unix nanoseconds */
|
|
114
|
+
from: bigint;
|
|
115
|
+
to: bigint;
|
|
116
|
+
/** the invariant its bytes broke */
|
|
117
|
+
reason: string;
|
|
118
|
+
}
|
|
119
|
+
export declare class Records {
|
|
120
|
+
#private;
|
|
121
|
+
constructor(link: Link);
|
|
122
|
+
/**
|
|
123
|
+
* A logger of a stream: its calls return at once, and its lines reach the
|
|
124
|
+
* server every second, as Go's slog handler's and Python's logging.Handler's do.
|
|
125
|
+
*/
|
|
126
|
+
logger(stream: string, options?: LoggerOptions): Logger;
|
|
127
|
+
/** Hands over what every logger holds, as the store does when it closes. */
|
|
128
|
+
stop(): Promise<void>;
|
|
129
|
+
/**
|
|
130
|
+
* Appends records in one transaction, all or none; a refused one names
|
|
131
|
+
* itself as `call`, with its stream and name. A read sees them at once. A
|
|
132
|
+
* record of no trace of its own takes the one withTrace runs the call in.
|
|
133
|
+
*/
|
|
134
|
+
append(records: RecordInput | readonly RecordInput[]): Promise<void>;
|
|
135
|
+
/**
|
|
136
|
+
* One page of the records a query matches, from one snapshot, in event-time
|
|
137
|
+
* order; next, while a limit or a budget ended the page early, is passed back
|
|
138
|
+
* as `after` with the same query. A page never splits a timestamp.
|
|
139
|
+
*/
|
|
140
|
+
scan(query?: RecordsQuery): Promise<Page<LogRecord, string>>;
|
|
141
|
+
/** Every record a query matches, a page at a time. */
|
|
142
|
+
all(query?: Omit<RecordsQuery, 'after'>): AsyncGenerator<LogRecord>;
|
|
143
|
+
/**
|
|
144
|
+
* The sealed records after a cursor, in the order they were sealed; the
|
|
145
|
+
* cursor to follow from next, and the segments retention removed before
|
|
146
|
+
* the cursor reached them. A record reaches a follower once it is sealed.
|
|
147
|
+
*/
|
|
148
|
+
follow(cursor?: Cursor, limit?: number): Promise<{
|
|
149
|
+
records: LogRecord[];
|
|
150
|
+
cursor: Cursor;
|
|
151
|
+
expired: number;
|
|
152
|
+
}>;
|
|
153
|
+
/**
|
|
154
|
+
* A writer of another program's output, pino's lines or a child's stdout,
|
|
155
|
+
* that never waits: each line becomes a record of the stream as the server's
|
|
156
|
+
* Lines makes it, a stack trace's lines joined and a JSON or logfmt line's
|
|
157
|
+
* fields kept. What does not fit its buffer is dropped and counted.
|
|
158
|
+
*/
|
|
159
|
+
lines(stream: string, options?: {
|
|
160
|
+
buffer?: number;
|
|
161
|
+
}): LinesWriter;
|
|
162
|
+
/** The rows the server's records have met that no longer read. */
|
|
163
|
+
damaged(): Promise<Damage[]>;
|
|
164
|
+
/** Removes a damaged row, a repair an admin connection alone may make. */
|
|
165
|
+
drop(damage: Damage): Promise<void>;
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* An upload of lines that stays open while it is written: write never waits,
|
|
169
|
+
* holding what the stream's credit does not let go yet up to its buffer and
|
|
170
|
+
* dropping past it. A connection lost drops what it held and the next write
|
|
171
|
+
* uploads on the next connection.
|
|
172
|
+
*/
|
|
173
|
+
export declare class LinesWriter {
|
|
174
|
+
#private;
|
|
175
|
+
/** bytes dropped since the writer began: a full buffer, or a lost connection */
|
|
176
|
+
dropped: number;
|
|
177
|
+
constructor(link: Link, stream: string, most: number);
|
|
178
|
+
/** Takes a piece of output, cut anywhere. It returns at once. */
|
|
179
|
+
write(chunk: string | Uint8Array): boolean;
|
|
180
|
+
/** Hands over what the writer holds, a line cut short included, and ends the upload. */
|
|
181
|
+
end(): Promise<void>;
|
|
182
|
+
}
|