@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/env/index.md

@@ -1,233 +1,115 @@
-# Environment
-
-Structured access to application environment variables with prefix filtering, type-safe retrieval, and stage detection.
-
-## Quick Reference
-
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis-helpers` |
-| **Classes** | `ApplicationEnvironment`, `Environment` |
-| **Implements** | `IApplicationEnvironment` (interface) |
-| **Singleton** | `applicationEnvironment` (alias `Envs`) -- auto-initialized at module load |
-| **Runtimes** | Both |
-
-#### Import Paths
-
-```typescript
-// Singleton instance (recommended)
-import { applicationEnvironment, Envs } from '@venizia/ignis-helpers';
-
-// Classes
-import { ApplicationEnvironment, Environment } from '@venizia/ignis-helpers';
-
-// Interface
-import type { IApplicationEnvironment } from '@venizia/ignis-helpers';
-```
+---
+title: Environment
+description: Prefix-filtered, type-safe access to environment variables plus deployment-stage detection
+difficulty: beginner
+---
 
-## Creating an Instance
+# Environment
 
-### Singleton (Recommended)
+`applicationEnvironment` is a singleton that filters `process.env` down to your app's prefix and gives typed access to it; `Environment` reads the current deployment stage from `NODE_ENV`.
 
-A pre-configured `applicationEnvironment` singleton is auto-initialized at module load time. It reads `process.env` and filters keys matching the configured prefix (default: `APP_ENV`). An alias `Envs` is also exported for convenience.
+## In one example
 
 ```typescript
 import { applicationEnvironment } from '@venizia/ignis-helpers';
-// or
-import { Envs } from '@venizia/ignis-helpers';
 
 const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
-const jwtSecret2 = Envs.get<string>('APP_ENV_JWT_SECRET');
+const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', { defaultValue: 5000 });
 ```
 
-> [!TIP]
-> For most applications, the singleton is all you need. It is created once at module load and shares the same filtered environment across your entire app.
+The singleton is created once at module load, reading only keys that start with `APP_ENV` (the default prefix) from `process.env`. `Envs` is an exported alias for the same instance.
 
-### Custom Instance
+## How it works
 
-If you need a different prefix or a custom set of environment variables, construct your own instance.
+- **Construction filters by prefix.** `new ApplicationEnvironment({ prefix, envs })` copies only the keys of `envs` that start with `prefix` into an internal map - everything else is invisible to `get()`. The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` and `process.env`.
+- **`get()` takes an options object, not a positional default.** The signature is `get<ReturnType, BeforeTransformType = unknown>(key, opts?: { defaultValue?, transform? })`. Without `transform`, it returns the raw value (still a `string`) or `defaultValue` when the key is missing. With `transform`, it calls `transform(rawValue)` and falls back to `defaultValue` if that returns `undefined` or `null`.
+- **`get<T>()` is a type cast without `transform`, not a runtime conversion.** Every `process.env` value is a `string`; asking for `get<number>('APP_ENV_PORT')` still returns a string at runtime unless you pass `transform: Number`.
+- **Stage detection is separate from the singleton.** `Environment.current` reads `process.env.NODE_ENV` directly (falling back to `'development'` when unset); `Environment.is({ name })` compares against it. `ApplicationEnvironment.isDevelopment()` is narrower - it checks `NODE_ENV === 'development'` exactly, so the `'dev'` alias returns `false` there even though it counts as a development stage everywhere else.
 
-```typescript
-import { ApplicationEnvironment } from '@venizia/ignis-helpers';
+**Deployment stages** (`Environment.*`)
 
-const customEnv = new ApplicationEnvironment({
-  prefix: 'MY_APP_ENV',
-  envs: process.env,
-});
+| Constant | Value | In `DEVELOPMENT_ENVS` |
+|----------|-------|------------------------|
+| `LOCAL` | `'local'` | yes |
+| `DEBUG` | `'debug'` | yes |
+| `DEVELOPMENT` | `'development'` | yes |
+| `DEV` | `'dev'` | yes - short spelling of `development` |
+| `SIT` | `'sit'` | yes |
+| `UAT` | `'uat'` | no |
+| `ALPHA` | `'alpha'` | no |
+| `BETA` | `'beta'` | no |
+| `STAGING` | `'staging'` | no |
+| `PRODUCTION` | `'production'` | no |
 
-const host = customEnv.get<string>('MY_APP_ENV_SERVER_HOST');
-```
+All ten stages are in `Environment.COMMON_ENVS`, which the Logger uses to decide whether `DEBUG=true` is honored. The five marked above are `Environment.DEVELOPMENT_ENVS` - the set IGNIS's error handler consults to decide whether a response may carry a stack trace or a raw driver message. The rule is fail-closed: `alpha`, `beta`, `uat`, `staging`, a typo'd name, and an unset `NODE_ENV` are all sanitized as production.
 
