@tinyshed/tinystore 0.1.0-rc.2 → 0.1.0-rc.4

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 CHANGED
@@ -28,7 +28,9 @@ import { open } from '@tinyshed/tinystore'
28
28
 
29
29
  await using store = await open('./data')
30
30
 
31
- const db = await store.sql('app')
31
+ const db = await store.sql('app', {
32
+ migrations: { '0001_users.sql': 'create table users (id integer primary key, name text)' },
33
+ })
32
34
  await db.exec`insert into users (id, name) values (${42}, ${'Ada'})`
33
35
 
34
36
  const sessions = store.kv.bucket<string>('sessions', { sliding: '30d' })
@@ -61,14 +63,14 @@ contains. With npm, pnpm or Yarn, install it as `npm install @tinyshed/tinystore
61
63
 
62
64
  <!-- landing:engines -->
63
65
 
64
- | | | |
65
- |---|---|---|
66
- | [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/sql/README.md) | Relational state | The application's own SQL databases: tables from structs, checked migrations. |
67
- | [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md) | Application state | Current state: typed buckets, counters, expiry, versions. |
68
- | [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md) | Durable background work | Work that runs at its time: retries, leases, repeats. |
69
- | [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md) | Files and objects | Files by path, checked when read whole. |
70
- | [Records](https://github.com/tinyshed/tinystore/blob/main/docs/records/README.md) | Logs and events | Read by time, level and keys. |
71
- | [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
66
+ | | | |
67
+ |-----------------------------------------------------------------------------------|-------------------------|-------------------------------------------------------------------------------|
68
+ | [SQL](https://github.com/tinyshed/tinystore/blob/main/docs/sql/README.md) | Relational state | The application's own SQL databases: tables from structs, checked migrations. |
69
+ | [KV](https://github.com/tinyshed/tinystore/blob/main/docs/kv/README.md) | Application state | Current state: typed buckets, counters, expiry, versions. |
70
+ | [Jobs](https://github.com/tinyshed/tinystore/blob/main/docs/jobs/README.md) | Durable background work | Work that runs at its time: retries, leases, repeats. |
71
+ | [Blobs](https://github.com/tinyshed/tinystore/blob/main/docs/blobs/README.md) | Files and objects | Files by path, checked when read whole. |
72
+ | [Records](https://github.com/tinyshed/tinystore/blob/main/docs/records/README.md) | Logs and events | Read by time, level and keys. |
73
+ | [Metrics](https://github.com/tinyshed/tinystore/blob/main/docs/metrics/README.md) | Time series | Samples kept bit for bit, answered exactly. |
72
74
 
73
75
  <!-- /landing:engines -->
74
76
 
package/dist/config.d.ts CHANGED
@@ -4,18 +4,57 @@ import { type StandardSchemaV1 } from './schema.ts';
4
4
  export type DeepPartial<T> = {
5
5
  [K in keyof T]?: T[K] extends readonly unknown[] ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K];
6
6
  };
7
- export interface ConfigOptions<T> {
8
- /** a file's values over the defaults, as Bun reads YAML, JSON or TOML: `import file from './config.yaml'` */
9
- file?: DeepPartial<T>;
10
- /** the variables' prefix: 'APP' reads APP_PORT; none when absent */
11
- prefix?: string;
12
- /** a field's own variable, by its path: `{ dbUrl: 'DATABASE_URL' }`; false reads none */
13
- env?: Record<string, string> | false;
14
- /** paths set by the defaults, the file or the environment alone: never kept, shown as *** */
15
- secret?: readonly string[];
16
- /** checks the config each time it is made: zod's, valibot's or another Standard Schema */
17
- schema?: StandardSchemaV1<unknown, T>;
7
+ type Kind = 'string' | 'number' | 'boolean';
8
+ /** A field of a config's defaults made by `secret` or `required`, in place of its value. */
9
+ export declare class Setting<V> {
10
+ readonly kind: Kind;
11
+ /** absent for a field a layer has to give */
12
+ readonly fallback: V | undefined;
13
+ readonly secret: boolean;
14
+ /** its own variable, read in place of the prefix and its path */
15
+ readonly variable: string | undefined;
16
+ constructor(kind: Kind, fallback: V | undefined, secret: boolean, variable: string | undefined);
18
17
  }
18
+ /**
19
+ * A secret: never kept by update, and shown as *** by sources(). It reads
20
+ * its own variable when given one, and is required without a default.
21
+ *
22
+ * ```ts
23
+ * db: { url: secret('DATABASE_URL'), pool: 10 }
24
+ * ```
25
+ */
26
+ export declare function secret(variable?: string, fallback?: string): Setting<string>;
27
+ /** A field a layer has to give, or the config does not open: a string unless kind says. */
28
+ export declare function required(): Setting<string>;
29
+ export declare function required(kind: StringConstructor): Setting<string>;
30
+ export declare function required(kind: NumberConstructor): Setting<number>;
31
+ export declare function required(kind: BooleanConstructor): Setting<boolean>;
32
+ /** The environment as a layer of a config, which `fromEnv` makes. */
33
+ export declare class FromEnv {
34
+ readonly prefix: string;
35
+ readonly files: readonly string[];
36
+ constructor(prefix: string, files: readonly string[]);
37
+ }
38
+ /**
39
+ * The environment as a config's layer: `fromEnv('APP')` reads db.pool from
40
+ * APP_DB_POOL, and `fromEnv()` from DB_POOL. The .env files given are read
41
+ * first, the process's own variables over them, a missing file skipped.
42
+ */
43
+ export declare function fromEnv(prefix?: string, ...files: string[]): FromEnv;
44
+ /** A config's check, which `validate` makes. */
45
+ export declare class Validate {
46
+ readonly schema: StandardSchemaV1;
47
+ constructor(schema: StandardSchemaV1);
48
+ }
49
+ /** Checks a config each time it is made, with zod's, valibot's or another Standard Schema. */
50
+ export declare function validate(schema: StandardSchemaV1): Validate;
51
+ /** A config's value, as its defaults make it: each Setting its value's type. */
52
+ export type ConfigValue<D extends object> = {
53
+ [K in keyof D]: FieldValue<D[K]>;
54
+ };
55
+ type FieldValue<F> = F extends Setting<infer V> ? V : F extends readonly unknown[] | Date ? F : F extends object ? ConfigValue<F> : F;
56
+ /** What a config takes after its defaults, each over the one before. */
57
+ export type ConfigLayer<V> = DeepPartial<V> | FromEnv | Validate;
19
58
  /** Where a field's value came from. */
20
59
  export interface Source {
21
60
  path: string;
@@ -33,18 +72,28 @@ export interface Source {
33
72
  * 'APP', 'limits.maxRps' → APP_LIMITS_MAX_RPS
34
73
  */
35
74
  export declare function envName(prefix: string, path: string): string;
36
- /** A config: open it with `store.kv.config(name, defaults, options)`. */
75
+ /**
76
+ * The variables of a .env file, as Go's and Python's configs read one: NAME=value
77
+ * lines, export before a name, # comments, a comment after a space, double
78
+ * quotes reading \n \r \t \" and \\, single quotes reading nothing, a quoted
79
+ * value over lines; a later name wins.
80
+ */
81
+ export declare function parseDotenv(text: string): Record<string, string>;
82
+ /** A config: open it with `store.kv.config(name, defaults, ...layers)`. */
37
83
  export declare class Config<T extends object> {
38
84
  #private;
39
85
  readonly name: string;
40
- /** Configs come from `store.kv.config`, which waits for the first state. */
41
- constructor(link: Link, name: string, defaults: T, options: ConfigOptions<T>);
86
+ /** Configs come from `store.kv.config`, which lays their layers and waits for the first state. */
87
+ constructor(link: Link, name: string, defaults: object);
42
88
  /** The config now, frozen: update changes it. */
43
89
  get value(): T;
90
+ /** Lays each layer over the defaults, the one before it under it, and checks what is required. */
91
+ lay(layers: readonly unknown[]): Promise<void>;
44
92
  /**
45
93
  * Changes the fields change names, at any depth; each one that changed is
46
94
  * checked, kept, and seen by every store watching the config. A change the
47
- * schema refuses, or one of a secret, is InvalidError and keeps nothing.
95
+ * schema refuses, one of a secret, or one leaving a required field empty, is
96
+ * InvalidError and keeps nothing.
48
97
  */
49
98
  update(change: DeepPartial<T>): Promise<void>;
50
99
  /** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
@@ -58,3 +107,4 @@ export declare class Config<T extends object> {
58
107
  /** Stops following the config, as the store does when it closes. */
59
108
  stop(): void;
60
109
  }
110
+ export {};
package/dist/config.js CHANGED
@@ -1,11 +1,69 @@
1
1
  // An application's settings, as Go's kv.Config makes them: the defaults, then
2
- // a file's values, then the environment, then what update kept, which the
3
- // server keeps field by field in kv.db and sends to every store watching the
4
- // config. `value` is read from memory and is new after each change.
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.
5
+ import { readFile } from 'node:fs/promises';
5
6
  import { ClosedError, InvalidError } from './errors.js';
6
7
  import { checkName, handleOn } from './handles.js';
7
- import { check } from './schema.js';
8
+ import { check, isSchema } from './schema.js';
8
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;
23
+ }
24
+ }
25
+ /**
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
+ * ```
32
+ */
33
+ export function secret(variable, fallback) {
34
+ return new Setting('string', fallback, true, variable);
35
+ }
36
+ export function required(kind = String) {
37
+ return new Setting(kind === Number ? 'number' : kind === Boolean ? 'boolean' : 'string', undefined, false, undefined);
38
+ }
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;
46
+ }
47
+ }
48
+ /**
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.
52
+ */
53
+ export function fromEnv(prefix = '', ...files) {
54
+ return new FromEnv(prefix, files);
55
+ }
56
+ /** A config's check, which `validate` makes. */
57
+ export class Validate {
58
+ schema;
59
+ constructor(schema) {
60
+ this.schema = schema;
61
+ }
62
+ }
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);
66
+ }
9
67
  /**
10
68
  * A field's variable: the prefix and its path in upper snake case, as Go's and
11
69
  * Python's configs name it.
@@ -35,57 +93,155 @@ export function envName(prefix, path) {
35
93
  const isUpper = (c) => c !== c.toLowerCase() && c === c.toUpperCase();
36
94
  const isLower = (c) => c !== c.toUpperCase() && c === c.toLowerCase();
37
95
  const isDigit = (c) => c >= '0' && c <= '9';
38
- /** A config: open it with `store.kv.config(name, defaults, options)`. */
96
+ /**
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.
101
+ */
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)];
157
+ }
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;
162
+ }
163
+ else {
164
+ out += c;
165
+ }
166
+ }
167
+ throw new InvalidError(`line ${number}: a value opened with ${quote} is never closed`);
168
+ }
169
+ /** A config: open it with `store.kv.config(name, defaults, ...layers)`. */
39
170
  export class Config {
40
171
  name;
41
172
  #link;
42
173
  #open;
43
- #leaves;
174
+ #fields;
44
175
  #base;
45
176
  #from;
46
- #secret;
47
- #schema;
177
+ #schemas = [];
48
178
  #listeners = new Set();
179
+ /** the last fromEnv's prefix, for a missing field's variable */
180
+ #prefix;
49
181
  #kept = new Map();
50
182
  #ignored = new Map();
51
- #value;
183
+ #value = {};
52
184
  #stream;
53
185
  #closed = false;
54
- /** Configs come from `store.kv.config`, which waits for the first state. */
55
- constructor(link, name, defaults, options) {
186
+ /** Configs come from `store.kv.config`, which lays their layers and waits for the first state. */
187
+ constructor(link, name, defaults) {
56
188
  checkName(name, 'config');
57
189
  this.#link = link;
58
190
  this.name = name;
59
191
  this.#open = KvBucket.encode({ name, config: true });
60
- this.#leaves = new Map(leavesOf(defaults));
61
- this.#schema = options.schema;
62
- this.#secret = new Set(options.secret ?? []);
63
- for (const path of this.#secret) {
64
- this.#leaf(path);
65
- }
66
- this.#from = new Map([...this.#leaves.keys()].map(path => [path, 'default']));
67
- this.#base = layered(this.#leaves, defaults, options, this.#from);
68
- this.#value = deepFreeze(structuredClone(this.#base));
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']));
69
195
  }
70
196
  /** The config now, frozen: update changes it. */
71
197
  get value() {
72
198
  return this.#value;
73
199
  }
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));
225
+ }
74
226
  /**
75
227
  * Changes the fields change names, at any depth; each one that changed is
76
228
  * checked, kept, and seen by every store watching the config. A change the
77
- * schema refuses, or one of a secret, is InvalidError and keeps nothing.
229
+ * schema refuses, one of a secret, or one leaving a required field empty, is
230
+ * InvalidError and keeps nothing.
78
231
  */
