@tinyshed/tinystore 0.1.0-rc.5 → 0.1.0-rc.7

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/config.ts CHANGED
@@ -1,144 +1,564 @@
1
- // An application's settings, as Go's kv.Config makes them: the defaults, then
2
- // each layer in the order given, then what update kept, which the server
3
- // keeps field by field in kv.db and sends to every store watching the config.
4
- // `value` is read from memory and is new after each change.
1
+ // A program's settings as one typed value, as docs/guides/config/README.md has it: a
2
+ // declaration, then objects, files and the environment in the order the
3
+ // program writes them, each declaring again what came before, and the live
4
+ // settings' changes, which the store keeps and every process sees. The core
5
+ // reads the layers, checks the rules and keeps the changes. This module
6
+ // spells the declaration as data, reads the program's own files and
7
+ // variables, which belong to it and not to the server, and follows the config
8
+ // on one stream that every handle and watcher of it in the process shares.
5
9
 
6
10
  import { readFile } from 'node:fs/promises'
7
11
 
8
- import type { Link } from './connection.ts'
9
- import { ClosedError, InvalidError } from './errors.ts'
10
- import { checkName, handleOn } from './handles.ts'
12
+ import type { Connection, Idempotence, Link } from './connection.ts'
13
+ import { CancelledError, ConflictError, InvalidError, UnavailableError } from './errors.ts'
11
14
  import { check, isSchema, type StandardSchemaV1 } from './schema.ts'
12
- import type { Stream } from './session.ts'
13
- import { KvBucket, KvCall, KvConfigure, KvKept, methods } from './wire/messages.ts'
15
+ import { ConnectionLostError, type Stream } from './session.ts'
16
+ import { type DurationText, ms, spelled } from './time.ts'
17
+ import type { Read } from './wire/codec.ts'
18
+ import {
19
+ ConfigOpen,
20
+ ConfigReset,
21
+ ConfigUpdate,
22
+ ConfigValue,
23
+ Handle,
24
+ methods,
25
+ } from './wire/protocol.ts'
14
26
 
