@clipboard-health/config 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @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.
+
+## Table of contents <!-- omit from toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+  - [Type-safe configuration](#type-safe-configuration)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+npm install @clipboard-health/config
+```
+
+## Usage
+
+### Type-safe configuration
+
+For additional detail, see the `createConfig` documentation.
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/config.ts
+
+import { ok } from "node:assert/strict";
+
+import { createConfig } from "@clipboard-health/config";
+import { z } from "zod";
+
+const allowed = ["local", "development", "production"] as const;
+type Allowed = (typeof allowed)[number];
+
+function createEnvironmentConfig(current: Allowed) {
+  return createConfig({
+    config: {
+      baseUrl: {
+        defaultValue: "http://localhost:3000",
+        description: "Base URL for API requests",
+        overrides: {
+          development: "https://dev.example.com",
+          production: "https://api.example.com",
+        },
+      },
+      database: {
+        port: {
+          defaultValue: 5432,
+          description: "Database port",
+        },
+      },
+    },
+    environment: { allowed, current },
+    schema: z.object({
+      baseUrl: z.string().url(),
+      database: z.object({
+        // Use `z.coerce` to override with environment variables.
+        port: z.coerce.number().min(1024).max(65_535),
+      }),
+    }),
+  });
+}
+
+{
+  // Uses default values.
+  const config = createEnvironmentConfig("local");
+  ok(config.baseUrl === "http://localhost:3000");
+  ok(config.database.port === 5432);
+}
+
+{
+  // Uses baseUrl environment override.
+  const config = createEnvironmentConfig("development");
+  ok(config.baseUrl === "https://dev.example.com");
+  ok(config.database.port === 5432);
+}
+
+// Uses environment variable overrides.
+const original = { ...process.env };
+try {
+  process.env["BASE_URL"] = "https://staging.example.com";
+  process.env["DATABASE_PORT"] = "54320";
+
+  const config = createEnvironmentConfig("local");
+  ok(config.baseUrl === "https://staging.example.com");
+  ok(config.database.port === 54_320);
+} finally {
+  process.env = { ...original };
+}
+
+```
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "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",
+  "dependencies": {
+    "decamelize": "5.0.1",
+    "tslib": "2.8.0",
+    "zod": "3.23.8",
+    "zod-validation-error": "3.4.0"
+  },
+  "devDependencies": {
+    "@clipboard-health/contract-core": "0.2.0"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "embed": "embedme README.md"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

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

package/src/index.js

@@ -0,0 +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/types"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

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

package/src/lib/config.d.ts

@@ -0,0 +1,40 @@
+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 declare function createConfig<const SchemaT extends Record<string, unknown>, const EnvironmentT extends readonly string[]>(params: Readonly<ConfigParams<SchemaT, EnvironmentT>>): Readonly<SchemaT>;

package/src/lib/config.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createConfig = createConfig;
+const zod_validation_error_1 = require("zod-validation-error");
+const deepFreeze_1 = require("./internal/deepFreeze");
+const resolver_1 = require("./internal/resolver");
+/**
+ * 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
+ */
+function createConfig(params) {
+    const { config, environment, schema } = 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 });
+    }
+    return (0, deepFreeze_1.deepFreeze)(result.data);
+}
+//# sourceMappingURL=config.js.map

package/src/lib/config.js.map

@@ -0,0 +1 @@
+{"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"}

package/src/lib/internal/deepFreeze.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Recursively freezes an object and all its nested properties.
+ *
+ * @template T - Type of the object to freeze
+ * @param value - The object to freeze
+ * @param seen - Internal parameter to track circular references
+ * @returns A deeply frozen version of the input object.
+ */
+export declare function deepFreeze<T extends object>(value: T, seen?: WeakSet<WeakKey>): Readonly<T>;

