@clipboard-health/config 0.9.0 → 0.10.1

package/README.md

@@ -1,6 +1,40 @@
 # @clipboard-health/config <!-- omit from toc -->
 
-Type-safe static configuration management: a pure function to resolve, validate against a Zod schema, and freeze configuration values.
+<embedex source="packages/config/examples/config.md">
+
+Type-safe static configuration management: a pure function to resolve, validate against a Zod
+schema, and freeze configuration values.
+
+Configuration values resolve in order from highest precedence to lowest:
+
+1. Environment variables
+   - Resolved converting configuration path from camelCase to UPPER_SNAKE. For example, the `{
+myApi: { port: 3000 } }` configuration resolves to `MY_API_PORT`.
+2. Environment-specific overrides, {@link ConfigValue.overrides}
+3. Default values, {@link ConfigValue.defaultValue}
+
+Supported configuration value types:
+
+- bigint
+- boolean
+- date
+- number
+- string
+- arrays and nested objects using the above types
+
+To override arrays with environment variables, use stringified JSON arrays, e.g. `["a","b"]`.
+
+**IMPORTANT**: To avoid runtime errors:
+
+1. Environment variables are strings, so use `z.coerce` Zod types for those you plan to override.
+   Note that `z.coerce.boolean()` coerces any truthy value to `true`. To restrict to `"true" |
+"false"`, use the `booleanString` schema from `@clipboard-health/contract-core`.
+2. The resulting configuration is deeply frozen and will throw a runtime error if you attempt to
+   modify it. The actual return type is `ReadonlyDeep<SchemaT>`, but the library returns a
+   `Readonly<SchemaT>` because the former prevents clients from passing configuration values to
+   functions that don't explicitly accept `readonly` types.
+
+</embedex>
 
 ## Table of contents <!-- omit from toc -->
 
@@ -19,13 +53,9 @@ npm install @clipboard-health/config
 
 ### Type-safe configuration
 
-See the [createConfig.ts](./src/lib/createConfig.ts) TypeDoc comment.
+<embedex source="packages/config/examples/config.ts">
 
-A usage example:
-
-<!-- prettier-ignore -->
 ```ts
-// packages/config/examples/config.ts
 import { ok } from "node:assert/strict";
 
 import { createConfig } from "@clipboard-health/config";
@@ -89,9 +119,10 @@ try {
 } finally {
   process.env = { ...original };
 }
-
 ```
 
