@entwico/zod-conf 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 entwico GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# zod-conf
+
+Type-safe configuration management with Zod schemas and environment variables.
+
+Not affiliated with the official Zod library.
+
+## Features
+
+- **Type-safe** - Full TypeScript support with Zod schema validation
+- **Multi-source** - Load from env vars, config files (e.g. YAML), or any plain object
+- **Env-first** - Bind schema fields directly to environment variables
+- **Simple API** - Intuitive, Zod-native API that feels familiar
+- **Zero compromise** - All Zod features work - transformations, refinements, and more
+- **Lightweight** - Only Zod as peer dependency, no extra bloat
+- **Universal** - Works with process.env, dotenv, or any environment loader
+
+## Installation
+
+```bash
+npm install @entwico/zod-conf zod
+# or
+yarn add @entwico/zod-conf zod
+# or
+pnpm add @entwico/zod-conf zod
+```
+
+## Quick Start
+
+```typescript
+import zc from '@entwico/zod-conf';
+
+// define your configuration schema
+const schema = zc.define({
+  port: zc.env('PORT').number().default(3000),
+  host: zc.env('HOST').string().default('localhost'),
+  debug: zc.env('DEBUG').boolean().default(false),
+});
+
+// load configuration from environment
+const config = schema.load({
+  env: process.env,
+});
+
+console.log(config);
+// { port: 3000, host: 'localhost', debug: false }
+```
+
+## Usage
+
+### Basic Types
+
+```typescript
+const schema = zc.define({
+  // string
+  apiUrl: zc.env('API_URL').string(),
+
+  // number
+  port: zc.env('PORT').number(),
+
+  // boolean
+  isProduction: zc.env('NODE_ENV').boolean(),
+
+  // enum
+  logLevel: zc.env('LOG_LEVEL').enum(['debug', 'info', 'warn', 'error']),
+});
+```
+
+### Defaults and Optional Values
+
+```typescript
+const schema = zc.define({
+  // with default value
+  port: zc.env('PORT').number().default(3000),
+
+  // optional field
+  apiKey: zc.env('API_KEY').string().optional(),
+
+  // nullable field
+  proxyUrl: zc.env('PROXY_URL').string().nullable(),
+});
+```
+
+### Nested Objects
+
+```typescript
+const schema = zc.define({
+  server: zc.object({
+    host: zc.env('SERVER_HOST').string().default('localhost'),
+    port: zc.env('SERVER_PORT').number().default(3000),
+  }),
+  database: zc.object({
+    url: zc.env('DATABASE_URL').string(),
+    pool: zc.object({
+      min: zc.env('DB_POOL_MIN').number().default(1),
+      max: zc.env('DB_POOL_MAX').number().default(10),
+    }),
+  }),
+});
+```
+
+### TypeScript Enums
+
+```typescript
+enum LogLevel {
+  DEBUG = 'debug',
+  INFO = 'info',
+  WARN = 'warn',
+  ERROR = 'error',
+}
+
+const schema = zc.define({
+  logLevel: zc.env('LOG_LEVEL').enum(LogLevel).default(LogLevel.INFO),
+});
+```
+
+### Loading Configuration
+
+```typescript
+// from process.env
+const config = schema.load({ env: process.env });
+
+// from .env file (using dotenv)
+import { config as dotenvConfig } from 'dotenv';
+
+const env = dotenvConfig();
+const config = schema.load({ env: env.parsed });
+
+// from custom source
+const config = schema.load({
+  env: {
+    PORT: '8080',
+    HOST: '0.0.0.0',
+  },
+});
+```
+
+### Multiple Configuration Sources
+
+You can load from multiple sources. Loaders are processed left-to-right; later loaders override earlier ones.
+
+```typescript
+import { parse } from 'yaml';
+import { readFileSync } from 'fs';
+
+const yamlConfig = parse(readFileSync('config.yml', 'utf8'));
+
+// yaml values are used as base, env vars override
+const config = schema.load({ values: yamlConfig }, { env: process.env });
+```
+
+You can also layer multiple objects for defaults:
+
+```typescript
+const defaults = { port: 3000, host: 'localhost' };
+const yamlConfig = parse(readFileSync('config.yml', 'utf8'));
+
+const config = schema.load({ values: defaults }, { values: yamlConfig }, { env: process.env });
+```
+
+The `values` loader maps values by property name and passes them directly to Zod — no string coercion is needed since YAML/JSON already preserves types. This also means you can use types that env vars can't represent, like arrays:
+
+```typescript
+import { z } from 'zod';
+
+const schema = zc.define({
+  host: zc.env('HOST').string().default('localhost'),
+  port: zc.env('PORT').number().default(3000),
+  allowedOrigins: z.array(z.string()),
+  servers: z.array(z.object({ host: z.string(), port: z.number() })),
+});
+
+// arrays come from yaml, scalar fields can be overridden by env
+const config = schema.load({ values: yamlConfig }, { env: process.env });
+```
+
+### Error Handling
+
+The error-handling is similar to Zod's standard behavior:
+
+```typescript
+// throws on validation error
+try {
+  const config = schema.load({ env: process.env });
+} catch (error) {
+  console.error('Configuration validation failed:', error);
+}
+
+// safe parsing without throwing
+const result = schema.safeLoad({ env: process.env });
+if (result.success) {
+  console.log('Config:', result.data);
+} else {
+  console.error('Validation errors:', result.error);
+}
+```
+
+### Advanced: Transformations
+
+All Zod transformations work seamlessly:
+
+```typescript
+const schema = zc.define({
+  port: zc
+    .env('PORT')
+    .number()
+    .default(3000)
+    .transform((p) => Math.max(1024, p)), // Ensure port is at least 1024
+
+  apiUrl: zc
+    .env('API_URL')
+    .string()
+    .transform((url) => url.replace(/\/$/, '')), // Remove trailing slash
+});
+```
+
+## API Reference
+
+### `zc.define(shape)`
+
+Creates a configuration schema with environment variable bindings.
+
+- **shape**: An object where each value is created using `zc.env()` or `zc.object()`
+- **returns**: A `ZodConfSchema` instance with `load()` and `safeLoad()` methods
+
+### `zc.env(key)`
+
+Binds a schema field to an environment variable.
+
+- **key**: The environment variable name
+- **returns**: An object with methods for different types:
+  - `.string()` - String value
+  - `.number()` - Numeric value (auto-converted)
+  - `.boolean()` - Boolean value (accepts 'true'/'false')
+  - `.enum(values)` - Enum value (string array or TypeScript enum)
+
+### `zc.object(shape)`
+
+Creates a nested object schema.
+
+- **shape**: An object where values are `zc.env()` or nested `zc.object()` calls
+- **returns**: A Zod object schema
+
+### `schema.load(...loaders)`
+
+Loads and validates configuration from one or more loaders.
+
+- **loaders**: One or more loader objects, processed left-to-right (later overrides earlier)
+  - `{ env: Record<string, string | undefined> }` - Load from environment variables
+  - `{ values: Record<string, unknown> }` - Load from a plain object (e.g. parsed YAML/JSON)
+- **returns**: Validated configuration object
+- **throws**: ZodError if validation fails
+
+### `schema.safeLoad(...loaders)`
+
+Safely loads configuration without throwing. Same loader arguments as `load()`.
+
+- **returns**: `{ success: true, data: T }` or `{ success: false, error: ZodError }`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { boolean, number, string, enum as zenum } from 'zod';
+export { ZodConfSchema, type Loader, type EnvLoader, type ValuesLoader } from './values/define.js';
+export declare const zc: {
+    define: <T extends import("zod").ZodRawShape>(shape: T) => import("./values/define.js").ZodConfSchema<T>;
+    env: (key: string) => {
+        string: () => import("zod").ZodString;
+        number: () => import("zod").ZodCoercedNumber<unknown>;
+        boolean: () => import("zod").ZodCoercedBoolean<unknown>;
+        enum: {
+            <const T extends readonly string[]>(values: T): import("zod").ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+            <const T extends Readonly<Record<string, string | number>>>(entries: T): import("zod").ZodEnum<T>;
+        };
+    };
+    object: <T extends import("zod").ZodRawShape>(shape: T) => import("zod").ZodObject<T>;
+    string: typeof string;
+    boolean: typeof boolean;
+    number: typeof number;
+    enum: typeof zenum;
+};
+export default zc;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,IAAI,KAAK,EAAE,MAAM,KAAK,CAAC;AAK7D,OAAO,EAAE,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnG,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;CAWd,CAAC;AAEF,eAAe,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+import { boolean, number, string, enum as zenum } from 'zod';
+import { define } from './values/define.js';
+import { env } from './values/env.js';
+import { object } from './values/object.js';
+export { ZodConfSchema } from './values/define.js';
+export const zc = {
+    define,
+    env,
+    object,
+    string,
+    boolean,
+    number,
+    enum: zenum,
+};
+export default zc;

