@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/config.js
ADDED
|
@@ -0,0 +1,417 @@
|
|
|
1
|
+
// An application's settings, as Go's kv.Config makes them: the defaults, then
|
|
2
|
+
// a file's values, then the environment, then what update kept, which the
|
|
3
|
+
// server keeps field by field in kv.db and sends to every store watching the
|
|
4
|
+
// config. `value` is read from memory and is new after each change.
|
|
5
|
+
import { ClosedError, InvalidError } from './errors.js';
|
|
6
|
+
import { checkName, handleOn } from './handles.js';
|
|
7
|
+
import { check } from './schema.js';
|
|
8
|
+
import { KvBucket, KvCall, KvConfigure, KvKept, methods } from './wire/messages.js';
|
|
9
|
+
/**
|
|
10
|
+
* A field's variable: the prefix and its path in upper snake case, as Go's and
|
|
11
|
+
* Python's configs name it.
|
|
12
|
+
*
|
|
13
|
+
* 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
|
|
14
|
+
*/
|
|
15
|
+
export function envName(prefix, path) {
|
|
16
|
+
const chars = [...path];
|
|
17
|
+
let name = '';
|
|
18
|
+
chars.forEach((c, i) => {
|
|
19
|
+
if (c === '.' || c === '-') {
|
|
20
|
+
name += '_';
|
|
21
|
+
return;
|
|
22
|
+
}
|
|
23
|
+
const before = chars[i - 1];
|
|
24
|
+
const after = chars[i + 1];
|
|
25
|
+
if (i > 0 && isUpper(c) && before !== undefined) {
|
|
26
|
+
const lowerAfter = after !== undefined && isLower(after);
|
|
27
|
+
if (isLower(before) || isDigit(before) || (isUpper(before) && lowerAfter)) {
|
|
28
|
+
name += '_';
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
name += c.toUpperCase();
|
|
32
|
+
});
|
|
33
|
+
return prefix === '' ? name : `${prefix}_${name}`;
|
|
34
|
+
}
|
|
35
|
+
const isUpper = (c) => c !== c.toLowerCase() && c === c.toUpperCase();
|
|
36
|
+
const isLower = (c) => c !== c.toUpperCase() && c === c.toLowerCase();
|
|
37
|
+
const isDigit = (c) => c >= '0' && c <= '9';
|
|
38
|
+
/** A config: open it with `store.kv.config(name, defaults, options)`. */
|
|
39
|
+
export class Config {
|
|
40
|
+
name;
|
|
41
|
+
#link;
|
|
42
|
+
#open;
|
|
43
|
+
#leaves;
|
|
44
|
+
#base;
|
|
45
|
+
#from;
|
|
46
|
+
#secret;
|
|
47
|
+
#schema;
|
|
48
|
+
#listeners = new Set();
|
|
49
|
+
#kept = new Map();
|
|
50
|
+
#ignored = new Map();
|
|
51
|
+
#value;
|
|
52
|
+
#stream;
|
|
53
|
+
#closed = false;
|
|
54
|
+
/** Configs come from `store.kv.config`, which waits for the first state. */
|
|
55
|
+
constructor(link, name, defaults, options) {
|
|
56
|
+
checkName(name, 'config');
|
|
57
|
+
this.#link = link;
|
|
58
|
+
this.name = name;
|
|
59
|
+
this.#open = KvBucket.encode({ name, config: true });
|
|
60
|
+
this.#leaves = new Map(leavesOf(defaults));
|
|
61
|
+
this.#schema = options.schema;
|
|
62
|
+
this.#secret = new Set(options.secret ?? []);
|
|
63
|
+
for (const path of this.#secret) {
|
|
64
|
+
this.#leaf(path);
|
|
65
|
+
}
|
|
66
|
+
this.#from = new Map([...this.#leaves.keys()].map(path => [path, 'default']));
|
|
67
|
+
this.#base = layered(this.#leaves, defaults, options, this.#from);
|
|
68
|
+
this.#value = deepFreeze(structuredClone(this.#base));
|
|
69
|
+
}
|
|
70
|
+
/** The config now, frozen: update changes it. */
|
|
71
|
+
get value() {
|
|
72
|
+
return this.#value;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Changes the fields change names, at any depth; each one that changed is
|
|
76
|
+
* checked, kept, and seen by every store watching the config. A change the
|
|
77
|
+
* schema refuses, or one of a secret, is InvalidError and keeps nothing.
|
|
78
|
+
*/
|
|
79
|
+
async update(change) {
|
|
80
|
+
const next = merged(structuredClone(this.#value), change);
|
|
81
|
+
const set = [];
|
|
82
|
+
for (const path of this.#leaves.keys()) {
|
|
83
|
+
const now = JSON.stringify(pathIn(next, path));
|
|
84
|
+
if (now === JSON.stringify(pathIn(this.#value, path))) {
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
if (this.#secret.has(path)) {
|
|
88
|
+
throw new InvalidError(`config ${this.name}: ${path} is a secret, set by the defaults, the file or the environment alone`);
|
|
89
|
+
}
|
|
90
|
+
set.push(path, now);
|
|
91
|
+
}
|
|
92
|
+
if (set.length === 0) {
|
|
93
|
+
return;
|
|
94
|
+
}
|
|
95
|
+
await this.#checked(next);
|
|
96
|
+
await this.#send(set, []);
|
|
97
|
+
}
|
|
98
|
+
/** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
|
|
99
|
+
async reset(...paths) {
|
|
100
|
+
for (const path of paths) {
|
|
101
|
+
if (![...this.#leaves.keys()].some(leaf => under(leaf, path))) {
|
|
102
|
+
throw new InvalidError(`config ${this.name} has no field ${path}`);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
const reset = [...this.#kept.keys()].filter(kept => paths.length === 0 || paths.some(path => under(kept, path)));
|
|
106
|
+
if (reset.length > 0) {
|
|
107
|
+
await this.#send([], reset);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/** Calls fn with the config now and after each change, whoever made it; the function it returns stops that. */
|
|
111
|
+
watch(fn) {
|
|
112
|
+
this.#listeners.add(fn);
|
|
113
|
+
fn(this.#value);
|
|
114
|
+
return () => this.#listeners.delete(fn);
|
|
115
|
+
}
|
|
116
|
+
/** Where each field's value came from, and why a kept value is left out. */
|
|
117
|
+
sources() {
|
|
118
|
+
return [...this.#leaves.keys()].map(path => {
|
|
119
|
+
const kept = this.#kept.has(path) && !this.#ignored.has(path);
|
|
120
|
+
const source = {
|
|
121
|
+
path,
|
|
122
|
+
value: this.#secret.has(path)
|
|
123
|
+
? '***'
|
|
124
|
+
: (JSON.stringify(pathIn(this.#value, path)) ?? 'null'),
|
|
125
|
+
from: kept ? 'kept' : (this.#from.get(path) ?? 'default'),
|
|
126
|
+
};
|
|
127
|
+
const ignored = this.#ignored.get(path);
|
|
128
|
+
return ignored === undefined ? source : { ...source, ignored };
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
/** Follows the config's changes until the store closes; resolves once the first state is read. */
|
|
132
|
+
start() {
|
|
133
|
+
return new Promise((resolve, reject) => {
|
|
134
|
+
void this.#follow(resolve, reject);
|
|
135
|
+
});
|
|
136
|
+
}
|
|
137
|
+
/** Stops following the config, as the store does when it closes. */
|
|
138
|
+
stop() {
|
|
139
|
+
this.#closed = true;
|
|
140
|
+
this.#stream?.cancel();
|
|
141
|
+
}
|
|
142
|
+
async #follow(ready, failed) {
|
|
143
|
+
let first = true;
|
|
144
|
+
for (let pause = 100; !this.#closed; pause = Math.min(pause * 2, 5000)) {
|
|
145
|
+
try {
|
|
146
|
+
await this.#link.run('read', async (connection) => {
|
|
147
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
148
|
+
const stream = await connection.session.open(methods['kv.watch'], KvCall.encode({ handle }), true);
|
|
149
|
+
this.#stream = stream;
|
|
150
|
+
await stream.next();
|
|
151
|
+
for (;;) {
|
|
152
|
+
const event = await stream.next();
|
|
153
|
+
stream.consumed(event.body.length);
|
|
154
|
+
if (event.end) {
|
|
155
|
+
return;
|
|
156
|
+
}
|
|
157
|
+
await this.#apply(KvKept.decode(event.body).fields ?? []);
|
|
158
|
+
pause = 100;
|
|
159
|
+
if (first) {
|
|
160
|
+
first = false;
|
|
161
|
+
ready();
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
catch (err) {
|
|
167
|
+
if (first) {
|
|
168
|
+
failed(err);
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
if (this.#closed || err instanceof ClosedError) {
|
|
172
|
+
return;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
await new Promise(resolve => setTimeout(resolve, pause));
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
/** Keeps set, path and JSON each, and forgets reset, then makes the config with them. */
|
|
179
|
+
async #send(set, reset) {
|
|
180
|
+
await this.#link.run('write', async (connection) => {
|
|
181
|
+
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
182
|
+
const body = KvConfigure.encode({
|
|
183
|
+
handle,
|
|
184
|
+
set: set.length > 0 ? set : undefined,
|
|
185
|
+
reset: reset.length > 0 ? reset : undefined,
|
|
186
|
+
});
|
|
187
|
+
await connection.session.call(methods['kv.configure'], body);
|
|
188
|
+
});
|
|
189
|
+
const kept = new Map(this.#kept);
|
|
190
|
+
for (let i = 0; i + 1 < set.length; i += 2) {
|
|
191
|
+
kept.set(set[i], set[i + 1]);
|
|
192
|
+
}
|
|
193
|
+
for (const path of reset) {
|
|
194
|
+
kept.delete(path);
|
|
195
|
+
}
|
|
196
|
+
await this.#build(kept);
|
|
197
|
+
}
|
|
198
|
+
/** Takes up the kept fields a watch sent. */
|
|
199
|
+
async #apply(fields) {
|
|
200
|
+
const kept = new Map();
|
|
201
|
+
for (let i = 0; i + 1 < fields.length; i += 2) {
|
|
202
|
+
kept.set(fields[i], fields[i + 1]);
|
|
203
|
+
}
|
|
204
|
+
await this.#build(kept);
|
|
205
|
+
}
|
|
206
|
+
/** Makes the config from its base and what is kept, leaving out what no longer fits, and tells the watchers. */
|
|
207
|
+
async #build(kept) {
|
|
208
|
+
const ignored = new Map();
|
|
209
|
+
let next = withKept(this.#base, this.#leaves, kept, ignored);
|
|
210
|
+
let issues = await this.#issues(next);
|
|
211
|
+
if (issues !== undefined && kept.size > ignored.size) {
|
|
212
|
+
for (const path of kept.keys()) {
|
|
213
|
+
ignored.set(path, ignored.get(path) ?? `the config fails with it: ${issues}`);
|
|
214
|
+
}
|
|
215
|
+
next = structuredClone(this.#base);
|
|
216
|
+
issues = await this.#issues(next);
|
|
217
|
+
}
|
|
218
|
+
if (issues !== undefined) {
|
|
219
|
+
throw new InvalidError(`config ${this.name}: ${issues}`);
|
|
220
|
+
}
|
|
221
|
+
const changed = JSON.stringify(next) !== JSON.stringify(this.#value);
|
|
222
|
+
this.#kept = kept;
|
|
223
|
+
this.#ignored = ignored;
|
|
224
|
+
this.#value = deepFreeze(next);
|
|
225
|
+
if (changed) {
|
|
226
|
+
for (const listener of this.#listeners) {
|
|
227
|
+
listener(this.#value);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
async #checked(value) {
|
|
232
|
+
const issues = await this.#issues(value);
|
|
233
|
+
if (issues !== undefined) {
|
|
234
|
+
throw new InvalidError(`config ${this.name}: ${issues}`);
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
async #issues(value) {
|
|
238
|
+
if (this.#schema === undefined) {
|
|
239
|
+
return undefined;
|
|
240
|
+
}
|
|
241
|
+
const checked = await check(this.#schema, value);
|
|
242
|
+
return 'issues' in checked ? checked.issues : undefined;
|
|
243
|
+
}
|
|
244
|
+
#leaf(path) {
|
|
245
|
+
if (!this.#leaves.has(path)) {
|
|
246
|
+
throw new InvalidError(`config ${this.name} has no field ${path}`);
|
|
247
|
+
}
|
|
248
|
+
return this.#leaves.get(path);
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
/** The defaults, the file and the environment, each over the one before. */
|
|
252
|
+
function layered(leaves, defaults, options, from) {
|
|
253
|
+
const base = structuredClone(defaults);
|
|
254
|
+
if (options.file !== undefined) {
|
|
255
|
+
for (const [path, value] of leavesOf(options.file)) {
|
|
256
|
+
const wanted = leaves.get(path);
|
|
257
|
+
if (!leaves.has(path)) {
|
|
258
|
+
continue;
|
|
259
|
+
}
|
|
260
|
+
if (!fits(value, wanted)) {
|
|
261
|
+
throw new InvalidError(`the file's ${path}: ${JSON.stringify(value)} is no ${kindOf(wanted)}`);
|
|
262
|
+
}
|
|
263
|
+
setPath(base, path, value);
|
|
264
|
+
from.set(path, 'file');
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
if (options.env === false) {
|
|
268
|
+
return base;
|
|
269
|
+
}
|
|
270
|
+
for (const [path, wanted] of leaves) {
|
|
271
|
+
const name = options.env?.[path] ?? envName(options.prefix ?? '', path);
|
|
272
|
+
const text = process.env[name];
|
|
273
|
+
if (text !== undefined) {
|
|
274
|
+
setPath(base, path, fromEnv(text, wanted, name));
|
|
275
|
+
from.set(path, `env ${name}`);
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
return base;
|
|
279
|
+
}
|
|
280
|
+
/** The base with each kept value that fits its field over it. */
|
|
281
|
+
function withKept(base, leaves, kept, ignored) {
|
|
282
|
+
const next = structuredClone(base);
|
|
283
|
+
for (const [path, spelled] of kept) {
|
|
284
|
+
if (!leaves.has(path)) {
|
|
285
|
+
ignored.set(path, 'the config has no such field');
|
|
286
|
+
continue;
|
|
287
|
+
}
|
|
288
|
+
let value;
|
|
289
|
+
try {
|
|
290
|
+
value = JSON.parse(spelled);
|
|
291
|
+
}
|
|
292
|
+
catch {
|
|
293
|
+
ignored.set(path, `${spelled} is no JSON`);
|
|
294
|
+
continue;
|
|
295
|
+
}
|
|
296
|
+
if (!fits(value, leaves.get(path))) {
|
|
297
|
+
ignored.set(path, `${spelled} is no ${kindOf(leaves.get(path))}`);
|
|
298
|
+
continue;
|
|
299
|
+
}
|
|
300
|
+
setPath(next, path, value);
|
|
301
|
+
}
|
|
302
|
+
return next;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* A variable's text as a value of its default's kind: a number, true or
|
|
306
|
+
* false, a list split at its commas or given as JSON, and anything else as JSON.
|
|
307
|
+
*
|
|
308
|
+
* 8080 ← '3000' → 3000, ['x'] ← 'a.com, b.com' → ['a.com', 'b.com']
|
|
309
|
+
*/
|
|
310
|
+
function fromEnv(text, wanted, name) {
|
|
311
|
+
const trimmed = text.trim();
|
|
312
|
+
if (typeof wanted === 'string') {
|
|
313
|
+
return text;
|
|
314
|
+
}
|
|
315
|
+
if (typeof wanted === 'number') {
|
|
316
|
+
const n = Number(trimmed);
|
|
317
|
+
if (trimmed === '' || !Number.isFinite(n)) {
|
|
318
|
+
throw new InvalidError(`${name}: ${JSON.stringify(text)} is no number`);
|
|
319
|
+
}
|
|
320
|
+
return n;
|
|
321
|
+
}
|
|
322
|
+
if (typeof wanted === 'boolean') {
|
|
323
|
+
if (['1', 't', 'T', 'TRUE', 'true', 'True'].includes(trimmed)) {
|
|
324
|
+
return true;
|
|
325
|
+
}
|
|
326
|
+
if (['0', 'f', 'F', 'FALSE', 'false', 'False'].includes(trimmed)) {
|
|
327
|
+
return false;
|
|
328
|
+
}
|
|
329
|
+
throw new InvalidError(`${name}: ${JSON.stringify(text)} is not true or false`);
|
|
330
|
+
}
|
|
331
|
+
if (Array.isArray(wanted) && !trimmed.startsWith('[')) {
|
|
332
|
+
const item = wanted[0] ?? '';
|
|
333
|
+
return trimmed === '' ? [] : trimmed.split(',').map(part => fromEnv(part.trim(), item, name));
|
|
334
|
+
}
|
|
335
|
+
try {
|
|
336
|
+
const value = JSON.parse(trimmed);
|
|
337
|
+
if (fits(value, wanted)) {
|
|
338
|
+
return value;
|
|
339
|
+
}
|
|
340
|
+
}
|
|
341
|
+
catch {
|
|
342
|
+
// refused below, naming the variable
|
|
343
|
+
}
|
|
344
|
+
throw new InvalidError(`${name}: ${JSON.stringify(text)} is no ${kindOf(wanted)}`);
|
|
345
|
+
}
|
|
346
|
+
/** A value's fields to the last that is not a plain object, by their dotted paths. */
|
|
347
|
+
function leavesOf(value, parent = '') {
|
|
348
|
+
const leaves = [];
|
|
349
|
+
for (const [key, inner] of Object.entries(value)) {
|
|
350
|
+
const path = parent === '' ? key : `${parent}.${key}`;
|
|
351
|
+
if (plain(inner)) {
|
|
352
|
+
leaves.push(...leavesOf(inner, path));
|
|
353
|
+
}
|
|
354
|
+
else {
|
|
355
|
+
leaves.push([path, inner]);
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
return leaves;
|
|
359
|
+
}
|
|
360
|
+
function plain(value) {
|
|
361
|
+
return (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date));
|
|
362
|
+
}
|
|
363
|
+
/** A value fits a field when it is of its default's kind; a default of null takes anything. */
|
|
364
|
+
function fits(value, wanted) {
|
|
365
|
+
if (wanted === null || wanted === undefined) {
|
|
366
|
+
return true;
|
|
367
|
+
}
|
|
368
|
+
if (Array.isArray(wanted)) {
|
|
369
|
+
return Array.isArray(value);
|
|
370
|
+
}
|
|
371
|
+
return typeof value === typeof wanted && (typeof wanted !== 'object' || plain(value));
|
|
372
|
+
}
|
|
373
|
+
function kindOf(wanted) {
|
|
374
|
+
return Array.isArray(wanted) ? 'list' : typeof wanted;
|
|
375
|
+
}
|
|
376
|
+
function pathIn(tree, path) {
|
|
377
|
+
let at = tree;
|
|
378
|
+
for (const name of path.split('.')) {
|
|
379
|
+
if (!plain(at)) {
|
|
380
|
+
return undefined;
|
|
381
|
+
}
|
|
382
|
+
at = at[name];
|
|
383
|
+
}
|
|
384
|
+
return at;
|
|
385
|
+
}
|
|
386
|
+
function setPath(tree, path, value) {
|
|
387
|
+
const names = path.split('.');
|
|
388
|
+
let at = tree;
|
|
389
|
+
for (const name of names.slice(0, -1)) {
|
|
390
|
+
const inner = at[name];
|
|
391
|
+
if (!plain(inner)) {
|
|
392
|
+
at[name] = {};
|
|
393
|
+
}
|
|
394
|
+
at = at[name];
|
|
395
|
+
}
|
|
396
|
+
at[names[names.length - 1]] = value;
|
|
397
|
+
}
|
|
398
|
+
/** change merged into tree at every depth; a list is replaced whole. */
|
|
399
|
+
function merged(tree, change) {
|
|
400
|
+
for (const [key, value] of Object.entries(change)) {
|
|
401
|
+
const inner = tree[key];
|
|
402
|
+
tree[key] = plain(value) && plain(inner) ? merged(inner, value) : value;
|
|
403
|
+
}
|
|
404
|
+
return tree;
|
|
405
|
+
}
|
|
406
|
+
function under(path, given) {
|
|
407
|
+
return path === given || path.startsWith(`${given}.`);
|
|
408
|
+
}
|
|
409
|
+
function deepFreeze(value) {
|
|
410
|
+
if (typeof value === 'object' && value !== null) {
|
|
411
|
+
for (const inner of Object.values(value)) {
|
|
412
|
+
deepFreeze(inner);
|
|
413
|
+
}
|
|
414
|
+
Object.freeze(value);
|
|
415
|
+
}
|
|
416
|
+
return value;
|
|
417
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { PrivateChild, Runtime, TlsOptions, Transport } from './runtime.ts';
|
|
2
|
+
import { Session, type SessionOptions, type Stream } from './session.ts';
|
|
3
|
+
export declare class Connection {
|
|
4
|
+
#private;
|
|
5
|
+
readonly session: Session;
|
|
6
|
+
/** the handles this connection opened, by what they are: a bucket's name and options */
|
|
7
|
+
readonly handles: Map<string, Promise<number>>;
|
|
8
|
+
constructor(session: Session, transport: Transport, closing?: () => Promise<unknown>);
|
|
9
|
+
/** Connects, shakes hands, and gives up after the handshake's time. */
|
|
10
|
+
static dial(runtime: Runtime, endpoint: string, options: SessionOptions, tls?: TlsOptions): Promise<Connection>;
|
|
11
|
+
/**
|
|
12
|
+
* Shakes hands over a private child's stdin and stdout. Closing waits for
|
|
13
|
+
* the child's exit, since until then it holds the directory: its LOCK, and
|
|
14
|
+
* on Windows every file it opened, which a removal fails on.
|
|
15
|
+
*/
|
|
16
|
+
static overChild(child: PrivateChild, session: Session): Promise<Connection>;
|
|
17
|
+
/** Ends the connection; a private child is waited for until it has exited. */
|
|
18
|
+
close(): Promise<void>;
|
|
19
|
+
}
|
|
20
|
+
/** Where a link dials. */
|
|
21
|
+
export type Dialer = () => Promise<Connection>;
|
|
22
|
+
/**
|
|
23
|
+
* Finds the directory's sidecar through SERVE or starts one, as docs/wire.md
|
|
24
|
+
* "Finding a local server" says: a sidecar found proves itself before the
|
|
25
|
+
* first call, and one started exits with 3 when another holds the directory,
|
|
26
|
+
* whose SERVE the client then waits for. A sidecar of an older release than
|
|
27
|
+
* this SDK's is stopped and replaced with this SDK's binary; another server
|
|
28
|
+
* of an older release, a person's or a program's own, is told of once.
|
|
29
|
+
*/
|
|
30
|
+
export declare function sidecar(runtime: Runtime, dir: string, binary: () => string, idle?: number, older?: (server: string) => boolean): Dialer;
|
|
31
|
+
/**
|
|
32
|
+
* Whether a server's release is older than the SDK's own; a build that is no
|
|
33
|
+
* release, a development copy's or a Go pseudo-version, is neither.
|
|
34
|
+
*/
|
|
35
|
+
export declare function olderRelease(server: string, own: string): boolean;
|
|
36
|
+
/** What a program whose SDK replaced a sidecar of an older release is told. */
|
|
37
|
+
export declare function replacedSidecar(server: string, own: string, dir: string): string;
|
|
38
|
+
/** What a program whose SDK found a server of an older release that is no sidecar is told. */
|
|
39
|
+
export declare function olderServer(server: string, own: string, dir: string): string;
|
|
40
|
+
/** A private child: tinystore serve --stdio, living and dying with this process. */
|
|
41
|
+
export declare function privateChild(runtime: Runtime, dir: string, binary: () => string, clock?: Date): Dialer;
|
|
42
|
+
/** A remote server: tls:// checks its certificate before the token leaves; tcp:// does not. */
|
|
43
|
+
export declare function remote(runtime: Runtime, url: string, token: string, tls?: TlsOptions): Dialer;
|
|
44
|
+
/** What a call may do when its connection is lost: go again, or say its outcome is unknown. */
|
|
45
|
+
export type Idempotence = 'read' | 'write';
|
|
46
|
+
/**
|
|
47
|
+
* Gives calls a connection, dialling again once the last one ended, and runs
|
|
48
|
+
* a call so that a lost connection costs it what it must: a call whose
|
|
49
|
+
* REQUEST had not left goes again, so does a read that had, and a write that
|
|
50
|
+
* had is OutcomeUnknownError.
|
|
51
|
+
*/
|
|
52
|
+
export declare class Link {
|
|
53
|
+
#private;
|
|
54
|
+
constructor(dial: Dialer);
|
|
55
|
+
/** The connection a call goes on. */
|
|
56
|
+
connection(): Promise<Connection>;
|
|
57
|
+
/**
|
|
58
|
+
* Runs a call on the link's connection. build makes its REQUEST's body for
|
|
59
|
+
* that connection, whose handles it may open; run sends it.
|
|
60
|
+
*/
|
|
61
|
+
run<T>(idempotence: Idempotence, attempt: (connection: Connection) => Promise<T>, signal?: AbortSignal): Promise<T>;
|
|
62
|
+
/** Closes the connection and every one to come. */
|
|
63
|
+
close(): Promise<void>;
|
|
64
|
+
}
|
|
65
|
+
/** What a download sent: its header, its items, and the trailer that ended it. */
|
|
66
|
+
export interface Downloaded {
|
|
67
|
+
header: Uint8Array;
|
|
68
|
+
items: Uint8Array[];
|
|
69
|
+
trailer: Uint8Array;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Runs a download to its end: the RESPONSE that heads it, an item a DATA, and
|
|
73
|
+
* the DATA that ends it, giving each item's credit back as it arrives, since
|
|
74
|
+
* the server bounds a page before it sends it. A download the server answers
|
|
75
|
+
* with a RESPONSE that ends it has no items and that RESPONSE for trailer.
|
|
76
|
+
*/
|
|
77
|
+
export declare function download(connection: Connection, method: number, body: Uint8Array, signal?: AbortSignal): Promise<Downloaded>;
|
|
78
|
+
export type { Stream };
|