@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
package/dist/kv.js
CHANGED
|
@@ -1,661 +1,320 @@
|
|
|
1
|
-
// The application's current state in kv.db, as
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
|
|
5
|
-
import {
|
|
6
|
-
import { checkName, handleOn, ownerText,
|
|
7
|
-
import { Limiter, limiterOpen } from './limiter.js';
|
|
8
|
-
import { Once } from './once.js';
|
|
9
|
-
import { Quota, quotaOpen } from './quota.js';
|
|
10
|
-
import { check, isSchema } from './schema.js';
|
|
1
|
+
// The application's current state in kv.db, as docs/guides/kv/README.md has it: buckets
|
|
2
|
+
// of one value type by key, keys in branches, expiry by the store's clock and
|
|
3
|
+
// versions that never repeat, with counters beside them. A handle opens with
|
|
4
|
+
// its first call on a connection.
|
|
5
|
+
import { CorruptError, InvalidError } from './errors.js';
|
|
6
|
+
import { checkName, handleOn, ownerText, viaLink, } from './handles.js';
|
|
11
7
|
import { dateOf, ms, unixMs } from './time.js';
|
|
12
8
|
import { textOf } from './wire/codec.js';
|
|
13
|
-
import {
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
this.#link = link;
|
|
19
|
-
}
|
|
20
|
-
/**
|
|
21
|
-
* The config name, shaped and typed as its defaults, then each layer over
|
|
22
|
-
* the one before: a file's values, `fromEnv`, and what update kept over
|
|
23
|
-
* them all. It resolves once the server's state is read, and follows every
|
|
24
|
-
* change from then on, whoever makes it, until the store closes.
|
|
25
|
-
*
|
|
26
|
-
* ```ts
|
|
27
|
-
* const cfg = await store.kv.config('app', {
|
|
28
|
-
* port: 8080,
|
|
29
|
-
* db: { url: secret('DATABASE_URL'), pool: 10 },
|
|
30
|
-
* }, file, fromEnv('APP'))
|
|
31
|
-
* cfg.value.port // APP_PORT=3000 makes it 3000
|
|
32
|
-
* await cfg.update({ port: 4000 }) // kept: 4000 after a restart too
|
|
33
|
-
* ```
|
|
34
|
-
*/
|
|
35
|
-
async config(name, defaults, ...layers) {
|
|
36
|
-
const config = new Config(this.#link, name, defaults);
|
|
37
|
-
await config.lay(layers);
|
|
38
|
-
this.#configs.add(config);
|
|
39
|
-
try {
|
|
40
|
-
await config.start();
|
|
41
|
-
}
|
|
42
|
-
catch (err) {
|
|
43
|
-
this.#configs.delete(config);
|
|
44
|
-
throw err;
|
|
45
|
-
}
|
|
46
|
-
return config;
|
|
47
|
-
}
|
|
48
|
-
/** A limiter of requests by key: `store.kv.limiter('api', { rate: '100/s', burst: 20 })`. */
|
|
49
|
-
limiter(name, options) {
|
|
50
|
-
return new Limiter(this.#link, name, limiterOpen(name, options), []);
|
|
51
|
-
}
|
|
52
|
-
/**
|
|
53
|
-
* A quota of uses by key, its windows by name, each counted from a key's
|
|
54
|
-
* first use and all of them together or none:
|
|
55
|
-
* `store.kv.quota('ai', { session: '100/5h', weekly: '300/7d' })`.
|
|
56
|
-
*/
|
|
57
|
-
quota(name, windows) {
|
|
58
|
-
return new Quota(this.#link, name, quotaOpen(name, windows), []);
|
|
59
|
-
}
|
|
60
|
-
once(name, of, options) {
|
|
61
|
-
checkName(name, 'once');
|
|
62
|
-
let values = jsonValues;
|
|
63
|
-
if (isSchema(of)) {
|
|
64
|
-
values = schemaValues(of);
|
|
65
|
-
}
|
|
66
|
-
else if (of !== undefined) {
|
|
67
|
-
options = of;
|
|
68
|
-
}
|
|
69
|
-
const open = KvBucket.encode({
|
|
70
|
-
name,
|
|
71
|
-
once: true,
|
|
72
|
-
defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
|
|
73
|
-
});
|
|
74
|
-
return new Once(this.#link, name, open, values, []);
|
|
75
|
-
}
|
|
76
|
-
/** Stops following configs, as the store does when it closes. */
|
|
77
|
-
stop() {
|
|
78
|
-
for (const config of this.#configs) {
|
|
79
|
-
config.stop();
|
|
80
|
-
}
|
|
81
|
-
}
|
|
82
|
-
bucket(name, of, options) {
|
|
83
|
-
checkName(name, 'bucket');
|
|
84
|
-
let values = jsonValues;
|
|
85
|
-
if (typeof of === 'string') {
|
|
86
|
-
values = valuesOf(of);
|
|
87
|
-
}
|
|
88
|
-
else if (isSchema(of)) {
|
|
89
|
-
values = schemaValues(of);
|
|
90
|
-
}
|
|
91
|
-
else if (of !== undefined) {
|
|
92
|
-
options = of;
|
|
93
|
-
}
|
|
94
|
-
if (options?.defaultTtl !== undefined && options.sliding !== undefined) {
|
|
95
|
-
throw new InvalidError(`bucket ${name}: sliding and defaultTtl are one or the other`);
|
|
96
|
-
}
|
|
97
|
-
const open = KvBucket.encode({
|
|
98
|
-
name,
|
|
99
|
-
defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
|
|
100
|
-
sliding: options?.sliding === undefined ? undefined : ms(options.sliding),
|
|
101
|
-
});
|
|
102
|
-
return new Bucket(this.#link, name, open, values, []);
|
|
103
|
-
}
|
|
104
|
-
counters(name, of, options) {
|
|
105
|
-
checkName(name, 'counters');
|
|
106
|
-
const big = of === 'bigint';
|
|
107
|
-
if (typeof of === 'object') {
|
|
108
|
-
options = of;
|
|
109
|
-
}
|
|
110
|
-
const open = KvBucket.encode({
|
|
111
|
-
name,
|
|
112
|
-
counters: true,
|
|
113
|
-
defaultTtl: options?.defaultTtl === undefined ? undefined : ms(options.defaultTtl),
|
|
114
|
-
loseAtMost: options?.loseAtMost === undefined ? undefined : ms(options.loseAtMost),
|
|
115
|
-
});
|
|
116
|
-
return new Counters(this.#link, name, open, big, []);
|
|
117
|
-
}
|
|
118
|
-
/**
|
|
119
|
-
* Runs the calls fn asks for in one transaction, all or none: the calls of
|
|
120
|
-
* buckets it takes through withTx, whose promises settle once the batch
|
|
121
|
-
* has. fn returns before anything is sent, since no transaction is held
|
|
122
|
-
* across the network: a call cannot wait for another's answer inside it.
|
|
123
|
-
* What fn returns comes back answered, an array's promises each:
|
|
124
|
-
*
|
|
125
|
-
* const [code] = await store.kv.batch(tx => [codes.withTx(tx).take(k), used.withTx(tx).set(k, 1)])
|
|
126
|
-
*/
|
|
127
|
-
batch(fn) {
|
|
128
|
-
return runCalls(this.#link, 'batch', fn);
|
|
129
|
-
}
|
|
130
|
-
/**
|
|
131
|
-
* Reads the gets and hases fn asks for from one snapshot, and gives back
|
|
132
|
-
* what fn returns, answered as batch answers it:
|
|
133
|
-
*
|
|
134
|
-
* const [profile, prefs] = await store.kv.view(tx => [a.withTx(tx).get(id), b.withTx(tx).get(id)])
|
|
135
|
-
*/
|
|
136
|
-
view(fn) {
|
|
137
|
-
return runCalls(this.#link, 'view', fn);
|
|
138
|
-
}
|
|
139
|
-
/**
|
|
140
|
-
* Runs fn as one transaction that reads before it decides what to write,
|
|
141
|
-
* as Go's Tx does, without holding the writer across the network: a read
|
|
142
|
-
* goes to the server at once, a write waits, and when fn returns the writes
|
|
143
|
-
* commit in one batch that first checks every key fn read is still as it
|
|
144
|
-
* read it. When another write changed one meanwhile, fn runs again, five
|
|
145
|
-
* times at most before ConflictError, so it does nothing else that must
|
|
146
|
-
* happen once. It gives back what fn returns.
|
|
147
|
-
*
|
|
148
|
-
* const userId = await store.kv.tx(async tx => {
|
|
149
|
-
* const userId = await codes.withTx(tx).take(digest(code))
|
|
150
|
-
* if (userId === undefined) throw new InvalidCode()
|
|
151
|
-
* sessions.withTx(tx).of(userId).set(digest(token), { device })
|
|
152
|
-
* return userId
|
|
153
|
-
* })
|
|
154
|
-
*/
|
|
155
|
-
async tx(fn) {
|
|
156
|
-
for (let run = 1;; run++) {
|
|
157
|
-
const tx = new Tx(this.#link);
|
|
158
|
-
const returned = await fn(tx);
|
|
159
|
-
try {
|
|
160
|
-
await tx.commit();
|
|
161
|
-
return returned;
|
|
162
|
-
}
|
|
163
|
-
catch (err) {
|
|
164
|
-
if (run >= txRuns || !tx.stale(err)) {
|
|
165
|
-
throw err;
|
|
166
|
-
}
|
|
167
|
-
}
|
|
168
|
-
}
|
|
169
|
-
}
|
|
170
|
-
}
|
|
171
|
-
/** How many times tx runs its function before a key it read that keeps changing is ConflictError. */
|
|
172
|
-
const txRuns = 5;
|
|
173
|
-
/** The calls a batch or a view gathered, in their order. */
|
|
174
|
-
export class Batch {
|
|
175
|
-
kind;
|
|
176
|
-
calls = [];
|
|
177
|
-
#done = false;
|
|
178
|
-
#made = new WeakSet();
|
|
179
|
-
constructor(kind) {
|
|
180
|
-
this.kind = kind;
|
|
181
|
-
}
|
|
182
|
-
/** Whether the promise is one of this batch's calls', rather than an async function's. */
|
|
183
|
-
made(promise) {
|
|
184
|
-
return this.#made.has(promise);
|
|
185
|
-
}
|
|
186
|
-
record(call, settle) {
|
|
187
|
-
if (this.#done) {
|
|
188
|
-
throw new InvalidError(`a ${this.kind} takes its calls while its function runs, before it is sent`);
|
|
189
|
-
}
|
|
190
|
-
if (this.kind === 'view' && call.method !== 'kv.get' && call.method !== 'kv.has') {
|
|
191
|
-
throw new InvalidError(`${call.method} in a view, which reads`);
|
|
192
|
-
}
|
|
193
|
-
let resolve;
|
|
194
|
-
let reject;
|
|
195
|
-
const settled = new Promise((res, rej) => {
|
|
196
|
-
resolve = res;
|
|
197
|
-
reject = rej;
|
|
198
|
-
});
|
|
199
|
-
// a caller need not await a call it only wanted done
|
|
200
|
-
settled.catch(() => { });
|
|
201
|
-
this.#made.add(settled);
|
|
202
|
-
this.calls.push({
|
|
203
|
-
...call,
|
|
204
|
-
settle: async (entry) => {
|
|
205
|
-
try {
|
|
206
|
-
resolve(await settle(entry));
|
|
207
|
-
}
|
|
208
|
-
catch (err) {
|
|
209
|
-
reject(err);
|
|
210
|
-
}
|
|
211
|
-
},
|
|
212
|
-
fail: reject,
|
|
213
|
-
});
|
|
214
|
-
return settled;
|
|
215
|
-
}
|
|
216
|
-
close() {
|
|
217
|
-
this.#done = true;
|
|
218
|
-
}
|
|
219
|
-
}
|
|
220
|
-
const absent = { found: false, value: null, version: '', expires: undefined };
|
|
221
|
-
/**
|
|
222
|
-
* A transaction of store.kv.tx: a read goes to the server at once and is
|
|
223
|
-
* remembered with its version, so that a key read again answers the same; a
|
|
224
|
-
* write waits for the commit, and a key read after it answers what it wrote.
|
|
225
|
-
*/
|
|
226
|
-
export class Tx {
|
|
227
|
-
#link;
|
|
228
|
-
#reads = new Map();
|
|
229
|
-
#writes = new Map();
|
|
230
|
-
#checks = 0;
|
|
231
|
-
#done = false;
|
|
232
|
-
constructor(link) {
|
|
233
|
-
this.#link = link;
|
|
234
|
-
}
|
|
235
|
-
record(call, settle) {
|
|
236
|
-
if (this.#done) {
|
|
237
|
-
throw new InvalidError('a tx takes its calls while its function runs, before it commits');
|
|
238
|
-
}
|
|
239
|
-
const at = placeOf(call);
|
|
240
|
-
switch (call.method) {
|
|
241
|
-
case 'kv.get':
|
|
242
|
-
case 'kv.has':
|
|
243
|
-
return this.#read(at, call).then(settle);
|
|
244
|
-
case 'kv.take': {
|
|
245
|
-
const read = this.#read(at, call);
|
|
246
|
-
this.#writes.set(at, { call: { ...call, method: 'kv.delete' }, entry: absent });
|
|
247
|
-
return read.then(settle);
|
|
248
|
-
}
|
|
249
|
-
case 'kv.set': {
|
|
250
|
-
// a set's value is what the bucket encoded, which a read decodes
|
|
251
|
-
const value = (call.call.value ?? null);
|
|
252
|
-
const entry = { found: true, value, version: '', expires: undefined };
|
|
253
|
-
this.#writes.set(at, { call, entry });
|
|
254
|
-
return settle(entry);
|
|
255
|
-
}
|
|
256
|
-
case 'kv.delete':
|
|
257
|
-
this.#writes.set(at, { call, entry: absent });
|
|
258
|
-
return settle(absent);
|
|
259
|
-
}
|
|
260
|
-
throw new InvalidError(`${call.method} in a tx`);
|
|
261
|
-
}
|
|
262
|
-
#read(at, call) {
|
|
263
|
-
const written = this.#writes.get(at);
|
|
264
|
-
if (written !== undefined) {
|
|
265
|
-
return Promise.resolve(written.entry);
|
|
266
|
-
}
|
|
267
|
-
let reading = this.#reads.get(at);
|
|
268
|
-
if (reading === undefined) {
|
|
269
|
-
reading = this.#fetch(call);
|
|
270
|
-
// a read fn never awaited still fails the commit, which awaits it
|
|
271
|
-
reading.catch(() => { });
|
|
272
|
-
this.#reads.set(at, reading);
|
|
273
|
-
}
|
|
274
|
-
return reading.then(read => read.entry);
|
|
275
|
-
}
|
|
276
|
-
async #fetch(call) {
|
|
277
|
-
const ask = { owners: call.call.owners, key: call.call.key };
|
|
278
|
-
const e = await this.#link.run('read', async (connection) => {
|
|
279
|
-
const handle = await handleOn(connection, methods['kv.open'], call.open);
|
|
280
|
-
const body = await connection.session.call(methods['kv.get'], KvCall.encode({ ...ask, handle }));
|
|
281
|
-
return KvEntry.decode(body);
|
|
282
|
-
});
|
|
283
|
-
return {
|
|
284
|
-
call: { method: 'kv.get', open: call.open, call: ask },
|
|
285
|
-
version: e.version,
|
|
286
|
-
entry: entryOfWire(e),
|
|
287
|
-
};
|
|
288
|
-
}
|
|
289
|
-
/**
|
|
290
|
-
* Sends what fn wrote in one batch, after a check of each key it read: a
|
|
291
|
-
* key it found at the version it found, a key it found absent still
|
|
292
|
-
* absent. A tx that only read checks its reads from one snapshot.
|
|
293
|
-
*/
|
|
294
|
-
async commit() {
|
|
295
|
-
this.#done = true;
|
|
296
|
-
const calls = [];
|
|
297
|
-
for (const reading of this.#reads.values()) {
|
|
298
|
-
const read = await reading;
|
|
299
|
-
const still = read.entry.found ? { ifVersion: read.version } : { ifAbsent: true };
|
|
300
|
-
calls.push({ ...read.call, call: { ...read.call.call, ...still } });
|
|
301
|
-
}
|
|
302
|
-
this.#checks = calls.length;
|
|
303
|
-
for (const write of this.#writes.values()) {
|
|
304
|
-
calls.push(write.call);
|
|
305
|
-
}
|
|
306
|
-
if (calls.length === 0) {
|
|
307
|
-
return;
|
|
308
|
-
}
|
|
309
|
-
const writes = this.#writes.size > 0;
|
|
310
|
-
await this.#link.run(writes ? 'write' : 'read', async (connection) => {
|
|
311
|
-
const encoded = [];
|
|
312
|
-
for (const call of calls) {
|
|
313
|
-
const handle = await handleOn(connection, methods['kv.open'], call.open);
|
|
314
|
-
encoded.push({ method: methods[call.method], ...call.call, handle });
|
|
315
|
-
}
|
|
316
|
-
const method = writes ? methods['kv.batch'] : methods['kv.view'];
|
|
317
|
-
await connection.session.call(method, KvCalls.encode({ calls: encoded }));
|
|
318
|
-
});
|
|
319
|
-
}
|
|
320
|
-
/** Whether the commit failed for a key fn read that changed since, which another run reads anew. */
|
|
321
|
-
stale(err) {
|
|
322
|
-
return err instanceof ConflictError && Number(err.what.call) < this.#checks;
|
|
323
|
-
}
|
|
324
|
-
}
|
|
325
|
-
/**
|
|
326
|
-
* A key's place as one text: its bucket's open and its owners included, an
|
|
327
|
-
* integer its decimal spelling, as the store keeps it.
|
|
328
|
-
*/
|
|
329
|
-
function placeOf(call) {
|
|
330
|
-
const part = (p) => p instanceof Uint8Array ? `b${Buffer.from(p).toString('base64')}` : `t${String(p ?? '')}`;
|
|
331
|
-
const owners = call.call.owners ?? [];
|
|
332
|
-
return [Buffer.from(call.open).toString('base64'), ...owners.map(part), part(call.call.key)].join('\u0000');
|
|
333
|
-
}
|
|
334
|
-
async function runCalls(link, kind, fn) {
|
|
335
|
-
const tx = new Batch(kind);
|
|
336
|
-
const returned = fn(tx);
|
|
337
|
-
tx.close();
|
|
338
|
-
if (returned instanceof Promise && !tx.made(returned)) {
|
|
339
|
-
throw new InvalidError(`a ${kind}'s function returns before anything is sent; it cannot await inside`);
|
|
340
|
-
}
|
|
341
|
-
if (tx.calls.length > 0) {
|
|
342
|
-
await sendCalls(link, kind, tx);
|
|
343
|
-
}
|
|
344
|
-
return settle(returned);
|
|
345
|
-
}
|
|
346
|
-
async function sendCalls(link, kind, tx) {
|
|
347
|
-
try {
|
|
348
|
-
const results = await link.run(kind === 'view' ? 'read' : 'write', async (connection) => {
|
|
349
|
-
const calls = [];
|
|
350
|
-
for (const call of tx.calls) {
|
|
351
|
-
const handle = await handleOn(connection, methods['kv.open'], call.open);
|
|
352
|
-
calls.push({ method: methods[call.method], ...call.call, handle });
|
|
353
|
-
}
|
|
354
|
-
const body = await connection.session.call(methods[`kv.${kind}`], KvCalls.encode({ calls }));
|
|
355
|
-
return KvResults.decode(body).entries ?? [];
|
|
356
|
-
});
|
|
357
|
-
await Promise.all(tx.calls.map((call, i) => call.settle(entryOfWire(results[i] ?? {}))));
|
|
358
|
-
}
|
|
359
|
-
catch (err) {
|
|
360
|
-
for (const call of tx.calls) {
|
|
361
|
-
call.fail?.(err);
|
|
362
|
-
}
|
|
363
|
-
throw err;
|
|
364
|
-
}
|
|
365
|
-
}
|
|
366
|
-
function entryOfWire(e) {
|
|
367
|
-
return {
|
|
368
|
-
found: e.found ?? false,
|
|
369
|
-
value: e.value ?? null,
|
|
370
|
-
version: versionText(e.version),
|
|
371
|
-
expires: dateOf(e.expires),
|
|
372
|
-
};
|
|
373
|
-
}
|
|
374
|
-
/** A version's bytes as text, each byte a code unit, so that any bytes go back as they came. */
|
|
375
|
-
function versionText(version) {
|
|
376
|
-
return version === undefined ? '' : String.fromCharCode(...version);
|
|
377
|
-
}
|
|
378
|
-
function versionBytes(version) {
|
|
379
|
-
return Uint8Array.from(version, c => c.charCodeAt(0));
|
|
380
|
-
}
|
|
381
|
-
function writeFields(options) {
|
|
382
|
-
return {
|
|
383
|
-
ttl: options?.ttl === undefined ? undefined : ms(options.ttl),
|
|
384
|
-
expireAt: options?.expireAt === undefined ? undefined : unixMs(options.expireAt),
|
|
385
|
-
ifVersion: options?.ifVersion === undefined ? undefined : versionBytes(options.ifVersion),
|
|
386
|
-
};
|
|
9
|
+
import { KvBranch, KvBucketOpen, KvCall, KvCount, KvCountersOpen, KvEntry, KvFound, KvList, KvPage, KvWritten, methods, } from './wire/protocol.js';
|
|
10
|
+
// a handle's parts, kept out of its public shape, for store.tx
|
|
11
|
+
const parts = new WeakMap();
|
|
12
|
+
export function partsOf(handle) {
|
|
13
|
+
return parts.get(handle);
|
|
387
14
|
}
|
|
388
|
-
/**
|
|
389
|
-
* A bucket's values under one branch of owners, the root when there are
|
|
390
|
-
* none: `sessions.of(user.id).get(token)`.
|
|
391
|
-
*/
|
|
15
|
+
/** A bucket's values under one branch of owners, the bucket's own when there are none. */
|
|
392
16
|
export class Bucket {
|
|
393
17
|
name;
|
|
394
18
|
#link;
|
|
395
19
|
#open;
|
|
396
20
|
#values;
|
|
397
|
-
#
|
|
398
|
-
|
|
21
|
+
#under;
|
|
22
|
+
#home;
|
|
23
|
+
#via;
|
|
24
|
+
/** reads a get's or a take's answer: the value, undefined where the key held none */
|
|
25
|
+
#value;
|
|
26
|
+
/**
|
|
27
|
+
* Buckets come from `store.bucket`, `db.bucket` and their `under`; inside
|
|
28
|
+
* a database's transaction, from `tx.with(bucket)`, whose calls go through
|
|
29
|
+
* the transaction.
|
|
30
|
+
*/
|
|
31
|
+
constructor(link, name, open, values, under, home, via) {
|
|
399
32
|
this.#link = link;
|
|
400
33
|
this.name = name;
|
|
401
34
|
this.#open = open;
|
|
402
35
|
this.#values = values;
|
|
403
|
-
this.#
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
* it, or inside a tx, whose reads answer at once and writes wait for it.
|
|
415
|
-
*/
|
|
416
|
-
withTx(tx) {
|
|
417
|
-
return new BucketTx(tx, this.#open, this.#values, this.#owners);
|
|
418
|
-
}
|
|
419
|
-
async #call(method, fields, idempotence) {
|
|
420
|
-
return this.#link.run(idempotence, async (connection) => {
|
|
421
|
-
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
422
|
-
const body = KvCall.encode({
|
|
423
|
-
handle,
|
|
424
|
-
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
425
|
-
...fields,
|
|
426
|
-
});
|
|
427
|
-
return KvEntry.decode(await connection.session.call(methods[method], body));
|
|
428
|
-
});
|
|
36
|
+
this.#under = under;
|
|
37
|
+
this.#home = home;
|
|
38
|
+
this.#via = via ?? home?.via(`kv bucket ${name}`) ?? viaLink(link);
|
|
39
|
+
this.#value = r => valueIn(r, values);
|
|
40
|
+
const own = { link, name, open, openMethod: 'kv.bucket.open', under, home };
|
|
41
|
+
parts.set(this, { ...own, values: values });
|
|
42
|
+
}
|
|
43
|
+
/** The branch the owners name below this one: whose keys these are. */
|
|
44
|
+
under(...owners) {
|
|
45
|
+
const under = [...this.#under, ...owners.map(keyText)];
|
|
46
|
+
return new Bucket(this.#link, this.name, this.#open, this.#values, under, this.#home, this.#via);
|
|
429
47
|
}
|
|
430
48
|
/** The key's value, undefined when it holds none. */
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
return entry?.value;
|
|
49
|
+
get(key) {
|
|
50
|
+
return this.#ask('kv.get', { key }, 'read', this.#value);
|
|
434
51
|
}
|
|
435
52
|
/** The key's value with its version and expiry, undefined when it holds none. */
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
return undefined;
|
|
440
|
-
}
|
|
441
|
-
return {
|
|
442
|
-
value: await this.#values.decode(e.value ?? null),
|
|
443
|
-
version: versionText(e.version),
|
|
444
|
-
expires: dateOf(e.expires),
|
|
445
|
-
};
|
|
53
|
+
entry(key) {
|
|
54
|
+
return this.#ask('kv.get', { key }, 'read', r => {
|
|
55
|
+
const found = KvEntry.read(r);
|
|
56
|
+
return found.found === true ? entryOf(key, found, this.#values) : undefined;
|
|
57
|
+
});
|
|
446
58
|
}
|
|
447
|
-
|
|
448
|
-
return
|
|
59
|
+
has(key) {
|
|
60
|
+
return this.#ask('kv.has', { key }, 'read', found);
|
|
449
61
|
}
|
|
450
|
-
/** Writes the value; a
|
|
62
|
+
/** Writes the value; a key that exists keeps its expiry unless the options give one. */
|
|
451
63
|
async set(key, value, options) {
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
/** Writes the value and gives its new version and expiry. */
|
|
455
|
-
async setEntry(key, value, options) {
|
|
456
|
-
const raw = await this.#values.encode(value);
|
|
457
|
-
const e = await this.#call('kv.set', { key, value: raw, ...writeFields(options) }, 'write');
|
|
458
|
-
return { value, version: versionText(e.version), expires: dateOf(e.expires) };
|
|
64
|
+
const raw = this.#values.encode(value);
|
|
65
|
+
await this.#ask('kv.set', { key, value: raw, ...writeFields(options) }, 'write', unread);
|
|
459
66
|
}
|
|
460
67
|
/** Writes the value only where no live key is, and says whether it did. */
|
|
461
|
-
async
|
|
462
|
-
|
|
68
|
+
async create(key, value, options) {
|
|
69
|
+
const raw = this.#values.encode(value);
|
|
70
|
+
return this.#ask('kv.create', { key, value: raw, ...writeFields(options) }, 'write', written);
|
|
71
|
+
}
|
|
72
|
+
/** Puts the key in a bucket used as a set; false when it was there. */
|
|
73
|
+
async add(key, options) {
|
|
74
|
+
return this.#ask('kv.create', { key, ...writeFields(options) }, 'write', written);
|
|
463
75
|
}
|
|
464
76
|
/**
|
|
465
|
-
*
|
|
466
|
-
*
|
|
77
|
+
* Reads the value and removes the key in one commit: of two callers taking
|
|
78
|
+
* a one-time code at once, one gets it.
|
|
467
79
|
*/
|
|
468
|
-
async
|
|
469
|
-
|
|
470
|
-
const e = await this.#call('kv.set', { key, value: raw, ifAbsent: true, ...writeFields(options) }, 'write');
|
|
471
|
-
const created = e.found === true;
|
|
472
|
-
return {
|
|
473
|
-
created,
|
|
474
|
-
entry: {
|
|
475
|
-
value: created ? value : await this.#values.decode(e.value ?? null),
|
|
476
|
-
version: versionText(e.version),
|
|
477
|
-
expires: dateOf(e.expires),
|
|
478
|
-
},
|
|
479
|
-
};
|
|
80
|
+
async take(key, options) {
|
|
81
|
+
return this.#ask('kv.take', { key, ...writeFields(options) }, 'write', this.#value);
|
|
480
82
|
}
|
|
83
|
+
/** Removes the key, and says whether it was there. */
|
|
481
84
|
async delete(key, options) {
|
|
482
|
-
|
|
85
|
+
return this.#ask('kv.delete', { key, ...writeFields(options) }, 'write', found);
|
|
483
86
|
}
|
|
484
87
|
/**
|
|
485
|
-
*
|
|
486
|
-
*
|
|
88
|
+
* Gives a live key a new expiry, a span from now or a time, keeping its
|
|
89
|
+
* value; false when it holds none.
|
|
487
90
|
*/
|
|
488
|
-
async
|
|
489
|
-
const
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
/** Gives a live key a new expiry, keeping its value and version; false when it holds none. */
|
|
493
|
-
async touch(key, options) {
|
|
494
|
-
return (await this.#call('kv.touch', { key, ...writeFields(options) }, 'write')).found === true;
|
|
91
|
+
async expire(key, when, options) {
|
|
92
|
+
const expiry = when instanceof Date ? { expiresAt: when } : { ttl: when };
|
|
93
|
+
const fields = { key, ...writeFields({ ...options, ...expiry }) };
|
|
94
|
+
return this.#ask('kv.expire', fields, 'write', found);
|
|
495
95
|
}
|
|
496
96
|
/** Removes this branch's keys and every branch under it, at once however many. */
|
|
497
97
|
async clear() {
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
limit: options?.limit,
|
|
509
|
-
}), true);
|
|
510
|
-
const items = [];
|
|
511
|
-
for (;;) {
|
|
512
|
-
const event = await stream.next();
|
|
513
|
-
if (event.kind === 'response') {
|
|
514
|
-
continue;
|
|
515
|
-
}
|
|
516
|
-
stream.consumed(event.body.length);
|
|
517
|
-
if (event.end) {
|
|
518
|
-
return { items, page: KvPage.decode(event.body) };
|
|
519
|
-
}
|
|
520
|
-
items.push(KvEntry.decode(event.body));
|
|
521
|
-
}
|
|
522
|
-
});
|
|
523
|
-
const decoded = [];
|
|
524
|
-
for (const e of items) {
|
|
525
|
-
decoded.push({
|
|
526
|
-
key: e.key ?? '',
|
|
527
|
-
value: await this.#values.decode(e.value ?? null),
|
|
528
|
-
version: versionText(e.version),
|
|
529
|
-
expires: dateOf(e.expires),
|
|
530
|
-
});
|
|
531
|
-
}
|
|
532
|
-
return { items: decoded, next: page.more === true ? (page.after ?? '') : undefined };
|
|
98
|
+
const under = underField(this.#under);
|
|
99
|
+
await this.#via.call(methods['kv.bucket.open'], this.#open, methods['kv.clear'], handle => KvBranch.encode({ handle, under }), 'write');
|
|
100
|
+
}
|
|
101
|
+
/** One page of this branch's own keys, in the byte order of their text: `"10"` before `"9"`. */
|
|
102
|
+
async list(options) {
|
|
103
|
+
const under = underField(this.#under);
|
|
104
|
+
const body = await this.#via.call(methods['kv.bucket.open'], this.#open, methods['kv.list'], handle => KvList.encode({ handle, under, after: options?.after, limit: options?.limit }), 'read');
|
|
105
|
+
const page = KvPage.decode(body);
|
|
106
|
+
const entries = (page.entries ?? []).map(found => entryOf(found.key ?? '', found, this.#values));
|
|
107
|
+
return { entries, next: page.next === undefined ? undefined : keyText(page.next) };
|
|
533
108
|
}
|
|
534
109
|
/**
|
|
535
|
-
* Walks this branch's own keys a page at a time, holding
|
|
536
|
-
*
|
|
110
|
+
* Walks this branch's own keys a page at a time, holding nothing between
|
|
111
|
+
* pages: a key written during the walk may or may not be met. It renews no
|
|
112
|
+
* idle key.
|
|
537
113
|
*/
|
|
538
114
|
async *all(options) {
|
|
539
115
|
let after;
|
|
540
116
|
for (;;) {
|
|
541
|
-
const page = await this.
|
|
542
|
-
yield* page.
|
|
117
|
+
const page = await this.list({ ...options, ...(after === undefined ? {} : { after }) });
|
|
118
|
+
yield* page.entries;
|
|
543
119
|
if (page.next === undefined) {
|
|
544
120
|
return;
|
|
545
121
|
}
|
|
546
122
|
after = page.next;
|
|
547
123
|
}
|
|
548
124
|
}
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
this.#open = open;
|
|
559
|
-
this.#values = values;
|
|
560
|
-
this.#owners = owners;
|
|
561
|
-
}
|
|
562
|
-
of(...owners) {
|
|
563
|
-
return new BucketTx(this.#tx, this.#open, this.#values, [
|
|
564
|
-
...this.#owners,
|
|
565
|
-
...owners.map(ownerText),
|
|
566
|
-
]);
|
|
567
|
-
}
|
|
568
|
-
#record(method, fields, settle) {
|
|
569
|
-
const owners = this.#owners.length > 0 ? this.#owners : undefined;
|
|
570
|
-
return this.#tx.record({ method, open: this.#open, call: { owners, ...fields } }, settle);
|
|
571
|
-
}
|
|
572
|
-
get(key) {
|
|
573
|
-
return this.#record('kv.get', { key }, async (e) => e.found ? this.#values.decode(e.value) : undefined);
|
|
574
|
-
}
|
|
575
|
-
has(key) {
|
|
576
|
-
return this.#record('kv.has', { key }, async (e) => e.found);
|
|
577
|
-
}
|
|
578
|
-
set(key, value, options) {
|
|
579
|
-
return this.#record('kv.set', { key, value: this.#encodeNow(value), ...writeFields(options) }, async () => { });
|
|
580
|
-
}
|
|
581
|
-
delete(key, options) {
|
|
582
|
-
return this.#record('kv.delete', { key, ...writeFields(options) }, async () => { });
|
|
583
|
-
}
|
|
584
|
-
take(key) {
|
|
585
|
-
return this.#record('kv.take', { key }, async (e) => e.found ? this.#values.decode(e.value) : undefined);
|
|
586
|
-
}
|
|
587
|
-
// a batch is sent once its function returns, so a value is encoded as it is given
|
|
588
|
-
#encodeNow(value) {
|
|
589
|
-
const raw = this.#values.encode(value);
|
|
590
|
-
if (raw instanceof Promise) {
|
|
591
|
-
throw new InvalidError('a bucket whose values encode asynchronously takes no batch');
|
|
592
|
-
}
|
|
593
|
-
return raw;
|
|
125
|
+
// a call on one key: its fields written where they leave from, its answer read where it arrived
|
|
126
|
+
#ask(method, fields, idempotence, read) {
|
|
127
|
+
// the caller's own fields, made the call's: an object more a call is one too many
|
|
128
|
+
const call = fields;
|
|
129
|
+
call.under = underField(this.#under);
|
|
130
|
+
return this.#via.ask(methods['kv.bucket.open'], this.#open, methods[method], (w, handle) => {
|
|
131
|
+
call.handle = handle;
|
|
132
|
+
KvCall.write(w, call);
|
|
133
|
+
}, read, idempotence);
|
|
594
134
|
}
|
|
595
135
|
}
|
|
136
|
+
const [foundField] = KvEntry.fields.found;
|
|
137
|
+
const [valueField] = KvEntry.fields.value;
|
|
596
138
|
/**
|
|
597
|
-
*
|
|
598
|
-
*
|
|
139
|
+
* Reads an entry for its value alone, undefined where the key held none: the
|
|
140
|
+
* two fields a get needs, the value decoded from where the answer lies unless
|
|
141
|
+
* its bucket keeps the bytes.
|
|
599
142
|
*/
|
|
143
|
+
function valueIn(r, values) {
|
|
144
|
+
let found = false;
|
|
145
|
+
let raw = null;
|
|
146
|
+
for (let n = r.message(); n > 0; n--) {
|
|
147
|
+
const field = r.field();
|
|
148
|
+
if (field === foundField) {
|
|
149
|
+
found = r.bool();
|
|
150
|
+
}
|
|
151
|
+
else if (field !== valueField) {
|
|
152
|
+
r.skip();
|
|
153
|
+
}
|
|
154
|
+
else if (!r.nil()) {
|
|
155
|
+
raw = r.type() !== 'bin' ? r.int64() : values.keeps === true ? r.bytes() : r.bin();
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
r.leave();
|
|
159
|
+
return found ? values.decode(raw) : undefined;
|
|
160
|
+
}
|
|
161
|
+
const found = (r) => KvFound.read(r).found === true;
|
|
162
|
+
const written = (r) => KvWritten.read(r).written === true;
|
|
163
|
+
/** Reads past an answer nobody asked to see. */
|
|
164
|
+
const unread = (r) => r.skip();
|
|
165
|
+
/** Numbers by key that only add up: 0 for one never added to or expired. */
|
|
600
166
|
export class Counters {
|
|
601
167
|
name;
|
|
602
168
|
#link;
|
|
603
169
|
#open;
|
|
604
|
-
#
|
|
605
|
-
|
|
606
|
-
constructor(link, name, open,
|
|
170
|
+
#under;
|
|
171
|
+
/** Counters come from `store.counters` and their `under`. */
|
|
172
|
+
constructor(link, name, open, under) {
|
|
607
173
|
this.#link = link;
|
|
608
174
|
this.name = name;
|
|
609
175
|
this.#open = open;
|
|
610
|
-
this.#
|
|
611
|
-
this
|
|
612
|
-
}
|
|
613
|
-
of(...owners) {
|
|
614
|
-
return new Counters(this.#link, this.name, this.#open, this.#big, [
|
|
615
|
-
...this.#owners,
|
|
616
|
-
...owners.map(ownerText),
|
|
617
|
-
]);
|
|
618
|
-
}
|
|
619
|
-
async #call(method, key, n) {
|
|
620
|
-
const e = await this.#link.run(method === 'kv.get' ? 'read' : 'write', async (connection) => {
|
|
621
|
-
const handle = await handleOn(connection, methods['kv.open'], this.#open);
|
|
622
|
-
const body = KvCall.encode({
|
|
623
|
-
handle,
|
|
624
|
-
owners: this.#owners.length > 0 ? this.#owners : undefined,
|
|
625
|
-
key,
|
|
626
|
-
n,
|
|
627
|
-
});
|
|
628
|
-
return KvEntry.decode(await connection.session.call(methods[method], body));
|
|
629
|
-
});
|
|
630
|
-
const value = typeof e.value === 'bigint' ? e.value : 0n;
|
|
631
|
-
return (this.#big ? value : numberOf(value, this.name));
|
|
176
|
+
this.#under = under;
|
|
177
|
+
parts.set(this, { link, name, open, openMethod: 'kv.counters.open', under });
|
|
632
178
|
}
|
|
633
|
-
|
|
634
|
-
|
|
179
|
+
under(...owners) {
|
|
180
|
+
const under = [...this.#under, ...owners.map(keyText)];
|
|
181
|
+
return new Counters(this.#link, this.name, this.#open, under);
|
|
635
182
|
}
|
|
636
|
-
/** Adds n, 1 unless given, and gives the new
|
|
637
|
-
add(key, n = 1) {
|
|
638
|
-
return this.#
|
|
183
|
+
/** Adds n, 1 unless given, and gives the new count. */
|
|
184
|
+
async add(key, n = 1) {
|
|
185
|
+
return this.#count('kv.counters.add', { key, n }, 'write');
|
|
639
186
|
}
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
return this.#call('kv.max', key, n);
|
|
187
|
+
async get(key) {
|
|
188
|
+
return this.#count('kv.counters.get', { key }, 'read');
|
|
643
189
|
}
|
|
190
|
+
/** Removes the counter, and says whether it was there. */
|
|
644
191
|
async delete(key) {
|
|
645
|
-
await this.#call('kv.delete', key);
|
|
192
|
+
const body = await this.#call('kv.counters.delete', { key }, 'write');
|
|
193
|
+
return KvFound.decode(body).found === true;
|
|
646
194
|
}
|
|
195
|
+
/** Removes this branch's counters and every branch's under it. */
|
|
647
196
|
async clear() {
|
|
648
|
-
await this.#
|
|
197
|
+
await this.#link.run('write', async (connection) => {
|
|
198
|
+
const handle = await handleOn(connection, methods['kv.counters.open'], this.#open);
|
|
199
|
+
const branch = KvBranch.encode({ handle, under: underField(this.#under) });
|
|
200
|
+
await connection.session.call(methods['kv.counters.clear'], branch);
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
async #count(method, fields, idempotence) {
|
|
204
|
+
const count = KvCount.decode(await this.#call(method, fields, idempotence)).value ?? 0n;
|
|
205
|
+
return numberOf(BigInt(count), this.name);
|
|
206
|
+
}
|
|
207
|
+
#call(method, fields, idempotence) {
|
|
208
|
+
return callOn(this.#link, 'kv.counters.open', this.#open, this.#under, method, fields, idempotence);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
/**
|
|
212
|
+
* What a bucket's open sends, checked before anything leaves; `database` is
|
|
213
|
+
* the handle of the database whose file keeps it.
|
|
214
|
+
*/
|
|
215
|
+
export function bucketOpen(name, options = {}, database) {
|
|
216
|
+
checkName(name, 'bucket');
|
|
217
|
+
if (options.ttl !== undefined && options.idle !== undefined) {
|
|
218
|
+
throw new InvalidError(`kv bucket ${name}: ttl and idle are one or the other`);
|
|
219
|
+
}
|
|
220
|
+
return KvBucketOpen.encode({
|
|
221
|
+
name,
|
|
222
|
+
ttl: options.ttl === undefined ? undefined : ms(options.ttl),
|
|
223
|
+
idle: options.idle === undefined ? undefined : ms(options.idle),
|
|
224
|
+
database,
|
|
225
|
+
encrypted: options.encrypted === true,
|
|
226
|
+
});
|
|
227
|
+
}
|
|
228
|
+
export function countersOpen(name, options = {}) {
|
|
229
|
+
checkName(name, 'counters');
|
|
230
|
+
return KvCountersOpen.encode({
|
|
231
|
+
name,
|
|
232
|
+
ttl: options.ttl === undefined ? undefined : ms(options.ttl),
|
|
233
|
+
flushEvery: options.flushEvery === undefined ? undefined : ms(options.flushEvery),
|
|
234
|
+
});
|
|
235
|
+
}
|
|
236
|
+
/** Calls a method of a handle's branch on the link's connection, the handle opened there first. */
|
|
237
|
+
export function callOn(link, openMethod, open, under, method, fields, idempotence) {
|
|
238
|
+
return link.run(idempotence, async (connection) => {
|
|
239
|
+
const handle = await handleOn(connection, methods[openMethod], open);
|
|
240
|
+
const call = KvCall.encode({ ...fields, handle, under: underField(under) });
|
|
241
|
+
return connection.session.call(methods[method], call);
|
|
242
|
+
});
|
|
243
|
+
}
|
|
244
|
+
/** A branch's owners as a call sends them: none at the root. */
|
|
245
|
+
export function underField(under) {
|
|
246
|
+
return under.length > 0 ? [...under] : undefined;
|
|
247
|
+
}
|
|
248
|
+
export function writeFields(options) {
|
|
249
|
+
return {
|
|
250
|
+
ttl: options?.ttl === undefined ? undefined : ms(options.ttl),
|
|
251
|
+
expiresAt: options?.expiresAt === undefined ? undefined : unixMs(options.expiresAt),
|
|
252
|
+
ifVersion: options?.ifVersion === undefined ? undefined : versionBytes(options.ifVersion),
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
export function entryOf(key, found, values) {
|
|
256
|
+
return {
|
|
257
|
+
key: keyText(key),
|
|
258
|
+
value: values.decode(found.value ?? null),
|
|
259
|
+
version: versionText(found.version),
|
|
260
|
+
expiresAt: dateOf(found.expiresAt),
|
|
261
|
+
};
|
|
262
|
+
}
|
|
263
|
+
/** A version's bytes as text, each byte a code unit, so that any bytes go back as they came. */
|
|
264
|
+
export function versionText(version) {
|
|
265
|
+
return version === undefined ? '' : String.fromCharCode(...version);
|
|
266
|
+
}
|
|
267
|
+
export function versionBytes(version) {
|
|
268
|
+
return Uint8Array.from(version, c => c.charCodeAt(0));
|
|
269
|
+
}
|
|
270
|
+
/** A key or an owner as the server spells it: an integer its decimal text, bytes the text they spell. */
|
|
271
|
+
export function keyText(key) {
|
|
272
|
+
const text = ownerText(key);
|
|
273
|
+
if (typeof text === 'string') {
|
|
274
|
+
return text;
|
|
275
|
+
}
|
|
276
|
+
const spelled = textOf(text);
|
|
277
|
+
if (spelled === undefined) {
|
|
278
|
+
throw new InvalidError('a key of bytes that are not UTF-8, which kv does not keep yet');
|
|
649
279
|
}
|
|
280
|
+
return spelled;
|
|
650
281
|
}
|
|
651
|
-
function numberOf(n,
|
|
282
|
+
function numberOf(n, name) {
|
|
652
283
|
if (n > BigInt(Number.MAX_SAFE_INTEGER) || n < BigInt(Number.MIN_SAFE_INTEGER)) {
|
|
653
|
-
throw new CorruptError(
|
|
284
|
+
throw new CorruptError(`kv counters ${name}: ${n} does not fit a number exactly`);
|
|
654
285
|
}
|
|
655
286
|
return Number(n);
|
|
656
287
|
}
|
|
657
288
|
const utf8 = new TextEncoder();
|
|
658
|
-
|
|
289
|
+
/** The first byte of a row of bytes, the kind of value that wrote it, as the core and every SDK write it. */
|
|
290
|
+
const kinds = { text: 1, bytes: 2, json: 3, float: 4, u64: 5, f32: 6 };
|
|
291
|
+
const kindNames = {
|
|
292
|
+
1: 'text',
|
|
293
|
+
2: 'bytes',
|
|
294
|
+
3: 'JSON',
|
|
295
|
+
4: 'a float',
|
|
296
|
+
5: 'a u64',
|
|
297
|
+
6: 'an f32',
|
|
298
|
+
};
|
|
299
|
+
function tagged(kind, body) {
|
|
300
|
+
const row = new Uint8Array(body.length + 1);
|
|
301
|
+
row[0] = kind;
|
|
302
|
+
row.set(body, 1);
|
|
303
|
+
return row;
|
|
304
|
+
}
|
|
305
|
+
/** The body of a row that `kind` wrote; a row another kind wrote is corrupt here, never read as this one. */
|
|
306
|
+
function bodyOf(raw, kind, wanted) {
|
|
307
|
+
if (!(raw instanceof Uint8Array)) {
|
|
308
|
+
throw new CorruptError(`a stored value is ${describe(raw)} where ${wanted} was written`);
|
|
309
|
+
}
|
|
310
|
+
if (raw[0] !== kind) {
|
|
311
|
+
const written = raw.length === 0 ? 'no bytes' : (kindNames[raw[0]] ?? 'bytes of no kind');
|
|
312
|
+
throw new CorruptError(`${wanted} from a row of ${written}`);
|
|
313
|
+
}
|
|
314
|
+
return raw.subarray(1);
|
|
315
|
+
}
|
|
316
|
+
/** JSON, what a bucket keeps unless its type says otherwise; a row of nothing, a set's member, reads as null. */
|
|
317
|
+
export const jsonValues = {
|
|
659
318
|
encode: value => {
|
|
660
319
|
let text;
|
|
661
320
|
try {
|
|
@@ -667,36 +326,24 @@ const jsonValues = {
|
|
|
667
326
|
if (text === undefined) {
|
|
668
327
|
throw new InvalidError('a value JSON cannot write: undefined, a function or a symbol');
|
|
669
328
|
}
|
|
670
|
-
return utf8.encode(text);
|
|
329
|
+
return tagged(kinds.json, utf8.encode(text));
|
|
671
330
|
},
|
|
672
331
|
decode: raw => {
|
|
673
|
-
if (
|
|
674
|
-
|
|
332
|
+
if (raw === null) {
|
|
333
|
+
return null;
|
|
675
334
|
}
|
|
676
|
-
const
|
|
335
|
+
const json = bodyOf(raw, kinds.json, 'JSON');
|
|
677
336
|
try {
|
|
678
|
-
return JSON.parse(
|
|
337
|
+
return JSON.parse(textOf(json) ?? '');
|
|
679
338
|
}
|
|
680
339
|
catch (err) {
|
|
681
340
|
throw new CorruptError(`a stored value is not JSON any more: ${err.message}`);
|
|
682
341
|
}
|
|
683
342
|
},
|
|
684
343
|
};
|
|
685
|
-
function
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
decode: async (raw) => {
|
|
689
|
-
const checked = await check(schema, await jsonValues.decode(raw));
|
|
690
|
-
if ('issues' in checked) {
|
|
691
|
-
throw new CorruptError(`a stored value does not meet the bucket's schema: ${checked.issues}`);
|
|
692
|
-
}
|
|
693
|
-
return checked.value;
|
|
694
|
-
},
|
|
695
|
-
};
|
|
696
|
-
}
|
|
697
|
-
function valuesOf(kind) {
|
|
698
|
-
switch (kind) {
|
|
699
|
-
case 'json':
|
|
344
|
+
export function valuesOf(type) {
|
|
345
|
+
switch (type) {
|
|
346
|
+
case undefined:
|
|
700
347
|
return jsonValues;
|
|
701
348
|
case 'string':
|
|
702
349
|
return {
|
|
@@ -704,36 +351,35 @@ function valuesOf(kind) {
|
|
|
704
351
|
if (typeof v !== 'string') {
|
|
705
352
|
throw new InvalidError(`a ${typeof v} in a bucket of strings`);
|
|
706
353
|
}
|
|
707
|
-
return utf8.encode(v);
|
|
354
|
+
return tagged(kinds.text, utf8.encode(v));
|
|
708
355
|
},
|
|
709
356
|
decode: raw => {
|
|
710
|
-
|
|
357
|
+
if (raw === null) {
|
|
358
|
+
return '';
|
|
359
|
+
}
|
|
360
|
+
const text = textOf(bodyOf(raw, kinds.text, 'text'));
|
|
711
361
|
if (text === undefined) {
|
|
712
|
-
throw new CorruptError(
|
|
362
|
+
throw new CorruptError('a stored value is text that is not UTF-8');
|
|
713
363
|
}
|
|
714
364
|
return text;
|
|
715
365
|
},
|
|
716
366
|
};
|
|
717
367
|
case 'bytes':
|
|
718
368
|
return {
|
|
369
|
+
keeps: true,
|
|
719
370
|
encode: v => {
|
|
720
371
|
if (!(v instanceof Uint8Array)) {
|
|
721
372
|
throw new InvalidError(`a ${typeof v} in a bucket of bytes`);
|
|
722
373
|
}
|
|
723
|
-
return v;
|
|
724
|
-
},
|
|
725
|
-
decode: raw => {
|
|
726
|
-
if (raw !== null && !(raw instanceof Uint8Array)) {
|
|
727
|
-
throw new CorruptError(`a stored value is ${describe(raw)} where bytes were written`);
|
|
728
|
-
}
|
|
729
|
-
return raw ?? new Uint8Array(0);
|
|
374
|
+
return tagged(kinds.bytes, v);
|
|
730
375
|
},
|
|
376
|
+
decode: raw => (raw === null ? new Uint8Array(0) : bodyOf(raw, kinds.bytes, 'bytes')),
|
|
731
377
|
};
|
|
732
378
|
case 'int':
|
|
733
379
|
return {
|
|
734
380
|
encode: v => {
|
|
735
381
|
if (typeof v !== 'number' || !Number.isSafeInteger(v)) {
|
|
736
|
-
throw new InvalidError(`${String(v)} is not an integer a number holds exactly; open the bucket
|
|
382
|
+
throw new InvalidError(`${String(v)} is not an integer a number holds exactly; open the bucket with type 'bigint'`);
|
|
737
383
|
}
|
|
738
384
|
return BigInt(v);
|
|
739
385
|
},
|
|
@@ -742,7 +388,7 @@ function valuesOf(kind) {
|
|
|
742
388
|
throw new CorruptError(`a stored value is ${describe(raw)} where an integer was written`);
|
|
743
389
|
}
|
|
744
390
|
if (raw > BigInt(Number.MAX_SAFE_INTEGER) || raw < BigInt(Number.MIN_SAFE_INTEGER)) {
|
|
745
|
-
throw new CorruptError(`${raw} does not fit a number exactly; open the bucket
|
|
391
|
+
throw new CorruptError(`${raw} does not fit a number exactly; open the bucket with type 'bigint'`);
|
|
746
392
|
}
|
|
747
393
|
return Number(raw);
|
|
748
394
|
},
|
|
@@ -770,13 +416,14 @@ function valuesOf(kind) {
|
|
|
770
416
|
}
|
|
771
417
|
const bytes = new Uint8Array(8);
|
|
772
418
|
new DataView(bytes.buffer).setFloat64(0, v);
|
|
773
|
-
return bytes;
|
|
419
|
+
return tagged(kinds.float, bytes);
|
|
774
420
|
},
|
|
775
421
|
decode: raw => {
|
|
776
|
-
|
|
777
|
-
|
|
422
|
+
const bits = bodyOf(raw, kinds.float, 'a float');
|
|
423
|
+
if (bits.length !== 8) {
|
|
424
|
+
throw new CorruptError(`a float from ${bits.length} bytes rather than 8`);
|
|
778
425
|
}
|
|
779
|
-
return new DataView(
|
|
426
|
+
return new DataView(bits.buffer, bits.byteOffset, 8).getFloat64(0);
|
|
780
427
|
},
|
|
781
428
|
};
|
|
782
429
|
case 'bool':
|
|
@@ -794,22 +441,8 @@ function valuesOf(kind) {
|
|
|
794
441
|
return raw !== 0n;
|
|
795
442
|
},
|
|
796
443
|
};
|
|
797
|
-
case 'none':
|
|
798
|
-
return {
|
|
799
|
-
encode: v => {
|
|
800
|
-
if (v !== null) {
|
|
801
|
-
throw new InvalidError('a bucket of none keeps no value: set null');
|
|
802
|
-
}
|
|
803
|
-
return null;
|
|
804
|
-
},
|
|
805
|
-
decode: raw => {
|
|
806
|
-
if (raw !== null) {
|
|
807
|
-
throw new CorruptError(`a stored value is ${describe(raw)} in a bucket that keeps none`);
|
|
808
|
-
}
|
|
809
|
-
return null;
|
|
810
|
-
},
|
|
811
|
-
};
|
|
812
444
|
}
|
|
445
|
+
throw new InvalidError(`a bucket's type is string, bytes, int, bigint, float or bool, not ${String(type)}`);
|
|
813
446
|
}
|
|
814
447
|
function describe(raw) {
|
|
815
448
|
if (raw === null) {
|