package/dist/values/define.d.ts

@@ -0,0 +1,23 @@
+import { ZodObject, type ZodRawShape, type infer as ZodInfer } from 'zod';
+type Env = Record<string, string | undefined>;
+export type EnvLoader = {
+    env: Env;
+    values?: never | undefined;
+};
+export type ValuesLoader = {
+    values: Record<string, unknown>;
+    env?: never | undefined;
+};
+export type Loader = EnvLoader | ValuesLoader;
+export declare class ZodConfSchema<T extends ZodRawShape> {
+    private shape;
+    private schema;
+    constructor(shape: T, schema: ZodObject<T>);
+    private resolveEnvValue;
+    private loadValue;
+    load(...loaders: [Loader, ...Loader[]]): ZodInfer<ZodObject<T>>;
+    safeLoad(...loaders: [Loader, ...Loader[]]): import("zod").ZodSafeParseResult<import("zod/v4/core").$InferObjectOutput<T, {}>>;
+}
+export declare const define: <T extends ZodRawShape>(shape: T) => ZodConfSchema<T>;
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/values/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/values/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAU,KAAK,WAAW,EAAgB,KAAK,KAAK,IAAI,QAAQ,EAAE,MAAM,KAAK,CAAC;AAGhG,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CAAC;AACxF,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;AAE9C,qBAAa,aAAa,CAAC,CAAC,SAAS,WAAW;IAE5C,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,MAAM;gBADN,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAG9B,OAAO,CAAC,eAAe;IA2DvB,OAAO,CAAC,SAAS;IA6DjB,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IA8B/D,QAAQ,CAAC,GAAG,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;CAK3C;AA4BD,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,KAAG,aAAa,CAAC,CAAC,CAEvE,CAAC"}

