node-safe-env 0.1.2 → 0.1.3

package/README.md

@@ -1,23 +1,49 @@
 # node-safe-env
 
+![npm](https://img.shields.io/npm/v/node-safe-env)
+![npm downloads](https://img.shields.io/npm/dm/node-safe-env)
+![license](https://img.shields.io/npm/l/node-safe-env)
+![node](https://img.shields.io/node/v/node-safe-env)
+
 Schema-based environment validation for Node.js and TypeScript.
 
-`node-safe-env` helps you fail fast at startup: validate env variables, parse them into typed runtime values, and get all validation issues in one clear error report.
+Validate environment variables at startup, parse them into runtime types, and catch configuration problems before your app boots.
 
 ## Why node-safe-env?
 
-- Fail-fast startup validation: catch config mistakes before your app starts serving traffic.
-- Typed parsing: parse strings from `.env` and `process.env` into `number`, `boolean`, `Date`, arrays, and more.
-- Aggregated errors: see all invalid/missing values at once.
-- CLI validation: validate your env setup from scripts and CI.
-- `.env.example` validation: keep examples aligned with your schema.
-- Debug tracing: inspect where each value came from and how it was parsed.
+- Fail fast during application startup.
+- Parse raw env strings into typed runtime values.
+- See aggregated validation issues in one error report.
+- Validate `.env` and `.env.example` usage from scripts or CI.
+- Inspect where values came from with debug tracing.
+
+## Features
+
+- Schema-based environment validation
+- TypeScript-friendly schema inference
+- Automatic parsing for numbers, booleans, arrays, dates
+- Nested schemas with flattened env keys
+- CLI validation for env and `.env.example`
+- Aggregated validation errors
+- Debug tracing for env source resolution
 
-## Try It Now
+## Try it instantly
+
+You can run the CLI without installing the package globally. The quickest way to try `node-safe-env` is with `npx`.
 
 ```bash
 npx node-safe-env --help
+```
+
+Validate environment variables:
+
+```bash
 npx node-safe-env validate --schema ./env.schema.ts
+```
+
+Validate `.env.example`:
+
+```bash
 npx node-safe-env validate-example --schema ./env.schema.ts
 ```
 
@@ -27,6 +53,15 @@ npx node-safe-env validate-example --schema ./env.schema.ts
 npm install node-safe-env
 ```
 
+## Examples
+
+Runnable examples are available in the repository and mirror common usage patterns.
+
+- `examples/basic` - minimal schema validation
+- `examples/nested` - nested schema with flattened env keys
+- `examples/advanced` - arrays, custom parsing, debug mode, masking
+- `examples/cli-schema` - schema module intended for CLI validation
+
 ## Quick Start
 
 Define a schema:
@@ -62,7 +97,18 @@ What this gives you:
 - `required: true` means the value must exist.
 - `default` is used when a value is missing.
 - `type` controls parsing and validation.
-- returned `env` is strongly typed from your schema.
+- The returned `env` object is strongly typed from your schema.
+
+Example `.env`:
+
+```env
+APP_NAME=DemoApp
+PORT=4000
+DEBUG=true
+NODE_ENV=development
+```
+
+Values are read as strings from the environment and then parsed according to your schema.
 
 ## What Is a Schema in node-safe-env?
 
@@ -70,12 +116,12 @@ A schema is an object where each key maps to a rule object.
 
 Each rule describes:
 
-- what type the value should be (`type`)
-- whether it must be present (`required`)
-- what to use if missing (`default`)
-- optional rule-specific settings (for example enum values, array options, custom parser)
+- What type the value should be with `type`
+- Whether it must be present with `required`
+- What to use if it is missing with `default`
+- Any rule-specific options such as enum values, array settings, or a custom parser
 
-Use `defineEnv()` when you want better literal type inference and reusable exported schema modules.
+Use `defineEnv()` when you want better literal type inference and a reusable exported schema module.
 
 ```ts
 // env.schema.ts
@@ -87,13 +133,80 @@ export const schema = defineEnv({
 } as const);
 ```
 
+## When to use node-safe-env
+
+Use this library if you want to:
+
+- validate environment variables at application startup
+- enforce typed configuration in Node.js or TypeScript projects
+- ensure `.env.example` stays aligned with your configuration schema
+- detect configuration issues early in CI pipelines
+
+## Common Use Cases
+
+- App startup validation: load and validate env once during bootstrap.
+- CI checks for `.env.example`: fail pull requests when required keys are missing or stale.
+- Debugging source issues: use debug output to understand where values were loaded from.
+
+## Value at a Glance
+
+`node-safe-env` is a schema-based env validator with:
+
+- TypeScript-friendly schema inference
+- CLI commands for runtime and `.env.example` validation
+- Structured, aggregated validation errors
+- Source tracing and debug visibility
+
+## Nested Schemas
+
+Schemas can be nested, but environment variable names are always flattened. Keys are generated by joining object path segments with `_` and converting each segment to uppercase. The library does not convert camelCase to snake_case, so `server.allowedHosts` becomes `SERVER_ALLOWEDHOSTS`, not `SERVER_ALLOWED_HOSTS`.
+
+Examples:
+
+- `server.port` -> `SERVER_PORT`
+- `database.url` -> `DATABASE_URL`
+- `server.allowedHosts` -> `SERVER_ALLOWEDHOSTS`
+
+```ts
+const env = createEnv({
+  server: {
+    port: { type: "port", default: 3000 },
+    allowedHosts: { type: "array", required: true },
+  },
+  database: {
+    url: { type: "string", required: true },
+  },
+});
+
+console.log(env.server.port);
+```
+
+```env
+SERVER_PORT=4000
+SERVER_ALLOWEDHOSTS=localhost,example.com
+DATABASE_URL=postgres://localhost:5432/app
+```
+
 ## CLI
 
-`node-safe-env` includes:
+`node-safe-env` includes two CLI commands:
 
 - `validate`: validate current environment values against your schema
 - `validate-example`: validate `.env.example` coverage against your schema
 
+You can run the CLI without installing the package globally:
+
+```bash
+npx node-safe-env --help
+```
+
+Most common commands:
+
+```bash
+npx node-safe-env validate --schema ./env.schema.ts
+npx node-safe-env validate-example --schema ./env.schema.ts
+```
+
 ```bash
 node-safe-env validate --schema ./env.schema.ts
 node-safe-env validate-example --schema ./env.schema.ts
@@ -109,11 +222,21 @@ The `--schema` module supports both JavaScript and TypeScript files:
 
 Accepted export shapes:
 
-- default export
-- named export `schema`
+- Default export
+- Named export `schema`
 
 ## `.env.example` Validation
 
+`.env.example` should contain all keys defined in your schema so new environments and CI checks stay aligned with your application configuration.
+
+Example `.env.example`:
+
+```env
+PORT=3000
+DEBUG=false
+NODE_ENV=development
+```
+
 Validate a real file:
 
 ```ts
@@ -135,21 +258,6 @@ const issues = validateExampleEnv(schema, {
 });
 ```
 
-## Common Use Cases
-
-- App startup validation: load and validate env once during bootstrap.
-- CI checks for `.env.example`: fail PRs when required keys are missing or stale.
-- Debugging source issues: use debug/tracing output to understand where values were loaded from.
-
-## Value at a Glance
-
-`node-safe-env` is a schema-based env validator with:
-
-- TypeScript-friendly schema inference
-- CLI commands for runtime and `.env.example` validation
-- structured, aggregated validation errors
-- source tracing and debug visibility
-
 ## Rule Types
 
 Supported `type` values:
@@ -168,38 +276,20 @@ Supported `type` values:
 - `date`
 - `custom`
 
-## Nested Schemas
-
-Schemas can be nested. Env keys are flattened with `_` between segments.
-
-```ts
-const env = createEnv({
-  server: {
-    port: { type: "port", default: 3000 },
-  },
-  database: {
-    url: { type: "string", required: true },
-  },
-});
-```
-
-```env
-SERVER_PORT=4000
-DATABASE_URL=postgres://localhost:5432/app
-```
-
 ## Loading Order
 
-When `options.source` is not provided, values are merged in this order (last wins):
+When `options.source` is not provided, values are merged in this order and later sources win:
 
 1. `.env`
 2. `.env.local`
 3. `.env.<NODE_ENV>`
-4. custom file from `options.envFile`
+4. Custom file from `options.envFile`
 5. `process.env`
 
 ## Debug Mode
 
+Use debug mode to inspect how values were loaded and resolved.
+
 ```ts
 import { createEnv, type EnvDebugReport } from "node-safe-env";
 
@@ -212,7 +302,7 @@ createEnv(schema, {
 });
 ```
 
-Or:
+Or log debug reports directly:
 
 ```ts
 createEnv(schema, { debug: true });
@@ -224,7 +314,7 @@ createEnv(schema, { debug: true });
 createEnv(schema, { strict: true });
 ```
 
-Strict mode reports unknown environment keys as issues.
+Strict mode reports unknown environment keys as validation issues.
 
 ## Error Handling
 
@@ -289,4 +379,4 @@ npm run check
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,11 +1,22 @@
 {
   "name": "node-safe-env",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A tiny schema-based env loader and validator for Node.js.",
   "keywords": [
     "env",
+    "environment",
+    "environment variables",
     "dotenv",
+    "env validation",
     "config",
+    "configuration",
+    "node env",
+    "env schema",
+    "typescript env",
+    "env validator",
+    "env loader",
+    "env parser",
+    "node configuration",
     "validator",
     "node"
   ],