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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/README.md +37 -37
  2. package/bin/tinystore.js +12 -1
  3. package/dist/backup.d.ts +33 -0
  4. package/dist/backup.js +49 -0
  5. package/dist/blobs.d.ts +160 -79
  6. package/dist/blobs.js +510 -217
  7. package/dist/channels.d.ts +90 -0
  8. package/dist/channels.js +291 -0
  9. package/dist/clock.js +3 -3
  10. package/dist/config.d.ts +209 -86
  11. package/dist/config.js +581 -538
  12. package/dist/connection.d.ts +64 -2
  13. package/dist/connection.js +201 -16
  14. package/dist/console.d.ts +27 -3
  15. package/dist/console.js +165 -12
  16. package/dist/dotenv.d.ts +7 -0
  17. package/dist/dotenv.js +79 -0
  18. package/dist/errors.d.ts +61 -1
  19. package/dist/errors.js +81 -1
  20. package/dist/handles.d.ts +44 -2
  21. package/dist/handles.js +81 -2
  22. package/dist/index.d.ts +17 -11
  23. package/dist/index.js +5 -3
  24. package/dist/instruments.d.ts +177 -0
  25. package/dist/instruments.js +819 -0
  26. package/dist/jobs.d.ts +335 -239
  27. package/dist/jobs.js +716 -536
  28. package/dist/json.d.ts +2 -0
  29. package/dist/json.js +122 -0
  30. package/dist/kv.d.ts +130 -243
  31. package/dist/kv.js +273 -640
  32. package/dist/limits.d.ts +80 -0
  33. package/dist/limits.js +139 -0
  34. package/dist/locks.d.ts +62 -0
  35. package/dist/locks.js +237 -0
  36. package/dist/logger.d.ts +45 -9
  37. package/dist/logger.js +150 -38
  38. package/dist/metrics.d.ts +210 -209
  39. package/dist/metrics.js +319 -556
  40. package/dist/once.d.ts +19 -18
  41. package/dist/once.js +74 -63
  42. package/dist/query.d.ts +181 -0
  43. package/dist/query.js +788 -0
  44. package/dist/records.d.ts +241 -150
  45. package/dist/records.js +507 -291
  46. package/dist/runtime/addon.d.ts +14 -0
  47. package/dist/runtime/addon.js +69 -0
  48. package/dist/runtime/bun.js +5 -7
  49. package/dist/runtime/node.js +5 -7
  50. package/dist/runtime/pipe.d.ts +17 -0
  51. package/dist/runtime/pipe.js +133 -0
  52. package/dist/runtime/shared.d.ts +6 -0
  53. package/dist/runtime/shared.js +19 -0
  54. package/dist/runtime.d.ts +5 -2
  55. package/dist/search.d.ts +189 -0
  56. package/dist/search.js +281 -0
  57. package/dist/session.d.ts +31 -3
  58. package/dist/session.js +153 -41
  59. package/dist/sql.d.ts +228 -78
  60. package/dist/sql.js +745 -240
  61. package/dist/store.d.ts +244 -24
  62. package/dist/store.js +270 -67
  63. package/dist/time.d.ts +5 -1
  64. package/dist/time.js +22 -2
  65. package/dist/tx.d.ts +61 -0
  66. package/dist/tx.js +314 -0
  67. package/dist/wire/codec.d.ts +23 -7
  68. package/dist/wire/codec.js +56 -35
  69. package/dist/wire/frame.d.ts +2 -0
  70. package/dist/wire/frame.js +31 -14
  71. package/dist/wire/messages.d.ts +259 -0
  72. package/dist/wire/messages.js +22 -0
  73. package/dist/wire/msgpack.d.ts +49 -1
  74. package/dist/wire/msgpack.js +293 -56
  75. package/dist/wire/protocol.d.ts +2683 -0
  76. package/dist/wire/protocol.js +10846 -0
  77. package/package.json +39 -38
  78. package/src/backup.ts +81 -0
  79. package/src/blobs.ts +678 -301
  80. package/src/channels.ts +377 -0
  81. package/src/clock.ts +4 -4
  82. package/src/config.ts +902 -612
  83. package/src/connection.ts +279 -21
  84. package/src/console.ts +180 -12
  85. package/src/dotenv.ts +82 -0
  86. package/src/errors.ts +105 -0
  87. package/src/handles.ts +157 -8
  88. package/src/index.ts +158 -52
  89. package/src/instruments.ts +1042 -0
  90. package/src/jobs.ts +1017 -733
  91. package/src/json.ts +133 -0
  92. package/src/kv.ts +424 -847
  93. package/src/limits.ts +202 -0
  94. package/src/locks.ts +320 -0
  95. package/src/logger.ts +209 -40
  96. package/src/metrics.ts +557 -752
  97. package/src/once.ts +86 -83
  98. package/src/query.ts +1005 -0
  99. package/src/records.ts +795 -418
  100. package/src/runtime/addon.ts +99 -0
  101. package/src/runtime/bun.ts +5 -7
  102. package/src/runtime/node.ts +5 -7
  103. package/src/runtime/pipe.ts +178 -0
  104. package/src/runtime/shared.ts +20 -0
  105. package/src/runtime.ts +5 -2
  106. package/src/search.ts +480 -0
  107. package/src/session.ts +187 -41
  108. package/src/sql.ts +993 -306
  109. package/src/store.ts +473 -78
  110. package/src/time.ts +48 -3
  111. package/src/tx.ts +426 -0
  112. package/src/wire/codec.ts +78 -37
  113. package/src/wire/frame.ts +44 -14
  114. package/src/wire/messages.ts +25 -0
  115. package/src/wire/msgpack.ts +327 -56
  116. package/src/wire/protocol.ts +11709 -0
  117. package/dist/limiter.d.ts +0 -45
  118. package/dist/limiter.js +0 -68
  119. package/dist/quota.d.ts +0 -44
  120. package/dist/quota.js +0 -98
  121. package/src/limiter.ts +0 -99
  122. package/src/quota.ts +0 -137
package/dist/config.js CHANGED
@@ -1,72 +1,257 @@
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
  import { readFile } from 'node:fs/promises';
6
- import { ClosedError, InvalidError } from './errors.js';
7
- import { checkName, handleOn } from './handles.js';
10
+ import { CancelledError, ConflictError, InvalidError, UnavailableError } from './errors.js';
8
11
  import { check, isSchema } from './schema.js';
