@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.
Files changed (100) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +262 -0
  3. package/bin/tinystore.js +50 -0
  4. package/dist/background.d.ts +30 -0
  5. package/dist/background.js +93 -0
  6. package/dist/blobs.d.ts +98 -0
  7. package/dist/blobs.js +299 -0
  8. package/dist/cancel.d.ts +14 -0
  9. package/dist/cancel.js +22 -0
  10. package/dist/clock.d.ts +21 -0
  11. package/dist/clock.js +35 -0
  12. package/dist/config.d.ts +60 -0
  13. package/dist/config.js +417 -0
  14. package/dist/connection.d.ts +78 -0
  15. package/dist/connection.js +405 -0
  16. package/dist/console.d.ts +48 -0
  17. package/dist/console.js +195 -0
  18. package/dist/errors.d.ts +103 -0
  19. package/dist/errors.js +158 -0
  20. package/dist/handles.d.ts +28 -0
  21. package/dist/handles.js +37 -0
  22. package/dist/index.d.ts +21 -0
  23. package/dist/index.js +7 -0
  24. package/dist/jobs.d.ts +304 -0
  25. package/dist/jobs.js +684 -0
  26. package/dist/kv.d.ts +283 -0
  27. package/dist/kv.js +815 -0
  28. package/dist/limiter.d.ts +45 -0
  29. package/dist/limiter.js +68 -0
  30. package/dist/logger.d.ts +96 -0
  31. package/dist/logger.js +243 -0
  32. package/dist/metrics.d.ts +249 -0
  33. package/dist/metrics.js +610 -0
  34. package/dist/once.d.ts +31 -0
  35. package/dist/once.js +116 -0
  36. package/dist/quota.d.ts +44 -0
  37. package/dist/quota.js +98 -0
  38. package/dist/records.d.ts +182 -0
  39. package/dist/records.js +346 -0
  40. package/dist/runtime/bun.d.ts +2 -0
  41. package/dist/runtime/bun.js +164 -0
  42. package/dist/runtime/node.d.ts +2 -0
  43. package/dist/runtime/node.js +157 -0
  44. package/dist/runtime/shared.d.ts +25 -0
  45. package/dist/runtime/shared.js +45 -0
  46. package/dist/runtime.d.ts +48 -0
  47. package/dist/runtime.js +4 -0
  48. package/dist/schema.d.ts +39 -0
  49. package/dist/schema.js +21 -0
  50. package/dist/session.d.ts +120 -0
  51. package/dist/session.js +546 -0
  52. package/dist/sql.d.ts +121 -0
  53. package/dist/sql.js +342 -0
  54. package/dist/store.d.ts +103 -0
  55. package/dist/store.js +153 -0
  56. package/dist/time.d.ts +35 -0
  57. package/dist/time.js +44 -0
  58. package/dist/trace.d.ts +18 -0
  59. package/dist/trace.js +22 -0
  60. package/dist/wire/codec.d.ts +90 -0
  61. package/dist/wire/codec.js +383 -0
  62. package/dist/wire/frame.d.ts +41 -0
  63. package/dist/wire/frame.js +102 -0
  64. package/dist/wire/messages.d.ts +1403 -0
  65. package/dist/wire/messages.js +472 -0
  66. package/dist/wire/msgpack.d.ts +93 -0
  67. package/dist/wire/msgpack.js +680 -0
  68. package/package.json +40 -0
  69. package/src/background.ts +108 -0
  70. package/src/blobs.ts +437 -0
  71. package/src/cancel.ts +26 -0
  72. package/src/clock.ts +45 -0
  73. package/src/config.ts +501 -0
  74. package/src/connection.ts +512 -0
  75. package/src/console.ts +228 -0
  76. package/src/errors.ts +211 -0
  77. package/src/handles.ts +68 -0
  78. package/src/index.ts +92 -0
  79. package/src/jobs.ts +963 -0
  80. package/src/kv.ts +1093 -0
  81. package/src/limiter.ts +99 -0
  82. package/src/logger.ts +326 -0
  83. package/src/metrics.ts +896 -0
  84. package/src/once.ts +142 -0
  85. package/src/quota.ts +137 -0
  86. package/src/records.ts +537 -0
  87. package/src/runtime/bun.ts +190 -0
  88. package/src/runtime/node.ts +177 -0
  89. package/src/runtime/shared.ts +61 -0
  90. package/src/runtime.ts +57 -0
  91. package/src/schema.ts +69 -0
  92. package/src/session.ts +665 -0
  93. package/src/sql.ts +478 -0
  94. package/src/store.ts +219 -0
  95. package/src/time.ts +87 -0
  96. package/src/trace.ts +32 -0
  97. package/src/wire/codec.ts +445 -0
  98. package/src/wire/frame.ts +139 -0
  99. package/src/wire/messages.ts +562 -0
  100. package/src/wire/msgpack.ts +712 -0
