@tinyshed/tinystore 0.1.0-rc.4 → 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.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/src/store.ts CHANGED
@@ -1,20 +1,78 @@
1
- import { randomBytes } from 'node:crypto'
2
- import { open as openFile, rename, rm } from 'node:fs/promises'
3
-
4
- import { Blobs } from './blobs.ts'
1
+ import { type Backup, type BackupOptions, backup } from './backup.ts'
2
+ import { type Files, type FilesOptions, openFiles } from './blobs.ts'
3
+ import { Channel } from './channels.ts'
5
4
  import { Clock } from './clock.ts'
6
- import { Link, privateChild, remote, sidecar } from './connection.ts'
5
+ import { Config, type ConfigOptions, type Layer, type Value } from './config.ts'
6
+ import {
7
+ asking,
8
+ checkDurability,
9
+ type Durability,
10
+ embedded,
11
+ Link,
12
+ privateChild,
13
+ remote,
14
+ type SelfMetrics,
15
+ sidecar,
16
+ } from './connection.ts'
7
17
  import { ClosedError, InvalidError } from './errors.ts'
8
- import { Jobs } from './jobs.ts'
9
- import { Kv } from './kv.ts'
18
+ import { Instruments } from './instruments.ts'
19
+ import {
20
+ openQueue,
21
+ openSchedule,
22
+ type Queue,
23
+ type QueueOptions,
24
+ type Run,
25
+ type Schedule,
26
+ type ScheduleOptions,
27
+ type ScheduleWhen,
28
+ type Worker,
29
+ } from './jobs.ts'
30
+ import {
31
+ Bucket,
32
+ type BucketOptions,
33
+ bucketOpen,
34
+ Counters,
35
+ type CountersOptions,
36
+ countersOpen,
37
+ type Values,
38
+ valuesOf,
39
+ } from './kv.ts'
40
+ import {
41
+ Quota,
42
+ quotaOpen,
43
+ type Rate,
44
+ RateLimit,
45
+ type RateLimitOptions,
46
+ rateLimitOpen,
47
+ } from './limits.ts'
48
+ import { Lock, type LockOptions, Semaphore, type SemaphoreOptions } from './locks.ts'
49
+ import { type Logger, sayOwn } from './logger.ts'
10
50
  import { Metrics } from './metrics.ts'
11
- import { Records } from './records.ts'
51
+ import { Once, type OnceOptions, onceOpen } from './once.ts'
52
+ import {
53
+ AllEvents,
54
+ type Events,
55
+ type EventsOptions,
56
+ openEvents,
57
+ type StoreLoggerOptions,
58
+ storeLogger,
59
+ } from './records.ts'
12
60
  import { bunRuntime } from './runtime/bun.ts'
13
61
  import { nodeRuntime } from './runtime/node.ts'
62
+ import { platformPackage } from './runtime/shared.ts'
14
63
  import type { Runtime, TlsOptions } from './runtime.ts'
15
- import { type Database, openDatabase, type SqlOptions } from './sql.ts'
64
+ import type { StandardSchemaV1 } from './schema.ts'
65
+ import {
66
+ dropIndex,
67
+ type IndexInfo,
68
+ type IndexOptions,
69
+ indexOpen,
70
+ listIndexes,
71
+ SearchIndex,
72
+ } from './search.ts'
73
+ import { type Database, type DatabaseOptions, openDatabase } from './sql.ts'
16
74
  import { type Duration, ms, type Time, unixMs } from './time.ts'
17
- import { Empty, methods } from './wire/messages.ts'
75
+ import { runTx, type Tx } from './tx.ts'
18
76
 