+</embedex>
+
 ## Local development commands
 
 See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@clipboard-health/config",
   "description": "Type-safe static configuration management: a pure function to resolve, validate against a Zod schema, and freeze configuration values.",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
   "dependencies": {
-    "@clipboard-health/util-ts": "2.13.0",
+    "@clipboard-health/util-ts": "2.14.1",
     "decamelize": "5.0.1",
     "dotenv": "16.4.5",
     "tslib": "2.8.0",

package/src/lib/createConfig.d.ts

@@ -1,16 +1,20 @@
 import { type ConfigParams } from "./types";
 /**
+ * <embedex source="packages/config/examples/config.md">
+ *
  * Type-safe static configuration management: a pure function to resolve, validate against a Zod
  * schema, and freeze configuration values.
  *
  * Configuration values resolve in order from highest precedence to lowest:
+ *
  * 1. Environment variables
  *    - Resolved converting configuration path from camelCase to UPPER_SNAKE. For example, the `{
- *      myApi: { port: 3000 } }` configuration resolves to `MY_API_PORT`.
+ * myApi: { port: 3000 } }` configuration resolves to `MY_API_PORT`.
  * 2. Environment-specific overrides, {@link ConfigValue.overrides}
  * 3. Default values, {@link ConfigValue.defaultValue}
  *
  * Supported configuration value types:
+ *
  * - bigint
  * - boolean
  * - date
@@ -21,17 +25,21 @@ import { type ConfigParams } from "./types";
  * To override arrays with environment variables, use stringified JSON arrays, e.g. `["a","b"]`.
  *
  * **IMPORTANT**: To avoid runtime errors:
+ *
  * 1. Environment variables are strings, so use `z.coerce` Zod types for those you plan to override.
  *    Note that `z.coerce.boolean()` coerces any truthy value to `true`. To restrict to `"true" |
- *    "false"`, use the `booleanString` schema from `@clipboard-health/contract-core`.
+ * "false"`, use the `booleanString` schema from `@clipboard-health/contract-core`.
  * 2. The resulting configuration is deeply frozen and will throw a runtime error if you attempt to
  *    modify it. The actual return type is `ReadonlyDeep<SchemaT>`, but the library returns a
  *    `Readonly<SchemaT>` because the former prevents clients from passing configuration values to
  *    functions that don't explicitly accept `readonly` types.
  *
+ * </embedex>
+ *
  * @example
+ * <embedex source="packages/config/examples/config.ts">
+ *
  * ```ts
- * // packages/config/examples/config.ts
  * import { ok } from "node:assert/strict";
  *
  * import { createConfig } from "@clipboard-health/config";
@@ -95,9 +103,10 @@ import { type ConfigParams } from "./types";
  * } finally {
  *   process.env = { ...original };
  * }
- *
  * ```
  *
+ * </embedex>
+ *
  * @throws {Error} When configuration values fail schema validation
  * @returns A deeply frozen configuration object matching the provided schema
  */

package/src/lib/createConfig.js

@@ -8,17 +8,21 @@ const zod_validation_error_1 = require("zod-validation-error");
 const resolver_1 = require("./internal/resolver");
 dotenv_1.default.config();
 /**
+ * <embedex source="packages/config/examples/config.md">
+ *
  * Type-safe static configuration management: a pure function to resolve, validate against a Zod
  * schema, and freeze configuration values.
  *
  * Configuration values resolve in order from highest precedence to lowest:
+ *
  * 1. Environment variables
  *    - Resolved converting configuration path from camelCase to UPPER_SNAKE. For example, the `{
- *      myApi: { port: 3000 } }` configuration resolves to `MY_API_PORT`.
+ * myApi: { port: 3000 } }` configuration resolves to `MY_API_PORT`.
  * 2. Environment-specific overrides, {@link ConfigValue.overrides}
  * 3. Default values, {@link ConfigValue.defaultValue}
  *
  * Supported configuration value types:
+ *
  * - bigint
  * - boolean
  * - date
@@ -29,17 +33,21 @@ dotenv_1.default.config();
  * To override arrays with environment variables, use stringified JSON arrays, e.g. `["a","b"]`.
  *
  * **IMPORTANT**: To avoid runtime errors:
+ *
  * 1. Environment variables are strings, so use `z.coerce` Zod types for those you plan to override.
  *    Note that `z.coerce.boolean()` coerces any truthy value to `true`. To restrict to `"true" |
- *    "false"`, use the `booleanString` schema from `@clipboard-health/contract-core`.
+ * "false"`, use the `booleanString` schema from `@clipboard-health/contract-core`.
  * 2. The resulting configuration is deeply frozen and will throw a runtime error if you attempt to
  *    modify it. The actual return type is `ReadonlyDeep<SchemaT>`, but the library returns a
  *    `Readonly<SchemaT>` because the former prevents clients from passing configuration values to
  *    functions that don't explicitly accept `readonly` types.
  *
+ * </embedex>
+ *
  * @example
+ * <embedex source="packages/config/examples/config.ts">
+ *
  * ```ts
- * // packages/config/examples/config.ts
  * import { ok } from "node:assert/strict";
  *
  * import { createConfig } from "@clipboard-health/config";
@@ -103,9 +111,10 @@ dotenv_1.default.config();
  * } finally {
  *   process.env = { ...original };
  * }
- *
  * ```
  *
+ * </embedex>
+ *
  * @throws {Error} When configuration values fail schema validation
  * @returns A deeply frozen configuration object matching the provided schema
  */

package/src/lib/createConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"createConfig.js","sourceRoot":"","sources":["../../../../../packages/config/src/lib/createConfig.ts"],"names":[],"mappings":";;AA+GA,oCAeC;;AA9HD,uDAAuD;AACvD,4DAA4B;AAC5B,+DAAoD;AAEpD,kDAA8C;AAG9C,gBAAM,CAAC,MAAM,EAAE,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqGG;AACH,SAAgB,YAAY,CAG1B,MAAqD;IACrD,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAA,kBAAO,EAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7F,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAA,mCAAY,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE;YAC3F,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAA,oBAAU,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"createConfig.js","sourceRoot":"","sources":["../../../../../packages/config/src/lib/createConfig.ts"],"names":[],"mappings":";;AAwHA,oCAeC;;AAvID,uDAAuD;AACvD,4DAA4B;AAC5B,+DAAoD;AAEpD,kDAA8C;AAG9C,gBAAM,CAAC,MAAM,EAAE,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8GG;AACH,SAAgB,YAAY,CAG1B,MAAqD;IACrD,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAA,kBAAO,EAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC7F,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,oCAAoC,IAAA,mCAAY,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE;YAC3F,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAA,oBAAU,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}