envapt 8.1.1 → 8.2.1

package/dist/types/types/Options.d.mts

@@ -2,8 +2,8 @@ import { Environment } from "../core/Environment.mjs";
 import { EnvaptConverter } from "./Conversion.mjs";
 //#region src/types/Options.d.ts
 /**
- * Options for the \@Envapt decorator (modern API). `required: true` is mutually exclusive
- * with `fallback`; see the per-converter overloads in `Envapt.ts` for the type-level mutex.
+ * Options for the \@Envapt decorator (modern API). `required: true` and `fallback` cannot be
+ * used together, and the `@Envapt` overloads reject the pair at compile time.
  * @public
  * @see {@link https://envapt.materwelon.dev/docs/decorators#declaring-decorated-fields}
  */
@@ -21,27 +21,27 @@ interface EnvaptOptions<TFallback = string> {
  * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
  */
 interface EnvProfile {
-  /** One or more `.env` paths to load for this environment. Order matters: earlier paths take precedence. */
+  /** One or more `.env` paths to load for this environment. Earlier paths take precedence. */
   paths: string | string[];
 }
 /**
  * Configuration object for `Envapter.configureProfiles`. Maps each `Environment` to an optional
  * profile override. Unspecified environments fall through to the default cascade behavior
- * (`.env.${env}.local`, `.env.local`, `.env.${env}`, `.env`).
+ * (`.env.${env}.local`, `.env.${env}`, `.env.local`, `.env`).
  * @public
  * @see {@link https://envapt.materwelon.dev/docs/environment#custom-profiles}
  */
 type ProfilesConfig = Partial<Record<Environment, EnvProfile>> & {
   /**
    * When `false`, disables the default dotenv-flow cascade entirely. Only the explicitly
-   * configured paths are loaded. Defaults to `true` (cascade still runs, configured paths
-   * are layered on top with higher precedence).
+   * configured paths are loaded. Defaults to `true` (the cascade still runs and configured
+   * paths take higher precedence).
    */
   useDefaults?: boolean;
 };
 /**
  * How the portable build's filesystem-only config APIs behave when called. `'warn'` (the default)
- * warns once and no-ops, `'throw'` throws `FileApiUnsupported`. The node build runs these APIs
+ * warns once and no-ops. `'throw'` throws `FileApiUnsupported`. The node build runs these APIs
  * normally and is unaffected by this value.
  * @public
  * @see {@link https://envapt.materwelon.dev/docs/compatibility#binding-by-runtime}

package/dist/types/types/Schema.d.mts

@@ -7,5 +7,5 @@ type Err<Msg extends string> = Msg & {
 type SchemaMustBeSync = Err<'Schema must be synchronous. envapt is boot-time config loading; async refinements (validate returning `Promise<Result>`) belong outside the env layer.'>;
 type SchemaConstraint<Schema extends StandardSchemaV1> = ReturnType<Schema['~standard']['validate']> extends Promise<unknown> ? SchemaMustBeSync : Schema;
 //#endregion
-export type { Err, SchemaConstraint, SchemaMustBeSync };
+export type { SchemaConstraint };
 //# sourceMappingURL=Schema.d.mts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "envapt",
   "type": "module",
-  "version": "8.1.1",
+  "version": "8.2.1",
   "description": "Type-safe config for TypeScript. Read typed values from any source, process.env, .env files, Cloudflare Workers bindings, browser bundles, or any object you supply. Zero runtime dependencies, one API across Node, Bun, Deno, Workers, and the browser. TC39 accessor decorators (legacy decorators at envapt/legacy), converters, and Standard Schema (zod/valibot/arktype) validation.",
   "types": "./dist/types/index.d.mts",
   "exports": {
@@ -178,7 +178,7 @@
   "license": "Apache-2.0",
   "engines": {
     "node": ">=20.0.0",
-    "bun": ">=1.3.0",
+    "bun": ">=1.3.11",
     "deno": ">=2.5.0"
   },
   "publishConfig": {
@@ -186,16 +186,15 @@
     "provenance": true
   },
   "devDependencies": {
-    "@cloudflare/vitest-pool-workers": "0.18.0",
-    "@cloudflare/workers-types": "^5.20260730.1",
-    "@vitest/browser": "4.1.10",
-    "@vitest/browser-playwright": "4.1.10",
-    "arktype": "^2.2.2",
-    "esbuild": "^0.28.1",
-    "playwright": "1.61.1",
+    "@cloudflare/vitest-pool-workers": "0.22.0",
+    "@cloudflare/workers-types": "^5.20260911.1",
+    "@vitest/browser-playwright": "4.1.11",
+    "arktype": "^2.2.3",
+    "esbuild": "^0.28.2",
+    "playwright": "1.63.0",
     "typescript7": "npm:typescript@7.0.2",
-    "valibot": "^1.4.2",
-    "zod": "4.4.3"
+    "valibot": "^1.5.0",
+    "zod": "4.6.4"
   },
   "scripts": {
     "clean": "rm -rf dist",
@@ -208,7 +207,6 @@
     "fmt:check": "prettier --check '{src,tests,scripts}/**/*.{ts,tsx,json,md}' --cache",
     "fmt:all": "prettier --write .",
     "tc": "tsc --noEmit",
-    "tsd": "tsd",
     "test": "vitest run",
     "test:watch": "vitest dev",
     "test:integration": "node tests/integration/run.mjs",
@@ -231,5 +229,5 @@
     "bump": "pnpm tsx ../../scripts/release/bump-jsr.ts",
     "release": "pnpm run cs:publish"
   },
