@clipboard-health/config 0.1.0 → 0.2.0

package/README.md

@@ -19,7 +19,76 @@ npm install @clipboard-health/config
 
 ### Type-safe configuration
 
-For additional detail, see the `createConfig` documentation.
+The TypeDoc comment for the `createConfig` function:
+
+<!-- prettier-ignore -->
+```ts
+// ./src/lib/createConfig.ts
+
+import { fromZodError } from "zod-validation-error";
+
+import { deepFreeze } from "./internal/deepFreeze";
+import { resolve } from "./internal/resolver";
+import { type ConfigParams } from "./types";
+
+/**
+ * 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
+ *    {@link https://github.com/ClipboardHealth/core-utils/blob/main/packages/contract-core/src/lib/schemas/booleanString.ts
+ *    `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.
+ *
+ * @includeExample ./packages/config/examples/config.ts
+ * @see [Usage example](../../examples/config.ts)
+ *
+ * @throws {Error} When configuration values fail schema validation
+ * @returns A deeply frozen configuration object matching the provided schema
+ */
+export function createConfig<
+  const SchemaT extends Record<string, unknown>,
+  const EnvironmentT extends readonly string[],
+>(params: Readonly<ConfigParams<SchemaT, EnvironmentT>>): Readonly<SchemaT> {
+  const { config, environment, schema } = params;
+  const { current } = environment;
+
+  const result = schema.safeParse(resolve({ config, environment: current, path: [], schema }));
+  if (!result.success) {
+    throw new Error(`Configuration validation failed: ${fromZodError(result.error).toString()}`, {
+      cause: result.error,
+    });
+  }
+
+  return deepFreeze(result.data);
+}
+
+```
+
+A usage example:
 
 <!-- prettier-ignore -->
 ```ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.1.0",
+  "version": "0.2.0",
   "dependencies": {
     "decamelize": "5.0.1",
     "tslib": "2.8.0",

package/src/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./lib/config";
+export * from "./lib/createConfig";
 export * from "./lib/types";

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./lib/config"), exports);
+tslib_1.__exportStar(require("./lib/createConfig"), exports);
 tslib_1.__exportStar(require("./lib/types"), exports);
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/config/src/index.ts"],"names":[],"mappings":";;;AAAA,uDAA6B;AAC7B,sDAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/config/src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,sDAA4B"}

package/src/lib/{config.js → createConfig.js}

@@ -47,8 +47,10 @@ function createConfig(params) {
     const { current } = environment;
     const result = schema.safeParse((0, resolver_1.resolve)({ config, environment: current, path: [], schema }));
     if (!result.success) {
-        throw new Error((0, zod_validation_error_1.fromZodError)(result.error).toString(), { cause: result.error });
+        throw new Error(`Configuration validation failed: ${(0, zod_validation_error_1.fromZodError)(result.error).toString()}`, {
+            cause: result.error,
+        });
     }
     return (0, deepFreeze_1.deepFreeze)(result.data);
 }
-//# sourceMappingURL=config.js.map
+//# sourceMappingURL=createConfig.js.map

package/src/lib/createConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createConfig.js","sourceRoot":"","sources":["../../../../../packages/config/src/lib/createConfig.ts"],"names":[],"mappings":";;AA4CA,oCAeC;AA3DD,+DAAoD;AAEpD,sDAAmD;AACnD,kDAA8C;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,uBAAU,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}

package/src/lib/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../packages/config/src/lib/config.ts"],"names":[],"mappings":";;AA4CA,oCAaC;AAzDD,+DAAoD;AAEpD,sDAAmD;AACnD,kDAA8C;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;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,IAAA,mCAAY,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,IAAA,uBAAU,EAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC"}