@tinyshed/tinystore 0.6.0 → 0.7.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.
package/dist/config.d.ts CHANGED
@@ -95,6 +95,7 @@ export interface FileLayer {
95
95
  readonly [layerMark]: 'file';
96
96
  readonly path: string;
97
97
  readonly optional: boolean;
98
+ readonly secrets: boolean;
98
99
  }
99
100
  /** The environment a config reads. */
100
101
  export interface EnvLayer {
@@ -110,6 +111,12 @@ export type Layer<D> = FileLayer | EnvLayer | Overlay<D> | false | null | undefi
110
111
  export interface FileOptions {
111
112
  /** a file that may be absent: then it declares nothing, and explain says so */
112
113
  optional?: boolean | undefined;
114
+ /**
115
+ * false refuses a secret the file gives, for a file committed beside the
116
+ * code: its secrets come from the environment, and the error names the
117
+ * variable and its _FILE that give one, never the file
118
+ */
119
+ secrets?: boolean | undefined;
113
120
  }
114
121
  /** Settings' own variables by their paths: `{ port: 'PORT', db: { url: 'DATABASE_URL' } }`. */
115
122
  export interface Vars {
@@ -140,7 +147,7 @@ export interface UpdateOptions {
140
147
  /** A setting's line of explain. */
141
148
  export interface ExplainLine {
142
149
  readonly path: string;
143
- /** as JSON, a duration spelled, a secret as *** */
150
+ /** as JSON, a duration spelled, a secret as ***, unset for none */
144
151
  readonly value: string;
145
152
  /** the layer that gave it: APP_PORT, app.yaml, layer 2, the declaration, a change */
146
153
  readonly from: string;
@@ -156,7 +163,7 @@ export interface ExplainLine {
156
163
  }
157
164
  /** A value a setting was given, and where it came from. */
158
165
  export interface ExplainGiven {
159
- /** as JSON, a duration spelled, a secret as *** */
166
+ /** as JSON, a duration spelled, a secret as ***, unset for none */
160
167
  readonly value: string;
161
168
  readonly from: ExplainOrigin;
162
169
  }
@@ -221,6 +228,13 @@ export declare function secret(given: StringConstructor | string): Setting<Secre
221
228
  /** A setting with no default: a layer must give it, or the config does not open. */
222
229
  export declare function required<T extends Token>(type: T): Setting<Of<T>>;
223
230
  export declare function required<V>(rule: Setting<V, false, false>): Setting<V>;
231
+ /**
232
+ * A setting with no value until a layer gives one: `optional(String)` reads as
233
+ * `string | null`, `optional(secret(String))` as `Secret | null`, and
234
+ * `optional(int({ min: 1 }))` as `number | null`. explain says it is unset.
235
+ */
236
+ export declare function optional<T extends Token>(type: T): Setting<Of<T> | null>;
237
+ export declare function optional<V, S extends boolean>(rule: Setting<V, false, boolean, S>): Setting<V | null, false, true, S>;
224
238
  /**
225
239
  * A setting that may change while the program runs: its change is kept in
226
240
  * the store, goes over every layer until it is reset, and reaches every
@@ -266,7 +280,11 @@ export declare function entries<G extends object>(item: G, options?: EntriesOpti
266
280
  * what the layers gave the first is dropped, and explain says so.
267
281
  */
268
282
  export declare function chosenBy<const G extends Readonly<Record<string, object>>>(by: string, groups: G): Chosen<G>;
269
- /** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
283
+ /**
284
+ * A file a config reads: TOML, YAML or JSON by its extension, a relative path
285
+ * the program's. `file('dashbin.toml', { secrets: false })` refuses a secret it
286
+ * gives.
287
+ */
270
288
  export declare function file(path: string, options?: FileOptions): FileLayer;
271
289
  /**
272
290
  * The environment a config reads: `env('APP')` reads APP_ and each setting's
package/dist/config.js CHANGED
@@ -55,6 +55,10 @@ function layerOf(value) {
55
55
  function kindOf(token) {
56
56
  return token === String ? 'text' : token === Number ? 'number' : 'boolean';
57
57
  }
58
+ /** What `required` and `optional` mark: a type, `String`, or a rule. */
59
+ function ruleOf(given) {
60
+ return typeof given === 'function' ? { kind: kindOf(given) } : describedOf(given);
61
+ }
58
62
  function bounds(rules) {
59
63
  const out = {};
60
64
  if (rules?.min !== undefined) {
@@ -79,7 +83,7 @@ export function secret(given) {
79
83
  return setting({ kind: 'text', secret: true, default: given });
80
84
  }
81
85
  export function required(given) {
82
- const inner = typeof given === 'function' ? { kind: kindOf(given) } : describedOf(given);
86
+ const inner = ruleOf(given);
83
87
  if (inner === undefined) {
84
88
  throw new InvalidError('required takes String, Number, Boolean, or a rule without its default');
85
89
  }
@@ -93,6 +97,18 @@ export function required(given) {
93
97
  const { default: _default, ...rest } = inner;
94
98
  return setting({ ...rest, required: true });
95
99
  }
100
+ export function optional(given) {
101
+ const inner = ruleOf(given);
102
+ if (inner?.live === true) {
103
+ throw new InvalidError('live is the outermost mark: live(optional(…))');
104
+ }
105
+ if (inner === undefined || inner.default !== undefined) {
106
+ throw new InvalidError('optional takes String, Number, Boolean, secret(String) or a rule without its default');
107
+ }
108
+ refuseEntries(inner);
109
+ const { required: _required, ...rest } = inner;
110
+ return setting({ ...rest, default: null });
111
+ }
96
112
  export function live(given) {
97
113
  if (isPlainObject(given) && describedOf(given) === undefined && Object.keys(given).length > 0) {
98
114
  throw new InvalidError('a mark goes on a setting, not on a group: mark each of its settings');
@@ -206,9 +222,18 @@ function refuseEntries(inner) {
206
222
  throw new InvalidError('a chosen group takes no mark: each of its settings carries its own');
207
223
  }
208
224
  }
209
- /** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
225
+ /**
226
+ * A file a config reads: TOML, YAML or JSON by its extension, a relative path
227
+ * the program's. `file('dashbin.toml', { secrets: false })` refuses a secret it
228
+ * gives.
229
+ */
210
230
  export function file(path, options = {}) {
211
- return Object.freeze({ [layerMark]: 'file', path, optional: options.optional === true });
231
+ return Object.freeze({
232
+ [layerMark]: 'file',
233
+ path,
234
+ optional: options.optional === true,
235
+ secrets: options.secrets !== false,
236
+ });
212
237
  }
213
238
  /**
214
239
  * The environment a config reads: `env('APP')` reads APP_ and each setting's
@@ -363,9 +388,10 @@ async function layerData(layer, place, declared) {
363
388
  }
364
389
  const kind = layerOf(layer);
365
390
  if (kind === 'file') {
366
- const { path, optional } = layer;
391
+ const { path, optional, secrets } = layer;
367
392
  const text = await readText(path);
368
- return { file: { name: path, optional, ...(text === undefined ? {} : { text }) } };
393
+ const refused = secrets ? {} : { secrets: false };
394
+ return { file: { name: path, optional, ...refused, ...(text === undefined ? {} : { text }) } };
369
395
  }
370
396
  if (kind === 'env') {
371
397
  return { env: await envData(layer, declared) };
@@ -456,7 +482,8 @@ function viewedSetting(described, value) {
456
482
  return Object.freeze(Object.fromEntries(each.map(([key, entry]) => [key, viewed(item, entry)])));
457
483
  }
458
484
  if (described.secret === true) {
459
- return new Secret(typeof value === 'string' ? value : '');
485
+ // one declared optional is null until a layer gives it
486
+ return value === null ? null : new Secret(typeof value === 'string' ? value : '');
460
487
  }
461
488
  return viewedKind(described.kind, value);
462
489
  }
package/dist/index.d.ts CHANGED
@@ -3,7 +3,7 @@ export type { Body, FileBytes, FileInfo, FileListOptions, FileOptions, FilePage,
3
3
  export { withSignal } from './cancel.ts';
4
4
  export type { Channel, EachOptions, Message as ChannelMessage, Missed, SubscribeOptions, Subscription, TxChannel, } from './channels.ts';
5
5
  export type { Clock } from './clock.ts';
6
- export { type Bounds, type Changes, type Chosen, type Config, type ConfigOptions, chosenBy, type DurationBounds, duration, type Entries, type EntriesOptions, type EnvLayer, type EnvOptions, type Explained, type ExplainGiven, type ExplainLine, type ExplainOrigin, entries, env, type FileLayer, file, int, type Layer, list, live, type Overlay, oneOf, required, Secret, type Setting, secret, type UpdateOptions, type Value, type Vars, } from './config.ts';
6
+ export { type Bounds, type Changes, type Chosen, type Config, type ConfigOptions, chosenBy, type DurationBounds, duration, type Entries, type EntriesOptions, type EnvLayer, type EnvOptions, type Explained, type ExplainGiven, type ExplainLine, type ExplainOrigin, entries, env, type FileLayer, file, int, type Layer, list, live, type Overlay, oneOf, optional, required, Secret, type Setting, secret, type UpdateOptions, type Value, type Vars, } from './config.ts';
7
7
  export type { Durability, SelfMetrics } from './connection.ts';
8
8
  export { type ConsoleFormat, type ConsoleTime, secrets } from './console.ts';
9
9
  export * from './errors.ts';
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  export { withSignal } from './cancel.js';
2
- export { chosenBy, duration, entries, env, file, int, list, live, oneOf, required, Secret, secret, } from './config.js';
2
+ export { chosenBy, duration, entries, env, file, int, list, live, oneOf, optional, required, Secret, secret, } from './config.js';
3
3
  export { secrets } from './console.js';
4
4
  export * from './errors.js';
5
5
  export { colors, logger } from './logger.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyshed/tinystore",
3
- "version": "0.6.0",
3
+ "version": "0.7.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.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"
34
+ "@tinyshed/tinystore-linux-x64": "0.7.0",
35
+ "@tinyshed/tinystore-linux-arm64": "0.7.0",
36
+ "@tinyshed/tinystore-linux-x64-musl": "0.7.0",
37
+ "@tinyshed/tinystore-linux-arm64-musl": "0.7.0",
38
+ "@tinyshed/tinystore-darwin-arm64": "0.7.0",
39
+ "@tinyshed/tinystore-darwin-x64": "0.7.0",
40
+ "@tinyshed/tinystore-win32-x64": "0.7.0"
41
41
  }
42
42
  }
package/src/config.ts CHANGED
@@ -198,6 +198,7 @@ export interface FileLayer {
198
198
  readonly [layerMark]: 'file'
199
199
  readonly path: string
200
200
  readonly optional: boolean
201
+ readonly secrets: boolean
201
202
  }
202
203
 
203
204
  /** The environment a config reads. */
@@ -216,6 +217,12 @@ export type Layer<D> = FileLayer | EnvLayer | Overlay<D> | false | null | undefi
216
217
  export interface FileOptions {
217
218
  /** a file that may be absent: then it declares nothing, and explain says so */
218
219
  optional?: boolean | undefined
220
+ /**
221
+ * false refuses a secret the file gives, for a file committed beside the
222
+ * code: its secrets come from the environment, and the error names the
223
+ * variable and its _FILE that give one, never the file
224
+ */
225
+ secrets?: boolean | undefined
219
226
  }
220
227
 
221
228
  /** Settings' own variables by their paths: `{ port: 'PORT', db: { url: 'DATABASE_URL' } }`. */
@@ -251,7 +258,7 @@ export interface UpdateOptions {
251
258
  /** A setting's line of explain. */
252
259
  export interface ExplainLine {
253
260
  readonly path: string
254
- /** as JSON, a duration spelled, a secret as *** */
261
+ /** as JSON, a duration spelled, a secret as ***, unset for none */
255
262
  readonly value: string
256
263
  /** the layer that gave it: APP_PORT, app.yaml, layer 2, the declaration, a change */
257
264
  readonly from: string
@@ -268,7 +275,7 @@ export interface ExplainLine {
268
275
 
269
276
  /** A value a setting was given, and where it came from. */
270
277
  export interface ExplainGiven {
271
- /** as JSON, a duration spelled, a secret as *** */
278
+ /** as JSON, a duration spelled, a secret as ***, unset for none */
272
279
  readonly value: string
273
280
  readonly from: ExplainOrigin
274
281
  }
@@ -360,6 +367,11 @@ function kindOf(token: Token): Kind {
360
367
  return token === String ? 'text' : token === Number ? 'number' : 'boolean'
361
368
  }
362
369
 
370
+ /** What `required` and `optional` mark: a type, `String`, or a rule. */
371
+ function ruleOf(given: Token | Setting<unknown, boolean, boolean, boolean>): Described | undefined {
372
+ return typeof given === 'function' ? { kind: kindOf(given) } : describedOf(given)
373
+ }
374
+
363
375
  function bounds(rules: Bounds | undefined): Rules {
364
376
  const out: Rules = {}
365
377
  if (rules?.min !== undefined) {
@@ -391,7 +403,7 @@ export function required<V>(rule: Setting<V, false, false>): Setting<V>
391
403
  export function required(
392
404
  given: Token | Setting<unknown, boolean, boolean, boolean>,
393
405
  ): Setting<unknown> {
394
- const inner = typeof given === 'function' ? { kind: kindOf(given) } : describedOf(given)
406
+ const inner = ruleOf(given)
395
407
  if (inner === undefined) {
396
408
  throw new InvalidError('required takes String, Number, Boolean, or a rule without its default')
397
409
  }
@@ -406,6 +418,32 @@ export function required(
406
418
  return setting({ ...rest, required: true })
407
419
  }
408
420
 
421
+ /**
422
+ * A setting with no value until a layer gives one: `optional(String)` reads as
423
+ * `string | null`, `optional(secret(String))` as `Secret | null`, and
424
+ * `optional(int({ min: 1 }))` as `number | null`. explain says it is unset.
425
+ */
426
+ export function optional<T extends Token>(type: T): Setting<Of<T> | null>
427
+ export function optional<V, S extends boolean>(
428
+ rule: Setting<V, false, boolean, S>,
429
+ ): Setting<V | null, false, true, S>
430
+ export function optional(
431
+ given: Token | Setting<unknown, boolean, boolean, boolean>,
432
+ ): Setting<unknown, false, true, boolean> {
433
+ const inner = ruleOf(given)
434
+ if (inner?.live === true) {
435
+ throw new InvalidError('live is the outermost mark: live(optional(…))')
436
+ }
437
+ if (inner === undefined || inner.default !== undefined) {
438
+ throw new InvalidError(
439
+ 'optional takes String, Number, Boolean, secret(String) or a rule without its default',
440
+ )
441
+ }
442
+ refuseEntries(inner)
443
+ const { required: _required, ...rest } = inner
444
+ return setting({ ...rest, default: null })
445
+ }
446
+
409
447
  /**
410
448
  * A setting that may change while the program runs: its change is kept in
411
449
  * the store, goes over every layer until it is reset, and reaches every
@@ -584,9 +622,18 @@ function refuseEntries(inner: Described): void {
584
622
  }
585
623
  }
586
624
 
587
- /** A file a config reads: TOML, YAML or JSON by its extension, a relative path the program's. */
625
+ /**
626
+ * A file a config reads: TOML, YAML or JSON by its extension, a relative path
627
+ * the program's. `file('dashbin.toml', { secrets: false })` refuses a secret it
628
+ * gives.
629
+ */
588
630
  export function file(path: string, options: FileOptions = {}): FileLayer {
589
- return Object.freeze({ [layerMark]: 'file' as const, path, optional: options.optional === true })
631
+ return Object.freeze({
632
+ [layerMark]: 'file' as const,
633
+ path,
634
+ optional: options.optional === true,
635
+ secrets: options.secrets !== false,
636
+ })
590
637
  }
591
638
 
592
639
  /**
@@ -758,9 +805,10 @@ async function layerData(
758
805
  }
759
806
  const kind = layerOf(layer)
760
807
  if (kind === 'file') {
761
- const { path, optional } = layer as FileLayer
808
+ const { path, optional, secrets } = layer as FileLayer
762
809
  const text = await readText(path)
763
- return { file: { name: path, optional, ...(text === undefined ? {} : { text }) } }
810
+ const refused = secrets ? {} : { secrets: false }
811
+ return { file: { name: path, optional, ...refused, ...(text === undefined ? {} : { text }) } }
764
812
  }
765
813
  if (kind === 'env') {
766
814
  return { env: await envData(layer as EnvLayer, declared) }
@@ -853,7 +901,8 @@ function viewedSetting(described: Described, value: unknown): unknown {
853
901
  return Object.freeze(Object.fromEntries(each.map(([key, entry]) => [key, viewed(item, entry)])))
854
902
  }
855
903
  if (described.secret === true) {
856
- return new Secret(typeof value === 'string' ? value : '')
904
+ // one declared optional is null until a layer gives it
905
+ return value === null ? null : new Secret(typeof value === 'string' ? value : '')
857
906
  }
858
907
  return viewedKind(described.kind, value)
859
908
  }
package/src/index.ts CHANGED
@@ -50,6 +50,7 @@ export {
50
50
  live,
51
51
  type Overlay,
52
52
  oneOf,
53
+ optional,
53
54
  required,
54
55
  Secret,
55
56
  type Setting,