@wtf/project-config 2.0.0 → 3.0.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/README.md CHANGED
@@ -6,21 +6,20 @@ One file for the settings of a project's tools: a `wtf` object with a section fo
6
6
  environment's variables over it, checks it by the tool's schema, and writes values back. A repo
7
7
  loads its config itself and hands each section to the tool it is for, as a preset's options.
8
8
 
9
- | Subpath | What you get |
10
- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
11
- | `.` | The types: `NamespaceConfig`, `SectionsOf`, `ResolvedConfig`, `SectionSchema`, `ConfigPlatform`, `ConfigSyncPlatform`, … |
12
- | `./load` | `loadConfig({ platform })`, of code or JSON; `loadConfigSync({ platform })`, of JSON alone; `ignoredWarning` |
13
- | `./node` | `nodeSyncPlatform(platform)`, a platform's files read synchronously by `node:fs`; `nodeLoadModule(root, beside?)` |
14
- | `./section` | `sectionOf(resolved, name, schema?)` and `sectionOfSync`: a tool's section, the environment over it, checked; `issuesOf`, `mergeSection` |
15
- | `./locate` | `locateConfig`, `projectRootOf` and their sync twins; `configFilesOf`, `configNamesOf`, `jsonFilesOf`, `DEFAULT_NAMESPACE` |
16
- | `./env` | `withEnvironment`, `variablesOf`, `envNameOf`, `envPrefixOf`: variables such as `WTF_VITE_COMPRESS` over a value |
17
- | `./placeholder` | `expandPlaceholders` and `expandString`: each `${env:NAME}` replaced by its variable |
18
- | `./path` | `configPathOf('vite.compress')`, `textOfConfigPath`, `valueAt` |
19
- | `./write` | `setConfigValue` and `unsetConfigValue`, in the JSON file or in package.json's key |
20
- | `./schema` | `namespaceSchema('wtf', sections)`: one JSON Schema for the whole file, of each tool's schema |
21
- | `./define` | `defineConfig<S>(config)`: a code config, typed by the sections of the tools |
22
- | `./named` | `resolveNamed`, `resolveNamedSet`, `factoryOf`, `namedSchema`, `namedSetSchema`: a value or a function named in JSON |
23
- | `./errors` | `ConfigError` and every other error, each with a stable `code` |
9
+ | Subpath | What you get |
10
+ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
11
+ | `.` | The types: `NamespaceConfig`, `SectionsOf`, `ResolvedConfig`, `SectionSchema`, `ConfigPlatform`, … |
12
+ | `./load` | `loadConfig({ platform })`, of code or JSON; `ignoredWarning` |
13
+ | `./section` | `sectionOf(resolved, name, schema?)`: a tool's section, the environment over it, checked; `issuesOf`, `issuesOfSync`, `mergeSection` |
14
+ | `./locate` | `locateConfig`, `projectRootOf`; `configFilesOf`, `configNamesOf`, `jsonFilesOf`, `DEFAULT_NAMESPACE` |
15
+ | `./env` | `withEnvironment`, `variablesOf`, `envNameOf`, `envPrefixOf`: variables such as `WTF_VITE_COMPRESS` over a value |
16
+ | `./placeholder` | `expandPlaceholders` and `expandString`: each `${env:NAME}` replaced by its variable |
17
+ | `./path` | `configPathOf('vite.compress')`, `textOfConfigPath`, `valueAt` |
18
+ | `./write` | `setConfigValue` and `unsetConfigValue`, in the JSON file or in package.json's key |
19
+ | `./schema` | `namespaceSchema('wtf', sections)`: one JSON Schema for the whole file, of each tool's schema |
20
+ | `./define` | `defineConfig<S>(config)`: a code config, typed by the sections of the tools |
21
+ | `./named` | `resolveNamed`, `resolveNamedSet`, `factoryOf`, `namedSchema`, `namedSetSchema`: a value or a function named in JSON |
22
+ | `./errors` | `ConfigError` and every other error, each with a stable `code` |
24
23
 
25
24
  ```ts
26
25
  // vite.config.ts
@@ -53,14 +52,6 @@ A JSON file holds plain data. A code config exports its object by default, or a
53
52
  returns one, and may hold what JSON cannot, as a function, where a tool's options take one. Node
54
53
  imports it, `wtf.config.ts` too, as it strips the types itself.
55
54
 
56
- ## Asynchronous and synchronous
57
-
58
- `loadConfig` reads every kind of file, as importing code is asynchronous. `loadConfigSync` is for a
59
- tool that loads its own config synchronously: it reads `wtf.config.json` and package.json's key, of
60
- a platform whose files are read synchronously, as `nodeSyncPlatform(platform)` of `./node` gives,
61
- and throws a `SyncConfigInCodeError` when the config in use is code. `sectionOfSync` checks a
62
- section synchronously, and throws a `SyncSchemaError` of a schema that answers with a promise.
63
-
64
55
  ## The environment over it
65
56
 
66
57
  The loads keep the environment of the platform, its `env`. A variable `WTF_<SECTION>_<KEY>` sets a value of a
@@ -96,8 +87,8 @@ over it. Sets merge in order, a later one over an earlier one by name, and a set
96
87
  export of a module that is one, or an array of those:
97
88
 
98
89
  ```ts