-#### Constructor Options
+## Common tasks
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `prefix` | `string` | -- (required) | Only keys starting with this prefix are included |
-| `envs` | `Record<string, string \| number \| undefined>` | -- (required) | The environment object to filter (typically `process.env`) |
+### Read a variable with a default
 
-The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` as the prefix and `process.env` as the environment source.
-
-## Usage
-
-### Reading Variables
-
-Use `get<ReturnType>(key, defaultValue?)` to retrieve a typed environment variable. Only keys matching the configured prefix are available. An optional `defaultValue` is returned when the key is not found.
+`defaultValue` goes inside the options object, not as a second positional argument.
 
 ```typescript
-import { applicationEnvironment } from '@venizia/ignis-helpers';
-
-const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
-const serverPort = applicationEnvironment.get<string>('APP_ENV_SERVER_PORT');
-const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', 5000);
-```
-
-> [!WARNING]
-> `get<T>()` performs a TypeScript type cast, not a runtime conversion. All `process.env` values are strings. If the raw value is `"3000"`, `get<number>()` still returns the string at runtime. Parse it yourself if needed.
-
-### Setting Variables
-
-Use `set<ValueType>(key, value)` to add or override a variable at runtime.
-
-```typescript
-applicationEnvironment.set('APP_ENV_FEATURE_FLAG', 'enabled');
+const port = applicationEnvironment.get<string>('APP_ENV_SERVER_PORT', { defaultValue: '3000' });
 ```
 
-### Listing Keys
+### Convert a value while reading it
 
-Use `keys()` to retrieve all filtered environment variable keys.
+Pass `transform` to parse instead of casting.
 
 ```typescript
-const allKeys = applicationEnvironment.keys();
-// e.g. ['APP_ENV_SERVER_HOST', 'APP_ENV_SERVER_PORT', 'APP_ENV_JWT_SECRET']
+const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', {
+  transform: value => Number(value),
+  defaultValue: 5000,
+});
 ```
 
-### Checking Development Mode
+### Set or merge variables at runtime
 
-Use `isDevelopment()` to check if `process.env.NODE_ENV` is `'development'`.
+`set()` writes a single key; `merge()` overwrites several at once - both bypass the prefix filter (they write directly, no `startsWith` check).
 
 ```typescript
-if (applicationEnvironment.isDevelopment()) {
-  // Enable verbose logging, seed data, etc.
-}
+applicationEnvironment.set('APP_ENV_FEATURE_FLAG', 'enabled');
+applicationEnvironment.merge({ envs: { APP_ENV_REGION: 'ap-southeast-1' } });
 ```
 
-### Environment Stage Detection
-
-The `Environment` class provides static helpers for checking the current `NODE_ENV`.
+### Branch on the deployment stage
 
 ```typescript
 import { Environment } from '@venizia/ignis-helpers';
 