package/src/lib/internal/deepFreeze.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepFreeze = deepFreeze;
+/**
+ * Recursively freezes an object and all its nested properties.
+ *
+ * @template T - Type of the object to freeze
+ * @param value - The object to freeze
+ * @param seen - Internal parameter to track circular references
+ * @returns A deeply frozen version of the input object.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+function deepFreeze(value, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    Reflect.ownKeys(value).forEach((key) => {
+        const property = value[key];
+        if (property && typeof property === "object" && !Object.isFrozen(property)) {
+            // eslint-disable-next-line @typescript-eslint/ban-types
+            deepFreeze(property, seen);
+        }
+    });
+    return Object.freeze(value);
+}
+//# sourceMappingURL=deepFreeze.js.map

package/src/lib/internal/deepFreeze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepFreeze.js","sourceRoot":"","sources":["../../../../../../packages/config/src/lib/internal/deepFreeze.ts"],"names":[],"mappings":";;AASA,gCAeC;AAxBD;;;;;;;GAOG;AACH,wDAAwD;AACxD,SAAgB,UAAU,CAAmB,KAAQ,EAAE,IAAI,GAAG,IAAI,OAAO,EAAE;IACzE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACf,OAAO,CAAC,OAAO,CAAC,KAAK,CAAoB,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3E,wDAAwD;YACxD,UAAU,CAA2B,QAAQ,EAAE,IAAI,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/src/lib/internal/isDefined.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Type guard that checks if a value is neither null nor undefined.
+ */
+export declare function isDefined<T>(value: T): value is NonNullable<T>;

package/src/lib/internal/isDefined.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDefined = isDefined;
+/**
+ * Type guard that checks if a value is neither null nor undefined.
+ */
+function isDefined(value) {
+    return value !== null && value !== undefined;
+}
+//# sourceMappingURL=isDefined.js.map

package/src/lib/internal/isDefined.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isDefined.js","sourceRoot":"","sources":["../../../../../../packages/config/src/lib/internal/isDefined.ts"],"names":[],"mappings":";;AAGA,8BAEC;AALD;;GAEG;AACH,SAAgB,SAAS,CAAI,KAAQ;IACnC,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC;AAC/C,CAAC"}

package/src/lib/internal/resolver.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { type ConfigValueMap } from "../types";
+interface ResolveParams<SchemaT extends Record<string, unknown>> {
+    config: Readonly<ConfigValueMap<SchemaT, readonly string[]>>;
+    environment: string;
+    path: readonly string[];
+    schema: z.ZodType<SchemaT>;
+}
+export declare function resolve<SchemaT extends Record<string, unknown>>(params: Readonly<ResolveParams<SchemaT>>): Record<string, unknown>;
+export {};

