@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
package/src/store.ts
CHANGED
|
@@ -1,20 +1,78 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
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 {
|
|
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 {
|
|
9
|
-
import {
|
|
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 {
|
|
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
|
|
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 {
|
|
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
|
|
76
|
-
this.
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
*
|
|
150
|
-
*
|
|
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
|
-
|
|
156
|
-
await this.
|
|
157
|
-
this.
|
|
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
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
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 ??
|
|
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:
|
|
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
|
+
}
|