dotenv-runtime 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,1206 @@
-# Temporary Holding Version
+# dotenv-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> A fast, validated, zero-dependency environment configuration toolkit for Node.js.
+
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/runtime%20dependencies-0-success)](#)
+[![License](https://img.shields.io/badge/license-BSD--2--Clause-blue)](LICENSE)
+
+`dotenv-runtime` loads `.env` files into `process.env` or an isolated configuration object while adding the features production applications commonly need:
+
+- Async configuration loading
+- Variable expansion
+- Required-variable checks
+- Typed schema validation
+- Type coercion
+- Multiple `.env` files with deterministic precedence
+- Parent-directory discovery
+- Isolated configuration targets
+- Structured errors and load metadata
+- A production-oriented command runner
+- CommonJS, ESM, and TypeScript support
+
+The default behavior remains familiar to users of [`dotenv`](https://github.com/motdotla/dotenv). Extended functionality is explicit and opt-in.
+
+---
+
+## Why dotenv-runtime?
+
+Environment configuration usually starts simple:
+
+```js
+require('dotenv').config()
+```
+
+But production applications often need more:
+
+- Multiple environment files
+- Validation before startup
+- Required variables
+- Typed values
+- Variable references
+- Async file loading
+- Monorepo-friendly `.env` discovery
+- Isolated configuration for tests
+- Strict startup failures
+- A CLI for launching commands
+
+`dotenv-runtime` provides these capabilities without adding runtime dependencies.
+
+### Highlights
+
+| Feature | Supported |
+| --- | :---: |
+| Zero runtime dependencies | ✅ |
+| CommonJS | ✅ |
+| Native ESM | ✅ |
+| TypeScript declarations | ✅ |
+| Sync configuration | ✅ |
+| Async configuration | ✅ |
+| Variable expansion | ✅ |
+| Required variables | ✅ |
+| Schema validation | ✅ |
+| Type coercion | ✅ |
+| Multiple `.env` files | ✅ |
+| Parent-directory discovery | ✅ |
+| Isolated configuration targets | ✅ |
+| Optimized parser | ✅ |
+| CLI command runner | ✅ |
+| Optional encrypted configuration | ✅ |
+
+---
+
+## Requirements
+
+- **Node.js 20 or later**
+
+---
+
+## Installation
+
+```sh
+npm install dotenv-runtime
+```
+
+---
+
+# Quick Start
+
+Create a `.env` file:
+
+```dotenv
+APP_NAME=payments-api
+PORT=3000
+LOG_LEVEL=info
+```
+
+Load it from your application:
+
+```js
+const dotenv = require('dotenv-runtime')
+
+const result = dotenv.config()
+
+if (result.error) {
+  throw result.error
+}
+
+console.log(process.env.APP_NAME)
+```
+
+### ESM
+
+```js
+import dotenv, { config } from 'dotenv-runtime'
+
+config()
+```
+
+### ESM preload
+
+If you want configuration loaded as a side effect:
+
+```js
+import 'dotenv-runtime/config'
+```
+
+---
+
+# Production Configuration
+
+For production applications, you can combine multiple features into a single configuration pipeline.
+
+```js
+import { config } from 'dotenv-runtime'
+
+const result = config({
+  path: [
+    '.env.production.local',
+    '.env.production'
+  ],
+
+  expand: true,
+
+  required: [
+    'DATABASE_URL',
+    'PORT'
+  ],
+
+  strict: true,
+
+  quiet: true,
+
+  schema: {
+    DATABASE_URL: 'url',
+
+    PORT: {
+      type: 'integer',
+      min: 1,
+      max: 65535,
+      required: true
+    },
+
+    LOG_LEVEL: {
+      type: 'string',
+      enum: [
+        'debug',
+        'info',
+        'warn',
+        'error'
+      ],
+      default: 'info'
+    }
+  }
+})
+
+const {
+  PORT,
+  LOG_LEVEL
+} = result.validated
+```
+
+Environment variables written to `process.env` remain strings.
+
+Coerced and validated values are returned separately through:
+
+```js
+result.validated
+```
+
+This lets you keep the familiar `.env` / `process.env` behavior while still working with properly typed configuration inside your application.
+
+---
+
+# `.env` Syntax
+
+`dotenv-runtime` supports the established `.env` syntax:
+
+```dotenv
+# Comments and blank lines are ignored.
+
+PLAIN=value
+
+EMPTY=
+
+SINGLE_QUOTED='literal value'
+
+DOUBLE_QUOTED="supports escaped\nnewlines"
+
+BACKTICKED=`multiline-friendly value`
+
+export EXPORTED=value
+
+COLON: value
+
+INLINE=value # comment
+
+HASH="value#inside-quotes"
+
+MULTILINE="first line
+second line"
+```
+
+Keys may contain:
+
+- Letters
+- Numbers
+- Underscores
+- Periods
+- Hyphens
+
+Parsed values are strings.
+
+Existing environment values are preserved unless:
+
+```js
+override: true
+```
+
+is enabled.
+
+---
+
+# Core API
+
+`dotenv-runtime` exports eight primary functions:
+
+```text
+config()
+configDotenv()
+configAsync()
+parse()
+populate()
+expand()
+validate()
+findUp()
+```
+
+---
+
+## `config(options?)`
+
+Loads the configured environment files synchronously.
+
+The pipeline is:
+
+```text
+Load files
+   ↓
+Parse
+   ↓
+Expand references
+   ↓
+Check required values
+   ↓
+Validate schema
+   ↓
+Commit final values
+```
+
+Example:
+
+```js
+const dotenv = require('dotenv-runtime')
+
+const result = dotenv.config({
+  path: '.env.local',
+  quiet: true
+})
+```
+
+### Return value
+
+```ts
+interface DotenvConfigOutput<T> {
+  parsed: Record<string, string>
+  loaded: string[]
+  errors: Error[]
+  error?: Error
+  validated?: T
+}
+```
+
+### Result fields
+
+| Property | Description |
+| --- | --- |
+| `parsed` | Parsed configuration values |
+| `loaded` | Absolute paths successfully loaded |
+| `errors` | All load or processing errors in encounter order |
+| `error` | Primary error for conventional single-error handling |
+| `validated` | Typed configuration returned after schema validation |
+
+`loaded` contains absolute paths for successfully read files.
+
+`errors` contains every encountered load or processing error.
+
+`error` provides the primary error for applications that only need conventional single-error handling.
+
+---
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `path` | `string \| URL \| Array<string \| URL>` | `<cwd>/.env` | File or ordered list of files to load |
+| `cwd` | `string` | `process.cwd()` | Base directory for relative paths and discovery |
+| `encoding` | `BufferEncoding` | `utf8` | File encoding |
+| `processEnv` | `Record<string, string>` | `process.env` | Target object receiving configuration |
+| `override` | `boolean` | `false` | Replace existing values and allow later files to win |
+| `quiet` | `boolean` | `false` | Suppress the injection summary |
+| `debug` | `boolean` | `false` | Print diagnostic information |
+| `fast` | `boolean` | `false` | Use the optimized parser |
+| `expand` | `boolean` | `false` | Expand variable references before validation |
+| `required` | `string \| string[]` | — | Require non-empty final values |
+| `allowEmpty` | `boolean` | `false` | Allow required values to be empty |
+| `schema` | `DotenvSchema` | — | Validate and coerce configuration |
+| `strict` | `boolean` | `false` | Throw instead of returning processing errors |
+| `searchUp` | `boolean \| string` | `false` | Search ancestor directories for `.env` or a named file |
+| `stopDir` | `string` | filesystem root | Stop upward discovery at this directory |
+| `secure` | `boolean` | `false` | Delegate encrypted configuration to `@dotenvx/dotenvx` |
+
+---
+
+# Async Loading
+
+## `configAsync(options?)`
+
+`configAsync()` provides the same configuration pipeline as `config()` while using the promise-based filesystem API.
+
+Multiple files can be read concurrently.
+
+```js
+import { configAsync } from 'dotenv-runtime'
+
+const result = await configAsync({
+  path: [
+    '.env.local',
+    '.env'
+  ],
+
+  processEnv: {},
+
+  quiet: true
+})
+```
+
+Use `config()` when environment configuration is part of normal synchronous application bootstrap.
+
+Use `configAsync()` when startup is already asynchronous, configuration files are stored on slower storage, several files need to be loaded, or you prefer promise-based initialization.
+
+---
+
+# `configDotenv(options?)`
+
+Runs the local environment-file loading pipeline directly.
+
+`config()` normally delegates to `configDotenv()` unless secure mode is enabled.
+
+---
+
+# Parsing
+
+## `parse(source, options?)`
+
+Parses a string or `Buffer` without:
+
+- Reading files
+- Mutating `process.env`
+- Mutating another environment object
+
+```js
+import { parse } from 'dotenv-runtime'
+
+const values = parse(
+  'HOST=localhost\nPORT=3000'
+)
+
+console.log(values)
+```
+
+Result:
+
+```js
+{
+  HOST: 'localhost',
+  PORT: '3000'
+}
+```
+
+### Optimized parser
+
+The optimized scanner can be selected explicitly:
+
+```js
+const values = parse(source, {
+  fast: true
+})
+```
+
+The scanner supports:
+
+- BOM-prefixed files
+- Multiline quoted values
+- Escaped quotes
+- Escaped backslashes
+- Comments
+- `export` prefixes
+- Ordered duplicate-key behavior
+
+---
+
+# Populating Configuration
+
+## `populate(target, values, options?)`
+
+Copies configuration values into a target object.
+
+It returns only the values that were actually written.
+
+```js
+import { populate } from 'dotenv-runtime'
+
+const target = {
+  PORT: '8080'
+}
+
+const populated = populate(
+  target,
+  {
+    PORT: '3000',
+    HOST: 'localhost'
+  },
+  {
+    override: false
+  }
+)
+```
+
+The result is:
+
+```js
+// target
+{
+  PORT: '8080',
+  HOST: 'localhost'
+}
+
+// populated
+{
+  HOST: 'localhost'
+}
+```
+
+Existing properties are preserved by default, including properties whose value is `undefined`.
+
+Special property names are assigned safely without modifying object prototypes.
+
+---
+
+# Variable Expansion
+
+## `expand(values, options?)`
+
+Resolves variable references and returns a new object.
+
+The input object is never mutated.
+
+Variable expansion **never executes shell commands**.
+
+Example:
+
+```dotenv
+HOST=localhost
+PORT=3000
+
+BASE_URL=http://${HOST}:${PORT}
+
+OPTIONAL=${UNSET:-fallback}
+
+LITERAL=\$HOST
+```
+
+Supported expressions:
+
+| Expression | Behavior |
+| --- | --- |
+| `$NAME` | Resolve `NAME` |
+| `${NAME}` | Resolve `NAME` |
+| `${NAME-default}` | Use `default` when `NAME` is unset |
+| `${NAME:-default}` | Use `default` when `NAME` is unset or empty |
+| `\$NAME` | Preserve `$NAME` literally |
+
+### Precedence
+
+Existing values in `processEnv` take precedence during expansion.
+
+Use:
+
+```js
+const expanded = expand(values, {
+  processEnv: process.env,
+  override: true
+})
+```
+
+to prefer local values instead.
+
+### Circular references
+
+Circular references throw a:
+
+```text
+dotenv-runtime_EXPANSION_CYCLE
+```
+
+error.
+
+The error identifies the variables involved without exposing their values.
+
+Shell expressions such as:
+
+```sh
+$(command)
+```
+
+are not executed and remain untouched.
+
+---
+
+# Validation & Type Coercion
+
+## `validate(values, schema)`
+
+Validates configuration against a schema and returns a new object containing the declared fields.
+
+Values can optionally be coerced into useful JavaScript types.
+
+```js
+import { validate } from 'dotenv-runtime'
+
+const settings = validate(process.env, {
+  APP_ENV: {
+    type: 'string',
+    enum: [
+      'development',
+      'test',
+      'production'
+    ],
+    required: true
+  },
+
+  PORT: {
+    type: 'integer',
+    min: 1,
+    max: 65535,
+    default: 3000
+  },
+
+  ENABLE_CACHE: 'boolean',
+
+  CACHE_OPTIONS: 'json',
+
+  PUBLIC_URL: 'url'
+})
+```
+
+## Supported Types
+
+| Type | Output | Accepted input |
+| --- | --- | --- |
+| `string` | `string` | Any defined value |
+| `number` | `number` | Finite numeric value |
+| `integer` | `number` | Safe integer |
+| `boolean` | `boolean` | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` |
+| `json` | JSON value | Valid JSON text or an existing value |
+| `url` | `string` | URL accepted by the standard `URL` parser |
+
+## Validation Rules
+
+A schema descriptor can define:
+
+```ts
+interface DotenvValidationRule {
+  type?:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'boolean'
+    | 'json'
+    | 'url'
+
+  required?: boolean
+
+  allowEmpty?: boolean
+
+  default?: unknown
+
+  enum?: readonly unknown[]
+
+  min?: number
+
+  max?: number
+
+  pattern?: RegExp | string
+
+  validate?:
+    (value: unknown) =>
+      boolean | string | void
+
+  transform?:
+    (value: unknown) => unknown
+}
+```
+
+### Type shorthand
+
+Instead of:
+
+```js
+PORT: {
+  type: 'integer'
+}
+```
+
+you can use:
+
+```js
+PORT: 'integer'
+```
+
+A type shorthand marks the field as required.
+
+Descriptor rules are optional unless:
+
+```js
+required: true
+```
+
+is specified.
+
+Validation failures are collected in:
+
+```js
+error.issues
+```
+
+Built-in diagnostics identify configuration keys and validation rules without exposing configuration values.
+
+---
+
+# Multiple `.env` Files
+
+Multiple files can be supplied in a deterministic order:
+
+```js
+dotenv.config({
+  path: [
+    '.env.local',
+    '.env'
+  ]
+})
+```
+
+Files are processed in exactly the order provided.
+
+## Default behavior
+
+Without `override`:
+
+1. Existing target values are preserved.
+2. The first file defining a key wins.
+3. Later files only add keys that are still absent.
+
+For example:
+
+```text
+.env.local
+.env
+```
+
+means `.env.local` has priority over `.env`.
+
+## With `override: true`
+
+```js
+dotenv.config({
+  path: [
+    '.env.local',
+    '.env'
+  ],
+  override: true
+})
+```
+
+The behavior becomes:
+
+1. File values replace existing target values.
+2. The last file defining a key wins.
+
+## Atomic configuration
+
+Required checks and schema validation run against the final candidate environment **before** parsed values are committed.
+
+This means a failure in required-variable validation, variable expansion, or schema validation cannot partially update the target environment.
+
+---
+
+# Parent Directory Discovery
+
+## `findUp(filename?, options?)`
+
+Searches upward from a directory and returns the nearest matching file.
+
+```js
+import { findUp } from 'dotenv-runtime'
+
+const envPath = findUp('.env', {
+  cwd: __dirname,
+  stopDir: '/workspace'
+})
+```
+
+Returns an absolute path or `undefined` when no matching file is found.
+
+### Configuration shortcut
+
+```js
+dotenv.config({
+  searchUp: true
+})
+```
+
+searches for `.env`.
+
+You can also specify a filename:
+
+```js
+dotenv.config({
+  searchUp: '.env.production'
+})
+```
+
+This is especially useful for monorepos and applications nested inside workspace directories.
+
+---
+
+# Strict Error Handling
+
+By default, errors are returned through the configuration result.
+
+```js
+const result = dotenv.config({
+  path: '.env.production'
+})
+
+if (result.error) {
+  console.error(result.error.message)
+  process.exit(1)
+}
+```
+
+For applications that prefer exceptions, enable strict mode:
+
+```js
+dotenv.config({
+  path: '.env.production',
+  required: [
+    'DATABASE_URL'
+  ],
+  strict: true
+})
+```
+
+With `strict: true`, the primary configuration failure is thrown immediately.
+
+---
+
+# Isolated Configuration
+
+You do not have to write configuration into `process.env`.
+
+Pass your own target:
+
+```js
+const environment = {}
+
+const result = dotenv.config({
+  path: '.env.test',
+  processEnv: environment,
+  quiet: true
+})
+```
+
+This is useful for:
+
+- Tests
+- Build tools
+- Multiple configuration contexts
+- Libraries
+- Sandboxed configuration
+- Applications that should avoid global environment mutation
+
+---
+
+# Command-Line Interface
+
+`dotenv-runtime` includes a command runner for launching processes with loaded environment variables.
+
+## Basic usage
+
+```sh
+dotenv-runtime run -- node server.js
+```
+
+The `--` separator marks the beginning of the child process command.
+
+## Multiple files
+
+```sh
+dotenv-runtime run \
+  -f .env.local \
+  -f .env \
+  -- node server.js
+```
+
+Files are processed in the specified order.
+
+## Required variables
+
+```sh
+dotenv-runtime run \
+  --expand \
+  --required DATABASE_URL,PORT \
+  -- node server.js
+```
+
+## Search parent directories
+
+```sh
+dotenv-runtime run \
+  --search-up \
+  -- npm test
+```
+
+## CLI options
+
+| Option | Description |
+| --- | --- |
+| `-f, --file <path>` | Load a file; repeatable |
+| `--cwd <path>` | Resolve files from another directory |
+| `--search-up[=<name>]` | Find `.env` or a named file in an ancestor directory |
+| `--expand` | Expand variable references safely |
+| `--required <names>` | Require comma-separated variables; repeatable |
+| `--allow-empty` | Permit empty required values |
+| `--override` | Replace existing environment values |
+| `--strict` | Fail on load or validation errors |
+| `--fast` | Use the optimized parser |
+| `--secure` | Delegate encrypted loading to `@dotenvx/dotenvx` |
+| `--debug` | Print diagnostics |
+| `--quiet` | Suppress the injection summary |
+| `-h, --help` | Show command help |
+| `-v, --version` | Print the installed version |
+
+The `--` separator is required.
+
+The child process receives its arguments directly, and `dotenv-runtime` propagates the child's exit status.
+
+---
+
+# Environment-Based Configuration
+
+Configuration defaults can also be provided through environment variables.
+
+Two prefixes are supported:
+
+```text
+dotenv-runtime_CONFIG_
+DOTENV_CONFIG_
+```
+
+The `dotenv-runtime_CONFIG_` prefix takes precedence when both are present.
+
+Supported variables:
+
+```text
+PATH
+ENCODING
+CWD
+QUIET
+DEBUG
+OVERRIDE
+SECURE
+FAST
+EXPAND
+STRICT
+SEARCH_UP
+ALLOW_EMPTY
+REQUIRED
+```
+
+`REQUIRED` accepts a comma-separated list.
+
+Example:
+
+```sh
+dotenv-runtime_CONFIG_PATH=.env.production \
+dotenv-runtime_CONFIG_EXPAND=true \
+dotenv-runtime_CONFIG_REQUIRED=DATABASE_URL,PORT \
+node server.js
+```
+
+Explicit API options and CLI flags take precedence over environment-based defaults.
+
+---
+
+# Security
+
+`dotenv-runtime` treats `.env` files as configuration data rather than executable input.
+
+### Safety properties
+
+- Variable expansion never executes commands.
+- Built-in validation errors do not include configuration values.
+- Required-variable and schema failures are atomic.
+- Special property names cannot modify object prototypes.
+- The core package performs no network operations.
+- The core package has no runtime dependencies.
+
+### Protect your `.env` files
+
+`.env` files commonly contain credentials and other secrets.
+
+Do not:
+
+- Commit secrets to source control
+- Log entire configuration objects
+- Expose `.env` files publicly
+- Share production environment files unnecessarily
+
+Use restrictive file permissions and your deployment platform's secret-management facilities for production credentials.
+
+## Encrypted Configuration
+
+Encrypted configuration is optional.
+
+Install `@dotenvx/dotenvx` separately:
+
+```sh
+npm install @dotenvx/dotenvx
+```
+
+Then enable secure mode:
+
+```js
+dotenv.config({
+  secure: true
+})
+```
+
+The core package does not require the encrypted configuration dependency unless secure mode is used.
+
+---
+
+# TypeScript
+
+TypeScript declarations are included with the package.
+
+```ts
+import { config } from 'dotenv-runtime'
+
+interface Settings {
+  PORT: number
+  ENABLE_CACHE: boolean
+}
+
+const result = config<Settings>({
+  schema: {
+    PORT: 'integer',
+    ENABLE_CACHE: 'boolean'
+  },
+
+  strict: true
+})
+
+result.validated?.PORT.toFixed()
+```
+
+The generic type can describe the validated configuration returned by the loader.
+
+Compatibility type aliases beginning with `Dotenv` are retained to make migration easier.
+
+---
+
+# CommonJS & ESM
+
+`dotenv-runtime` provides both CommonJS and native ESM builds.
+
+### CommonJS
+
+```js
+const dotenv = require('dotenv-runtime')
+
+dotenv.config()
+```
+
+### ESM
+
+```js
+import dotenv from 'dotenv-runtime'
+
+dotenv.config()
+```
+
+### Named import
+
+```js
+import { config } from 'dotenv-runtime'
+
+config()
+```
+
+### ESM preload
+
+```js
+import 'dotenv-runtime/config'
+```
+
+---
+
+# Migrating from `dotenv`
+
+For basic usage, migration is intentionally simple.
+
+### Before
+
+```js
+const dotenv = require('dotenv')
+
+dotenv.config()
+```
+
+### After
+
+```js
+const dotenv = require('dotenv-runtime')
+
+dotenv.config()
+```
+
+### ESM preload
+
+Before:
+
+```js
+import 'dotenv/config'
+```
+
+After:
+
+```js
+import 'dotenv-runtime/config'
+```
+
+The core defaults remain familiar:
+
+- `.env` is loaded from the current working directory
+- Values are strings
+- Existing target keys are preserved
+- Multiple paths use first-file-wins behavior
+- `override: true` enables replacement
+
+`dotenv-runtime` is an independent fork and is **not** the official `dotenv` distribution.
+
+---
+
+# Development
+
+Install the locked development dependencies:
+
+```sh
+npm ci
+```
+
+Run the complete verification pipeline:
+
+```sh
+npm test
+```
+
+The test pipeline:
+
+1. Builds every module format
+2. Checks JavaScript style
+3. Validates TypeScript declarations
+4. Runs unit and integration tests
+5. Runs CLI and parser tests
+6. Executes sample programs
+
+## Run samples
+
+```sh
+node samples/basic/test.js
+```
+
+```sh
+node samples/features/test.js
+```
+
+## Verify the package before publishing
+
+```sh
+npm pack --dry-run
+```
+
+---
+
+# Project Structure
+
+```text
+.
+├── lib/          Runtime implementation and declarations
+├── scripts/      Reproducible build tooling
+├── tests/        Unit, integration, CLI, parser, and type tests
+├── samples/      Executable consumer-style examples
+└── dist/         Generated CommonJS, ESM, CLI,
+                  preload, and declaration files
+```
+
+---
+
+# Design Principles
+
+`dotenv-runtime` is built around a few simple principles.
+
+### Familiar by default
+
+Basic usage should feel immediately familiar to existing `dotenv` users.
+
+### Explicit extensions
+
+Advanced behavior is opt-in rather than silently changing traditional behavior.
+
+### Deterministic configuration
+
+Multiple files, overrides, expansion, and validation follow predictable rules.
+
+### No unnecessary dependencies
+
+The core runtime remains dependency-free.
+
+### Safe configuration handling
+
+Configuration values should be treated as data, not executable input.
+
+### Atomic startup
+
+Validation should happen before configuration is committed, preventing partially configured environments.
+
+### Type-aware configuration
+
+Environment variables begin as strings, but applications can explicitly validate and coerce them into useful types.
+
+---
+
+# Upstream Attribution
+
+`dotenv-runtime` is derived from [`dotenv`](https://github.com/motdotla/dotenv) and retains its BSD 2-Clause licensing terms.
+
+This fork adds independent:
+
+- APIs
+- Packaging
+- Tests
+- Documentation
+- Build tooling
+- Configuration features
+- Release policy
+
+---
+
+# License
+
+BSD 2-Clause.
+
+See [`LICENSE`](LICENSE) for the complete license text.