envapt 5.2.0-next.2 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # envapt
 
+## 5.2.0
+
+### Minor Changes
+
+- e506a6d: `Envapter` now detects the test environment and reads Vite's `MODE`.
+    - `Environment.Test` and `Envapter.isTest` are added. `NODE_ENV=test` (and Vite's `MODE=test`) now resolve to `Environment.Test`, where they previously fell through to `Development`. As a result, `isDevelopment` is no longer `true` under a test runner that sets `NODE_ENV=test`.
+    - `MODE` joins the detection chain, after `ENVIRONMENT`, `ENV`, and `NODE_ENV`. Vite-family browser builds expose `import.meta.env.MODE` but none of the others, so `new ManualEnvSource(import.meta.env)` now sets the environment from `MODE`.
+    - Environment names match case-insensitively. Previously `staging` was matched case-sensitively, so `STAGING` or `Staging` fell through to `Development`; `production` was already case-insensitive.
+    - When no environment key is set, or its value is unrecognized, detection defaults to `Development` and emits a debug warning (visible with `Envapter.debug = 'warn'`).
+
+- e506a6d: envapt now runs on the browser and Cloudflare Workers, not only Node. The engine reads variables through a pluggable `EnvSource` instead of reading `process.env` directly, so the same `Envapter` and `@Envapt` API works against an injected object or a Workers binding.
+
+    `Envapter.useSource(source)` binds the source; the bound source then backs every read, the `.env` cascade, and `Envapter.syncProcessEnv`. Built-in sources, all exported from `envapt`:
+    - `NodeEnvSource`: a `process.env` snapshot plus the `.env` cascade. Bound automatically on Node, Bun, and Deno, so you do not call `useSource` yourself.
+    - `WorkerEnvSource`: reads a Cloudflare Workers `env` binding. Non-string bindings are JSON-stringified so the converters still apply.
+    - `ManualEnvSource`: reads any object you pass in, snapshotted at construction, with non-string values JSON-stringified like `WorkerEnvSource`. Pass `import.meta.env` or a bundler-injected object directly on the browser, or a plain object in tests.
+
+    ```ts
+    import { Envapter, ManualEnvSource } from 'envapt';
+
+    Envapter.useSource(new ManualEnvSource({ PORT: '3000', FLAG: 'true' }));
+    Envapter.getNumber('PORT'); // 3000
+    ```
+
+    The core imports no `node:*` module: `node:fs`, `node:path`, `node:process`, and `node:url` are confined to `NodeEnvSource`. envapt ships a build per runtime, so a Workers or browser bundle pulls in no Node built-ins, and workerd needs no `nodejs_compat` flag. Bare `envapt` resolves the right build through the `exports` conditions, and the dedicated `envapt/workerd` and `envapt/browser` entries add the matching types, which omit the file-only APIs so a stray call is a compile error rather than a runtime `FileApiUnsupported`.
+
+    Two new `EnvaptErrorCodes` replace silent no-ops with a thrown error:
+    - `NoSourceBound` (307): thrown on the first read when no source is bound.
+    - `FileApiUnsupported` (306): thrown when `envPaths`, `baseDir`, or `configureProfiles` is called on a source without a filesystem.
+
+    `EnvSource` is a union of `BareEnvSource` (no filesystem) and `FileEnvSource` (which requires `readFile`, `resolvePath`, `normalizeBaseDir`, and `writeVars` together), so a custom source has either the full file API or none of it.
+
+    On Node, the `.env` cascade now loads when envapt is first imported rather than on the first variable read.
+
+### Patch Changes
+
+- bad5f6b: update package.json desc and engines/os
+- e506a6d: `Converters.Time` string fallbacks now accept decimals, matching raw env values.
+
+    A fallback like `'1.5h'` previously threw `MalformedTimeFallback` even though the `TimeFallback` type (`` `${number}${TimeUnit}` ``) accepts it at compile time. Raw env values already allowed decimals, so the restriction only applied to fallbacks, which was inconsistent. A string fallback still requires an explicit unit (a unitless number is a number fallback), but `'1.5h'` now resolves to `5400000`.
+
+- b8e26dd: Move the build and lint toolchain to TypeScript 6.0. No public API or runtime change.
+
 ## 5.2.0-next.2
 
 ### Patch Changes

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "envapt",
   "type": "module",
-  "version": "5.2.0-next.2",
+  "version": "5.2.0",
   "description": "Type-safe environment variables for TypeScript. Zero-dependency .env loader and parser with one API across Node, Bun, Deno, Cloudflare Workers, and the Browser. Decorators, converters, Standard Schema (zod/valibot/arktype) validation, and much more.",
   "types": "./dist/node/index.d.mts",
   "exports": {