@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.
- package/README.md +37 -37
- package/bin/tinystore.js +12 -1
- package/dist/backup.d.ts +33 -0
- package/dist/backup.js +49 -0
- package/dist/blobs.d.ts +160 -79
- package/dist/blobs.js +510 -217
- package/dist/channels.d.ts +90 -0
- package/dist/channels.js +291 -0
- package/dist/clock.js +3 -3
- package/dist/config.d.ts +209 -86
- package/dist/config.js +581 -538
- package/dist/connection.d.ts +64 -2
- package/dist/connection.js +201 -16
- package/dist/console.d.ts +27 -3
- package/dist/console.js +165 -12
- package/dist/dotenv.d.ts +7 -0
- package/dist/dotenv.js +79 -0
- package/dist/errors.d.ts +61 -1
- package/dist/errors.js +81 -1
- package/dist/handles.d.ts +44 -2
- package/dist/handles.js +81 -2
- package/dist/index.d.ts +17 -11
- package/dist/index.js +5 -3
- package/dist/instruments.d.ts +177 -0
- package/dist/instruments.js +819 -0
- package/dist/jobs.d.ts +335 -239
- package/dist/jobs.js +716 -536
- package/dist/json.d.ts +2 -0
- package/dist/json.js +122 -0
- package/dist/kv.d.ts +130 -243
- package/dist/kv.js +273 -640
- package/dist/limits.d.ts +80 -0
- package/dist/limits.js +139 -0
- package/dist/locks.d.ts +62 -0
- package/dist/locks.js +237 -0
- package/dist/logger.d.ts +45 -9
- package/dist/logger.js +150 -38
- package/dist/metrics.d.ts +210 -209
- package/dist/metrics.js +319 -556
- package/dist/once.d.ts +19 -18
- package/dist/once.js +74 -63
- package/dist/query.d.ts +181 -0
- package/dist/query.js +788 -0
- package/dist/records.d.ts +241 -150
- package/dist/records.js +507 -291
- package/dist/runtime/addon.d.ts +14 -0
- package/dist/runtime/addon.js +69 -0
- package/dist/runtime/bun.js +5 -7
- package/dist/runtime/node.js +5 -7
- package/dist/runtime/pipe.d.ts +17 -0
- package/dist/runtime/pipe.js +133 -0
- package/dist/runtime/shared.d.ts +6 -0
- package/dist/runtime/shared.js +19 -0
- package/dist/runtime.d.ts +5 -2
- package/dist/search.d.ts +189 -0
- package/dist/search.js +281 -0
- package/dist/session.d.ts +31 -3
- package/dist/session.js +153 -41
- package/dist/sql.d.ts +228 -78
- package/dist/sql.js +745 -240
- package/dist/store.d.ts +244 -24
- package/dist/store.js +270 -67
- package/dist/time.d.ts +5 -1
- package/dist/time.js +22 -2
- package/dist/tx.d.ts +61 -0
- package/dist/tx.js +314 -0
- package/dist/wire/codec.d.ts +23 -7
- package/dist/wire/codec.js +56 -35
- package/dist/wire/frame.d.ts +2 -0
- package/dist/wire/frame.js +31 -14
- package/dist/wire/messages.d.ts +259 -0
- package/dist/wire/messages.js +22 -0
- package/dist/wire/msgpack.d.ts +49 -1
- package/dist/wire/msgpack.js +293 -56
- package/dist/wire/protocol.d.ts +2683 -0
- package/dist/wire/protocol.js +10846 -0
- package/package.json +39 -38
- package/src/backup.ts +81 -0
- package/src/blobs.ts +678 -301
- package/src/channels.ts +377 -0
- package/src/clock.ts +4 -4
- package/src/config.ts +902 -612
- package/src/connection.ts +279 -21
- package/src/console.ts +180 -12
- package/src/dotenv.ts +82 -0
- package/src/errors.ts +105 -0
- package/src/handles.ts +157 -8
- package/src/index.ts +158 -52
- package/src/instruments.ts +1042 -0
- package/src/jobs.ts +1017 -733
- package/src/json.ts +133 -0
- package/src/kv.ts +424 -847
- package/src/limits.ts +202 -0
- package/src/locks.ts +320 -0
- package/src/logger.ts +209 -40
- package/src/metrics.ts +557 -752
- package/src/once.ts +86 -83
- package/src/query.ts +1005 -0
- package/src/records.ts +795 -418
- package/src/runtime/addon.ts +99 -0
- package/src/runtime/bun.ts +5 -7
- package/src/runtime/node.ts +5 -7
- package/src/runtime/pipe.ts +178 -0
- package/src/runtime/shared.ts +20 -0
- package/src/runtime.ts +5 -2
- package/src/search.ts +480 -0
- package/src/session.ts +187 -41
- package/src/sql.ts +993 -306
- package/src/store.ts +473 -78
- package/src/time.ts +48 -3
- package/src/tx.ts +426 -0
- package/src/wire/codec.ts +78 -37
- package/src/wire/frame.ts +44 -14
- package/src/wire/messages.ts +25 -0
- package/src/wire/msgpack.ts +327 -56
- package/src/wire/protocol.ts +11709 -0
- package/dist/limiter.d.ts +0 -45
- package/dist/limiter.js +0 -68
- package/dist/quota.d.ts +0 -44
- package/dist/quota.js +0 -98
- package/src/limiter.ts +0 -99
- package/src/quota.ts +0 -137
package/src/config.ts
CHANGED
|
@@ -1,144 +1,564 @@
|
|
|
1
|
-
//
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
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 {
|
|
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
|
|
13
|
-
import {
|
|
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
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
56
|
+
interface Described extends Rules {
|
|
57
|
+
kind: Kind
|
|
58
|
+
default?: unknown
|
|
59
|
+
required?: boolean
|
|
60
|
+
live?: boolean
|
|
61
|
+
secret?: boolean
|
|
62
|
+
}
|
|
25
63
|
|
|
26
|
-
/**
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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(
|
|
36
|
-
this
|
|
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
|
|
45
|
-
*
|
|
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(
|
|
52
|
-
|
|
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
|
|
56
|
-
export function required(): Setting<
|
|
57
|
-
export function required(
|
|
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
|
-
|
|
62
|
-
): Setting<
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
*
|
|
84
|
-
*
|
|
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
|
|
88
|
-
|
|
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
|
-
/**
|
|
92
|
-
|
|
93
|
-
|
|
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
|
-
|
|
96
|
-
|
|
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
|
-
/**
|
|
101
|
-
export function
|
|
102
|
-
return
|
|
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
|
-
/**
|
|
106
|
-
|
|
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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
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
|
|
141
|
-
* Python
|
|
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
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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
|
-
|
|
598
|
+
throw new InvalidError(`${path}: ${(err as Error).message}`)
|
|
187
599
|
}
|
|
188
|
-
return values
|
|
189
600
|
}
|
|
190
601
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
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
|
|
200
|
-
if (
|
|
201
|
-
|
|
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
|
-
|
|
204
|
-
|
|
205
|
-
name = name.slice('export '.length).trim()
|
|
617
|
+
if (kind === 'env') {
|
|
618
|
+
return { env: await envData(layer as EnvLayer, declared) }
|
|
206
619
|
}
|
|
207
|
-
if (
|
|
208
|
-
|
|
620
|
+
if (isPlainObject(layer)) {
|
|
621
|
+
return { object: layer, place }
|
|
209
622
|
}
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
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
|
-
|
|
215
|
-
|
|
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
|
-
|
|
218
|
-
const
|
|
219
|
-
|
|
220
|
-
|
|
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
|
|
661
|
+
return { prefix: layer.prefix, vars: layer.vars, variables, files, dotenv }
|
|
223
662
|
}
|
|
224
663
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
for (
|
|
229
|
-
const
|
|
230
|
-
if (
|
|
231
|
-
|
|
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
|
-
|
|
673
|
+
return found
|
|
243
674
|
}
|
|
244
675
|
|
|
245
|
-
/** A
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
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
|
-
|
|
277
|
-
|
|
278
|
-
return
|
|
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
|
-
|
|
282
|
-
|
|
283
|
-
|
|
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
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
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
|
-
|
|
340
|
-
|
|
341
|
-
for (const
|
|
342
|
-
|
|
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
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
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
|
-
|
|
362
|
-
|
|
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
|
-
|
|
376
|
-
|
|
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
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
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
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
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
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
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
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
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
|
-
|
|
797
|
+
config.#following = config.#follow()
|
|
798
|
+
return config
|
|
419
799
|
}
|
|
420
800
|
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
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
|
-
|
|
429
|
-
|
|
430
|
-
|
|
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.#
|
|
433
|
-
|
|
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 (
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
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
|
-
/**
|
|
490
|
-
async
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
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
|
-
/**
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
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
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
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
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
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
|
|
877
|
+
return this.#following
|
|
539
878
|
}
|
|
540
|
-
}
|
|
541
879
|
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
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
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
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
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
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
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
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
|
-
|
|
918
|
+
const next = viewed(this.#declared, JSON.parse(answer.value ?? '{}')) as Value<D>
|
|
610
919
|
try {
|
|
611
|
-
|
|
612
|
-
} catch {
|
|
613
|
-
|
|
614
|
-
|
|
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
|
-
|
|
617
|
-
|
|
618
|
-
|
|
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
|
-
|
|
621
|
-
|
|
622
|
-
|
|
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
|
-
|
|
631
|
-
|
|
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
|
-
|
|
668
|
-
|
|
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
|
-
/**
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
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
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
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
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
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
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
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
|
}
|