package/dist/values/define.js

@@ -0,0 +1,101 @@
+import { ZodObject, object } from 'zod';
+import { _envMetadata } from './env-metadata.js';
+export class ZodConfSchema {
+    shape;
+    schema;
+    constructor(shape, schema) {
+        this.shape = shape;
+        this.schema = schema;
+    }
+    resolveEnvValue(schema, env) {
+        let currentSchema = schema;
+        let envKey;
+        let envType;
+        while (currentSchema && !envKey) {
+            const metadata = _envMetadata.get(currentSchema);
+            if (metadata) {
+                envKey = metadata.key;
+                envType = metadata.type;
+                break;
+            }
+            const def = currentSchema._def;
+            if (def?.innerType) {
+                currentSchema = def.innerType;
+            }
+            else if (def?.schema) {
+                currentSchema = def.schema;
+            }
+            else {
+                break;
+            }
+        }
+        if (!envKey) {
+            return undefined;
+        }
+        const value = env[envKey];
+        switch (envType) {
+            case 'string':
+                return value;
+            case 'number':
+                return value ? Number(value) : undefined;
+            case 'boolean':
+                return value === 'true' ? true : value === 'false' ? false : undefined;
+            case 'enum': {
+                const numValue = Number(value);
+                if (value && !isNaN(numValue) && Number.isInteger(numValue)) {
+                    return numValue;
+                }
+                return value;
+            }
+            default:
+                return undefined;
+        }
+    }
+    loadValue(shape, loaders) {
+        const input = {};
+        for (const key in shape) {
+            const schema = shape[key];
+            if (schema instanceof ZodObject) {
+                const subLoaders = loaders.map((loader) => {
+                    if ('values' in loader && loader.values) {
+                        const nested = loader.values[key];
+                        return { values: nested && typeof nested === 'object' ? nested : {} };
+                    }
+                    return loader;
+                });
+                input[key] = this.loadValue(schema.shape, subLoaders);
+            }
+            else {
+                for (const loader of loaders) {
+                    if ('values' in loader && loader.values) {
+                        const value = loader.values[key];
+                        if (value !== undefined) {
+                            input[key] = value;
+                        }
+                    }
+                    else if ('env' in loader && loader.env) {
+                        const value = this.resolveEnvValue(schema, loader.env);
+                        if (value !== undefined) {
+                            input[key] = value;
+                        }
+                    }
+                }
+            }
+        }
+        return input;
+    }
+    load(...loaders) {
+        const result = this.safeLoad(...loaders);
+        if (!result.success) {
+            throw result.error;
+        }
+        return result.data;
+    }
+    safeLoad(...loaders) {
+        const value = this.loadValue(this.shape, loaders);
+        return this.schema.safeParse(value);
+    }
+}
+export const define = (shape) => {
+    return new ZodConfSchema(shape, object(shape));
+};