19
77
  export interface OpenOptions {
20
78
  /**
@@ -23,6 +81,24 @@ export interface OpenOptions {
23
81
  * scripts, one process alone.
24
82
  */
25
83
  private?: boolean
84
+ /**
85
+ * The core inside this process, loaded from its library, rather than a
86
+ * server beside it: no process and no socket.
87
+ */
88
+ embedded?: boolean
89
+ /**
90
+ * The core for `embedded`: under Bun the C library, TINYSTORE_LIBRARY when
91
+ * absent, and under Node its addon, tinystore.node, TINYSTORE_ADDON when
92
+ * absent; then this platform's package's.
93
+ */
94
+ library?: string | undefined
95
+ /**
96
+ * Measures the store into its own metrics, under names that start with
97
+ * `tinystore_`: its commits and their waits, its files, its memory and
98
+ * the machine it runs on, which `{ system: false }` leaves out. Off
99
+ * unless asked for; a sidecar found running keeps its own.
100
+ */
101
+ selfMetrics?: SelfMetrics
26
102
  /** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
27
103
  binary?: string
28
104
  /**
@@ -36,6 +112,61 @@ export interface OpenOptions {
36
112
  * come due and records age at once. Needs `private`.
37
113
  */
38
114
  clock?: Time
115
+ /**
116
+ * How far a commit of the store's files goes before it returns: `'full'`
117
+ * unless given. `'os'` does not wait for the disk, so a write returns in
118
+ * microseconds, survives this program's crash, and may be lost with the
119
+ * last others to a power loss. It is the store's, set by whoever opens it
120
+ * first: a sidecar found running with another is refused. A database may
121
+ * say its own, `store.database('audit', { durability: 'full' })`.
122
+ */
123
+ durability?: Durability
124
+ /**
125
+ * The file of the store's encryption key, which seals the values of its
126
+ * encrypted buckets: 64 hex digits, as `openssl rand -hex 32` writes, kept
127
+ * apart from the store's data. The store reads it and never makes it.
128
+ * Without it the key is `encryption.key` in the store's directory, which the
129
+ * store makes when the first encrypted bucket opens. A sidecar found
130
+ * running keeps the key it was started with.
131
+ */
132
+ encryptionKeyFile?: string
133
+ /**
134
+ * Makes the store a node: it keeps a log of each file it writes, serves
135
+ * its files to other nodes, and copies the files of the node it takes
136
+ * from, reading them here and passing their writes to their home. A draft,
137
+ * as its names are:
138
+ *
139
+ * const store = await open('./data', { embedded: true, node: { from: ['eu.internal:7444'] } })
140
+ */
141
+ node?: NodeOptions | undefined
142
+ }
143
+
144
+ /** What a store's node is: whom it copies, and where it serves. */
145
+ export interface NodeOptions {
146
+ /** where this node takes the files it copies, `host:port`, tried in order */
147
+ from?: string[] | undefined
148
+ /** where other nodes take files from this one, `host:port` */
149
+ serve?: string | undefined
150
+ /** the files it copies, as `kv.db` or `sql/app.db`; every file but its own records and metrics when absent */
151
+ files?: string[] | undefined
152
+ /** what it says to the node it takes from, and asks of the nodes that take from it; embedded alone */
153
+ token?: string | undefined
154
+ /** the file of that token, for a server this process starts */
155
+ tokenFile?: string | undefined
156
+ /** a write of a file this node writes answers once a node copying it holds the commit */
157
+ synchronous?: boolean | undefined
158
+ /** the nodes, by address or id, a synchronous commit waits for one of; any node copying the file when absent */
159
+ synchronousWith?: string[] | undefined
160
+ /**
161
+ * this node is the home of the catalog, which names each file's home: one
162
+ * node of a network, chosen by a person; the others then write each file
163
+ * they make once their claim of its name won, and need no `files`
164
+ */
165
+ catalog?: boolean | undefined
166
+ /** where other nodes reach this one, `host:port`, when `serve` listens on every interface */
167
+ advertise?: string | undefined
168
+ /** plain TCP on links beyond this machine, which anyone on the way reads; without it such a link takes TLS */
169
+ insecure?: boolean | undefined
39
170
  }
40
171
 
41
172
  /** What a server is, as its WELCOME said it to this store's connection. */