-  "readme": "<img src=\"https://raw.githubusercontent.com/materwelonDhruv/envapt/main/.github/assets/logo.png\" width=\"120\" align=\"left\" alt=\"envapt logo\" />\n\n<h3>envapt</h3>\n\n<p>\n  <strong>The apt way to read typed config.</strong><br/>\n  Read config from any source as real typed values, with zero runtime dependencies.\n</p>\n\n<p>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/envapt?logo=npm&logoColor=cb3838&label=%20&labelColor=103544&color=cb3838\"></a>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"downloads\" src=\"https://img.shields.io/npm/dm/envapt?style=flat&color=f7f6e8&labelColor=103544&label=downloads\"></a>\n  <a href=\"https://jsr.io/@materwelon/envapt\"><img alt=\"jsr\" src=\"https://jsr.io/badges/@materwelon/envapt\"></a>\n  <img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/materwelonDhruv/envapt/checks.yml?branch=main&label=tests&style=flat&logo=github&color=3fb950&labelColor=103544\">\n  <a href=\"LICENSE\"><img alt=\"License\" src=\"https://img.shields.io/npm/l/envapt?style=flat&color=e97826&logo=apache&label=\"></a>\n</p>\n\n<br clear=\"left\"/>\n\nenvapt returns config as the type you asked for instead of the `string | undefined` you get raw, with\na fallback that removes `undefined` from the return type. It reads from whatever source you bind. On\nNode, Bun, and Deno that is `process.env` and your `.env` files, bound on import. On Cloudflare\nWorkers, in the browser, or for a secrets object you fetched at boot, you bind the source with\n`Envapter.useSource(...)`.\n\n```ts\nimport { Converters, Envapter } from 'envapt';\n\nconst { port, databaseUrl, cacheTtl, allowedOrigins } = Envapter.getRequiredAll(\n    {\n        PORT: Converters.Port, // number, checked against 0-65535\n        DATABASE_URL: Converters.Url, // URL\n        CACHE_TTL: Converters.Time, // \"15m\" parsed to 900000\n        ALLOWED_ORIGINS: Converters.array() // string[]\n        // ... and many more built-in converters\n    },\n    'camelCase'\n);\n```\n\nCall that at startup and a missing value fails the boot, with one error naming every key that was\nmissing. Reads with a fallback (`Envapter.getNumber('WORKERS', 4)`) never throw.\n\n**[Read the docs →](https://envapt.materwelon.dev)**\n\n## What you get\n\n- **Typed values.** A fallback removes `undefined` from the return type. Built-in converters cover\n  numbers, integers, floats, booleans, bigint, symbols, JSON, URLs, regular expressions, dates,\n  durations, ports, emails, and arrays, or pass your own function or a Standard Schema validator\n  (zod, valibot, arktype).\n- **Any source.** A source is any object with a `readVars()` method, so you can bind `process.env`, a\n  Cloudflare Workers binding, a browser bundle, or a secrets payload you fetched from a store at boot.\n  On Node, Bun, and Deno one binds on import.\n- **Zero runtime dependencies.** The reader, converters, and built-in `.env` parser are self-contained,\n  so nothing is added to your dependency tree.\n- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3`, Deno\n  `>=2.5` (ESM and CJS). The portable build resolves through the package `exports`\n  conditions.\n- **`.env` loading built in on Node.** The default Node source adds a per-environment file cascade,\n  `${VAR}` templates, and strict / required checks. Off Node there is no filesystem, so you bind\n  another source with `Envapter.useSource(...)` and read with the same typed API.\n\n## Install\n\n```sh\nnpm install envapt\npnpm add envapt\nyarn add envapt\nbun add envapt\ndeno add jsr:@materwelon/envapt\n```\n\n## Quick start\n\nRead values functionally with `Envapter`, or bind them to class fields with the `@Envapt` decorator.\nBoth share the same parsing, converters, and cache.\n\n### Functional\n\nRead a value from any call site, in JavaScript or TypeScript. No build step. On Node the source is\nbound for you. On Workers and in the browser, call `Envapter.useSource(...)` first.\n\n```ts\nimport { Converters, Envapter } from 'envapt';\n\nconst requestTimeout = Envapter.getUsing('REQUEST_TIMEOUT', Converters.Time, '30s'); // 30000\nconst maxRetries = Envapter.getNumber('MAX_RETRIES', 3);\nconst debug = Envapter.getBoolean('DEBUG', false);\n```\n\nOn Cloudflare Workers, `env` is importable at module scope, so bind it once in a config module, and in\nthe browser seed a `PortableSource` from the object your bundler injects.\n\n```ts\nimport { env } from 'cloudflare:workers';\nimport { Envapter, PortableSource } from 'envapt';\n\nEnvapter.useSource(new PortableSource(env));\n\nexport const apiToken = Envapter.get('API_TOKEN');\n```\n\n### Decorator\n\nBind a value to a class field with a TC39 accessor decorator. No `experimentalDecorators` flag, and it runs on Bun and Deno from `.ts` directly.\n\n```ts\nimport { Converters, Envapt, EnvTime } from 'envapt';\n\nclass Config {\n    @Envapt('PORT', { converter: Converters.Port, fallback: 3000 })\n    static accessor port: number;\n\n    @EnvTime('CACHE_TTL', '15m')\n    static accessor cacheTtl: number;\n}\n```\n\nThe legacy (experimentalDecorators) decorators are exported from `envapt/legacy`.\n\n## Agent skill\n\nInstall the envapt agent skill so AI coding tools use the correct API:\n\n```sh\nnpx skills add materwelonDhruv/envapt\n```\n\n---\n\n<p align=\"center\"><sub>Built by <a href=\"https://github.com/materwelondhruv\">@materwelonDhruv</a> · Apache 2.0</sub></p>\n"
+  "readme": "<img src=\"https://raw.githubusercontent.com/materwelonDhruv/envapt/main/.github/assets/logo.png\" width=\"120\" align=\"left\" alt=\"envapt logo\" />\n\n<h3>envapt</h3>\n\n<p>\n  <strong>The apt way to read typed config.</strong><br/>\n  Read config from any source as real typed values, with zero runtime dependencies.\n</p>\n\n<p>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/envapt?logo=npm&logoColor=cb3838&label=%20&labelColor=103544&color=cb3838\"></a>\n  <a href=\"https://www.npmjs.com/package/envapt\"><img alt=\"downloads\" src=\"https://img.shields.io/npm/dm/envapt?style=flat&color=f7f6e8&labelColor=103544&label=downloads\"></a>\n  <a href=\"https://jsr.io/@materwelon/envapt\"><img alt=\"jsr\" src=\"https://jsr.io/badges/@materwelon/envapt\"></a>\n  <img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/materwelonDhruv/envapt/checks.yml?branch=main&label=tests&style=flat&logo=github&color=3fb950&labelColor=103544\">\n  <a href=\"LICENSE\"><img alt=\"License\" src=\"https://img.shields.io/npm/l/envapt?style=flat&color=e97826&logo=apache&label=\"></a>\n</p>\n\n<br clear=\"left\"/>\n\nenvapt returns config as the type you asked for, with a fallback that removes `undefined` from the\nreturn type. It reads from whatever source you bind. On Node, Bun, and Deno that is `process.env`\nand your `.env` files, bound on import. On Cloudflare Workers, in the browser, or for a secrets\nobject you fetched at boot, you bind the source with `Envapter.useSource(...)`.\n\n```ts\nimport { Converters, Envapter } from 'envapt';\n\nconst { port, databaseUrl, cacheTtl, allowedOrigins } = Envapter.getRequiredAll(\n    {\n        PORT: Converters.Port, // number, checked against 0-65535\n        DATABASE_URL: Converters.Url, // URL\n        CACHE_TTL: Converters.Time, // \"15m\" parsed to 900000\n        ALLOWED_ORIGINS: Converters.array() // string[]\n        // ... and many more built-in converters\n    },\n    'camelCase'\n);\n```\n\nCall that at startup and a missing value fails the boot, with one error naming every key that was\nmissing. Reads with a fallback (`Envapter.getNumber('WORKERS', 4)`) never throw.\n\n**[Read the docs →](https://envapt.materwelon.dev)**\n\n## What you get\n\n- **Typed values.** A fallback removes `undefined` from the return type. Built-in converters cover\n  numbers, integers, floats, booleans, bigint, symbols, JSON, URLs, regular expressions, dates,\n  durations, ports, emails, and arrays, or pass your own function or a Standard Schema validator\n  (zod, valibot, arktype).\n- **Any source.** A source is any object with a `readVars()` method, so you can bind `process.env`, a\n  Cloudflare Workers binding, a browser bundle, or a secrets payload you fetched from a store at boot.\n  On Node, Bun, and Deno one binds on import.\n- **Zero runtime dependencies.** The reader, converters, and built-in `.env` parser are self-contained,\n  so nothing is added to your dependency tree.\n- **Runs on Node, Bun, Deno, Cloudflare Workers, and the browser.** Node `>=20`, Bun `>=1.3.11`, Deno\n  `>=2.5` (ESM and CJS). The portable build resolves through the package `exports`\n  conditions.\n- **`.env` loading built in on Node.** The default Node source adds a per-environment file cascade,\n  `${VAR}` templates, and strict / required checks. Off Node there is no filesystem, so you bind\n  another source with `Envapter.useSource(...)` and read with the same typed API.\n\n## Install\n\n```sh\nnpm install envapt\npnpm add envapt\nyarn add envapt\nbun add envapt\ndeno add jsr:@materwelon/envapt\n```\n\n## Quick start\n\nRead values functionally with `Envapter`, or bind them to class fields with the `@Envapt` decorator.\nBoth share the same parsing, converters, and cache.\n\n### Functional\n\nRead a value from any call site, in JavaScript or TypeScript. No build step. On Node the source is\nbound for you. On Workers and in the browser, call `Envapter.useSource(...)` first.\n\n```ts\nimport { Converters, Envapter } from 'envapt';\n\nconst requestTimeout = Envapter.getUsing('REQUEST_TIMEOUT', Converters.Time, '30s'); // 30000\nconst maxRetries = Envapter.getNumber('MAX_RETRIES', 3);\nconst debug = Envapter.getBoolean('DEBUG', false);\n```\n\nOn Cloudflare Workers, `env` is importable at module scope, so bind it once in a config module, and in\nthe browser seed a `PortableSource` from the object your bundler injects.\n\n```ts\nimport { env } from 'cloudflare:workers';\nimport { Envapter, PortableSource } from 'envapt';\n\nEnvapter.useSource(new PortableSource(env));\n\nexport const apiToken = Envapter.get('API_TOKEN');\n```\n\n### Decorator\n\nBind a value to a class field with a TC39 accessor decorator. No `experimentalDecorators` flag, and it runs on Bun and Deno from `.ts` directly.\n\n```ts\nimport { Converters, Envapt, EnvTime } from 'envapt';\n\nclass Config {\n    @Envapt('PORT', { converter: Converters.Port, fallback: 3000 })\n    static accessor port: number;\n\n    @EnvTime('CACHE_TTL', '15m')\n    static accessor cacheTtl: number;\n}\n```\n\nThe legacy (experimentalDecorators) decorators are exported from `envapt/legacy`.\n\n## Agent skill\n\nInstall the envapt agent skill so AI coding tools use the correct API:\n\n```sh\nnpx skills add materwelonDhruv/envapt\n```\n\n---\n\n<p align=\"center\"><sub>Built by <a href=\"https://github.com/materwelondhruv\">@materwelonDhruv</a> · Apache 2.0</sub></p>\n"
 }