@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/sql.js
ADDED
|
@@ -0,0 +1,342 @@
|
|
|
1
|
+
// The application's own SQLite databases, sql/<name>.db, as Go's sqldb keeps
|
|
2
|
+
// them: the application writes every query, the server owns the file, its
|
|
3
|
+
// connections and its migrations, which the first open applies and every
|
|
4
|
+
// later one checks.
|
|
5
|
+
import { readdir, readFile } from 'node:fs/promises';
|
|
6
|
+
import { join } from 'node:path';
|
|
7
|
+
import { InvalidError } from './errors.js';
|
|
8
|
+
import { checkName, handleOn, settle } from './handles.js';
|
|
9
|
+
import { watch } from './session.js';
|
|
10
|
+
import { methods, SqlColumns, SqlDatabase, SqlDone, SqlResults, SqlRow, SqlStatement, SqlStatements, } from './wire/messages.js';
|
|
11
|
+
function statementOf(given) {
|
|
12
|
+
const [first, ...rest] = given;
|
|
13
|
+
if (typeof first !== 'string') {
|
|
14
|
+
return { sql: first.join('?'), args: rest };
|
|
15
|
+
}
|
|
16
|
+
const only = rest[0];
|
|
17
|
+
if (rest.length === 1 && isNamed(only)) {
|
|
18
|
+
return { sql: first, named: only };
|
|
19
|
+
}
|
|
20
|
+
return { sql: first, args: rest };
|
|
21
|
+
}
|
|
22
|
+
function isNamed(value) {
|
|
23
|
+
return (typeof value === 'object' &&
|
|
24
|
+
value !== null &&
|
|
25
|
+
!(value instanceof Date) &&
|
|
26
|
+
!(value instanceof Uint8Array) &&
|
|
27
|
+
!Array.isArray(value));
|
|
28
|
+
}
|
|
29
|
+
/** Opens a database by its name, applying or checking its migrations. */
|
|
30
|
+
export async function openDatabase(link, name, options) {
|
|
31
|
+
checkName(name, 'database');
|
|
32
|
+
const migrations = options?.migrations === undefined ? undefined : await migrationFiles(options.migrations);
|
|
33
|
+
const open = SqlDatabase.encode({ name, migrations });
|
|
34
|
+
const db = new Database(link, name, open);
|
|
35
|
+
await link.run('write', connection => db.handle(connection));
|
|
36
|
+
return db;
|
|
37
|
+
}
|
|
38
|
+
async function migrationFiles(given) {
|
|
39
|
+
if (typeof given !== 'string') {
|
|
40
|
+
const files = Array.isArray(given)
|
|
41
|
+
? [...given]
|
|
42
|
+
: Object.entries(given).map(([name, text]) => ({ name, text }));
|
|
43
|
+
return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
44
|
+
}
|
|
45
|
+
let dir = given;
|
|
46
|
+
let entries = await readdir(dir, { withFileTypes: true });
|
|
47
|
+
if (!entries.some(e => e.isFile() && e.name.endsWith('.sql'))) {
|
|
48
|
+
const dirs = entries.filter(e => e.isDirectory());
|
|
49
|
+
if (dirs.length === 1) {
|
|
50
|
+
dir = join(dir, dirs[0].name);
|
|
51
|
+
entries = await readdir(dir, { withFileTypes: true });
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
const names = entries
|
|
55
|
+
.filter(e => e.isFile() && e.name.endsWith('.sql'))
|
|
56
|
+
.map(e => e.name)
|
|
57
|
+
.sort();
|
|
58
|
+
if (names.length === 0) {
|
|
59
|
+
throw new InvalidError(`no .sql migrations in ${given}`);
|
|
60
|
+
}
|
|
61
|
+
return Promise.all(names.map(async (name) => ({ name, text: await readFile(join(dir, name), 'utf8') })));
|
|
62
|
+
}
|
|
63
|
+
/** Reads a query's rows as objects, refusing two columns of one name, which one object cannot hold. */
|
|
64
|
+
function rowsOf(columns, rows) {
|
|
65
|
+
if (new Set(columns).size !== columns.length) {
|
|
66
|
+
const twice = columns.find((c, i) => columns.indexOf(c) !== i);
|
|
67
|
+
throw new InvalidError(`two columns named ${twice}: name them apart with as`);
|
|
68
|
+
}
|
|
69
|
+
return rows.map(values => {
|
|
70
|
+
const row = {};
|
|
71
|
+
columns.forEach((column, i) => {
|
|
72
|
+
row[column] = values[i] ?? null;
|
|
73
|
+
});
|
|
74
|
+
return row;
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
function one(rows) {
|
|
78
|
+
if (rows.length > 1) {
|
|
79
|
+
throw new InvalidError(`a query for one row answered ${rows.length}`);
|
|
80
|
+
}
|
|
81
|
+
return rows[0];
|
|
82
|
+
}
|
|
83
|
+
function scalar(columns, rows) {
|
|
84
|
+
if (rows.length === 0) {
|
|
85
|
+
throw new InvalidError('a scalar query answered no row; one always answers, as count(*) does');
|
|
86
|
+
}
|
|
87
|
+
if (columns.length !== 1 || rows.length > 1) {
|
|
88
|
+
throw new InvalidError(`a scalar query answered ${rows.length} rows of ${columns.length} columns`);
|
|
89
|
+
}
|
|
90
|
+
return rows[0][0];
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* A database. What a call's name starts with says where it runs: exec and
|
|
94
|
+
* its kin may write and run on the file's one writer, grouped with the other
|
|
95
|
+
* writes; all, one, scalar and each read, on readers that refuse to write.
|
|
96
|
+
*/
|
|
97
|
+
export class Database {
|
|
98
|
+
name;
|
|
99
|
+
#link;
|
|
100
|
+
#open;
|
|
101
|
+
constructor(link, name, open) {
|
|
102
|
+
this.#link = link;
|
|
103
|
+
this.name = name;
|
|
104
|
+
this.#open = open;
|
|
105
|
+
}
|
|
106
|
+
handle(connection) {
|
|
107
|
+
return handleOn(connection, methods['sql.open'], this.#open);
|
|
108
|
+
}
|
|
109
|
+
async #query(given, write, signal) {
|
|
110
|
+
const statement = statementOf(given);
|
|
111
|
+
return this.#link.run(write ? 'write' : 'read', async (connection) => {
|
|
112
|
+
const handle = await this.handle(connection);
|
|
113
|
+
const stream = await connection.session.open(methods['sql.query'], SqlStatement.encode({ handle, ...statement, write: write || undefined }), true);
|
|
114
|
+
const unwatch = watch(signal, stream);
|
|
115
|
+
try {
|
|
116
|
+
const head = await stream.next();
|
|
117
|
+
const columns = SqlColumns.decode(head.body).columns ?? [];
|
|
118
|
+
const rows = [];
|
|
119
|
+
for (;;) {
|
|
120
|
+
const event = await stream.next();
|
|
121
|
+
stream.consumed(event.body.length);
|
|
122
|
+
if (event.end) {
|
|
123
|
+
return { columns, rows };
|
|
124
|
+
}
|
|
125
|
+
rows.push((SqlRow.decode(event.body).values ?? []));
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
finally {
|
|
129
|
+
unwatch();
|
|
130
|
+
}
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
/** Every row a query answers, held in memory: the server refuses past 64 MiB of them. */
|
|
134
|
+
async all(...statement) {
|
|
135
|
+
const { columns, rows } = await this.#query(statement, false);
|
|
136
|
+
return rowsOf(columns, rows);
|
|
137
|
+
}
|
|
138
|
+
/** The one row a query answers, undefined for none; two is InvalidError. */
|
|
139
|
+
async one(...statement) {
|
|
140
|
+
return one(await this.all(...statement));
|
|
141
|
+
}
|
|
142
|
+
/** The one value of a query that always answers one row, as count(*) does. */
|
|
143
|
+
async scalar(...statement) {
|
|
144
|
+
const { columns, rows } = await this.#query(statement, false);
|
|
145
|
+
return scalar(columns, rows);
|
|
146
|
+
}
|
|
147
|
+
/** The columns and rows of a query as SQLite returned them, arrays rather than objects. */
|
|
148
|
+
query(...statement) {
|
|
149
|
+
return this.#query(statement, false);
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Reads a query's rows one at a time as they arrive, within the credit
|
|
153
|
+
* the client grants: the client holds a row and the frames in flight.
|
|
154
|
+
*/
|
|
155
|
+
async *each(...statement) {
|
|
156
|
+
const { sql, args, named } = statementOf(statement);
|
|
157
|
+
const connection = await this.#link.connection();
|
|
158
|
+
const handle = await this.handle(connection);
|
|
159
|
+
const stream = await connection.session.open(methods['sql.query'], SqlStatement.encode({ handle, sql, args, named }), true);
|
|
160
|
+
let ended = false;
|
|
161
|
+
try {
|
|
162
|
+
const columns = SqlColumns.decode((await stream.next()).body).columns ?? [];
|
|
163
|
+
rowsOf(columns, []);
|
|
164
|
+
for (;;) {
|
|
165
|
+
const event = await stream.next();
|
|
166
|
+
stream.consumed(event.body.length);
|
|
167
|
+
if (event.end) {
|
|
168
|
+
ended = true;
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
yield rowsOf(columns, [(SqlRow.decode(event.body).values ?? [])])[0];
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
finally {
|
|
175
|
+
if (!ended) {
|
|
176
|
+
stream.cancel();
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
/** Runs a statement on the writer and says what it changed. */
|
|
181
|
+
async exec(...statement) {
|
|
182
|
+
const given = statementOf(statement);
|
|
183
|
+
return this.#link.run('write', async (connection) => {
|
|
184
|
+
const handle = await this.handle(connection);
|
|
185
|
+
const body = await connection.session.call(methods['sql.exec'], SqlStatement.encode({ handle, ...given }));
|
|
186
|
+
const done = SqlDone.decode(body);
|
|
187
|
+
return { changes: done.changes ?? 0, lastId: done.lastId ?? 0 };
|
|
188
|
+
});
|
|
189
|
+
}
|
|
190
|
+
/** The rows a write's returning clause answers, run on the writer. */
|
|
191
|
+
async execAll(...statement) {
|
|
192
|
+
const { columns, rows } = await this.#query(statement, true);
|
|
193
|
+
return rowsOf(columns, rows);
|
|
194
|
+
}
|
|
195
|
+
async execOne(...statement) {
|
|
196
|
+
return one(await this.execAll(...statement));
|
|
197
|
+
}
|
|
198
|
+
async execScalar(...statement) {
|
|
199
|
+
const { columns, rows } = await this.#query(statement, true);
|
|
200
|
+
return scalar(columns, rows);
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Runs the statements fn asks for in one transaction, all or none: a
|
|
204
|
+
* failure names its statement as `call`. fn returns before anything is
|
|
205
|
+
* sent, since no transaction is held across the network, and what it
|
|
206
|
+
* returns comes back answered, an array's promises each:
|
|
207
|
+
*
|
|
208
|
+
* const [note] = await db.batch(tx => [tx.one`insert into notes (title) values (${t}) returning *`])
|
|
209
|
+
*/
|
|
210
|
+
batch(fn) {
|
|
211
|
+
return this.#run(false, fn);
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* Runs the reads fn asks for from one snapshot, and gives back what fn
|
|
215
|
+
* returns, answered as batch answers it:
|
|
216
|
+
*
|
|
217
|
+
* const [notes, total] = await db.view(tx => [tx.all`select * from notes`, tx.scalar`select count(*) from notes`])
|
|
218
|
+
*/
|
|
219
|
+
view(fn) {
|
|
220
|
+
return this.#run(true, fn);
|
|
221
|
+
}
|
|
222
|
+
async #run(read, fn) {
|
|
223
|
+
const tx = new SqlBatch(read, this.name);
|
|
224
|
+
const returned = fn(tx);
|
|
225
|
+
tx.close();
|
|
226
|
+
if (returned instanceof Promise && !tx.made(returned)) {
|
|
227
|
+
throw new InvalidError('a batch function returns before anything is sent; it cannot await inside');
|
|
228
|
+
}
|
|
229
|
+
if (tx.statements.length > 0 || tx.jobs.length > 0) {
|
|
230
|
+
await this.#send(read, tx);
|
|
231
|
+
}
|
|
232
|
+
return settle(returned);
|
|
233
|
+
}
|
|
234
|
+
async #send(read, tx) {
|
|
235
|
+
try {
|
|
236
|
+
const results = await this.#link.run(read ? 'read' : 'write', async (connection) => {
|
|
237
|
+
const handle = await this.handle(connection);
|
|
238
|
+
const jobs = [];
|
|
239
|
+
for (const queued of tx.jobs) {
|
|
240
|
+
const queue = await handleOn(connection, methods['jobs.open'], queued.open);
|
|
241
|
+
jobs.push({ handle: queue, jobs: [queued.job] });
|
|
242
|
+
}
|
|
243
|
+
const body = await connection.session.call(methods['sql.batch'], SqlStatements.encode({
|
|
244
|
+
handle,
|
|
245
|
+
statements: tx.statements.map(s => s.statement),
|
|
246
|
+
read: read || undefined,
|
|
247
|
+
jobs: jobs.length > 0 ? jobs : undefined,
|
|
248
|
+
}));
|
|
249
|
+
return SqlResults.decode(body).results ?? [];
|
|
250
|
+
});
|
|
251
|
+
tx.statements.forEach((s, i) => {
|
|
252
|
+
s.settle(results[i] ?? {});
|
|
253
|
+
});
|
|
254
|
+
for (const queued of tx.jobs) {
|
|
255
|
+
queued.settle();
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
catch (err) {
|
|
259
|
+
for (const s of [...tx.statements, ...tx.jobs]) {
|
|
260
|
+
s.fail(err);
|
|
261
|
+
}
|
|
262
|
+
throw err;
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
/** The statements of a batch or a view, whose promises settle with it. */
|
|
267
|
+
export class SqlBatch {
|
|
268
|
+
read;
|
|
269
|
+
/** the database the batch runs in, whose queues alone take its jobs */
|
|
270
|
+
database;
|
|
271
|
+
statements = [];
|
|
272
|
+
jobs = [];
|
|
273
|
+
#done = false;
|
|
274
|
+
#made = new WeakSet();
|
|
275
|
+
constructor(read, database) {
|
|
276
|
+
this.read = read;
|
|
277
|
+
this.database = database;
|
|
278
|
+
}
|
|
279
|
+
close() {
|
|
280
|
+
this.#done = true;
|
|
281
|
+
}
|
|
282
|
+
/** Whether the promise is one of this batch's statements', rather than an async function's. */
|
|
283
|
+
made(promise) {
|
|
284
|
+
return this.#made.has(promise);
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* Adds a job to the batch, for a queue's withTx: a program writes
|
|
288
|
+
* `queue.withTx(tx).enqueue(value)`, on a queue opened `in` this database.
|
|
289
|
+
*/
|
|
290
|
+
enqueue(open, job) {
|
|
291
|
+
if (this.read) {
|
|
292
|
+
throw new InvalidError('a job in a view, which reads');
|
|
293
|
+
}
|
|
294
|
+
const { promise, settle, fail } = this.#promise();
|
|
295
|
+
this.jobs.push({ open, job, settle: () => settle(undefined), fail });
|
|
296
|
+
return promise;
|
|
297
|
+
}
|
|
298
|
+
#promise() {
|
|
299
|
+
if (this.#done) {
|
|
300
|
+
throw new InvalidError('a batch takes its statements while its function runs, before it is sent');
|
|
301
|
+
}
|
|
302
|
+
let settle;
|
|
303
|
+
let fail;
|
|
304
|
+
const promise = new Promise((res, rej) => {
|
|
305
|
+
settle = res;
|
|
306
|
+
fail = rej;
|
|
307
|
+
});
|
|
308
|
+
// a caller need not await a call it only wanted done
|
|
309
|
+
promise.catch(() => { });
|
|
310
|
+
this.#made.add(promise);
|
|
311
|
+
return { promise, settle, fail };
|
|
312
|
+
}
|
|
313
|
+
#record(given, rows, settle) {
|
|
314
|
+
const statement = statementOf(given);
|
|
315
|
+
const { promise: settled, settle: resolve, fail: reject } = this.#promise();
|
|
316
|
+
this.statements.push({
|
|
317
|
+
statement: { ...statement, rows: rows && !this.read ? true : undefined },
|
|
318
|
+
settle: result => {
|
|
319
|
+
try {
|
|
320
|
+
resolve(settle(result));
|
|
321
|
+
}
|
|
322
|
+
catch (err) {
|
|
323
|
+
reject(err);
|
|
324
|
+
}
|
|
325
|
+
},
|
|
326
|
+
fail: reject,
|
|
327
|
+
});
|
|
328
|
+
return settled;
|
|
329
|
+
}
|
|
330
|
+
exec(...statement) {
|
|
331
|
+
return this.#record(statement, false, r => ({ changes: r.changes ?? 0, lastId: r.lastId ?? 0 }));
|
|
332
|
+
}
|
|
333
|
+
all(...statement) {
|
|
334
|
+
return this.#record(statement, true, r => rowsOf(r.columns ?? [], (r.rows ?? [])));
|
|
335
|
+
}
|
|
336
|
+
one(...statement) {
|
|
337
|
+
return this.#record(statement, true, r => one(rowsOf(r.columns ?? [], (r.rows ?? []))));
|
|
338
|
+
}
|
|
339
|
+
scalar(...statement) {
|
|
340
|
+
return this.#record(statement, true, r => scalar(r.columns ?? [], (r.rows ?? [])));
|
|
341
|
+
}
|
|
342
|
+
}
|
package/dist/store.d.ts
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import { Blobs } from './blobs.ts';
|
|
2
|
+
import { Clock } from './clock.ts';
|
|
3
|
+
import { Link } from './connection.ts';
|
|
4
|
+
import { Jobs } from './jobs.ts';
|
|
5
|
+
import { Kv } from './kv.ts';
|
|
6
|
+
import { Metrics } from './metrics.ts';
|
|
7
|
+
import { Records } from './records.ts';
|
|
8
|
+
import type { Runtime, TlsOptions } from './runtime.ts';
|
|
9
|
+
import { type Database, type SqlOptions } from './sql.ts';
|
|
10
|
+
import { type Duration, type Time } from './time.ts';
|
|
11
|
+
export interface OpenOptions {
|
|
12
|
+
/**
|
|
13
|
+
* A server of this process's own, a child on stdin and stdout that lives
|
|
14
|
+
* and dies with it, rather than the directory's shared sidecar: tests,
|
|
15
|
+
* scripts, one process alone.
|
|
16
|
+
*/
|
|
17
|
+
private?: boolean;
|
|
18
|
+
/** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
|
|
19
|
+
binary?: string;
|
|
20
|
+
/**
|
|
21
|
+
* How long a sidecar this process starts stays once its last connection
|
|
22
|
+
* has gone: 30 s unless given, 0 for ever. One found running keeps its own.
|
|
23
|
+
*/
|
|
24
|
+
idle?: Duration;
|
|
25
|
+
/**
|
|
26
|
+
* Runs a private server on a test's clock, starting at this time, which
|
|
27
|
+
* `store.clock` moves forward instead of a test waiting: keys expire, jobs
|
|
28
|
+
* come due and records age at once. Needs `private`.
|
|
29
|
+
*/
|
|
30
|
+
clock?: Time;
|
|
31
|
+
}
|
|
32
|
+
/** What a server is, as its WELCOME said it to this store's connection. */
|
|
33
|
+
export interface Status {
|
|
34
|
+
/** its version: v0.1.0, or (devel) for one built from a checkout */
|
|
35
|
+
server: string;
|
|
36
|
+
protocol: number;
|
|
37
|
+
/** the engines it serves */
|
|
38
|
+
engines: string[];
|
|
39
|
+
/** admin may change a schema and drop records; data reads and writes */
|
|
40
|
+
capability: 'admin' | 'data';
|
|
41
|
+
}
|
|
42
|
+
export interface ConnectOptions {
|
|
43
|
+
/** a line of the server's tokens file, admin or data */
|
|
44
|
+
token: string;
|
|
45
|
+
tls?: TlsOptions;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* The store in a directory, as another process serves it. Close it once, as
|
|
49
|
+
* a Go program closes its tinystore.Store: `await using store = await open(dir)`.
|
|
50
|
+
*/
|
|
51
|
+
export declare class Store implements AsyncDisposable {
|
|
52
|
+
#private;
|
|
53
|
+
readonly kv: Kv;
|
|
54
|
+
readonly jobs: Jobs;
|
|
55
|
+
readonly blobs: Blobs;
|
|
56
|
+
readonly records: Records;
|
|
57
|
+
readonly metrics: Metrics;
|
|
58
|
+
/** The test's clock of a private store opened with `clock`; on any other, its calls are InvalidError. */
|
|
59
|
+
readonly clock: Clock;
|
|
60
|
+
constructor(link: Link);
|
|
61
|
+
/**
|
|
62
|
+
* What the server this store reaches is: its version, the protocol the
|
|
63
|
+
* connection speaks, the engines it serves and what the connection may do.
|
|
64
|
+
* A client newer than its server learns here what it may ask for; a call
|
|
65
|
+
* past it is UnimplementedError, naming the server's version.
|
|
66
|
+
*/
|
|
67
|
+
status(): Promise<Status>;
|
|
68
|
+
/**
|
|
69
|
+
* Opens a database of the application's own, sql/<name>.db. The first open
|
|
70
|
+
* in the server, on an admin connection, applies its migrations; every
|
|
71
|
+
* later one checks them against what the file applied.
|
|
72
|
+
*/
|
|
73
|
+
sql(name: string, options?: SqlOptions): Promise<Database>;
|
|
74
|
+
/**
|
|
75
|
+
* Writes a backup of the whole store to a zip at path while the store keeps
|
|
76
|
+
* working, as `tinystore backup` does: every engine's file, with its size
|
|
77
|
+
* and checksum, which `tinystore restore` checks. The zip is written beside
|
|
78
|
+
* path and renamed into place once whole, so a backup that fails leaves no
|
|
79
|
+
* zip. It needs an admin connection; a remote server sends the zip over it.
|
|
80
|
+
*/
|
|
81
|
+
backup(path: string): Promise<void>;
|
|
82
|
+
/**
|
|
83
|
+
* Ingests the instruments' last values and hands over the loggers' lines,
|
|
84
|
+
* then closes the connection. A private child is waited for until it has
|
|
85
|
+
* exited, so that the directory is free once this returns; the directory's
|
|
86
|
+
* sidecar goes once it has been idle.
|
|
87
|
+
*/
|
|
88
|
+
close(): Promise<void>;
|
|
89
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Opens the store in a directory through its sidecar, found through SERVE or
|
|
93
|
+
* started, or through a private child when asked. It returns once the server
|
|
94
|
+
* has answered, so that a directory that cannot be served fails here.
|
|
95
|
+
*/
|
|
96
|
+
export declare function open(dir: string, options?: OpenOptions): Promise<Store>;
|
|
97
|
+
export declare function openWith(runtime: Runtime, dir: string, options?: OpenOptions): Promise<Store>;
|
|
98
|
+
/**
|
|
99
|
+
* Connects to a remote server: tls:// checks the server's certificate before
|
|
100
|
+
* the token leaves; tcp:// sends the token in the clear, for a network its
|
|
101
|
+
* operator trusts.
|
|
102
|
+
*/
|
|
103
|
+
export declare function connect(url: string, options: ConnectOptions): Promise<Store>;
|
package/dist/store.js
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import { randomBytes } from 'node:crypto';
|
|
2
|
+
import { open as openFile, rename, rm } from 'node:fs/promises';
|
|
3
|
+
import { Blobs } from './blobs.js';
|
|
4
|
+
import { Clock } from './clock.js';
|
|
5
|
+
import { Link, privateChild, remote, sidecar } from './connection.js';
|
|
6
|
+
import { ClosedError, InvalidError } from './errors.js';
|
|
7
|
+
import { Jobs } from './jobs.js';
|
|
8
|
+
import { Kv } from './kv.js';
|
|
9
|
+
import { Metrics } from './metrics.js';
|
|
10
|
+
import { Records } from './records.js';
|
|
11
|
+
import { bunRuntime } from './runtime/bun.js';
|
|
12
|
+
import { nodeRuntime } from './runtime/node.js';
|
|
13
|
+
import { openDatabase } from './sql.js';
|
|
14
|
+
import { ms, unixMs } from './time.js';
|
|
15
|
+
import { Empty, methods } from './wire/messages.js';
|
|
16
|
+
/**
|
|
17
|
+
* The store in a directory, as another process serves it. Close it once, as
|
|
18
|
+
* a Go program closes its tinystore.Store: `await using store = await open(dir)`.
|
|
19
|
+
*/
|
|
20
|
+
export class Store {
|
|
21
|
+
kv;
|
|
22
|
+
jobs;
|
|
23
|
+
blobs;
|
|
24
|
+
records;
|
|
25
|
+
metrics;
|
|
26
|
+
/** The test's clock of a private store opened with `clock`; on any other, its calls are InvalidError. */
|
|
27
|
+
clock;
|
|
28
|
+
#link;
|
|
29
|
+
constructor(link) {
|
|
30
|
+
this.#link = link;
|
|
31
|
+
this.clock = new Clock(link);
|
|
32
|
+
this.kv = new Kv(link);
|
|
33
|
+
this.jobs = new Jobs(link);
|
|
34
|
+
this.blobs = new Blobs(link);
|
|
35
|
+
this.records = new Records(link);
|
|
36
|
+
this.metrics = new Metrics(link);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* What the server this store reaches is: its version, the protocol the
|
|
40
|
+
* connection speaks, the engines it serves and what the connection may do.
|
|
41
|
+
* A client newer than its server learns here what it may ask for; a call
|
|
42
|
+
* past it is UnimplementedError, naming the server's version.
|
|
43
|
+
*/
|
|
44
|
+
async status() {
|
|
45
|
+
const agreed = await (await this.#link.connection()).session.welcomed;
|
|
46
|
+
return {
|
|
47
|
+
server: agreed.server,
|
|
48
|
+
protocol: Number(agreed.protocol),
|
|
49
|
+
engines: [...agreed.engines],
|
|
50
|
+
capability: agreed.capability === 'admin' ? 'admin' : 'data',
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Opens a database of the application's own, sql/<name>.db. The first open
|
|
55
|
+
* in the server, on an admin connection, applies its migrations; every
|
|
56
|
+
* later one checks them against what the file applied.
|
|
57
|
+
*/
|
|
58
|
+
sql(name, options) {
|
|
59
|
+
return openDatabase(this.#link, name, options);
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Writes a backup of the whole store to a zip at path while the store keeps
|
|
63
|
+
* working, as `tinystore backup` does: every engine's file, with its size
|
|
64
|
+
* and checksum, which `tinystore restore` checks. The zip is written beside
|
|
65
|
+
* path and renamed into place once whole, so a backup that fails leaves no
|
|
66
|
+
* zip. It needs an admin connection; a remote server sends the zip over it.
|
|
67
|
+
*/
|
|
68
|
+
async backup(path) {
|
|
69
|
+
const part = `${path}.${randomBytes(4).toString('hex')}.part`;
|
|
70
|
+
try {
|
|
71
|
+
await this.#link.run('read', async (connection) => {
|
|
72
|
+
const file = await openFile(part, 'w');
|
|
73
|
+
try {
|
|
74
|
+
const stream = await connection.session.open(methods['server.backup'], Empty.encode({}), true);
|
|
75
|
+
await stream.next(); // the RESPONSE that heads the zip
|
|
76
|
+
for (;;) {
|
|
77
|
+
const event = await stream.next();
|
|
78
|
+
stream.consumed(event.body.length);
|
|
79
|
+
await file.write(event.body);
|
|
80
|
+
if (event.end) {
|
|
81
|
+
break;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
await file.sync();
|
|
85
|
+
}
|
|
86
|
+
finally {
|
|
87
|
+
await file.close();
|
|
88
|
+
}
|
|
89
|
+
});
|
|
90
|
+
await rename(part, path);
|
|
91
|
+
}
|
|
92
|
+
catch (err) {
|
|
93
|
+
await rm(part, { force: true });
|
|
94
|
+
throw err;
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Ingests the instruments' last values and hands over the loggers' lines,
|
|
99
|
+
* then closes the connection. A private child is waited for until it has
|
|
100
|
+
* exited, so that the directory is free once this returns; the directory's
|
|
101
|
+
* sidecar goes once it has been idle.
|
|
102
|
+
*/
|
|
103
|
+
async close() {
|
|
104
|
+
await this.metrics.stop();
|
|
105
|
+
await this.records.stop();
|
|
106
|
+
this.kv.stop();
|
|
107
|
+
await this.#link.close();
|
|
108
|
+
}
|
|
109
|
+
[Symbol.asyncDispose]() {
|
|
110
|
+
return this.close();
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
/** Bun's own runtime under Bun, and Node's under Node. */
|
|
114
|
+
const runtime = typeof Bun === 'undefined' ? nodeRuntime : bunRuntime;
|
|
115
|
+
/**
|
|
116
|
+
* Opens the store in a directory through its sidecar, found through SERVE or
|
|
117
|
+
* started, or through a private child when asked. It returns once the server
|
|
118
|
+
* has answered, so that a directory that cannot be served fails here.
|
|
119
|
+
*/
|
|
120
|
+
export async function open(dir, options = {}) {
|
|
121
|
+
return openWith(runtime, dir, options);
|
|
122
|
+
}
|
|
123
|
+
export async function openWith(runtime, dir, options = {}) {
|
|
124
|
+
const binary = () => findBinary(runtime, options.binary);
|
|
125
|
+
const idle = options.idle === undefined ? undefined : ms(options.idle);
|
|
126
|
+
if (options.clock !== undefined && options.private !== true) {
|
|
127
|
+
throw new InvalidError("a clock is a private server's: a shared sidecar runs on the system's time");
|
|
128
|
+
}
|
|
129
|
+
const clock = options.clock === undefined ? undefined : new Date(unixMs(options.clock));
|
|
130
|
+
const link = new Link(options.private === true
|
|
131
|
+
? privateChild(runtime, dir, binary, clock)
|
|
132
|
+
: sidecar(runtime, dir, binary, idle));
|
|
133
|
+
await link.connection();
|
|
134
|
+
return new Store(link);
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Connects to a remote server: tls:// checks the server's certificate before
|
|
138
|
+
* the token leaves; tcp:// sends the token in the clear, for a network its
|
|
139
|
+
* operator trusts.
|
|
140
|
+
*/
|
|
141
|
+
export async function connect(url, options) {
|
|
142
|
+
const link = new Link(remote(runtime, url, options.token, options.tls));
|
|
143
|
+
await link.connection();
|
|
144
|
+
return new Store(link);
|
|
145
|
+
}
|
|
146
|
+
function findBinary(runtime, given) {
|
|
147
|
+
const found = given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore');
|
|
148
|
+
if (found === undefined || found === '') {
|
|
149
|
+
throw new ClosedError(`no tinystore binary: @tinyshed/tinystore-${process.platform}-${process.arch} is not installed; ` +
|
|
150
|
+
'install it, put tinystore on PATH, or set TINYSTORE_BIN');
|
|
151
|
+
}
|
|
152
|
+
return found;
|
|
153
|
+
}
|
package/dist/time.d.ts
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** A duration's units, largest first, in the order its text writes them. */
|
|
2
|
+
type Units = ['w', 'd', 'h', 'm', 's', 'ms'];
|
|
3
|
+
/** One of a duration's units: weeks, days, hours, minutes, seconds, milliseconds. */
|
|
4
|
+
export type Unit = Units[number];
|
|
5
|
+
/**
|
|
6
|
+
* Every spelling of units each written once, largest first: a number and its
|
|
7
|
+
* unit, then the same of the units after it, or none.
|
|
8
|
+
*
|
|
9
|
+
* ['s', 'ms'] → `${number}s${number}ms` | `${number}s` | `${number}ms`
|
|
10
|
+
*/
|
|
11
|
+
type Spelled<U extends readonly string[]> = U extends readonly [
|
|
12
|
+
infer First extends string,
|
|
13
|
+
...infer Rest extends string[]
|
|
14
|
+
] ? `${number}${First}${Spelled<Rest> | ''}` | Spelled<Rest> : never;
|
|
15
|
+
/**
|
|
16
|
+
* A duration's text, '30d', '1h30m', '15m', '1s' or '250ms', which the type
|
|
17
|
+
* checks as it is written, so that '1hr' or '90mins' does not compile. Text
|
|
18
|
+
* from elsewhere, an environment's, is cast as Duration and checked when the
|
|
19
|
+
* call runs.
|
|
20
|
+
*/
|
|
21
|
+
export type DurationText = Spelled<Units>;
|
|
22
|
+
/** A length of time: milliseconds, or the text of one, such as '1h30m'. */
|
|
23
|
+
export type Duration = number | DurationText;
|
|
24
|
+
/** A moment: a Date, or unix milliseconds. */
|
|
25
|
+
export type Time = Date | number;
|
|
26
|
+
/**
|
|
27
|
+
* A duration's milliseconds; each unit once, largest first: 1h30m, not
|
|
28
|
+
* 90m30m. It takes any text, since text cast as a Duration reaches it too.
|
|
29
|
+
*/
|
|
30
|
+
export declare function ms(d: Duration | string): number;
|
|
31
|
+
/** A moment's unix milliseconds. */
|
|
32
|
+
export declare function unixMs(t: Time): number;
|
|
33
|
+
/** A moment the server named in unix milliseconds, none for 0 or absent. */
|
|
34
|
+
export declare function dateOf(unix: number | undefined): Date | undefined;
|
|
35
|
+
export {};
|
package/dist/time.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { InvalidError } from './errors.js';
|
|
2
|
+
const units = {
|
|
3
|
+
ms: 1,
|
|
4
|
+
s: 1000,
|
|
5
|
+
m: 60_000,
|
|
6
|
+
h: 3_600_000,
|
|
7
|
+
d: 86_400_000,
|
|
8
|
+
w: 604_800_000,
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* A duration's milliseconds; each unit once, largest first: 1h30m, not
|
|
12
|
+
* 90m30m. It takes any text, since text cast as a Duration reaches it too.
|
|
13
|
+
*/
|
|
14
|
+
export function ms(d) {
|
|
15
|
+
if (typeof d === 'number') {
|
|
16
|
+
if (!Number.isFinite(d) || d < 0) {
|
|
17
|
+
throw new InvalidError(`a duration of ${d} milliseconds`);
|
|
18
|
+
}
|
|
19
|
+
return Math.round(d);
|
|
20
|
+
}
|
|
21
|
+
const parts = /^(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m(?!s))?(?:(\d+)s)?(?:(\d+)ms)?$/.exec(d.trim());
|
|
22
|
+
if (parts === null || d.trim() === '') {
|
|
23
|
+
throw new InvalidError(`the duration ${JSON.stringify(d)}; write it as 30d, 1h30m, 15m, 1s or 250ms`);
|
|
24
|
+
}
|
|
25
|
+
const [, w, days, h, m, s, milli] = parts;
|
|
26
|
+
return (Number(w ?? 0) * units.w +
|
|
27
|
+
Number(days ?? 0) * units.d +
|
|
28
|
+
Number(h ?? 0) * units.h +
|
|
29
|
+
Number(m ?? 0) * units.m +
|
|
30
|
+
Number(s ?? 0) * units.s +
|
|
31
|
+
Number(milli ?? 0));
|
|
32
|
+
}
|
|
33
|
+
/** A moment's unix milliseconds. */
|
|
34
|
+
export function unixMs(t) {
|
|
35
|
+
const n = typeof t === 'number' ? t : t.getTime();
|
|
36
|
+
if (!Number.isFinite(n)) {
|
|
37
|
+
throw new InvalidError('an invalid Date');
|
|
38
|
+
}
|
|
39
|
+
return Math.trunc(n);
|
|
40
|
+
}
|
|
41
|
+
/** A moment the server named in unix milliseconds, none for 0 or absent. */
|
|
42
|
+
export function dateOf(unix) {
|
|
43
|
+
return unix === undefined || unix === 0 ? undefined : new Date(unix);
|
|
44
|
+
}
|