15
- /** A value of T with any of its fields, at any depth, left out. */
16
- export type DeepPartial<T> = {
17
- [K in keyof T]?: T[K] extends readonly unknown[]
18
- ? T[K]
19
- : T[K] extends object
20
- ? DeepPartial<T[K]>
21
- : T[K]
27
+ // what marks a setting and a layer: text keys, so that a program's own keys
28
+ // never are one and the types say them in a published declaration
29
+ const mark = '~setting'
30
+ const layerMark = '~layer'
31
+
32
+ /** The tries a change makes while other changes race it. */
33
+ const attempts = 8
34
+
35
+ // The declaration as the core reads it: docs/guides/config/README.md, and
36
+ // crates/tinystore/src/kv/config/data.rs, which reads this JSON.
37
+ type Kind =
38
+ | 'text'
39
+ | 'integer'
40
+ | 'number'
41
+ | 'boolean'
42
+ | 'duration'
43
+ | 'object'
44
+ | 'any'
45
+ | { list: Item }
46
+ type Item = ({ kind: Kind } & Rules) | { group: Group }
47
+ type Group = Record<string, Node>
48
+ type Node = Described | { group: Group }
49
+
50
+ interface Rules {
51
+ min?: number
52
+ max?: number
53
+ oneOf?: string[]
22
54
  }
23
55
 
24
- type Kind = 'string' | 'number' | 'boolean'
56
+ interface Described extends Rules {
57
+ kind: Kind
58
+ default?: unknown
59
+ required?: boolean
60
+ live?: boolean
61
+ secret?: boolean
62
+ }
25
63
 
26
- /** A field of a config's defaults made by `secret` or `required`, in place of its value. */
27
- export class Setting<V> {
28
- readonly kind: Kind
29
- /** absent for a field a layer has to give */
30
- readonly fallback: V | undefined
31
- readonly secret: boolean
32
- /** its own variable, read in place of the prefix and its path */
33
- readonly variable: string | undefined
64
+ /**
65
+ * A setting its declaration says more of than a default would: its rules, a
66
+ * secret, one a layer must give, or one that may change while the program
67
+ * runs. `V` is what the program reads it as, `Live` whether it may change,
68
+ * and `Given` whether it has a default or is required, as a declaration needs.
69
+ */
70
+ export interface Setting<
71
+ V,
72
+ Live extends boolean = false,
73
+ Given extends boolean = true,
74
+ IsSecret extends boolean = false,
75
+ > {
76
+ readonly [mark]: Described
77
+ /** what the program reads it as; nothing at run time */
78
+ readonly '~value'?: V
79
+ readonly '~live'?: Live
80
+ readonly '~given'?: Given
81
+ readonly '~secret'?: IsSecret
82
+ }
83
+
84
+ /** A setting's text that prints as *** wherever it goes; `reveal` gives it. */
85
+ export class Secret {
86
+ readonly #text: string
34
87
 
35
- constructor(kind: Kind, fallback: V | undefined, secret: boolean, variable: string | undefined) {
36
- this.kind = kind
37
- this.fallback = fallback
38
- this.secret = secret
39
- this.variable = variable
88
+ constructor(text: string) {
89
+ this.#text = text
40
90
  }
91
+
92
+ /** The secret's text, where the program hands it to what needs it. */
93
+ reveal(): string {
94
+ return this.#text
95
+ }
96
+
97
+ toString(): string {
98
+ return '***'
99
+ }
100
+
101
+ toJSON(): string {
102
+ return '***'
103
+ }
104
+
105
+ [Symbol.for('nodejs.util.inspect.custom')](): string {
106
+ return '***'
107
+ }
108
+ }
109
+
110
+ /** What a program reads of a declaration: a setting as its value, a group as its settings. */
111
+ export type Value<D> =
112
+ D extends Setting<infer V, boolean, boolean, boolean>
113
+ ? V
114
+ : D extends string
115
+ ? string
116
+ : D extends number
117
+ ? number
118
+ : D extends boolean
119
+ ? boolean
120
+ : D extends null
121
+ ? null
122
+ : D extends readonly (infer I)[]
123
+ ? readonly Value<I>[]
124
+ : D extends object
125
+ ? { readonly [K in keyof D]: Value<D[K]> }
126
+ : never
127
+
128
+ type LiveIn<D> =
129
+ D extends Setting<unknown, infer L, boolean, boolean>
130
+ ? L
131
+ : D extends readonly unknown[]
132
+ ? false
133
+ : D extends object
134
+ ? true extends { [K in keyof D]: LiveIn<D[K]> }[keyof D]
135
+ ? true
136
+ : false
137
+ : false
138
+
139
+ /** The live settings a change may name, each as the program reads it, at any depth. */
140
+ export type Changes<D> = {
141
+ readonly [K in keyof D as LiveIn<D[K]> extends true ? K : never]?: D[K] extends Setting<
142
+ infer V,
143
+ true,
144
+ boolean,
145
+ boolean
146
+ >
147
+ ? V
148
+ : Changes<D[K]>
149
+ }
150
+
151
+ /** An object in code over the declaration: any of its settings, at any depth, a secret as text. */
152
+ export type Overlay<D> = {
153
+ readonly [K in keyof D]?: D[K] extends Setting<infer V, boolean, boolean, boolean>
154
+ ? V extends Secret
155
+ ? string
156
+ : V
157
+ : D[K] extends readonly unknown[]
158
+ ? Value<D[K]>
159
+ : D[K] extends object
160
+ ? Overlay<D[K]>
161
+ : Value<D[K]>
162
+ }
163
+
164
+ /** A file a config reads: TOML, YAML or JSON by its extension. */
165
+ export interface FileLayer {
166
+ readonly [layerMark]: 'file'
167
+ readonly path: string
168
+ readonly optional: boolean
169
+ }
170
+
171
+ /** The environment a config reads. */
172
+ export interface EnvLayer {
173
+ readonly [layerMark]: 'env'
174
+ readonly prefix: string
175
+ /** a setting's own variable, by its path */
176
+ readonly vars: Readonly<Record<string, string>>
177
+ readonly files: readonly string[]
178
+ readonly from: Readonly<Record<string, string | undefined>> | undefined
179
+ }
180
+
181
+ /** A layer of a config's list: an object in code, a file, the environment, or nothing. */
182
+ export type Layer<D> = FileLayer | EnvLayer | Overlay<D> | false | null | undefined
183
+
184
+ export interface FileOptions {
185
+ /** a file that may be absent: then it declares nothing, and explain says so */
186
+ optional?: boolean | undefined
187
+ }
188
+
189
+ /** Settings' own variables by their paths: `{ port: 'PORT', db: { url: 'DATABASE_URL' } }`. */
190
+ export interface Vars {
191
+ readonly [key: string]: string | Vars
192
+ }
193
+
194
+ export interface EnvOptions {
195
+ /** a setting's variable of its own, in place of its prefixed one */
196
+ vars?: Vars | undefined
197
+ /** .env files, whose variables count where the process has none; Bun reads .env itself */
198
+ files?: readonly string[] | undefined
199
+ /** these variables in place of the process's, the only environment read, as a test gives them */
200
+ from?: Readonly<Record<string, string | undefined>> | undefined
201
+ }
202
+
203
+ export interface ConfigOptions<V> {
204
+ /**
205
+ * the program's own check of the whole value, at open and before a change
206
+ * is kept: a Standard Schema such as zod's or valibot's, or a function
207
+ * that throws
208
+ */
209
+ validate?: StandardSchemaV1 | ((value: V) => unknown) | undefined
210
+ /** refuses to open while a kept change no longer fits, rather than ignoring it and saying so */
211
+ strict?: boolean | undefined
212
+ }
213
+
214
+ export interface UpdateOptions {
215
+ /** keeps the change only while the config is at this version, else ConflictError */
216
+ ifVersion?: number | undefined
217
+ }
218
+
219
+ /** A setting's line of explain. */
220
+ export interface ExplainLine {
221
+ readonly path: string
222
+ /** as JSON, a duration spelled, a secret as *** */
223
+ readonly value: string
224
+ /** the layer that gave it: APP_PORT, app.yaml, layer 2, the declaration, a change */
225
+ readonly from: string
226
+ /** the values it went over, newest first */
227
+ readonly over: string
228
+ }
229
+
230
+ /** Every setting's line, for console.table, and what was read and not used. */
231
+ export type Explained = readonly ExplainLine[] & { readonly notes: readonly string[] }
232
+
233
+ type Token = StringConstructor | NumberConstructor | BooleanConstructor
234
+ type Of<T> = T extends StringConstructor
235
+ ? string
236
+ : T extends NumberConstructor
237
+ ? number
238
+ : T extends BooleanConstructor
239
+ ? boolean
240
+ : never
241
+ type Primitive = string | number | boolean
242
+ type Widened<V> = V extends string
243
+ ? string
244
+ : V extends number
245
+ ? number
246
+ : V extends boolean
247
+ ? boolean
248
+ : V extends readonly (infer I)[]
249
+ ? Widened<I>[]
250
+ : V
251
+
252
+ /** The bounds of a number: the smallest and the largest it may be. */
253
+ export interface Bounds {
254
+ min?: number | undefined
255
+ max?: number | undefined
256
+ }
257
+
258
+ /** The bounds of a duration, each a duration's text. */
259
+ export interface DurationBounds {
260
+ min?: DurationText | undefined
261
+ max?: DurationText | undefined
262
+ }
263
+
264
+ /** A list's default and how many items it holds at least and at most. */
265
+ export interface ListOptions<V> extends Bounds {
266
+ default?: readonly V[] | undefined
267
+ }
268
+
269
+ function setting<V, L extends boolean = false, G extends boolean = true, S extends boolean = false>(
270
+ described: Described,
271
+ ): Setting<V, L, G, S> {
272
+ return Object.freeze({ [mark]: described }) as unknown as Setting<V, L, G, S>
273
+ }
274
+
275
+ function describedOf(value: unknown): Described | undefined {
276
+ return typeof value === 'object' && value !== null && mark in value
277
+ ? (value as { [mark]: Described })[mark]
278
+ : undefined
279
+ }
280
+
281
+ function layerOf(value: unknown): string | undefined {
282
+ return typeof value === 'object' && value !== null && layerMark in value
283
+ ? (value as { [layerMark]: string })[layerMark]
284
+ : undefined
285
+ }
286
+
287
+ function kindOf(token: Token): Kind {
288
+ return token === String ? 'text' : token === Number ? 'number' : 'boolean'
289
+ }
290
+
291
+ function bounds(rules: Bounds | undefined): Rules {
292
+ const out: Rules = {}
293
+ if (rules?.min !== undefined) {
294
+ out.min = rules.min
295
+ }
296
+ if (rules?.max !== undefined) {
297
+ out.max = rules.max
298
+ }
299
+ return out
41
300
  }
42
301
 
43
302
  /**
44
- * A secret: never kept by update, and shown as *** by sources(). It reads
45
- * its own variable when given one, and is required without a default.
46
- *
47
- * ```ts
48
- * db: { url: secret('DATABASE_URL'), pool: 10 }
49
- * ```
303
+ * A setting that prints as *** wherever it goes and that only a layer gives:
304
+ * `secret(String)` must be given, `secret('')` has a default.
50
305
  */
51
- export function secret(variable?: string, fallback?: string): Setting<string> {
52
- return new Setting('string', fallback, true, variable)
306
+ export function secret(given: StringConstructor | string): Setting<Secret, false, true, true> {
307
+ if (given === String) {
308
+ return setting({ kind: 'text', secret: true, required: true })
309
+ }
310
+ if (typeof given !== 'string') {
311
+ throw new InvalidError('a secret is text: secret(String), or secret with its default text')
312
+ }
313
+ return setting({ kind: 'text', secret: true, default: given })
53
314
  }
54
315
 
55
- /** A field a layer has to give, or the config does not open: a string unless kind says. */
56
- export function required(): Setting<string>
57
- export function required(kind: StringConstructor): Setting<string>
58
- export function required(kind: NumberConstructor): Setting<number>
59
- export function required(kind: BooleanConstructor): Setting<boolean>
316
+ /** A setting with no default: a layer must give it, or the config does not open. */
317
+ export function required<T extends Token>(type: T): Setting<Of<T>>
318
+ export function required<V>(rule: Setting<V, false, false>): Setting<V>
60
319
  export function required(
61
- kind: StringConstructor | NumberConstructor | BooleanConstructor = String,
62
- ): Setting<string | number | boolean> {
63
- return new Setting<string | number | boolean>(
64
- kind === Number ? 'number' : kind === Boolean ? 'boolean' : 'string',
65
- undefined,
66
- false,
67
- undefined,
68
- )
69
- }
70
-
71
- /** The environment as a layer of a config, which `fromEnv` makes. */
72
- export class FromEnv {
73
- readonly prefix: string
74
- readonly files: readonly string[]
320
+ given: Token | Setting<unknown, boolean, boolean, boolean>,
321
+ ): Setting<unknown> {
322
+ const inner = typeof given === 'function' ? { kind: kindOf(given) } : describedOf(given)
323
+ if (inner === undefined) {
324
+ throw new InvalidError('required takes String, Number, Boolean, or a rule without its default')
325
+ }
326
+ if (inner.secret === true) {
327
+ throw new InvalidError('a secret is required already: secret(String)')
328
+ }
329
+ if (inner.live === true) {
330
+ throw new InvalidError('live is the outermost mark: live(required(…))')
331
+ }
332
+ const { default: _default, ...rest } = inner
333
+ return setting({ ...rest, required: true })
334
+ }
335
+
336
+ /**
337
+ * A setting that may change while the program runs: its change is kept in
338
+ * the store, goes over every layer until it is reset, and reaches every
339
+ * process. `live(100)`, `live(int(100, { min: 0 }))`, `live(required(String))`.
340
+ */
341
+ export function live<V>(rule: Setting<V, false, true>): Setting<V, true>
342
+ export function live<const V extends Primitive | readonly Primitive[]>(
343
+ value: V,
344
+ ): Setting<Widened<V>, true>
345
+ export function live(given: unknown): Setting<unknown, true> {
346
+ if (isPlainObject(given) && describedOf(given) === undefined && Object.keys(given).length > 0) {
347
+ throw new InvalidError('a mark goes on a setting, not on a group: mark each of its settings')
348
+ }
349
+ const inner = describedOf(given) ?? declaredValue(given, 'live')
350
+ if (inner.secret === true) {
351
+ throw new InvalidError('a secret is never live')
352
+ }
353
+ if (inner.live === true) {
354
+ throw new InvalidError('live twice')
355
+ }
356
+ return setting({ ...inner, live: true })
357
+ }
75
358
 
76
- constructor(prefix: string, files: readonly string[]) {
77
- this.prefix = prefix
78
- this.files = files
359
+ /** A whole number in its bounds: `int(8080, { min: 1, max: 65535 })`; `int({ min: 1 })` goes in required. */
360
+ export function int(rules?: Bounds): Setting<number, false, false>
361
+ export function int(fallback: number, rules?: Bounds): Setting<number>
362
+ export function int(first?: number | Bounds, rules?: Bounds): Setting<number, boolean, boolean> {
363
+ if (typeof first === 'number') {
364
+ return setting({ kind: 'integer', default: first, ...bounds(rules) })
79
365
  }
366
+ return setting({ kind: 'integer', ...bounds(first) })
80
367
  }
81
368
 
82
369
  /**
83
- * The environment as a config's layer: `fromEnv('APP')` reads db.pool from
84
- * APP_DB_POOL, and `fromEnv()` from DB_POOL. The .env files given are read
85
- * first, the process's own variables over them, a missing file skipped.
370
+ * One of a set of texts, its default first: `oneOf('info', ['debug', 'warn', 'error'])`
371
+ * reads as 'info' | 'debug' | 'warn' | 'error'; `oneOf(['eu', 'us'])` goes in required.
86
372
  */
87
- export function fromEnv(prefix = '', ...files: string[]): FromEnv {
88
- return new FromEnv(prefix, files)
373
+ export function oneOf<const O extends readonly [string, ...string[]]>(
374
+ values: O,
375
+ ): Setting<O[number], false, false>
376
+ export function oneOf<const T extends string, const O extends readonly string[]>(
377
+ fallback: T,
378
+ others: O,
379
+ ): Setting<T | O[number]>
380
+ export function oneOf(
381
+ first: string | readonly string[],
382
+ others: readonly string[] = [],
383
+ ): Setting<string, boolean, boolean> {
384
+ if (typeof first === 'string') {
385
+ return setting({ kind: 'text', default: first, oneOf: [first, ...others] })
386
+ }
387
+ return setting({ kind: 'text', oneOf: [...first] })
388
+ }
389
+
390
+ /** A duration, read as one is written: `duration('30s')`, `duration({ max: '1h' })` in required. */
391
+ export function duration(rules?: DurationBounds): Setting<DurationText, false, false>
392
+ export function duration(fallback: DurationText, rules?: DurationBounds): Setting<DurationText>
393
+ export function duration(
394
+ first?: DurationText | DurationBounds,
395
+ rules?: DurationBounds,
396
+ ): Setting<DurationText, boolean, boolean> {
397
+ const [fallback, given] = typeof first === 'string' ? [first, rules] : [undefined, first]
398
+ const described: Described = { kind: 'duration' }
399
+ if (given?.min !== undefined) {
400
+ described.min = ms(given.min)
401
+ }
402
+ if (given?.max !== undefined) {
403
+ described.max = ms(given.max)
404
+ }
405
+ return setting(fallback === undefined ? described : { ...described, default: fallback })
89
406
  }
90
407
 
91
- /** A config's check, which `validate` makes. */
92
- export class Validate {
93
- readonly schema: StandardSchemaV1
408
+ /**
409
+ * A list: of `String`, `Number` or `Boolean`, of a rule, or of groups, each
410
+ * item checked; its `min` and `max` count its items. A list written as a
411
+ * value, `['localhost']`, needs no `list`.
412
+ */
413
+ export function list<T extends Token>(
414
+ item: T,
415
+ options?: ListOptions<Of<T>>,
416
+ ): Setting<readonly Of<T>[]>
417
+ export function list<V>(
418
+ item: Setting<V, false, boolean>,
419
+ options?: ListOptions<V>,
420
+ ): Setting<readonly V[]>
421
+ export function list<G extends object>(
422
+ item: G,
423
+ options?: ListOptions<Value<G>>,
424
+ ): Setting<readonly Value<G>[]>
425
+ export function list(item: unknown, options: ListOptions<unknown> = {}): Setting<unknown> {
426
+ return setting({
427
+ kind: { list: itemOf(item) },
428
+ default: options.default ?? [],
429
+ ...bounds(options),
430
+ })
431
+ }
94
432
 
95
- constructor(schema: StandardSchemaV1) {
96
- this.schema = schema
433
+ function itemOf(item: unknown): Item {
434
+ if (item === String || item === Number || item === Boolean) {
435
+ return { kind: kindOf(item as Token) }
436
+ }
437
+ const inner = describedOf(item)
438
+ if (inner !== undefined) {
439
+ if (inner.live === true || inner.secret === true) {
440
+ throw new InvalidError("a list's items are neither live nor secret: the list is one setting")
441
+ }
442
+ const { kind, min, max, oneOf } = inner
443
+ return { kind, ...bounds({ min, max }), ...(oneOf === undefined ? {} : { oneOf }) }
444
+ }
445
+ if (isPlainObject(item)) {
446
+ return { group: declaredGroup(item, '[]') }
97
447
  }
448
+ throw new InvalidError(`a list of ${String(item)}: of String, Number, Boolean, a rule or a group`)
98
449
  }
99
450
 
100
- /** Checks a config each time it is made, with zod's, valibot's or another Standard Schema. */
101
- export function validate(schema: StandardSchemaV1): Validate {
102
- return new Validate(schema)
451
+ /** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
452
+ export function file(path: string, options: FileOptions = {}): FileLayer {
453
+ return Object.freeze({ [layerMark]: 'file' as const, path, optional: options.optional === true })
103
454
  }
104
455
 
105
- /** A config's value, as its defaults make it: each Setting its value's type. */
106
- export type ConfigValue<D extends object> = { [K in keyof D]: FieldValue<D[K]> }
456
+ /**
457
+ * The environment a config reads: `env('APP')` reads APP_ and each setting's
458
+ * path in upper snake case, `APP_LIMITS_RPS` for limits.rps.
459
+ */
460
+ export function env(prefix: string, options: EnvOptions = {}): EnvLayer {
461
+ return Object.freeze({
462
+ [layerMark]: 'env' as const,
463
+ prefix,
464
+ vars: flattened(options.vars ?? {}, ''),
465
+ files: [...(options.files ?? [])],
466
+ from: options.from,
467
+ })
468
+ }
107
469
 
108
- type FieldValue<F> =
109
- F extends Setting<infer V>
110
- ? V
111
- : F extends readonly unknown[] | Date
112
- ? F
113
- : F extends object
114
- ? ConfigValue<F>
115
- : F
116
-
117
- /** What a config takes after its defaults, each over the one before. */
118
- export type ConfigLayer<V> = DeepPartial<V> | FromEnv | Validate
119
-
120
- /** Where a field's value came from. */
121
- export interface Source {
122
- path: string
123
- /** its JSON, or *** for a secret */
124
- value: string
125
- /** 'default', 'file', 'env NAME' or 'kept' */
126
- from: string
127
- /** why a kept value is left out, when it is */
128
- ignored?: string
129
- }
130
-
131
- interface Field {
132
- /** its default, or '', 0 or false for one without */
133
- sample: unknown
134
- secret: boolean
135
- required: boolean
136
- variable: string | undefined
470
+ function flattened(vars: Vars, path: string): Record<string, string> {
471
+ const out: Record<string, string> = {}
472
+ for (const [key, value] of Object.entries(vars)) {
473
+ const at = path === '' ? key : `${path}.${key}`
474
+ if (typeof value === 'string') {
475
+ out[at] = value
476
+ } else {
477
+ Object.assign(out, flattened(value, at))
478
+ }
479
+ }
480
+ return out
481
+ }
482
+
483
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
484
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
485
+ return false
486
+ }
487
+ const proto = Object.getPrototypeOf(value)
488
+ return proto === Object.prototype || proto === null
489
+ }
490
+
491
+ function declaredGroup(value: Record<string, unknown>, path: string): Group {
492
+ const group: Group = {}
493
+ for (const [key, field] of Object.entries(value)) {
494
+ group[key] = declaredNode(field, path === '' ? key : `${path}.${key}`)
495
+ }
496
+ return group
497
+ }
498
+
499
+ function declaredNode(value: unknown, path: string): Node {
500
+ const described = describedOf(value)
501
+ if (described !== undefined) {
502
+ return described
503
+ }
504
+ if (isPlainObject(value) && Object.keys(value).length > 0) {
505
+ return { group: declaredGroup(value, path) }
506
+ }
507
+ return declaredValue(value, path)
508
+ }
509
+
510
+ /** A setting a plain default declares: its kind is its default's. */
511
+ function declaredValue(value: unknown, path: string): Described {
512
+ switch (typeof value) {
513
+ case 'string':
514
+ return { kind: 'text', default: value }
515
+ case 'number':
516
+ return { kind: 'number', default: value }
517
+ case 'boolean':
518
+ return { kind: 'boolean', default: value }
519
+ case 'function':
520
+ throw new InvalidError(
521
+ `${path}: a type is no default; required(${(value as Token).name}) declares one a layer must give`,
522
+ )
523
+ case 'undefined':
524
+ throw new InvalidError(`${path}: a setting has a default, or is required`)
525
+ }
526
+ if (value === null) {
527
+ return { kind: 'any', default: null }
528
+ }
529
+ if (Array.isArray(value)) {
530
+ return { kind: { list: plainItem(value[0]) }, default: value }
531
+ }
532
+ if (isPlainObject(value)) {
533
+ return { kind: 'object', default: {} }
534
+ }
535
+ throw new InvalidError(`${path}: ${String(value)} is no default a config keeps`)
536
+ }
537
+
538
+ function plainItem(first: unknown): Item {
539
+ switch (typeof first) {
540
+ case 'string':
541
+ return { kind: 'text' }
542
+ case 'number':
543
+ return { kind: 'number' }
544
+ case 'boolean':
545
+ return { kind: 'boolean' }
546
+ default:
547
+ return { kind: 'any' }
548
+ }
549
+ }
550
+
551
+ /** Every setting's path, as the core names its variable. */
552
+ function paths(group: Group, path: string): string[] {
553
+ return Object.entries(group).flatMap(([key, node]) => {
554
+ const at = path === '' ? key : `${path}.${key}`
555
+ return 'group' in node ? paths(node.group, at) : [at]
556
+ })
137
557
  }
138
558
 
139
559
  /**
140
- * A field's variable: the prefix and its path in upper snake case, as Go's and
141
- * Python's configs name it.
560
+ * A setting's variable: the prefix and its path in upper snake case, as Go,
561
+ * Python and the core name it (testdata/config/env.json).
142
562
  *
143
563
  * 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
144
564
  */
@@ -167,593 +587,463 @@ const isUpper = (c: string) => c !== c.toLowerCase() && c === c.toUpperCase()
167
587
  const isLower = (c: string) => c !== c.toUpperCase() && c === c.toLowerCase()
168
588
  const isDigit = (c: string) => c >= '0' && c <= '9'
169
589
 
170
- /**
171
- * The variables of a .env file, as Go's and Python's configs read one: NAME=value
172
- * lines, export before a name, # comments, a comment after a space, double
173
- * quotes reading \n \r \t \" and \\, single quotes reading nothing, a quoted
174
- * value over lines; a later name wins.
175
- */
176
- export function parseDotenv(text: string): Record<string, string> {
177
- const values: Record<string, string> = {}
178
- let line = 1
179
- let rest = text
180
- while (rest !== '') {
181
- const [name, value, after] = dotenvAssignment(rest, line)
182
- line += rest.slice(0, rest.length - after.length).split('\n').length - 1
183
- if (name !== '') {
184
- values[name] = value
590
+ /** A file's text, none when it does not exist. */
591
+ async function readText(path: string): Promise<string | undefined> {
592
+ try {
593
+ return await readFile(path, 'utf8')
594
+ } catch (err) {
595
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
596
+ return undefined
185
597
  }
186
- rest = after
598
+ throw new InvalidError(`${path}: ${(err as Error).message}`)
187
599
  }
188
- return values
189
600
  }
190
601
 
191
- function dotenvAssignment(text: string, number: number): [string, string, string] {
192
- const end = text.indexOf('\n')
193
- const line = end < 0 ? text : text.slice(0, end)
194
- const rest = end < 0 ? '' : text.slice(end + 1)
195
- const trimmed = line.trim()
196
- if (trimmed === '' || trimmed.startsWith('#')) {
197
- return ['', '', rest]
602
+ /** A layer as the core reads it, its files and variables read here. */
603
+ async function layerData(
604
+ layer: unknown,
605
+ place: number,
606
+ declared: Group,
607
+ ): Promise<object | undefined> {
608
+ if (layer === false || layer === null || layer === undefined) {
609
+ return undefined
198
610
  }
199
- const equals = line.indexOf('=')
200
- if (equals < 0) {
201
- throw new InvalidError(`line ${number}: ${JSON.stringify(line)} is no NAME=value`)
611
+ const kind = layerOf(layer)
612
+ if (kind === 'file') {
613
+ const { path, optional } = layer as FileLayer
614
+ const text = await readText(path)
615
+ return { file: { name: path, optional, ...(text === undefined ? {} : { text }) } }
202
616
  }
203
- let name = line.slice(0, equals).trim()
204
- if (name.startsWith('export ')) {
205
- name = name.slice('export '.length).trim()
617
+ if (kind === 'env') {
618
+ return { env: await envData(layer as EnvLayer, declared) }
206
619
  }
207
- if (!/^[\p{L}_][\p{L}\p{Nd}_]*$/u.test(name)) {
208
- throw new InvalidError(`line ${number}: ${JSON.stringify(name)} is no variable's name`)
620
+ if (isPlainObject(layer)) {
621
+ return { object: layer, place }
209
622
  }
210
- let start = equals + 1
211
- while (line[start] === ' ' || line[start] === '\t') {
212
- start++
623
+ throw new InvalidError(`layer ${place}: an object, file(…) or env(…)`)
624
+ }
625
+
626
+ /**
627
+ * What the environment gives, read here: the variables of every setting and
628
+ * those with the prefix, never the rest of the process's, the files their
629
+ * NAME_FILE names, and the .env files' text.
630
+ */
631
+ async function envData(layer: EnvLayer, declared: Group): Promise<object> {
632
+ const windows = process.platform === 'win32'
633
+ const key = (name: string) => (windows ? name.toUpperCase() : name)
634
+ const named = paths(declared, '').map(path => layer.vars[path] ?? envName(layer.prefix, path))
635
+ const wanted = new Set(named.flatMap(name => [key(name), key(`${name}_FILE`)]))
636
+ const start = key(`${layer.prefix}_`)
637
+ const variables: Record<string, string> = {}
638
+ for (const [name, value] of Object.entries(layer.from ?? process.env)) {
639
+ const k = key(name)
640
+ if (value !== undefined && (wanted.has(k) || (layer.prefix !== '' && k.startsWith(start)))) {
641
+ variables[k] = value
642
+ }
213
643
  }
214
- if (line[start] === '"' || line[start] === "'") {
215
- return [name, ...dotenvQuoted(text.slice(start), number)]
644
+ const dotenv: { name: string; text: string }[] = []
645
+ for (const name of layer.files) {
646
+ const text = await readText(name)
647
+ if (text !== undefined) {
648
+ dotenv.push({ name, text })
649
+ }
216
650
  }
217
- let value = line.slice(start)
218
- const comment = value.indexOf(' #')
219
- if (comment >= 0) {
220
- value = value.slice(0, comment)
651
+ const files: Record<string, string> = {}
652
+ const namedFiles = [...Object.entries(variables), ...dotenv.flatMap(d => fileVariables(d.text))]
653
+ for (const [name, path] of namedFiles) {
654
+ if (name.endsWith('_FILE')) {
655
+ const text = await readText(path)
656
+ if (text !== undefined) {
657
+ files[path] = text
658
+ }
659
+ }
221
660
  }
222
- return [name, value.replace(/[ \t\r]+$/, ''), rest]
661
+ return { prefix: layer.prefix, vars: layer.vars, variables, files, dotenv }
223
662
  }
224
663
 
225
- function dotenvQuoted(text: string, number: number): [string, string] {
226
- const quote = text[0]
227
- let out = ''
228
- for (let i = 1; i < text.length; i++) {
229
- const c = text[i] as string
230
- if (c === quote) {
231
- const end = text.indexOf('\n', i + 1)
232
- return [out, end < 0 ? '' : text.slice(end + 1)]
233
- }
234
- if (c === '\\' && quote === '"' && i + 1 < text.length) {
235
- i++
236
- const escaped = text[i] as string
237
- out += escaped === 'n' ? '\n' : escaped === 'r' ? '\r' : escaped === 't' ? '\t' : escaped
238
- } else {
239
- out += c
664
+ /** The NAME_FILE lines of a .env file's text, whose files the core cannot read. */
665
+ function fileVariables(text: string): [string, string][] {
666
+ const found: [string, string][] = []
667
+ for (const line of text.split('\n')) {
668
+ const match = /^\s*(?:export\s+)?([\p{L}_][\p{L}\p{Nd}_]*_FILE)\s*=\s*(.*?)\s*$/u.exec(line)
669
+ if (match !== null) {
670
+ found.push([match[1]!, match[2]!.replace(/^(['"])(.*)\1$/, '$2')])
240
671
  }
241
672
  }
242
- throw new InvalidError(`line ${number}: a value opened with ${quote} is never closed`)
673
+ return found
243
674
  }
244
675
 
245
- /** A config: open it with `store.kv.config(name, defaults, ...layers)`. */
246
- export class Config<T extends object> {
247
- readonly name: string
248
- readonly #link: Link
249
- readonly #open: Uint8Array
250
- readonly #fields: Map<string, Field>
251
- readonly #base: Record<string, unknown>
252
- readonly #from: Map<string, string>
253
- readonly #schemas: StandardSchemaV1[] = []
254
- readonly #listeners = new Set<(value: T) => void>()
255
- /** the last fromEnv's prefix, for a missing field's variable */
256
- #prefix: string | undefined
257
- #kept = new Map<string, string>()
258
- #ignored = new Map<string, string>()
259
- #value = {} as T
260
- #stream: Stream | undefined
261
- #closed = false
262
-
263
- /** Configs come from `store.kv.config`, which lays their layers and waits for the first state. */
264
- constructor(link: Link, name: string, defaults: object) {
265
- checkName(name, 'config')
266
- this.#link = link
267
- this.name = name
268
- this.#open = KvBucket.encode({ name, config: true })
269
- this.#fields = new Map(leavesOf(defaults).map(([path, leaf]) => [path, fieldOf(leaf)]))
270
- this.#base = valuesOf(defaults as Record<string, unknown>)
271
- this.#from = new Map(
272
- [...this.#fields].filter(([, field]) => !field.required).map(([path]) => [path, 'default']),
273
- )
676
+ /** A value as the program reads it: a duration spelled, a secret wrapped, all of it frozen. */
677
+ function viewed(group: Group, value: unknown): unknown {
678
+ const source = (isPlainObject(value) ? value : {}) as Record<string, unknown>
679
+ const out: Record<string, unknown> = {}
680
+ for (const [key, node] of Object.entries(group)) {
681
+ out[key] = 'group' in node ? viewed(node.group, source[key]) : viewedSetting(node, source[key])
274
682
  }
683
+ return Object.freeze(out)
684
+ }
275
685
 
276
- /** The config now, frozen: update changes it. */
277
- get value(): T {
278
- return this.#value
686
+ function viewedSetting(described: Described, value: unknown): unknown {
687
+ if (described.secret === true) {
688
+ return new Secret(typeof value === 'string' ? value : '')
279
689
  }
690
+ return viewedKind(described.kind, value)
691
+ }
280
692
 
281
- /** Lays each layer over the defaults, the one before it under it, and checks what is required. */
282
- async lay(layers: readonly unknown[]): Promise<void> {
283
- for (const layer of layers) {
284
- if (layer instanceof FromEnv) {
285
- await this.#layEnvironment(layer)
286
- } else if (layer instanceof Validate) {
287
- this.#schemas.push(layer.schema)
288
- } else if (isSchema(layer)) {
289
- throw new InvalidError(
290
- `config ${this.name}: a schema checks the config as validate(schema)`,
291
- )
292
- } else if (plain(layer)) {
293
- this.#layFile(layer)
294
- } else {
295
- throw new InvalidError(
296
- `config ${this.name}: a layer is a file's values, fromEnv() or validate(), not ${String(layer)}`,
297
- )
298
- }
299
- }
300
- for (const [path, field] of this.#fields) {
301
- if (field.required && missing(pathIn(this.#base, path))) {
302
- throw new InvalidError(`config ${this.name}: ${this.#requiredText(path, field)}`)
303
- }
304
- }
305
- this.#value = deepFreeze(structuredClone(this.#base)) as T
693
+ function viewedKind(kind: Kind, value: unknown): unknown {
694
+ if (kind === 'duration' && typeof value === 'number') {
695
+ return spelled(value)
306
696
  }
307
-
308
- /**
309
- * Changes the fields change names, at any depth; each one that changed is
310
- * checked, kept, and seen by every store watching the config. A change the
311
- * schema refuses, one of a secret, or one leaving a required field empty, is
312
- * InvalidError and keeps nothing.
313
- */
314
- async update(change: DeepPartial<T>): Promise<void> {
315
- const next = merged(structuredClone(this.#value) as Record<string, unknown>, change)
316
- const set: string[] = []
317
- for (const [path, field] of this.#fields) {
318
- const now = JSON.stringify(pathIn(next, path))
319
- if (now === JSON.stringify(pathIn(this.#value, path))) {
320
- continue
321
- }
322
- if (field.secret) {
323
- throw new InvalidError(
324
- `config ${this.name}: ${path} is a secret, set by the defaults, a file or the environment alone`,
325
- )
326
- }
327
- if (field.required && missing(pathIn(next, path))) {
328
- throw new InvalidError(`config ${this.name}: ${path} is required`)
329
- }
330
- set.push(path, now)
331
- }
332
- if (set.length === 0) {
333
- return
334
- }
335
- await this.#checked(next)
336
- await this.#send(set, [])
697
+ if (typeof kind === 'object' && Array.isArray(value)) {
698
+ const item = kind.list
699
+ const items = value.map(each =>
700
+ 'group' in item ? viewed(item.group, each) : viewedKind(item.kind, each),
701
+ )
702
+ return Object.freeze(items)
337
703
  }
704
+ return frozen(value)
705
+ }
338
706
 
339
- /** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
340
- async reset(...paths: string[]): Promise<void> {
341
- for (const path of paths) {
342
- if (![...this.#fields.keys()].some(leaf => under(leaf, path))) {
343
- throw new InvalidError(`config ${this.name} has no field ${path}`)
344
- }
345
- }
346
- const reset = [...this.#kept.keys()].filter(
347
- kept => paths.length === 0 || paths.some(path => under(kept, path)),
348
- )
349
- if (reset.length > 0) {
350
- await this.#send([], reset)
707
+ function frozen(value: unknown): unknown {
708
+ if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
709
+ for (const inner of Object.values(value)) {
710
+ frozen(inner)
351
711
  }
712
+ Object.freeze(value)
352
713
  }
714
+ return value
715
+ }
353
716
 
354
- /** Calls fn with the config now and after each change, whoever made it; the function it returns stops that. */
355
- watch(fn: (value: T) => void): () => void {
356
- this.#listeners.add(fn)
357
- fn(this.#value)
358
- return () => this.#listeners.delete(fn)
717
+ /** A partial value over a whole one: the groups it names merged, anything else replaced. */
718
+ function merged(value: unknown, changes: unknown): unknown {
719
+ if (!isPlainObject(value) || !isPlainObject(changes)) {
720
+ return changes
359
721
  }
360
-
361
- /** Where each field's value came from, and why a kept value is left out. */
362
- sources(): Source[] {
363
- return [...this.#fields].map(([path, field]) => {
364
- const kept = this.#kept.has(path) && !this.#ignored.has(path)
365
- const source: Source = {
366
- path,
367
- value: field.secret ? '***' : (JSON.stringify(pathIn(this.#value, path)) ?? 'null'),
368
- from: kept ? 'kept' : (this.#from.get(path) ?? 'default'),
369
- }
370
- const ignored = this.#ignored.get(path)
371
- return ignored === undefined ? source : { ...source, ignored }
372
- })
722
+ const out: Record<string, unknown> = { ...value }
723
+ for (const [key, change] of Object.entries(changes)) {
724
+ out[key] = merged(value[key], change)
373
725
  }
726
+ return out
727
+ }
374
728
 
375
- /** Follows the config's changes until the store closes; resolves once the first state is read. */
376
- start(): Promise<void> {
377
- return new Promise((resolve, reject) => {
378
- void this.#follow(resolve, reject)
379
- })
380
- }
729
+ type Watcher<V> = (next: V, previous: V | undefined) => void
730
+ type Answer = Read<typeof ConfigValue.fields>
381
731
 
382
- /** Stops following the config, as the store does when it closes. */
383
- stop(): void {
384
- this.#closed = true
385
- this.#stream?.cancel()
386
- }
732
+ /**
733
+ * A program's settings as one typed value, read from memory: open one with
734
+ * `store.config(name, [declaration, ...layers])`.
735
+ */
736
+ export class Config<D> {
737
+ readonly name: string
738
+ readonly #link: Link
739
+ readonly #declared: Group
740
+ readonly #open: Uint8Array
741
+ readonly #check: ((value: unknown) => Promise<void>) | undefined
742
+ readonly #handles = new WeakMap<Connection, Promise<number>>()
743
+ readonly #watchers = new Set<Watcher<Value<D>>>()
744
+ #value: Value<D>
745
+ #version = 0
746
+ #lines: ExplainLine[] = []
747
+ #notes: string[] = []
748
+ /** why validate refused the newest value the store sent, a change another program made */
749
+ #refused: InvalidError | undefined
750
+ #taking: Promise<void> = Promise.resolve()
751
+ #newer: (() => void)[] = []
752
+ #stream: Stream | undefined
753
+ #stopped = false
754
+ /** the loop that follows the config, which ends once it is stopped */
755
+ #following: Promise<void> = Promise.resolve()
387
756
 
388
- #layFile(values: Record<string, unknown>): void {
389
- for (const [path, value] of leavesOf(values)) {
390
- const field = this.#fields.get(path)
391
- if (field === undefined) {
392
- continue
393
- }
394
- if (!fits(value, field.sample)) {
395
- throw new InvalidError(
396
- `the file's ${path}: ${JSON.stringify(value)} is no ${kindOf(field.sample)}`,
397
- )
398
- }
399
- setPath(this.#base, path, value)
400
- this.#from.set(path, 'file')
401
- }
757
+ private constructor(
758
+ link: Link,
759
+ name: string,
760
+ declared: Group,
761
+ open: Uint8Array,
762
+ check: ((value: unknown) => Promise<void>) | undefined,
763
+ ) {
764
+ this.#link = link
765
+ this.name = name
766
+ this.#declared = declared
767
+ this.#open = open
768
+ this.#check = check
769
+ this.#value = viewed(declared, {}) as Value<D>
402
770
  }
403
771
 
404
- async #layEnvironment(layer: FromEnv): Promise<void> {
405
- const variables: Record<string, string | undefined> = {}
406
- for (const file of layer.files) {
407
- Object.assign(variables, await readDotenv(file))
772
+ /** Opens a config from its list: the declaration first, then its layers in order. */
773
+ static async open<D>(
774
+ link: Link,
775
+ name: string,
776
+ layers: readonly unknown[],
777
+ options: ConfigOptions<Value<D>>,
778
+ ): Promise<Config<D>> {
779
+ const [declaration, ...rest] = layers
780
+ if (!isPlainObject(declaration)) {
781
+ throw new InvalidError(`config ${name}: the list's first entry is its declaration, an object`)
408
782
  }
409
- Object.assign(variables, process.env)
410
- for (const [path, field] of this.#fields) {
411
- const name = field.variable ?? envName(layer.prefix, path)
412
- const text = variables[name]
413
- if (text !== undefined) {
414
- setPath(this.#base, path, readVariable(text, field.sample, name))
415
- this.#from.set(path, `env ${name}`)
416
- }
783
+ const declared = declaredGroup(declaration, '')
784
+ const data = await Promise.all(rest.map((layer, at) => layerData(layer, at + 2, declared)))
785
+ const open = ConfigOpen.encode({
786
+ name,
787
+ declaration: JSON.stringify(declared),
788
+ layers: JSON.stringify(data.filter(layer => layer !== undefined)),
789
+ strict: options.strict === true,
790
+ })
791
+ const config = new Config<D>(link, name, declared, open, checkerOf(name, options.validate))
792
+ await link.run('read', connection => config.#handleOn(connection))
793
+ await config.#taking
794
+ if (config.#refused !== undefined) {
795
+ throw config.#refused
417
796
  }
418
- this.#prefix = layer.prefix
797
+ config.#following = config.#follow()
798
+ return config
419
799
  }
420
800
 
421
- #requiredText(path: string, field: Field): string {
422
- if (this.#prefix === undefined) {
423
- return `${path} is required`
424
- }
425
- return `${path} is required: set ${field.variable ?? envName(this.#prefix, path)}`
801
+ /** The settings as they are now: a read of memory, so read it where it is used. */
802
+ get value(): Value<D> {
803
+ return this.#value
804
+ }
805
+
806
+ /** The version of the changes the value holds, which `ifVersion` takes. */
807
+ get version(): number {
808
+ return this.#version
426
809
  }
427
810
 
428
- async #follow(ready: () => void, failed: (err: unknown) => void): Promise<void> {
429
- let first = true
430
- for (let pause = 100; !this.#closed; pause = Math.min(pause * 2, 5000)) {
811
+ /**
812
+ * Changes live settings: the ones `changes` names are kept in the store, go
813
+ * over every layer until they are reset, and reach every handle of the
814
+ * config. The value they make passes validate first; all are kept or none.
815
+ */
816
+ async update(changes: Changes<D>, options: UpdateOptions = {}): Promise<void> {
817
+ for (let tries = 1; ; tries++) {
818
+ const version = options.ifVersion ?? this.#version
819
+ await this.#check?.(merged(this.#value, changes))
820
+ const body = (handle: number) =>
821
+ ConfigUpdate.encode({ handle, version, changes: JSON.stringify(changes) })
431
822
  try {
432
- await this.#link.run('read', async connection => {
433
- const handle = await handleOn(connection, methods['kv.open'], this.#open)
434
- const stream = await connection.session.open(
435
- methods['kv.watch'],
436
- KvCall.encode({ handle }),
437
- true,
438
- )
439
- this.#stream = stream
440
- await stream.next()
441
- for (;;) {
442
- const event = await stream.next()
443
- stream.consumed(event.body.length)
444
- if (event.end) {
445
- return
446
- }
447
- await this.#apply(KvKept.decode(event.body).fields ?? [])
448
- pause = 100
449
- if (first) {
450
- first = false
451
- ready()
452
- }
453
- }
454
- })
823
+ await this.#call('write', methods['config.update'], body)
824
+ return
455
825
  } catch (err) {
456
- if (first) {
457
- failed(err)
458
- return
459
- }
460
- if (this.#closed || err instanceof ClosedError) {
461
- return
826
+ if (
827
+ !(err instanceof ConflictError) ||
828
+ options.ifVersion !== undefined ||
829
+ tries === attempts
830
+ ) {
831
+ throw err
462
832
  }
833
+ await this.#newerThan(version)
463
834
  }
464
- await new Promise(resolve => setTimeout(resolve, pause))
465
- }
466
- }
467
-
468
- /** Keeps set, path and JSON each, and forgets reset, then makes the config with them. */
469
- async #send(set: string[], reset: string[]): Promise<void> {
470
- await this.#link.run('write', async connection => {
471
- const handle = await handleOn(connection, methods['kv.open'], this.#open)
472
- const body = KvConfigure.encode({
473
- handle,
474
- set: set.length > 0 ? set : undefined,
475
- reset: reset.length > 0 ? reset : undefined,
476
- })
477
- await connection.session.call(methods['kv.configure'], body)
478
- })
479
- const kept = new Map(this.#kept)
480
- for (let i = 0; i + 1 < set.length; i += 2) {
481
- kept.set(set[i] as string, set[i + 1] as string)
482
- }
483
- for (const path of reset) {
484
- kept.delete(path)
485
835
  }
486
- await this.#build(kept)
487
836
  }
488
837
 
489
- /** Takes up the kept fields a watch sent. */
490
- async #apply(fields: string[]): Promise<void> {
491
- const kept = new Map<string, string>()
492
- for (let i = 0; i + 1 < fields.length; i += 2) {
493
- kept.set(fields[i] as string, fields[i + 1] as string)
494
- }
495
- await this.#build(kept)
838
+ /** Drops the change kept of the setting or the group at `path`, or of every setting. */
839
+ async reset(path = ''): Promise<void> {
840
+ await this.#call('write', methods['config.reset'], handle =>
841
+ ConfigReset.encode({ handle, path }),
842
+ )
496
843
  }
497
844
 
498
- /** Makes the config from its base and what is kept, leaving out what no longer fits, and tells the watchers. */
499
- async #build(kept: Map<string, string>): Promise<void> {
500
- const ignored = new Map<string, string>()
501
- let next = withKept(this.#base, this.#fields, kept, ignored)
502
- let issues = await this.#issues(next)
503
- if (issues !== undefined && kept.size > ignored.size) {
504
- for (const path of kept.keys()) {
505
- ignored.set(path, ignored.get(path) ?? `the config fails with it: ${issues}`)
506
- }
507
- next = structuredClone(this.#base)
508
- issues = await this.#issues(next)
509
- }
510
- if (issues !== undefined) {
511
- throw new InvalidError(`config ${this.name}: ${issues}`)
512
- }
513
- const changed = JSON.stringify(next) !== JSON.stringify(this.#value)
514
- this.#kept = kept
515
- this.#ignored = ignored
516
- this.#value = deepFreeze(next) as T
517
- if (changed) {
518
- for (const listener of this.#listeners) {
519
- listener(this.#value)
520
- }
845
+ /**
846
+ * Calls `watcher` with the settings now, then with each change and the value
847
+ * before it, made in this process or another. It returns the call that stops it.
848
+ */
849
+ watch(watcher: (next: Value<D>, previous: Value<D> | undefined) => void): () => void {
850
+ this.#watchers.add(watcher)
851
+ watcher(this.#value, undefined)
852
+ return () => {
853
+ this.#watchers.delete(watcher)
521
854
  }
522
855
  }
523
856
 
524
- async #checked(value: Record<string, unknown>): Promise<void> {
525
- const issues = await this.#issues(value)
526
- if (issues !== undefined) {
527
- throw new InvalidError(`config ${this.name}: ${issues}`)
528
- }
857
+ /** Every setting with its value, the layer that gave it and what it went over. */
858
+ explain(): Explained {
859
+ const refused =
860
+ this.#refused === undefined ? [] : [`a value validate refused: ${this.#refused.message}`]
861
+ return Object.assign([...this.#lines], { notes: [...this.#notes, ...refused] })
529
862
  }
530
863
 
531
- async #issues(value: Record<string, unknown>): Promise<string | undefined> {
532
- for (const schema of this.#schemas) {
533
- const checked = await check(schema, value)
534
- if ('issues' in checked) {
535
- return checked.issues
536
- }
864
+ /**
865
+ * Stops following the config: the store closes. It resolves once the
866
+ * stream that follows it is cancelled, so that the store's connection
867
+ * ends after its CANCEL: a stream the server still ran would keep a
868
+ * private child, or a sidecar's connection, draining for ten seconds.
869
+ */
870
+ stop(): Promise<void> {
871
+ this.#stopped = true
872
+ this.#watchers.clear()
873
+ this.#stream?.cancel()
874
+ for (const wake of this.#newer.splice(0)) {
875
+ wake()
537
876
  }
538
- return undefined
877
+ return this.#following
539
878
  }
540
- }
541
879
 
542
- function fieldOf(leaf: unknown): Field {
543
- if (!(leaf instanceof Setting)) {
544
- return { sample: leaf, secret: false, required: false, variable: undefined }
545
- }
546
- return {
547
- sample: leaf.fallback ?? { string: '', number: 0, boolean: false }[leaf.kind],
548
- secret: leaf.secret,
549
- required: leaf.fallback === undefined,
550
- variable: leaf.variable,
880
+ /** Runs a call on the config's handle on the link's connection, and takes the value it answers. */
881
+ async #call(
882
+ idempotence: Idempotence,
883
+ method: number,
884
+ body: (handle: number) => Uint8Array,
885
+ ): Promise<void> {
886
+ await this.#link.run(idempotence, async connection => {
887
+ const handle = await this.#handleOn(connection)
888
+ await this.#take(ConfigValue.decode(await connection.session.call(method, body(handle))))
889
+ })
551
890
  }
552
- }
553
891
 
554
- /** The defaults' values: a Setting's default, and nothing for one without. */
555
- function valuesOf(tree: Record<string, unknown>): Record<string, unknown> {
556
- const values: Record<string, unknown> = {}
557
- for (const [key, inner] of Object.entries(tree)) {
558
- if (inner instanceof Setting) {
559
- if (inner.fallback !== undefined) {
560
- values[key] = inner.fallback
561
- }
562
- } else {
563
- values[key] = plain(inner) ? valuesOf(inner) : structuredClone(inner)
892
+ /** The config's handle on a connection, opened there first, its value taken. */
893
+ #handleOn(connection: Connection): Promise<number> {
894
+ let handle = this.#handles.get(connection)
895
+ if (handle === undefined) {
896
+ handle = connection.session.call(methods['config.open'], this.#open).then(async body => {
897
+ const opened = ConfigValue.decode(body)
898
+ await this.#take(opened)
899
+ return opened.handle ?? 0
900
+ })
901
+ this.#handles.set(connection, handle)
902
+ handle.catch(() => this.#handles.delete(connection))
564
903
  }
904
+ return handle
565
905
  }
566
- return values
567
- }
568
-
569
- /** A required field's value no layer gave, or gave empty. */
570
- function missing(value: unknown): boolean {
571
- return value === undefined || value === ''
572
- }
573
906
 
574
- async function readDotenv(path: string): Promise<Record<string, string>> {
575
- let text: string
576
- try {
577
- text = await readFile(path, 'utf8')
578
- } catch (err) {
579
- if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
580
- return {}
581
- }
582
- throw err
583
- }
584
- try {
585
- return parseDotenv(text)
586
- } catch (err) {
587
- throw new InvalidError(`${path}: ${(err as Error).message}`)
907
+ /** Takes a value the store sent, in the order it came; an older one than this has is left. */
908
+ #take(answer: Answer): Promise<void> {
909
+ this.#taking = this.#taking.then(() => this.#accept(answer))
910
+ return this.#taking
588
911
  }
589
- }
590
912
 
591
- /** The base with each kept value that fits its field over it; a secret is never taken from what was kept. */
592
- function withKept(
593
- base: Record<string, unknown>,
594
- fields: Map<string, Field>,
595
- kept: Map<string, string>,
596
- ignored: Map<string, string>,
597
- ): Record<string, unknown> {
598
- const next = structuredClone(base)
599
- for (const [path, spelled] of kept) {
600
- const field = fields.get(path)
601
- if (field === undefined) {
602
- ignored.set(path, 'the config has no such field')
603
- continue
604
- }
605
- if (field.secret) {
606
- ignored.set(path, 'the field is a secret')
607
- continue
913
+ async #accept(answer: Answer): Promise<void> {
914
+ const version = answer.version ?? 0
915
+ if (version < this.#version || (version === this.#version && this.#lines.length > 0)) {
916
+ return
608
917
  }
609
- let value: unknown
918
+ const next = viewed(this.#declared, JSON.parse(answer.value ?? '{}')) as Value<D>
610
919
  try {
611
- value = JSON.parse(spelled)
612
- } catch {
613
- ignored.set(path, `${spelled} is no JSON`)
614
- continue
920
+ await this.#check?.(next)
921
+ } catch (err) {
922
+ this.#refused = err instanceof InvalidError ? err : new InvalidError((err as Error).message)
923
+ if (this.#lines.length > 0) {
924
+ process.stderr.write(
925
+ `version ${version}: ${this.#refused.message}; the value before it stays\n`,
926
+ )
927
+ }
928
+ return
615
929
  }
616
- if (!fits(value, field.sample)) {
617
- ignored.set(path, `${spelled} is no ${kindOf(field.sample)}`)
618
- continue
930
+ const previous = this.#value
931
+ this.#refused = undefined
932
+ this.#value = next
933
+ this.#version = version
934
+ this.#lines = (answer.lines ?? []).map(line => ({
935
+ path: line.path ?? '',
936
+ value: line.value ?? '',
937
+ from: line.from ?? '',
938
+ over: (line.over ?? []).join(', '),
939
+ }))
940
+ this.#notes = answer.notes ?? []
941
+ for (const wake of this.#newer.splice(0)) {
942
+ wake()
619
943
  }
620
- if (field.required && missing(value)) {
621
- ignored.set(path, 'the field is required')
622
- continue
944
+ for (const watcher of this.#watchers) {
945
+ try {
946
+ watcher(next, previous)
947
+ } catch (err) {
948
+ process.stderr.write(`config ${this.name}: a watcher threw: ${(err as Error).message}\n`)
949
+ }
623
950
  }
624
- setPath(next, path, value)
625
951
  }
626
- return next
627
- }
628
952
 
629
- /**
630
- * A variable's text as a value of its default's kind: a number, true or
631
- * false, a list split at its commas or given as JSON, and anything else as JSON.
632
- *
633
- * 8080 ← '3000' → 3000, ['x'] ← 'a.com, b.com' → ['a.com', 'b.com']
634
- */
635
- function readVariable(text: string, wanted: unknown, name: string): unknown {
636
- const trimmed = text.trim()
637
- if (typeof wanted === 'string') {
638
- return text
639
- }
640
- if (typeof wanted === 'number') {
641
- const n = Number(trimmed)
642
- if (trimmed === '' || !Number.isFinite(n)) {
643
- throw new InvalidError(`${name}: ${JSON.stringify(text)} is no number`)
644
- }
645
- return n
646
- }
647
- if (typeof wanted === 'boolean') {
648
- if (['1', 't', 'T', 'TRUE', 'true', 'True'].includes(trimmed)) {
649
- return true
650
- }
651
- if (['0', 'f', 'F', 'FALSE', 'false', 'False'].includes(trimmed)) {
652
- return false
653
- }
654
- throw new InvalidError(`${name}: ${JSON.stringify(text)} is not true or false`)
655
- }
656
- if (Array.isArray(wanted) && !trimmed.startsWith('[')) {
657
- const item = wanted[0] ?? ''
658
- return trimmed === ''
659
- ? []
660
- : trimmed.split(',').map(part => readVariable(part.trim(), item, name))
661
- }
662
- try {
663
- const value: unknown = JSON.parse(trimmed)
664
- if (fits(value, wanted)) {
665
- return value
953
+ /** Waits until a version later than `version` came, or a second passed. */
954
+ #newerThan(version: number): Promise<void> {
955
+ if (this.#version > version || this.#stopped) {
956
+ return Promise.resolve()
666
957
  }
667
- } catch {
668
- // refused below, naming the variable
958
+ return new Promise(resolve => {
959
+ const timer = setTimeout(resolve, 1000)
960
+ this.#newer.push(() => {
961
+ clearTimeout(timer)
962
+ resolve()
963
+ })
964
+ })
669
965
  }
670
- throw new InvalidError(`${name}: ${JSON.stringify(text)} is no ${kindOf(wanted)}`)
671
- }
672
966
 
673
- /** A value's fields to the last that is not a plain object, by their dotted paths. */
674
- function leavesOf(value: unknown, parent = ''): [string, unknown][] {
675
- const leaves: [string, unknown][] = []
676
- for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
677
- const path = parent === '' ? key : `${parent}.${key}`
678
- if (plain(inner)) {
679
- leaves.push(...leavesOf(inner, path))
680
- } else {
681
- leaves.push([path, inner])
967
+ /**
968
+ * Follows the config on one stream until the store closes: a lost
969
+ * connection or a server going away follows again on the next one.
970
+ */
971
+ async #follow(): Promise<void> {
972
+ while (!this.#stopped) {
973
+ try {
974
+ const stream = await this.#link.run('read', async connection => {
975
+ const handle = await this.#handleOn(connection)
976
+ if (this.#stopped) {
977
+ return undefined
978
+ }
979
+ const opened = await connection.session.open(
980
+ methods['config.follow'],
981
+ Handle.encode({ handle }),
982
+ true,
983
+ )
984
+ // kept before its first answer, so that a stop meanwhile cancels it
985
+ this.#stream = opened
986
+ if (this.#stopped) {
987
+ opened.cancel()
988
+ }
989
+ await opened.next()
990
+ return opened
991
+ })
992
+ if (stream === undefined) {
993
+ return
994
+ }
995
+ this.#stream = stream
996
+ if (this.#stopped) {
997
+ stream.cancel()
998
+ return
999
+ }
1000
+ for (;;) {
1001
+ const event = await stream.next()
1002
+ stream.consumed(event.body.length)
1003
+ if (event.end) {
1004
+ break
1005
+ }
1006
+ await this.#take(ConfigValue.decode(event.body))
1007
+ }
1008
+ } catch (err) {
1009
+ if (this.#stopped) {
1010
+ return
1011
+ }
1012
+ const passing =
1013
+ err instanceof ConnectionLostError ||
1014
+ err instanceof UnavailableError ||
1015
+ err instanceof CancelledError
1016
+ if (!passing) {
1017
+ await new Promise(resolve => setTimeout(resolve, 1000))
1018
+ }
1019
+ }
682
1020
  }
683
1021
  }
684
- return leaves
685
- }
686
-
687
- function plain(value: unknown): value is Record<string, unknown> {
688
- return (
689
- typeof value === 'object' &&
690
- value !== null &&
691
- !Array.isArray(value) &&
692
- !(value instanceof Date) &&
693
- !(value instanceof Setting) &&
694
- !(value instanceof FromEnv) &&
695
- !(value instanceof Validate)
696
- )
697
- }
698
-
699
- /** A value fits a field when it is of its default's kind; a default of null takes anything. */
700
- function fits(value: unknown, wanted: unknown): boolean {
701
- if (wanted === null || wanted === undefined) {
702
- return true
703
- }
704
- if (Array.isArray(wanted)) {
705
- return Array.isArray(value)
706
- }
707
- return typeof value === typeof wanted && (typeof wanted !== 'object' || plain(value))
708
1022
  }
709
1023
 
710
- function kindOf(wanted: unknown): string {
711
- return Array.isArray(wanted) ? 'list' : typeof wanted
712
- }
713
-
714
- function pathIn(tree: unknown, path: string): unknown {
715
- let at = tree
716
- for (const name of path.split('.')) {
717
- if (!plain(at)) {
718
- return undefined
719
- }
720
- at = at[name]
1024
+ /** The check a config's validate makes of a whole value, throwing InvalidError when it refuses. */
1025
+ function checkerOf<V>(
1026
+ name: string,
1027
+ validate: ConfigOptions<V>['validate'],
1028
+ ): ((value: unknown) => Promise<void>) | undefined {
1029
+ if (validate === undefined) {
1030
+ return undefined
721
1031
  }
722
- return at
723
- }
724
-
725
- function setPath(tree: Record<string, unknown>, path: string, value: unknown): void {
726
- const names = path.split('.')
727
- let at = tree
728
- for (const name of names.slice(0, -1)) {
729
- const inner = at[name]
730
- if (!plain(inner)) {
731
- at[name] = {}
1032
+ if (isSchema(validate)) {
1033
+ return async value => {
1034
+ const checked = await check(validate, value)
1035
+ if ('issues' in checked) {
1036
+ throw new InvalidError(`config ${name}: ${checked.issues}`)
1037
+ }
732
1038
  }
733
- at = at[name] as Record<string, unknown>
734
- }
735
- at[names[names.length - 1] as string] = value
736
- }
737
-
738
- /** change merged into tree at every depth; a list is replaced whole. */
739
- function merged(tree: Record<string, unknown>, change: unknown): Record<string, unknown> {
740
- for (const [key, value] of Object.entries(change as Record<string, unknown>)) {
741
- const inner = tree[key]
742
- tree[key] = plain(value) && plain(inner) ? merged(inner, value) : value
743
1039
  }
744
- return tree
745
- }
746
-
747
- function under(path: string, given: string): boolean {
748
- return path === given || path.startsWith(`${given}.`)
749
- }
750
-
751
- function deepFreeze<V>(value: V): V {
752
- if (typeof value === 'object' && value !== null) {
753
- for (const inner of Object.values(value)) {
754
- deepFreeze(inner)
1040
+ return async value => {
1041
+ try {
1042
+ await validate(value as V)
1043
+ } catch (err) {
1044
+ throw err instanceof InvalidError
1045
+ ? err
1046
+ : new InvalidError(`config ${name}: ${(err as Error).message}`)
755
1047
  }
756
- Object.freeze(value)
757
1048
  }
758
- return value
759
1049
  }