79
232
  async update(change) {
80
233
  const next = merged(structuredClone(this.#value), change);
81
234
  const set = [];
82
- for (const path of this.#leaves.keys()) {
235
+ for (const [path, field] of this.#fields) {
83
236
  const now = JSON.stringify(pathIn(next, path));
84
237
  if (now === JSON.stringify(pathIn(this.#value, path))) {
85
238
  continue;
86
239
  }
87
- if (this.#secret.has(path)) {
88
- throw new InvalidError(`config ${this.name}: ${path} is a secret, set by the defaults, the file or the environment alone`);
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`);
89
245
  }
90
246
  set.push(path, now);
91
247
  }
@@ -98,7 +254,7 @@ export class Config {
98
254
  /** Forgets what update kept for paths, each a field or a group of them; all of it without paths. */
99
255
  async reset(...paths) {
100
256
  for (const path of paths) {
101
- if (![...this.#leaves.keys()].some(leaf => under(leaf, path))) {
257
+ if (![...this.#fields.keys()].some(leaf => under(leaf, path))) {
102
258
  throw new InvalidError(`config ${this.name} has no field ${path}`);
103
259
  }
104
260
  }
@@ -115,13 +271,11 @@ export class Config {
115
271
  }
116
272
  /** Where each field's value came from, and why a kept value is left out. */
117
273
  sources() {
118
- return [...this.#leaves.keys()].map(path => {
274
+ return [...this.#fields].map(([path, field]) => {
119
275
  const kept = this.#kept.has(path) && !this.#ignored.has(path);
120
276
  const source = {
121
277
  path,
122
- value: this.#secret.has(path)
123
- ? '***'
124
- : (JSON.stringify(pathIn(this.#value, path)) ?? 'null'),
278
+ value: field.secret ? '***' : (JSON.stringify(pathIn(this.#value, path)) ?? 'null'),
125
279
  from: kept ? 'kept' : (this.#from.get(path) ?? 'default'),
126
280
  };
127
281
  const ignored = this.#ignored.get(path);
@@ -139,6 +293,41 @@ export class Config {
139
293
  this.#closed = true;
140
294
  this.#stream?.cancel();
141
295
  }
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');
307
+ }
308
+ }
309
+ async #layEnvironment(layer) {
310
+ const variables = {};
311
+ for (const file of layer.files) {
312
+ Object.assign(variables, await readDotenv(file));
313
+ }
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}`);
321
+ }
322
+ }
323
+ this.#prefix = layer.prefix;
324
+ }
325
+ #requiredText(path, field) {
326
+ if (this.#prefix === undefined) {
327
+ return `${path} is required`;
328
+ }
329
+ return `${path} is required: set ${field.variable ?? envName(this.#prefix, path)}`;
330
+ }
142
331
  async #follow(ready, failed) {
143
332
  let first = true;
144
333
  for (let pause = 100; !this.#closed; pause = Math.min(pause * 2, 5000)) {
@@ -206,7 +395,7 @@ export class Config {
206
395
  /** Makes the config from its base and what is kept, leaving out what no longer fits, and tells the watchers. */
207
396
  async #build(kept) {
208
397
  const ignored = new Map();
209
- let next = withKept(this.#base, this.#leaves, kept, ignored);
398
+ let next = withKept(this.#base, this.#fields, kept, ignored);
210
399
  let issues = await this.#issues(next);
211
400
  if (issues !== undefined && kept.size > ignored.size) {
212
401
  for (const path of kept.keys()) {
@@ -235,56 +424,76 @@ export class Config {
235
424
  }
236
425
  }
237
426
  async #issues(value) {
238
- if (this.#schema === undefined) {
239
- return undefined;
240
- }
241
- const checked = await check(this.#schema, value);
242
- return 'issues' in checked ? checked.issues : undefined;
243
- }
244
- #leaf(path) {
245
- if (!this.#leaves.has(path)) {
246
- throw new InvalidError(`config ${this.name} has no field ${path}`);
427
+ for (const schema of this.#schemas) {
428
+ const checked = await check(schema, value);
429
+ if ('issues' in checked) {
430
+ return checked.issues;
431
+ }
247
432
  }
248
- return this.#leaves.get(path);
433
+ return undefined;
249
434
  }
250
435
  }
251
- /** The defaults, the file and the environment, each over the one before. */
252
- function layered(leaves, defaults, options, from) {
253
- const base = structuredClone(defaults);
254
- if (options.file !== undefined) {
255
- for (const [path, value] of leavesOf(options.file)) {
256
- const wanted = leaves.get(path);
257
- if (!leaves.has(path)) {
258
- continue;
259
- }
260
- if (!fits(value, wanted)) {
261
- throw new InvalidError(`the file's ${path}: ${JSON.stringify(value)} is no ${kindOf(wanted)}`);
436
+ function fieldOf(leaf) {
437
+ if (!(leaf instanceof Setting)) {
438
+ return { sample: leaf, secret: false, required: false, variable: undefined };
439
+ }
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;
262
454
  }
263
- setPath(base, path, value);
264
- from.set(path, 'file');
455
+ }
456
+ else {
457
+ values[key] = plain(inner) ? valuesOf(inner) : structuredClone(inner);
265
458
  }
266
459
  }
267
- if (options.env === false) {
268
- return base;
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');
269
470
  }
270
- for (const [path, wanted] of leaves) {
271
- const name = options.env?.[path] ?? envName(options.prefix ?? '', path);
272
- const text = process.env[name];
273
- if (text !== undefined) {
274
- setPath(base, path, fromEnv(text, wanted, name));
275
- from.set(path, `env ${name}`);
471
+ catch (err) {
472
+ if (err.code === 'ENOENT') {
473
+ return {};
276
474
  }
475
+ throw err;
476
+ }
477
+ try {
478
+ return parseDotenv(text);
479
+ }
480
+ catch (err) {
481
+ throw new InvalidError(`${path}: ${err.message}`);
277
482
  }
278
- return base;
279
483
  }
280
- /** The base with each kept value that fits its field over it. */
281
- function withKept(base, leaves, kept, ignored) {
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) {
282
486
  const next = structuredClone(base);
283
487
  for (const [path, spelled] of kept) {
284
- if (!leaves.has(path)) {
488
+ const field = fields.get(path);
489
+ if (field === undefined) {
285
490
  ignored.set(path, 'the config has no such field');
286
491
  continue;
287
492
  }
493
+ if (field.secret) {
494
+ ignored.set(path, 'the field is a secret');
495
+ continue;
496
+ }
288
497
  let value;
289
498
  try {
290
499
  value = JSON.parse(spelled);
@@ -293,8 +502,12 @@ function withKept(base, leaves, kept, ignored) {
293
502
  ignored.set(path, `${spelled} is no JSON`);
294
503
  continue;
295
504
  }
296
- if (!fits(value, leaves.get(path))) {
297
- ignored.set(path, `${spelled} is no ${kindOf(leaves.get(path))}`);
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');
298
511
  continue;
299
512
  }
300
513
  setPath(next, path, value);
@@ -307,7 +520,7 @@ function withKept(base, leaves, kept, ignored) {
307
520
  *
308
521
  * 8080 ← '3000' → 3000, ['x'] ← 'a.com, b.com' → ['a.com', 'b.com']
309
522
  */
310
- function fromEnv(text, wanted, name) {
523
+ function readVariable(text, wanted, name) {
311
524
  const trimmed = text.trim();
312
525
  if (typeof wanted === 'string') {
313
526
  return text;
@@ -330,7 +543,9 @@ function fromEnv(text, wanted, name) {
330
543
  }
331
544
  if (Array.isArray(wanted) && !trimmed.startsWith('[')) {
332
545
  const item = wanted[0] ?? '';
333
- return trimmed === '' ? [] : trimmed.split(',').map(part => fromEnv(part.trim(), item, name));
546
+ return trimmed === ''
547
+ ? []
548
+ : trimmed.split(',').map(part => readVariable(part.trim(), item, name));
334
549
  }
335
550
  try {
336
551
  const value = JSON.parse(trimmed);
@@ -358,7 +573,13 @@ function leavesOf(value, parent = '') {
358
573
  return leaves;
359
574
  }
360
575
  function plain(value) {
361
- return (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date));
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));
362
583
  }
363
584
  /** A value fits a field when it is of its default's kind; a default of null takes anything. */
364
585
  function fits(value, wanted) {
package/dist/console.d.ts CHANGED
@@ -1,5 +1,14 @@
1
1
  /** How a logger writes its lines as they are logged; without one, pretty on a terminal and JSON otherwise. */
2
2
  export type ConsoleFormat = 'pretty' | 'json' | 'off';
3
+ /** How a pretty line shows its time: `11:02:11.123`, `2026-10-02 11:02:11.123 +03:00` or none. */
4
+ export type ConsoleTime = 'clock' | 'full' | 'off';
5
+ export interface Look {
6
+ color: boolean;
7
+ /** a test's, whose lines do not depend on the machine's zone */
8
+ utc?: boolean;
9
+ time?: ConsoleTime | undefined;
10
+ hideStream?: boolean | undefined;
11
+ }
3
12
  /** A line as a console writes it and the store keeps it: its fields already JSON. */
4
13
  export interface ConsoleLine {
5
14
  at: Date;
@@ -30,7 +39,7 @@ export declare function jsonLine(line: ConsoleLine): string;
30
39
  * traceback, follows the line, indented. A key or a string shows without its
31
40
  * quotes when it is one word with no '=', quote or backslash.
32
41
  */
33
- export declare function prettyLine(line: ConsoleLine, color: boolean, utc?: boolean): string;
42
+ export declare function prettyLine(line: ConsoleLine, look: Look): string;
34
43
  /** A level as slog spells it: INFO, WARN+2, DEBUG-4. */
35
44
  export declare function levelLabel(level: number): string;
36
45
  /**