dev-env-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raju Kumar Yadav
+
+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,205 @@
+# dev-env-toolkit
+
+[![npm version](https://img.shields.io/npm/v/dev-env-toolkit.svg)](https://www.npmjs.com/package/dev-env-toolkit)
+[![npm downloads](https://img.shields.io/npm/dm/dev-env-toolkit.svg)](https://www.npmjs.com/package/dev-env-toolkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-green.svg)](https://www.npmjs.com/package/dev-env-toolkit)
+
+> Type-safe environment variables for Node.js and TypeScript
+
+A zero-dependency, TypeScript-first toolkit for managing environment variables with full type inference, validation, and helpful error messages.
+
+## Features
+
+- **Type-Safe**: Full TypeScript support with automatic type inference
+- **Zero Dependencies**: No external runtime dependencies
+- **Chainable API**: Intuitive Zod-like schema definition
+- **Validation**: Built-in validators for strings, numbers, booleans, enums, and arrays
+- **Helpful Errors**: Clear error messages showing exactly what went wrong
+- **.env Support**: Built-in parser for .env files
+
+## Installation
+
+```bash
+npm install dev-env-toolkit
+```
+
+## Quick Start
+
+```typescript
+import { env } from 'dev-env-toolkit';
+
+// Define your environment schema
+const config = env.create({
+  PORT: env.number().default(3000),
+  DATABASE_URL: env.string().url(),
+  NODE_ENV: env.enum(['development', 'production', 'test'] as const),
+  DEBUG: env.boolean().default(false),
+  API_KEYS: env.array().separator(','),
+});
+
+// Fully typed! TypeScript knows the exact types
+console.log(config.PORT);        // number
+console.log(config.DATABASE_URL); // string
+console.log(config.NODE_ENV);     // 'development' | 'production' | 'test'
+console.log(config.DEBUG);        // boolean
+console.log(config.API_KEYS);     // string[]
+```
+
+## Validators
+
+### String
+
+```typescript
+env.string()                    // Required string
+env.string().optional()         // Optional string
+env.string().default('value')   // With default value
+env.string().min(5)             // Minimum length
+env.string().max(100)           // Maximum length
+env.string().url()              // Valid URL format
+env.string().email()            // Valid email format
+env.string().regex(/^[A-Z]+$/)  // Custom regex pattern
+```
+
+### Number
+
+```typescript
+env.number()                    // Required number
+env.number().optional()         // Optional number
+env.number().default(3000)      // With default value
+env.number().min(1)             // Minimum value
+env.number().max(65535)         // Maximum value
+env.number().int()              // Must be integer
+env.number().positive()         // Must be positive
+env.number().port()             // Valid port (1-65535, integer)
+```
+
+### Boolean
+
+Accepts: `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` (case-insensitive)
+
+```typescript
+env.boolean()                   // Required boolean
+env.boolean().optional()        // Optional boolean
+env.boolean().default(false)    // With default value
+```
+
+### Enum
+
+```typescript
+env.enum(['development', 'production', 'test'] as const)
+env.enum(['small', 'medium', 'large'] as const).default('medium')
+```
+
+### Array
+
+```typescript
+env.array()                     // Comma-separated by default
+env.array().separator('|')      // Custom separator
+env.array().min(1)              // Minimum items
+env.array().max(10)             // Maximum items
+env.array().default(['a', 'b']) // Default value
+```
+
+## Loading .env Files
+
+```typescript
+import { env } from 'dev-env-toolkit';
+
+// Load from .env file before parsing
+const config = env.create({
+  DATABASE_URL: env.string(),
+}, { path: '.env' });
+
+// Or load manually
+env.load('.env');
+env.load('.env.local', { override: true }); // Override existing values
+```
+
+## Safe Parsing
+
+Use `safeParse` to handle validation errors without throwing:
+
+```typescript
+import { env } from 'dev-env-toolkit';
+
+const result = env.safeParse({
+  PORT: env.number(),
+  DATABASE_URL: env.string(),
+});
+
+if (result.success) {
+  console.log(result.data.PORT);
+} else {
+  console.error('Validation failed:', result.errors);
+  // result.errors: [{ key: 'DATABASE_URL', message: '...' }]
+}
+```
+
+## Error Messages
+
+When validation fails, you get clear, actionable error messages:
+
+```
+Environment Validation Failed
+
+Found 2 errors:
+
+  DATABASE_URL: Required environment variable is missing
+
+  PORT: Invalid number format
+    Received: not-a-number
+
+Tip: Check your .env file or environment variables
+```
+
+## TypeScript Integration
+
+The library provides full type inference:
+
+```typescript
+import { env, type InferEnv } from 'dev-env-toolkit';
+
+const schema = {
+  PORT: env.number().default(3000),
+  DEBUG: env.boolean().optional(),
+  NODE_ENV: env.enum(['development', 'production'] as const),
+};
+
+// Extract the type
+type Config = InferEnv<typeof schema>;
+// { PORT: number; DEBUG: boolean | undefined; NODE_ENV: 'development' | 'production' }
+
+const config = env.create(schema);
+```
+
+## API Reference
+
+### `env.create(schema, options?)`
+
+Create a type-safe configuration object from environment variables.
+
+**Options:**
+- `path?: string` - Path to .env file to load
+- `throwOnError?: boolean` - Whether to throw on validation errors (default: `true`)
+- `env?: Record<string, string>` - Custom environment object (default: `process.env`)
+
+### `env.safeParse(schema, options?)`
+
+Parse environment variables without throwing. Returns a result object.
+
+### `env.load(path, options?)`
+
+Load environment variables from a .env file into `process.env`.
+
+**Options:**
+- `override?: boolean` - Whether to override existing values (default: `false`)
+
+### `env.parse(path)`
+
+Parse a .env file and return the key-value pairs without modifying `process.env`.
+
+## License
+
+MIT