@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.
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/dist/store.d.ts CHANGED
@@ -1,13 +1,23 @@
1
- import { Blobs } from './blobs.ts';
1
+ import { type Backup, type BackupOptions } from './backup.ts';
2
+ import { type Files, type FilesOptions } from './blobs.ts';
3
+ import { Channel } from './channels.ts';
2
4
  import { Clock } from './clock.ts';
3
- import { Link } from './connection.ts';
4
- import { Jobs } from './jobs.ts';
5
- import { Kv } from './kv.ts';
5
+ import { Config, type ConfigOptions, type Layer, type Value } from './config.ts';
6
+ import { type Durability, Link, type SelfMetrics } from './connection.ts';
7
+ import { type Queue, type QueueOptions, type Run, type Schedule, type ScheduleOptions, type ScheduleWhen } from './jobs.ts';
8
+ import { Bucket, type BucketOptions, Counters, type CountersOptions } from './kv.ts';
9
+ import { Quota, type Rate, RateLimit, type RateLimitOptions } from './limits.ts';
10
+ import { Lock, type LockOptions, Semaphore, type SemaphoreOptions } from './locks.ts';
11
+ import { type Logger } from './logger.ts';
6
12
  import { Metrics } from './metrics.ts';
7
- import { Records } from './records.ts';
13
+ import { Once, type OnceOptions } from './once.ts';
14
+ import { AllEvents, type Events, type EventsOptions, type StoreLoggerOptions } from './records.ts';
8
15
  import type { Runtime, TlsOptions } from './runtime.ts';
9
- import { type Database, type SqlOptions } from './sql.ts';
16
+ import type { StandardSchemaV1 } from './schema.ts';
17
+ import { type IndexInfo, type IndexOptions, SearchIndex } from './search.ts';
18
+ import { type Database, type DatabaseOptions } from './sql.ts';
10
19
  import { type Duration, type Time } from './time.ts';
20
+ import { type Tx } from './tx.ts';
11
21
  export interface OpenOptions {
12
22
  /**
13
23
  * A server of this process's own, a child on stdin and stdout that lives
@@ -15,6 +25,24 @@ export interface OpenOptions {
15
25
  * scripts, one process alone.
16
26
  */
17
27
  private?: boolean;
28
+ /**
29
+ * The core inside this process, loaded from its library, rather than a
30
+ * server beside it: no process and no socket.
31
+ */
32
+ embedded?: boolean;
33
+ /**
34
+ * The core for `embedded`: under Bun the C library, TINYSTORE_LIBRARY when
35
+ * absent, and under Node its addon, tinystore.node, TINYSTORE_ADDON when
36
+ * absent; then this platform's package's.
37
+ */
38
+ library?: string | undefined;
39
+ /**
40
+ * Measures the store into its own metrics, under names that start with
41
+ * `tinystore_`: its commits and their waits, its files, its memory and
42
+ * the machine it runs on, which `{ system: false }` leaves out. Off
43
+ * unless asked for; a sidecar found running keeps its own.
44
+ */
45
+ selfMetrics?: SelfMetrics;
18
46
  /** The tinystore binary: TINYSTORE_BIN, this platform's package, or PATH's when absent. */
19
47
  binary?: string;
20
48
  /**
@@ -28,6 +56,60 @@ export interface OpenOptions {
28
56
  * come due and records age at once. Needs `private`.
29
57
  */
30
58
  clock?: Time;
59
+ /**
60
+ * How far a commit of the store's files goes before it returns: `'full'`
61
+ * unless given. `'os'` does not wait for the disk, so a write returns in
62
+ * microseconds, survives this program's crash, and may be lost with the
63
+ * last others to a power loss. It is the store's, set by whoever opens it
64
+ * first: a sidecar found running with another is refused. A database may
65
+ * say its own, `store.database('audit', { durability: 'full' })`.
66
+ */
67
+ durability?: Durability;
68
+ /**
69
+ * The file of the store's encryption key, which seals the values of its
70
+ * encrypted buckets: 64 hex digits, as `openssl rand -hex 32` writes, kept
71
+ * apart from the store's data. The store reads it and never makes it.
72
+ * Without it the key is `encryption.key` in the store's directory, which the
73
+ * store makes when the first encrypted bucket opens. A sidecar found
74
+ * running keeps the key it was started with.
75
+ */
76
+ encryptionKeyFile?: string;
77
+ /**
78
+ * Makes the store a node: it keeps a log of each file it writes, serves
79
+ * its files to other nodes, and copies the files of the node it takes
80
+ * from, reading them here and passing their writes to their home. A draft,
81
+ * as its names are:
82
+ *
83
+ * const store = await open('./data', { embedded: true, node: { from: ['eu.internal:7444'] } })
84
+ */
85
+ node?: NodeOptions | undefined;
86
+ }
87
+ /** What a store's node is: whom it copies, and where it serves. */
88
+ export interface NodeOptions {
89
+ /** where this node takes the files it copies, `host:port`, tried in order */
90
+ from?: string[] | undefined;
91
+ /** where other nodes take files from this one, `host:port` */
92
+ serve?: string | undefined;
93
+ /** the files it copies, as `kv.db` or `sql/app.db`; every file but its own records and metrics when absent */
94
+ files?: string[] | undefined;
95
+ /** what it says to the node it takes from, and asks of the nodes that take from it; embedded alone */
96
+ token?: string | undefined;
97
+ /** the file of that token, for a server this process starts */
98
+ tokenFile?: string | undefined;
99
+ /** a write of a file this node writes answers once a node copying it holds the commit */
100
+ synchronous?: boolean | undefined;
101
+ /** the nodes, by address or id, a synchronous commit waits for one of; any node copying the file when absent */
102
+ synchronousWith?: string[] | undefined;
103
+ /**
104
+ * this node is the home of the catalog, which names each file's home: one
105
+ * node of a network, chosen by a person; the others then write each file
106
+ * they make once their claim of its name won, and need no `files`
107
+ */
108
+ catalog?: boolean | undefined;
109
+ /** where other nodes reach this one, `host:port`, when `serve` listens on every interface */
110
+ advertise?: string | undefined;
111
+ /** plain TCP on links beyond this machine, which anyone on the way reads; without it such a link takes TLS */
112
+ insecure?: boolean | undefined;
31
113
  }
