xenv-config 2.1.7 → 3.0.0

package/README.md

@@ -1,7 +1,16 @@
-[![NPM version][npm-image]][npm-url]
-
 # xenv-config
 
+[![License][license-image]][license-url]
+[![build][build-image]][build-url]
+
+[![Downloads][downloads-image]][downloads-url]
+
+[![npm badge][npm-badge-png]][package-url]
+
+- [API reference](https://fynjs.pages.dev/api/modules/xenv-config) - TypeDoc
+- [Markdown reference](docs/reference.md) - the full API and runtime behavior in one file. Also ships in the package.
+- [GitHub](https://github.com/jchip/fynjs/tree/main/packages/xenv-config)
+
 Load config from env, user config, or default spec.
 
 ## Install
@@ -36,7 +45,7 @@ expect(config.__$trace__).to.deep.equal({
   fooOption: { src: "default" },
   barOption: { src: "env", name: "BAR_OPTION" },
   zooOption: { src: "option" },
-  jsonOption: { src: "env,option" }
+  jsonOption: { src: "env,option", name: "JSON_OPTION" }
 });
 ```
 
@@ -59,6 +68,7 @@ Returns `config` object.
 
 - `_env` - Object that represents environment instead of `process.env`
 - `merge` - function to merge `json` object instead of using `Object.assign`
+- `sources` - ordered list of sources to check, from `env`, `option` and `default`. Default is `["env", "option"]`, and `default` is always checked last. An unknown name throws.
 
 ## Spec
 
@@ -104,8 +114,9 @@ When loading from `env`, in order to indicate what value to convert the string i
 - `boolean` - (boolean) convert with `x === "true" || x === "yes" || x === "1" || x === "on"`
 - `truthy` - (boolean from truthy check) convert with `!!x`
 - `json` - (JSON) parsed with `JSON.parse`
+- `array` - (array) parsed with `JSON.parse`. The first source found wins, and nothing is merged.
 
-> If `type` is not specified, and `default` exist and not a function, then `typeof default` will be used.
+> If `type` is not specified, and `default` exist and not a function, then `typeof default` will be used. A `null` default is `string`, and an array default is `array`: env is parsed with `JSON.parse`, and the first source found wins with no merging.
 
 ### Trace
 
@@ -123,6 +134,7 @@ The hidden field `__$trace__` contain data for each key to indicate where its va
 - Values from all three sources are combined in the following order `env`, `option`, `default`.
 - It uses `Object.assign` to combine values unless you pass in a `merge` function in options. For example, merge from `lodash`.
 - `trace.src` would be a comma separate list of them. For example, `"env,option"`, `"env,option,default"`, or `"option,default"`
+- When env contributed, the trace also has `name`, the env var name used.
 
 ## Option Orders
 
@@ -133,5 +145,11 @@ The order of source to check are:
 3.  The default value from spec if it's declared
 4.  Nothing
 
-[npm-image]: https://badge.fury.io/js/xenv-config.svg
-[npm-url]: https://npmjs.org/package/xenv-config
+[license-image]: https://img.shields.io/npm/l/xenv-config.svg
+[license-url]: LICENSE
+[build-image]: https://github.com/jchip/fynjs/actions/workflows/ci.yml/badge.svg
+[build-url]: https://github.com/jchip/fynjs/actions/workflows/ci.yml
+[downloads-image]: https://img.shields.io/npm/dm/xenv-config.svg
+[downloads-url]: https://npm-stat.com/charts.html?package=xenv-config
+[npm-badge-png]: https://nodei.co/npm/xenv-config.png?downloads=true&stars=true
+[package-url]: https://npmjs.com/package/xenv-config

package/dist/index.js

@@ -9,7 +9,8 @@ const typeGetters = {
         return lower === "true" || lower === "yes" || lower === "1" || lower === "on";
     },
     truthy: x => !!x,
-    json: x => JSON.parse(x)
+    json: x => JSON.parse(x),
+    array: x => JSON.parse(x)
 };
 const getEnvName = (optKey, opt, env) => {
     if (!Object.prototype.hasOwnProperty.call(opt, "env"))
@@ -40,9 +41,17 @@ const xenvConfig = (spec, userConfig, options) => {
     userConfig = userConfig || {};
     const trace = {};
     const getType = (opt) => {
-        const tod = Object.prototype.hasOwnProperty.call(opt, "default") && typeof opt.default;
-        const type = opt.type || (tod !== "function" && tod) || "string";
-        return type === "object" ? "json" : type;
+        if (opt.type)
+            return opt.type === "object" ? "json" : opt.type;
+        if (!Object.prototype.hasOwnProperty.call(opt, "default"))
+            return "string";
+        // typeof says "object" for both, but neither is a json object to merge into
+        if (opt.default === null)
+            return "string";
+        if (Array.isArray(opt.default))
+            return "array";
+        const tod = typeof opt.default;
+        return tod === "object" ? "json" : tod === "function" ? "string" : tod;
     };
     const getGetter = (opt) => {
         const type = getType(opt);
@@ -78,9 +87,13 @@ const xenvConfig = (spec, userConfig, options) => {
             return undefined;
         }
     };
-    const sources = (options && options.sources) || ["env", "option"];
-    sources.push("default");
+    const sources = [...((options && options.sources) || ["env", "option"]), "default"];
+    const badSource = sources.find(s => !Object.prototype.hasOwnProperty.call(getters, s));
+    if (badSource !== undefined) {
+        throw new Error(`xenv-config: unknown source "${badSource}"; valid sources are ${Object.keys(getters).join(", ")}`);
+    }
     const config = Object.keys(spec).reduce((cfg, k) => {
+        var _a;
         const opt = spec[k];
         const type = getType(opt);
         let found;
@@ -90,8 +103,9 @@ const xenvConfig = (spec, userConfig, options) => {
         else {
             const mapped = sources.map(s => getters[s](opt, k)).filter((x) => Boolean(x));
             if (mapped.length > 0) {
+                const name = (_a = mapped.find(x => x.trace.name)) === null || _a === void 0 ? void 0 : _a.trace.name;
                 found = {
-                    trace: { src: mapped.map(x => x.trace.src).join(",") },
+                    trace: { src: mapped.map(x => x.trace.src).join(","), ...(name && { name }) },
                     value: merge.apply(null, [{}].concat(mapped.map(x => x.value).reverse()))
                 };
             }

package/docs/reference.md

@@ -0,0 +1,238 @@
+# xenv-config reference
+
+`xenv-config` builds a config object from a spec. Each key is resolved from an env var, a user config object, or a default, and every resolved key gets a trace record that says where it came from. No runtime dependencies. ESM only (`"type": "module"`).
+
+## Imports
+
+```js
+import xenvConfig from "xenv-config";
+```
+
+```ts
+import xenvConfig, {
+  type XenvConfigTrace,
+  type XenvConfigSpecOption,
+  type XenvConfigSpec,
+  type XenvConfigEnv,
+  type XenvConfigUserConfig,
+  type XenvConfigMergeFn,
+  type XenvConfigOptions,
+  type XenvConfigResult
+} from "xenv-config";
+```
+
+The only runtime export is the default export, the function `xenvConfig`. There are no named runtime exports and no subpaths (only `xenv-config/package.json`). The package has no CommonJS build, so `require("xenv-config")` as shown in the README does not apply to this version; use `import`.
+
+Type-only exports: `XenvConfigTrace`, `XenvConfigSpecOption`, `XenvConfigSpec`, `XenvConfigEnv`, `XenvConfigUserConfig`, `XenvConfigMergeFn`, `XenvConfigOptions`, `XenvConfigResult`.
+
+Not exported: the internal `typeGetters` table, `getEnvName` and `FoundValue`.
+
+## `xenvConfig(spec, userConfig?, options?)`
+
+```ts
+const xenvConfig: <T = Record<string, unknown>>(
+  spec: XenvConfigSpec,
+  userConfig?: XenvConfigUserConfig,
+  options?: XenvConfigOptions
+) => XenvConfigResult<T>;
+```
+
+Resolves every key of `spec` and returns a new plain object. It is synchronous. `T` is only a type cast of the result; nothing is checked against it.
+
+| Parameter | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `spec` | `XenvConfigSpec` | required | Keys are iterated with `Object.keys(spec)`. Each value is a `XenvConfigSpecOption`. `undefined` or `null` `spec` throws a `TypeError`. |
+| `userConfig` | `XenvConfigUserConfig` | `{}` | Values supplied by the caller. A falsy value is replaced with `{}`. |
+| `options` | `XenvConfigOptions` | none | See `XenvConfigOptions`. |
+
+For each spec key the function:
+
+1. Finds a value by walking the sources (see Source order).
+2. If nothing is found, the key is skipped. It is absent from the result and from `__$trace__`. `post` is not called.
+3. Otherwise records the trace, runs `post` if the spec has one, and stores the result.
+
+### Source order
+
+Three sources exist, each named by a string:
+
+| Source name | Looks in | Found when | Trace |
+| --- | --- | --- | --- |
+| `"env"` | env object (`options._env` or `process.env`) | the spec has an own `env` property that names a variable that is an own property of the env object | `{ src: "env", name }` |
+| `"option"` | `userConfig` | `userConfig` has the key as an own property | `{ src: "option" }` |
+| `"default"` | spec | the spec has an own `default` property | `{ src: "default" }` |
+
+The default order is `["env", "option"]`, and `"default"` is appended last. For non-json types the first source that finds a value wins and the rest are not consulted.
+
+Reorder with `options.sources`. Example: `sources: ["option", "env"]` makes user config beat env. A source left out of the list is never consulted, except `"default"`, which is always appended. Rules:
+
+- Presence is tested with `Object.prototype.hasOwnProperty`. A present key whose value is `undefined`, `null`, `""` or `false` still counts as found. An empty string env var is found.
+- Inherited properties are not seen, on `spec` entries, `userConfig` and the env object.
+- `options.sources` is not mutated. `"default"` is appended to a copy.
+- A source name other than `"env"`, `"option"` or `"default"` throws before any key is resolved: `xenv-config: unknown source "<name>"; valid sources are env, option, default`.
+- The `"default"` entry: if `default` is a function it is called with no arguments and its return value is used. A function is never type-coerced.
+
+### Env lookup
+
+The env var name is chosen from `spec[key].env`, which is read only when `env` is an own property of the spec option.
+
+| `env` value | Name used |
+| --- | --- |
+| absent, `false`, `""` | none, the env source finds nothing |
+| `true` | the spec key itself |
+| `string` | that exact name |
+| `string[]` | the first name in the list that is an own property of the env object |
+
+If the chosen name is not an own property of the env object, the env source finds nothing. For an array, the match requires own presence, so a present empty string wins over a later name. An empty array finds nothing.
+
+When a name is found, the raw value is `env[name]`, then:
+
+1. If `envMap` is set and has the raw value as an own key, the mapped value is used as is. No type coercion is applied to it (`post` still runs). The raw value is used as a property key, so a non-string raw value is converted to a string for the lookup.
+2. Otherwise the raw value is coerced by the key's type (see Types).
+
+## `XenvConfigSpecOption`
+
+```ts
+interface XenvConfigSpecOption {
+  env?: string | string[] | boolean;
+  envMap?: Record<string, unknown>;
+  type?: string;
+  default?: unknown;
+  post?: (value: unknown, trace: XenvConfigTrace) => unknown;
+  [extra: string]: unknown;
+}
+```
+
+All fields are optional. A spec option with none of them resolves only from `userConfig`. Extra properties are allowed by the type and ignored by the code.
+
+| Field | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `env` | `string \| string[] \| boolean` | none | Which env var to read. See Env lookup. |
+| `envMap` | `Record<string, unknown>` | none | Maps raw env strings to final values. Only applies to the env source. Checked before type coercion. A hit skips coercion. |
+| `type` | `string` | inferred | How to coerce an env string. See Types. Applies only to env values, not to `userConfig` values or defaults, except that `json` also changes how all sources combine. |
+| `default` | `unknown` | none | Fallback value, or a function that returns it. Presence is tested as an own property, so `default: undefined` counts as a default and yields `undefined`. A function default is called each time `xenvConfig` runs. Not coerced. |
+| `post` | `(value, trace) => unknown` | none | Runs on the resolved value after a source is found. Its return value is stored in the result. Receives the same trace object that is stored in `__$trace__`, so mutating it changes the stored trace. Not called when the key is not found. Runs for every source, including `option` and `default`. |
+
+## Types
+
+The type for a key is decided by `type` first, then inference:
+
+1. `opt.type` if truthy.
+2. Else, when `default` is an own property, inferred from it (see the table below).
+3. Else `"string"`.
+
+Then `"object"` is rewritten to `"json"`. A type name not listed below falls back to the `string` converter. Only `"json"` (after the rewrite) triggers merge behavior.
+
+| Type | Converter for an env value `x` | Notes |
+| --- | --- | --- |
+| `string` | `` `${x}` `` | Also the fallback for any unknown type name. |
+| `number` | `parseInt(x, 10)` | Integer. A non-numeric string gives `NaN` (JSON serializes it as `null`). `"1.9"` gives `1`. |
+| `float` | `parseFloat(x)` | |
+| `boolean` | lower-cased `x` is `"true"`, `"yes"`, `"1"` or `"on"` | Case-insensitive. Any other string gives `false`. A non-string raw value throws (see Errors). |
+| `truthy` | `!!x` | An empty string gives `false`. Any non-empty string, including `"false"` and `"0"`, gives `true`. |
+| `json` | `JSON.parse(x)` | Needs strict JSON. `{b:90}` is invalid. See json merging. |
+| `array` | `JSON.parse(x)` | Same parse as `json`, but first-wins like other types. Nothing is merged. |
+
+Inference from `default`:
+
+| `default` | Inferred type |
+| --- | --- |
+| a string | `string` |
+| a number | `number` (integer, `parseInt`) |
+| a boolean | `boolean` |
+| `null` | `string`. With no other source the value stays `null`. |
+| an array | `array`. The first source found wins and its value is returned as is. |
+| any other object | `json` |
+| `undefined` (own property set to `undefined`) | no converter of that name, so `string` conversion |
+| a function, or no `default` | `string` |
+
+An explicit `type` always overrides inference. `type: "object"` is accepted as an alias of `json`.
+
+### json merging
+
+When the resolved type is `json`, sources are not first-wins. Every source in `sources` (plus `"default"`) is consulted. All found values are merged.
+
+- The env value is parsed with `JSON.parse`, or taken from `envMap` when a mapping hits.
+- Merge call: `merge({}, ...values)` where values are ordered lowest priority first. With the default order the call is `merge({}, defaultValue, optionValue, envValue)`, so env wins, then option, then default. With a custom `sources`, the earlier a source is in the list, the higher its priority.
+- `merge` is `options.merge` or `Object.assign` (shallow). Pass a deep merge such as lodash `merge` for nested objects.
+- The result is always a new object, so defaults and user config are not mutated by the merge.
+- If no source finds a value, the key is skipped.
+- Values are merged as given. With `Object.assign`, a string merges as indexed characters, an array as indexed keys, and `null` or `undefined` is ignored.
+- The trace is `{ src: "<names joined by comma>" }`, in `sources` order, only for the sources that found a value, for example `"env,option,default"` or `"option,default"`. When env contributed, the trace also has `name`, the env var name used.
+
+## `XenvConfigOptions`
+
+```ts
+interface XenvConfigOptions {
+  _env?: XenvConfigEnv;
+  merge?: XenvConfigMergeFn;
+  sources?: string[];
+}
+```
+
+| Option | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `_env` | `XenvConfigEnv` (`Record<string, unknown>`) | `process.env` | Env-like object to read. Used when truthy. Values need not be strings, but `boolean` rejects non-strings. |
+| `merge` | `XenvConfigMergeFn` | `Object.assign` | Called as `merge.apply(null, [{}, ...values])` for json keys. Must return the merged object. Its return value is used as the key's value. |
+| `sources` | `string[]` | `["env", "option"]` | Ordered source names to consult. `"default"` is always appended, after your list. The array you pass is not changed. An unknown name throws. |
+
+## Result
+
+```ts
+type XenvConfigResult<T = Record<string, unknown>> = T & {
+  readonly __$trace__: Record<string, XenvConfigTrace>;
+};
+
+interface XenvConfigTrace {
+  src: string;
+  name?: string;
+}
+```
+
+The result is a plain `{}` with one property per resolved spec key, in spec key order.
+
+- `__$trace__` is defined with `Object.defineProperty`: `enumerable: false`, `writable: false`, `configurable: false`. It is skipped by `Object.keys`, spread, `JSON.stringify` and deep-equal checks, but is read as `config.__$trace__`. Copying the object with spread or `Object.assign` drops it.
+- `__$trace__[key]` exists exactly when `key` is in the result.
+- `trace.src` is `"env"`, `"option"`, `"default"`, or for json keys a comma-joined list of those.
+- `trace.name` is set when env provided the value, or contributed to a json value. It holds the env var name actually used, which is useful with an `env` array.
+- Values from `userConfig` and `default` are stored by reference, not cloned (non-json keys).
+
+```js
+const config = xenvConfig(
+  {
+    port: { env: ["APP_PORT", "PORT"], type: "number", default: 8080 },
+    debug: { env: true, type: "boolean" },
+    opts: { env: "OPTS", type: "json", default: { a: 1 } }
+  },
+  { opts: { b: 2 } },
+  { _env: { PORT: "9000", OPTS: '{"c":3}' } }
+);
+// config: { port: 9000, opts: { a: 1, b: 2, c: 3 } }  (debug is absent)
+// config.__$trace__:
+//   port: { src: "env", name: "PORT" }
+//   opts: { src: "env,option,default", name: "OPTS" }
+```
+
+## Errors
+
+Nothing is caught or wrapped. All errors are thrown synchronously from `xenvConfig`.
+
+| Condition | Error |
+| --- | --- |
+| `boolean` type and the env value (or `_env` value) is not a string | `AssertionError` from `node:assert`, message `xenv-config: [<key>] trying to convert non-string env value <value> to boolean.` |
+| `json` type and the env string is not valid JSON | `SyntaxError` from `JSON.parse` |
+| `sources` contains an unknown name | `Error`, message `xenv-config: unknown source "<name>"; valid sources are env, option, default`. Thrown before any key is resolved. |
+| `spec` is `undefined` or `null` | `TypeError` from `Object.keys` |
+| A function `default`, `post`, or `merge` throws | the error propagates unchanged |
+| `type: "json"` where `x` is not a string, such as a non-string `_env` value | `JSON.parse` coerces it to a string first, so it may parse or throw `SyntaxError` |
+
+Absence of a value is not an error. Missing keys are left out of the result.
+
+## Quirks
+
+- `type: "json"` needs strict JSON in env. The README example `JSON_OPTION = "{b:90}"` throws `SyntaxError`; use `'{"b":90}'`.
+- `number` env values that are not integers give `NaN` rather than an error. Empty env strings give `NaN`.
+- `envMap` hits are returned as is, with no coercion by `type`.
+- `userConfig` values and defaults are never coerced, only env values are.
+- A key present in the env object with value `undefined` counts as found. For `string` type it yields the string `"undefined"`.
+- The README says the order is env, option, default. The code matches this by default, but only `"default"` is forced last. The README does not document `options.sources`.
+- The README says `boolean` is `x === "true" || ...`. The code lower-cases first, so `"TRUE"` is `true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xenv-config",
-  "version": "2.1.7",
+  "version": "3.0.0",
   "description": "Load config from env, user config, or default spec",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -16,7 +16,7 @@
   "engines": {
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
-  "homepage": "https://github.com/jchip/fynjs/tree/main/packages/xenv-config",
+  "homepage": "https://fynjs.pages.dev/api/modules/xenv-config",
   "bugs": {
     "url": "https://github.com/jchip/fynjs/issues"
   },
@@ -43,7 +43,8 @@
   "author": "Joel Chen",
   "license": "Apache-2.0",
   "files": [
-    "dist"
+    "dist",
+    "docs/reference.md"
   ],
   "devDependencies": {
     "@types/lodash-es": "^4.17.12",
@@ -51,7 +52,7 @@
     "@vitest/coverage-v8": "^5.0.0",
     "lodash-es": "^4.18.1",
     "prettier": "^3.5.3",
-    "publish-util": "^3.1.7",
+    "publish-util": "^3.1.8",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"