@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/tx.js
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
// A transaction across the wire, which never holds the writer while the host
|
|
2
|
+
// awaits: a read goes at once and is kept with what it found; a write waits,
|
|
3
|
+
// and when the function returns the writes commit in one kv.tx, after a check
|
|
4
|
+
// that every key it read is still as it read it. A check that fails runs the
|
|
5
|
+
// function again.
|
|
6
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
7
|
+
import { channelParts, txChannel } from './channels.js';
|
|
8
|
+
import { ConflictError, InvalidError } from './errors.js';
|
|
9
|
+
import { handleOn } from './handles.js';
|
|
10
|
+
import { commitJobs, queueParts, StoreTxQueue } from './jobs.js';
|
|
11
|
+
import { entryOf, keyText, partsOf, underField, writeFields, } from './kv.js';
|
|
12
|
+
import { ms, unixMs } from './time.js';
|
|
13
|
+
import { KvCall, KvEntry, KvTx, methods } from './wire/protocol.js';
|
|
14
|
+
/** How many times tx runs its function before a key it read that keeps changing is ConflictError. */
|
|
15
|
+
const runs = 5;
|
|
16
|
+
// Whether the caller runs inside a transaction's function, as its async
|
|
17
|
+
// context carries it: a lock's hold refuses to wait there.
|
|
18
|
+
const inside = new AsyncLocalStorage();
|
|
19
|
+
/** Whether the caller runs inside the function of a store's transaction. */
|
|
20
|
+
export function insideStoreTx() {
|
|
21
|
+
return inside.getStore() === true;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Runs fn as one transaction and gives back what it returns: its writes all
|
|
25
|
+
* commit or none do. When a key fn read changed before the commit, fn runs
|
|
26
|
+
* again, five times at most, so it does nothing else that must happen once.
|
|
27
|
+
*/
|
|
28
|
+
export async function runTx(link, fn) {
|
|
29
|
+
for (let run = 1;; run++) {
|
|
30
|
+
const tx = new Tx(link);
|
|
31
|
+
const returned = await inside.run(true, () => fn(tx));
|
|
32
|
+
try {
|
|
33
|
+
await tx.commit();
|
|
34
|
+
return returned;
|
|
35
|
+
}
|
|
36
|
+
catch (err) {
|
|
37
|
+
const changed = err instanceof ConflictError && err.what.check !== undefined;
|
|
38
|
+
if (run >= runs || !changed) {
|
|
39
|
+
throw err;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
const absent = { found: false };
|
|
45
|
+
/** The calls of a transaction, each through `tx.with(handle)`. */
|
|
46
|
+
export class Tx {
|
|
47
|
+
#link;
|
|
48
|
+
#reads = new Map();
|
|
49
|
+
/** what the transaction wrote to a key, so that a read after it answers it */
|
|
50
|
+
#written = new Map();
|
|
51
|
+
#cleared = [];
|
|
52
|
+
#ops = [];
|
|
53
|
+
/** a queue's writes: a transaction takes the handles of one file, kv.db's or jobs.db's */
|
|
54
|
+
#jobs = [];
|
|
55
|
+
/** messages published inside, handed over once the commit answered */
|
|
56
|
+
#published = [];
|
|
57
|
+
#file;
|
|
58
|
+
#done = false;
|
|
59
|
+
constructor(link) {
|
|
60
|
+
this.#link = link;
|
|
61
|
+
}
|
|
62
|
+
with(handle) {
|
|
63
|
+
const channel = channelParts(handle);
|
|
64
|
+
if (channel !== undefined) {
|
|
65
|
+
// a store's transaction commits in one kv.tx, which carries no message:
|
|
66
|
+
// its messages leave once its commit answered
|
|
67
|
+
return txChannel(channel.name, channel.branch, async (body) => {
|
|
68
|
+
this.#published.push(body);
|
|
69
|
+
});
|
|
70
|
+
}
|
|
71
|
+
const queue = queueParts(handle);
|
|
72
|
+
if (queue !== undefined) {
|
|
73
|
+
const what = `jobs queue ${queue.name}`;
|
|
74
|
+
this.#takes(queue.source.link, queue.source.home?.describe, 'jobs.db', what);
|
|
75
|
+
return new StoreTxQueue(queue, op => {
|
|
76
|
+
this.#open();
|
|
77
|
+
this.#jobs.push(op);
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
const parts = partsOf(handle);
|
|
81
|
+
if (parts === undefined) {
|
|
82
|
+
throw new InvalidError('tx.with takes a bucket, counters or a queue');
|
|
83
|
+
}
|
|
84
|
+
this.#takes(parts.link, parts.home?.describe, 'kv.db', `kv ${parts.name}`);
|
|
85
|
+
if (parts.values === undefined) {
|
|
86
|
+
return new TxCounters(this, parts);
|
|
87
|
+
}
|
|
88
|
+
return new TxBucket(this, parts, parts.values);
|
|
89
|
+
}
|
|
90
|
+
/** What the key holds as this transaction sees it: its own writes over what the store held. */
|
|
91
|
+
async read(parts, key) {
|
|
92
|
+
this.#open();
|
|
93
|
+
const text = keyText(key);
|
|
94
|
+
const own = this.#own(parts, text);
|
|
95
|
+
if (own !== undefined) {
|
|
96
|
+
return own;
|
|
97
|
+
}
|
|
98
|
+
const place = placeOf(parts, text);
|
|
99
|
+
let reading = this.#reads.get(place);
|
|
100
|
+
if (reading === undefined) {
|
|
101
|
+
reading = this.#fetch(parts, text);
|
|
102
|
+
// a read the function never awaited still fails the commit, which awaits it
|
|
103
|
+
reading.catch(() => { });
|
|
104
|
+
this.#reads.set(place, reading);
|
|
105
|
+
}
|
|
106
|
+
return (await reading).found;
|
|
107
|
+
}
|
|
108
|
+
/** Keeps a write for the commit; found is what a read of its key answers after it. */
|
|
109
|
+
write(method, parts, fields, found) {
|
|
110
|
+
this.#open();
|
|
111
|
+
this.#ops.push({ method, parts, fields });
|
|
112
|
+
if (found !== undefined && fields.key !== undefined) {
|
|
113
|
+
this.#written.set(placeOf(parts, keyText(fields.key)), { found, at: this.#ops.length });
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
clear(parts) {
|
|
117
|
+
this.write('kv.clear', parts, {});
|
|
118
|
+
this.#cleared.push({ handle: handleOf(parts), under: parts.under, at: this.#ops.length });
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* Refuses a handle of another store, one kept in a database's file, and
|
|
122
|
+
* one of the store's other file: a bucket and a queue of the store are two
|
|
123
|
+
* files, and no write is atomic across two.
|
|
124
|
+
*/
|
|
125
|
+
#takes(link, home, file, what) {
|
|
126
|
+
if (link !== this.#link) {
|
|
127
|
+
throw new InvalidError(`${what}: a handle of another store, in a transaction of this one`);
|
|
128
|
+
}
|
|
129
|
+
if (home !== undefined) {
|
|
130
|
+
throw new InvalidError(`${home}: ${what}: kept in the database's file, outside this transaction of the store: take it in with db.tx`);
|
|
131
|
+
}
|
|
132
|
+
if (this.#file !== undefined && this.#file !== file) {
|
|
133
|
+
throw new InvalidError(`${what}: kept in ${file}, outside this transaction of ${this.#file}: open both from a database to commit them together`);
|
|
134
|
+
}
|
|
135
|
+
this.#file = file;
|
|
136
|
+
}
|
|
137
|
+
/** Sends the writes in one kv.tx, after a check of each key read: still at its version, or still absent. */
|
|
138
|
+
/** Commits the writes, then hands over the messages published inside. */
|
|
139
|
+
async commit() {
|
|
140
|
+
this.#done = true;
|
|
141
|
+
await this.#commitWrites();
|
|
142
|
+
for (const body of this.#published) {
|
|
143
|
+
await this.#link.run('write', connection => connection.session.call(methods['channels.publish'], body));
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
async #commitWrites() {
|
|
147
|
+
if (this.#jobs.length > 0) {
|
|
148
|
+
return commitJobs(this.#link, this.#jobs);
|
|
149
|
+
}
|
|
150
|
+
const reads = await Promise.all(this.#reads.values());
|
|
151
|
+
if (reads.length === 0 && this.#ops.length === 0) {
|
|
152
|
+
return;
|
|
153
|
+
}
|
|
154
|
+
await this.#link.run(this.#ops.length > 0 ? 'write' : 'read', async (connection) => {
|
|
155
|
+
const handle = (parts) => handleOn(connection, methods[parts.openMethod], parts.open);
|
|
156
|
+
const checks = [];
|
|
157
|
+
for (const read of reads) {
|
|
158
|
+
const version = read.found.found === true ? read.found.version : undefined;
|
|
159
|
+
checks.push({
|
|
160
|
+
handle: await handle(read.parts),
|
|
161
|
+
under: underField(read.parts.under),
|
|
162
|
+
key: read.key,
|
|
163
|
+
version,
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
const writes = [];
|
|
167
|
+
for (const op of this.#ops) {
|
|
168
|
+
const call = {
|
|
169
|
+
...op.fields,
|
|
170
|
+
handle: await handle(op.parts),
|
|
171
|
+
under: underField(op.parts.under),
|
|
172
|
+
};
|
|
173
|
+
writes.push({ method: methods[op.method], call });
|
|
174
|
+
}
|
|
175
|
+
await connection.session.call(methods['kv.tx'], KvTx.encode({ checks, writes }));
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
#open() {
|
|
179
|
+
if (this.#done) {
|
|
180
|
+
throw new InvalidError('a transaction takes its calls while its function runs, before it commits');
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
// the transaction's own word on a key: a write of it, or a clear of a branch above it, whichever came last
|
|
184
|
+
#own(parts, key) {
|
|
185
|
+
const written = this.#written.get(placeOf(parts, key));
|
|
186
|
+
let cleared = 0;
|
|
187
|
+
for (const clear of this.#cleared) {
|
|
188
|
+
if (clear.handle === handleOf(parts) && startsWith(parts.under, clear.under)) {
|
|
189
|
+
cleared = Math.max(cleared, clear.at);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
if (written !== undefined && written.at > cleared) {
|
|
193
|
+
return written.found;
|
|
194
|
+
}
|
|
195
|
+
return cleared > 0 ? absent : undefined;
|
|
196
|
+
}
|
|
197
|
+
async #fetch(parts, key) {
|
|
198
|
+
const found = await this.#link.run('read', async (connection) => {
|
|
199
|
+
const handle = await handleOn(connection, methods[parts.openMethod], parts.open);
|
|
200
|
+
const call = KvCall.encode({ handle, under: underField(parts.under), key });
|
|
201
|
+
return KvEntry.decode(await connection.session.call(methods['kv.get'], call));
|
|
202
|
+
});
|
|
203
|
+
return { parts, key, found };
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
/** A bucket's calls inside a transaction: reads answer at once, writes wait for its commit. */
|
|
207
|
+
export class TxBucket {
|
|
208
|
+
#tx;
|
|
209
|
+
#parts;
|
|
210
|
+
#values;
|
|
211
|
+
constructor(tx, parts, values) {
|
|
212
|
+
this.#tx = tx;
|
|
213
|
+
this.#parts = parts;
|
|
214
|
+
this.#values = values;
|
|
215
|
+
}
|
|
216
|
+
under(...owners) {
|
|
217
|
+
const parts = { ...this.#parts, under: [...this.#parts.under, ...owners.map(keyText)] };
|
|
218
|
+
return new TxBucket(this.#tx, parts, this.#values);
|
|
219
|
+
}
|
|
220
|
+
async get(key) {
|
|
221
|
+
return (await this.entry(key))?.value;
|
|
222
|
+
}
|
|
223
|
+
async entry(key) {
|
|
224
|
+
const found = await this.#tx.read(this.#parts, key);
|
|
225
|
+
return found.found === true ? entryOf(key, found, this.#values) : undefined;
|
|
226
|
+
}
|
|
227
|
+
async has(key) {
|
|
228
|
+
return (await this.#tx.read(this.#parts, key)).found === true;
|
|
229
|
+
}
|
|
230
|
+
async set(key, value, options) {
|
|
231
|
+
const raw = this.#values.encode(value);
|
|
232
|
+
this.#tx.write('kv.set', this.#parts, { key, value: raw, ...writeFields(options) }, { found: true, value: raw });
|
|
233
|
+
}
|
|
234
|
+
/** Writes the value only where no live key is, and says whether it will. */
|
|
235
|
+
async create(key, value, options) {
|
|
236
|
+
if ((await this.#tx.read(this.#parts, key)).found === true) {
|
|
237
|
+
return false;
|
|
238
|
+
}
|
|
239
|
+
const raw = this.#values.encode(value);
|
|
240
|
+
this.#tx.write('kv.create', this.#parts, { key, value: raw, ...writeFields(options) }, { found: true, value: raw });
|
|
241
|
+
return true;
|
|
242
|
+
}
|
|
243
|
+
async add(key, options) {
|
|
244
|
+
if ((await this.#tx.read(this.#parts, key)).found === true) {
|
|
245
|
+
return false;
|
|
246
|
+
}
|
|
247
|
+
this.#tx.write('kv.create', this.#parts, { key, ...writeFields(options) }, { found: true, value: null });
|
|
248
|
+
return true;
|
|
249
|
+
}
|
|
250
|
+
async take(key, options) {
|
|
251
|
+
const found = await this.#remove('kv.take', key, options);
|
|
252
|
+
return found.found === true ? this.#values.decode(found.value ?? null) : undefined;
|
|
253
|
+
}
|
|
254
|
+
async delete(key, options) {
|
|
255
|
+
return (await this.#remove('kv.delete', key, options)).found === true;
|
|
256
|
+
}
|
|
257
|
+
async expire(key, when, options) {
|
|
258
|
+
const found = await this.#tx.read(this.#parts, key);
|
|
259
|
+
if (found.found !== true && options?.ifVersion === undefined) {
|
|
260
|
+
return false;
|
|
261
|
+
}
|
|
262
|
+
const expiry = when instanceof Date ? { expiresAt: when } : { ttl: when };
|
|
263
|
+
const expiresAt = when instanceof Date ? unixMs(when) : Date.now() + ms(when);
|
|
264
|
+
const fields = { key, ...writeFields({ ...options, ...expiry }) };
|
|
265
|
+
this.#tx.write('kv.expire', this.#parts, fields, found.found === true ? { ...found, expiresAt } : undefined);
|
|
266
|
+
return found.found === true;
|
|
267
|
+
}
|
|
268
|
+
/** Removes this branch's keys and every branch's under it, with the commit. */
|
|
269
|
+
async clear() {
|
|
270
|
+
this.#tx.clear(this.#parts);
|
|
271
|
+
}
|
|
272
|
+
// a take or a delete: what the key held, and its removal, sent when the
|
|
273
|
+
// key was there or when the caller named the version it must be at
|
|
274
|
+
async #remove(method, key, options) {
|
|
275
|
+
const found = await this.#tx.read(this.#parts, key);
|
|
276
|
+
if (found.found === true || options?.ifVersion !== undefined) {
|
|
277
|
+
this.#tx.write(method, this.#parts, { key, ...writeFields(options) }, absent);
|
|
278
|
+
}
|
|
279
|
+
return found;
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
/** Counters inside a transaction: an add commits with its writes. */
|
|
283
|
+
export class TxCounters {
|
|
284
|
+
#tx;
|
|
285
|
+
#parts;
|
|
286
|
+
constructor(tx, parts) {
|
|
287
|
+
this.#tx = tx;
|
|
288
|
+
this.#parts = parts;
|
|
289
|
+
}
|
|
290
|
+
under(...owners) {
|
|
291
|
+
return new TxCounters(this.#tx, {
|
|
292
|
+
...this.#parts,
|
|
293
|
+
under: [...this.#parts.under, ...owners.map(keyText)],
|
|
294
|
+
});
|
|
295
|
+
}
|
|
296
|
+
/** Adds n, 1 unless given, with the commit; the count is known once it has. */
|
|
297
|
+
async add(key, n = 1) {
|
|
298
|
+
this.#tx.write('kv.counters.add', this.#parts, { key, n });
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
/** A key's place as one text, its handle and owners included, each kept apart. */
|
|
302
|
+
function placeOf(parts, key) {
|
|
303
|
+
return JSON.stringify([handleOf(parts), parts.under, key]);
|
|
304
|
+
}
|
|
305
|
+
/** A handle's place as text: its open's bytes, which a store's own handle has. */
|
|
306
|
+
function handleOf(parts) {
|
|
307
|
+
if (typeof parts.open === 'function') {
|
|
308
|
+
throw new InvalidError(`kv ${parts.name}: a handle of a database, in a transaction of kv.db`);
|
|
309
|
+
}
|
|
310
|
+
return `${parts.openMethod} ${Buffer.from(parts.open).toString('base64')}`;
|
|
311
|
+
}
|
|
312
|
+
function startsWith(under, branch) {
|
|
313
|
+
return branch.length <= under.length && branch.every((owner, i) => under[i] === owner);
|
|
314
|
+
}
|
package/dist/wire/codec.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ import { Reader, Writer } from './msgpack.ts';
|
|
|
6
6
|
export interface Codec<Out, In = Out> {
|
|
7
7
|
/** what the value is, which the tests that read vectors go by */
|
|
8
8
|
readonly kind: string;
|
|
9
|
-
/** a list's items, or what a nullable holds when it holds something */
|
|
9
|
+
/** a list's items, a map's values, or what a nullable holds when it holds something */
|
|
10
10
|
readonly item?: Codec<unknown, never>;
|
|
11
11
|
write(w: Writer, value: In): void;
|
|
12
12
|
read(r: Reader): Out;
|
|
@@ -44,6 +44,10 @@ export type SqlArg = SqlValue | boolean | Date | undefined;
|
|
|
44
44
|
export declare const sqlValue: Codec<SqlValue | boolean, SqlArg>;
|
|
45
45
|
/** Names mapped to text, in the byte order of their UTF-8, which is their code points' order. */
|
|
46
46
|
export declare function names<V, In = V>(value: Codec<V, In>): Codec<Record<string, V>, Record<string, In>>;
|
|
47
|
+
/** Writes a map of names in the byte order of their UTF-8, each value as `item` writes it. */
|
|
48
|
+
export declare function writeNames<In>(w: Writer, named: Record<string, In>, item: (w: Writer, value: In) => void): void;
|
|
49
|
+
/** Reads a map of names, a name twice refused, each value as `item` reads it. */
|
|
50
|
+
export declare function readNames<V>(r: Reader, item: (r: Reader) => V): Record<string, V>;
|
|
47
51
|
/** Orders strings as their UTF-8 bytes are ordered, which UTF-16's code units do not. */
|
|
48
52
|
export declare function byCodePoint(a: string, b: string): number;
|
|
49
53
|
/** A column of int64s as a bin, eight bytes little-endian each. */
|
|
@@ -61,30 +65,42 @@ type OutOf<C> = C extends Codec<infer O, never> ? O : never;
|
|
|
61
65
|
type InOf<C> = C extends Codec<unknown, infer I> ? I : never;
|
|
62
66
|
/** What a message reads: every field it holds, a field it lacks undefined. */
|
|
63
67
|
export type Read<F extends Fields> = {
|
|
64
|
-
[K in keyof F]?: OutOf<F[K][1]
|
|
68
|
+
[K in keyof F]?: OutOf<F[K][1]> | undefined;
|
|
65
69
|
};
|
|
66
70
|
/** What a message is written from: a field undefined is left out. */
|
|
67
71
|
export type Written<F extends Fields> = {
|
|
68
72
|
[K in keyof F]?: InOf<F[K][1]> | undefined;
|
|
69
73
|
};
|
|
74
|
+
/**
|
|
75
|
+
* A message's reader and writer written out a field at a time, as
|
|
76
|
+
* crates/protocol writes every message of the schema: what its table of
|
|
77
|
+
* fields says, without walking the table.
|
|
78
|
+
*/
|
|
79
|
+
export interface Made<F extends Fields> {
|
|
80
|
+
write(w: Writer, value: Written<F>): void;
|
|
81
|
+
read(r: Reader): Read<F>;
|
|
82
|
+
}
|
|
70
83
|
/**
|
|
71
84
|
* A message: a map of the fields its declaration names, keys ascending. A
|
|
72
85
|
* field is written when its value is not undefined, so an absent field and a
|
|
73
86
|
* zero one stay what the caller said; a key the declaration lacks is skipped
|
|
74
|
-
* as it reads, well formed and within bounds.
|
|
87
|
+
* as it reads, well formed and within bounds. A message the schema declares
|
|
88
|
+
* is read and written by its own code; one declared by hand, by its table.
|
|
75
89
|
*/
|
|
76
90
|
export declare class Message<F extends Fields> implements Codec<Read<F>, Written<F>> {
|
|
77
91
|
#private;
|
|
78
92
|
readonly kind = "message";
|
|
79
93
|
readonly name: string;
|
|
80
94
|
readonly fields: F;
|
|
81
|
-
|
|
82
|
-
write(w: Writer, value: Written<F>)
|
|
95
|
+
/** Writes the message at the writer's end; a function of its own, to be passed as one. */
|
|
96
|
+
readonly write: (w: Writer, value: Written<F>) => void;
|
|
97
|
+
/** Reads the message the reader is at; a function of its own, to be passed as one. */
|
|
98
|
+
readonly read: (r: Reader) => Read<F>;
|
|
99
|
+
constructor(name: string, fields: F, made?: Made<F>);
|
|
83
100
|
/** The message's bytes. */
|
|
84
101
|
encode(value: Written<F>): Uint8Array;
|
|
85
102
|
/** Reads a body that is this message and nothing after it. */
|
|
86
103
|
decode(body: Uint8Array): Read<F>;
|
|
87
|
-
read(r: Reader): Read<F>;
|
|
88
104
|
}
|
|
89
|
-
export declare function message<const F extends Fields>(name: string, fields: F): Message<F>;
|
|
105
|
+
export declare function message<const F extends Fields>(name: string, fields: F, made?: Made<NoInfer<F>>): Message<F>;
|
|
90
106
|
export {};
|
package/dist/wire/codec.js
CHANGED
|
@@ -40,7 +40,7 @@ export const str = {
|
|
|
40
40
|
export const bin = {
|
|
41
41
|
kind: 'bin',
|
|
42
42
|
write: (w, v) => w.bin(v),
|
|
43
|
-
read: r => r.
|
|
43
|
+
read: r => r.bytes(),
|
|
44
44
|
};
|
|
45
45
|
const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
|
|
46
46
|
/** The text bytes spell, or undefined when they are not UTF-8. */
|
|
@@ -59,7 +59,7 @@ export function textOf(bytes) {
|
|
|
59
59
|
export const text = {
|
|
60
60
|
kind: 'text',
|
|
61
61
|
write: (w, v) => writeText(w, v),
|
|
62
|
-
read: r => (r.type() === 'bin' ? r.
|
|
62
|
+
read: r => (r.type() === 'bin' ? r.bytes() : r.str()),
|
|
63
63
|
};
|
|
64
64
|
function writeText(w, v) {
|
|
65
65
|
if (typeof v === 'string') {
|
|
@@ -88,7 +88,7 @@ export const key = {
|
|
|
88
88
|
read: r => {
|
|
89
89
|
switch (r.type()) {
|
|
90
90
|
case 'bin':
|
|
91
|
-
return r.
|
|
91
|
+
return r.bytes();
|
|
92
92
|
case 'int':
|
|
93
93
|
return String(r.int64());
|
|
94
94
|
}
|
|
@@ -112,7 +112,7 @@ export const kvValue = {
|
|
|
112
112
|
if (r.nil()) {
|
|
113
113
|
return null;
|
|
114
114
|
}
|
|
115
|
-
return r.type() === 'bin' ? r.
|
|
115
|
+
return r.type() === 'bin' ? r.bytes() : r.int64();
|
|
116
116
|
},
|
|
117
117
|
};
|
|
118
118
|
export const sqlValue = {
|
|
@@ -125,10 +125,8 @@ export const sqlValue = {
|
|
|
125
125
|
return null;
|
|
126
126
|
case 'bool':
|
|
127
127
|
return r.bool();
|
|
128
|
-
case 'int':
|
|
129
|
-
|
|
130
|
-
return n >= Number.MIN_SAFE_INTEGER && n <= Number.MAX_SAFE_INTEGER ? Number(n) : n;
|
|
131
|
-
}
|
|
128
|
+
case 'int':
|
|
129
|
+
return r.integer();
|
|
132
130
|
case 'float':
|
|
133
131
|
return r.float();
|
|
134
132
|
case 'bin':
|
|
@@ -176,23 +174,28 @@ function writeSQL(w, v) {
|
|
|
176
174
|
export function names(value) {
|
|
177
175
|
return {
|
|
178
176
|
kind: value.kind === 'sql value' ? 'sql names' : 'names',
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
for (const name of sorted) {
|
|
183
|
-
w.str(name);
|
|
184
|
-
value.write(w, v[name]);
|
|
185
|
-
}
|
|
186
|
-
},
|
|
187
|
-
read: r => {
|
|
188
|
-
const named = {};
|
|
189
|
-
r.names(name => {
|
|
190
|
-
named[name] = value.read(r);
|
|
191
|
-
});
|
|
192
|
-
return named;
|
|
193
|
-
},
|
|
177
|
+
item: value,
|
|
178
|
+
write: (w, v) => writeNames(w, v, value.write),
|
|
179
|
+
read: r => readNames(r, value.read),
|
|
194
180
|
};
|
|
195
181
|
}
|
|
182
|
+
/** Writes a map of names in the byte order of their UTF-8, each value as `item` writes it. */
|
|
183
|
+
export function writeNames(w, named, item) {
|
|
184
|
+
const sorted = Object.keys(named).sort(byCodePoint);
|
|
185
|
+
w.map(sorted.length);
|
|
186
|
+
for (const name of sorted) {
|
|
187
|
+
w.str(name);
|
|
188
|
+
item(w, named[name]);
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
/** Reads a map of names, a name twice refused, each value as `item` reads it. */
|
|
192
|
+
export function readNames(r, item) {
|
|
193
|
+
const named = {};
|
|
194
|
+
r.names(name => {
|
|
195
|
+
named[name] = item(r);
|
|
196
|
+
});
|
|
197
|
+
return named;
|
|
198
|
+
}
|
|
196
199
|
/** Orders strings as their UTF-8 bytes are ordered, which UTF-16's code units do not. */
|
|
197
200
|
export function byCodePoint(a, b) {
|
|
198
201
|
const x = a[Symbol.iterator]();
|
|
@@ -313,15 +316,20 @@ export function nullable(value) {
|
|
|
313
316
|
* A message: a map of the fields its declaration names, keys ascending. A
|
|
314
317
|
* field is written when its value is not undefined, so an absent field and a
|
|
315
318
|
* zero one stay what the caller said; a key the declaration lacks is skipped
|
|
316
|
-
* as it reads, well formed and within bounds.
|
|
319
|
+
* as it reads, well formed and within bounds. A message the schema declares
|
|
320
|
+
* is read and written by its own code; one declared by hand, by its table.
|
|
317
321
|
*/
|
|
318
322
|
export class Message {
|
|
319
323
|
kind = 'message';
|
|
320
324
|
name;
|
|
321
325
|
fields;
|
|
326
|
+
/** Writes the message at the writer's end; a function of its own, to be passed as one. */
|
|
327
|
+
write;
|
|
328
|
+
/** Reads the message the reader is at; a function of its own, to be passed as one. */
|
|
329
|
+
read;
|
|
322
330
|
#order;
|
|
323
331
|
#byKey = [];
|
|
324
|
-
constructor(name, fields) {
|
|
332
|
+
constructor(name, fields, made) {
|
|
325
333
|
this.name = name;
|
|
326
334
|
this.fields = fields;
|
|
327
335
|
this.#order = Object.entries(fields)
|
|
@@ -334,23 +342,36 @@ export class Message {
|
|
|
334
342
|
for (const f of this.#order) {
|
|
335
343
|
this.#byKey[f.key] = f;
|
|
336
344
|
}
|
|
345
|
+
this.write = made?.write ?? ((w, value) => this.#write(w, value));
|
|
346
|
+
this.read = made?.read ?? (r => this.#read(r));
|
|
337
347
|
}
|
|
338
|
-
write(w, value) {
|
|
348
|
+
#write(w, value) {
|
|
339
349
|
const held = value;
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
350
|
+
const order = this.#order;
|
|
351
|
+
if (order.length > 15) {
|
|
352
|
+
let n = 0;
|
|
353
|
+
for (const f of order) {
|
|
354
|
+
if (held[f.name] !== undefined) {
|
|
355
|
+
n++;
|
|
356
|
+
}
|
|
344
357
|
}
|
|
358
|
+
w.map(n);
|
|
345
359
|
}
|
|
346
|
-
|
|
347
|
-
|
|
360
|
+
// up to 15 fields are counted as they are written, into the byte kept for the count
|
|
361
|
+
const count = order.length > 15 ? -1 : w.reserve(1);
|
|
362
|
+
let n = 0;
|
|
363
|
+
for (let i = 0; i < order.length; i++) {
|
|
364
|
+
const f = order[i];
|
|
348
365
|
const v = held[f.name];
|
|
349
366
|
if (v !== undefined) {
|
|
367
|
+
n++;
|
|
350
368
|
w.uint(f.key);
|
|
351
369
|
f.codec.write(w, v);
|
|
352
370
|
}
|
|
353
371
|
}
|
|
372
|
+
if (count >= 0) {
|
|
373
|
+
w.mapAt(count, n);
|
|
374
|
+
}
|
|
354
375
|
}
|
|
355
376
|
/** The message's bytes. */
|
|
356
377
|
encode(value) {
|
|
@@ -365,7 +386,7 @@ export class Message {
|
|
|
365
386
|
r.end();
|
|
366
387
|
return value;
|
|
367
388
|
}
|
|
368
|
-
read(r) {
|
|
389
|
+
#read(r) {
|
|
369
390
|
const read = {};
|
|
370
391
|
r.fields(key => {
|
|
371
392
|
const f = this.#byKey[key];
|
|
@@ -378,6 +399,6 @@ export class Message {
|
|
|
378
399
|
return read;
|
|
379
400
|
}
|
|
380
401
|
}
|
|
381
|
-
export function message(name, fields) {
|
|
382
|
-
return new Message(name, fields);
|
|
402
|
+
export function message(name, fields, made) {
|
|
403
|
+
return new Message(name, fields, made);
|
|
383
404
|
}
|
package/dist/wire/frame.d.ts
CHANGED
|
@@ -27,6 +27,8 @@ export interface Header {
|
|
|
27
27
|
export declare function kindName(kind: number): string;
|
|
28
28
|
/** Reads a header from its twelve bytes without checking it. */
|
|
29
29
|
export declare function parseHeader(bytes: Uint8Array, at?: number): Header;
|
|
30
|
+
/** Writes a header where its twelve bytes were kept, once its body's length is known. */
|
|
31
|
+
export declare function putHeader(bytes: Uint8Array, at: number, kind: number, flags: number, method: number, stream: number, length: number): void;
|
|
30
32
|
/**
|
|
31
33
|
* Refuses a header that breaks the protocol: an unknown kind, a flag its kind
|
|
32
34
|
* does not define, ERROR without END, a method outside a REQUEST or none in
|
package/dist/wire/frame.js
CHANGED
|
@@ -36,15 +36,37 @@ export function kindName(kind) {
|
|
|
36
36
|
}
|
|
37
37
|
/** Reads a header from its twelve bytes without checking it. */
|
|
38
38
|
export function parseHeader(bytes, at = 0) {
|
|
39
|
-
|
|
39
|
+
if (bytes.length - at < headerSize) {
|
|
40
|
+
throw new ProtocolError(`a header of ${bytes.length - at} bytes`);
|
|
41
|
+
}
|
|
40
42
|
return {
|
|
41
|
-
length:
|
|
42
|
-
kind:
|
|
43
|
-
flags:
|
|
44
|
-
method:
|
|
45
|
-
stream:
|
|
43
|
+
length: uint32At(bytes, at),
|
|
44
|
+
kind: bytes[at + 4],
|
|
45
|
+
flags: bytes[at + 5],
|
|
46
|
+
method: bytes[at + 6] | (bytes[at + 7] << 8),
|
|
47
|
+
stream: uint32At(bytes, at + 8),
|
|
46
48
|
};
|
|
47
49
|
}
|
|
50
|
+
/** Writes a header where its twelve bytes were kept, once its body's length is known. */
|
|
51
|
+
export function putHeader(bytes, at, kind, flags, method, stream, length) {
|
|
52
|
+
putUint32(bytes, at, length);
|
|
53
|
+
bytes[at + 4] = kind;
|
|
54
|
+
bytes[at + 5] = flags;
|
|
55
|
+
bytes[at + 6] = method;
|
|
56
|
+
bytes[at + 7] = method >>> 8;
|
|
57
|
+
putUint32(bytes, at + 8, stream);
|
|
58
|
+
}
|
|
59
|
+
// Four bytes, the low one first. Not through a DataView: asking a small array
|
|
60
|
+
// for its buffer makes the engine move it to one, for every frame.
|
|
61
|
+
function uint32At(bytes, at) {
|
|
62
|
+
return ((bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16) | (bytes[at + 3] << 24)) >>> 0);
|
|
63
|
+
}
|
|
64
|
+
function putUint32(bytes, at, n) {
|
|
65
|
+
bytes[at] = n;
|
|
66
|
+
bytes[at + 1] = n >>> 8;
|
|
67
|
+
bytes[at + 2] = n >>> 16;
|
|
68
|
+
bytes[at + 3] = n >>> 24;
|
|
69
|
+
}
|
|
48
70
|
/**
|
|
49
71
|
* Refuses a header that breaks the protocol: an unknown kind, a flag its kind
|
|
50
72
|
* does not define, ERROR without END, a method outside a REQUEST or none in
|
|
@@ -82,21 +104,16 @@ export function checkHeader(h, maxBody) {
|
|
|
82
104
|
/** Writes a frame: its header, the body's length its own, then the body. */
|
|
83
105
|
export function frame(kind, flags, method, stream, body) {
|
|
84
106
|
const bytes = new Uint8Array(headerSize + body.length);
|
|
85
|
-
|
|
86
|
-
view.setUint32(0, body.length, true);
|
|
87
|
-
view.setUint8(4, kind);
|
|
88
|
-
view.setUint8(5, flags);
|
|
89
|
-
view.setUint16(6, method, true);
|
|
90
|
-
view.setUint32(8, stream, true);
|
|
107
|
+
putHeader(bytes, 0, kind, flags, method, stream, body.length);
|
|
91
108
|
bytes.set(body, headerSize);
|
|
92
109
|
return bytes;
|
|
93
110
|
}
|
|
94
111
|
/** A CREDIT granting n bytes on a stream. */
|
|
95
112
|
export function credit(stream, n) {
|
|
96
113
|
const body = new Uint8Array(4);
|
|
97
|
-
|
|
114
|
+
putUint32(body, 0, n);
|
|
98
115
|
return frame(Kind.credit, 0, 0, stream, body);
|
|
99
116
|
}
|
|
100
117
|
export function granted(body) {
|
|
101
|
-
return
|
|
118
|
+
return uint32At(body, 0);
|
|
102
119
|
}
|