package/src/sql.ts ADDED
@@ -0,0 +1,478 @@
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
+
6
+ import { readdir, readFile } from 'node:fs/promises'
7
+ import { join } from 'node:path'
8
+
9
+ import type { Connection, Link } from './connection.ts'
10
+ import { InvalidError } from './errors.ts'
11
+ import { checkName, handleOn, type Settled, settle } from './handles.ts'
12
+ import { watch } from './session.ts'
13
+ import type { SqlArg, SqlValue } from './wire/codec.ts'
14
+ import {
15
+ type JobsJob,
16
+ methods,
17
+ SqlColumns,
18
+ SqlDatabase,
19
+ SqlDone,
20
+ SqlResults,
21
+ SqlRow,
22
+ SqlStatement,
23
+ SqlStatements,
24
+ } from './wire/messages.ts'
25
+
26
+ export type { SqlArg, SqlValue }
27
+
28
+ /** A row as SQLite returned it, by its columns' names. */
29
+ export type Row = Record<string, SqlValue>
30
+
31
+ /**
32
+ * A database's migrations: a directory whose .sql files they are, at its root
33
+ * or in its one directory, or the files themselves by name.
34
+ */
35
+ export type Migrations = string | Record<string, string> | readonly { name: string; text: string }[]
36
+
37
+ export interface SqlOptions {
38
+ /** what the first open applies, on an admin connection, and every later open checks */
39
+ migrations?: Migrations
40
+ }
41
+
42
+ /** What a write changed: the rows, and the rowid of the last it inserted. */
43
+ export interface Done {
44
+ changes: number
45
+ lastId: number
46
+ }
47
+
48
+ /**
49
+ * A statement's text and arguments, in any of the three ways a call takes
50
+ * them: positional after the text, one object of named ones, or a template
51
+ * whose values are its arguments.
52
+ *
53
+ * db.all('select * from notes where id = ?', id)
54
+ * db.all('select * from notes where id = :id', { id })
55
+ * db.all`select * from notes where id = ${id}`
56
+ */
57
+ export type Statement = [sql: string | TemplateStringsArray, ...args: unknown[]]
58
+
59
+ function statementOf(given: Statement): {
60
+ sql: string
61
+ args?: SqlArg[]
62
+ named?: Record<string, SqlArg>
63
+ } {
64
+ const [first, ...rest] = given
65
+ if (typeof first !== 'string') {
66
+ return { sql: first.join('?'), args: rest as SqlArg[] }
67
+ }
68
+ const only = rest[0]
69
+ if (rest.length === 1 && isNamed(only)) {
70
+ return { sql: first, named: only as Record<string, SqlArg> }
71
+ }
72
+ return { sql: first, args: rest as SqlArg[] }
73
+ }
74
+
75
+ function isNamed(value: unknown): boolean {
76
+ return (
77
+ typeof value === 'object' &&
78
+ value !== null &&
79
+ !(value instanceof Date) &&
80
+ !(value instanceof Uint8Array) &&
81
+ !Array.isArray(value)
82
+ )
83
+ }
84
+
85
+ /** Opens a database by its name, applying or checking its migrations. */
86
+ export async function openDatabase(
87
+ link: Link,
88
+ name: string,
89
+ options?: SqlOptions,
90
+ ): Promise<Database> {
91
+ checkName(name, 'database')
92
+ const migrations =
93
+ options?.migrations === undefined ? undefined : await migrationFiles(options.migrations)
94
+ const open = SqlDatabase.encode({ name, migrations })
95
+ const db = new Database(link, name, open)
96
+ await link.run('write', connection => db.handle(connection))
97
+ return db
98
+ }
99
+
100
+ async function migrationFiles(given: Migrations): Promise<{ name: string; text: string }[]> {
101
+ if (typeof given !== 'string') {
102
+ const files = Array.isArray(given)
103
+ ? [...given]
104
+ : Object.entries(given).map(([name, text]) => ({ name, text }))
105
+ return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
106
+ }
107
+ let dir = given
108
+ let entries = await readdir(dir, { withFileTypes: true })
109
+ if (!entries.some(e => e.isFile() && e.name.endsWith('.sql'))) {
110
+ const dirs = entries.filter(e => e.isDirectory())
111
+ if (dirs.length === 1) {
112
+ dir = join(dir, dirs[0]!.name)
113
+ entries = await readdir(dir, { withFileTypes: true })
114
+ }
115
+ }
116
+ const names = entries
117
+ .filter(e => e.isFile() && e.name.endsWith('.sql'))
118
+ .map(e => e.name)
119
+ .sort()
120
+ if (names.length === 0) {
121
+ throw new InvalidError(`no .sql migrations in ${given}`)
122
+ }
123
+ return Promise.all(
124
+ names.map(async name => ({ name, text: await readFile(join(dir, name), 'utf8') })),
125
+ )
126
+ }
127
+
128
+ /** Reads a query's rows as objects, refusing two columns of one name, which one object cannot hold. */
129
+ function rowsOf<T>(columns: string[], rows: SqlValue[][]): T[] {
130
+ if (new Set(columns).size !== columns.length) {
131
+ const twice = columns.find((c, i) => columns.indexOf(c) !== i)
132
+ throw new InvalidError(`two columns named ${twice}: name them apart with as`)
133
+ }
134
+ return rows.map(values => {
135
+ const row: Record<string, SqlValue> = {}
136
+ columns.forEach((column, i) => {
137
+ row[column] = values[i] ?? null
138
+ })
139
+ return row as T
140
+ })
141
+ }
142
+
143
+ function one<T>(rows: T[]): T | undefined {
144
+ if (rows.length > 1) {
145
+ throw new InvalidError(`a query for one row answered ${rows.length}`)
146
+ }
147
+ return rows[0]
148
+ }
149
+
150
+ function scalar<T>(columns: string[], rows: SqlValue[][]): T {
151
+ if (rows.length === 0) {
152
+ throw new InvalidError('a scalar query answered no row; one always answers, as count(*) does')
153
+ }
154
+ if (columns.length !== 1 || rows.length > 1) {
155
+ throw new InvalidError(
156
+ `a scalar query answered ${rows.length} rows of ${columns.length} columns`,
157
+ )
158
+ }
159
+ return rows[0]![0] as T
160
+ }
161
+
162
+ /**
163
+ * A database. What a call's name starts with says where it runs: exec and
164
+ * its kin may write and run on the file's one writer, grouped with the other
165
+ * writes; all, one, scalar and each read, on readers that refuse to write.
166
+ */
167
+ export class Database {
168
+ readonly name: string
169
+ readonly #link: Link
170
+ readonly #open: Uint8Array
171
+
172
+ constructor(link: Link, name: string, open: Uint8Array) {
173
+ this.#link = link
174
+ this.name = name
175
+ this.#open = open
176
+ }
177
+
178
+ handle(connection: Connection): Promise<number> {
179
+ return handleOn(connection, methods['sql.open'], this.#open)
180
+ }
181
+
182
+ async #query(given: Statement, write: boolean, signal?: AbortSignal) {
183
+ const statement = statementOf(given)
184
+ return this.#link.run(write ? 'write' : 'read', async connection => {
185
+ const handle = await this.handle(connection)
186
+ const stream = await connection.session.open(
187
+ methods['sql.query'],
188
+ SqlStatement.encode({ handle, ...statement, write: write || undefined }),
189
+ true,
190
+ )
191
+ const unwatch = watch(signal, stream)
192
+ try {
193
+ const head = await stream.next()
194
+ const columns = SqlColumns.decode(head.body).columns ?? []
195
+ const rows: SqlValue[][] = []
196
+ for (;;) {
197
+ const event = await stream.next()
198
+ stream.consumed(event.body.length)
199
+ if (event.end) {
200
+ return { columns, rows }
201
+ }
202
+ rows.push((SqlRow.decode(event.body).values ?? []) as SqlValue[])
203
+ }
204
+ } finally {
205
+ unwatch()
206
+ }
207
+ })
208
+ }
209
+
210
+ /** Every row a query answers, held in memory: the server refuses past 64 MiB of them. */
211
+ async all<T = Row>(...statement: Statement): Promise<T[]> {
212
+ const { columns, rows } = await this.#query(statement, false)
213
+ return rowsOf<T>(columns, rows)
214
+ }
215
+
216
+ /** The one row a query answers, undefined for none; two is InvalidError. */
217
+ async one<T = Row>(...statement: Statement): Promise<T | undefined> {
218
+ return one(await this.all<T>(...statement))
219
+ }
220
+
221
+ /** The one value of a query that always answers one row, as count(*) does. */
222
+ async scalar<T = SqlValue>(...statement: Statement): Promise<T> {
223
+ const { columns, rows } = await this.#query(statement, false)
224
+ return scalar<T>(columns, rows)
225
+ }
226
+
227
+ /** The columns and rows of a query as SQLite returned them, arrays rather than objects. */
228
+ query(...statement: Statement): Promise<{ columns: string[]; rows: SqlValue[][] }> {
229
+ return this.#query(statement, false)
230
+ }
231
+
232
+ /**
233
+ * Reads a query's rows one at a time as they arrive, within the credit
234
+ * the client grants: the client holds a row and the frames in flight.
235
+ */
236
+ async *each<T = Row>(...statement: Statement): AsyncGenerator<T> {
237
+ const { sql, args, named } = statementOf(statement)
238
+ const connection = await this.#link.connection()
239
+ const handle = await this.handle(connection)
240
+ const stream = await connection.session.open(
241
+ methods['sql.query'],
242
+ SqlStatement.encode({ handle, sql, args, named }),
243
+ true,
244
+ )
245
+ let ended = false
246
+ try {
247
+ const columns = SqlColumns.decode((await stream.next()).body).columns ?? []
248
+ rowsOf(columns, [])
249
+ for (;;) {
250
+ const event = await stream.next()
251
+ stream.consumed(event.body.length)
252
+ if (event.end) {
253
+ ended = true
254
+ return
255
+ }
256
+ yield rowsOf<T>(columns, [(SqlRow.decode(event.body).values ?? []) as SqlValue[]])[0]!
257
+ }
258
+ } finally {
259
+ if (!ended) {
260
+ stream.cancel()
261
+ }
262
+ }
263
+ }
264
+
265
+ /** Runs a statement on the writer and says what it changed. */
266
+ async exec(...statement: Statement): Promise<Done> {
267
+ const given = statementOf(statement)
268
+ return this.#link.run('write', async connection => {
269
+ const handle = await this.handle(connection)
270
+ const body = await connection.session.call(
271
+ methods['sql.exec'],
272
+ SqlStatement.encode({ handle, ...given }),
273
+ )
274
+ const done = SqlDone.decode(body)
275
+ return { changes: done.changes ?? 0, lastId: done.lastId ?? 0 }
276
+ })
277
+ }
278
+
279
+ /** The rows a write's returning clause answers, run on the writer. */
280
+ async execAll<T = Row>(...statement: Statement): Promise<T[]> {
281
+ const { columns, rows } = await this.#query(statement, true)
282
+ return rowsOf<T>(columns, rows)
283
+ }
284
+
285
+ async execOne<T = Row>(...statement: Statement): Promise<T | undefined> {
286
+ return one(await this.execAll<T>(...statement))
287
+ }
288
+
289
+ async execScalar<T = SqlValue>(...statement: Statement): Promise<T> {
290
+ const { columns, rows } = await this.#query(statement, true)
291
+ return scalar<T>(columns, rows)
292
+ }
293
+
294
+ /**
295
+ * Runs the statements fn asks for in one transaction, all or none: a
296
+ * failure names its statement as `call`. fn returns before anything is
297
+ * sent, since no transaction is held across the network, and what it
298
+ * returns comes back answered, an array's promises each:
299
+ *
300
+ * const [note] = await db.batch(tx => [tx.one`insert into notes (title) values (${t}) returning *`])
301
+ */
302
+ batch<const T = void>(fn: (tx: SqlBatch) => T): Promise<Settled<T>> {
303
+ return this.#run(false, fn)
304
+ }
305
+
306
+ /**
307
+ * Runs the reads fn asks for from one snapshot, and gives back what fn
308
+ * returns, answered as batch answers it:
309
+ *
310
+ * const [notes, total] = await db.view(tx => [tx.all`select * from notes`, tx.scalar`select count(*) from notes`])
311
+ */
312
+ view<const T = void>(fn: (tx: SqlBatch) => T): Promise<Settled<T>> {
313
+ return this.#run(true, fn)
314
+ }
315
+
316
+ async #run<T>(read: boolean, fn: (tx: SqlBatch) => T): Promise<Settled<T>> {
317
+ const tx = new SqlBatch(read, this.name)
318
+ const returned = fn(tx)
319
+ tx.close()
320
+ if (returned instanceof Promise && !tx.made(returned)) {
321
+ throw new InvalidError(
322
+ 'a batch function returns before anything is sent; it cannot await inside',
323
+ )
324
+ }
325
+ if (tx.statements.length > 0 || tx.jobs.length > 0) {
326
+ await this.#send(read, tx)
327
+ }
328
+ return settle(returned)
329
+ }
330
+
331
+ async #send(read: boolean, tx: SqlBatch): Promise<void> {
332
+ try {
333
+ const results = await this.#link.run(read ? 'read' : 'write', async connection => {
334
+ const handle = await this.handle(connection)
335
+ const jobs = []
336
+ for (const queued of tx.jobs) {
337
+ const queue = await handleOn(connection, methods['jobs.open'], queued.open)
338
+ jobs.push({ handle: queue, jobs: [queued.job] })
339
+ }
340
+ const body = await connection.session.call(
341
+ methods['sql.batch'],
342
+ SqlStatements.encode({
343
+ handle,
344
+ statements: tx.statements.map(s => s.statement),
345
+ read: read || undefined,
346
+ jobs: jobs.length > 0 ? jobs : undefined,
347
+ }),
348
+ )
349
+ return SqlResults.decode(body).results ?? []
350
+ })
351
+ tx.statements.forEach((s, i) => {
352
+ s.settle(results[i] ?? {})
353
+ })
354
+ for (const queued of tx.jobs) {
355
+ queued.settle()
356
+ }
357
+ } catch (err) {
358
+ for (const s of [...tx.statements, ...tx.jobs]) {
359
+ s.fail(err)
360
+ }
361
+ throw err
362
+ }
363
+ }
364
+ }
365
+
366
+ type Result = ReturnType<typeof SqlResults.decode>['results'] extends (infer R)[] | undefined
367
+ ? R
368
+ : never
369
+
370
+ interface Batched {
371
+ statement: Parameters<typeof SqlStatement.encode>[0]
372
+ settle: (result: Result) => void
373
+ fail: (err: unknown) => void
374
+ }
375
+
376
+ /** A job a batch enqueues after its statements, on a queue that lives in its database. */
377
+ interface Queued {
378
+ /** the queue's jobs.open, whose handle the batch opens on its connection */
379
+ open: Uint8Array
380
+ job: Parameters<typeof JobsJob.encode>[0]
381
+ settle: () => void
382
+ fail: (err: unknown) => void
383
+ }
384
+
385
+ /** The statements of a batch or a view, whose promises settle with it. */
386
+ export class SqlBatch {
387
+ readonly read: boolean
388
+ /** the database the batch runs in, whose queues alone take its jobs */
389
+ readonly database: string
390
+ readonly statements: Batched[] = []
391
+ readonly jobs: Queued[] = []
392
+ #done = false
393
+ readonly #made = new WeakSet<Promise<unknown>>()
394
+
395
+ constructor(read: boolean, database: string) {
396
+ this.read = read
397
+ this.database = database
398
+ }
399
+
400
+ close(): void {
401
+ this.#done = true
402
+ }
403
+
404
+ /** Whether the promise is one of this batch's statements', rather than an async function's. */
405
+ made(promise: Promise<unknown>): boolean {
406
+ return this.#made.has(promise)
407
+ }
408
+
409
+ /**
410
+ * Adds a job to the batch, for a queue's withTx: a program writes
411
+ * `queue.withTx(tx).enqueue(value)`, on a queue opened `in` this database.
412
+ */
413
+ enqueue(open: Uint8Array, job: Queued['job']): Promise<void> {
414
+ if (this.read) {
415
+ throw new InvalidError('a job in a view, which reads')
416
+ }
417
+ const { promise, settle, fail } = this.#promise<void>()
418
+ this.jobs.push({ open, job, settle: () => settle(undefined), fail })
419
+ return promise
420
+ }
421
+
422
+ #promise<T>(): { promise: Promise<T>; settle: (v: T) => void; fail: (err: unknown) => void } {
423
+ if (this.#done) {
424
+ throw new InvalidError(
425
+ 'a batch takes its statements while its function runs, before it is sent',
426
+ )
427
+ }
428
+ let settle!: (v: T) => void
429
+ let fail!: (e: unknown) => void
430
+ const promise = new Promise<T>((res, rej) => {
431
+ settle = res
432
+ fail = rej
433
+ })
434
+ // a caller need not await a call it only wanted done
435
+ promise.catch(() => {})
436
+ this.#made.add(promise)
437
+ return { promise, settle, fail }
438
+ }
439
+
440
+ #record<T>(given: Statement, rows: boolean, settle: (result: Result) => T): Promise<T> {
441
+ const statement = statementOf(given)
442
+ const { promise: settled, settle: resolve, fail: reject } = this.#promise<T>()
443
+ this.statements.push({
444
+ statement: { ...statement, rows: rows && !this.read ? true : undefined },
445
+ settle: result => {
446
+ try {
447
+ resolve(settle(result))
448
+ } catch (err) {
449
+ reject(err)
450
+ }
451
+ },
452
+ fail: reject,
453
+ })
454
+ return settled
455
+ }
456
+
457
+ exec(...statement: Statement): Promise<Done> {
458
+ return this.#record(statement, false, r => ({ changes: r.changes ?? 0, lastId: r.lastId ?? 0 }))
459
+ }
460
+
461
+ all<T = Row>(...statement: Statement): Promise<T[]> {
462
+ return this.#record(statement, true, r =>
463
+ rowsOf<T>(r.columns ?? [], (r.rows ?? []) as SqlValue[][]),
464
+ )
465
+ }
466
+
467
+ one<T = Row>(...statement: Statement): Promise<T | undefined> {
468
+ return this.#record(statement, true, r =>
469
+ one(rowsOf<T>(r.columns ?? [], (r.rows ?? []) as SqlValue[][])),
470
+ )
471
+ }
472
+
473
+ scalar<T = SqlValue>(...statement: Statement): Promise<T> {
474
+ return this.#record(statement, true, r =>
475
+ scalar<T>(r.columns ?? [], (r.rows ?? []) as SqlValue[][]),
476
+ )
477
+ }
478
+ }
package/src/store.ts ADDED
@@ -0,0 +1,219 @@
1
+ import { randomBytes } from 'node:crypto'
2
+ import { open as openFile, rename, rm } from 'node:fs/promises'
3
+
4
+ import { Blobs } from './blobs.ts'
5
+ import { Clock } from './clock.ts'
6
+ import { Link, privateChild, remote, sidecar } from './connection.ts'
7
+ import { ClosedError, InvalidError } from './errors.ts'
8
+ import { Jobs } from './jobs.ts'
9
+ import { Kv } from './kv.ts'
10
+ import { Metrics } from './metrics.ts'
11
+ import { Records } from './records.ts'
12
+ import { bunRuntime } from './runtime/bun.ts'
13
+ import { nodeRuntime } from './runtime/node.ts'
14
+ import type { Runtime, TlsOptions } from './runtime.ts'
15
+ import { type Database, openDatabase, type SqlOptions } from './sql.ts'
16
+ import { type Duration, ms, type Time, unixMs } from './time.ts'
17
+ import { Empty, methods } from './wire/messages.ts'
18
+
19
+ export interface OpenOptions {
20
+ /**
21
+ * A server of this process's own, a child on stdin and stdout that lives
22
+ * and dies with it, rather than the directory's shared sidecar: tests,
23
+ * scripts, one process alone.
24
+ */
25
+ private?: boolean
26
+ /** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
27
+ binary?: string
28
+ /**
29
+ * How long a sidecar this process starts stays once its last connection
30
+ * has gone: 30 s unless given, 0 for ever. One found running keeps its own.
31
+ */
32
+ idle?: Duration
33
+ /**
34
+ * Runs a private server on a test's clock, starting at this time, which
35
+ * `store.clock` moves forward instead of a test waiting: keys expire, jobs
36
+ * come due and records age at once. Needs `private`.
37
+ */
38
+ clock?: Time
39
+ }
40
+
41
+ /** What a server is, as its WELCOME said it to this store's connection. */
42
+ export interface Status {
43
+ /** its version: v0.1.0, or (devel) for one built from a checkout */
44
+ server: string
45
+ protocol: number
46
+ /** the engines it serves */
47
+ engines: string[]
48
+ /** admin may change a schema and drop records; data reads and writes */
49
+ capability: 'admin' | 'data'
50
+ }
51
+
52
+ export interface ConnectOptions {
53
+ /** a line of the server's tokens file, admin or data */
54
+ token: string
55
+ tls?: TlsOptions
56
+ }
57
+
58
+ /**
59
+ * The store in a directory, as another process serves it. Close it once, as
60
+ * a Go program closes its tinystore.Store: `await using store = await open(dir)`.
61
+ */
62
+ export class Store implements AsyncDisposable {
63
+ readonly kv: Kv
64
+ readonly jobs: Jobs
65
+ readonly blobs: Blobs
66
+ readonly records: Records
67
+ readonly metrics: Metrics
68
+ /** The test's clock of a private store opened with `clock`; on any other, its calls are InvalidError. */
69
+ readonly clock: Clock
70
+ readonly #link: Link
71
+
72
+ constructor(link: Link) {
73
+ this.#link = link
74
+ this.clock = new Clock(link)
75
+ this.kv = new Kv(link)
76
+ this.jobs = new Jobs(link)
77
+ this.blobs = new Blobs(link)
78
+ this.records = new Records(link)
79
+ this.metrics = new Metrics(link)
80
+ }
81
+
82
+ /**
83
+ * What the server this store reaches is: its version, the protocol the
84
+ * connection speaks, the engines it serves and what the connection may do.
85
+ * A client newer than its server learns here what it may ask for; a call
86
+ * past it is UnimplementedError, naming the server's version.
87
+ */
88
+ async status(): Promise<Status> {
89
+ const agreed = await (await this.#link.connection()).session.welcomed
90
+ return {
91
+ server: agreed.server,
92
+ protocol: Number(agreed.protocol),
93
+ engines: [...agreed.engines],
94
+ capability: agreed.capability === 'admin' ? 'admin' : 'data',
95
+ }
96
+ }
97
+
98
+ /**
99
+ * Opens a database of the application's own, sql/<name>.db. The first open
100
+ * in the server, on an admin connection, applies its migrations; every
101
+ * later one checks them against what the file applied.
102
+ */
103
+ sql(name: string, options?: SqlOptions): Promise<Database> {
104
+ return openDatabase(this.#link, name, options)
105
+ }
106
+
107
+ /**
108
+ * Writes a backup of the whole store to a zip at path while the store keeps
109
+ * working, as `tinystore backup` does: every engine's file, with its size
110
+ * and checksum, which `tinystore restore` checks. The zip is written beside
111
+ * path and renamed into place once whole, so a backup that fails leaves no
112
+ * zip. It needs an admin connection; a remote server sends the zip over it.
113
+ */
114
+ async backup(path: string): Promise<void> {
115
+ const part = `${path}.${randomBytes(4).toString('hex')}.part`
116
+ try {
117
+ await this.#link.run('read', async connection => {
118
+ const file = await openFile(part, 'w')
119
+ try {
120
+ const stream = await connection.session.open(
121
+ methods['server.backup'],
122
+ Empty.encode({}),
123
+ true,
124
+ )
125
+ await stream.next() // the RESPONSE that heads the zip
126
+ for (;;) {
127
+ const event = await stream.next()
128
+ stream.consumed(event.body.length)
129
+ await file.write(event.body)
130
+ if (event.end) {
131
+ break
132
+ }
133
+ }
134
+ await file.sync()
135
+ } finally {
136
+ await file.close()
137
+ }
138
+ })
139
+ await rename(part, path)
140
+ } catch (err) {
141
+ await rm(part, { force: true })
142
+ throw err
143
+ }
144
+ }
145
+
146
+ /**
147
+ * Ingests the instruments' last values and hands over the loggers' lines,
148
+ * then closes the connection. A private child is waited for until it has
149
+ * exited, so that the directory is free once this returns; the directory's
150
+ * sidecar goes once it has been idle.
151
+ */
152
+ async close(): Promise<void> {
153
+ await this.metrics.stop()
154
+ await this.records.stop()
155
+ this.kv.stop()
156
+ await this.#link.close()
157
+ }
158
+
159
+ [Symbol.asyncDispose](): Promise<void> {
160
+ return this.close()
161
+ }
162
+ }
163
+
164
+ /** Bun's own runtime under Bun, and Node's under Node. */
165
+ const runtime: Runtime = typeof Bun === 'undefined' ? nodeRuntime : bunRuntime
166
+
167
+ /**
168
+ * Opens the store in a directory through its sidecar, found through SERVE or
169
+ * started, or through a private child when asked. It returns once the server
170
+ * has answered, so that a directory that cannot be served fails here.
171
+ */
172
+ export async function open(dir: string, options: OpenOptions = {}): Promise<Store> {
173
+ return openWith(runtime, dir, options)
174
+ }
175
+
176
+ export async function openWith(
177
+ runtime: Runtime,
178
+ dir: string,
179
+ options: OpenOptions = {},
180
+ ): Promise<Store> {
181
+ const binary = () => findBinary(runtime, options.binary)
182
+ const idle = options.idle === undefined ? undefined : ms(options.idle)
183
+ if (options.clock !== undefined && options.private !== true) {
184
+ throw new InvalidError(
185
+ "a clock is a private server's: a shared sidecar runs on the system's time",
186
+ )
187
+ }
188
+ const clock = options.clock === undefined ? undefined : new Date(unixMs(options.clock))
189
+ const link = new Link(
190
+ options.private === true
191
+ ? privateChild(runtime, dir, binary, clock)
192
+ : sidecar(runtime, dir, binary, idle),
193
+ )
194
+ await link.connection()
195
+ return new Store(link)
196
+ }
197
+
198
+ /**
199
+ * Connects to a remote server: tls:// checks the server's certificate before
200
+ * the token leaves; tcp:// sends the token in the clear, for a network its
201
+ * operator trusts.
202
+ */
203
+ export async function connect(url: string, options: ConnectOptions): Promise<Store> {
204
+ const link = new Link(remote(runtime, url, options.token, options.tls))
205
+ await link.connection()
206
+ return new Store(link)
207
+ }
208
+
209
+ function findBinary(runtime: Runtime, given: string | undefined): string {
210
+ const found =
211
+ given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore')
212
+ if (found === undefined || found === '') {
213
+ throw new ClosedError(
214
+ `no tinystore binary: @tinyshed/tinystore-${process.platform}-${process.arch} is not installed; ` +
215
+ 'install it, put tinystore on PATH, or set TINYSTORE_BIN',
216
+ )
217
+ }
218
+ return found
219
+ }