32
114
  /** What a server is, as its WELCOME said it to this store's connection. */
33
115
  export interface Status {
@@ -50,14 +132,151 @@ export interface ConnectOptions {
50
132
  */
51
133
  export declare class Store implements AsyncDisposable {
52
134
  #private;
53
- readonly kv: Kv;
54
- readonly jobs: Jobs;
55
- readonly blobs: Blobs;
56
- readonly records: Records;
57
135
  readonly metrics: Metrics;
58
136
  /** The test's clock of a private store opened with `clock`; on any other, its calls are InvalidError. */
59
137
  readonly clock: Clock;
60
138
  constructor(link: Link);
139
+ /**
140
+ * A stream of events by name, made with its first event: events appended
141
+ * whole and read back by time and by what they hold. Without a name, every
142
+ * stream, to read.
143
+ *
144
+ * const audit = store.events('audit', { keep: '365d' })
145
+ * await audit.append('role.changed', { user: 42, role: 'admin' })
146
+ * const page = await store.events().list({ since: '1h', minLevel: 'warn' })
147
+ */
148
+ events(): AllEvents;
149
+ events(stream: string, options?: EventsOptions): Events;
150
+ /**
151
+ * A logger of the stream: each line printed as it is logged and kept
152
+ * within a second, and a call never waits; what its buffer has no room
153
+ * for is dropped and counted. The store's close hands over what it holds.
154
+ * Its options are the config `log`'s, whose level a change of any process
155
+ * sets for every logger of the store once each has its config open:
156
+ *
157
+ * const log = store.logger('api', { redact: secrets })
158
+ * log.info('signed in', { user: 42 })
159
+ * const settings = await store.config('log', [{ level: live('info') }])
160
+ * await settings.update({ level: 'debug' })
161
+ */
162
+ logger(stream: string, options?: StoreLoggerOptions): Logger;
163
+ /**
164
+ * A bucket of values by key, JSON unless `type` says otherwise:
165
+ *
166
+ * const sessions = store.bucket<Session>('sessions', { idle: '30d' })
167
+ * const codes = store.bucket<number>('login-codes', { ttl: '15m', type: 'int' })
168
+ * const seen = store.bucket('stripe-events', { ttl: '7d' }) // keys alone: a set
169
+ */
170
+ bucket<T = unknown>(name: string, options?: BucketOptions): Bucket<T>;
171
+ /** Numbers by key that only add up: `store.counters('login-attempts', { ttl: '15m' })`. */
172
+ counters(name: string, options?: CountersOptions): Counters;
173
+ /** A smooth rate of requests a key: `store.rateLimit('api', { rate: '100/s', burst: 20 })`. */
174
+ rateLimit(name: string, options: RateLimitOptions): RateLimit;
175
+ /**
176
+ * Uses by key in named windows, each counted from a key's first use, all
177
+ * of them or none: `store.quota('ai', { daily: '100/1d', weekly: '300/7d' })`.
178
+ */
179
+ quota<W extends string>(name: string, windows: Record<W, Rate>): Quota<W>;
180
+ /**
181
+ * Documents of one type set by id and found again by their words, by
182
+ * vectors the program's model gives them, or by both:
183
+ *
184
+ * const articles = store.index<Article>('articles', { fields: { title: 2, body: 1 } })
185
+ * const { hits } = await articles.search('как испечь хлеб')
186
+ *
187
+ * Opening an index with other settings than it holds changes it, and
188
+ * never waits for the work a change needs.
189
+ */
190
+ index<T = unknown>(name: string, options?: IndexOptions): SearchIndex<T>;
191
+ /**
192
+ * Opens an index as `index` does and reads it again beside itself in the
193
+ * background: a change `rebuild: 'manual'` left waiting, or its documents
194
+ * numbered again. It answers once the rebuild began; `ready()` waits for it.
195
+ */
196
+ reindex<T = unknown>(name: string, options?: IndexOptions): Promise<SearchIndex<T>>;
197
+ /** Drops an index and every document it holds, in the background; says whether there was one. */
198
+ dropIndex(name: string): Promise<boolean>;
199
+ /** Every index the store holds: its documents and vectors, when it was last opened, and a rebuild under way. */
200
+ indexes(): Promise<IndexInfo[]>;
201
+ /**
202
+ * Messages of one type that every subscriber listening when one is
203
+ * published receives, in memory and at most once:
204
+ * `const chat = store.channel<Chat>('chat'); await chat.under(roomId).publish(message)`.
205
+ */
206
+ channel<T = unknown>(name: string): Channel<T>;
207
+ /**
208
+ * Keys held one holder at a time, across every program of the store:
209
+ * `await store.lock('invoices').hold(invoice.id, lease => charge(invoice, lease.fence))`.
210
+ */
211
+ lock(name: string, options?: LockOptions): Lock;
212
+ /** Keys held by up to `limit` at a time: `store.semaphore('uploads', { limit: 3 })`. */
213
+ semaphore(name: string, options: SemaphoreOptions): Semaphore;
214
+ /** A function run once a key, its JSON answer kept a day unless `keep` says: `store.once<Receipt>('charges')`. */
215
+ once<T = unknown>(name: string, options?: OnceOptions): Once<T>;
216
+ /**
217
+ * A queue of jobs of one type, JSON, run in the order of their time; a
218
+ * Standard Schema, zod's or valibot's, gives it its type and checks each
219
+ * value before a handler gets it:
220
+ *
221
+ * const emails = store.queue<Email>('emails', { attempts: 20, backoff: { initial: '5s', max: '30m' } })
222
+ * const refreshes = store.queue('refreshes', { schema: Refresh, concurrency: { total: 8, group: 2 } })
223
+ */
224
+ queue<S extends StandardSchemaV1>(name: string, options: QueueOptions & {
225
+ schema: S;
226
+ }): Queue<StandardSchemaV1.InferOutput<S>>;
227
+ queue<T = unknown>(name: string, options?: QueueOptions): Queue<T>;
228
+ /**
229
+ * A repeat the code owns: one repeating job under name, and handler run at
230
+ * each of its times, started at once as a queue's work is. The code's
231
+ * repeat replaces the one kept each time the program opens it.
232
+ *
233
+ * store.schedule('cleanup', { cron: '10 3 * * *', timeZone: 'Europe/Berlin' }, async run => {
234
+ * await purgeDeletedBefore(daysBefore(run.at, 30))
235
+ * })
236
+ */
237
+ schedule(name: string, when: ScheduleWhen, handler: (run: Run) => unknown, options?: ScheduleOptions): Schedule;
238
+ /**
239
+ * Runs fn as one transaction over the handles it takes in with
240
+ * `tx.with(handle)`, and gives back what fn returns. Reads go at once;
241
+ * writes commit together when fn returns, after a check that nothing it
242
+ * read has changed, and fn runs again when something did, five times at
243
+ * most, so it does nothing else that must happen once.
244
+ *
245
+ * await store.tx(async tx => {
246
+ * const left = (await tx.with(stock).get(sku)) ?? 0
247
+ * if (left < 1) throw new SoldOut()
248
+ * await tx.with(stock).set(sku, left - 1)
249
+ * })
250
+ */
251
+ tx<T>(fn: (tx: Tx) => T | Promise<T>): Promise<T>;
252
+ /**
253
+ * A program's settings as one typed value: the declaration first, every
254
+ * setting with its default, then objects, files and the environment, each
255
+ * over the ones before it, and a live setting's change over them all.
256
+ *
257
+ * const config = await store.config('app', [
258
+ * { port: 8080, db: { url: secret(String) }, limits: { rps: live(100) } },
259
+ * file('app.yaml'),
260
+ * env('APP', { vars: { port: 'PORT' } }),
261
+ * ])
262
+ *
263
+ * It follows every change, whoever makes it, until the store closes; the
264
+ * same config opened again in the process shares its one stream.
265
+ */
266
+ config<D extends object>(name: string, layers: readonly [D, ...NoInfer<Layer<D>>[]], options?: ConfigOptions<Value<D>>): Promise<Config<D>>;
267
+ /**
268
+ * A backup of every engine of the store as one zip, made while the store
269
+ * keeps working, written beside `path` and renamed once whole, so that a
270
+ * backup that fails leaves no zip. A file of the program's goes in only
271
+ * when `include` names it, and the store's encryption key only when
272
+ * `includeEncryptionKey` asks; `tinystore restore` puts it back into an empty
273
+ * directory, every byte checked. Through a server, it takes an admin's
274
+ * token.
275
+ *
276
+ * const backup = await store.backup('backup-2026-10-13.zip', { include: ['secret.key'] })
277
+ * if (backup.keyLeftOut) console.warn('keep encryption.key apart: the backup opens with it alone')
278
+ */
279
+ backup(path: string, options?: BackupOptions): Promise<Backup>;
61
280
  /**
62
281
  * What the server this store reaches is: its version, the protocol the
63
282
  * connection speaks, the engines it serves and what the connection may do.
@@ -66,24 +285,25 @@ export declare class Store implements AsyncDisposable {
66
285
  */
67
286
  status(): Promise<Status>;
68
287
  /**
69
- * Opens a database of the application's own, sql/<name>.db. The first open
70
- * in the server, on an admin connection, applies its migrations; every
71
- * later one checks them against what the file applied. Without migrations
72
- * it opens the file as it is, an empty one if there is none, and checks
73
- * nothing.
288
+ * A named set of files by path, written whole and replaced whole:
289
+ *
290
+ * const avatars = store.files('avatars')
291
+ * const reports = store.files('reports', { ttl: '24h', maxFileSize: '2GiB' })
74
292
  */
75
- sql(name: string, options?: SqlOptions): Promise<Database>;
293
+ files(name: string, options?: FilesOptions): Files;
76
294
  /**
77
- * Writes a backup of the whole store to a zip at path while the store keeps
78
- * working, as `tinystore backup` does: every engine's file, with its size
79
- * and checksum, which `tinystore restore` checks. The zip is written beside
80
- * path and renamed into place once whole, so a backup that fails leaves no
81
- * zip. It needs an admin connection; a remote server sends the zip over it.
295
+ * The application's database name, sql/<name>.db, once its migrations
296
+ * are applied and checked: a migration that fails, or one changed after
297
+ * it was applied, is told here, at the start. Without migrations the file
298
+ * opens as it is, an empty one when there is none.
299
+ *
300
+ * const db = await store.database('app', { migrations: `${import.meta.dir}/migrations` })
82
301
  */
83
- backup(path: string): Promise<void>;
302
+ database(name: string, options?: DatabaseOptions): Promise<Database>;
84
303
  /**
85
- * Ingests the instruments' last values and hands over the loggers' lines,
86
- * then closes the connection. A private child is waited for until it has
304
+ * Stops every worker, each once its handlers under way have answered,
305
+ * ingests the instruments' last values, hands over the loggers' lines and
306
+ * cancels every config's stream, then closes the connection. A private child is waited for until it has
87
307
  * exited, so that the directory is free once this returns; the directory's
88
308
  * sidecar goes once it has been idle.
89
309
  */