@@ -60,23 +191,258 @@ export interface ConnectOptions {
60
191
  * a Go program closes its tinystore.Store: `await using store = await open(dir)`.
61
192
  */
62
193
  export class Store implements AsyncDisposable {
63
- readonly kv: Kv
64
- readonly jobs: Jobs
65
- readonly blobs: Blobs
66
- readonly records: Records
67
194
  readonly metrics: Metrics
68
195
  /** The test's clock of a private store opened with `clock`; on any other, its calls are InvalidError. */
69
196
  readonly clock: Clock
70
197
  readonly #link: Link
198
+ /** the configs open, by what opened them, so that the same open shares one stream */
199
+ readonly #configs = new Map<
200
+ string,
201
+ { config: Promise<{ stop(): Promise<void> }>; validate: unknown }
202
+ >()
203
+ readonly #workers = new Set<Worker>()
204
+ readonly #loggers = new Set<Logger>()
205
+ readonly #instruments: Instruments
206
+ #closing = false
71
207
 
72
208
  constructor(link: Link) {
73
209
  this.#link = link
74
210
  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)
211
+ this.#instruments = new Instruments(link)
212
+ this.metrics = new Metrics(link, this.#instruments)
213
+ }
214
+
215
+ /**
216
+ * A stream of events by name, made with its first event: events appended
217
+ * whole and read back by time and by what they hold. Without a name, every
218
+ * stream, to read.
219
+ *
220
+ * const audit = store.events('audit', { keep: '365d' })
221
+ * await audit.append('role.changed', { user: 42, role: 'admin' })
222
+ * const page = await store.events().list({ since: '1h', minLevel: 'warn' })
223
+ */
224
+ events(): AllEvents
225
+ events(stream: string, options?: EventsOptions): Events
226
+ events(stream?: string, options?: EventsOptions): Events | AllEvents {
227
+ return stream === undefined
228
+ ? new AllEvents(this.#link)
229
+ : openEvents(this.#link, stream, options)
230
+ }
231
+
232
+ /**
233
+ * A logger of the stream: each line printed as it is logged and kept
234
+ * within a second, and a call never waits; what its buffer has no room
235
+ * for is dropped and counted. The store's close hands over what it holds.
236
+ * Its options are the config `log`'s, whose level a change of any process
237
+ * sets for every logger of the store once each has its config open:
238
+ *
239
+ * const log = store.logger('api', { redact: secrets })
240
+ * log.info('signed in', { user: 42 })
241
+ * const settings = await store.config('log', [{ level: live('info') }])
242
+ * await settings.update({ level: 'debug' })
243
+ */
244
+ logger(stream: string, options?: StoreLoggerOptions): Logger {
245
+ const [logger, log] = storeLogger(this.#link, stream, options)
246
+ this.#loggers.add(logger)
247
+ this.config('log', log.layers).then(
248
+ config => void config.watch(value => log.take(value.level)),
249
+ (err: unknown) => {
250
+ if (!this.#closing) {
251
+ saidUnfollowed(err)
252
+ }
253
+ },
254
+ )
255
+ return logger
256
+ }
257
+
258
+ /**
259
+ * A bucket of values by key, JSON unless `type` says otherwise:
260
+ *
261
+ * const sessions = store.bucket<Session>('sessions', { idle: '30d' })
262
+ * const codes = store.bucket<number>('login-codes', { ttl: '15m', type: 'int' })
263
+ * const seen = store.bucket('stripe-events', { ttl: '7d' }) // keys alone: a set
264
+ */
265
+ bucket<T = unknown>(name: string, options?: BucketOptions): Bucket<T> {
266
+ const values = valuesOf(options?.type) as Values<T>
267
+ return new Bucket<T>(this.#link, name, bucketOpen(name, options), values, [])
268
+ }
269
+
270
+ /** Numbers by key that only add up: `store.counters('login-attempts', { ttl: '15m' })`. */
271
+ counters(name: string, options?: CountersOptions): Counters {
272
+ return new Counters(this.#link, name, countersOpen(name, options), [])
273
+ }
274
+
275
+ /** A smooth rate of requests a key: `store.rateLimit('api', { rate: '100/s', burst: 20 })`. */
276
+ rateLimit(name: string, options: RateLimitOptions): RateLimit {
277
+ return new RateLimit(this.#link, name, rateLimitOpen(name, options), [])
278
+ }
279
+
280
+ /**
281
+ * Uses by key in named windows, each counted from a key's first use, all
282
+ * of them or none: `store.quota('ai', { daily: '100/1d', weekly: '300/7d' })`.
283
+ */
284
+ quota<W extends string>(name: string, windows: Record<W, Rate>): Quota<W> {
285
+ return new Quota<W>(this.#link, name, quotaOpen(name, windows), [])
286
+ }
287
+
288
+ /**
289
+ * Documents of one type set by id and found again by their words, by
290
+ * vectors the program's model gives them, or by both:
291
+ *
292
+ * const articles = store.index<Article>('articles', { fields: { title: 2, body: 1 } })
293
+ * const { hits } = await articles.search('как испечь хлеб')
294
+ *
295
+ * Opening an index with other settings than it holds changes it, and
296
+ * never waits for the work a change needs.
297
+ */
298
+ index<T = unknown>(name: string, options?: IndexOptions): SearchIndex<T> {
299
+ return new SearchIndex<T>(this.#link, name, indexOpen(name, options))
300
+ }
301
+
302
+ /**
303
+ * Opens an index as `index` does and reads it again beside itself in the
304
+ * background: a change `rebuild: 'manual'` left waiting, or its documents
305
+ * numbered again. It answers once the rebuild began; `ready()` waits for it.
306
+ */
307
+ async reindex<T = unknown>(name: string, options?: IndexOptions): Promise<SearchIndex<T>> {
308
+ const index = new SearchIndex<T>(this.#link, name, indexOpen(name, options, true))
309
+ await index.status()
310
+ return index
311
+ }
312
+
313
+ /** Drops an index and every document it holds, in the background; says whether there was one. */
314
+ dropIndex(name: string): Promise<boolean> {
315
+ return dropIndex(this.#link, name)
316
+ }
317
+
318
+ /** Every index the store holds: its documents and vectors, when it was last opened, and a rebuild under way. */
319
+ indexes(): Promise<IndexInfo[]> {
320
+ return listIndexes(this.#link)
321
+ }
322
+
323
+ /**
324
+ * Messages of one type that every subscriber listening when one is
325
+ * published receives, in memory and at most once:
326
+ * `const chat = store.channel<Chat>('chat'); await chat.under(roomId).publish(message)`.
327
+ */
328
+ channel<T = unknown>(name: string): Channel<T> {
329
+ return new Channel<T>(this.#link, name)
330
+ }
331
+
332
+ /**
333
+ * Keys held one holder at a time, across every program of the store:
334
+ * `await store.lock('invoices').hold(invoice.id, lease => charge(invoice, lease.fence))`.
335
+ */
336
+ lock(name: string, options?: LockOptions): Lock {
337
+ return new Lock(this.#link, name, options)
338
+ }
339
+
340
+ /** Keys held by up to `limit` at a time: `store.semaphore('uploads', { limit: 3 })`. */
341
+ semaphore(name: string, options: SemaphoreOptions): Semaphore {
342
+ return new Semaphore(this.#link, name, options)
343
+ }
344
+
345
+ /** A function run once a key, its JSON answer kept a day unless `keep` says: `store.once<Receipt>('charges')`. */
346
+ once<T = unknown>(name: string, options?: OnceOptions): Once<T> {
347
+ return new Once<T>(this.#link, name, onceOpen(name, options), [])
348
+ }
349
+
350
+ /**
351
+ * A queue of jobs of one type, JSON, run in the order of their time; a
352
+ * Standard Schema, zod's or valibot's, gives it its type and checks each
353
+ * value before a handler gets it:
354
+ *
355
+ * const emails = store.queue<Email>('emails', { attempts: 20, backoff: { initial: '5s', max: '30m' } })
356
+ * const refreshes = store.queue('refreshes', { schema: Refresh, concurrency: { total: 8, group: 2 } })
357
+ */
358
+ queue<S extends StandardSchemaV1>(
359
+ name: string,
360
+ options: QueueOptions & { schema: S },
361
+ ): Queue<StandardSchemaV1.InferOutput<S>>
362
+ queue<T = unknown>(name: string, options?: QueueOptions): Queue<T>
363
+ queue(name: string, options: QueueOptions & { schema?: StandardSchemaV1 } = {}): Queue<unknown> {
364
+ return openQueue(this.#link, this.#workers, name, options)
365
+ }
366
+
367
+ /**
368
+ * A repeat the code owns: one repeating job under name, and handler run at
369
+ * each of its times, started at once as a queue's work is. The code's
370
+ * repeat replaces the one kept each time the program opens it.
371
+ *
372
+ * store.schedule('cleanup', { cron: '10 3 * * *', timeZone: 'Europe/Berlin' }, async run => {
373
+ * await purgeDeletedBefore(daysBefore(run.at, 30))
374
+ * })
375
+ */
376
+ schedule(
377
+ name: string,
378
+ when: ScheduleWhen,
379
+ handler: (run: Run) => unknown,
380
+ options?: ScheduleOptions,
381
+ ): Schedule {
382
+ return openSchedule(this.#link, this.#workers, name, when, handler, options)
383
+ }
384
+
385
+ /**
386
+ * Runs fn as one transaction over the handles it takes in with
387
+ * `tx.with(handle)`, and gives back what fn returns. Reads go at once;
388
+ * writes commit together when fn returns, after a check that nothing it
389
+ * read has changed, and fn runs again when something did, five times at
390
+ * most, so it does nothing else that must happen once.
391
+ *
392
+ * await store.tx(async tx => {
393
+ * const left = (await tx.with(stock).get(sku)) ?? 0
394
+ * if (left < 1) throw new SoldOut()
395
+ * await tx.with(stock).set(sku, left - 1)
396
+ * })
397
+ */
398
+ tx<T>(fn: (tx: Tx) => T | Promise<T>): Promise<T> {
399
+ return runTx(this.#link, fn)
400
+ }
401
+
402
+ /**
403
+ * A program's settings as one typed value: the declaration first, every
404
+ * setting with its default, then objects, files and the environment, each
405
+ * over the ones before it, and a live setting's change over them all.
406
+ *
407
+ * const config = await store.config('app', [
408
+ * { port: 8080, db: { url: secret(String) }, limits: { rps: live(100) } },
409
+ * file('app.yaml'),
410
+ * env('APP', { vars: { port: 'PORT' } }),
411
+ * ])
412
+ *
413
+ * It follows every change, whoever makes it, until the store closes; the
414
+ * same config opened again in the process shares its one stream.
415
+ */
416
+ async config<D extends object>(
417
+ name: string,
418
+ layers: readonly [D, ...NoInfer<Layer<D>>[]],
419
+ options: ConfigOptions<Value<D>> = {},
420
+ ): Promise<Config<D>> {
421
+ const key = JSON.stringify([name, layers, options.strict === true])
422
+ const found = this.#configs.get(key)
423
+ if (found !== undefined && found.validate === options.validate) {
424
+ return found.config as unknown as Promise<Config<D>>
425
+ }
426
+ const config = Config.open<D>(this.#link, name, layers, options)
427
+ this.#configs.set(key, { config, validate: options.validate })
428
+ config.catch(() => this.#configs.delete(key))
429
+ return config
430
+ }
431
+
432
+ /**
433
+ * A backup of every engine of the store as one zip, made while the store
434
+ * keeps working, written beside `path` and renamed once whole, so that a
435
+ * backup that fails leaves no zip. A file of the program's goes in only
436
+ * when `include` names it, and the store's encryption key only when
437
+ * `includeEncryptionKey` asks; `tinystore restore` puts it back into an empty
438
+ * directory, every byte checked. Through a server, it takes an admin's
439
+ * token.
440
+ *
441
+ * const backup = await store.backup('backup-2026-10-13.zip', { include: ['secret.key'] })
442
+ * if (backup.keyLeftOut) console.warn('keep encryption.key apart: the backup opens with it alone')
443
+ */
444
+ backup(path: string, options: BackupOptions = {}): Promise<Backup> {
445
+ return backup(this.#link, path, options)
80
446
  }
81
447
 
82
448
  /**
@@ -96,65 +462,47 @@ export class Store implements AsyncDisposable {
96
462
  }
97
463
 
98
464
  /**
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. Without migrations
102
- * it opens the file as it is, an empty one if there is none, and checks
103
- * nothing.
104
- */
105
- sql(name: string, options?: SqlOptions): Promise<Database> {
106
- return openDatabase(this.#link, name, options)
107
- }
108
-
109
- /**
110
- * Writes a backup of the whole store to a zip at path while the store keeps
111
- * working, as `tinystore backup` does: every engine's file, with its size
112
- * and checksum, which `tinystore restore` checks. The zip is written beside
113
- * path and renamed into place once whole, so a backup that fails leaves no
114
- * zip. It needs an admin connection; a remote server sends the zip over it.
115
- */
116
- async backup(path: string): Promise<void> {
117
- const part = `${path}.${randomBytes(4).toString('hex')}.part`
118
- try {
119
- await this.#link.run('read', async connection => {
120
- const file = await openFile(part, 'w')
121
- try {
122
- const stream = await connection.session.open(
123
- methods['server.backup'],
124
- Empty.encode({}),
125
- true,
126
- )
127
- await stream.next() // the RESPONSE that heads the zip
128
- for (;;) {
129
- const event = await stream.next()
130
- stream.consumed(event.body.length)
131
- await file.write(event.body)
132
- if (event.end) {
133
- break
134
- }
135
- }
136
- await file.sync()
137
- } finally {
138
- await file.close()
139
- }
140
- })
141
- await rename(part, path)
142
- } catch (err) {
143
- await rm(part, { force: true })
144
- throw err
145
- }
465
+ * A named set of files by path, written whole and replaced whole:
466
+ *
467
+ * const avatars = store.files('avatars')
468
+ * const reports = store.files('reports', { ttl: '24h', maxFileSize: '2GiB' })
469
+ */
470
+ files(name: string, options?: FilesOptions): Files {
471
+ return openFiles(this.#link, name, options)
146
472
  }
147
473
 
148
474
  /**
149
- * Ingests the instruments' last values and hands over the loggers' lines,
150
- * then closes the connection. A private child is waited for until it has
475
+ * The application's database name, sql/<name>.db, once its migrations
476
+ * are applied and checked: a migration that fails, or one changed after
477
+ * it was applied, is told here, at the start. Without migrations the file
478
+ * opens as it is, an empty one when there is none.
479
+ *
480
+ * const db = await store.database('app', { migrations: `${import.meta.dir}/migrations` })
481
+ */
482
+ database(name: string, options?: DatabaseOptions): Promise<Database> {
483
+ return openDatabase(this.#link, this.#workers, name, options)
484
+ }
485
+
486
+ /**
487
+ * Stops every worker, each once its handlers under way have answered,
488
+ * ingests the instruments' last values, hands over the loggers' lines and
489
+ * cancels every config's stream, then closes the connection. A private child is waited for until it has
151
490
  * exited, so that the directory is free once this returns; the directory's
152
491
  * sidecar goes once it has been idle.
153
492
  */
154
493
  async close(): Promise<void> {
155
- await this.metrics.stop()
156
- await this.records.stop()
157
- this.kv.stop()
494
+ this.#closing = true
495
+ await Promise.all([...this.#workers].map(worker => worker.stop()))
496
+ await this.#instruments.stop()
497
+ await Promise.all([...this.#loggers].map(logger => logger.stop()))
498
+ await Promise.all(
499
+ [...this.#configs.values()].map(({ config }) =>
500
+ config.then(
501
+ opened => opened.stop(),
502
+ () => {},
503
+ ),
504
+ ),
505
+ )
158
506
  await this.#link.close()
159
507
  }
160
508
 
@@ -163,6 +511,18 @@ export class Store implements AsyncDisposable {
163
511
  }
164
512
  }
165
513
 
514
+ let unfollowed = false
515
+
516
+ /** Says once in a process that a store's logger follows no config `log`, its level then the code's and the environment's. */
517
+ function saidUnfollowed(err: unknown): void {
518
+ if (!unfollowed) {
519
+ unfollowed = true
520
+ sayOwn('warn', 'a logger follows no config log', {
521
+ error: err instanceof Error ? err.message : String(err),
522
+ })
523
+ }
524
+ }
525
+
166
526
  /** Bun's own runtime under Bun, and Node's under Node. */
167
527
  const runtime: Runtime = typeof Bun === 'undefined' ? nodeRuntime : bunRuntime
168
528
 
@@ -189,11 +549,21 @@ export async function openWith(
189
549
  )
190
550
  }
191
551
  const clock = options.clock === undefined ? undefined : new Date(unixMs(options.clock))
192
- const link = new Link(
193
- options.private === true
194
- ? privateChild(runtime, dir, binary, clock)
195
- : sidecar(runtime, dir, binary, idle),
196
- )
552
+ const durability = options.durability
553
+ checkDurability(durability, 'open')
554
+ const started = {
555
+ durability,
556
+ encryptionKeyFile: options.encryptionKeyFile,
557
+ node: options.node,
558
+ selfMetrics: options.selfMetrics,
559
+ }
560
+ const dial =
561
+ options.embedded === true
562
+ ? embedded(runtime, dir, () => findLibrary(runtime, options.library), started)
563
+ : options.private === true
564
+ ? privateChild(runtime, dir, binary, clock, started)
565
+ : sidecar(runtime, dir, binary, { idle, ...started })
566
+ const link = new Link(asking(dial, dir, durability))
197
567
  await link.connection()
198
568
  return new Store(link)
199
569
  }
@@ -235,13 +605,38 @@ function checkDirectory(dir: string): void {
235
605
  }
236
606
 
237
607
  function findBinary(runtime: Runtime, given: string | undefined): string {
608
+ const executable = runtime.windows ? 'tinystore.exe' : 'tinystore'
238
609
  const found =
239
- given ?? process.env.TINYSTORE_BIN ?? runtime.packagedBinary() ?? runtime.which('tinystore')
610
+ given ??
611
+ process.env.TINYSTORE_BIN ??
612
+ runtime.packaged(`bin/${executable}`) ??
613
+ runtime.which('tinystore')
240
614
  if (found === undefined || found === '') {
241
615
  throw new ClosedError(
242
- `no tinystore binary: @tinyshed/tinystore-${process.platform}-${process.arch} is not installed; ` +
616
+ `no tinystore binary: ${platformPackage()} is not installed; ` +
243
617
  'install it, put tinystore on PATH, or set TINYSTORE_BIN',
244
618
  )
245
619
  }
246
620
  return found
247
621
  }
622
+
623
+ /**
624
+ * The core an embedded store loads: under Bun the C library, under Node its
625
+ * addon; the one given, the variable's, or this platform's package's.
626
+ */
627
+ function findLibrary(runtime: Runtime, library: string | undefined): string {
628
+ const node = typeof Bun === 'undefined'
629
+ const variable = node ? 'TINYSTORE_ADDON' : 'TINYSTORE_LIBRARY'
630
+ const file = node
631
+ ? 'tinystore.node'
632
+ : ({ win32: 'tinystore_ffi.dll', darwin: 'libtinystore_ffi.dylib' }[
633
+ process.platform as string
634
+ ] ?? 'libtinystore_ffi.so')
635
+ const found = library ?? process.env[variable] ?? runtime.packaged(`lib/${file}`)
636
+ if (found === undefined || found === '') {
637
+ throw new InvalidError(
638
+ `an embedded store needs the core: ${platformPackage()} is not installed; pass library or set ${variable}`,
639
+ )
640
+ }
641
+ return found
642
+ }