@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/config.ts ADDED
@@ -0,0 +1,501 @@
1
+ // An application's settings, as Go's kv.Config makes them: the defaults, then
2
+ // a file's values, then the environment, then what update kept, which the
3
+ // server keeps field by field in kv.db and sends to every store watching the
4
+ // config. `value` is read from memory and is new after each change.
5
+
6
+ import type { Link } from './connection.ts'
7
+ import { ClosedError, InvalidError } from './errors.ts'
8
+ import { checkName, handleOn } from './handles.ts'
9
+ import { check, type StandardSchemaV1 } from './schema.ts'
10
+ import type { Stream } from './session.ts'
11
+ import { KvBucket, KvCall, KvConfigure, KvKept, methods } from './wire/messages.ts'
12
+
13
+ /** A value of T with any of its fields, at any depth, left out. */
14
+ export type DeepPartial<T> = {
15
+ [K in keyof T]?: T[K] extends readonly unknown[]
16
+ ? T[K]
17
+ : T[K] extends object
18
+ ? DeepPartial<T[K]>
19
+ : T[K]
20
+ }
21
+
22
+ export interface ConfigOptions<T> {
23
+ /** a file's values over the defaults, as Bun reads YAML, JSON or TOML: `import file from './config.yaml'` */
24
+ file?: DeepPartial<T>
25
+ /** the variables' prefix: 'APP' reads APP_PORT; none when absent */
26
+ prefix?: string
27
+ /** a field's own variable, by its path: `{ dbUrl: 'DATABASE_URL' }`; false reads none */
28
+ env?: Record<string, string> | false
29
+ /** paths set by the defaults, the file or the environment alone: never kept, shown as *** */
30
+ secret?: readonly string[]
31
+ /** checks the config each time it is made: zod's, valibot's or another Standard Schema */
32
+ schema?: StandardSchemaV1<unknown, T>
33
+ }
34
+
35
+ /** Where a field's value came from. */
36
+ export interface Source {
37
+ path: string
38
+ /** its JSON, or *** for a secret */
39
+ value: string
40
+ /** 'default', 'file', 'env NAME' or 'kept' */
41
+ from: string
42
+ /** why a kept value is left out, when it is */
43
+ ignored?: string
44
+ }
45
+
46
+ /**
47
+ * A field's variable: the prefix and its path in upper snake case, as Go's and
48
+ * Python's configs name it.
49
+ *
50
+ * 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
51
+ */
52
+ export function envName(prefix: string, path: string): string {
53
+ const chars = [...path]
54
+ let name = ''
55
+ chars.forEach((c, i) => {
56
+ if (c === '.' || c === '-') {
57
+ name += '_'
58
+ return
59
+ }
60
+ const before = chars[i - 1]
61
+ const after = chars[i + 1]
62
+ if (i > 0 && isUpper(c) && before !== undefined) {
63
+ const lowerAfter = after !== undefined && isLower(after)
64
+ if (isLower(before) || isDigit(before) || (isUpper(before) && lowerAfter)) {
65
+ name += '_'
66
+ }
67
+ }
68
+ name += c.toUpperCase()
69
+ })
70
+ return prefix === '' ? name : `${prefix}_${name}`
71
+ }
72
+
73
+ const isUpper = (c: string) => c !== c.toLowerCase() && c === c.toUpperCase()
74
+ const isLower = (c: string) => c !== c.toUpperCase() && c === c.toLowerCase()
75
+ const isDigit = (c: string) => c >= '0' && c <= '9'
76
+
77
+ /** A config: open it with `store.kv.config(name, defaults, options)`. */
78
+ export class Config<T extends object> {
79
+ readonly name: string
80
+ readonly #link: Link
81
+ readonly #open: Uint8Array
82
+ readonly #leaves: Map<string, unknown>
83
+ readonly #base: Record<string, unknown>
84
+ readonly #from: Map<string, string>
85
+ readonly #secret: Set<string>
86
+ readonly #schema: StandardSchemaV1<unknown, T> | undefined
87
+ readonly #listeners = new Set<(value: T) => void>()
88
+ #kept = new Map<string, string>()
89
+ #ignored = new Map<string, string>()
90
+ #value: T
91
+ #stream: Stream | undefined
92
+ #closed = false
93
+
94
+ /** Configs come from `store.kv.config`, which waits for the first state. */
95
+ constructor(link: Link, name: string, defaults: T, options: ConfigOptions<T>) {
96
+ checkName(name, 'config')
97
+ this.#link = link
98
+ this.name = name
99
+ this.#open = KvBucket.encode({ name, config: true })
100
+ this.#leaves = new Map(leavesOf(defaults))
101
+ this.#schema = options.schema
102
+ this.#secret = new Set(options.secret ?? [])
103
+ for (const path of this.#secret) {
104
+ this.#leaf(path)
105
+ }
106
+ this.#from = new Map([...this.#leaves.keys()].map(path => [path, 'default']))
107
+ this.#base = layered(this.#leaves, defaults, options, this.#from)
108
+ this.#value = deepFreeze(structuredClone(this.#base)) as T
109
+ }
110
+
111
+ /** The config now, frozen: update changes it. */
112
+ get value(): T {
113
+ return this.#value
114
+ }
115
+
116
+ /**
117
+ * Changes the fields change names, at any depth; each one that changed is
118
+ * checked, kept, and seen by every store watching the config. A change the
119
+ * schema refuses, or one of a secret, is InvalidError and keeps nothing.
120
+ */
121
+ async update(change: DeepPartial<T>): Promise<void> {
122
+ const next = merged(structuredClone(this.#value) as Record<string, unknown>, change)
123
+ const set: string[] = []
124
+ for (const path of this.#leaves.keys()) {
125
+ const now = JSON.stringify(pathIn(next, path))
126
+ if (now === JSON.stringify(pathIn(this.#value, path))) {
127
+ continue
128
+ }
129
+ if (this.#secret.has(path)) {
130
+ throw new InvalidError(
131
+ `config ${this.name}: ${path} is a secret, set by the defaults, the file or the environment alone`,
132
+ )
133
+ }
134
+ set.push(path, now)
135
+ }
136
+ if (set.length === 0) {
137
+ return
138
+ }
139
+ await this.#checked(next)
140
+ await this.#send(set, [])
141
+ }
142
+
143
+ /** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
144
+ async reset(...paths: string[]): Promise<void> {
145
+ for (const path of paths) {
146
+ if (![...this.#leaves.keys()].some(leaf => under(leaf, path))) {
147
+ throw new InvalidError(`config ${this.name} has no field ${path}`)
148
+ }
149
+ }
150
+ const reset = [...this.#kept.keys()].filter(
151
+ kept => paths.length === 0 || paths.some(path => under(kept, path)),
152
+ )
153
+ if (reset.length > 0) {
154
+ await this.#send([], reset)
155
+ }
156
+ }
157
+
158
+ /** Calls fn with the config now and after each change, whoever made it; the function it returns stops that. */
159
+ watch(fn: (value: T) => void): () => void {
160
+ this.#listeners.add(fn)
161
+ fn(this.#value)
162
+ return () => this.#listeners.delete(fn)
163
+ }
164
+
165
+ /** Where each field's value came from, and why a kept value is left out. */
166
+ sources(): Source[] {
167
+ return [...this.#leaves.keys()].map(path => {
168
+ const kept = this.#kept.has(path) && !this.#ignored.has(path)
169
+ const source: Source = {
170
+ path,
171
+ value: this.#secret.has(path)
172
+ ? '***'
173
+ : (JSON.stringify(pathIn(this.#value, path)) ?? 'null'),
174
+ from: kept ? 'kept' : (this.#from.get(path) ?? 'default'),
175
+ }
176
+ const ignored = this.#ignored.get(path)
177
+ return ignored === undefined ? source : { ...source, ignored }
178
+ })
179
+ }
180
+
181
+ /** Follows the config's changes until the store closes; resolves once the first state is read. */
182
+ start(): Promise<void> {
183
+ return new Promise((resolve, reject) => {
184
+ void this.#follow(resolve, reject)
185
+ })
186
+ }
187
+
188
+ /** Stops following the config, as the store does when it closes. */
189
+ stop(): void {
190
+ this.#closed = true
191
+ this.#stream?.cancel()
192
+ }
193
+
194
+ async #follow(ready: () => void, failed: (err: unknown) => void): Promise<void> {
195
+ let first = true
196
+ for (let pause = 100; !this.#closed; pause = Math.min(pause * 2, 5000)) {
197
+ try {
198
+ await this.#link.run('read', async connection => {
199
+ const handle = await handleOn(connection, methods['kv.open'], this.#open)
200
+ const stream = await connection.session.open(
201
+ methods['kv.watch'],
202
+ KvCall.encode({ handle }),
203
+ true,
204
+ )
205
+ this.#stream = stream
206
+ await stream.next()
207
+ for (;;) {
208
+ const event = await stream.next()
209
+ stream.consumed(event.body.length)
210
+ if (event.end) {
211
+ return
212
+ }
213
+ await this.#apply(KvKept.decode(event.body).fields ?? [])
214
+ pause = 100
215
+ if (first) {
216
+ first = false
217
+ ready()
218
+ }
219
+ }
220
+ })
221
+ } catch (err) {
222
+ if (first) {
223
+ failed(err)
224
+ return
225
+ }
226
+ if (this.#closed || err instanceof ClosedError) {
227
+ return
228
+ }
229
+ }
230
+ await new Promise(resolve => setTimeout(resolve, pause))
231
+ }
232
+ }
233
+
234
+ /** Keeps set, path and JSON each, and forgets reset, then makes the config with them. */
235
+ async #send(set: string[], reset: string[]): Promise<void> {
236
+ await this.#link.run('write', async connection => {
237
+ const handle = await handleOn(connection, methods['kv.open'], this.#open)
238
+ const body = KvConfigure.encode({
239
+ handle,
240
+ set: set.length > 0 ? set : undefined,
241
+ reset: reset.length > 0 ? reset : undefined,
242
+ })
243
+ await connection.session.call(methods['kv.configure'], body)
244
+ })
245
+ const kept = new Map(this.#kept)
246
+ for (let i = 0; i + 1 < set.length; i += 2) {
247
+ kept.set(set[i] as string, set[i + 1] as string)
248
+ }
249
+ for (const path of reset) {
250
+ kept.delete(path)
251
+ }
252
+ await this.#build(kept)
253
+ }
254
+
255
+ /** Takes up the kept fields a watch sent. */
256
+ async #apply(fields: string[]): Promise<void> {
257
+ const kept = new Map<string, string>()
258
+ for (let i = 0; i + 1 < fields.length; i += 2) {
259
+ kept.set(fields[i] as string, fields[i + 1] as string)
260
+ }
261
+ await this.#build(kept)
262
+ }
263
+
264
+ /** Makes the config from its base and what is kept, leaving out what no longer fits, and tells the watchers. */
265
+ async #build(kept: Map<string, string>): Promise<void> {
266
+ const ignored = new Map<string, string>()
267
+ let next = withKept(this.#base, this.#leaves, kept, ignored)
268
+ let issues = await this.#issues(next)
269
+ if (issues !== undefined && kept.size > ignored.size) {
270
+ for (const path of kept.keys()) {
271
+ ignored.set(path, ignored.get(path) ?? `the config fails with it: ${issues}`)
272
+ }
273
+ next = structuredClone(this.#base)
274
+ issues = await this.#issues(next)
275
+ }
276
+ if (issues !== undefined) {
277
+ throw new InvalidError(`config ${this.name}: ${issues}`)
278
+ }
279
+ const changed = JSON.stringify(next) !== JSON.stringify(this.#value)
280
+ this.#kept = kept
281
+ this.#ignored = ignored
282
+ this.#value = deepFreeze(next) as T
283
+ if (changed) {
284
+ for (const listener of this.#listeners) {
285
+ listener(this.#value)
286
+ }
287
+ }
288
+ }
289
+
290
+ async #checked(value: Record<string, unknown>): Promise<void> {
291
+ const issues = await this.#issues(value)
292
+ if (issues !== undefined) {
293
+ throw new InvalidError(`config ${this.name}: ${issues}`)
294
+ }
295
+ }
296
+
297
+ async #issues(value: Record<string, unknown>): Promise<string | undefined> {
298
+ if (this.#schema === undefined) {
299
+ return undefined
300
+ }
301
+ const checked = await check(this.#schema, value)
302
+ return 'issues' in checked ? checked.issues : undefined
303
+ }
304
+
305
+ #leaf(path: string): unknown {
306
+ if (!this.#leaves.has(path)) {
307
+ throw new InvalidError(`config ${this.name} has no field ${path}`)
308
+ }
309
+ return this.#leaves.get(path)
310
+ }
311
+ }
312
+
313
+ /** The defaults, the file and the environment, each over the one before. */
314
+ function layered<T>(
315
+ leaves: Map<string, unknown>,
316
+ defaults: T,
317
+ options: ConfigOptions<T>,
318
+ from: Map<string, string>,
319
+ ): Record<string, unknown> {
320
+ const base = structuredClone(defaults) as Record<string, unknown>
321
+ if (options.file !== undefined) {
322
+ for (const [path, value] of leavesOf(options.file)) {
323
+ const wanted = leaves.get(path)
324
+ if (!leaves.has(path)) {
325
+ continue
326
+ }
327
+ if (!fits(value, wanted)) {
328
+ throw new InvalidError(
329
+ `the file's ${path}: ${JSON.stringify(value)} is no ${kindOf(wanted)}`,
330
+ )
331
+ }
332
+ setPath(base, path, value)
333
+ from.set(path, 'file')
334
+ }
335
+ }
336
+ if (options.env === false) {
337
+ return base
338
+ }
339
+ for (const [path, wanted] of leaves) {
340
+ const name = options.env?.[path] ?? envName(options.prefix ?? '', path)
341
+ const text = process.env[name]
342
+ if (text !== undefined) {
343
+ setPath(base, path, fromEnv(text, wanted, name))
344
+ from.set(path, `env ${name}`)
345
+ }
346
+ }
347
+ return base
348
+ }
349
+
350
+ /** The base with each kept value that fits its field over it. */
351
+ function withKept(
352
+ base: Record<string, unknown>,
353
+ leaves: Map<string, unknown>,
354
+ kept: Map<string, string>,
355
+ ignored: Map<string, string>,
356
+ ): Record<string, unknown> {
357
+ const next = structuredClone(base)
358
+ for (const [path, spelled] of kept) {
359
+ if (!leaves.has(path)) {
360
+ ignored.set(path, 'the config has no such field')
361
+ continue
362
+ }
363
+ let value: unknown
364
+ try {
365
+ value = JSON.parse(spelled)
366
+ } catch {
367
+ ignored.set(path, `${spelled} is no JSON`)
368
+ continue
369
+ }
370
+ if (!fits(value, leaves.get(path))) {
371
+ ignored.set(path, `${spelled} is no ${kindOf(leaves.get(path))}`)
372
+ continue
373
+ }
374
+ setPath(next, path, value)
375
+ }
376
+ return next
377
+ }
378
+
379
+ /**
380
+ * A variable's text as a value of its default's kind: a number, true or
381
+ * false, a list split at its commas or given as JSON, and anything else as JSON.
382
+ *
383
+ * 8080 ← '3000' → 3000, ['x'] ← 'a.com, b.com' → ['a.com', 'b.com']
384
+ */
385
+ function fromEnv(text: string, wanted: unknown, name: string): unknown {
386
+ const trimmed = text.trim()
387
+ if (typeof wanted === 'string') {
388
+ return text
389
+ }
390
+ if (typeof wanted === 'number') {
391
+ const n = Number(trimmed)
392
+ if (trimmed === '' || !Number.isFinite(n)) {
393
+ throw new InvalidError(`${name}: ${JSON.stringify(text)} is no number`)
394
+ }
395
+ return n
396
+ }
397
+ if (typeof wanted === 'boolean') {
398
+ if (['1', 't', 'T', 'TRUE', 'true', 'True'].includes(trimmed)) {
399
+ return true
400
+ }
401
+ if (['0', 'f', 'F', 'FALSE', 'false', 'False'].includes(trimmed)) {
402
+ return false
403
+ }
404
+ throw new InvalidError(`${name}: ${JSON.stringify(text)} is not true or false`)
405
+ }
406
+ if (Array.isArray(wanted) && !trimmed.startsWith('[')) {
407
+ const item = wanted[0] ?? ''
408
+ return trimmed === '' ? [] : trimmed.split(',').map(part => fromEnv(part.trim(), item, name))
409
+ }
410
+ try {
411
+ const value: unknown = JSON.parse(trimmed)
412
+ if (fits(value, wanted)) {
413
+ return value
414
+ }
415
+ } catch {
416
+ // refused below, naming the variable
417
+ }
418
+ throw new InvalidError(`${name}: ${JSON.stringify(text)} is no ${kindOf(wanted)}`)
419
+ }
420
+
421
+ /** A value's fields to the last that is not a plain object, by their dotted paths. */
422
+ function leavesOf(value: unknown, parent = ''): [string, unknown][] {
423
+ const leaves: [string, unknown][] = []
424
+ for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
425
+ const path = parent === '' ? key : `${parent}.${key}`
426
+ if (plain(inner)) {
427
+ leaves.push(...leavesOf(inner, path))
428
+ } else {
429
+ leaves.push([path, inner])
430
+ }
431
+ }
432
+ return leaves
433
+ }
434
+
435
+ function plain(value: unknown): value is Record<string, unknown> {
436
+ return (
437
+ typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)
438
+ )
439
+ }
440
+
441
+ /** A value fits a field when it is of its default's kind; a default of null takes anything. */
442
+ function fits(value: unknown, wanted: unknown): boolean {
443
+ if (wanted === null || wanted === undefined) {
444
+ return true
445
+ }
446
+ if (Array.isArray(wanted)) {
447
+ return Array.isArray(value)
448
+ }
449
+ return typeof value === typeof wanted && (typeof wanted !== 'object' || plain(value))
450
+ }
451
+
452
+ function kindOf(wanted: unknown): string {
453
+ return Array.isArray(wanted) ? 'list' : typeof wanted
454
+ }
455
+
456
+ function pathIn(tree: unknown, path: string): unknown {
457
+ let at = tree
458
+ for (const name of path.split('.')) {
459
+ if (!plain(at)) {
460
+ return undefined
461
+ }
462
+ at = at[name]
463
+ }
464
+ return at
465
+ }
466
+
467
+ function setPath(tree: Record<string, unknown>, path: string, value: unknown): void {
468
+ const names = path.split('.')
469
+ let at = tree
470
+ for (const name of names.slice(0, -1)) {
471
+ const inner = at[name]
472
+ if (!plain(inner)) {
473
+ at[name] = {}
474
+ }
475
+ at = at[name] as Record<string, unknown>
476
+ }
477
+ at[names[names.length - 1] as string] = value
478
+ }
479
+
480
+ /** change merged into tree at every depth; a list is replaced whole. */
481
+ function merged(tree: Record<string, unknown>, change: unknown): Record<string, unknown> {
482
+ for (const [key, value] of Object.entries(change as Record<string, unknown>)) {
483
+ const inner = tree[key]
484
+ tree[key] = plain(value) && plain(inner) ? merged(inner, value) : value
485
+ }
486
+ return tree
487
+ }
488
+
489
+ function under(path: string, given: string): boolean {
490
+ return path === given || path.startsWith(`${given}.`)
491
+ }
492
+
493
+ function deepFreeze<V>(value: V): V {
494
+ if (typeof value === 'object' && value !== null) {
495
+ for (const inner of Object.values(value)) {
496
+ deepFreeze(inner)
497
+ }
498
+ Object.freeze(value)
499
+ }
500
+ return value
501
+ }