9
- import { KvBucket, KvCall, KvConfigure, KvKept, methods } from './wire/messages.js';
10
- /** A field of a config's defaults made by `secret` or `required`, in place of its value. */
11
- export class Setting {
12
- kind;
13
- /** absent for a field a layer has to give */
14
- fallback;
15
- secret;
16
- /** its own variable, read in place of the prefix and its path */
17
- variable;
18
- constructor(kind, fallback, secret, variable) {
19
- this.kind = kind;
20
- this.fallback = fallback;
21
- this.secret = secret;
22
- this.variable = variable;
12
+ import { ConnectionLostError } from './session.js';
13
+ import { ms, spelled } from './time.js';
14
+ import { ConfigOpen, ConfigReset, ConfigUpdate, ConfigValue, Handle, methods, } from './wire/protocol.js';
15
+ // what marks a setting and a layer: text keys, so that a program's own keys
16
+ // never are one and the types say them in a published declaration
17
+ const mark = '~setting';
18
+ const layerMark = '~layer';
19
+ /** The tries a change makes while other changes race it. */
20
+ const attempts = 8;
21
+ /** A setting's text that prints as *** wherever it goes; `reveal` gives it. */
22
+ export class Secret {
23
+ #text;
24
+ constructor(text) {
25
+ this.#text = text;
26
+ }
27
+ /** The secret's text, where the program hands it to what needs it. */
28
+ reveal() {
29
+ return this.#text;
30
+ }
31
+ toString() {
32
+ return '***';
33
+ }
34
+ toJSON() {
35
+ return '***';
36
+ }
37
+ [Symbol.for('nodejs.util.inspect.custom')]() {
38
+ return '***';
23
39
  }
24
40
  }
41
+ function setting(described) {
42
+ return Object.freeze({ [mark]: described });
43
+ }
44
+ function describedOf(value) {
45
+ return typeof value === 'object' && value !== null && mark in value
46
+ ? value[mark]
47
+ : undefined;
48
+ }
49
+ function layerOf(value) {
50
+ return typeof value === 'object' && value !== null && layerMark in value
51
+ ? value[layerMark]
52
+ : undefined;
53
+ }
54
+ function kindOf(token) {
55
+ return token === String ? 'text' : token === Number ? 'number' : 'boolean';
56
+ }
57
+ function bounds(rules) {
58
+ const out = {};
59
+ if (rules?.min !== undefined) {
60
+ out.min = rules.min;
61
+ }
62
+ if (rules?.max !== undefined) {
63
+ out.max = rules.max;
64
+ }
65
+ return out;
66
+ }
25
67
  /**
26
- * A secret: never kept by update, and shown as *** by sources(). It reads
27
- * its own variable when given one, and is required without a default.
28
- *
29
- * ```ts
30
- * db: { url: secret('DATABASE_URL'), pool: 10 }
31
- * ```
68
+ * A setting that prints as *** wherever it goes and that only a layer gives:
69
+ * `secret(String)` must be given, `secret('')` has a default.
32
70
  */
33
- export function secret(variable, fallback) {
34
- return new Setting('string', fallback, true, variable);
71
+ export function secret(given) {
72
+ if (given === String) {
73
+ return setting({ kind: 'text', secret: true, required: true });
74
+ }
75
+ if (typeof given !== 'string') {
76
+ throw new InvalidError('a secret is text: secret(String), or secret with its default text');
77
+ }
78
+ return setting({ kind: 'text', secret: true, default: given });
79
+ }
80
+ export function required(given) {
81
+ const inner = typeof given === 'function' ? { kind: kindOf(given) } : describedOf(given);
82
+ if (inner === undefined) {
83
+ throw new InvalidError('required takes String, Number, Boolean, or a rule without its default');
84
+ }
85
+ if (inner.secret === true) {
86
+ throw new InvalidError('a secret is required already: secret(String)');
87
+ }
88
+ if (inner.live === true) {
89
+ throw new InvalidError('live is the outermost mark: live(required(…))');
90
+ }
91
+ const { default: _default, ...rest } = inner;
92
+ return setting({ ...rest, required: true });
35
93
  }
36
- export function required(kind = String) {
37
- return new Setting(kind === Number ? 'number' : kind === Boolean ? 'boolean' : 'string', undefined, false, undefined);
94
+ export function live(given) {
95
+ if (isPlainObject(given) && describedOf(given) === undefined && Object.keys(given).length > 0) {
96
+ throw new InvalidError('a mark goes on a setting, not on a group: mark each of its settings');
97
+ }
98
+ const inner = describedOf(given) ?? declaredValue(given, 'live');
99
+ if (inner.secret === true) {
100
+ throw new InvalidError('a secret is never live');
101
+ }
102
+ if (inner.live === true) {
103
+ throw new InvalidError('live twice');
104
+ }
105
+ return setting({ ...inner, live: true });
106
+ }
107
+ export function int(first, rules) {
108
+ if (typeof first === 'number') {
109
+ return setting({ kind: 'integer', default: first, ...bounds(rules) });
110
+ }
111
+ return setting({ kind: 'integer', ...bounds(first) });
112
+ }
113
+ export function oneOf(first, others = []) {
114
+ if (typeof first === 'string') {
115
+ return setting({ kind: 'text', default: first, oneOf: [first, ...others] });
116
+ }
117
+ return setting({ kind: 'text', oneOf: [...first] });
38
118
  }
39
- /** The environment as a layer of a config, which `fromEnv` makes. */
40
- export class FromEnv {
41
- prefix;
42
- files;
43
- constructor(prefix, files) {
44
- this.prefix = prefix;
45
- this.files = files;
119
+ export function duration(first, rules) {
120
+ const [fallback, given] = typeof first === 'string' ? [first, rules] : [undefined, first];
121
+ const described = { kind: 'duration' };
122
+ if (given?.min !== undefined) {
123
+ described.min = ms(given.min);
124
+ }
125
+ if (given?.max !== undefined) {
126
+ described.max = ms(given.max);
127
+ }
128
+ return setting(fallback === undefined ? described : { ...described, default: fallback });
129
+ }
130
+ export function list(item, options = {}) {
131
+ return setting({
132
+ kind: { list: itemOf(item) },
133
+ default: options.default ?? [],
134
+ ...bounds(options),
135
+ });
136
+ }
137
+ function itemOf(item) {
138
+ if (item === String || item === Number || item === Boolean) {
139
+ return { kind: kindOf(item) };
140
+ }
141
+ const inner = describedOf(item);
142
+ if (inner !== undefined) {
143
+ if (inner.live === true || inner.secret === true) {
144
+ throw new InvalidError("a list's items are neither live nor secret: the list is one setting");
145
+ }
146
+ const { kind, min, max, oneOf } = inner;
147
+ return { kind, ...bounds({ min, max }), ...(oneOf === undefined ? {} : { oneOf }) };
46
148
  }
149
+ if (isPlainObject(item)) {
150
+ return { group: declaredGroup(item, '[]') };
151
+ }
152
+ throw new InvalidError(`a list of ${String(item)}: of String, Number, Boolean, a rule or a group`);
153
+ }
154
+ /** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
155
+ export function file(path, options = {}) {
156
+ return Object.freeze({ [layerMark]: 'file', path, optional: options.optional === true });
47
157
  }
48
158
  /**
49
- * The environment as a config's layer: `fromEnv('APP')` reads db.pool from
50
- * APP_DB_POOL, and `fromEnv()` from DB_POOL. The .env files given are read
51
- * first, the process's own variables over them, a missing file skipped.
159
+ * The environment a config reads: `env('APP')` reads APP_ and each setting's
160
+ * path in upper snake case, `APP_LIMITS_RPS` for limits.rps.
52
161
  */
53
- export function fromEnv(prefix = '', ...files) {
54
- return new FromEnv(prefix, files);
162
+ export function env(prefix, options = {}) {
163
+ return Object.freeze({
164
+ [layerMark]: 'env',
165
+ prefix,
166
+ vars: flattened(options.vars ?? {}, ''),
167
+ files: [...(options.files ?? [])],
168
+ from: options.from,
169
+ });
170
+ }
171
+ function flattened(vars, path) {
172
+ const out = {};
173
+ for (const [key, value] of Object.entries(vars)) {
174
+ const at = path === '' ? key : `${path}.${key}`;
175
+ if (typeof value === 'string') {
176
+ out[at] = value;
177
+ }
178
+ else {
179
+ Object.assign(out, flattened(value, at));
180
+ }
181
+ }
182
+ return out;
183
+ }
184
+ function isPlainObject(value) {
185
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
186
+ return false;
187
+ }
188
+ const proto = Object.getPrototypeOf(value);
189
+ return proto === Object.prototype || proto === null;
190
+ }
191
+ function declaredGroup(value, path) {
192
+ const group = {};
193
+ for (const [key, field] of Object.entries(value)) {
194
+ group[key] = declaredNode(field, path === '' ? key : `${path}.${key}`);
195
+ }
196
+ return group;
197
+ }
198
+ function declaredNode(value, path) {
199
+ const described = describedOf(value);
200
+ if (described !== undefined) {
201
+ return described;
202
+ }
203
+ if (isPlainObject(value) && Object.keys(value).length > 0) {
204
+ return { group: declaredGroup(value, path) };
205
+ }
206
+ return declaredValue(value, path);
207
+ }
208
+ /** A setting a plain default declares: its kind is its default's. */
209
+ function declaredValue(value, path) {
210
+ switch (typeof value) {
211
+ case 'string':
212
+ return { kind: 'text', default: value };
213
+ case 'number':
214
+ return { kind: 'number', default: value };
215
+ case 'boolean':
216
+ return { kind: 'boolean', default: value };
217
+ case 'function':
218
+ throw new InvalidError(`${path}: a type is no default; required(${value.name}) declares one a layer must give`);
219
+ case 'undefined':
220
+ throw new InvalidError(`${path}: a setting has a default, or is required`);
221
+ }
222
+ if (value === null) {
223
+ return { kind: 'any', default: null };
224
+ }
225
+ if (Array.isArray(value)) {
226
+ return { kind: { list: plainItem(value[0]) }, default: value };
227
+ }
228
+ if (isPlainObject(value)) {
229
+ return { kind: 'object', default: {} };
230
+ }
231
+ throw new InvalidError(`${path}: ${String(value)} is no default a config keeps`);
55
232
  }
56
- /** A config's check, which `validate` makes. */
57
- export class Validate {
58
- schema;
59
- constructor(schema) {
60
- this.schema = schema;
233
+ function plainItem(first) {
234
+ switch (typeof first) {
235
+ case 'string':
236
+ return { kind: 'text' };
237
+ case 'number':
238
+ return { kind: 'number' };
239
+ case 'boolean':
240
+ return { kind: 'boolean' };
241
+ default:
242
+ return { kind: 'any' };
61
243
  }
62
244
  }
63
- /** Checks a config each time it is made, with zod's, valibot's or another Standard Schema. */
64
- export function validate(schema) {
65
- return new Validate(schema);
245
+ /** Every setting's path, as the core names its variable. */
246
+ function paths(group, path) {
247
+ return Object.entries(group).flatMap(([key, node]) => {
248
+ const at = path === '' ? key : `${path}.${key}`;
249
+ return 'group' in node ? paths(node.group, at) : [at];
250
+ });
66
251
  }
67
252
  /**
68
- * A field's variable: the prefix and its path in upper snake case, as Go's and
69
- * Python's configs name it.
253
+ * A setting's variable: the prefix and its path in upper snake case, as Go,
254
+ * Python and the core name it (testdata/config/env.json).
70
255
  *
71
256
  * 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
72
257
  */
@@ -93,546 +278,404 @@ export function envName(prefix, path) {
93
278
  const isUpper = (c) => c !== c.toLowerCase() && c === c.toUpperCase();
94
279
  const isLower = (c) => c !== c.toUpperCase() && c === c.toLowerCase();
95
280
  const isDigit = (c) => c >= '0' && c <= '9';
281
+ /** A file's text, none when it does not exist. */
282
+ async function readText(path) {
283
+ try {
284
+ return await readFile(path, 'utf8');
285
+ }
286
+ catch (err) {
287
+ if (err.code === 'ENOENT') {
288
+ return undefined;
289
+ }
290
+ throw new InvalidError(`${path}: ${err.message}`);
291
+ }
292
+ }
293
+ /** A layer as the core reads it, its files and variables read here. */
294
+ async function layerData(layer, place, declared) {
295
+ if (layer === false || layer === null || layer === undefined) {
296
+ return undefined;
297
+ }
298
+ const kind = layerOf(layer);
299
+ if (kind === 'file') {
300
+ const { path, optional } = layer;
301
+ const text = await readText(path);
302
+ return { file: { name: path, optional, ...(text === undefined ? {} : { text }) } };
303
+ }
304
+ if (kind === 'env') {
305
+ return { env: await envData(layer, declared) };
306
+ }
307
+ if (isPlainObject(layer)) {
308
+ return { object: layer, place };
309
+ }
310
+ throw new InvalidError(`layer ${place}: an object, file(…) or env(…)`);
311
+ }
96
312
  /**
97
- * The variables of a .env file, as Go's and Python's configs read one: NAME=value
98
- * lines, export before a name, # comments, a comment after a space, double
99
- * quotes reading \n \r \t \" and \\, single quotes reading nothing, a quoted
100
- * value over lines; a later name wins.
313
+ * What the environment gives, read here: the variables of every setting and
314
+ * those with the prefix, never the rest of the process's, the files their
315
+ * NAME_FILE names, and the .env files' text.
101
316
  */
102
- export function parseDotenv(text) {
103
- const values = {};
104
- let line = 1;
105
- let rest = text;
106
- while (rest !== '') {
107
- const [name, value, after] = dotenvAssignment(rest, line);
108
- line += rest.slice(0, rest.length - after.length).split('\n').length - 1;
109
- if (name !== '') {
110
- values[name] = value;
111
- }
112
- rest = after;
113
- }
114
- return values;
115
- }
116
- function dotenvAssignment(text, number) {
117
- const end = text.indexOf('\n');
118
- const line = end < 0 ? text : text.slice(0, end);
119
- const rest = end < 0 ? '' : text.slice(end + 1);
120
- const trimmed = line.trim();
121
- if (trimmed === '' || trimmed.startsWith('#')) {
122
- return ['', '', rest];
123
- }
124
- const equals = line.indexOf('=');
125
- if (equals < 0) {
126
- throw new InvalidError(`line ${number}: ${JSON.stringify(line)} is no NAME=value`);
127
- }
128
- let name = line.slice(0, equals).trim();
129
- if (name.startsWith('export ')) {
130
- name = name.slice('export '.length).trim();
131
- }
132
- if (!/^[\p{L}_][\p{L}\p{Nd}_]*$/u.test(name)) {
133
- throw new InvalidError(`line ${number}: ${JSON.stringify(name)} is no variable's name`);
134
- }
135
- let start = equals + 1;
136
- while (line[start] === ' ' || line[start] === '\t') {
137
- start++;
138
- }
139
- if (line[start] === '"' || line[start] === "'") {
140
- return [name, ...dotenvQuoted(text.slice(start), number)];
141
- }
142
- let value = line.slice(start);
143
- const comment = value.indexOf(' #');
144
- if (comment >= 0) {
145
- value = value.slice(0, comment);
146
- }
147
- return [name, value.replace(/[ \t\r]+$/, ''), rest];
148
- }
149
- function dotenvQuoted(text, number) {
150
- const quote = text[0];
151
- let out = '';
152
- for (let i = 1; i < text.length; i++) {
153
- const c = text[i];
154
- if (c === quote) {
155
- const end = text.indexOf('\n', i + 1);
156
- return [out, end < 0 ? '' : text.slice(end + 1)];
317
+ async function envData(layer, declared) {
318
+ const windows = process.platform === 'win32';
319
+ const key = (name) => (windows ? name.toUpperCase() : name);
320
+ const named = paths(declared, '').map(path => layer.vars[path] ?? envName(layer.prefix, path));
321
+ const wanted = new Set(named.flatMap(name => [key(name), key(`${name}_FILE`)]));
322
+ const start = key(`${layer.prefix}_`);
323
+ const variables = {};
324
+ for (const [name, value] of Object.entries(layer.from ?? process.env)) {
325
+ const k = key(name);
326
+ if (value !== undefined && (wanted.has(k) || (layer.prefix !== '' && k.startsWith(start)))) {
327
+ variables[k] = value;
328
+ }
329
+ }
330
+ const dotenv = [];
331
+ for (const name of layer.files) {
332
+ const text = await readText(name);
333
+ if (text !== undefined) {
334
+ dotenv.push({ name, text });
335
+ }
336
+ }
337
+ const files = {};
338
+ const namedFiles = [...Object.entries(variables), ...dotenv.flatMap(d => fileVariables(d.text))];
339
+ for (const [name, path] of namedFiles) {
340
+ if (name.endsWith('_FILE')) {
341
+ const text = await readText(path);
342
+ if (text !== undefined) {
343
+ files[path] = text;
344
+ }
157
345
  }
158
- if (c === '\\' && quote === '"' && i + 1 < text.length) {
159
- i++;
160
- const escaped = text[i];
161
- out += escaped === 'n' ? '\n' : escaped === 'r' ? '\r' : escaped === 't' ? '\t' : escaped;
346
+ }
347
+ return { prefix: layer.prefix, vars: layer.vars, variables, files, dotenv };
348
+ }
349
+ /** The NAME_FILE lines of a .env file's text, whose files the core cannot read. */
350
+ function fileVariables(text) {
351
+ const found = [];
352
+ for (const line of text.split('\n')) {
353
+ const match = /^\s*(?:export\s+)?([\p{L}_][\p{L}\p{Nd}_]*_FILE)\s*=\s*(.*?)\s*$/u.exec(line);
354
+ if (match !== null) {
355
+ found.push([match[1], match[2].replace(/^(['"])(.*)\1$/, '$2')]);
162
356
  }
163
- else {
164
- out += c;
357
+ }
358
+ return found;
359
+ }
360
+ /** A value as the program reads it: a duration spelled, a secret wrapped, all of it frozen. */
361
+ function viewed(group, value) {
362
+ const source = (isPlainObject(value) ? value : {});
363
+ const out = {};
364
+ for (const [key, node] of Object.entries(group)) {
365
+ out[key] = 'group' in node ? viewed(node.group, source[key]) : viewedSetting(node, source[key]);
366
+ }
367
+ return Object.freeze(out);
368
+ }
369
+ function viewedSetting(described, value) {
370
+ if (described.secret === true) {
371
+ return new Secret(typeof value === 'string' ? value : '');
372
+ }
373
+ return viewedKind(described.kind, value);
374
+ }
375
+ function viewedKind(kind, value) {
376
+ if (kind === 'duration' && typeof value === 'number') {
377
+ return spelled(value);
378
+ }
379
+ if (typeof kind === 'object' && Array.isArray(value)) {
380
+ const item = kind.list;
381
+ const items = value.map(each => 'group' in item ? viewed(item.group, each) : viewedKind(item.kind, each));
382
+ return Object.freeze(items);
383
+ }
384
+ return frozen(value);
385
+ }
386
+ function frozen(value) {
387
+ if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
388
+ for (const inner of Object.values(value)) {
389
+ frozen(inner);
165
390
  }
391
+ Object.freeze(value);
392
+ }
393
+ return value;
394
+ }
395
+ /** A partial value over a whole one: the groups it names merged, anything else replaced. */
396
+ function merged(value, changes) {
397
+ if (!isPlainObject(value) || !isPlainObject(changes)) {
398
+ return changes;
166
399
  }
167
- throw new InvalidError(`line ${number}: a value opened with ${quote} is never closed`);
400
+ const out = { ...value };
401
+ for (const [key, change] of Object.entries(changes)) {
402
+ out[key] = merged(value[key], change);
403
+ }
404
+ return out;
168
405
  }
169
- /** A config: open it with `store.kv.config(name, defaults, ...layers)`. */
406
+ /**
407
+ * A program's settings as one typed value, read from memory: open one with
408
+ * `store.config(name, [declaration, ...layers])`.
409
+ */
170
410
  export class Config {
171
411
  name;
172
412
  #link;
413
+ #declared;
173
414
  #open;
174
- #fields;
175
- #base;
176
- #from;
177
- #schemas = [];
178
- #listeners = new Set();
179
- /** the last fromEnv's prefix, for a missing field's variable */
180
- #prefix;
181
- #kept = new Map();
182
- #ignored = new Map();
183
- #value = {};
415
+ #check;
416
+ #handles = new WeakMap();
417
+ #watchers = new Set();
418
+ #value;
419
+ #version = 0;
420
+ #lines = [];
421
+ #notes = [];
422
+ /** why validate refused the newest value the store sent, a change another program made */
423
+ #refused;
424
+ #taking = Promise.resolve();
425
+ #newer = [];
184
426
  #stream;
185
- #closed = false;
186
- /** Configs come from `store.kv.config`, which lays their layers and waits for the first state. */
187
- constructor(link, name, defaults) {
188
- checkName(name, 'config');
427
+ #stopped = false;
428
+ /** the loop that follows the config, which ends once it is stopped */
429
+ #following = Promise.resolve();
430
+ constructor(link, name, declared, open, check) {
189
431
  this.#link = link;
190
432
  this.name = name;
191
- this.#open = KvBucket.encode({ name, config: true });
192
- this.#fields = new Map(leavesOf(defaults).map(([path, leaf]) => [path, fieldOf(leaf)]));
193
- this.#base = valuesOf(defaults);
194
- this.#from = new Map([...this.#fields].filter(([, field]) => !field.required).map(([path]) => [path, 'default']));
433
+ this.#declared = declared;
434
+ this.#open = open;
435
+ this.#check = check;
436
+ this.#value = viewed(declared, {});
437
+ }
438
+ /** Opens a config from its list: the declaration first, then its layers in order. */
439
+ static async open(link, name, layers, options) {
440
+ const [declaration, ...rest] = layers;
441
+ if (!isPlainObject(declaration)) {
442
+ throw new InvalidError(`config ${name}: the list's first entry is its declaration, an object`);
443
+ }
444
+ const declared = declaredGroup(declaration, '');
445
+ const data = await Promise.all(rest.map((layer, at) => layerData(layer, at + 2, declared)));
446
+ const open = ConfigOpen.encode({
447
+ name,
448
+ declaration: JSON.stringify(declared),
449
+ layers: JSON.stringify(data.filter(layer => layer !== undefined)),
450
+ strict: options.strict === true,
451
+ });
452
+ const config = new Config(link, name, declared, open, checkerOf(name, options.validate));
453
+ await link.run('read', connection => config.#handleOn(connection));
454
+ await config.#taking;
455
+ if (config.#refused !== undefined) {
456
+ throw config.#refused;
457
+ }
458
+ config.#following = config.#follow();
459
+ return config;
195
460
  }
196
- /** The config now, frozen: update changes it. */
461
+ /** The settings as they are now: a read of memory, so read it where it is used. */
197
462
  get value() {
198
463
  return this.#value;
199
464
  }
200
- /** Lays each layer over the defaults, the one before it under it, and checks what is required. */
201
- async lay(layers) {
202
- for (const layer of layers) {
203
- if (layer instanceof FromEnv) {
204
- await this.#layEnvironment(layer);
205
- }
206
- else if (layer instanceof Validate) {
207
- this.#schemas.push(layer.schema);
208
- }
209
- else if (isSchema(layer)) {
210
- throw new InvalidError(`config ${this.name}: a schema checks the config as validate(schema)`);
211
- }
212
- else if (plain(layer)) {
213
- this.#layFile(layer);
214
- }
215
- else {
216
- throw new InvalidError(`config ${this.name}: a layer is a file's values, fromEnv() or validate(), not ${String(layer)}`);
217
- }
218
- }
219
- for (const [path, field] of this.#fields) {
220
- if (field.required && missing(pathIn(this.#base, path))) {
221
- throw new InvalidError(`config ${this.name}: ${this.#requiredText(path, field)}`);
222
- }
223
- }
224
- this.#value = deepFreeze(structuredClone(this.#base));
465
+ /** The version of the changes the value holds, which `ifVersion` takes. */
466
+ get version() {
467
+ return this.#version;
225
468
  }
226
469
  /**
227
- * Changes the fields change names, at any depth; each one that changed is
228
- * checked, kept, and seen by every store watching the config. A change the
229
- * schema refuses, one of a secret, or one leaving a required field empty, is
230
- * InvalidError and keeps nothing.
470
+ * Changes live settings: the ones `changes` names are kept in the store, go
471
+ * over every layer until they are reset, and reach every handle of the
472
+ * config. The value they make passes validate first; all are kept or none.
231
473
  */
232
- async update(change) {
233
- const next = merged(structuredClone(this.#value), change);
234
- const set = [];
235
- for (const [path, field] of this.#fields) {
236
- const now = JSON.stringify(pathIn(next, path));
237
- if (now === JSON.stringify(pathIn(this.#value, path))) {
238
- continue;
239
- }
240
- if (field.secret) {
241
- throw new InvalidError(`config ${this.name}: ${path} is a secret, set by the defaults, a file or the environment alone`);
242
- }
243
- if (field.required && missing(pathIn(next, path))) {
244
- throw new InvalidError(`config ${this.name}: ${path} is required`);
474
+ async update(changes, options = {}) {
475
+ for (let tries = 1;; tries++) {
476
+ const version = options.ifVersion ?? this.#version;
477
+ await this.#check?.(merged(this.#value, changes));
478
+ const body = (handle) => ConfigUpdate.encode({ handle, version, changes: JSON.stringify(changes) });
479
+ try {
480
+ await this.#call('write', methods['config.update'], body);
481
+ return;
245
482
  }
246
- set.push(path, now);
247
- }
248
- if (set.length === 0) {
249
- return;
250
- }
251
- await this.#checked(next);
252
- await this.#send(set, []);
253
- }
254
- /** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
255
- async reset(...paths) {
256
- for (const path of paths) {
257
- if (![...this.#fields.keys()].some(leaf => under(leaf, path))) {
258
- throw new InvalidError(`config ${this.name} has no field ${path}`);
483
+ catch (err) {
484
+ if (!(err instanceof ConflictError) ||
485
+ options.ifVersion !== undefined ||
486
+ tries === attempts) {
487
+ throw err;
488
+ }
489
+ await this.#newerThan(version);
259
490
  }
260
491
  }
261
- const reset = [...this.#kept.keys()].filter(kept => paths.length === 0 || paths.some(path => under(kept, path)));
262
- if (reset.length > 0) {
263
- await this.#send([], reset);
264
- }
265
492
  }
266
- /** Calls fn with the config now and after each change, whoever made it; the function it returns stops that. */
267
- watch(fn) {
268
- this.#listeners.add(fn);
269
- fn(this.#value);
270
- return () => this.#listeners.delete(fn);
271
- }
272
- /** Where each field's value came from, and why a kept value is left out. */
273
- sources() {
274
- return [...this.#fields].map(([path, field]) => {
275
- const kept = this.#kept.has(path) && !this.#ignored.has(path);
276
- const source = {
277
- path,
278
- value: field.secret ? '***' : (JSON.stringify(pathIn(this.#value, path)) ?? 'null'),
279
- from: kept ? 'kept' : (this.#from.get(path) ?? 'default'),
280
- };
281
- const ignored = this.#ignored.get(path);
282
- return ignored === undefined ? source : { ...source, ignored };
283
- });
493
+ /** Drops the change kept of the setting or the group at `path`, or of every setting. */
494
+ async reset(path = '') {
495
+ await this.#call('write', methods['config.reset'], handle => ConfigReset.encode({ handle, path }));
284
496
  }
285
- /** Follows the config's changes until the store closes; resolves once the first state is read. */
286
- start() {
287
- return new Promise((resolve, reject) => {
288
- void this.#follow(resolve, reject);
289
- });
497
+ /**
498
+ * Calls `watcher` with the settings now, then with each change and the value
499
+ * before it, made in this process or another. It returns the call that stops it.
500
+ */
501
+ watch(watcher) {
502
+ this.#watchers.add(watcher);
503
+ watcher(this.#value, undefined);
504
+ return () => {
505
+ this.#watchers.delete(watcher);
506
+ };
507
+ }
508
+ /** Every setting with its value, the layer that gave it and what it went over. */
509
+ explain() {
510
+ const refused = this.#refused === undefined ? [] : [`a value validate refused: ${this.#refused.message}`];
511
+ return Object.assign([...this.#lines], { notes: [...this.#notes, ...refused] });
290
512
  }
291
- /** Stops following the config, as the store does when it closes. */
513
+ /**
514
+ * Stops following the config: the store closes. It resolves once the
515
+ * stream that follows it is cancelled, so that the store's connection
516
+ * ends after its CANCEL: a stream the server still ran would keep a
517
+ * private child, or a sidecar's connection, draining for ten seconds.
518
+ */
292
519
  stop() {
293
- this.#closed = true;
520
+ this.#stopped = true;
521
+ this.#watchers.clear();
294
522
  this.#stream?.cancel();
523
+ for (const wake of this.#newer.splice(0)) {
524
+ wake();
525
+ }
526
+ return this.#following;
295
527
  }
296
- #layFile(values) {
297
- for (const [path, value] of leavesOf(values)) {
298
- const field = this.#fields.get(path);
299
- if (field === undefined) {
300
- continue;
301
- }
302
- if (!fits(value, field.sample)) {
303
- throw new InvalidError(`the file's ${path}: ${JSON.stringify(value)} is no ${kindOf(field.sample)}`);
304
- }
305
- setPath(this.#base, path, value);
306
- this.#from.set(path, 'file');
528
+ /** Runs a call on the config's handle on the link's connection, and takes the value it answers. */
529
+ async #call(idempotence, method, body) {
530
+ await this.#link.run(idempotence, async (connection) => {
531
+ const handle = await this.#handleOn(connection);
532
+ await this.#take(ConfigValue.decode(await connection.session.call(method, body(handle))));
533
+ });
534
+ }
535
+ /** The config's handle on a connection, opened there first, its value taken. */
536
+ #handleOn(connection) {
537
+ let handle = this.#handles.get(connection);
538
+ if (handle === undefined) {
539
+ handle = connection.session.call(methods['config.open'], this.#open).then(async (body) => {
540
+ const opened = ConfigValue.decode(body);
541
+ await this.#take(opened);
542
+ return opened.handle ?? 0;
543
+ });
544
+ this.#handles.set(connection, handle);
545
+ handle.catch(() => this.#handles.delete(connection));
307
546
  }
547
+ return handle;
308
548
  }
309
- async #layEnvironment(layer) {
310
- const variables = {};
311
- for (const file of layer.files) {
312
- Object.assign(variables, await readDotenv(file));
549
+ /** Takes a value the store sent, in the order it came; an older one than this has is left. */
550
+ #take(answer) {
551
+ this.#taking = this.#taking.then(() => this.#accept(answer));
552
+ return this.#taking;
553
+ }
554
+ async #accept(answer) {
555
+ const version = answer.version ?? 0;
556
+ if (version < this.#version || (version === this.#version && this.#lines.length > 0)) {
557
+ return;
313
558
  }
314
- Object.assign(variables, process.env);
315
- for (const [path, field] of this.#fields) {
316
- const name = field.variable ?? envName(layer.prefix, path);
317
- const text = variables[name];
318
- if (text !== undefined) {
319
- setPath(this.#base, path, readVariable(text, field.sample, name));
320
- this.#from.set(path, `env ${name}`);
559
+ const next = viewed(this.#declared, JSON.parse(answer.value ?? '{}'));
560
+ try {
561
+ await this.#check?.(next);
562
+ }
563
+ catch (err) {
564
+ this.#refused = err instanceof InvalidError ? err : new InvalidError(err.message);
565
+ if (this.#lines.length > 0) {
566
+ process.stderr.write(`version ${version}: ${this.#refused.message}; the value before it stays\n`);
567
+ }
568
+ return;
569
+ }
570
+ const previous = this.#value;
571
+ this.#refused = undefined;
572
+ this.#value = next;
573
+ this.#version = version;
574
+ this.#lines = (answer.lines ?? []).map(line => ({
575
+ path: line.path ?? '',
576
+ value: line.value ?? '',
577
+ from: line.from ?? '',
578
+ over: (line.over ?? []).join(', '),
579
+ }));
580
+ this.#notes = answer.notes ?? [];
581
+ for (const wake of this.#newer.splice(0)) {
582
+ wake();
583
+ }
584
+ for (const watcher of this.#watchers) {
585
+ try {
586
+ watcher(next, previous);
587
+ }
588
+ catch (err) {
589
+ process.stderr.write(`config ${this.name}: a watcher threw: ${err.message}\n`);
321
590
  }
322
591
  }
323
- this.#prefix = layer.prefix;
324
592
  }
325
- #requiredText(path, field) {
326
- if (this.#prefix === undefined) {
327
- return `${path} is required`;
593
+ /** Waits until a version later than `version` came, or a second passed. */
594
+ #newerThan(version) {
595
+ if (this.#version > version || this.#stopped) {
596
+ return Promise.resolve();
328
597
  }
329
- return `${path} is required: set ${field.variable ?? envName(this.#prefix, path)}`;
598
+ return new Promise(resolve => {
599
+ const timer = setTimeout(resolve, 1000);
600
+ this.#newer.push(() => {
601
+ clearTimeout(timer);
602
+ resolve();
603
+ });
604
+ });
330
605
  }
331
- async #follow(ready, failed) {
332
- let first = true;
333
- for (let pause = 100; !this.#closed; pause = Math.min(pause * 2, 5000)) {
606
+ /**
607
+ * Follows the config on one stream until the store closes: a lost
608
+ * connection or a server going away follows again on the next one.
609
+ */
610
+ async #follow() {
611
+ while (!this.#stopped) {
334
612
  try {
335
- await this.#link.run('read', async (connection) => {
336
- const handle = await handleOn(connection, methods['kv.open'], this.#open);
337
- const stream = await connection.session.open(methods['kv.watch'], KvCall.encode({ handle }), true);
338
- this.#stream = stream;
339
- await stream.next();
340
- for (;;) {
341
- const event = await stream.next();
342
- stream.consumed(event.body.length);
343
- if (event.end) {
344
- return;
345
- }
346
- await this.#apply(KvKept.decode(event.body).fields ?? []);
347
- pause = 100;
348
- if (first) {
349
- first = false;
350
- ready();
351
- }
613
+ const stream = await this.#link.run('read', async (connection) => {
614
+ const handle = await this.#handleOn(connection);
615
+ if (this.#stopped) {
616
+ return undefined;
617
+ }
618
+ const opened = await connection.session.open(methods['config.follow'], Handle.encode({ handle }), true);
619
+ // kept before its first answer, so that a stop meanwhile cancels it
620
+ this.#stream = opened;
621
+ if (this.#stopped) {
622
+ opened.cancel();
352
623
  }
624
+ await opened.next();
625
+ return opened;
353
626
  });
354
- }
355
- catch (err) {
356
- if (first) {
357
- failed(err);
627
+ if (stream === undefined) {
358
628
  return;
359
629
  }
360
- if (this.#closed || err instanceof ClosedError) {
630
+ this.#stream = stream;
631
+ if (this.#stopped) {
632
+ stream.cancel();
361
633
  return;
362
634
  }
635
+ for (;;) {
636
+ const event = await stream.next();
637
+ stream.consumed(event.body.length);
638
+ if (event.end) {
639
+ break;
640
+ }
641
+ await this.#take(ConfigValue.decode(event.body));
642
+ }
363
643
  }
364
- await new Promise(resolve => setTimeout(resolve, pause));
365
- }
366
- }
367
- /** Keeps set, path and JSON each, and forgets reset, then makes the config with them. */
368
- async #send(set, reset) {
369
- await this.#link.run('write', async (connection) => {
370
- const handle = await handleOn(connection, methods['kv.open'], this.#open);
371
- const body = KvConfigure.encode({
372
- handle,
373
- set: set.length > 0 ? set : undefined,
374
- reset: reset.length > 0 ? reset : undefined,
375
- });
376
- await connection.session.call(methods['kv.configure'], body);
377
- });
378
- const kept = new Map(this.#kept);
379
- for (let i = 0; i + 1 < set.length; i += 2) {
380
- kept.set(set[i], set[i + 1]);
381
- }
382
- for (const path of reset) {
383
- kept.delete(path);
384
- }
385
- await this.#build(kept);
386
- }
387
- /** Takes up the kept fields a watch sent. */
388
- async #apply(fields) {
389
- const kept = new Map();
390
- for (let i = 0; i + 1 < fields.length; i += 2) {
391
- kept.set(fields[i], fields[i + 1]);
392
- }
393
- await this.#build(kept);
394
- }
395
- /** Makes the config from its base and what is kept, leaving out what no longer fits, and tells the watchers. */
396
- async #build(kept) {
397
- const ignored = new Map();
398
- let next = withKept(this.#base, this.#fields, kept, ignored);
399
- let issues = await this.#issues(next);
400
- if (issues !== undefined && kept.size > ignored.size) {
401
- for (const path of kept.keys()) {
402
- ignored.set(path, ignored.get(path) ?? `the config fails with it: ${issues}`);
403
- }
404
- next = structuredClone(this.#base);
405
- issues = await this.#issues(next);
406
- }
407
- if (issues !== undefined) {
408
- throw new InvalidError(`config ${this.name}: ${issues}`);
409
- }
410
- const changed = JSON.stringify(next) !== JSON.stringify(this.#value);
411
- this.#kept = kept;
412
- this.#ignored = ignored;
413
- this.#value = deepFreeze(next);
414
- if (changed) {
415
- for (const listener of this.#listeners) {
416
- listener(this.#value);
417
- }
418
- }
419
- }
420
- async #checked(value) {
421
- const issues = await this.#issues(value);
422
- if (issues !== undefined) {
423
- throw new InvalidError(`config ${this.name}: ${issues}`);
424
- }
425
- }
426
- async #issues(value) {
427
- for (const schema of this.#schemas) {
428
- const checked = await check(schema, value);
429
- if ('issues' in checked) {
430
- return checked.issues;
644
+ catch (err) {
645
+ if (this.#stopped) {
646
+ return;
647
+ }
648
+ const passing = err instanceof ConnectionLostError ||
649
+ err instanceof UnavailableError ||
650
+ err instanceof CancelledError;
651
+ if (!passing) {
652
+ await new Promise(resolve => setTimeout(resolve, 1000));
653
+ }
431
654
  }
432
655
  }
433
- return undefined;
434
656
  }
435
657
  }
436
- function fieldOf(leaf) {
437
- if (!(leaf instanceof Setting)) {
438
- return { sample: leaf, secret: false, required: false, variable: undefined };
658
+ /** The check a config's validate makes of a whole value, throwing InvalidError when it refuses. */
659
+ function checkerOf(name, validate) {
660
+ if (validate === undefined) {
661
+ return undefined;
439
662
  }
440
- return {
441
- sample: leaf.fallback ?? { string: '', number: 0, boolean: false }[leaf.kind],
442
- secret: leaf.secret,
443
- required: leaf.fallback === undefined,
444
- variable: leaf.variable,
445
- };
446
- }
447
- /** The defaults' values: a Setting's default, and nothing for one without. */
448
- function valuesOf(tree) {
449
- const values = {};
450
- for (const [key, inner] of Object.entries(tree)) {
451
- if (inner instanceof Setting) {
452
- if (inner.fallback !== undefined) {
453
- values[key] = inner.fallback;
663
+ if (isSchema(validate)) {
664
+ return async (value) => {
665
+ const checked = await check(validate, value);
666
+ if ('issues' in checked) {
667
+ throw new InvalidError(`config ${name}: ${checked.issues}`);
454
668
  }
455
- }
456
- else {
457
- values[key] = plain(inner) ? valuesOf(inner) : structuredClone(inner);
458
- }
669
+ };
459
670
  }
460
- return values;
461
- }
462
- /** A required field's value no layer gave, or gave empty. */
463
- function missing(value) {
464
- return value === undefined || value === '';
465
- }
466
- async function readDotenv(path) {
467
- let text;
468
- try {
469
- text = await readFile(path, 'utf8');
470
- }
471
- catch (err) {
472
- if (err.code === 'ENOENT') {
473
- return {};
474
- }
475
- throw err;
476
- }
477
- try {
478
- return parseDotenv(text);
479
- }
480
- catch (err) {
481
- throw new InvalidError(`${path}: ${err.message}`);
482
- }
483
- }
484
- /** The base with each kept value that fits its field over it; a secret is never taken from what was kept. */
485
- function withKept(base, fields, kept, ignored) {
486
- const next = structuredClone(base);
487
- for (const [path, spelled] of kept) {
488
- const field = fields.get(path);
489
- if (field === undefined) {
490
- ignored.set(path, 'the config has no such field');
491
- continue;
492
- }
493
- if (field.secret) {
494
- ignored.set(path, 'the field is a secret');
495
- continue;
496
- }
497
- let value;
671
+ return async (value) => {
498
672
  try {
499
- value = JSON.parse(spelled);
500
- }
501
- catch {
502
- ignored.set(path, `${spelled} is no JSON`);
503
- continue;
504
- }
505
- if (!fits(value, field.sample)) {
506
- ignored.set(path, `${spelled} is no ${kindOf(field.sample)}`);
507
- continue;
508
- }
509
- if (field.required && missing(value)) {
510
- ignored.set(path, 'the field is required');
511
- continue;
673
+ await validate(value);
512
674
  }
513
- setPath(next, path, value);
514
- }
515
- return next;
516
- }
517
- /**
518
- * A variable's text as a value of its default's kind: a number, true or
519
- * false, a list split at its commas or given as JSON, and anything else as JSON.
520
- *
521
- * 8080 ← '3000' → 3000, ['x'] ← 'a.com, b.com' → ['a.com', 'b.com']
522
- */
523
- function readVariable(text, wanted, name) {
524
- const trimmed = text.trim();
525
- if (typeof wanted === 'string') {
526
- return text;
527
- }
528
- if (typeof wanted === 'number') {
529
- const n = Number(trimmed);
530
- if (trimmed === '' || !Number.isFinite(n)) {
531
- throw new InvalidError(`${name}: ${JSON.stringify(text)} is no number`);
532
- }
533
- return n;
534
- }
535
- if (typeof wanted === 'boolean') {
536
- if (['1', 't', 'T', 'TRUE', 'true', 'True'].includes(trimmed)) {
537
- return true;
675
+ catch (err) {
676
+ throw err instanceof InvalidError
677
+ ? err
678
+ : new InvalidError(`config ${name}: ${err.message}`);
538
679
  }
539
- if (['0', 'f', 'F', 'FALSE', 'false', 'False'].includes(trimmed)) {
540
- return false;
541
- }
542
- throw new InvalidError(`${name}: ${JSON.stringify(text)} is not true or false`);
543
- }
544
- if (Array.isArray(wanted) && !trimmed.startsWith('[')) {
545
- const item = wanted[0] ?? '';
546
- return trimmed === ''
547
- ? []
548
- : trimmed.split(',').map(part => readVariable(part.trim(), item, name));
549
- }
550
- try {
551
- const value = JSON.parse(trimmed);
552
- if (fits(value, wanted)) {
553
- return value;
554
- }
555
- }
556
- catch {
557
- // refused below, naming the variable
558
- }
559
- throw new InvalidError(`${name}: ${JSON.stringify(text)} is no ${kindOf(wanted)}`);
560
- }
561
- /** A value's fields to the last that is not a plain object, by their dotted paths. */
562
- function leavesOf(value, parent = '') {
563
- const leaves = [];
564
- for (const [key, inner] of Object.entries(value)) {
565
- const path = parent === '' ? key : `${parent}.${key}`;
566
- if (plain(inner)) {
567
- leaves.push(...leavesOf(inner, path));
568
- }
569
- else {
570
- leaves.push([path, inner]);
571
- }
572
- }
573
- return leaves;
574
- }
575
- function plain(value) {
576
- return (typeof value === 'object' &&
577
- value !== null &&
578
- !Array.isArray(value) &&
579
- !(value instanceof Date) &&
580
- !(value instanceof Setting) &&
581
- !(value instanceof FromEnv) &&
582
- !(value instanceof Validate));
583
- }
584
- /** A value fits a field when it is of its default's kind; a default of null takes anything. */
585
- function fits(value, wanted) {
586
- if (wanted === null || wanted === undefined) {
587
- return true;
588
- }
589
- if (Array.isArray(wanted)) {
590
- return Array.isArray(value);
591
- }
592
- return typeof value === typeof wanted && (typeof wanted !== 'object' || plain(value));
593
- }
594
- function kindOf(wanted) {
595
- return Array.isArray(wanted) ? 'list' : typeof wanted;
596
- }
597
- function pathIn(tree, path) {
598
- let at = tree;
599
- for (const name of path.split('.')) {
600
- if (!plain(at)) {
601
- return undefined;
602
- }
603
- at = at[name];
604
- }
605
- return at;
606
- }
607
- function setPath(tree, path, value) {
608
- const names = path.split('.');
609
- let at = tree;
610
- for (const name of names.slice(0, -1)) {
611
- const inner = at[name];
612
- if (!plain(inner)) {
613
- at[name] = {};
614
- }
615
- at = at[name];
616
- }
617
- at[names[names.length - 1]] = value;
618
- }
619
- /** change merged into tree at every depth; a list is replaced whole. */
620
- function merged(tree, change) {
621
- for (const [key, value] of Object.entries(change)) {
622
- const inner = tree[key];
623
- tree[key] = plain(value) && plain(inner) ? merged(inner, value) : value;
624
- }
625
- return tree;
626
- }
627
- function under(path, given) {
628
- return path === given || path.startsWith(`${given}.`);
629
- }
630
- function deepFreeze(value) {
631
- if (typeof value === 'object' && value !== null) {
632
- for (const inner of Object.values(value)) {
633
- deepFreeze(inner);
634
- }
635
- Object.freeze(value);
636
- }
637
- return value;
680
+ };
638
681
  }