-// Read the current stage (falls back to 'development' if NODE_ENV is unset)
-console.log(Environment.current);
-
-// Check a specific stage
-if (Environment.is({ name: 'staging' })) {
+if (Environment.is({ name: Environment.STAGING })) {
   // Staging-only behavior
 }
 ```
 
-#### Available Stages
-
-| Constant | Value | Development stage |
-|----------|-------|-------------------|
-| `Environment.LOCAL` | `'local'` | yes |
-| `Environment.DEBUG` | `'debug'` | yes |
-| `Environment.DEVELOPMENT` | `'development'` | yes |
-| `Environment.DEV` | `'dev'` | yes - the short spelling of `development` |
-| `Environment.SIT` | `'sit'` | yes |
-| `Environment.UAT` | `'uat'` | no |
-| `Environment.ALPHA` | `'alpha'` | no |
-| `Environment.BETA` | `'beta'` | no |
-| `Environment.STAGING` | `'staging'` | no |
-| `Environment.PRODUCTION` | `'production'` | no |
-
-All stages are collected in `Environment.COMMON_ENVS` (a `Set<string>`), which is used internally by the Logger to determine whether debug logging should be active. A `NODE_ENV` outside this set silences `DEBUG=true` entirely.
+### Use a custom prefix
 
-#### `Environment.DEVELOPMENT_ENVS` - the error-detail boundary
-
-The stages marked "development stage" above form `Environment.DEVELOPMENT_ENVS`. IGNIS's error handler consults this set to decide whether an error response may carry internal detail - a stack trace, a SQL constraint name, a raw driver message.
-
-The rule is fail-closed. A leak is opt-in by an explicit development name, so **anything else is sanitized as production**, including:
-
-- `alpha`, `beta`, `uat`, `staging` - real users reach these
-- an unrecognized name (a typo, a stage nobody added to the set)
-- `NODE_ENV` left unset
-
-Running a local service under `NODE_ENV=alpha` therefore gives you the same stripped-down error responses your users see. If you want the details while developing, set `NODE_ENV` to `development`, `dev`, or `local`.
-
-### Configuring the Prefix
-
-The default singleton reads `APPLICATION_ENV_PREFIX` from `process.env` to determine its prefix. Set this variable **before** any import of `@venizia/ignis-helpers`.
+Set `APPLICATION_ENV_PREFIX` before the first import of `@venizia/ignis-helpers` - the singleton is constructed at module load, so a later change has no effect on it.
 
 ```
 APPLICATION_ENV_PREFIX=MY_APP_ENV
-
 MY_APP_ENV_SERVER_HOST=0.0.0.0
-MY_APP_ENV_SERVER_PORT=3000
-```
-
-### Integration with BaseApplication
-
-The `applicationEnvironment` singleton is used by the framework's `BaseApplication` during startup to validate that all prefixed environment variables have non-empty values. If any key has an empty value, the application throws an error unless `ALLOW_EMPTY_ENV_VALUE` is set to a truthy value.
-
-```typescript
-// This validation runs automatically during application initialization.
-// To allow empty values, set in your environment:
-ALLOW_EMPTY_ENV_VALUE=true
-```
-
-## Troubleshooting
-
-### `get()` returns `undefined`
-
-**Cause:** The key does not start with the configured prefix, so it was filtered out during construction.
-
-**Fix:** Ensure your `.env` keys use the correct prefix:
-
 ```
-# Wrong -- missing prefix
-SERVER_PORT=3000
 
-# Correct -- matches default prefix
-APP_ENV_SERVER_PORT=3000
-```
-
-### Custom prefix not taking effect
-
-**Cause:** `APPLICATION_ENV_PREFIX` must be set **before** the module loads. If it is set after import, the singleton is already constructed with the default `APP_ENV`.
-
-**Fix:** Set the prefix in your `.env` file or at process start, before any import of `@venizia/ignis-helpers`:
-
-```
-APPLICATION_ENV_PREFIX=MY_APP_ENV
-```
-
-### `get<number>()` returns a string
-
-**Cause:** `get<T>()` performs a TypeScript type cast, not a runtime conversion. All `process.env` values are strings.
-
-**Fix:** Parse the value explicitly:
+### List every filtered key
 
 ```typescript
-const port = Number(applicationEnvironment.get<string>('APP_ENV_SERVER_PORT'));
+const allKeys = applicationEnvironment.keys();
+// e.g. ['APP_ENV_SERVER_HOST', 'APP_ENV_SERVER_PORT', 'APP_ENV_JWT_SECRET']
 ```
 
-### `[validateEnvs] Invalid Application Environment! Key: {key} | Value: {value}`
-
-**Cause:** During application startup, `BaseApplication.validateEnvs()` found a prefixed environment key with an empty or undefined value.
-
-**Fix:** Either provide a value for the key in your `.env` file, or allow empty values by setting:
+> [!TIP]
+> `BaseApplication` validates every prefixed key at startup and throws on an empty value unless `ALLOW_EMPTY_ENV_VALUE` is truthy - see [Application](/guides/core-concepts/application/).
 
-```
-ALLOW_EMPTY_ENV_VALUE=true
-```
+## See also
 
-## See Also
+- [Application](/guides/core-concepts/application/) - environment validation during startup
+- [Helpers Overview](/extensions/helpers/) - all available helpers
+- [Logger](/extensions/helpers/logger/) - uses `Environment.COMMON_ENVS` for debug log filtering
+- [Error](/extensions/helpers/error/) - uses `Environment.DEVELOPMENT_ENVS` to gate error detail
 
-- **Guides:**
-  - [Application](/guides/core-concepts/application/) -- Environment validation during startup
+**Files:**
 
-- **Other Helpers:**
-  - [Helpers Index](../index) -- All available helpers
-  - [Logger](/extensions/helpers/logger/) -- Uses `Environment.COMMON_ENVS` for debug log filtering
+- [`packages/helpers/src/modules/env/app-env.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/app-env.ts) - `Environment`, `ApplicationEnvironment`, the `applicationEnvironment` singleton
+- [`packages/helpers/src/modules/env/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/types.ts) - `IApplicationEnvironment` interface