@tinyshed/tinystore 0.5.0 → 0.6.0

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.
@@ -106,6 +106,11 @@ export const methods = {
106
106
  * nothing written and lets go of what came.
107
107
  */
108
108
  'metrics.uploadPrometheus': 0x0610,
109
+ /**
110
+ * A gauge's range replaced in one write: a read sees it as it was or as it
111
+ * is, never half; the same samples sent again write nothing.
112
+ */
113
+ 'metrics.replace': 0x0611,
109
114
  'records.open': 0x0501,
110
115
  'records.append': 0x0502,
111
116
  'records.list': 0x0503,
@@ -119,6 +124,7 @@ export const methods = {
119
124
  'records.lines': 0x050b,
120
125
  'records.damaged': 0x050c,
121
126
  'records.drop': 0x050d,
127
+ 'records.fields': 0x050e,
122
128
  'search.open': 0x0b01,
123
129
  'search.set': 0x0b02,
124
130
  'search.setMany': 0x0b03,
@@ -6372,6 +6378,60 @@ export const MetricsIngest = message('metrics.Ingest', {
6372
6378
  return { series: $series };
6373
6379
  },
6374
6380
  });
6381
+ /**
6382
+ * A gauge's samples of from to to, packed or not, replaced by the series'
6383
+ * own: a time given takes its value, a time not there before is added, and a
6384
+ * time the series does not give goes.
6385
+ */
6386
+ export const MetricsReplace = message('metrics.Replace', {
6387
+ series: [1, MetricsNewSeries],
6388
+ from: [2, int],
6389
+ /** excluded */
6390
+ to: [3, int],
6391
+ }, {
6392
+ write(w, v) {
6393
+ const head = w.openMap();
6394
+ let n = 0;
6395
+ if (v.series !== undefined) {
6396
+ w.field(1);
6397
+ MetricsNewSeries.write(w, v.series);
6398
+ n++;
6399
+ }
6400
+ if (v.from !== undefined) {
6401
+ w.field(2);
6402
+ w.int(v.from);
6403
+ n++;
6404
+ }
6405
+ if (v.to !== undefined) {
6406
+ w.field(3);
6407
+ w.int(v.to);
6408
+ n++;
6409
+ }
6410
+ w.closeMap(head, n);
6411
+ },
6412
+ read(r) {
6413
+ let $series;
6414
+ let $from;
6415
+ let $to;
6416
+ for (let n = r.message(); n > 0; n--) {
6417
+ switch (r.field()) {
6418
+ case 1:
6419
+ $series = MetricsNewSeries.read(r);
6420
+ break;
6421
+ case 2:
6422
+ $from = r.int();
6423
+ break;
6424
+ case 3:
6425
+ $to = r.int();
6426
+ break;
6427
+ default:
6428
+ r.skip();
6429
+ }
6430
+ }
6431
+ r.leave();
6432
+ return { series: $series, from: $from, to: $to };
6433
+ },
6434
+ });
6375
6435
  /**
6376
6436
  * A text an exporter serves, in Prometheus' format or OpenMetrics', whose
6377
6437
  * series the store writes every one or none, each with labels beside its own.
@@ -7609,13 +7669,19 @@ export const MetricsAck = message('metrics.Ack', {
7609
7669
  },
7610
7670
  });
7611
7671
  /**
7612
- * Opens a stream of events by name, made with its first event.
7672
+ * Opens a stream of events by name, made with its first event. Opened
7673
+ * through a database, the stream is records.db's all the same, and its
7674
+ * appends inside the database's transactions and batches are kept in the
7675
+ * database's file until they commit, then written to the stream before the
7676
+ * transaction or the batch answers.
7613
7677
  */
7614
7678
  export const RecordsOpen = message('records.Open', {
7615
7679
  /** [a-z0-9][a-z0-9_-]{0,63} */
7616
7680
  stream: [1, str],
7617
7681
  /** how long it keeps its events: its own, kept in the file */
7618
7682
  keep: [2, uint],
7683
+ /** a database's handle: its appends join its transactions and batches; none when absent */
7684
+ database: [3, uint],
7619
7685
  }, {
7620
7686
  write(w, v) {
7621
7687
  const head = w.openMap();
@@ -7630,11 +7696,17 @@ export const RecordsOpen = message('records.Open', {
7630
7696
  w.uint(v.keep);
7631
7697
  n++;
7632
7698
  }
7699
+ if (v.database !== undefined) {
7700
+ w.field(3);
7701
+ w.uint(v.database);
7702
+ n++;
7703
+ }
7633
7704
  w.closeMap(head, n);
7634
7705
  },
7635
7706
  read(r) {
7636
7707
  let $stream;
7637
7708
  let $keep;
7709
+ let $database;
7638
7710
  for (let n = r.message(); n > 0; n--) {
7639
7711
  switch (r.field()) {
7640
7712
  case 1:
@@ -7643,12 +7715,15 @@ export const RecordsOpen = message('records.Open', {
7643
7715
  case 2:
7644
7716
  $keep = r.uint();
7645
7717
  break;
7718
+ case 3:
7719
+ $database = r.uint();
7720
+ break;
7646
7721
  default:
7647
7722
  r.skip();
7648
7723
  }
7649
7724
  }
7650
7725
  r.leave();
7651
- return { stream: $stream, keep: $keep };
7726
+ return { stream: $stream, keep: $keep, database: $database };
7652
7727
  },
7653
7728
  });
7654
7729
  /**
@@ -8778,6 +8853,213 @@ export const RecordsStreams = message('records.Streams', {
8778
8853
  return { streams: $streams };
8779
8854
  },
8780
8855
  });
8856
+ /**
8857
+ * What the events of a stream carry, counted as they are packed and from
8858
+ * what waits, none of it read from a packed event.
8859
+ */
8860
+ export const RecordsFieldsAsked = message('records.FieldsAsked', {
8861
+ stream: [1, str],
8862
+ }, {
8863
+ write(w, v) {
8864
+ const head = w.openMap();
8865
+ let n = 0;
8866
+ if (v.stream !== undefined) {
8867
+ w.field(1);
8868
+ w.str(v.stream);
8869
+ n++;
8870
+ }
8871
+ w.closeMap(head, n);
8872
+ },
8873
+ read(r) {
8874
+ let $stream;
8875
+ for (let n = r.message(); n > 0; n--) {
8876
+ switch (r.field()) {
8877
+ case 1:
8878
+ $stream = r.str();
8879
+ break;
8880
+ default:
8881
+ r.skip();
8882
+ }
8883
+ }
8884
+ r.leave();
8885
+ return { stream: $stream };
8886
+ },
8887
+ });
8888
+ export const RecordsNameCount = message('records.NameCount', {
8889
+ name: [1, str],
8890
+ count: [2, uint],
8891
+ }, {
8892
+ write(w, v) {
8893
+ const head = w.openMap();
8894
+ let n = 0;
8895
+ if (v.name !== undefined) {
8896
+ w.field(1);
8897
+ w.str(v.name);
8898
+ n++;
8899
+ }
8900
+ if (v.count !== undefined) {
8901
+ w.field(2);
8902
+ w.uint(v.count);
8903
+ n++;
8904
+ }
8905
+ w.closeMap(head, n);
8906
+ },
8907
+ read(r) {
8908
+ let $name;
8909
+ let $count;
8910
+ for (let n = r.message(); n > 0; n--) {
8911
+ switch (r.field()) {
8912
+ case 1:
8913
+ $name = r.str();
8914
+ break;
8915
+ case 2:
8916
+ $count = r.uint();
8917
+ break;
8918
+ default:
8919
+ r.skip();
8920
+ }
8921
+ }
8922
+ r.leave();
8923
+ return { name: $name, count: $count };
8924
+ },
8925
+ });
8926
+ /**
8927
+ * A key of a stream's events' fields or contexts.
8928
+ */
8929
+ export const RecordsFieldInfo = message('records.FieldInfo', {
8930
+ name: [1, str],
8931
+ /** float, integer, text, bool, object, list or null, in that order */
8932
+ kinds: [2, list(str)],
8933
+ /** the events that carry it */
8934
+ count: [3, uint],
8935
+ }, {
8936
+ write(w, v) {
8937
+ const head = w.openMap();
8938
+ let n = 0;
8939
+ if (v.name !== undefined) {
8940
+ w.field(1);
8941
+ w.str(v.name);
8942
+ n++;
8943
+ }
8944
+ if (v.kinds !== undefined) {
8945
+ w.field(2);
8946
+ w.array(v.kinds.length);
8947
+ for (const item0 of v.kinds) {
8948
+ w.str(item0);
8949
+ }
8950
+ n++;
8951
+ }
8952
+ if (v.count !== undefined) {
8953
+ w.field(3);
8954
+ w.uint(v.count);
8955
+ n++;
8956
+ }
8957
+ w.closeMap(head, n);
8958
+ },
8959
+ read(r) {
8960
+ let $name;
8961
+ let $kinds;
8962
+ let $count;
8963
+ for (let n = r.message(); n > 0; n--) {
8964
+ switch (r.field()) {
8965
+ case 1:
8966
+ $name = r.str();
8967
+ break;
8968
+ case 2: {
8969
+ const items0 = [];
8970
+ for (let i0 = r.array(); i0 > 0; i0--) {
8971
+ items0.push(r.str());
8972
+ }
8973
+ r.leave();
8974
+ $kinds = items0;
8975
+ break;
8976
+ }
8977
+ case 3:
8978
+ $count = r.uint();
8979
+ break;
8980
+ default:
8981
+ r.skip();
8982
+ }
8983
+ }
8984
+ r.leave();
8985
+ return { name: $name, kinds: $kinds, count: $count };
8986
+ },
8987
+ });
8988
+ export const RecordsStreamFields = message('records.StreamFields', {
8989
+ eventNames: [1, list(RecordsNameCount)],
8990
+ fields: [2, list(RecordsFieldInfo)],
8991
+ context: [3, list(RecordsFieldInfo)],
8992
+ }, {
8993
+ write(w, v) {
8994
+ const head = w.openMap();
8995
+ let n = 0;
8996
+ if (v.eventNames !== undefined) {
8997
+ w.field(1);
8998
+ w.array(v.eventNames.length);
8999
+ for (const item0 of v.eventNames) {
9000
+ RecordsNameCount.write(w, item0);
9001
+ }
9002
+ n++;
9003
+ }
9004
+ if (v.fields !== undefined) {
9005
+ w.field(2);
9006
+ w.array(v.fields.length);
9007
+ for (const item0 of v.fields) {
9008
+ RecordsFieldInfo.write(w, item0);
9009
+ }
9010
+ n++;
9011
+ }
9012
+ if (v.context !== undefined) {
9013
+ w.field(3);
9014
+ w.array(v.context.length);
9015
+ for (const item0 of v.context) {
9016
+ RecordsFieldInfo.write(w, item0);
9017
+ }
9018
+ n++;
9019
+ }
9020
+ w.closeMap(head, n);
9021
+ },
9022
+ read(r) {
9023
+ let $eventNames;
9024
+ let $fields;
9025
+ let $context;
9026
+ for (let n = r.message(); n > 0; n--) {
9027
+ switch (r.field()) {
9028
+ case 1: {
9029
+ const items0 = [];
9030
+ for (let i0 = r.array(); i0 > 0; i0--) {
9031
+ items0.push(RecordsNameCount.read(r));
9032
+ }
9033
+ r.leave();
9034
+ $eventNames = items0;
9035
+ break;
9036
+ }
9037
+ case 2: {
9038
+ const items0 = [];
9039
+ for (let i0 = r.array(); i0 > 0; i0--) {
9040
+ items0.push(RecordsFieldInfo.read(r));
9041
+ }
9042
+ r.leave();
9043
+ $fields = items0;
9044
+ break;
9045
+ }
9046
+ case 3: {
9047
+ const items0 = [];
9048
+ for (let i0 = r.array(); i0 > 0; i0--) {
9049
+ items0.push(RecordsFieldInfo.read(r));
9050
+ }
9051
+ r.leave();
9052
+ $context = items0;
9053
+ break;
9054
+ }
9055
+ default:
9056
+ r.skip();
9057
+ }
9058
+ }
9059
+ r.leave();
9060
+ return { eventNames: $eventNames, fields: $fields, context: $context };
9061
+ },
9062
+ });
8781
9063
  /**
8782
9064
  * The keys the events a query finds hold, sorted.
8783
9065
  */
@@ -10107,13 +10389,15 @@ export const SqlOpen = message('sql.Open', {
10107
10389
  });
10108
10390
  /**
10109
10391
  * A statement's text and the values of its ?s, in order. In a batch it may
10110
- * be a call of jobs on a queue kept in the database's file instead, jobs.add
10111
- * with its request in body and no text, which commits with the batch's rows.
10392
+ * be a call of another engine instead, with its request in body and no
10393
+ * text, which commits with the batch's rows: jobs.add on a queue kept in the
10394
+ * database's file, or records.append on a stream opened through the
10395
+ * database, whose events reach the stream before the batch answers.
10112
10396
  */
10113
10397
  export const SqlText = message('sql.Text', {
10114
10398
  text: [1, str],
10115
10399
  values: [2, list(sqlValue)],
10116
- /** in a batch, jobs.add: the call in body */
10400
+ /** in a batch, jobs.add or records.append: the call in body */
10117
10401
  method: [3, uint],
10118
10402
  body: [4, bin],
10119
10403
  }, {
@@ -10574,7 +10858,8 @@ export const SqlDone = message('sql.Done', {
10574
10858
  });
10575
10859
  /**
10576
10860
  * Writes known before they run, written as one in a shared commit: its
10577
- * statements, and the adds of a queue kept in the database's file.
10861
+ * statements, the adds of a queue kept in the database's file, and the
10862
+ * appends of a stream opened through the database.
10578
10863
  */
10579
10864
  export const SqlBatch = message('sql.Batch', {
10580
10865
  handle: [1, uint],
@@ -10625,7 +10910,8 @@ export const SqlBatch = message('sql.Batch', {
10625
10910
  });
10626
10911
  /**
10627
10912
  * What each write of a batch did, in their order: a job's add changed one
10628
- * job, or none when its id was taken.
10913
+ * job, or none when its id was taken, and a stream's append the events its
10914
+ * stream holds no id of.
10629
10915
  */
10630
10916
  export const SqlBatched = message('sql.Batched', {
10631
10917
  done: [1, list(SqlDone)],
@@ -10700,7 +10986,9 @@ export const SqlTxOpen = message('sql.TxOpen', {
10700
10986
  * A transaction's call, or its end: the last DATA commits, or not. A call is
10701
10987
  * a statement, or a call of kv or jobs on a bucket or a queue kept in the
10702
10988
  * database's file: a method of theirs with its request, kv.set or jobs.add,
10703
- * which runs in the transaction.
10989
+ * which runs in the transaction; or records.append on a stream opened
10990
+ * through the database, whose events reach the stream once the transaction
10991
+ * commits, before its last DATA answers.
10704
10992
  */
10705
10993
  export const SqlTxCall = message('sql.TxCall', {
10706
10994
  text: [1, str],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "TinyStore for Bun and Node: kv, jobs, blobs, SQL, records and metrics in one directory, served by a sidecar",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://tinyshed.org/tinystore",
@@ -31,12 +31,12 @@
31
31
  "README.md"
32
32
  ],
33
33
  "optionalDependencies": {
34
- "@tinyshed/tinystore-linux-x64": "0.5.0",
35
- "@tinyshed/tinystore-linux-arm64": "0.5.0",
36
- "@tinyshed/tinystore-linux-x64-musl": "0.5.0",
37
- "@tinyshed/tinystore-linux-arm64-musl": "0.5.0",
38
- "@tinyshed/tinystore-darwin-arm64": "0.5.0",
39
- "@tinyshed/tinystore-darwin-x64": "0.5.0",
40
- "@tinyshed/tinystore-win32-x64": "0.5.0"
34
+ "@tinyshed/tinystore-linux-x64": "0.6.0",
35
+ "@tinyshed/tinystore-linux-arm64": "0.6.0",
36
+ "@tinyshed/tinystore-linux-x64-musl": "0.6.0",
37
+ "@tinyshed/tinystore-linux-arm64-musl": "0.6.0",
38
+ "@tinyshed/tinystore-darwin-arm64": "0.6.0",
39
+ "@tinyshed/tinystore-darwin-x64": "0.6.0",
40
+ "@tinyshed/tinystore-win32-x64": "0.6.0"
41
41
  }
42
42
  }
package/src/config.ts CHANGED
@@ -36,7 +36,7 @@ const layerMark = '~layer'
36
36
  const attempts = 8
37
37
 
38
38
  // The declaration as the core reads it: docs/guides/config/README.md, and
39
- // crates/tinystore/src/kv/config/data.rs, which reads this JSON.
39
+ // crates/tinystore/src/config/data.rs, which reads this JSON.
40
40
  type Kind =
41
41
  | 'text'
42
42
  | 'integer'
@@ -62,6 +62,12 @@ interface Described extends Rules {
62
62
  required?: boolean
63
63
  live?: boolean
64
64
  secret?: boolean
65
+ /** of a map of entries, each entry's group; its kind is 'object', as an older release reads it */
66
+ entries?: Group
67
+ /** of a chosen group, the key of the setting beside it whose value names its group */
68
+ chosenBy?: string
69
+ /** of a chosen group, each group by the name its chooser gives it; its kind is 'object' too */
70
+ groups?: Record<string, Group>
65
71
  }
66
72
 
67
73
  /**
@@ -84,6 +90,25 @@ export interface Setting<
84
90
  readonly '~secret'?: IsSecret
85
91
  }
86
92
 
93
+ /**
94
+ * A map of named entries, as `entries` declares one: each entry the group
95
+ * `G`, read as its settings are.
96
+ */
97
+ export interface Entries<G> extends Setting<Readonly<Record<string, Value<G>>>> {
98
+ /** what an object in code gives each entry; nothing at run time */
99
+ readonly '~entries': G
100
+ }
101
+
102
+ /**
103
+ * A group whose settings are those of one of `G`, the one a text setting
104
+ * beside it names, as `chosenBy` declares one: each of `G`'s groups read as
105
+ * its settings are.
106
+ */
107
+ export interface Chosen<G> extends Setting<Value<G[keyof G]>> {
108
+ /** what an object in code gives the group; nothing at run time */
109
+ readonly '~chosen': G
110
+ }
111
+
87
112
  /** A setting's text that prints as *** wherever it goes; `reveal` gives it. */
88
113
  export class Secret {
89
114
  readonly #text: string
@@ -153,15 +178,19 @@ export type Changes<D> = {
153
178
 
154
179
  /** An object in code over the declaration: any of its settings, at any depth, a secret as text. */
155
180
  export type Overlay<D> = {
156
- readonly [K in keyof D]?: D[K] extends Setting<infer V, boolean, boolean, boolean>
157
- ? V extends Secret
158
- ? string
159
- : V
160
- : D[K] extends readonly unknown[]
161
- ? Value<D[K]>
162
- : D[K] extends object
163
- ? Overlay<D[K]>
164
- : Value<D[K]>
181
+ readonly [K in keyof D]?: D[K] extends Entries<infer G>
182
+ ? Readonly<Record<string, Overlay<G>>>
183
+ : D[K] extends Chosen<infer G>
184
+ ? Overlay<G[keyof G]>
185
+ : D[K] extends Setting<infer V, boolean, boolean, boolean>
186
+ ? V extends Secret
187
+ ? string
188
+ : V
189
+ : D[K] extends readonly unknown[]
190
+ ? Value<D[K]>
191
+ : D[K] extends object
192
+ ? Overlay<D[K]>
193
+ : Value<D[K]>
165
194
  }
166
195
 
167
196
  /** A file a config reads: TOML, YAML or JSON by its extension. */
@@ -299,6 +328,11 @@ export interface DurationBounds {
299
328
  max?: DurationText | undefined
300
329
  }
301
330
 
331
+ /** The entries a map of entries' declaration gives, each as an object in code gives one. */
332
+ export interface EntriesOptions<G> {
333
+ default?: Readonly<Record<string, Overlay<G>>> | undefined
334
+ }
335
+
302
336
  /** A list's default and how many items it holds at least and at most. */
303
337
  export interface ListOptions<V> extends Bounds {
304
338
  default?: readonly V[] | undefined
@@ -361,6 +395,7 @@ export function required(
361
395
  if (inner === undefined) {
362
396
  throw new InvalidError('required takes String, Number, Boolean, or a rule without its default')
363
397
  }
398
+ refuseEntries(inner)
364
399
  if (inner.secret === true) {
365
400
  throw new InvalidError('a secret is required already: secret(String)')
366
401
  }
@@ -385,6 +420,7 @@ export function live(given: unknown): Setting<unknown, true> {
385
420
  throw new InvalidError('a mark goes on a setting, not on a group: mark each of its settings')
386
421
  }
387
422
  const inner = describedOf(given) ?? declaredValue(given, 'live')
423
+ refuseEntries(inner)
388
424
  if (inner.secret === true) {
389
425
  throw new InvalidError('a secret is never live')
390
426
  }
@@ -474,6 +510,7 @@ function itemOf(item: unknown): Item {
474
510
  }
475
511
  const inner = describedOf(item)
476
512
  if (inner !== undefined) {
513
+ refuseEntries(inner)
477
514
  if (inner.live === true || inner.secret === true) {
478
515
  throw new InvalidError("a list's items are neither live nor secret: the list is one setting")
479
516
  }
@@ -486,6 +523,67 @@ function itemOf(item: unknown): Item {
486
523
  throw new InvalidError(`a list of ${String(item)}: of String, Number, Boolean, a rule or a group`)
487
524
  }
488
525
 
526
+ /**
527
+ * A map of named entries, each the group `item` declares, whose fields are
528
+ * settings of their own, with their own marks: a file gives an entry field
529
+ * by field, and `APP_INSTANCE_AIMEE_PASSWORD`, or its `_FILE`, one field of
530
+ * the entry `aimee` that a layer before it made. A map written as a value,
531
+ * `{}`, is one setting, given whole.
532
+ */
533
+ export function entries<G extends object>(item: G, options: EntriesOptions<G> = {}): Entries<G> {
534
+ if (!isPlainObject(item) || describedOf(item) !== undefined || Object.keys(item).length === 0) {
535
+ throw new InvalidError(
536
+ 'an entry is a group of settings: entries({ host: String, password: secret(String) })',
537
+ )
538
+ }
539
+ const described = {
540
+ kind: 'object' as const,
541
+ default: options.default ?? {},
542
+ entries: declaredGroup(item, '*'),
543
+ }
544
+ return setting(described) as unknown as Entries<G>
545
+ }
546
+
547
+ /**
548
+ * A group whose settings are those of one of `groups`, the one the text
549
+ * setting beside it, `by`, names: `settings: chosenBy('plugin', { postgres,
550
+ * stripe })` reads an instance's settings as postgres's when its `plugin` is
551
+ * 'postgres'. Its fields are settings of their own, with their own marks; a
552
+ * field of a group not chosen is refused, and so is a `plugin` that names no
553
+ * group. A layer after the one that chose a group may choose another: then
554
+ * what the layers gave the first is dropped, and explain says so.
555
+ */
556
+ export function chosenBy<const G extends Readonly<Record<string, object>>>(
557
+ by: string,
558
+ groups: G,
559
+ ): Chosen<G> {
560
+ const named = Object.entries(groups)
561
+ if (typeof by !== 'string' || by === '' || !isPlainObject(groups) || named.length === 0) {
562
+ throw new InvalidError(
563
+ "a chosen group: chosenBy('plugin', { postgres: { host: String }, stripe: { key: secret(String) } })",
564
+ )
565
+ }
566
+ const declared: Record<string, Group> = {}
567
+ for (const [name, group] of named) {
568
+ if (!isPlainObject(group) || describedOf(group) !== undefined) {
569
+ throw new InvalidError(`chosenBy: ${name} is a group of settings, not a setting`)
570
+ }
571
+ declared[name] = declaredGroup(group, name)
572
+ }
573
+ const described = { kind: 'object' as const, default: {}, chosenBy: by, groups: declared }
574
+ return setting(described) as unknown as Chosen<G>
575
+ }
576
+
577
+ /** A mark around a map of entries or a chosen group, which marks none of their settings. */
578
+ function refuseEntries(inner: Described): void {
579
+ if (inner.entries !== undefined) {
580
+ throw new InvalidError('entries take no mark: each of their fields carries its own')
581
+ }
582
+ if (inner.groups !== undefined) {
583
+ throw new InvalidError('a chosen group takes no mark: each of its settings carries its own')
584
+ }
585
+ }
586
+
489
587
  /** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
490
588
  export function file(path: string, options: FileOptions = {}): FileLayer {
491
589
  return Object.freeze({ [layerMark]: 'file' as const, path, optional: options.optional === true })
@@ -586,11 +684,23 @@ function plainItem(first: unknown): Item {
586
684
  }
587
685
  }
588
686
 
589
- /** Every setting's path, as the core names its variable. */
687
+ /** Every setting's path, as the core names its variable, every map of entries' and every chosen group's. */
590
688
  function paths(group: Group, path: string): string[] {
591
689
  return Object.entries(group).flatMap(([key, node]) => {
592
690
  const at = path === '' ? key : `${path}.${key}`
593
- return 'group' in node ? paths(node.group, at) : [at]
691
+ if ('group' in node) {
692
+ return paths(node.group, at)
693
+ }
694
+ const chosen = Object.values(node.groups ?? {}).flatMap(inner => paths(inner, at))
695
+ return node.groups === undefined ? [at] : [...new Set(chosen)]
696
+ })
697
+ }
698
+
699
+ /** Every map of entries' path, whose entries' variables begin with its own. */
700
+ function entryMaps(group: Group, path: string): string[] {
701
+ return Object.entries(group).flatMap(([key, node]) => {
702
+ const at = path === '' ? key : `${path}.${key}`
703
+ return 'group' in node ? entryMaps(node.group, at) : node.entries === undefined ? [] : [at]
594
704
  })
595
705
  }
596
706
 
@@ -671,11 +781,15 @@ async function envData(layer: EnvLayer, declared: Group): Promise<object> {
671
781
  const key = (name: string) => (windows ? name.toUpperCase() : name)
672
782
  const named = paths(declared, '').map(path => layer.vars[path] ?? envName(layer.prefix, path))
673
783
  const wanted = new Set(named.flatMap(name => [key(name), key(`${name}_FILE`)]))
674
- const start = key(`${layer.prefix}_`)
784
+ // an entry's field is named by its key, so its map's variable is what it begins with
785
+ const starts = entryMaps(declared, '').map(path => key(`${envName(layer.prefix, path)}_`))
786
+ if (layer.prefix !== '') {
787
+ starts.push(key(`${layer.prefix}_`))
788
+ }
675
789
  const variables: Record<string, string> = {}
676
790
  for (const [name, value] of Object.entries(layer.from ?? process.env)) {
677
791
  const k = key(name)
678
- if (value !== undefined && (wanted.has(k) || (layer.prefix !== '' && k.startsWith(start)))) {
792
+ if (value !== undefined && (wanted.has(k) || starts.some(start => k.startsWith(start)))) {
679
793
  variables[k] = value
680
794
  }
681
795
  }
@@ -711,17 +825,33 @@ function fileVariables(text: string): [string, string][] {
711
825
  return found
712
826
  }
713
827
 
714
- /** A value as the program reads it: a duration spelled, a secret wrapped, all of it frozen. */
828
+ /**
829
+ * A value as the program reads it: a duration spelled, a secret wrapped, a
830
+ * chosen group as the group its chooser names, all of it frozen.
831
+ */
715
832
  function viewed(group: Group, value: unknown): unknown {
716
833
  const source = (isPlainObject(value) ? value : {}) as Record<string, unknown>
717
834
  const out: Record<string, unknown> = {}
718
835
  for (const [key, node] of Object.entries(group)) {
719
- out[key] = 'group' in node ? viewed(node.group, source[key]) : viewedSetting(node, source[key])
836
+ if ('group' in node) {
837
+ out[key] = viewed(node.group, source[key])
838
+ } else if (node.groups !== undefined) {
839
+ const name = source[node.chosenBy ?? '']
840
+ const chosen = typeof name === 'string' ? node.groups[name] : undefined
841
+ out[key] = viewed(chosen ?? {}, source[key])
842
+ } else {
843
+ out[key] = viewedSetting(node, source[key])
844
+ }
720
845
  }
721
846
  return Object.freeze(out)
722
847
  }
723
848
 
724
849
  function viewedSetting(described: Described, value: unknown): unknown {
850
+ const item = described.entries
851
+ if (item !== undefined) {
852
+ const each = Object.entries(isPlainObject(value) ? value : {})
853
+ return Object.freeze(Object.fromEntries(each.map(([key, entry]) => [key, viewed(item, entry)])))
854
+ }
725
855
  if (described.secret === true) {
726
856
  return new Secret(typeof value === 'string' ? value : '')
727
857
  }
@@ -831,7 +961,7 @@ function originOf(sent: SentOrigin): ExplainOrigin {
831
961
  }
832
962
  }
833
963
 
834
- /** The text the core's `from` says: crates/tinystore/src/kv/config/explain.rs, Origin's Display. */
964
+ /** The text the core's `from` says: crates/tinystore/src/config/explain.rs, Origin's Display. */
835
965
  function originText(origin: ExplainOrigin): string {
836
966
  switch (origin.kind) {
837
967
  case 'declaration':