@mrinal1224/safe-env 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mrinal Bhattacharya
+
+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,204 @@
+# 🛡️ Safe Env
+
+> Type-safe environment variable validation for Node.js & TypeScript.
+
+Stop discovering missing or invalid `.env` variables after your application has already started. **Safe Env** validates and parses environment configuration at startup while giving you inferred TypeScript types.
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mrinal/safe-env"><img src="https://img.shields.io/npm/v/@mrinal/safe-env?style=for-the-badge&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/mrinal1224/Safe-Env/stargazers"><img src="https://img.shields.io/github/stars/mrinal1224/Safe-Env?style=for-the-badge" alt="GitHub stars" /></a>
+  <a href="https://github.com/mrinal1224/Safe-Env/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mrinal1224/Safe-Env?style=for-the-badge" alt="License" /></a>
+  <a href="https://github.com/mrinal1224/Safe-Env/actions"><img src="https://img.shields.io/github/actions/workflow/status/mrinal1224/Safe-Env/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI status" /></a>
+</p>
+
+---
+
+## 🚨 The Problem
+
+Most Node.js applications eventually contain code like this:
+
+```ts
+const port = process.env.PORT;
+const jwtSecret = process.env.JWT_SECRET;
+const databaseUrl = process.env.DATABASE_URL;
+```
+
+Environment variables are exposed as strings and can be missing, malformed, or inconsistent with what your application expects.
+
+Safe Env gives you one schema for both runtime validation and TypeScript inference.
+
+---
+
+## ✨ Quick Start
+
+```bash
+npm install @mrinal/safe-env
+```
+
+```ts
+import { createEnv, z } from "@mrinal/safe-env";
+
+export const env = createEnv({
+  PORT: z.number().default(3000),
+  JWT_SECRET: z.string().min(32),
+  NODE_ENV: z.enum(["development", "production"] as const),
+  DEBUG: z.boolean().optional(),
+});
+```
+
+The result is inferred automatically:
+
+```ts
+env.PORT        // number
+env.JWT_SECRET  // string
+env.NODE_ENV    // "development" | "production"
+env.DEBUG       // boolean | undefined
+```
+
+---
+
+## 🧠 How It Works
+
+```text
+process.env
+    │
+    ▼
+Schema Definition
+    │
+    ▼
+Parse + Validate
+    │
+    ├── ✅ Valid → Typed Config
+    │
+    └── ❌ Invalid → SafeEnvError
+```
+
+Create the configuration object once and use `env` throughout the rest of your application instead of reading `process.env` everywhere.
+
+---
+
+## 🔧 Validators
+
+| Validator | Example |
+| --- | --- |
+| String | `z.string()` |
+| Number | `z.number()` |
+| Boolean | `z.boolean()` |
+| Enum | `z.enum(["development", "production"] as const)` |
+| Optional | `z.string().optional()` |
+| Default | `z.number().default(3000)` |
+| Minimum length | `z.string().min(32)` |
+| Maximum length | `z.string().max(100)` |
+
+---
+
+## ❌ Validation Errors
+
+Safe Env validates the complete schema and reports configuration problems together, so you can fix several variables in one run.
+
+Example:
+
+```text
+[safe-env] environment: Invalid environment configuration:
+  • [safe-env] PORT: must be a valid finite number, received "abc"
+  • [safe-env] JWT_SECRET: Missing required environment variable: JWT_SECRET
+```
+
+> Do not include secret values in custom error messages or logs in production.
+
+---
+
+## 📦 Package Support
+
+Safe Env is shipped as a small TypeScript library with:
+
+- ESM support
+- CommonJS support
+- Generated declaration files
+- Node.js `>=20`
+- No runtime dependencies
+
+---
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/mrinal1224/Safe-Env.git
+cd Safe-Env
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+For coverage:
+
+```bash
+npm run coverage
+```
+
+GitHub Actions runs typechecking, tests and the package build for pushes to `main` and pull requests.
+
+---
+
+## 🗺️ Roadmap
+
+### v0.1
+
+- [x] Runtime parsing
+- [x] String / number / boolean validators
+- [x] Enum validator
+- [x] Optional values
+- [x] Default values
+- [x] String length constraints
+- [x] Aggregated validation errors
+- [x] Type inference
+- [x] ESM + CommonJS package exports
+
+### v0.2
+
+- [ ] URL validator
+- [ ] Email validator
+- [ ] Regex validator
+- [ ] Custom validators
+- [ ] Transformations
+- [ ] Nested configuration
+- [ ] Better error metadata
+
+### v1.0
+
+- [ ] Stable API
+- [ ] Comprehensive integration tests
+- [ ] Documentation site
+- [ ] Automated semantic releases
+- [ ] NestJS integration
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome. Please keep the public API small and predictable.
+
+Before opening a pull request:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+---
+
+## 👨‍💻 Creator
+
+**Mrinal Bhattacharya**
+
+Software Engineer · Educator · Open Source Builder
+
+GitHub: [@mrinal1224](https://github.com/mrinal1224)
+
+---
+
+## 📄 License
+
+MIT © 2026 Mrinal Bhattacharya

package/dist/index.cjs

@@ -0,0 +1,187 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SafeEnvError: () => SafeEnvError,
+  createEnv: () => createEnv,
+  z: () => z
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var SafeEnvError = class extends Error {
+  key;
+  constructor(key, message) {
+    super(`[safe-env] ${key}: ${message}`);
+    this.name = "SafeEnvError";
+    this.key = key;
+  }
+};
+
+// src/createEnv.ts
+function createEnv(schema, source = process.env) {
+  const result = {};
+  const errors = [];
+  for (const [key, validator] of Object.entries(schema)) {
+    try {
+      result[key] = validator.parse(source[key], key);
+    } catch (error) {
+      if (error instanceof SafeEnvError) {
+        errors.push(error);
+        continue;
+      }
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(String(error));
+    }
+  }
+  if (errors.length > 0) {
+    const message = errors.map((error) => `  \u2022 ${error.message}`).join("\n");
+    throw new SafeEnvError("environment", `Invalid environment configuration:
+${message}`);
+  }
+  return result;
+}
+
+// src/validators/base.ts
+var BaseValidator = class {
+  isOptional = false;
+  hasDefault = false;
+  defaultValue;
+  __safeEnvOutput;
+  __safeEnvOptional;
+  optional() {
+    this.isOptional = true;
+    return this;
+  }
+  default(value) {
+    this.defaultValue = value;
+    this.hasDefault = true;
+    return this;
+  }
+  resolveUndefined(key) {
+    if (this.hasDefault) {
+      return this.defaultValue;
+    }
+    if (this.isOptional) {
+      return void 0;
+    }
+    throw new Error(`[safe-env] Missing required environment variable: ${key}`);
+  }
+};
+
+// src/validators/boolean.ts
+var BooleanValidator = class extends BaseValidator {
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new SafeEnvError(
+      key,
+      `must be "true" or "false", received ${JSON.stringify(value)}`
+    );
+  }
+};
+
+// src/validators/enum.ts
+var EnumValidator = class extends BaseValidator {
+  constructor(values) {
+    super();
+    this.values = values;
+  }
+  values;
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    if (this.values.includes(value)) {
+      return value;
+    }
+    throw new SafeEnvError(
+      key,
+      `must be one of ${this.values.map((item) => JSON.stringify(item)).join(", ")}, received ${JSON.stringify(value)}`
+    );
+  }
+};
+
+// src/validators/number.ts
+var NumberValidator = class extends BaseValidator {
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+      throw new SafeEnvError(key, `must be a valid finite number, received ${JSON.stringify(value)}`);
+    }
+    return parsed;
+  }
+};
+
+// src/validators/string.ts
+var StringValidator = class extends BaseValidator {
+  minLength;
+  maxLength;
+  min(length) {
+    this.minLength = length;
+    return this;
+  }
+  max(length) {
+    this.maxLength = length;
+    return this;
+  }
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    if (this.minLength !== void 0 && value.length < this.minLength) {
+      throw new SafeEnvError(
+        key,
+        `must be at least ${this.minLength} characters long`
+      );
+    }
+    if (this.maxLength !== void 0 && value.length > this.maxLength) {
+      throw new SafeEnvError(
+        key,
+        `must be at most ${this.maxLength} characters long`
+      );
+    }
+    return value;
+  }
+};
+
+// src/index.ts
+var z = {
+  string: () => new StringValidator(),
+  number: () => new NumberValidator(),
+  boolean: () => new BooleanValidator(),
+  enum: (values) => new EnumValidator(values)
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SafeEnvError,
+  createEnv,
+  z
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/createEnv.ts","../src/validators/base.ts","../src/validators/boolean.ts","../src/validators/enum.ts","../src/validators/number.ts","../src/validators/string.ts"],"sourcesContent":["import { createEnv } from \"./createEnv\";\nimport { BooleanValidator } from \"./validators/boolean\";\nimport { EnumValidator } from \"./validators/enum\";\nimport { NumberValidator } from \"./validators/number\";\nimport { StringValidator } from \"./validators/string\";\nimport type { AnyValidator, InferEnv, InferValidator } from \"./types\";\n\nexport { createEnv } from \"./createEnv\";\nexport { SafeEnvError } from \"./errors\";\nexport type { AnyValidator, InferEnv, InferValidator } from \"./types\";\n\nexport const z = {\n  string: () => new StringValidator(),\n  number: () => new NumberValidator(),\n  boolean: () => new BooleanValidator(),\n  enum: <const T extends readonly string[]>(values: T) => new EnumValidator(values),\n};\n\nexport type EnvSchema = Record<string, AnyValidator>;\nexport type InferSchema<T extends EnvSchema> = InferEnv<T>;\n\nvoid createEnv;\nvoid (null as unknown as InferValidator<AnyValidator>);\n","export class SafeEnvError extends Error {\n  public readonly key: string;\n\n  constructor(key: string, message: string) {\n    super(`[safe-env] ${key}: ${message}`);\n    this.name = \"SafeEnvError\";\n    this.key = key;\n  }\n}\n","import { SafeEnvError } from \"./errors\";\nimport type { AnyValidator, InferEnv } from \"./types\";\n\nexport function createEnv<T extends Record<string, AnyValidator>>(\n  schema: T,\n  source: NodeJS.ProcessEnv = process.env,\n): InferEnv<T> {\n  const result: Record<string, unknown> = {};\n  const errors: SafeEnvError[] = [];\n\n  for (const [key, validator] of Object.entries(schema)) {\n    try {\n      result[key] = validator.parse(source[key], key);\n    } catch (error) {\n      if (error instanceof SafeEnvError) {\n        errors.push(error);\n        continue;\n      }\n\n      if (error instanceof Error) {\n        throw error;\n      }\n\n      throw new Error(String(error));\n    }\n  }\n\n  if (errors.length > 0) {\n    const message = errors.map((error) => `  • ${error.message}`).join(\"\\n\");\n    throw new SafeEnvError(\"environment\", `Invalid environment configuration:\\n${message}`);\n  }\n\n  return result as InferEnv<T>;\n}\n","export abstract class BaseValidator<T> {\n  protected isOptional = false;\n  protected hasDefault = false;\n  protected defaultValue!: T;\n\n  readonly __safeEnvOutput!: T;\n  readonly __safeEnvOptional!: false;\n\n  optional(): OptionalValidator<T, this> {\n    this.isOptional = true;\n    return this as OptionalValidator<T, this>;\n  }\n\n  default(value: T): DefaultValidator<T, this> {\n    this.defaultValue = value;\n    this.hasDefault = true;\n    return this as DefaultValidator<T, this>;\n  }\n\n  protected resolveUndefined(key: string): T | undefined {\n    if (this.hasDefault) {\n      return this.defaultValue;\n    }\n\n    if (this.isOptional) {\n      return undefined;\n    }\n\n    throw new Error(`[safe-env] Missing required environment variable: ${key}`);\n  }\n\n  abstract parse(value: string | undefined, key: string): T | undefined;\n}\n\nexport type OptionalValidator<T, V extends BaseValidator<T>> = V & {\n  readonly __safeEnvOptional: true;\n};\n\nexport type DefaultValidator<T, V extends BaseValidator<T>> = V & {\n  readonly __safeEnvDefault: true;\n};\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class BooleanValidator extends BaseValidator<boolean> {\n  parse(value: string | undefined, key: string): boolean | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    if (value === \"true\") return true;\n    if (value === \"false\") return false;\n\n    throw new SafeEnvError(\n      key,\n      `must be \"true\" or \"false\", received ${JSON.stringify(value)}`,\n    );\n  }\n}\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class EnumValidator<T extends readonly string[]> extends BaseValidator<T[number]> {\n  constructor(private readonly values: T) {\n    super();\n  }\n\n  parse(value: string | undefined, key: string): T[number] | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    if (this.values.includes(value)) {\n      return value as T[number];\n    }\n\n    throw new SafeEnvError(\n      key,\n      `must be one of ${this.values.map((item) => JSON.stringify(item)).join(\", \")}, received ${JSON.stringify(value)}`,\n    );\n  }\n}\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class NumberValidator extends BaseValidator<number> {\n  parse(value: string | undefined, key: string): number | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    const parsed = Number(value);\n\n    if (!Number.isFinite(parsed)) {\n      throw new SafeEnvError(key, `must be a valid finite number, received ${JSON.stringify(value)}`);\n    }\n\n    return parsed;\n  }\n}\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class StringValidator extends BaseValidator<string> {\n  private minLength?: number;\n  private maxLength?: number;\n\n  min(length: number): this {\n    this.minLength = length;\n    return this;\n  }\n\n  max(length: number): this {\n    this.maxLength = length;\n    return this;\n  }\n\n  parse(value: string | undefined, key: string): string | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    if (this.minLength !== undefined && value.length < this.minLength) {\n      throw new SafeEnvError(\n        key,\n        `must be at least ${this.minLength} characters long`,\n      );\n    }\n\n    if (this.maxLength !== undefined && value.length > this.maxLength) {\n      throw new SafeEnvError(\n        key,\n        `must be at most ${this.maxLength} characters long`,\n      );\n    }\n\n    return value;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,65 @@
+declare abstract class BaseValidator<T> {
+    protected isOptional: boolean;
+    protected hasDefault: boolean;
+    protected defaultValue: T;
+    readonly __safeEnvOutput: T;
+    readonly __safeEnvOptional: false;
+    optional(): OptionalValidator<T, this>;
+    default(value: T): DefaultValidator<T, this>;
+    protected resolveUndefined(key: string): T | undefined;
+    abstract parse(value: string | undefined, key: string): T | undefined;
+}
+type OptionalValidator<T, V extends BaseValidator<T>> = V & {
+    readonly __safeEnvOptional: true;
+};
+type DefaultValidator<T, V extends BaseValidator<T>> = V & {
+    readonly __safeEnvDefault: true;
+};
+
+declare class BooleanValidator extends BaseValidator<boolean> {
+    parse(value: string | undefined, key: string): boolean | undefined;
+}
+
+declare class EnumValidator<T extends readonly string[]> extends BaseValidator<T[number]> {
+    private readonly values;
+    constructor(values: T);
+    parse(value: string | undefined, key: string): T[number] | undefined;
+}
+
+declare class NumberValidator extends BaseValidator<number> {
+    parse(value: string | undefined, key: string): number | undefined;
+}
+
+declare class StringValidator extends BaseValidator<string> {
+    private minLength?;
+    private maxLength?;
+    min(length: number): this;
+    max(length: number): this;
+    parse(value: string | undefined, key: string): string | undefined;
+}
+
+type AnyValidator = BaseValidator<unknown>;
+type InferValidator<T> = T extends BaseValidator<infer Output> ? T extends {
+    readonly __safeEnvOptional: true;
+} ? Output | undefined : Output : never;
+type InferEnv<T extends Record<string, AnyValidator>> = {
+    [K in keyof T]: InferValidator<T[K]>;
+};
+
+declare function createEnv<T extends Record<string, AnyValidator>>(schema: T, source?: NodeJS.ProcessEnv): InferEnv<T>;
+
+declare class SafeEnvError extends Error {
+    readonly key: string;
+    constructor(key: string, message: string);
+}
+
+declare const z: {
+    string: () => StringValidator;
+    number: () => NumberValidator;
+    boolean: () => BooleanValidator;
+    enum: <const T extends readonly string[]>(values: T) => EnumValidator<T>;
+};
+type EnvSchema = Record<string, AnyValidator>;
+type InferSchema<T extends EnvSchema> = InferEnv<T>;
+
+export { type AnyValidator, type EnvSchema, type InferEnv, type InferSchema, type InferValidator, SafeEnvError, createEnv, z };

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+declare abstract class BaseValidator<T> {
+    protected isOptional: boolean;
+    protected hasDefault: boolean;
+    protected defaultValue: T;
+    readonly __safeEnvOutput: T;
+    readonly __safeEnvOptional: false;
+    optional(): OptionalValidator<T, this>;
+    default(value: T): DefaultValidator<T, this>;
+    protected resolveUndefined(key: string): T | undefined;
+    abstract parse(value: string | undefined, key: string): T | undefined;
+}
+type OptionalValidator<T, V extends BaseValidator<T>> = V & {
+    readonly __safeEnvOptional: true;
+};
+type DefaultValidator<T, V extends BaseValidator<T>> = V & {
+    readonly __safeEnvDefault: true;
+};
+
+declare class BooleanValidator extends BaseValidator<boolean> {
+    parse(value: string | undefined, key: string): boolean | undefined;
+}
+
+declare class EnumValidator<T extends readonly string[]> extends BaseValidator<T[number]> {
+    private readonly values;
+    constructor(values: T);
+    parse(value: string | undefined, key: string): T[number] | undefined;
+}
+
+declare class NumberValidator extends BaseValidator<number> {
+    parse(value: string | undefined, key: string): number | undefined;
+}
+
+declare class StringValidator extends BaseValidator<string> {
+    private minLength?;
+    private maxLength?;
+    min(length: number): this;
+    max(length: number): this;
+    parse(value: string | undefined, key: string): string | undefined;
+}
+
+type AnyValidator = BaseValidator<unknown>;
+type InferValidator<T> = T extends BaseValidator<infer Output> ? T extends {
+    readonly __safeEnvOptional: true;
+} ? Output | undefined : Output : never;
+type InferEnv<T extends Record<string, AnyValidator>> = {
+    [K in keyof T]: InferValidator<T[K]>;
+};
+
+declare function createEnv<T extends Record<string, AnyValidator>>(schema: T, source?: NodeJS.ProcessEnv): InferEnv<T>;
+
+declare class SafeEnvError extends Error {
+    readonly key: string;
+    constructor(key: string, message: string);
+}
+
+declare const z: {
+    string: () => StringValidator;
+    number: () => NumberValidator;
+    boolean: () => BooleanValidator;
+    enum: <const T extends readonly string[]>(values: T) => EnumValidator<T>;
+};
+type EnvSchema = Record<string, AnyValidator>;
+type InferSchema<T extends EnvSchema> = InferEnv<T>;
+
+export { type AnyValidator, type EnvSchema, type InferEnv, type InferSchema, type InferValidator, SafeEnvError, createEnv, z };

package/dist/index.js

@@ -0,0 +1,158 @@
+// src/errors.ts
+var SafeEnvError = class extends Error {
+  key;
+  constructor(key, message) {
+    super(`[safe-env] ${key}: ${message}`);
+    this.name = "SafeEnvError";
+    this.key = key;
+  }
+};
+
+// src/createEnv.ts
+function createEnv(schema, source = process.env) {
+  const result = {};
+  const errors = [];
+  for (const [key, validator] of Object.entries(schema)) {
+    try {
+      result[key] = validator.parse(source[key], key);
+    } catch (error) {
+      if (error instanceof SafeEnvError) {
+        errors.push(error);
+        continue;
+      }
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(String(error));
+    }
+  }
+  if (errors.length > 0) {
+    const message = errors.map((error) => `  \u2022 ${error.message}`).join("\n");
+    throw new SafeEnvError("environment", `Invalid environment configuration:
+${message}`);
+  }
+  return result;
+}
+
+// src/validators/base.ts
+var BaseValidator = class {
+  isOptional = false;
+  hasDefault = false;
+  defaultValue;
+  __safeEnvOutput;
+  __safeEnvOptional;
+  optional() {
+    this.isOptional = true;
+    return this;
+  }
+  default(value) {
+    this.defaultValue = value;
+    this.hasDefault = true;
+    return this;
+  }
+  resolveUndefined(key) {
+    if (this.hasDefault) {
+      return this.defaultValue;
+    }
+    if (this.isOptional) {
+      return void 0;
+    }
+    throw new Error(`[safe-env] Missing required environment variable: ${key}`);
+  }
+};
+
+// src/validators/boolean.ts
+var BooleanValidator = class extends BaseValidator {
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    if (value === "true") return true;
+    if (value === "false") return false;
+    throw new SafeEnvError(
+      key,
+      `must be "true" or "false", received ${JSON.stringify(value)}`
+    );
+  }
+};
+
+// src/validators/enum.ts
+var EnumValidator = class extends BaseValidator {
+  constructor(values) {
+    super();
+    this.values = values;
+  }
+  values;
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    if (this.values.includes(value)) {
+      return value;
+    }
+    throw new SafeEnvError(
+      key,
+      `must be one of ${this.values.map((item) => JSON.stringify(item)).join(", ")}, received ${JSON.stringify(value)}`
+    );
+  }
+};
+
+// src/validators/number.ts
+var NumberValidator = class extends BaseValidator {
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+      throw new SafeEnvError(key, `must be a valid finite number, received ${JSON.stringify(value)}`);
+    }
+    return parsed;
+  }
+};
+
+// src/validators/string.ts
+var StringValidator = class extends BaseValidator {
+  minLength;
+  maxLength;
+  min(length) {
+    this.minLength = length;
+    return this;
+  }
+  max(length) {
+    this.maxLength = length;
+    return this;
+  }
+  parse(value, key) {
+    if (value === void 0) {
+      return this.resolveUndefined(key);
+    }
+    if (this.minLength !== void 0 && value.length < this.minLength) {
+      throw new SafeEnvError(
+        key,
+        `must be at least ${this.minLength} characters long`
+      );
+    }
+    if (this.maxLength !== void 0 && value.length > this.maxLength) {
+      throw new SafeEnvError(
+        key,
+        `must be at most ${this.maxLength} characters long`
+      );
+    }
+    return value;
+  }
+};
+
+// src/index.ts
+var z = {
+  string: () => new StringValidator(),
+  number: () => new NumberValidator(),
+  boolean: () => new BooleanValidator(),
+  enum: (values) => new EnumValidator(values)
+};
+export {
+  SafeEnvError,
+  createEnv,
+  z
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/createEnv.ts","../src/validators/base.ts","../src/validators/boolean.ts","../src/validators/enum.ts","../src/validators/number.ts","../src/validators/string.ts","../src/index.ts"],"sourcesContent":["export class SafeEnvError extends Error {\n  public readonly key: string;\n\n  constructor(key: string, message: string) {\n    super(`[safe-env] ${key}: ${message}`);\n    this.name = \"SafeEnvError\";\n    this.key = key;\n  }\n}\n","import { SafeEnvError } from \"./errors\";\nimport type { AnyValidator, InferEnv } from \"./types\";\n\nexport function createEnv<T extends Record<string, AnyValidator>>(\n  schema: T,\n  source: NodeJS.ProcessEnv = process.env,\n): InferEnv<T> {\n  const result: Record<string, unknown> = {};\n  const errors: SafeEnvError[] = [];\n\n  for (const [key, validator] of Object.entries(schema)) {\n    try {\n      result[key] = validator.parse(source[key], key);\n    } catch (error) {\n      if (error instanceof SafeEnvError) {\n        errors.push(error);\n        continue;\n      }\n\n      if (error instanceof Error) {\n        throw error;\n      }\n\n      throw new Error(String(error));\n    }\n  }\n\n  if (errors.length > 0) {\n    const message = errors.map((error) => `  • ${error.message}`).join(\"\\n\");\n    throw new SafeEnvError(\"environment\", `Invalid environment configuration:\\n${message}`);\n  }\n\n  return result as InferEnv<T>;\n}\n","export abstract class BaseValidator<T> {\n  protected isOptional = false;\n  protected hasDefault = false;\n  protected defaultValue!: T;\n\n  readonly __safeEnvOutput!: T;\n  readonly __safeEnvOptional!: false;\n\n  optional(): OptionalValidator<T, this> {\n    this.isOptional = true;\n    return this as OptionalValidator<T, this>;\n  }\n\n  default(value: T): DefaultValidator<T, this> {\n    this.defaultValue = value;\n    this.hasDefault = true;\n    return this as DefaultValidator<T, this>;\n  }\n\n  protected resolveUndefined(key: string): T | undefined {\n    if (this.hasDefault) {\n      return this.defaultValue;\n    }\n\n    if (this.isOptional) {\n      return undefined;\n    }\n\n    throw new Error(`[safe-env] Missing required environment variable: ${key}`);\n  }\n\n  abstract parse(value: string | undefined, key: string): T | undefined;\n}\n\nexport type OptionalValidator<T, V extends BaseValidator<T>> = V & {\n  readonly __safeEnvOptional: true;\n};\n\nexport type DefaultValidator<T, V extends BaseValidator<T>> = V & {\n  readonly __safeEnvDefault: true;\n};\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class BooleanValidator extends BaseValidator<boolean> {\n  parse(value: string | undefined, key: string): boolean | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    if (value === \"true\") return true;\n    if (value === \"false\") return false;\n\n    throw new SafeEnvError(\n      key,\n      `must be \"true\" or \"false\", received ${JSON.stringify(value)}`,\n    );\n  }\n}\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class EnumValidator<T extends readonly string[]> extends BaseValidator<T[number]> {\n  constructor(private readonly values: T) {\n    super();\n  }\n\n  parse(value: string | undefined, key: string): T[number] | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    if (this.values.includes(value)) {\n      return value as T[number];\n    }\n\n    throw new SafeEnvError(\n      key,\n      `must be one of ${this.values.map((item) => JSON.stringify(item)).join(\", \")}, received ${JSON.stringify(value)}`,\n    );\n  }\n}\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class NumberValidator extends BaseValidator<number> {\n  parse(value: string | undefined, key: string): number | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    const parsed = Number(value);\n\n    if (!Number.isFinite(parsed)) {\n      throw new SafeEnvError(key, `must be a valid finite number, received ${JSON.stringify(value)}`);\n    }\n\n    return parsed;\n  }\n}\n","import { BaseValidator } from \"./base\";\nimport { SafeEnvError } from \"../errors\";\n\nexport class StringValidator extends BaseValidator<string> {\n  private minLength?: number;\n  private maxLength?: number;\n\n  min(length: number): this {\n    this.minLength = length;\n    return this;\n  }\n\n  max(length: number): this {\n    this.maxLength = length;\n    return this;\n  }\n\n  parse(value: string | undefined, key: string): string | undefined {\n    if (value === undefined) {\n      return this.resolveUndefined(key);\n    }\n\n    if (this.minLength !== undefined && value.length < this.minLength) {\n      throw new SafeEnvError(\n        key,\n        `must be at least ${this.minLength} characters long`,\n      );\n    }\n\n    if (this.maxLength !== undefined && value.length > this.maxLength) {\n      throw new SafeEnvError(\n        key,\n        `must be at most ${this.maxLength} characters long`,\n      );\n    }\n\n    return value;\n  }\n}\n","import { createEnv } from \"./createEnv\";\nimport { BooleanValidator } from \"./validators/boolean\";\nimport { EnumValidator } from \"./validators/enum\";\nimport { NumberValidator } from \"./validators/number\";\nimport { StringValidator } from \"./validators/string\";\nimport type { AnyValidator, InferEnv, InferValidator } from \"./types\";\n\nexport { createEnv } from \"./createEnv\";\nexport { SafeEnvError } from \"./errors\";\nexport type { AnyValidator, InferEnv, InferValidator } from \"./types\";\n\nexport const z = {\n  string: () => new StringValidator(),\n  number: () => new NumberValidator(),\n  boolean: () => new BooleanValidator(),\n  enum: <const T extends readonly string[]>(values: T) => new EnumValidator(values),\n};\n\nexport type EnvSchema = Record<string, AnyValidator>;\nexport type InferSchema<T extends EnvSchema> = InferEnv<T>;\n\nvoid createEnv;\nvoid (null as unknown as InferValidator<AnyValidator>);\n"],"mappings":";AAAO,IAAM,eAAN,cAA2B,MAAM;AAAA,EACtB;AAAA,EAEhB,YAAY,KAAa,SAAiB;AACxC,UAAM,cAAc,GAAG,KAAK,OAAO,EAAE;AACrC,SAAK,OAAO;AACZ,SAAK,MAAM;AAAA,EACb;AACF;;;ACLO,SAAS,UACd,QACA,SAA4B,QAAQ,KACvB;AACb,QAAM,SAAkC,CAAC;AACzC,QAAM,SAAyB,CAAC;AAEhC,aAAW,CAAC,KAAK,SAAS,KAAK,OAAO,QAAQ,MAAM,GAAG;AACrD,QAAI;AACF,aAAO,GAAG,IAAI,UAAU,MAAM,OAAO,GAAG,GAAG,GAAG;AAAA,IAChD,SAAS,OAAO;AACd,UAAI,iBAAiB,cAAc;AACjC,eAAO,KAAK,KAAK;AACjB;AAAA,MACF;AAEA,UAAI,iBAAiB,OAAO;AAC1B,cAAM;AAAA,MACR;AAEA,YAAM,IAAI,MAAM,OAAO,KAAK,CAAC;AAAA,IAC/B;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,UAAU,OAAO,IAAI,CAAC,UAAU,YAAO,MAAM,OAAO,EAAE,EAAE,KAAK,IAAI;AACvE,UAAM,IAAI,aAAa,eAAe;AAAA,EAAuC,OAAO,EAAE;AAAA,EACxF;AAEA,SAAO;AACT;;;ACjCO,IAAe,gBAAf,MAAgC;AAAA,EAC3B,aAAa;AAAA,EACb,aAAa;AAAA,EACb;AAAA,EAED;AAAA,EACA;AAAA,EAET,WAAuC;AACrC,SAAK,aAAa;AAClB,WAAO;AAAA,EACT;AAAA,EAEA,QAAQ,OAAqC;AAC3C,SAAK,eAAe;AACpB,SAAK,aAAa;AAClB,WAAO;AAAA,EACT;AAAA,EAEU,iBAAiB,KAA4B;AACrD,QAAI,KAAK,YAAY;AACnB,aAAO,KAAK;AAAA,IACd;AAEA,QAAI,KAAK,YAAY;AACnB,aAAO;AAAA,IACT;AAEA,UAAM,IAAI,MAAM,qDAAqD,GAAG,EAAE;AAAA,EAC5E;AAGF;;;AC7BO,IAAM,mBAAN,cAA+B,cAAuB;AAAA,EAC3D,MAAM,OAA2B,KAAkC;AACjE,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,iBAAiB,GAAG;AAAA,IAClC;AAEA,QAAI,UAAU,OAAQ,QAAO;AAC7B,QAAI,UAAU,QAAS,QAAO;AAE9B,UAAM,IAAI;AAAA,MACR;AAAA,MACA,uCAAuC,KAAK,UAAU,KAAK,CAAC;AAAA,IAC9D;AAAA,EACF;AACF;;;ACdO,IAAM,gBAAN,cAAyD,cAAyB;AAAA,EACvF,YAA6B,QAAW;AACtC,UAAM;AADqB;AAAA,EAE7B;AAAA,EAF6B;AAAA,EAI7B,MAAM,OAA2B,KAAoC;AACnE,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,iBAAiB,GAAG;AAAA,IAClC;AAEA,QAAI,KAAK,OAAO,SAAS,KAAK,GAAG;AAC/B,aAAO;AAAA,IACT;AAEA,UAAM,IAAI;AAAA,MACR;AAAA,MACA,kBAAkB,KAAK,OAAO,IAAI,CAAC,SAAS,KAAK,UAAU,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,cAAc,KAAK,UAAU,KAAK,CAAC;AAAA,IACjH;AAAA,EACF;AACF;;;ACnBO,IAAM,kBAAN,cAA8B,cAAsB;AAAA,EACzD,MAAM,OAA2B,KAAiC;AAChE,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,iBAAiB,GAAG;AAAA,IAClC;AAEA,UAAM,SAAS,OAAO,KAAK;AAE3B,QAAI,CAAC,OAAO,SAAS,MAAM,GAAG;AAC5B,YAAM,IAAI,aAAa,KAAK,2CAA2C,KAAK,UAAU,KAAK,CAAC,EAAE;AAAA,IAChG;AAEA,WAAO;AAAA,EACT;AACF;;;ACdO,IAAM,kBAAN,cAA8B,cAAsB;AAAA,EACjD;AAAA,EACA;AAAA,EAER,IAAI,QAAsB;AACxB,SAAK,YAAY;AACjB,WAAO;AAAA,EACT;AAAA,EAEA,IAAI,QAAsB;AACxB,SAAK,YAAY;AACjB,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,OAA2B,KAAiC;AAChE,QAAI,UAAU,QAAW;AACvB,aAAO,KAAK,iBAAiB,GAAG;AAAA,IAClC;AAEA,QAAI,KAAK,cAAc,UAAa,MAAM,SAAS,KAAK,WAAW;AACjE,YAAM,IAAI;AAAA,QACR;AAAA,QACA,oBAAoB,KAAK,SAAS;AAAA,MACpC;AAAA,IACF;AAEA,QAAI,KAAK,cAAc,UAAa,MAAM,SAAS,KAAK,WAAW;AACjE,YAAM,IAAI;AAAA,QACR;AAAA,QACA,mBAAmB,KAAK,SAAS;AAAA,MACnC;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AACF;;;AC3BO,IAAM,IAAI;AAAA,EACf,QAAQ,MAAM,IAAI,gBAAgB;AAAA,EAClC,QAAQ,MAAM,IAAI,gBAAgB;AAAA,EAClC,SAAS,MAAM,IAAI,iBAAiB;AAAA,EACpC,MAAM,CAAoC,WAAc,IAAI,cAAc,MAAM;AAClF;","names":[]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mrinal1224/safe-env",
+  "version": "0.1.0",
+  "description": "Type-safe environment variable validation for Node.js and TypeScript.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "env",
+    "environment-variables",
+    "environment",
+    "typescript",
+    "validation",
+    "configuration",
+    "nodejs",
+    "config"
+  ],
+  "author": "Mrinal Bhattacharya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrinal1224/Safe-Env.git"
+  },
+  "homepage": "https://github.com/mrinal1224/Safe-Env#readme",
+  "bugs": {
+    "url": "https://github.com/mrinal1224/Safe-Env/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.0"
+  }
+}