package/dist/values/env-metadata.d.ts

@@ -0,0 +1,6 @@
+import { type ZodType } from 'zod';
+export declare const _envMetadata: WeakMap<ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, {
+    key: string;
+    type: string;
+}>;
+//# sourceMappingURL=env-metadata.d.ts.map

package/dist/values/env-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-metadata.d.ts","sourceRoot":"","sources":["../../src/values/env-metadata.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAGnC,eAAO,MAAM,YAAY;SAA+B,MAAM;UAAQ,MAAM;EAAK,CAAC"}

package/dist/values/env-metadata.js

@@ -0,0 +1 @@
+export const _envMetadata = new WeakMap();

package/dist/values/env.d.ts

@@ -0,0 +1,12 @@
+import { type util, type ZodEnum } from 'zod';
+import { coerce } from 'zod';
+export declare const env: (key: string) => {
+    string: () => import("zod").ZodString;
+    number: () => coerce.ZodCoercedNumber<unknown>;
+    boolean: () => coerce.ZodCoercedBoolean<unknown>;
+    enum: {
+        <const T extends readonly string[]>(values: T): ZodEnum<util.ToEnum<T[number]>>;
+        <const T extends Readonly<Record<string, string | number>>>(entries: T): ZodEnum<T>;
+    };
+};
+//# sourceMappingURL=env.d.ts.map

package/dist/values/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/values/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,OAAO,EAAgB,MAAM,KAAK,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAyB,MAAM,KAAK,CAAC;AAgCpD,eAAO,MAAM,GAAG,GAAI,KAAK,MAAM;;;;;eA2CC,CAAC,SAAS,SAAS,MAAM,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;eAExE,CAAC,6DAA4B,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;;CAS1E,CAAC"}

package/dist/values/env.js

@@ -0,0 +1,34 @@
+import { coerce, string, enum as zenum } from 'zod';
+import { _envMetadata } from './env-metadata.js';
+export const env = (key) => {
+    const wrap = (schema, envKey, envType) => {
+        const proxied = new Proxy(schema, {
+            get(target, prop) {
+                const value = target[prop];
+                if (typeof value === 'function') {
+                    return (...args) => {
+                        const result = value.apply(target, args);
+                        if (result && typeof result === 'object' && result._def) {
+                            return wrap(result, envKey, envType);
+                        }
+                        return result;
+                    };
+                }
+                return value;
+            },
+        });
+        _envMetadata.set(proxied, { key: envKey, type: envType });
+        return proxied;
+    };
+    return {
+        string: () => wrap(string(), key, 'string'),
+        number: () => wrap(coerce.number(), key, 'number'),
+        boolean: () => wrap(coerce.boolean(), key, 'boolean'),
+        enum: (() => {
+            function enumMethod(values) {
+                return wrap(zenum(values), key, 'enum');
+            }
+            return enumMethod;
+        })(),
+    };
+};

package/dist/values/object.d.ts

@@ -0,0 +1,4 @@
+import { type ZodObject } from 'zod';
+import { type ZodRawShape } from 'zod';
+export declare const object: <T extends ZodRawShape>(shape: T) => ZodObject<T>;
+//# sourceMappingURL=object.d.ts.map

package/dist/values/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/values/object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAiCvC,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,KAAG,SAAS,CAAC,CAAC,CAEnE,CAAC"}

package/dist/values/object.js

@@ -0,0 +1,4 @@
+import { object as zobject } from 'zod';
+export const object = (shape) => {
+    return zobject(shape);
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@entwico/zod-conf",
+  "version": "1.1.2",
+  "description": "Type-safe configuration management with Zod schemas and environment variables",
+  "license": "MIT",
+  "author": "admin@entwico.com",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "zod",
+    "config",
+    "configuration",
+    "env",
+    "environment",
+    "schema",
+    "validation",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entwico/zod-conf"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run build && npm run test && npm run lint",
+    "validate": "run-s lint typecheck test",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "typecheck": "tsc",
+    "test": "npx tsx --test --experimental-test-coverage src/index.test.ts",
+    "prepare": "husky",
+    "semantic-release": "semantic-release"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^25.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^9.1.7",
+    "npm-run-all": "^4.1.5",
+    "semantic-release": "^25.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "zod": "^4.3.6"
+  }
+}