99
- import { nodeLoadModule } from '@wtf/project-config/node'
100
90
  import {
91
+ type LoadModule,
101
92
  type NamedReference,
102
93
  type NamedSet,
103
94
  resolveNamed,
@@ -107,11 +98,12 @@ import {
107
98
  type Format = { readonly width: number; readonly ellipsis: string }
108
99
  declare const configured: { formatters?: NamedSet<Format>[]; format: NamedReference }
109
100
 
110
- declare const root: string
101
+ // In Node: nodeLoadModule(root, import.meta.url) of @wtf/platform-node/module.
102
+ declare const load: LoadModule
111
103
 
112
104
  const builtin = { short: { width: 40, ellipsis: '…' } }
113
105
  const formatters = await resolveNamedSet<Format>([builtin, ...(configured.formatters ?? [])], {
114
- load: nodeLoadModule(root, import.meta.url)
106
+ load
115
107
  })
116
108
  const format = await resolveNamed<Format>(configured.format, {
117
109
  key: 'format',
@@ -125,9 +117,10 @@ module that fails to load, `UNLOADABLE_MODULE`; an export it has not, `MISSING_E
125
117
  of the wrong shape, or one the `check` you pass refuses, `INVALID_NAMED_VALUE`. Each names where
126
118
  it failed: its `at` path, from the `at` you pass, the index of the `set` and the name of the
127
119
  `entry`, and the `module` and `export` a value came from. With `checkResults: true`, `check` also
128
- checks what each function entry gives. `nodeLoadModule`
129
- loads a path from the root you give it, and a package the root installs, else one installed beside
130
- your tool.
120
+ checks what each function entry gives. You pass the loader of the modules, `load`, a function
121
+ from a name to the module's exports. Node's is `nodeLoadModule(root, beside)` of
122
+ `@wtf/platform-node/module`: it loads a path from the root you give it, and a package the root
123
+ installs, else one installed beside your tool.
131
124
  `namedSchema('format', { names, options })` and `namedSetSchema({ entry })` give the schema of a
132
125
  reference and of the sets, so an editor completes the names.
133
126
 
@@ -136,7 +129,6 @@ reference and of the sets, so an editor completes the names.
136
129
  `./load`, `./locate` and `./write` read through the platform you pass: a `Platform` of
137
130
  [`@wtf/platform`](https://www.npmjs.com/package/@wtf/platform), whose `navigator.storage` gives
138
131
  the root of a WHATWG File System, as a browser's or `@wtf/platform-fs-memory`'s, or
139
- `nodeStorage()` of `@wtf/platform-fs-node` for Node's disk. The sync load takes a platform whose
140
- files are read synchronously, which `nodeSyncPlatform` of `./node` makes of Node's.
132
+ `nodeStorage()` of `@wtf/platform-fs-node` for Node's disk.
141
133
 
142
134
  See the [configuration guide](../project-docs/guides/config.md).
package/dist/errors.d.ts CHANGED
@@ -8,10 +8,9 @@
8
8
  * {@link UnwritableConfigFileError}, a write to a file that is never written;
9
9
  * {@link NoConfigValueError}, a value asked for that is not set; and
10
10
  * {@link EnvPlaceholderUnsetError}, a value that points at a variable of the environment that is
11
- * not set; {@link SyncConfigInCodeError}, a configuration of code loaded synchronously; and
12
- * {@link SyncSchemaError}, a section checked synchronously by a schema that checks asynchronously;
13
- * and {@link NamedError}, a reference of ./named that names no entry, or a module, an export or a
14
- * value that is not what it says. One that the arguments of a person cause exits 2.
11
+ * not set; {@link SyncSchemaError}, a value checked synchronously by a schema that checks
12
+ * asynchronously; and {@link NamedError}, a reference of ./named that names no entry, or a module,
13
+ * an export or a value that is not what it says. One that the arguments of a person cause exits 2.
15
14
  *
16
15
  * @packageDocumentation
17
16
  */
@@ -128,20 +127,7 @@ export declare class EnvPlaceholderUnsetError extends ConfigError {
128
127
  constructor(path: ConfigPath, variable: string);
129
128
  }
130
129
  /**
131
- * A configuration of code, as `wtf.config.ts`, loaded synchronously, as `loadConfigSync` of ./load
132
- * loads it for a tool that reads its config synchronously: code is imported, which is
133
- * asynchronous. Its message names the files a synchronous load reads, JSON and package.json's key.
134
- */
135
- export declare class SyncConfigInCodeError extends ConfigError {
136
- /** The file of code, by its absolute path. */
137
- readonly file: string;
138
- constructor(file: string, read: {
139
- readonly files: readonly string[];
140
- readonly key: string;
141
- });
142
- }
143
- /**
144
- * A section checked synchronously, as `sectionOfSync` of ./section checks it, by a schema that
130
+ * A value checked synchronously, as `issuesOfSync` of ./section checks it, by a schema that
145
131
  * checks asynchronously: a Standard Schema whose `validate` gives a promise, or a function that
146
132
  * does.
147
133
  */
package/dist/errors.js CHANGED
@@ -146,21 +146,7 @@ export class EnvPlaceholderUnsetError extends ConfigError {
146
146
  }
147
147
  }
148
148
  /**
149
- * A configuration of code, as `wtf.config.ts`, loaded synchronously, as `loadConfigSync` of ./load
150
- * loads it for a tool that reads its config synchronously: code is imported, which is
151
- * asynchronous. Its message names the files a synchronous load reads, JSON and package.json's key.
152
- */
153
- export class SyncConfigInCodeError extends ConfigError {
154
- /** The file of code, by its absolute path. */
155
- file;
156
- constructor(file, read) {
157
- const names = [...read.files, `the "${read.key}" key of package.json`];
158
- super('CONFIG_IN_CODE_SYNC', `The configuration is code, in ${file}, which a synchronous load cannot import: write it in ${names.join(' or ')}, or load it with loadConfig.`);
159
- this.file = file;
160
- }
161
- }
162
- /**
163
- * A section checked synchronously, as `sectionOfSync` of ./section checks it, by a schema that
149
+ * A value checked synchronously, as `issuesOfSync` of ./section checks it, by a schema that
164
150
  * checks asynchronously: a Standard Schema whose `validate` gives a promise, or a function that
165
151
  * does.
166
152
  */
@@ -1 +1 @@
1
- {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEtC;wDACwD;AACxD,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAQ;IACrB,kDAAkD;IACzC,QAAQ,GAAW,CAAC,CAAA;IAE7B,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsB;QAC/D,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAA;IAC7B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,WAAW;IACrD,sCAAsC;IAC7B,IAAI,CAAQ;IAErB,YAAY,IAAY,EAAE,MAAc,EAAE,OAAsB;QAC9D,KAAK,CAAC,qBAAqB,EAAE,GAAG,IAAI,KAAK,MAAM,EAAE,EAAE,OAAO,CAAC,CAAA;QAC3D,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IAClD,2DAA2D;IAClD,IAAI,CAAQ;IACrB,gCAAgC;IACvB,OAAO,CAAQ;IACxB,sDAAsD;IAC7C,MAAM,CAAwB;IAEvC,YACE,IAAY,EACZ,SAAiB,EACjB,OAAe,EACf,MAA8B,EAC9B,MAAc,SAAS;QAEvB,KAAK,CACH,wBAAwB,EACxB;YACE,GAAG,IAAI,SAAS,OAAO,mBAAmB,SAAS,8BAA8B;YACjF,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,KAAK,UAAU,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;SAC7F,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,iCAAiC;IACxB,IAAI,CAAQ;IACH,QAAQ,GAAW,CAAC,CAAA;IAEtC,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CAAC,qBAAqB,EAAE,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,EAAE,CAAC,CAAA;QAC5E,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD,8CAA8C;IACrC,IAAI,CAAQ;IAErB,YAAY,IAAY,EAAE,OAAoE;QAC5F,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,OAAO,CAAC,GAAG,uBAAuB,CAAC,CAAA;QAC5E,KAAK,CACH,gBAAgB,EAChB,iCAAiC,IAAI,2BAA2B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,CACpI,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD,+BAA+B;IACtB,IAAI,CAAQ;IACH,QAAQ,GAAW,CAAC,CAAA;IAEtC,YACE,IAAY,EACZ,EACE,SAAS,EACT,GAAG,GAAG,SAAS,EACf,IAAI,EACsF;QAE5F,KAAK,CACH,gBAAgB,EAChB,yBAAyB,IAAI,gBAAgB,SAAS,0BAA0B,GAAG,wBAAwB,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,IAAI,+BAA+B,GAAG,CACzL,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,WAAW;IACtD,mEAAmE;IAC1D,IAAI,CAAQ;IACrB,sBAAsB;IACb,KAAK,CAAQ;IACJ,QAAQ,GAAW,CAAC,CAAA;IAEtC,YAAY,IAAY,EAAE,KAAa;QACrC,KAAK,CACH,sBAAsB,EACtB,2BAA2B,IAAI,gBAAgB,KAAK,+BAA+B,CACpF,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,WAAW;IACxD,sBAAsB;IACb,KAAK,CAAQ;IACJ,QAAQ,GAAW,CAAC,CAAA;IAEtC,YAAY,KAAa,EAAE,OAA0B;QACnD,KAAK,CACH,wBAAwB,EACxB,GAAG,KAAK,qDAAqD,CAAC,GAAG,OAAO,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAC1G,CAAA;QACD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACjD,iCAAiC;IACxB,IAAI,CAAQ;IACrB,8FAA8F;IACrF,IAAI,CAAoB;IAEjC,YAAY,IAAY,EAAE,IAAwB;QAChD,KAAK,CACH,iBAAiB,EACjB,IAAI,KAAK,SAAS;YAChB,CAAC,CAAC,GAAG,IAAI,gDAAgD;YACzD,CAAC,CAAC,GAAG,IAAI,kBAAkB,IAAI,GAAG,CACrC,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,wBAAyB,SAAQ,WAAW;IACvD,wDAAwD;IAC/C,IAAI,CAAY;IACzB,mDAAmD;IAC1C,QAAQ,CAAQ;IAEzB,YAAY,IAAgB,EAAE,QAAgB;QAC5C,KAAK,CACH,8BAA8B,EAC9B,GAAG,UAAU,CAAC,IAAI,CAAC,4BAA4B,QAAQ,iCAAiC,QAAQ,mCAAmC,CACpI,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,WAAW;IACpD,8CAA8C;IACrC,IAAI,CAAQ;IAErB,YAAY,IAAY,EAAE,IAAiE;QACzF,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,GAAG,uBAAuB,CAAC,CAAA;QACtE,KAAK,CACH,qBAAqB,EACrB,iCAAiC,IAAI,yDAAyD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,+BAA+B,CAChJ,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,gCAAgC;IACvB,OAAO,CAAQ;IAExB,YAAY,OAAe;QACzB,KAAK,CACH,iBAAiB,EACjB,qBAAqB,OAAO,4DAA4D,CACzF,CAAA;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;CACF;AAmCD;;;;;;GAMG;AACH,MAAM,OAAO,UAAW,SAAQ,WAAW;IAEzC;;;;OAIG;IACM,EAAE,CAAY;IACvB,uGAAuG;IAC9F,GAAG,CAAoB;IAChC,mGAAmG;IAC1F,KAAK,CAAoB;IAClC,+CAA+C;IACtC,OAAO,CAAoB;IACpC,qFAAqF;IAC5E,KAAK,CAAmB;IACjC,0FAA0F;IACjF,MAAM,CAAoB;IACnC;2BACuB;IACd,MAAM,CAAoB;IACnC,kGAAkG;IACzF,MAAM,CAAwB;IAEvC,YACE,IAAoB,EACpB,OAAe,EACf,UAA6B,EAAE,EAC/B,OAAsB;QAEtB,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QAC7B,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,EAAE,CAAA;QAC1B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAA;QACtB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;QAC1B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAA;QAC3B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAC5B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAC5B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAA;IACpC,CAAC;CACF","sourcesContent":["/**\n * What `@wtf/project-config` throws, each a {@link ConfigError} of a stable `code`:\n * {@link InvalidConfigFileError}, a file of the configuration that holds no object;\n * {@link InvalidSectionError}, a section its tool's schema refuses; {@link ConfigPathError}, a path\n * that names no value; {@link ConfigInCodeError}, a write to a configuration of code;\n * {@link NoConfigFileError}, a write with no package.json to hold it;\n * {@link ConfigFileMismatchError}, a write to a file that is not the one in use;\n * {@link UnwritableConfigFileError}, a write to a file that is never written;\n * {@link NoConfigValueError}, a value asked for that is not set; and\n * {@link EnvPlaceholderUnsetError}, a value that points at a variable of the environment that is\n * not set; {@link SyncConfigInCodeError}, a configuration of code loaded synchronously; and\n * {@link SyncSchemaError}, a section checked synchronously by a schema that checks asynchronously;\n * and {@link NamedError}, a reference of ./named that names no entry, or a module, an export or a\n * value that is not what it says. One that the arguments of a person cause exits 2.\n *\n * @packageDocumentation\n */\nimport type { ConfigIssue, ConfigPath } from './index.ts'\nimport { textOfPath } from './text.ts'\n\n/** What this package throws: an Error with a stable SCREAMING_SNAKE `code`, and the `exitCode` a\n * command that fails by it exits with, 1 by default. */\nexport class ConfigError extends Error {\n readonly code: string\n /** What a command that fails by it exits with. */\n readonly exitCode: number = 1\n\n constructor(code: string, message: string, options?: ErrorOptions) {\n super(message, options)\n this.code = code\n this.name = new.target.name\n }\n}\n\n/**\n * A file of the configuration that holds no configuration: no JSON, no object, or a module that\n * fails to load, or exports no object.\n */\nexport class InvalidConfigFileError extends ConfigError {\n /** The file, by its absolute path. */\n readonly file: string\n\n constructor(file: string, reason: string, options?: ErrorOptions) {\n super('INVALID_CONFIG_FILE', `${file}: ${reason}`, options)\n this.file = file\n }\n}\n\n/**\n * A section of the configuration that the schema of its tool refuses: each issue, by the file and\n * the path of the value, from the key that names the configuration, the namespace by default.\n */\nexport class InvalidSectionError extends ConfigError {\n /** The file of the configuration, by its absolute path. */\n readonly file: string\n /** The section, by its name. */\n readonly section: string\n /** What is wrong, each by its path in the section. */\n readonly issues: readonly ConfigIssue[]\n\n constructor(\n file: string,\n namespace: string,\n section: string,\n issues: readonly ConfigIssue[],\n key: string = namespace\n ) {\n super(\n 'INVALID_CONFIG_SECTION',\n [\n `${file}: the ${section} section of the ${namespace} configuration is not valid:`,\n ...issues.map(({ path, message }) => ` ${textOfPath([key, section, ...path])}: ${message}`)\n ].join('\\n')\n )\n this.file = file\n this.section = section\n this.issues = issues\n }\n}\n\n/**\n * A path of the configuration that names no value to read or write: an empty one, or one that\n * goes into a value that is no object or list. A usage failure: it exits 2.\n */\nexport class ConfigPathError extends ConfigError {\n /** The path, as it was given. */\n readonly path: string\n override readonly exitCode: number = 2\n\n constructor(path: string, reason: string) {\n super('INVALID_CONFIG_PATH', `${path === '' ? 'The path' : path} ${reason}`)\n this.path = path\n }\n}\n\n/**\n * A write to a configuration of code, as `wtf.config.mjs`, `wtf.config.js` or `wtf.config.ts`: code\n * is changed by a person, and not by a tool. Its message names what is written: the JSON files, and\n * the key of package.json.\n */\nexport class ConfigInCodeError extends ConfigError {\n /** The file of code, by its absolute path. */\n readonly file: string\n\n constructor(file: string, written: { readonly files: readonly string[]; readonly key: string }) {\n const names = [...written.files, `the \"${written.key}\" key of package.json`]\n super(\n 'CONFIG_IN_CODE',\n `The configuration is code, in ${file}: change it there. Only ${names.join(' and ')} ${names.length === 1 ? 'is' : 'are'} written.`\n )\n this.file = file\n }\n}\n\n/**\n * A write to the configuration of a project that has none, in the key of package.json, the\n * default, where the root has no package.json. Its message names the key, and the JSON file to make\n * it in instead, if there is one. A usage failure: it exits 2.\n */\nexport class NoConfigFileError extends ConfigError {\n /** The root of the project. */\n readonly root: string\n override readonly exitCode: number = 2\n\n constructor(\n root: string,\n {\n namespace,\n key = namespace,\n json\n }: { readonly namespace: string; readonly key?: string; readonly json?: string | undefined }\n ) {\n super(\n 'NO_CONFIG_FILE',\n `No package.json is in ${root} to hold the ${namespace} configuration in its \"${key}\" key: make one there${json === undefined ? '' : `, or name ${json} to make the configuration in`}.`\n )\n this.root = root\n }\n}\n\n/**\n * A write to a file of the configuration that is not the one in use, as its JSON file named where\n * package.json holds it. A usage failure: it exits 2.\n */\nexport class ConfigFileMismatchError extends ConfigError {\n /** The file that holds the configuration, by its absolute path. */\n readonly file: string\n /** The file named. */\n readonly named: string\n override readonly exitCode: number = 2\n\n constructor(file: string, named: string) {\n super(\n 'CONFIG_FILE_MISMATCH',\n `The configuration is in ${file}, and not in ${named}: write it there, or move it.`\n )\n this.file = file\n this.named = named\n }\n}\n\n/**\n * A write to a file that is no JSON file of the names of the configuration, nor package.json: one\n * of code, or one its names do not hold. Its message names those that are written. A usage\n * failure: it exits 2.\n */\nexport class UnwritableConfigFileError extends ConfigError {\n /** The file named. */\n readonly named: string\n override readonly exitCode: number = 2\n\n constructor(named: string, written: readonly string[]) {\n super(\n 'UNWRITABLE_CONFIG_FILE',\n `${named} is no file the configuration is written to: name ${[...written, 'package.json'].join(' or ')}.`\n )\n this.named = named\n }\n}\n\n/** A value of the configuration that is not set, which was asked for. */\nexport class NoConfigValueError extends ConfigError {\n /** The path, as it was given. */\n readonly path: string\n /** The file of the configuration, by its absolute path, or `undefined` when there is none. */\n readonly file: string | undefined\n\n constructor(path: string, file: string | undefined) {\n super(\n 'NO_CONFIG_VALUE',\n file === undefined\n ? `${path} is not set: the project has no configuration.`\n : `${path} is not set in ${file}.`\n )\n this.path = path\n this.file = file\n }\n}\n\n/**\n * A value of the configuration that points at a variable of the environment, by a placeholder\n * `${env:NAME}`, which is not set, or is empty. Its message names the path of the value, from the\n * key that names the configuration, and the variable, and holds no value.\n */\nexport class EnvPlaceholderUnsetError extends ConfigError {\n /** The path of the value that holds the placeholder. */\n readonly path: ConfigPath\n /** The name of the variable of the environment. */\n readonly variable: string\n\n constructor(path: ConfigPath, variable: string) {\n super(\n 'CONFIG_ENV_PLACEHOLDER_UNSET',\n `${textOfPath(path)}: points at the variable ${variable} of the environment by \\${env:${variable}}, which is not set, or is empty.`\n )\n this.path = path\n this.variable = variable\n }\n}\n\n/**\n * A configuration of code, as `wtf.config.ts`, loaded synchronously, as `loadConfigSync` of ./load\n * loads it for a tool that reads its config synchronously: code is imported, which is\n * asynchronous. Its message names the files a synchronous load reads, JSON and package.json's key.\n */\nexport class SyncConfigInCodeError extends ConfigError {\n /** The file of code, by its absolute path. */\n readonly file: string\n\n constructor(file: string, read: { readonly files: readonly string[]; readonly key: string }) {\n const names = [...read.files, `the \"${read.key}\" key of package.json`]\n super(\n 'CONFIG_IN_CODE_SYNC',\n `The configuration is code, in ${file}, which a synchronous load cannot import: write it in ${names.join(' or ')}, or load it with loadConfig.`\n )\n this.file = file\n }\n}\n\n/**\n * A section checked synchronously, as `sectionOfSync` of ./section checks it, by a schema that\n * checks asynchronously: a Standard Schema whose `validate` gives a promise, or a function that\n * does.\n */\nexport class SyncSchemaError extends ConfigError {\n /** The section, by its name. */\n readonly section: string\n\n constructor(section: string) {\n super(\n 'SCHEMA_NOT_SYNC',\n `The schema of the ${section} section checks it asynchronously: read it with sectionOf.`\n )\n this.section = section\n }\n}\n\n/**\n * The codes of a {@link NamedError}: `UNKNOWN_NAME`, a reference of a name of no entry;\n * `UNLOADABLE_MODULE`, a module that fails to load, or of no loader given; `MISSING_EXPORT`, an\n * export the module has not; and `INVALID_NAMED_VALUE`, a reference, a set or a value that is not\n * of its shape, or that its check refuses.\n */\nexport type NamedErrorCode =\n | 'UNKNOWN_NAME'\n | 'UNLOADABLE_MODULE'\n | 'MISSING_EXPORT'\n | 'INVALID_NAMED_VALUE'\n\n/** What a {@link NamedError} names, of its code: where it failed, the name and those there are,\n * the module and its export, or the issues of a check. */\nexport type NamedErrorDetails = {\n /** Where the value that failed is, by its path from what the caller gave, of any code. */\n readonly at?: ConfigPath\n /** The index of the set that failed in the array of sets, of any code. */\n readonly set?: number\n /** The name of the entry that failed, of a set or of a reference, of any code. */\n readonly entry?: string\n /** The name of no entry, of `UNKNOWN_NAME`. */\n readonly name?: string\n /** The names of the entries there are, of `UNKNOWN_NAME`. */\n readonly names?: readonly string[]\n /** The module, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a value it exports. */\n readonly module?: string\n /** The name of its export, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a value it exports. */\n readonly export?: string\n /** What the check found wrong, of `INVALID_NAMED_VALUE`. */\n readonly issues?: readonly ConfigIssue[]\n}\n\n/**\n * A reference of ./named that cannot be resolved, of a stable code of {@link NamedErrorCode}: a\n * name of no entry, whose message lists the names there are; a module that fails to load; an\n * export it has not; or a reference, a set or a value of no shape it takes. Of any code, it names\n * where it failed: its path, `at`, the index of its `set` and the name of its `entry`, and the\n * `module` and `export` a value came from. A tool maps each code to its own, as it chooses.\n */\nexport class NamedError extends ConfigError {\n declare readonly code: NamedErrorCode\n /**\n * Where the value that failed is, by its path from what the caller gave: the path the caller\n * gives as `at`, the index of the set in an array of sets, and the name of the entry, as\n * `['formatters', '1', 'wide']`; empty when nothing narrows it.\n */\n readonly at: ConfigPath\n /** The index of the set that failed in the array of sets: none of one set alone, or of a reference. */\n readonly set: number | undefined\n /** The name of the entry that failed, of a set or of the one a reference names: none of others. */\n readonly entry: string | undefined\n /** The name of no entry, of `UNKNOWN_NAME`. */\n readonly unknown: string | undefined\n /** The names of the entries there are, of `UNKNOWN_NAME`; none of any other code. */\n readonly names: readonly string[]\n /** The module, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a value it exports. */\n readonly module: string | undefined\n /** The name of the export of the module, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a\n * value it exports. */\n readonly export: string | undefined\n /** What the check found wrong, of `INVALID_NAMED_VALUE` of a value it refuses; none of others. */\n readonly issues: readonly ConfigIssue[]\n\n constructor(\n code: NamedErrorCode,\n message: string,\n details: NamedErrorDetails = {},\n options?: ErrorOptions\n ) {\n super(code, message, options)\n this.at = details.at ?? []\n this.set = details.set\n this.entry = details.entry\n this.unknown = details.name\n this.names = details.names ?? []\n this.module = details.module\n this.export = details.export\n this.issues = details.issues ?? []\n }\n}\n"]}
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What `@wtf/project-config` throws, each a {@link ConfigError} of a stable `code`:\n * {@link InvalidConfigFileError}, a file of the configuration that holds no object;\n * {@link InvalidSectionError}, a section its tool's schema refuses; {@link ConfigPathError}, a path\n * that names no value; {@link ConfigInCodeError}, a write to a configuration of code;\n * {@link NoConfigFileError}, a write with no package.json to hold it;\n * {@link ConfigFileMismatchError}, a write to a file that is not the one in use;\n * {@link UnwritableConfigFileError}, a write to a file that is never written;\n * {@link NoConfigValueError}, a value asked for that is not set; and\n * {@link EnvPlaceholderUnsetError}, a value that points at a variable of the environment that is\n * not set; {@link SyncSchemaError}, a value checked synchronously by a schema that checks\n * asynchronously; and {@link NamedError}, a reference of ./named that names no entry, or a module,\n * an export or a value that is not what it says. One that the arguments of a person cause exits 2.\n *\n * @packageDocumentation\n */\nimport type { ConfigIssue, ConfigPath } from './index.ts'\nimport { textOfPath } from './text.ts'\n\n/** What this package throws: an Error with a stable SCREAMING_SNAKE `code`, and the `exitCode` a\n * command that fails by it exits with, 1 by default. */\nexport class ConfigError extends Error {\n readonly code: string\n /** What a command that fails by it exits with. */\n readonly exitCode: number = 1\n\n constructor(code: string, message: string, options?: ErrorOptions) {\n super(message, options)\n this.code = code\n this.name = new.target.name\n }\n}\n\n/**\n * A file of the configuration that holds no configuration: no JSON, no object, or a module that\n * fails to load, or exports no object.\n */\nexport class InvalidConfigFileError extends ConfigError {\n /** The file, by its absolute path. */\n readonly file: string\n\n constructor(file: string, reason: string, options?: ErrorOptions) {\n super('INVALID_CONFIG_FILE', `${file}: ${reason}`, options)\n this.file = file\n }\n}\n\n/**\n * A section of the configuration that the schema of its tool refuses: each issue, by the file and\n * the path of the value, from the key that names the configuration, the namespace by default.\n */\nexport class InvalidSectionError extends ConfigError {\n /** The file of the configuration, by its absolute path. */\n readonly file: string\n /** The section, by its name. */\n readonly section: string\n /** What is wrong, each by its path in the section. */\n readonly issues: readonly ConfigIssue[]\n\n constructor(\n file: string,\n namespace: string,\n section: string,\n issues: readonly ConfigIssue[],\n key: string = namespace\n ) {\n super(\n 'INVALID_CONFIG_SECTION',\n [\n `${file}: the ${section} section of the ${namespace} configuration is not valid:`,\n ...issues.map(({ path, message }) => ` ${textOfPath([key, section, ...path])}: ${message}`)\n ].join('\\n')\n )\n this.file = file\n this.section = section\n this.issues = issues\n }\n}\n\n/**\n * A path of the configuration that names no value to read or write: an empty one, or one that\n * goes into a value that is no object or list. A usage failure: it exits 2.\n */\nexport class ConfigPathError extends ConfigError {\n /** The path, as it was given. */\n readonly path: string\n override readonly exitCode: number = 2\n\n constructor(path: string, reason: string) {\n super('INVALID_CONFIG_PATH', `${path === '' ? 'The path' : path} ${reason}`)\n this.path = path\n }\n}\n\n/**\n * A write to a configuration of code, as `wtf.config.mjs`, `wtf.config.js` or `wtf.config.ts`: code\n * is changed by a person, and not by a tool. Its message names what is written: the JSON files, and\n * the key of package.json.\n */\nexport class ConfigInCodeError extends ConfigError {\n /** The file of code, by its absolute path. */\n readonly file: string\n\n constructor(file: string, written: { readonly files: readonly string[]; readonly key: string }) {\n const names = [...written.files, `the \"${written.key}\" key of package.json`]\n super(\n 'CONFIG_IN_CODE',\n `The configuration is code, in ${file}: change it there. Only ${names.join(' and ')} ${names.length === 1 ? 'is' : 'are'} written.`\n )\n this.file = file\n }\n}\n\n/**\n * A write to the configuration of a project that has none, in the key of package.json, the\n * default, where the root has no package.json. Its message names the key, and the JSON file to make\n * it in instead, if there is one. A usage failure: it exits 2.\n */\nexport class NoConfigFileError extends ConfigError {\n /** The root of the project. */\n readonly root: string\n override readonly exitCode: number = 2\n\n constructor(\n root: string,\n {\n namespace,\n key = namespace,\n json\n }: { readonly namespace: string; readonly key?: string; readonly json?: string | undefined }\n ) {\n super(\n 'NO_CONFIG_FILE',\n `No package.json is in ${root} to hold the ${namespace} configuration in its \"${key}\" key: make one there${json === undefined ? '' : `, or name ${json} to make the configuration in`}.`\n )\n this.root = root\n }\n}\n\n/**\n * A write to a file of the configuration that is not the one in use, as its JSON file named where\n * package.json holds it. A usage failure: it exits 2.\n */\nexport class ConfigFileMismatchError extends ConfigError {\n /** The file that holds the configuration, by its absolute path. */\n readonly file: string\n /** The file named. */\n readonly named: string\n override readonly exitCode: number = 2\n\n constructor(file: string, named: string) {\n super(\n 'CONFIG_FILE_MISMATCH',\n `The configuration is in ${file}, and not in ${named}: write it there, or move it.`\n )\n this.file = file\n this.named = named\n }\n}\n\n/**\n * A write to a file that is no JSON file of the names of the configuration, nor package.json: one\n * of code, or one its names do not hold. Its message names those that are written. A usage\n * failure: it exits 2.\n */\nexport class UnwritableConfigFileError extends ConfigError {\n /** The file named. */\n readonly named: string\n override readonly exitCode: number = 2\n\n constructor(named: string, written: readonly string[]) {\n super(\n 'UNWRITABLE_CONFIG_FILE',\n `${named} is no file the configuration is written to: name ${[...written, 'package.json'].join(' or ')}.`\n )\n this.named = named\n }\n}\n\n/** A value of the configuration that is not set, which was asked for. */\nexport class NoConfigValueError extends ConfigError {\n /** The path, as it was given. */\n readonly path: string\n /** The file of the configuration, by its absolute path, or `undefined` when there is none. */\n readonly file: string | undefined\n\n constructor(path: string, file: string | undefined) {\n super(\n 'NO_CONFIG_VALUE',\n file === undefined\n ? `${path} is not set: the project has no configuration.`\n : `${path} is not set in ${file}.`\n )\n this.path = path\n this.file = file\n }\n}\n\n/**\n * A value of the configuration that points at a variable of the environment, by a placeholder\n * `${env:NAME}`, which is not set, or is empty. Its message names the path of the value, from the\n * key that names the configuration, and the variable, and holds no value.\n */\nexport class EnvPlaceholderUnsetError extends ConfigError {\n /** The path of the value that holds the placeholder. */\n readonly path: ConfigPath\n /** The name of the variable of the environment. */\n readonly variable: string\n\n constructor(path: ConfigPath, variable: string) {\n super(\n 'CONFIG_ENV_PLACEHOLDER_UNSET',\n `${textOfPath(path)}: points at the variable ${variable} of the environment by \\${env:${variable}}, which is not set, or is empty.`\n )\n this.path = path\n this.variable = variable\n }\n}\n\n/**\n * A value checked synchronously, as `issuesOfSync` of ./section checks it, by a schema that\n * checks asynchronously: a Standard Schema whose `validate` gives a promise, or a function that\n * does.\n */\nexport class SyncSchemaError extends ConfigError {\n /** The section, by its name. */\n readonly section: string\n\n constructor(section: string) {\n super(\n 'SCHEMA_NOT_SYNC',\n `The schema of the ${section} section checks it asynchronously: read it with sectionOf.`\n )\n this.section = section\n }\n}\n\n/**\n * The codes of a {@link NamedError}: `UNKNOWN_NAME`, a reference of a name of no entry;\n * `UNLOADABLE_MODULE`, a module that fails to load, or of no loader given; `MISSING_EXPORT`, an\n * export the module has not; and `INVALID_NAMED_VALUE`, a reference, a set or a value that is not\n * of its shape, or that its check refuses.\n */\nexport type NamedErrorCode =\n | 'UNKNOWN_NAME'\n | 'UNLOADABLE_MODULE'\n | 'MISSING_EXPORT'\n | 'INVALID_NAMED_VALUE'\n\n/** What a {@link NamedError} names, of its code: where it failed, the name and those there are,\n * the module and its export, or the issues of a check. */\nexport type NamedErrorDetails = {\n /** Where the value that failed is, by its path from what the caller gave, of any code. */\n readonly at?: ConfigPath\n /** The index of the set that failed in the array of sets, of any code. */\n readonly set?: number\n /** The name of the entry that failed, of a set or of a reference, of any code. */\n readonly entry?: string\n /** The name of no entry, of `UNKNOWN_NAME`. */\n readonly name?: string\n /** The names of the entries there are, of `UNKNOWN_NAME`. */\n readonly names?: readonly string[]\n /** The module, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a value it exports. */\n readonly module?: string\n /** The name of its export, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a value it exports. */\n readonly export?: string\n /** What the check found wrong, of `INVALID_NAMED_VALUE`. */\n readonly issues?: readonly ConfigIssue[]\n}\n\n/**\n * A reference of ./named that cannot be resolved, of a stable code of {@link NamedErrorCode}: a\n * name of no entry, whose message lists the names there are; a module that fails to load; an\n * export it has not; or a reference, a set or a value of no shape it takes. Of any code, it names\n * where it failed: its path, `at`, the index of its `set` and the name of its `entry`, and the\n * `module` and `export` a value came from. A tool maps each code to its own, as it chooses.\n */\nexport class NamedError extends ConfigError {\n declare readonly code: NamedErrorCode\n /**\n * Where the value that failed is, by its path from what the caller gave: the path the caller\n * gives as `at`, the index of the set in an array of sets, and the name of the entry, as\n * `['formatters', '1', 'wide']`; empty when nothing narrows it.\n */\n readonly at: ConfigPath\n /** The index of the set that failed in the array of sets: none of one set alone, or of a reference. */\n readonly set: number | undefined\n /** The name of the entry that failed, of a set or of the one a reference names: none of others. */\n readonly entry: string | undefined\n /** The name of no entry, of `UNKNOWN_NAME`. */\n readonly unknown: string | undefined\n /** The names of the entries there are, of `UNKNOWN_NAME`; none of any other code. */\n readonly names: readonly string[]\n /** The module, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a value it exports. */\n readonly module: string | undefined\n /** The name of the export of the module, of `UNLOADABLE_MODULE` and `MISSING_EXPORT`, and of a\n * value it exports. */\n readonly export: string | undefined\n /** What the check found wrong, of `INVALID_NAMED_VALUE` of a value it refuses; none of others. */\n readonly issues: readonly ConfigIssue[]\n\n constructor(\n code: NamedErrorCode,\n message: string,\n details: NamedErrorDetails = {},\n options?: ErrorOptions\n ) {\n super(code, message, options)\n this.at = details.at ?? []\n this.set = details.set\n this.entry = details.entry\n this.unknown = details.name\n this.names = details.names ?? []\n this.module = details.module\n this.export = details.export\n this.issues = details.issues ?? []\n }\n}\n"]}
package/dist/files.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import type { ConfigPlatform, SyncFiles } from './index.ts';
1
+ import type { ConfigPlatform } from './index.ts';
2
2
  /** Whether `value` is a JSON object: no list, and not `null`. */
3
3
  export declare const isObject: (value: unknown) => value is Record<string, unknown>;
4
- /** What the configuration is read and written by, asynchronously. */
4
+ /** What the configuration is read and written by. */
5
5
  export type Files = {
6
6
  /** The text of the file at `path`, or `undefined` when no file is there. */
7
7
  readonly text: (path: string) => Promise<string | undefined>;
@@ -18,14 +18,12 @@ export type Read = {
18
18
  } | {
19
19
  readonly files: string;
20
20
  };
21
- /** A read of the configuration, written once: a generator of the reads it asks for, and its result. */
21
+ /** A read of the configuration: a generator of the reads it asks for, and its result. */
22
22
  export type Reads<T> = Generator<Read, T, unknown>;
23
23
  /**
24
- * What `reads` gives, each read done synchronously by `files`: what a read gives is the value of
25
- * its step, and what it throws is thrown at its step.
24
+ * What `reads` gives, each read done by `files`: what a read gives is the value of its step, and
25
+ * what it throws is thrown at its step.
26
26
  */
27
- export declare function readSync<T>(reads: Reads<T>, files: SyncFiles): T;
28
- /** What `reads` gives, each read done by `files`, as {@link readSync} does them. */
29
27
  export declare function readAsync<T>(reads: Reads<T>, files: Files): Promise<T>;
30
28
  /** The text of the file at `path`, `undefined` when none is there, asked of the runner. */
31
29
  export declare function textOf(path: string): Reads<string | undefined>;
package/dist/files.js CHANGED
@@ -33,26 +33,9 @@ export const filesOf = (platform) => ({
33
33
  }
34
34
  });
35
35
  /**
36
- * What `reads` gives, each read done synchronously by `files`: what a read gives is the value of
37
- * its step, and what it throws is thrown at its step.
36
+ * What `reads` gives, each read done by `files`: what a read gives is the value of its step, and
37
+ * what it throws is thrown at its step.
38
38
  */
39
- export function readSync(reads, files) {
40
- let step = reads.next();
41
- while (!step.done) {
42
- const read = step.value;
43
- let value;
44
- try {
45
- value = 'text' in read ? files.text(read.text) : files.files(read.files);
46
- }
47
- catch (error) {
48
- step = reads.throw(error);
49
- continue;
50
- }
51
- step = reads.next(value);
52
- }
53
- return step.value;
54
- }
55
- /** What `reads` gives, each read done by `files`, as {@link readSync} does them. */
56
39
  export async function readAsync(reads, files) {
57
40
  let step = reads.next();
58
41
  while (!step.done) {
package/dist/files.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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","sourcesContent":["// What the modules of the configuration read and write files by: the files of a platform, by\n// `@wtf/platform-fs/files`, asynchronously, or the files a caller reads synchronously; a read\n// written once, as a generator of the reads it asks for, and run either way; and what a file\n// holds the configuration as. Internal: no export map entry names it.\nimport type { PlatformError } from '@wtf/platform/errors'\nimport { handleAt, isNotFound, readText, writeText } from '@wtf/platform-fs/files'\nimport { isFileSystemError } from '@wtf/platform-fs/errors'\n\nimport { InvalidConfigFileError } from './errors.ts'\nimport type { ConfigPlatform, SyncFiles } from './index.ts'\n\n/** Whether `value` is a JSON object: no list, and not `null`. */\nexport const isObject = (value: unknown): value is Record<string, unknown> =>\n typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** What the configuration is read and written by, asynchronously. */\nexport type Files = {\n /** The text of the file at `path`, or `undefined` when no file is there. */\n readonly text: (path: string) => Promise<string | undefined>\n /** The names of the files in `folder`, none when it is no folder. */\n readonly files: (folder: string) => Promise<ReadonlySet<string>>\n /** The file at `path` written whole, made where it is not there. */\n readonly write: (path: string, text: string) => Promise<void>\n}\n\n/** Whether `error` says no entry of the kind asked for is there: none, or one of the other kind. */\nconst isMissing = (error: unknown): boolean =>\n isNotFound(error) ||\n isFileSystemError(error, 'TypeMismatchError') ||\n isFileSystemError((error as PlatformError | undefined)?.cause, 'TypeMismatchError')\n\n/** What `read` gives, or `fallback` when what it reads is not there. */\nasync function orMissing<T>(read: () => Promise<T>, fallback: T): Promise<T> {\n try {\n return await read()\n } catch (error) {\n if (isMissing(error)) return fallback\n throw error\n }\n}\n\n/** The files of `platform`, each path walked down from the root of its storage. */\nexport const filesOf = (platform: ConfigPlatform): Files => ({\n text: (path) => orMissing(() => readText(platform, path), undefined),\n files: (folder) =>\n orMissing(async () => {\n const names = new Set<string>()\n for await (const [name, entry] of (\n await handleAt(platform, folder, { kind: 'directory' })\n ).entries())\n if (entry.kind === 'file') names.add(name)\n return names\n }, new Set<string>()),\n write: async (path, text) => {\n await writeText(platform, path, text)\n }\n})\n\n/** A read a step of a generator asks for: the text of a file, or the names of a folder's files. */\nexport type Read = { readonly text: string } | { readonly files: string }\n\n/** A read of the configuration, written once: a generator of the reads it asks for, and its result. */\nexport type Reads<T> = Generator<Read, T, unknown>\n\n/**\n * What `reads` gives, each read done synchronously by `files`: what a read gives is the value of\n * its step, and what it throws is thrown at its step.\n */\nexport function readSync<T>(reads: Reads<T>, files: SyncFiles): T {\n let step = reads.next()\n while (!step.done) {\n const read = step.value\n let value: unknown\n try {\n value = 'text' in read ? files.text(read.text) : files.files(read.files)\n } catch (error) {\n step = reads.throw(error)\n continue\n }\n step = reads.next(value)\n }\n return step.value\n}\n\n/** What `reads` gives, each read done by `files`, as {@link readSync} does them. */\nexport async function readAsync<T>(reads: Reads<T>, files: Files): Promise<T> {\n let step = reads.next()\n while (!step.done) {\n const read = step.value\n let value: unknown\n try {\n // oxlint-disable-next-line no-await-in-loop -- each read follows from the one before\n value = 'text' in read ? await files.text(read.text) : await files.files(read.files)\n } catch (error) {\n step = reads.throw(error)\n continue\n }\n step = reads.next(value)\n }\n return step.value\n}\n\n/** The text of the file at `path`, `undefined` when none is there, asked of the runner. */\nexport function* textOf(path: string): Reads<string | undefined> {\n return (yield { text: path }) as string | undefined\n}\n\n/** The names of the files of `folder`, asked of the runner. */\nexport function* namesOf(folder: string): Reads<ReadonlySet<string>> {\n return (yield { files: folder }) as ReadonlySet<string>\n}\n\n/**\n * The package.json at `path`, as an object, or `undefined` when there is none. Its text is JSON of\n * an object, or an {@link InvalidConfigFileError}.\n */\nexport function* manifestAt(path: string): Reads<Record<string, unknown> | undefined> {\n const text = yield* textOf(path)\n if (text === undefined) return undefined\n return manifestOf(path, text)\n}\n\n/** The package.json at `path` of `text`, an object, or an {@link InvalidConfigFileError}. */\nexport function manifestOf(path: string, text: string): Record<string, unknown> {\n let manifest: unknown\n try {\n manifest = JSON.parse(text)\n } catch (error) {\n throw new InvalidConfigFileError(path, 'is no JSON.', { cause: error })\n }\n if (!isObject(manifest)) throw new InvalidConfigFileError(path, 'is no JSON object.')\n return manifest\n}\n\n/** What a file holds the configuration as: `code`, a module whose default export it is; `json`, a\n * JSON file; or `package`, the key of package.json. */\nexport type ConfigKind = 'code' | 'json' | 'package'\n\n/** The name of package.json, which holds the configuration by its key. */\nexport const PACKAGE_JSON = 'package.json'\n\n/**\n * What `file` holds the configuration as, by its name: package.json, by its key; code, as Node\n * imports it, `.mjs`, `.js`, `.ts`, `.cjs`, `.mts` or `.cts`; or JSON, `.json`. Any other is a\n * `TypeError`: it names no file the configuration can be read from.\n */\nexport function kindOf(file: string): ConfigKind {\n if (file === PACKAGE_JSON) return 'package'\n if (/\\.[cm]?[jt]s$/.test(file)) return 'code'\n if (file.endsWith('.json')) return 'json'\n throw new TypeError(\n `${file} is no file of the configuration: give a file of code (.mjs, .js, .ts) or of JSON (.json).`\n )\n}\n"]}
1
+ {"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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","sourcesContent":["// What the modules of the configuration read and write files by: the files of a platform, by\n// `@wtf/platform-fs/files`; a read written as a generator of the reads it asks for, and run by\n// those files; and what a file holds the configuration as. Internal: no export map entry names it.\nimport type { PlatformError } from '@wtf/platform/errors'\nimport { handleAt, isNotFound, readText, writeText } from '@wtf/platform-fs/files'\nimport { isFileSystemError } from '@wtf/platform-fs/errors'\n\nimport { InvalidConfigFileError } from './errors.ts'\nimport type { ConfigPlatform } from './index.ts'\n\n/** Whether `value` is a JSON object: no list, and not `null`. */\nexport const isObject = (value: unknown): value is Record<string, unknown> =>\n typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/** What the configuration is read and written by. */\nexport type Files = {\n /** The text of the file at `path`, or `undefined` when no file is there. */\n readonly text: (path: string) => Promise<string | undefined>\n /** The names of the files in `folder`, none when it is no folder. */\n readonly files: (folder: string) => Promise<ReadonlySet<string>>\n /** The file at `path` written whole, made where it is not there. */\n readonly write: (path: string, text: string) => Promise<void>\n}\n\n/** Whether `error` says no entry of the kind asked for is there: none, or one of the other kind. */\nconst isMissing = (error: unknown): boolean =>\n isNotFound(error) ||\n isFileSystemError(error, 'TypeMismatchError') ||\n isFileSystemError((error as PlatformError | undefined)?.cause, 'TypeMismatchError')\n\n/** What `read` gives, or `fallback` when what it reads is not there. */\nasync function orMissing<T>(read: () => Promise<T>, fallback: T): Promise<T> {\n try {\n return await read()\n } catch (error) {\n if (isMissing(error)) return fallback\n throw error\n }\n}\n\n/** The files of `platform`, each path walked down from the root of its storage. */\nexport const filesOf = (platform: ConfigPlatform): Files => ({\n text: (path) => orMissing(() => readText(platform, path), undefined),\n files: (folder) =>\n orMissing(async () => {\n const names = new Set<string>()\n for await (const [name, entry] of (\n await handleAt(platform, folder, { kind: 'directory' })\n ).entries())\n if (entry.kind === 'file') names.add(name)\n return names\n }, new Set<string>()),\n write: async (path, text) => {\n await writeText(platform, path, text)\n }\n})\n\n/** A read a step of a generator asks for: the text of a file, or the names of a folder's files. */\nexport type Read = { readonly text: string } | { readonly files: string }\n\n/** A read of the configuration: a generator of the reads it asks for, and its result. */\nexport type Reads<T> = Generator<Read, T, unknown>\n\n/**\n * What `reads` gives, each read done by `files`: what a read gives is the value of its step, and\n * what it throws is thrown at its step.\n */\nexport async function readAsync<T>(reads: Reads<T>, files: Files): Promise<T> {\n let step = reads.next()\n while (!step.done) {\n const read = step.value\n let value: unknown\n try {\n // oxlint-disable-next-line no-await-in-loop -- each read follows from the one before\n value = 'text' in read ? await files.text(read.text) : await files.files(read.files)\n } catch (error) {\n step = reads.throw(error)\n continue\n }\n step = reads.next(value)\n }\n return step.value\n}\n\n/** The text of the file at `path`, `undefined` when none is there, asked of the runner. */\nexport function* textOf(path: string): Reads<string | undefined> {\n return (yield { text: path }) as string | undefined\n}\n\n/** The names of the files of `folder`, asked of the runner. */\nexport function* namesOf(folder: string): Reads<ReadonlySet<string>> {\n return (yield { files: folder }) as ReadonlySet<string>\n}\n\n/**\n * The package.json at `path`, as an object, or `undefined` when there is none. Its text is JSON of\n * an object, or an {@link InvalidConfigFileError}.\n */\nexport function* manifestAt(path: string): Reads<Record<string, unknown> | undefined> {\n const text = yield* textOf(path)\n if (text === undefined) return undefined\n return manifestOf(path, text)\n}\n\n/** The package.json at `path` of `text`, an object, or an {@link InvalidConfigFileError}. */\nexport function manifestOf(path: string, text: string): Record<string, unknown> {\n let manifest: unknown\n try {\n manifest = JSON.parse(text)\n } catch (error) {\n throw new InvalidConfigFileError(path, 'is no JSON.', { cause: error })\n }\n if (!isObject(manifest)) throw new InvalidConfigFileError(path, 'is no JSON object.')\n return manifest\n}\n\n/** What a file holds the configuration as: `code`, a module whose default export it is; `json`, a\n * JSON file; or `package`, the key of package.json. */\nexport type ConfigKind = 'code' | 'json' | 'package'\n\n/** The name of package.json, which holds the configuration by its key. */\nexport const PACKAGE_JSON = 'package.json'\n\n/**\n * What `file` holds the configuration as, by its name: package.json, by its key; code, as Node\n * imports it, `.mjs`, `.js`, `.ts`, `.cjs`, `.mts` or `.cts`; or JSON, `.json`. Any other is a\n * `TypeError`: it names no file the configuration can be read from.\n */\nexport function kindOf(file: string): ConfigKind {\n if (file === PACKAGE_JSON) return 'package'\n if (/\\.[cm]?[jt]s$/.test(file)) return 'code'\n if (file.endsWith('.json')) return 'json'\n throw new TypeError(\n `${file} is no file of the configuration: give a file of code (.mjs, .js, .ts) or of JSON (.json).`\n )\n}\n"]}
package/dist/index.d.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * ({@link LocatedConfig}); what a tool reads ({@link ResolvedConfig}); the defaults a tool's
7
7
  * package gives ({@link ConfigDefaults}); a path in it ({@link ConfigPath}); what checks a section
8
8
  * ({@link SectionSchema}) and what it finds wrong ({@link ConfigIssue}); what a write did
9
- * ({@link ConfigWrite}); and what it is read by ({@link ConfigPlatform}, {@link ConfigSyncPlatform}).
9
+ * ({@link ConfigWrite}); and what it is read by ({@link ConfigPlatform}).
10
10
  * Types only, with no code.
11
11
  *
12
12
  * @packageDocumentation
@@ -14,7 +14,6 @@
14
14
  */
15
15
  import type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from '@standard-schema/spec';
16
16
  import type { FilesPlatform } from '@wtf/platform-fs/files';
17
- import type { Path } from '@wtf/platform/path';
18
17
  /**
19
18
  * The section of one tool, by its key `K` and its value `V`, as `ConfigSection<'vite', ViteOptions>`.
20
19
  * A section is optional: a project configures the tools it chooses.
@@ -172,25 +171,9 @@ export type ConfigWrite = {
172
171
  * `default` is the configuration. */
173
172
  export type ImportModule = (path: string) => Promise<unknown>;
174
173
  /**
175
- * What the configuration is read and written by, asynchronously: the platform's storage, whose
174
+ * What the configuration is read and written by: the platform's storage, whose
176
175
  * `getDirectory()` is the root of its file system, its paths, and its working folder, as
177
176
  * `@wtf/platform-fs/files` reads a platform's files. A `Platform` of `@wtf/platform` is one, as
178
177
  * `nodePlatform()` of `@wtf/platform-node/platform` makes Node's.
179
178
  */
180
179
  export type ConfigPlatform = FilesPlatform;
181
- /** What reads a project's files synchronously, by their absolute paths. */
182
- export type SyncFiles = {
183
- /** The text of the file at `path`, or `undefined` when no file is there. */
184
- readonly text: (path: string) => string | undefined;
185
- /** The names of the files in `folder`, none when it is no folder. */
186
- readonly files: (folder: string) => ReadonlySet<string>;
187
- };
188
- /**
189
- * What the configuration is read by synchronously: the platform's paths, and its files, read
190
- * synchronously, as no handle of the File System Standard is. `nodeSyncPlatform()` of ./node adds
191
- * Node's files to a platform.
192
- */
193
- export type ConfigSyncPlatform = {
194
- readonly path: Pick<Path, 'resolve' | 'join' | 'dirname'>;
195
- readonly files: SyncFiles;
196
- };
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The types of a project's configuration under a namespace, `wtf` by default: the object\n * ({@link NamespaceConfig}), made of a section for each tool ({@link ConfigSection}), or of the\n * sections the schemas of the tools type ({@link SectionsOf}); the names it is looked for by\n * ({@link ConfigNames}); the file it is in ({@link ConfigSource}); where it is\n * ({@link LocatedConfig}); what a tool reads ({@link ResolvedConfig}); the defaults a tool's\n * package gives ({@link ConfigDefaults}); a path in it ({@link ConfigPath}); what checks a section\n * ({@link SectionSchema}) and what it finds wrong ({@link ConfigIssue}); what a write did\n * ({@link ConfigWrite}); and what it is read by ({@link ConfigPlatform}, {@link ConfigSyncPlatform}).\n * Types only, with no code.\n *\n * @packageDocumentation\n * @module index\n */\nimport type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from '@standard-schema/spec'\nimport type { FilesPlatform } from '@wtf/platform-fs/files'\nimport type { Path } from '@wtf/platform/path'\n\n/**\n * The section of one tool, by its key `K` and its value `V`, as `ConfigSection<'vite', ViteOptions>`.\n * A section is optional: a project configures the tools it chooses.\n */\nexport type ConfigSection<K extends string, V> = { readonly [P in K]?: V }\n\n/**\n * The sections of the schemas `S`, each by its name: the input type of each schema, as\n * `SectionsOf<{ vite: typeof viteSchema }>` is `{ vite?: ViteOptions }`. A code config is typed by\n * it with `defineConfig` of ./define.\n */\nexport type SectionsOf<S extends Readonly<Record<string, StandardTypedV1>>> = {\n readonly [K in keyof S]?: StandardTypedV1.InferInput<S[K]>\n}\n\n/**\n * The configuration of a project under a namespace: the sections `S`, each checked by its type;\n * the `$schema` a JSON file names its schema by; and any other section, of a tool not named, as it\n * is. A tool reads its own section, and no other.\n *\n * ```ts\n * const config: NamespaceConfig<{ vite?: { compress?: false } }> = { vite: { compress: false } }\n * ```\n */\nexport type NamespaceConfig<S extends object = Record<never, never>> = S & {\n /** The JSON Schema of a JSON file of the configuration, as an editor reads it. */\n readonly $schema?: string\n readonly [section: string]: unknown\n}\n\n/**\n * The names the configuration of a namespace is looked for by, each a tool's to give: the files at\n * the root of the project, the key of its package.json, and the prefix of the environment's\n * variables over it. Of the namespace `wtf`, by default, `wtf.config.mjs`, `wtf.config.js`,\n * `wtf.config.ts` and `wtf.config.json`, the `wtf` key, and the variables `WTF_*`.\n */\nexport type ConfigNames = {\n /**\n * The files it can be in, in the order the first found is used, each of code (`.mjs`, `.js`,\n * `.ts`, `.cjs`, `.mts` or `.cts`) or of JSON (`.json`). The key of package.json comes last.\n */\n readonly files?: readonly string[]\n /** The key of package.json that holds it when no file does: the namespace by default. */\n readonly key?: string\n /**\n * The name the environment's variables over it start with: the key by default, so `wtf` is\n * `WTF_`, and `WTF_VITE_COMPRESS` sets `wtf.vite.compress`.\n */\n readonly env?: string\n}\n\n/** A file of the configuration found at the root of a project: one of its files, or package.json. */\nexport type ConfigSource = {\n /** Its name, as the names give it, or `package.json`. */\n readonly file: string\n /** Its absolute path. */\n readonly path: string\n}\n\n/**\n * Where a project's configuration is: the root of the project, the key of package.json, and each\n * file of it found there, in the order of its files, then package.json. The first is used; the\n * others are ignored.\n */\nexport type LocatedConfig = {\n readonly root: string\n /** The key of package.json, which a path of the configuration starts from: `wtf.vite.compress`. */\n readonly key: string\n readonly sources: readonly ConfigSource[]\n}\n\n/**\n * The configuration a tool's package gives under the project's, as its own defaults: each section\n * the project gives is merged over it, value by value, as `sectionOf` of ./section reads it.\n */\nexport type ConfigDefaults = {\n /** The object, of the sections of the namespace. */\n readonly config: NamespaceConfig\n /** The file it is in, by its absolute path, which an error of a section of it names. */\n readonly path: string\n}\n\n/**\n * The environment a tool reads the configuration with: the prefix of the variables over it, as\n * `WTF_`; each of those that is set and not empty, by its name; and the whole environment, in\n * `values`, which the placeholders `${env:NAME}` of a section are taken from. Only `sectionOf` of\n * ./section reads `values`: nothing shows or writes it.\n */\nexport type ConfigEnvironment = {\n readonly prefix: string\n readonly variables: Readonly<Record<string, string>>\n readonly values: Readonly<Record<string, string | undefined>>\n}\n\n/** A project's configuration, as a tool reads it. */\nexport type ResolvedConfig = {\n /** Its namespace. */\n readonly namespace: string\n /** The root of the project, where it was looked for. */\n readonly root: string\n /** The key of package.json it was looked for in, which a path of it starts from. */\n readonly key: string\n /** The object, `{}` when no file holds one. */\n readonly config: NamespaceConfig\n /** The file it came from, or `undefined` when no file holds one. */\n readonly source: ConfigSource | undefined\n /** The other files found, which are ignored, as only the first is used. */\n readonly ignored: readonly ConfigSource[]\n /** The configuration of the tool's package under the project's, when the tool gives one. */\n readonly defaults?: ConfigDefaults | undefined\n /**\n * The environment the tool gave, which a section is read with: its variables over the project's\n * configuration, and the values its placeholders are taken from. None when no environment was\n * given: then a placeholder names a variable that is not set.\n */\n readonly environment?: ConfigEnvironment | undefined\n}\n\n/** A path in the configuration, by its keys from the top: `['vite', 'compress']`. A key of digits\n * is an index of a list. */\nexport type ConfigPath = readonly string[]\n\n/** What is wrong with a value of a section: where it is, by its path in the section, and why. */\nexport type ConfigIssue = {\n readonly path: ConfigPath\n readonly message: string\n}\n\n/** A JSON Schema, as the object of its keywords, or `true` or `false`. */\nexport type JsonSchema = { readonly [keyword: string]: unknown } | boolean\n\n/** A function that checks a section: what is wrong with it, none when it is valid. */\nexport type ValidateSection = (\n value: unknown\n) => readonly ConfigIssue[] | Promise<readonly ConfigIssue[]>\n\n/**\n * What a tool checks its section by: a Standard Schema, as a preset's `./schema` exports one, or\n * zod's, whose output is what the section reads as; a JSON Schema of draft 2020-12, or a Standard\n * JSON Schema, which ajv checks; or a function of its own.\n */\nexport type SectionSchema<T = unknown> =\n | StandardSchemaV1<unknown, T>\n | StandardJSONSchemaV1<unknown, T>\n | JsonSchema\n | ValidateSection\n\n/**\n * What a write did: where, at which path, the value there before and after it, and whether it\n * changed the file, or made it.\n */\nexport type ConfigWrite = {\n readonly root: string\n /** The key of package.json, which a path of the configuration starts from. */\n readonly key: string\n /** The file written, or `undefined` when nothing was there to unset. */\n readonly source: ConfigSource | undefined\n /** The other files of the configuration found, which a reader ignores. */\n readonly ignored: readonly ConfigSource[]\n readonly path: ConfigPath\n /** The value at the path before the write, `undefined` when there was none. */\n readonly previous: unknown\n /** The value at the path after the write, `undefined` when it was unset. */\n readonly value: unknown\n /** Whether the file was written: false when the value was already so. */\n readonly changed: boolean\n /** Whether the file, or the key of package.json, was made by the write. */\n readonly created: boolean\n}\n\n/** What imports a file of code, as `wtf.config.ts`, by its absolute path: its module, whose\n * `default` is the configuration. */\nexport type ImportModule = (path: string) => Promise<unknown>\n\n/**\n * What the configuration is read and written by, asynchronously: the platform's storage, whose\n * `getDirectory()` is the root of its file system, its paths, and its working folder, as\n * `@wtf/platform-fs/files` reads a platform's files. A `Platform` of `@wtf/platform` is one, as\n * `nodePlatform()` of `@wtf/platform-node/platform` makes Node's.\n */\nexport type ConfigPlatform = FilesPlatform\n\n/** What reads a project's files synchronously, by their absolute paths. */\nexport type SyncFiles = {\n /** The text of the file at `path`, or `undefined` when no file is there. */\n readonly text: (path: string) => string | undefined\n /** The names of the files in `folder`, none when it is no folder. */\n readonly files: (folder: string) => ReadonlySet<string>\n}\n\n/**\n * What the configuration is read by synchronously: the platform's paths, and its files, read\n * synchronously, as no handle of the File System Standard is. `nodeSyncPlatform()` of ./node adds\n * Node's files to a platform.\n */\nexport type ConfigSyncPlatform = {\n readonly path: Pick<Path, 'resolve' | 'join' | 'dirname'>\n readonly files: SyncFiles\n}\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * The types of a project's configuration under a namespace, `wtf` by default: the object\n * ({@link NamespaceConfig}), made of a section for each tool ({@link ConfigSection}), or of the\n * sections the schemas of the tools type ({@link SectionsOf}); the names it is looked for by\n * ({@link ConfigNames}); the file it is in ({@link ConfigSource}); where it is\n * ({@link LocatedConfig}); what a tool reads ({@link ResolvedConfig}); the defaults a tool's\n * package gives ({@link ConfigDefaults}); a path in it ({@link ConfigPath}); what checks a section\n * ({@link SectionSchema}) and what it finds wrong ({@link ConfigIssue}); what a write did\n * ({@link ConfigWrite}); and what it is read by ({@link ConfigPlatform}).\n * Types only, with no code.\n *\n * @packageDocumentation\n * @module index\n */\nimport type { StandardJSONSchemaV1, StandardSchemaV1, StandardTypedV1 } from '@standard-schema/spec'\nimport type { FilesPlatform } from '@wtf/platform-fs/files'\n\n/**\n * The section of one tool, by its key `K` and its value `V`, as `ConfigSection<'vite', ViteOptions>`.\n * A section is optional: a project configures the tools it chooses.\n */\nexport type ConfigSection<K extends string, V> = { readonly [P in K]?: V }\n\n/**\n * The sections of the schemas `S`, each by its name: the input type of each schema, as\n * `SectionsOf<{ vite: typeof viteSchema }>` is `{ vite?: ViteOptions }`. A code config is typed by\n * it with `defineConfig` of ./define.\n */\nexport type SectionsOf<S extends Readonly<Record<string, StandardTypedV1>>> = {\n readonly [K in keyof S]?: StandardTypedV1.InferInput<S[K]>\n}\n\n/**\n * The configuration of a project under a namespace: the sections `S`, each checked by its type;\n * the `$schema` a JSON file names its schema by; and any other section, of a tool not named, as it\n * is. A tool reads its own section, and no other.\n *\n * ```ts\n * const config: NamespaceConfig<{ vite?: { compress?: false } }> = { vite: { compress: false } }\n * ```\n */\nexport type NamespaceConfig<S extends object = Record<never, never>> = S & {\n /** The JSON Schema of a JSON file of the configuration, as an editor reads it. */\n readonly $schema?: string\n readonly [section: string]: unknown\n}\n\n/**\n * The names the configuration of a namespace is looked for by, each a tool's to give: the files at\n * the root of the project, the key of its package.json, and the prefix of the environment's\n * variables over it. Of the namespace `wtf`, by default, `wtf.config.mjs`, `wtf.config.js`,\n * `wtf.config.ts` and `wtf.config.json`, the `wtf` key, and the variables `WTF_*`.\n */\nexport type ConfigNames = {\n /**\n * The files it can be in, in the order the first found is used, each of code (`.mjs`, `.js`,\n * `.ts`, `.cjs`, `.mts` or `.cts`) or of JSON (`.json`). The key of package.json comes last.\n */\n readonly files?: readonly string[]\n /** The key of package.json that holds it when no file does: the namespace by default. */\n readonly key?: string\n /**\n * The name the environment's variables over it start with: the key by default, so `wtf` is\n * `WTF_`, and `WTF_VITE_COMPRESS` sets `wtf.vite.compress`.\n */\n readonly env?: string\n}\n\n/** A file of the configuration found at the root of a project: one of its files, or package.json. */\nexport type ConfigSource = {\n /** Its name, as the names give it, or `package.json`. */\n readonly file: string\n /** Its absolute path. */\n readonly path: string\n}\n\n/**\n * Where a project's configuration is: the root of the project, the key of package.json, and each\n * file of it found there, in the order of its files, then package.json. The first is used; the\n * others are ignored.\n */\nexport type LocatedConfig = {\n readonly root: string\n /** The key of package.json, which a path of the configuration starts from: `wtf.vite.compress`. */\n readonly key: string\n readonly sources: readonly ConfigSource[]\n}\n\n/**\n * The configuration a tool's package gives under the project's, as its own defaults: each section\n * the project gives is merged over it, value by value, as `sectionOf` of ./section reads it.\n */\nexport type ConfigDefaults = {\n /** The object, of the sections of the namespace. */\n readonly config: NamespaceConfig\n /** The file it is in, by its absolute path, which an error of a section of it names. */\n readonly path: string\n}\n\n/**\n * The environment a tool reads the configuration with: the prefix of the variables over it, as\n * `WTF_`; each of those that is set and not empty, by its name; and the whole environment, in\n * `values`, which the placeholders `${env:NAME}` of a section are taken from. Only `sectionOf` of\n * ./section reads `values`: nothing shows or writes it.\n */\nexport type ConfigEnvironment = {\n readonly prefix: string\n readonly variables: Readonly<Record<string, string>>\n readonly values: Readonly<Record<string, string | undefined>>\n}\n\n/** A project's configuration, as a tool reads it. */\nexport type ResolvedConfig = {\n /** Its namespace. */\n readonly namespace: string\n /** The root of the project, where it was looked for. */\n readonly root: string\n /** The key of package.json it was looked for in, which a path of it starts from. */\n readonly key: string\n /** The object, `{}` when no file holds one. */\n readonly config: NamespaceConfig\n /** The file it came from, or `undefined` when no file holds one. */\n readonly source: ConfigSource | undefined\n /** The other files found, which are ignored, as only the first is used. */\n readonly ignored: readonly ConfigSource[]\n /** The configuration of the tool's package under the project's, when the tool gives one. */\n readonly defaults?: ConfigDefaults | undefined\n /**\n * The environment the tool gave, which a section is read with: its variables over the project's\n * configuration, and the values its placeholders are taken from. None when no environment was\n * given: then a placeholder names a variable that is not set.\n */\n readonly environment?: ConfigEnvironment | undefined\n}\n\n/** A path in the configuration, by its keys from the top: `['vite', 'compress']`. A key of digits\n * is an index of a list. */\nexport type ConfigPath = readonly string[]\n\n/** What is wrong with a value of a section: where it is, by its path in the section, and why. */\nexport type ConfigIssue = {\n readonly path: ConfigPath\n readonly message: string\n}\n\n/** A JSON Schema, as the object of its keywords, or `true` or `false`. */\nexport type JsonSchema = { readonly [keyword: string]: unknown } | boolean\n\n/** A function that checks a section: what is wrong with it, none when it is valid. */\nexport type ValidateSection = (\n value: unknown\n) => readonly ConfigIssue[] | Promise<readonly ConfigIssue[]>\n\n/**\n * What a tool checks its section by: a Standard Schema, as a preset's `./schema` exports one, or\n * zod's, whose output is what the section reads as; a JSON Schema of draft 2020-12, or a Standard\n * JSON Schema, which ajv checks; or a function of its own.\n */\nexport type SectionSchema<T = unknown> =\n | StandardSchemaV1<unknown, T>\n | StandardJSONSchemaV1<unknown, T>\n | JsonSchema\n | ValidateSection\n\n/**\n * What a write did: where, at which path, the value there before and after it, and whether it\n * changed the file, or made it.\n */\nexport type ConfigWrite = {\n readonly root: string\n /** The key of package.json, which a path of the configuration starts from. */\n readonly key: string\n /** The file written, or `undefined` when nothing was there to unset. */\n readonly source: ConfigSource | undefined\n /** The other files of the configuration found, which a reader ignores. */\n readonly ignored: readonly ConfigSource[]\n readonly path: ConfigPath\n /** The value at the path before the write, `undefined` when there was none. */\n readonly previous: unknown\n /** The value at the path after the write, `undefined` when it was unset. */\n readonly value: unknown\n /** Whether the file was written: false when the value was already so. */\n readonly changed: boolean\n /** Whether the file, or the key of package.json, was made by the write. */\n readonly created: boolean\n}\n\n/** What imports a file of code, as `wtf.config.ts`, by its absolute path: its module, whose\n * `default` is the configuration. */\nexport type ImportModule = (path: string) => Promise<unknown>\n\n/**\n * What the configuration is read and written by: the platform's storage, whose\n * `getDirectory()` is the root of its file system, its paths, and its working folder, as\n * `@wtf/platform-fs/files` reads a platform's files. A `Platform` of `@wtf/platform` is one, as\n * `nodePlatform()` of `@wtf/platform-node/platform` makes Node's.\n */\nexport type ConfigPlatform = FilesPlatform\n"]}
package/dist/load.d.ts CHANGED
@@ -1,10 +1,9 @@
1
1
  /**
2
2
  * A project's configuration, as a tool reads it: {@link loadConfig}, the object of the first file
3
3
  * of it found at the root of the project, of code or of JSON, the file it came from, and the
4
- * others found, which are ignored; {@link loadConfigSync}, the same of a JSON file or package.json
5
- * alone, for a tool that reads its config synchronously; {@link ignoredWarning}, what to say of
6
- * the files ignored; and {@link importFileModule}, which imports a configuration of code, as
7
- * `wtf.config.ts`, by its file URL, as Node imports a module.
4
+ * others found, which are ignored; {@link ignoredWarning}, what to say of the files ignored; and
5
+ * {@link importFileModule}, which imports a configuration of code, as `wtf.config.ts`, by its file
6
+ * URL, as Node imports a module.
8
7
  *
9
8
  * Each reads by the platform it is given, and nothing of the process: its files, its paths, the
10
9
  * folder it works in, which the project is looked for from, and its environment, whose variables
@@ -24,8 +23,7 @@
24
23
  * @packageDocumentation
25
24
  */
26
25
  import type { Platform } from '@wtf/platform';
27
- import type { Dirs } from '@wtf/platform/dirs';
28
- import type { ConfigDefaults, ConfigPlatform, ConfigSyncPlatform, ImportModule, ResolvedConfig } from './index.ts';
26
+ import type { ConfigDefaults, ConfigPlatform, ImportModule, ResolvedConfig } from './index.ts';
29
27
  import { type LocateNames } from './locate.ts';
30
28
  /** How a configuration is read, apart from the platform: the folder of the project, its names, and
31
29
  * the defaults of the tool's package. */
@@ -43,22 +41,14 @@ export type LoadLayers = LocateNames & {
43
41
  readonly defaults?: ConfigDefaults;
44
42
  };
45
43
  /**
46
- * What a configuration is read by asynchronously: the platform's files, its paths and its working
44
+ * What a configuration is read by: the platform's files, its paths and its working
47
45
  * folder ({@link ConfigPlatform}), and its environment, `env`, of which the variables of the prefix
48
46
  * of the names, as `WTF_`, are kept, and a section is read with them over it, and its placeholders
49
47
  * `${env:NAME}` taken from the whole (`sectionOf` of ./section). A `Platform` of `@wtf/platform` is
50
48
  * one.
51
49
  */
52
50
  export type LoadPlatform = ConfigPlatform & Pick<Platform, 'env'>;
53
- /**
54
- * What a configuration is read by synchronously: the platform's paths and its files, read
55
- * synchronously ({@link ConfigSyncPlatform}), its working folder, and its environment, as
56
- * {@link LoadPlatform} has them. `nodeSyncPlatform()` of ./node adds Node's files to a platform.
57
- */
58
- export type LoadSyncPlatform = ConfigSyncPlatform & Pick<Platform, 'env'> & {
59
- readonly dirs: Pick<Dirs, 'cwd'>;
60
- };
61
- /** How a configuration is read asynchronously. */
51
+ /** How a configuration is read. */
62
52
  export type LoadOptions = LoadLayers & {
63
53
  /** The platform it is read by ({@link LoadPlatform}). */
64
54
  readonly platform: LoadPlatform;
@@ -69,11 +59,6 @@ export type LoadOptions = LoadLayers & {
69
59
  */
70
60
  readonly importModule?: ImportModule;
71
61
  };
72
- /** How a configuration is read synchronously. */
73
- export type LoadSyncOptions = LoadLayers & {
74
- /** The platform it is read by synchronously ({@link LoadSyncPlatform}). */
75
- readonly platform: LoadSyncPlatform;
76
- };
77
62
  /**
78
63
  * What imports the module of the file at an absolute path, by its file URL, as the paths `path`
79
64
  * give it: what imports a configuration of code by default, `wtf.config.ts` among them, whose types
@@ -93,14 +78,6 @@ export declare const importFileModule: (path: Pick<ConfigPlatform["path"], "toFi
93
78
  * holds no object, or a module that fails to load, is an {@link InvalidConfigFileError}.
94
79
  */
95
80
  export declare function loadConfig({ importModule, platform, ...options }: LoadOptions): Promise<ResolvedConfig>;
96
- /**
97
- * The configuration of the project in `folder`, the working folder of the platform by default, with
98
- * the environment of the platform over it, as {@link loadConfig} reads it, read synchronously:
99
- * of a JSON file of the names, `wtf.config.json` by default, or the key of package.json, `wtf` by
100
- * default, for a tool that loads its own config synchronously. A configuration of code in use, as
101
- * `wtf.config.ts`, is a {@link SyncConfigInCodeError}, as importing it is asynchronous.
102
- */
103
- export declare function loadConfigSync({ platform, ...options }: LoadSyncOptions): ResolvedConfig;
104
81
  /**
105
82
  * What to say of the files of the configuration that are ignored, as a tool warns: `undefined`
106
83
  * when none is.
package/dist/load.js CHANGED
@@ -7,9 +7,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
7
7
  return path;
8
8
  };
9
9
  import { envPrefixOf, variablesOf } from "./env.js";
10
- import { InvalidConfigFileError, SyncConfigInCodeError } from "./errors.js";
11
- import { filesOf, isObject, kindOf, manifestOf, readAsync, readSync, textOf } from "./files.js";
12
- import { configNamesOf, jsonFilesOf, locateConfig, locateConfigSync } from "./locate.js";
10
+ import { InvalidConfigFileError } from "./errors.js";
11
+ import { filesOf, isObject, kindOf, manifestOf, readAsync, textOf } from "./files.js";
12
+ import { configNamesOf, locateConfig } from "./locate.js";
13
13
  /**
14
14
  * What imports the module of the file at an absolute path, by its file URL, as the paths `path`
15
15
  * give it: what imports a configuration of code by default, `wtf.config.ts` among them, whose types
@@ -88,28 +88,6 @@ export async function loadConfig({ importModule, platform, ...options }) {
88
88
  : await readAsync(configOfJson(source, key), filesOf(platform));
89
89
  return { namespace, root, key, config, source, ignored, ...layers };
90
90
  }
91
- /**
92
- * The configuration of the project in `folder`, the working folder of the platform by default, with
93
- * the environment of the platform over it, as {@link loadConfig} reads it, read synchronously:
94
- * of a JSON file of the names, `wtf.config.json` by default, or the key of package.json, `wtf` by
95
- * default, for a tool that loads its own config synchronously. A configuration of code in use, as
96
- * `wtf.config.ts`, is a {@link SyncConfigInCodeError}, as importing it is asynchronous.
97
- */
98
- export function loadConfigSync({ platform, ...options }) {
99
- const { namespace } = configNamesOf(options);
100
- const { root, key, sources } = locateConfigSync(options.folder ?? platform.dirs.cwd, {
101
- platform,
102
- ...locateNamesOf(options)
103
- });
104
- const [source, ...ignored] = sources;
105
- const layers = layersOf(options, platform.env);
106
- if (source === undefined)
107
- return { namespace, root, key, config: {}, source: undefined, ignored: [], ...layers };
108
- if (kindOf(source.file) === 'code')
109
- throw new SyncConfigInCodeError(source.path, { files: jsonFilesOf(options), key });
110
- const config = readSync(configOfJson(source, key), platform.files);
111
- return { namespace, root, key, config, source, ignored, ...layers };
112
- }
113
91
  /**
114
92
  * What to say of the files of the configuration that are ignored, as a tool warns: `undefined`
115
93
  * when none is.