package/src/lib/internal/resolver.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolve = resolve;
+const tslib_1 = require("tslib");
+const decamelize_1 = tslib_1.__importDefault(require("decamelize"));
+const zod_1 = require("zod");
+const isDefined_1 = require("./isDefined");
+function resolve(params) {
+    const { config, path, ...rest } = params;
+    return Object.fromEntries(Object.entries(config).map(([key, value]) => [
+        key,
+        isConfigValue(value)
+            ? resolveConfigValue({ ...rest, path: [...path, key], value })
+            : resolve({ ...rest, config: value, path: [...path, key] }),
+    ]));
+}
+function isConfigValue(value) {
+    return (typeof value === "object" &&
+        (0, isDefined_1.isDefined)(value) &&
+        "description" in value &&
+        "defaultValue" in value);
+}
+function resolveConfigValue(params) {
+    const { environment, path, schema, value } = params;
+    const variable = process.env[(0, decamelize_1.default)(path.join("_")).toUpperCase()];
+    if ((0, isDefined_1.isDefined)(variable)) {
+        return parseEnvironmentVariable(variable, getSchema(path, schema));
+    }
+    const override = value.overrides?.[environment];
+    if ((0, isDefined_1.isDefined)(override)) {
+        return override;
+    }
+    return value.defaultValue;
+}
+function parseEnvironmentVariable(value, schema) {
+    if (schema instanceof zod_1.z.ZodArray && typeof value === "string") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+function getSchema(path, schema) {
+    return path.reduce((result, key) => 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    result instanceof zod_1.z.ZodObject ? result.shape[key] : /* istanbul ignore next */ result, schema);
+}
+//# sourceMappingURL=resolver.js.map

package/src/lib/internal/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../../../../packages/config/src/lib/internal/resolver.ts"],"names":[],"mappings":";;AAoBA,0BAeC;;AAnCD,oEAAoC;AACpC,6BAAwB;AAGxB,2CAAwC;AAgBxC,SAAgB,OAAO,CACrB,MAAwC;IAExC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IAEzC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CACxB,CAAC,CAAC,GAAG,EAAE,KAAK,CAAuD,EAAE,EAAE,CAAC;QACtE,GAAG;QACH,aAAa,CAAC,KAAK,CAAC;YAClB,CAAC,CAAC,kBAAkB,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC;YAC9D,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;KAC9D,CACF,CACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,IAAA,qBAAS,EAAC,KAAK,CAAC;QAChB,aAAa,IAAI,KAAK;QACtB,cAAc,IAAI,KAAK,CACxB,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAgC;IAC1D,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAEpD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAA,oBAAU,EAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IACvE,IAAI,IAAA,qBAAS,EAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,OAAO,wBAAwB,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC,WAAW,CAAC,CAAC;IAChD,IAAI,IAAA,qBAAS,EAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,KAAK,CAAC,YAAY,CAAC;AAC5B,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAc,EAAE,MAA0B;IAC1E,IAAI,MAAM,YAAY,OAAC,CAAC,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9D,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,IAAuB,EAAE,MAA0B;IACpE,OAAO,IAAI,CAAC,MAAM,CAChB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;IACd,+DAA+D;IAC/D,MAAM,YAAY,OAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC,MAAM,EACvF,MAAM,CACP,CAAC;AACJ,CAAC"}

package/src/lib/types.d.ts

@@ -0,0 +1,44 @@
+import { type z } from "zod";
+/**
+ * Represents a single configuration value with metadata.
+ */
+export interface ConfigValue<SchemaT, EnvironmentT extends readonly string[]> {
+    /** Default value used when no override or environment variable is present */
+    defaultValue: SchemaT;
+    /** Human-readable description of the configuration value */
+    description: string;
+    /**
+     * Optional environment-specific overrides.
+     * @example { development: "dev-host", production: "prod-host" }
+     */
+    overrides?: Readonly<Partial<Record<EnvironmentT[number], SchemaT>>>;
+}
+/**
+ * Maps configuration schema to configuration values with metadata.
+ */
+export type ConfigValueMap<SchemaT, EnvironmentT extends readonly string[]> = {
+    [K in keyof SchemaT]: ConfigValueForType<SchemaT[K], EnvironmentT>;
+};
+type ConfigValueForType<T, EnvironmentT extends readonly string[]> = T extends unknown[] ? ConfigValue<T, EnvironmentT> : T extends Date ? ConfigValue<Date, EnvironmentT> : T extends bigint ? ConfigValue<bigint, EnvironmentT> : T extends z.EnumValues ? ConfigValue<T, EnvironmentT> : T extends Record<string, unknown> ? ConfigValueMap<T, EnvironmentT> : ConfigValue<T, EnvironmentT>;
+/**
+ * Parameters for creating a configuration instance.
+ */
+export interface ConfigParams<SchemaT extends Record<string, unknown>, EnvironmentT extends readonly string[]> {
+    /**
+     * Configuration values resolved in order of precedence. @see {@link createConfig}.
+     */
+    config: Readonly<ConfigValueMap<SchemaT, EnvironmentT>>;
+    /**
+     * The current environment and list of allowed environments.
+     * @example { current: "development", allowed: ["development", "production"] as const }
+     */
+    environment: {
+        allowed: EnvironmentT;
+        current: EnvironmentT[number];
+    };
+    /**
+     * Zod schema defining the configuration shape and validation rules.
+     */
+    schema: z.ZodType<SchemaT>;
+}
+export {};

package/src/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/config/src/lib/types.ts"],"names":[],"mappings":""}