celery-env 0.1.0 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>Environment validation that compiles to tiny standalone JavaScript.</strong>
+  <strong>Type-safe process.env validation that compiles to tiny standalone JavaScript.</strong>
 </p>
 
 <p align="center">
@@ -22,10 +22,18 @@ messages, and fast startup.
 
 ## Install
 
+Generated mode:
+
 ```sh
 npm install -D celery-env
 ```
 
+Runtime mode:
+
+```sh
+npm install celery-env
+```
+
 Other package managers:
 
 ```sh
@@ -74,6 +82,9 @@ import { loadEnv } from "./env.mjs";
 export const env = loadEnv(process.env);
 ```
 
+Celery validates the env object you pass. Load `.env` with your platform,
+shell, or `dotenv` before calling `loadEnv`.
+
 That is the main path: write `env.schema.mjs`, generate `src/env.mjs`, and use
 the typed result everywhere else.
 
@@ -91,6 +102,15 @@ If you already use Zod for forms, API payloads, or general data validation,
 keep using it there. Celery is for the narrower `process.env` problem where
 defaults, examples, generated files, and startup cost matter.
 
+## Quick Comparison
+
+| Choose | When |
+| --- | --- |
+| Celery generated mode | You want a committed standalone validator, generated TypeScript declarations, generated `.env.example`, no production dependency, or lower cold-start cost. |
+| Celery runtime mode | You like Celery's schema API but cannot add generation yet. |
+| Zod | You need general object, form, API, or nested data validation. |
+| Envalid / Envsafe / env-var | You want mature runtime-only env validation with no generated files. |
+
 ## Why Use It
 
 - **Generated validator**: no schema walk during app startup.
@@ -118,20 +138,37 @@ export const env = parseEnv(schema, process.env);
 
 ## Benchmarks
 
-Current report: Node v26.3.0, macOS arm64, Apple M3.
-
-| Metric | Result |
-| --- | ---: |
-| Valid real-schema geometric mean | 1.50x over best external competitor |
-| Real `process.env` geometric mean | 1.14x over best external competitor |
-| Invalid real-schema geometric mean | 1.32x over best external competitor |
-| Cold first validation | 2.42x faster than best external competitor |
-| Generated validator size | 526 gzip bytes |
-| Smallest external bundle gap | 2.15x smaller |
-
-Competitors measured include Zod, Valibot, Envalid, Envsafe, env-var, T3 Env
-Core, Valienv, env-schema, env-type-validator, safe-env-vars, and Convict where
-the benchmark applies. The claim is specific to this env-validation corpus.
+Snapshot: Node v26.3.0, macOS arm64, Apple M3, generated on 2026-06-24. Higher
+ops/sec is better; lower milliseconds and bytes are better. Generated-mode
+numbers exclude compile/generation cost.
+
+| Tool / mode | Real schemas ops/sec | Real `process.env` ops/sec | Invalid ops/sec | Cold first validation | Gzip snapshot |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Celery generated | 1,411,473 | 228,570 | 112,361 | 1.849 ms | 526 B |
+| Celery runtime | 776,241 | 185,124 | 96,846 | 2.598 ms | 2,779 B |
+| Zod | 516,820 | 141,126 | 39,760 | 33.999 ms | 20,894 B |
+| Valibot | 454,925 | 109,584 | 84,841 | 6.925 ms | 2,055 B |
+| Envalid | 125,202 | 85,436 | 16,731 | 9.598 ms | 7,318 B |
+| Envsafe | 940,564 | 184,818 | 19,359 | 5.694 ms | 3,292 B |
+| env-var | 51,287 | 44,727 | 31,922 | 7.679 ms | 2,969 B |
+| T3 Env Core | 316,627 | 168,740 | 10,264 | 32.366 ms | 19,531 B |
+
+The benchmark corpus includes realistic API, web, worker, list-heavy, and
+JSON-heavy env schemas. Results are workload-specific; real `process.env` access
+narrows some gaps compared with frozen plain env objects.
+
+Current npm package metadata:
+
+| Package | Version checked | Runtime deps | Unpacked npm size | Files |
+| --- | ---: | ---: | ---: | ---: |
+| `celery-env` | 0.1.2 | 0 | 95.7 kB | 20 |
+| `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
+| `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
+| `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |
+| `envsafe` | 2.0.3 | 0 | 91.4 kB | 27 |
+| `env-var` | 7.5.0 | 0 | 42.9 kB | 30 |
+
+Metadata checked with `npm view` on 2026-06-25.
 
 ## Documentation
 

package/docs/BENCHMARKS.md

@@ -6,16 +6,34 @@ not the local benchmark lab.
 
 ## Current Headline
 
-Current report: Node v26.3.0, macOS arm64, Apple M3.
+Snapshot: Node v26.3.0, V8 14.6.202.34-node.20, macOS arm64, Apple M3,
+generated on 2026-06-24. Higher ops/sec is better; lower milliseconds and bytes
+are better. Generated-mode numbers exclude compile/generation cost.
 
-| Metric | Result |
-| --- | ---: |
-| Valid real-schema geometric mean | 1.50x over best external competitor |
-| Real `process.env` geometric mean | 1.14x over best external competitor |
-| Invalid real-schema geometric mean | 1.32x over best external competitor |
-| Cold first validation | 2.42x faster than best external competitor |
-| Generated validator size | 526 gzip bytes |
-| Smallest external bundle gap | 2.15x smaller |
+| Tool / mode | Primary use | Generated no-dep validator | Real schemas ops/sec geom mean | Real `process.env` ops/sec geom mean | Invalid ops/sec geom mean | Cold first validation | Gzip snapshot |
+| --- | --- | --- | ---: | ---: | ---: | ---: | ---: |
+| Celery generated | Env config | Yes | 1,411,473 | 228,570 | 112,361 | 1.849 ms | 526 B |
+| Celery runtime | Env config | No | 776,241 | 185,124 | 96,846 | 2.598 ms | 2,779 B |
+| Zod | General validation | No | 516,820 | 141,126 | 39,760 | 33.999 ms | 20,894 B |
+| Valibot | General validation | No | 454,925 | 109,584 | 84,841 | 6.925 ms | 2,055 B |
+| Envalid | Env validation | No | 125,202 | 85,436 | 16,731 | 9.598 ms | 7,318 B |
+| Envsafe | Env validation | No | 940,564 | 184,818 | 19,359 | 5.694 ms | 3,292 B |
+| env-var | Env accessors | No | 51,287 | 44,727 | 31,922 | 7.679 ms | 2,969 B |
+| T3 Env Core | Typed env schema | No | 316,627 | 168,740 | 10,264 | 32.366 ms | 19,531 B |
+
+Summary against the best external per-case baseline:
+
+| Metric | Celery generated | Best external per-case baseline | Result |
+| --- | ---: | ---: | ---: |
+| Valid real-schema geometric mean | 1,411,473 ops/sec | 940,564 ops/sec | 1.50x |
+| Real `process.env` geometric mean | 228,570 ops/sec | 200,908 ops/sec | 1.14x |
+| Invalid real-schema geometric mean | 112,361 ops/sec | 84,841 ops/sec | 1.32x |
+| Cold first validation | 1.849 ms | 4.466 ms | 2.42x faster |
+| Shipped gzip snapshot | 526 B | 1,130 B | 2.15x smaller |
+
+These are results from the env-validation corpus. They are useful for choosing
+a tool, but they are not a guarantee for every schema, host runtime, or
+deployment shape.
 
 ## What Is Measured
 
@@ -32,11 +50,59 @@ The benchmark corpus includes Zod, Valibot, Envalid, Envsafe, env-var, T3 Env
 Core, Valienv, env-schema, env-type-validator, safe-env-vars, and Convict where
 the benchmark applies.
 
+Snapshot dependency versions:
+
+| Package | Version |
+| --- | ---: |
+| `zod` | 4.4.3 |
+| `valibot` | 1.4.1 |
+| `envalid` | 8.2.0 |
+| `envsafe` | 2.0.3 |
+| `env-var` | 7.5.0 |
+| `@t3-oss/env-core` | 0.13.11 |
+| `valienv` | 1.1.0 |
+| `env-schema` | 7.0.0 |
+| `env-type-validator` | 1.0.1 |
+| `safe-env-vars` | 1.0.8 |
+| `convict` | 6.2.5 |
+
+## Package Metadata
+
+Package footprint is separate from runtime speed. Current npm metadata checked
+on 2026-06-25:
+
+| Package | Version Checked | Runtime Deps | Unpacked npm Size | Files |
+| --- | ---: | ---: | ---: | ---: |
+| `celery-env` | 0.1.2 | 0 | 95.7 kB | 20 |
+| `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
+| `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
+| `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |
+| `envsafe` | 2.0.3 | 0 | 91.4 kB | 27 |
+| `env-var` | 7.5.0 | 0 | 42.9 kB | 30 |
+
+Celery's generated validator size can be much smaller than the package size
+because generated mode ships only the emitted validator in production code.
+
+## Reproducibility
+
+The published package intentionally does not ship the local benchmark lab or
+competitor dependencies. Public docs keep the benchmark summary and claim rules
+so the npm package stays small and dependency-free.
+
+When refreshing claims, record:
+
+- `celery-env` version or commit;
+- Node version, operating system, CPU, and date;
+- competitor package versions;
+- whether the row uses frozen env objects or real `process.env`;
+- whether errors are aggregate or fail-fast;
+- generated validator gzip size separately from npm package size.
+
 ## Claim Rules
 
 Use precise benchmark claims:
 
-- Good: "1.50x over the best external competitor on the real-schema corpus."
+- Good: "1.50x over the best external per-case baseline on the real-schema corpus."
 - Good: "526 gzip bytes for the measured small generated validator."
 - Avoid: "Celery is always 50x faster."
 

package/docs/CLI.md

@@ -45,6 +45,7 @@ Use `generate` after editing `env.schema.mjs`.
 | `--fail-fast` | Throw on the first error instead of aggregating errors. |
 | `--force` | Overwrite existing generated files. |
 | `--optimize speed` | Emit larger speed-prioritized code for supported cases. |
+| `--version`, `-v` | Print the installed CLI version. |
 
 ## Recommended App Command
 
@@ -53,7 +54,7 @@ Add a script:
 ```json
 {
   "scripts": {
-    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify"
+    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify --force"
   }
 }
 ```

package/docs/COMPARISON.md

@@ -3,6 +3,16 @@
 Celery is not a replacement for general validation libraries. It is a focused
 tool for environment configuration.
 
+## Quick Decision Guide
+
+| Choose | When |
+| --- | --- |
+| Celery generated mode | You want a committed standalone validator, generated TypeScript declarations, generated `.env.example`, no production dependency, or lower cold-start cost. |
+| Celery runtime mode | You like Celery's schema API but cannot add generation yet. |
+| Zod | You already need general object validation, nested data validation, or shared schemas beyond `process.env`. |
+| Envalid / Envsafe / env-var | You want a mature runtime-only env validator with no generated files or build step. |
+| Stay with your current tool | Env validation is not on the startup path and generated artifacts would add workflow friction. |
+
 ## Celery vs Zod
 
 Zod is excellent for general TypeScript validation: forms, API payloads,
@@ -38,15 +48,41 @@ Celery's main difference is generated mode:
 - TypeScript declarations can be generated from the same schema;
 - `.env.example` can be generated from schema metadata.
 
-## Choosing A Mode
+## Generated vs Runtime Mode
+
+| Question | Generated mode | Runtime mode |
+| --- | --- | --- |
+| Production dependency on `celery-env` | No | Yes |
+| Build or generate step | Yes | No |
+| Startup cost | Lowest | Schema parsed at runtime |
+| Generated `.d.ts` | Yes | Use `InferEnv` |
+| Generated `.env.example` | Yes | Only if you run the CLI |
+| Best fit | Services, serverless, production apps | Scripts, prototypes, no-build projects |
+
+## Choose Another Tool When
 
-| Use Case | Recommended Mode |
+| Need | Better Fit |
 | --- | --- |
-| Production app or service | Generated |
-| Serverless or cold-start-sensitive app | Generated |
-| CLI script or small internal tool | Runtime |
-| Prototype before deciding schema shape | Runtime |
-| App with no build/generate step allowed | Runtime |
+| General object, form, API, or nested JSON validation | Zod |
+| Runtime-only env validation with no generated artifacts | Envalid / Envsafe / env-var |
+| Built-in `.env` file loading | dotenv plus a validator |
+| Maximum ecosystem maturity | Zod or established env validators |
+| No schema execution during build or generation | A static config format or runtime-only validator |
+
+## Package Footprint
+
+This table is npm package metadata, not benchmark speed:
+
+| Package | Version Checked | Runtime Deps | Unpacked npm Size | Files |
+| --- | ---: | ---: | ---: | ---: |
+| `celery-env` | 0.1.2 | 0 | 95.7 kB | 20 |
+| `zod` | 4.4.3 | 0 | 4.56 MB | 718 |
+| `valibot` | 1.4.1 | 0 | 1.84 MB | 9 |
+| `envalid` | 8.2.0 | 1 | 88.8 kB | 39 |
+| `envsafe` | 2.0.3 | 0 | 91.4 kB | 27 |
+| `env-var` | 7.5.0 | 0 | 42.9 kB | 30 |
+
+Checked with `npm view` on 2026-06-25.
 
 ## What Celery Does Not Do
 

package/docs/GETTING_STARTED.md

@@ -1,7 +1,6 @@
 # Getting Started
 
-This guide assumes you have a Node project and want one reliable place to define
-environment variables.
+This guide shows the generated-validator path for a Node project.
 
 ## 1. Install
 
@@ -15,12 +14,12 @@ yarn add -D celery-env
 bun add -d celery-env
 ```
 
-Use a dev dependency when you generate validators. The generated output has no
-runtime dependency on `celery-env`.
+Generated validators do not need `celery-env` at runtime, so most apps install
+it as a dev dependency.
 
 ## 2. Create A Schema
 
-Create `env.schema.mjs` in your project root:
+Create `env.schema.mjs`:
 
 ```js
 import { bool, defineEnv, int, oneOf, str, url } from "celery-env";
@@ -63,7 +62,7 @@ npx celery-env generate \
   --minify
 ```
 
-This creates:
+The command writes:
 
 | File | Purpose |
 | --- | --- |
@@ -71,12 +70,12 @@ This creates:
 | `src/env.d.ts` | Types for editors and TypeScript. |
 | `.env.example` | Documented env template. |
 
-Add the command to `package.json` so the workflow is repeatable:
+Add a script so generation is repeatable:
 
 ```json
 {
   "scripts": {
-    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify"
+    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify --force"
   }
 }
 ```
@@ -89,12 +88,14 @@ import { loadEnv } from "./env.mjs";
 export const env = loadEnv(process.env);
 ```
 
+Celery validates the env object you pass. Load `.env` with your platform,
+shell, or `dotenv` before calling `loadEnv`.
+
 Use `env` everywhere else instead of reading `process.env` directly.
 
-## 5. Use A Nested App Config
+## 5. Optional: Shape App Config
 
-If your app already expects a nested config object, keep the generated env flat
-and adapt it in one small file:
+Keep the generated env flat. If your app wants nested config, adapt it once:
 
 ```js
 import { loadEnv } from "./env.mjs";
@@ -126,6 +127,21 @@ For most apps, commit all of these:
 Committing generated files keeps deployments simple because production does not
 need to run the generator.
 
+## Keep Generated Files In Sync
+
+Regenerate after changing `env.schema.mjs`:
+
+```sh
+npm run env:generate
+```
+
+In CI, verify generated files are current:
+
+```sh
+npm run env:generate
+git diff --exit-code src/env.mjs src/env.d.ts .env.example
+```
+
 ## Next Steps
 
 - Read [Schema API](SCHEMA.md) when adding validators.

package/docs/README.md

@@ -9,7 +9,7 @@ Start here if you are new to Celery or new to typed env validation.
 3. [CLI](CLI.md): `init`, `generate`, and generation flags.
 4. [TypeScript](TYPESCRIPT.md): generated types and `InferEnv`.
 5. [Runtime Mode](RUNTIME.md): use Celery without generation.
-6. [Comparison](COMPARISON.md): when to use Celery instead of general validators.
+6. [Comparison](COMPARISON.md): when to choose Celery, Zod, Envalid, Envsafe, or runtime-only env validators.
 7. [Troubleshooting](TROUBLESHOOTING.md): common setup and generation issues.
 8. [Migration Guide](MIGRATION.md): add Celery to an existing project.
 9. [Benchmarks](BENCHMARKS.md): what is measured and what claims are safe.

package/docs/SCHEMA.md

@@ -41,8 +41,8 @@ options describe defaults, examples, and environment-specific behavior.
 | `example` | Example value used in generated `.env.example`. |
 | `docs` | Longer documentation text for generated metadata. |
 
-`testDefault` wins over `devDefault`, and `default` applies in every
-environment.
+`testDefault` wins over `devDefault`, and both env-specific defaults win over
+`default`.
 
 ## Missing Values
 
@@ -70,8 +70,9 @@ int({ min: 1, max: 65535 })
 num({ min: 0, max: 1 })
 ```
 
-By default, numeric parsing follows JavaScript `Number()`. Use `strict: true`
-to reject values such as hex and exponent notation:
+By default, numeric parsing follows JavaScript `Number()`. For ports, limits,
+rates, and other config values, prefer `strict: true` to reject values such as
+hex and exponent notation:
 
 ```js
 int({ strict: true })

package/docs/assets/celery-mark.svg

@@ -1,7 +1,29 @@
 <svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
   <title id="title">celery-env mark</title>
-  <desc id="desc">A compact green celery-env leaf mark.</desc>
-  <rect width="128" height="128" rx="28" fill="#0F766E"/>
-  <path d="M71 19c-7 9-11 18-12 27 12-3 23-11 34-24 3 21-9 37-31 45 12 6 24 7 38 3-13 18-30 25-50 22-8-1-15-5-20-10 8-2 15-5 21-10-13-3-22-12-26-26 13 7 25 10 36 7-2-10 1-21 10-34Z" fill="#D9F99D"/>
-  <path d="M38 103c16-2 32-2 48 0" stroke="#ECFDF5" stroke-width="8" stroke-linecap="round"/>
+  <desc id="desc">A dark green terminal-inspired C mark with celery leaves.</desc>
+  <defs>
+    <linearGradient id="bg" x1="18" y1="10" x2="110" y2="118" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#064E3B"/>
+      <stop offset="1" stop-color="#022C22"/>
+    </linearGradient>
+    <linearGradient id="leaf" x1="38" y1="18" x2="94" y2="108" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#ECFCCB"/>
+      <stop offset="0.48" stop-color="#86EFAC"/>
+      <stop offset="1" stop-color="#22C55E"/>
+    </linearGradient>
+    <filter id="shadow" x="13" y="16" width="102" height="99" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse">
+      <feDropShadow dx="0" dy="8" stdDeviation="7" flood-color="#011B16" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+  <rect width="128" height="128" rx="30" fill="url(#bg)"/>
+  <path d="M104 78c0 18-13 29-36 29H46c-14 0-24-10-24-24V54c0-23 15-37 40-37h42v61Z" fill="#0F766E" opacity="0.42"/>
+  <g filter="url(#shadow)">
+    <path d="M87 92c-7 7-16 11-27 11-23 0-39-16-39-39 0-24 17-40 41-40 11 0 20 4 27 11" stroke="url(#leaf)" stroke-width="15" stroke-linecap="round"/>
+    <path d="M69 24c4-10 12-15 24-15-1 12-8 20-21 24" fill="#BBF7D0"/>
+    <path d="M57 25c-2-10-8-17-19-20-2 12 3 21 16 28" fill="#4ADE80"/>
+    <path d="M66 30c2-11 9-20 21-25 1 14-5 24-19 32" fill="#86EFAC"/>
+  </g>
+  <path d="M48 57l13 9-13 9" stroke="#ECFDF5" stroke-width="7" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M70 77h24" stroke="#D9F99D" stroke-width="7" stroke-linecap="round"/>
+  <path d="M38 33h50" stroke="#ECFDF5" stroke-opacity="0.18" stroke-width="4" stroke-linecap="round"/>
 </svg>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "celery-env",
-  "version": "0.1.0",
-  "description": "Zero-dependency environment validation with generated standalone validators.",
+  "version": "0.1.2",
+  "description": "Type-safe process.env validation that generates zero-dependency standalone validators.",
   "type": "module",
   "types": "./src/index.d.ts",
   "sideEffects": false,
@@ -55,20 +55,31 @@
     "size": "node scripts/size.mjs",
     "security:scan": "node scripts/security-scan.mjs && npm run prepublishOnly",
     "validate:publish": "node scripts/validate-publish.mjs",
-    "prepublishOnly": "npm test && npm run size && npm run validate:publish",
+    "smoke:pack": "node scripts/smoke-pack.mjs",
+    "prepublishOnly": "npm test && npm run size && npm run validate:publish && npm run smoke:pack",
     "demo:generate": "node src/cli.js --schema examples/env.schema.mjs --out .tmp/generated/env.mjs --types .tmp/generated/env.d.ts"
   },
   "keywords": [
     "env",
-    "validation",
+    "env-var",
+    "env-vars",
     "environment",
+    "environment-variables",
+    "process-env",
+    "env-validation",
+    "env-validator",
+    "validation",
     "config",
+    "configuration",
+    "config-validation",
     "schema",
+    "type-safe",
     "typescript",
-    "serverless",
-    "zod",
+    "typed-env",
+    "node",
     "dotenv",
-    "cli"
+    "cli",
+    "serverless"
   ],
   "license": "MIT",
   "engines": {

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { constants } from "node:fs";
-import { mkdir, open, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -9,6 +9,10 @@ const NOFOLLOW = constants.O_NOFOLLOW || 0;
 const args = parseArgs(process.argv.slice(2));
 
 if (args.help) usage(0);
+if (args.version) {
+  console.log(await packageVersion());
+  process.exit(0);
+}
 
 if (args.command === "init") {
   await init(args);
@@ -61,6 +65,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") out.help = true;
+    else if (arg === "--version" || arg === "-v") out.version = true;
     else if (arg === "--schema") out.schema = argv[++i];
     else if (arg === "--target") out.target = argv[++i];
     else if (arg === "--out") out.out = argv[++i];
@@ -124,10 +129,16 @@ export default defineEnv({
   throw new Error(`Unknown init target: ${target}`);
 }
 
+async function packageVersion() {
+  const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  return pkg.version;
+}
+
 function usage(code) {
   console.log(`Usage:
   celery-env --schema env.schema.mjs --out src/env.mjs [--types src/env.d.ts]
   celery-env generate --schema env.schema.mjs --out src/env.mjs [--types src/env.d.ts] [--example .env.example] [--force] [--optimize speed]
-  celery-env init --target node|next|vite --schema env.schema.mjs`);
+  celery-env init --target node|next|vite --schema env.schema.mjs
+  celery-env --version`);
   process.exit(code);
 }

package/src/compiler.js

@@ -20,6 +20,7 @@ export function generateValidator(schema, options = {}) {
     if (rule.t === LIST && needsListTempVar(rule)) needsListTemp = true;
     body.push(...emitRule(key, rule, `_${i}`, ctx));
   }
+  if (!ctx.f) envError(ctx);
   const lines = ctx.g;
   lines.push(`export function ${fn}(${param}) {`);
   if (!ctx.f) lines.push("  let r;");
@@ -28,7 +29,7 @@ export function generateValidator(schema, options = {}) {
   if (needsListTemp) lines.push("  let x;");
   lines.push(...body);
 
-  if (!ctx.f) lines.push("  if (r) throw Error(\"Invalid environment:\\n- \" + r.join(\"\\n- \"));");
+  if (!ctx.f) lines.push("  if (r) R(r);");
   lines.push(
     `  return ${returnObject(entries)};`,
     "}",
@@ -48,13 +49,14 @@ function generateObjectValidator(entries, fn, param, ctx, options) {
     if (rule.t === LIST && needsListTempVar(rule)) needsListTemp = true;
     body.push(...emitRule(key, rule, `o${prop(key)}`, ctx));
   }
+  if (!ctx.f) envError(ctx);
   const lines = ctx.g;
   lines.push(`export function ${fn}(${param}) {`);
   if (!ctx.f) lines.push("  let r;");
   lines.push("  let v;", "  const o = {};");
   if (needsListTemp) lines.push("  let x;");
   lines.push(...body);
-  if (!ctx.f) lines.push("  if (r) throw Error(\"Invalid environment:\\n- \" + r.join(\"\\n- \"));");
+  if (!ctx.f) lines.push("  if (r) R(r);");
   lines.push("  return o;", "}", `export default ${fn};`, "");
   if (options.minify) return lines.map((line) => line.trim()).join("");
   return lines.join("\n");
@@ -66,6 +68,7 @@ function generateSplitValidator(entries, fn, param, ctx, options) {
   for (let start = 0; start < entries.length; start += 32) {
     lines.push(...emitSplitChunk(entries, start, Math.min(start + 32, entries.length), n++, ctx));
   }
+  if (!ctx.f) envError(ctx);
 
   lines.push(`export function ${fn}(${param}) {`);
   if (!ctx.f) lines.push("  let r;");
@@ -73,7 +76,7 @@ function generateSplitValidator(entries, fn, param, ctx, options) {
   for (let i = 0; i < n; i++) {
     lines.push(ctx.f ? `  _c${i}(env, a);` : `  r = _c${i}(env, a, r);`);
   }
-  if (!ctx.f) lines.push("  if (r) throw Error(\"Invalid environment:\\n- \" + r.join(\"\\n- \"));");
+  if (!ctx.f) lines.push("  if (r) R(r);");
   lines.push(
     `  return ${returnObject(entries, "a")};`,
     "}",
@@ -221,6 +224,8 @@ function assertSchema(schema) {
   const entries = Object.entries(schema);
   for (const [key, rule] of entries) {
     if (!(rule && typeof rule === "object" && H(rule, "t") && typeof rule.t === "number")) throw new TypeError(`${key}: invalid celery-env spec`);
+    assertRuleOptions(key, rule);
+    if (rule.t === LIST && !(rule.item && typeof rule.item === "object" && H(rule.item, "t") && typeof rule.item.t === "number")) throw new TypeError(`${key}: list item is not a celery-env spec`);
     if (rule.t === LIST && rule.item.t === LIST) throw new TypeError(`${key}: nested list generation is not supported`);
     if (rule.requiredWhen != null && typeof rule.requiredWhen !== "function") throw new TypeError(`${key}: requiredWhen must be a function`);
     for (const field of ["default", "devDefault", "testDefault"]) {
@@ -232,6 +237,28 @@ function assertSchema(schema) {
   return entries;
 }
 
+function assertRuleOptions(key, rule) {
+  for (const field of ["min", "max"]) {
+    if (H(rule, field) && !Number.isFinite(rule[field])) throw new TypeError(`${key}: ${field} must be a finite number`);
+  }
+  if (H(rule, "strict") && typeof rule.strict !== "boolean") throw new TypeError(`${key}: strict must be a boolean`);
+  if (H(rule, "optional") && typeof rule.optional !== "boolean") throw new TypeError(`${key}: optional must be a boolean`);
+  if (H(rule, "startsWith") && typeof rule.startsWith !== "string") throw new TypeError(`${key}: startsWith must be a string`);
+  if (H(rule, "includes") && typeof rule.includes !== "string") throw new TypeError(`${key}: includes must be a string`);
+  if (H(rule, "protocols") && (!Array.isArray(rule.protocols) || rule.protocols.some(p => typeof p !== "string" || p === "" || p.includes(":")))) {
+    throw new TypeError(`${key}: protocols must be protocol names without ":"`);
+  }
+  if (rule.t === URL_T && H(rule, "protocols") && (!Array.isArray(rule.ps) || rule.ps.length !== rule.protocols.length || rule.ps.some((p, i) => p !== `${rule.protocols[i]}:`))) {
+    throw new TypeError(`${key}: malformed URL protocol spec`);
+  }
+  if (H(rule, "separator") && typeof rule.separator !== "string") throw new TypeError(`${key}: separator must be a string`);
+  if (H(rule, "trim") && typeof rule.trim !== "boolean") throw new TypeError(`${key}: trim must be a boolean`);
+  if (rule.t === ENUM && (!Array.isArray(rule.values) || !rule.values.length || rule.values.some(v => typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean" || typeof v === "number" && !Number.isFinite(v)))) {
+    throw new TypeError(`${key}: oneOf values must be strings, finite numbers, or booleans`);
+  }
+  if (rule.t === LIST && rule.item && typeof rule.item === "object") assertRuleOptions(`${key} item`, rule.item);
+}
+
 function validDefault(rule, value) {
   if (value === undefined) return rule.optional === true;
   switch (rule.t) {
@@ -299,7 +326,7 @@ function emitterContext(options) {
   if (optimize && optimize !== "default" && optimize !== "speed") throw new TypeError(`Unknown optimize mode: ${optimize}`);
   const t = options.splitLarge === false ? 1/0 : options.splitLargeThreshold ?? 512;
   if (!Number.isInteger(t) && t !== 1/0) throw new TypeError("splitLargeThreshold must be an integer");
-  return { e: 0, f: options.failFast === true, g: [], h: 0, j: 0, s: optimize > "default", t };
+  return { e: 0, f: options.failFast === true, g: [], h: 0, j: 0, r: 0, s: optimize > "default", t };
 }
 
 function functionName(options) {
@@ -352,6 +379,10 @@ function envFacade(ctx) {
   return "E(env)";
 }
 
+function envError(ctx) {
+  if(!ctx.r++)ctx.g.push(`function R(r){const e=Error("Invalid environment:\\n- "+r.join("\\n- "));e.name="EnvError";e.errors=r;throw e}`);
+}
+
 function simpleMissing(rule) {
   return !hasDefault(rule) && !rule.requiredWhen;
 }
@@ -369,12 +400,12 @@ function emitMissing(key, rule, pad, target, out, ctx) {
   if (H(rule, "default")) {
     out.push(`${pad}${used ? "else " : ""}${target} = ${literal(rule.default)};`);
   } else if (rule.optional && rule.requiredWhen) {
-    out.push(`${pad}${used ? "else " : ""}if (${requiredWhenExpr(rule)}(${envFacade(ctx)}) === true) ${err(`${key} is required`, ctx)};`);
+    out.push(`${pad}${used ? "else " : ""}if (${requiredWhenExpr(rule)}(${envFacade(ctx)}) === true) ${errMsg(key, " is required", ctx)};`);
     if (target > "b") out.push(`${pad}else ${target} = undefined;`);
   } else if (rule.optional) {
     out.push(`${pad}${used ? "else " : ""}${target} = undefined;`);
   } else {
-    out.push(`${pad}${used ? "else " : ""}${err(`${key} is required`, ctx)};`);
+    out.push(`${pad}${used ? "else " : ""}${errMsg(key, " is required", ctx)};`);
   }
 }
 
@@ -403,16 +434,16 @@ function emitPresent(key, rule, pad, target, ctx, value = "v") {
 
 function emitJson(key, pad, target, value, ctx) {
   if(!ctx.j++)ctx.g.push(`function J(v){return v[0]=="{"&&v[v.length-1]!="}"||v[0]=="["&&v[v.length-1]!="]"}`);
-  const er=err(`${key} must be valid JSON`,ctx);
+  const er=errMsg(key, " must be valid JSON",ctx);
   return [`${pad}try { if (J(${value})) throw 0; ${target} = JSON.parse(${value}); } catch { ${er}; }`];
 }
 
 function emitString(key, rule, pad, target, value, ctx) {
   const out = [];
-  if (rule.min != null && !skipMin(rule)) out.push(`${pad}if (${value}.length < ${num(rule.min)}) ${err(`${key} must have length >= ${rule.min}`, ctx)};`);
-  if (rule.max != null) out.push(`${out.length ? pad + "else " : pad}if (${value}.length > ${num(rule.max)}) ${err(`${key} must have length <= ${rule.max}`, ctx)};`);
-  if (rule.startsWith != null) out.push(`${out.length ? pad + "else " : pad}if (!${value}.startsWith(${literal(rule.startsWith)})) ${err(`${key} must start with ${rule.startsWith}`, ctx)};`);
-  if (rule.includes != null) out.push(`${out.length ? pad + "else " : pad}if (!${value}.includes(${literal(rule.includes)})) ${err(`${key} must include ${rule.includes}`, ctx)};`);
+  if (rule.min != null && !skipMin(rule)) out.push(`${pad}if (${value}.length < ${num(rule.min)}) ${errMsg(key, ` must have length >= ${rule.min}`, ctx)};`);
+  if (rule.max != null) out.push(`${out.length ? pad + "else " : pad}if (${value}.length > ${num(rule.max)}) ${errMsg(key, ` must have length <= ${rule.max}`, ctx)};`);
+  if (rule.startsWith != null) out.push(`${out.length ? pad + "else " : pad}if (!${value}.startsWith(${literal(rule.startsWith)})) ${errMsg(key, ` must start with ${rule.startsWith}`, ctx)};`);
+  if (rule.includes != null) out.push(`${out.length ? pad + "else " : pad}if (!${value}.includes(${literal(rule.includes)})) ${errMsg(key, ` must include ${rule.includes}`, ctx)};`);
   out.push(`${out.length ? pad + "else " : pad}${target} = ${value};`);
   return out;
 }
@@ -427,14 +458,14 @@ function emitNumber(key, rule, pad, target, integer, value, ctx) {
   const out = [];
   if (rule.strict) {
     const re = integer ? "/^[+-]?\\d+$/" : "/^[+-]?(?:\\d+\\.?\\d*|\\.\\d+)$/";
-    out.push(`${pad}if (!${re}.test(${value})) ${err(`${key} must be ${integer ? "a strict integer" : "a strict number"}`, ctx)};`);
+    out.push(`${pad}if (!${re}.test(${value})) ${errMsg(key, ` must be ${integer ? "a strict integer" : "a strict number"}`, ctx)};`);
     out.push(`${pad}else {`);
     pad += "  ";
   }
   out.push(`${pad}${value} = +${value};`);
-  out.push(`${pad}if (${integer ? int32Bounded(rule) ? `(${value} | 0) !== ${value}` : `!Number.isInteger(${value})` : `!isFinite(${value})`}) ${err(`${key} must be ${integer ? "an integer" : "a number"}`, ctx)};`);
-  if (rule.min != null) out.push(`${pad}else if (${value} < ${num(rule.min)}) ${err(`${key} must be >= ${rule.min}`, ctx)};`);
-  if (rule.max != null) out.push(`${pad}else if (${value} > ${num(rule.max)}) ${err(`${key} must be <= ${rule.max}`, ctx)};`);
+  out.push(`${pad}if (${integer ? int32Bounded(rule) ? `(${value} | 0) !== ${value}` : `!Number.isInteger(${value})` : `!isFinite(${value})`}) ${errMsg(key, ` must be ${integer ? "an integer" : "a number"}`, ctx)};`);
+  if (rule.min != null) out.push(`${pad}else if (${value} < ${num(rule.min)}) ${errMsg(key, ` must be >= ${rule.min}`, ctx)};`);
+  if (rule.max != null) out.push(`${pad}else if (${value} > ${num(rule.max)}) ${errMsg(key, ` must be <= ${rule.max}`, ctx)};`);
   out.push(`${pad}else ${target} = ${value};`);
   if (rule.strict) out.push(`${pad.slice(0, -2)}}`);
   return out;
@@ -454,13 +485,13 @@ function emitStrictNumScalar(key, rule, pad, target, value, ctx) {
     `${pad}    else if (c < 48 || c > 57) break;`,
     `${pad}    else d = 1;`,
     `${pad}  }`,
-    `${pad}  if (!d || q !== ${value}.length) ${err(`${key} must be a strict number`, ctx)};`,
+    `${pad}  if (!d || q !== ${value}.length) ${errMsg(key, " must be a strict number", ctx)};`,
     `${pad}  else {`,
     `${pad}    ${value} = +${value};`,
-    `${pad}    if (!isFinite(${value})) ${err(`${key} must be a number`, ctx)};`
+    `${pad}    if (!isFinite(${value})) ${errMsg(key, " must be a number", ctx)};`
   ];
-  if (rule.min != null) out.push(`${pad}    else if (${value} < ${num(rule.min)}) ${err(`${key} must be >= ${rule.min}`, ctx)};`);
-  if (rule.max != null) out.push(`${pad}    else if (${value} > ${num(rule.max)}) ${err(`${key} must be <= ${rule.max}`, ctx)};`);
+  if (rule.min != null) out.push(`${pad}    else if (${value} < ${num(rule.min)}) ${errMsg(key, ` must be >= ${rule.min}`, ctx)};`);
+  if (rule.max != null) out.push(`${pad}    else if (${value} > ${num(rule.max)}) ${errMsg(key, ` must be <= ${rule.max}`, ctx)};`);
   out.push(
     `${pad}    else ${target} = ${value};`,
     `${pad}  }`,
@@ -477,7 +508,7 @@ function emitStrictIntScalar(key, rule, pad, target, value, ctx) {
     `${pad}  let c = ${value}.charCodeAt(q);`,
     `${pad}  let g = 1;`,
     `${pad}  if (c === 43 || c === 45) { g = c === 45 ? -1 : 1; q++; }`,
-    `${pad}  if (q === z) ${err(`${key} must be a strict integer`, ctx)};`,
+    `${pad}  if (q === z) ${errMsg(key, " must be a strict integer", ctx)};`,
     `${pad}  else {`,
     `${pad}    let n = 0;`,
     `${pad}    for (; q < z; q++) {`,
@@ -485,13 +516,13 @@ function emitStrictIntScalar(key, rule, pad, target, value, ctx) {
     `${pad}      if (c < 48 || c > 57) break;`,
     `${pad}      n = n * 10 + c - 48;`,
     `${pad}    }`,
-    `${pad}    if (q !== z) ${err(`${key} must be a strict integer`, ctx)};`,
+    `${pad}    if (q !== z) ${errMsg(key, " must be a strict integer", ctx)};`,
     `${pad}    else {`,
     `${pad}      n *= g;`,
-    `${pad}      if ((n | 0) !== n) ${err(`${key} must be an integer`, ctx)};`
+    `${pad}      if ((n | 0) !== n) ${errMsg(key, " must be an integer", ctx)};`
   ];
-  if (rule.min != null) out.push(`${pad}      else if (n < ${num(rule.min)}) ${err(`${key} must be >= ${rule.min}`, ctx)};`);
-  if (rule.max != null) out.push(`${pad}      else if (n > ${num(rule.max)}) ${err(`${key} must be <= ${rule.max}`, ctx)};`);
+  if (rule.min != null) out.push(`${pad}      else if (n < ${num(rule.min)}) ${errMsg(key, ` must be >= ${rule.min}`, ctx)};`);
+  if (rule.max != null) out.push(`${pad}      else if (n > ${num(rule.max)}) ${errMsg(key, ` must be <= ${rule.max}`, ctx)};`);
   out.push(
     `${pad}      else ${target} = n;`,
     `${pad}    }`,
@@ -506,14 +537,14 @@ function emitEnum(key, rule, pad, target, value, ctx) {
     const checks = rule.values.map(v=>`${value} === ${literal(v)}`).join(" || ");
     return [
       `${pad}if (${checks}) ${target} = ${value};`,
-      `${pad}else ${err(`${key} must be one of ${rule.values.join(", ")}`, ctx)};`
+      `${pad}else ${errMsg(key, ` must be one of ${rule.values.join(", ")}`, ctx)};`
     ];
   }
   const out = [`${pad}switch (${value}) {`];
   for (const v of rule.values) {
     out.push(`${pad}  case ${literal(String(v))}: ${target} = ${literal(v)}; break;`);
   }
-  out.push(`${pad}  default: ${err(`${key} must be one of ${rule.values.join(", ")}`, ctx)};`);
+  out.push(`${pad}  default: ${errMsg(key, ` must be one of ${rule.values.join(", ")}`, ctx)};`);
   out.push(`${pad}}`);
   return out;
 }
@@ -521,9 +552,9 @@ function emitEnum(key, rule, pad, target, value, ctx) {
 function emitUrl(key, rule, pad, target, value, ctx) {
   if (rule.protocols) {
     const cases = rule.ps.map((protocol) => `case ${literal(protocol)}:`).join(" ");
-    return [`${pad}try { switch (new URL(${value}).protocol) { ${cases} ${target} = ${value}; break; default: ${err(`${key} must use protocol ${rule.protocols.join(", ")}`, ctx)}; } } catch { ${err(`${key} must be a URL`, ctx)}; }`];
+    return [`${pad}try { switch (new URL(${value}).protocol) { ${cases} ${target} = ${value}; break; default: ${errMsg(key, ` must use protocol ${rule.protocols.join(", ")}`, ctx)}; } } catch { ${errMsg(key, " must be a URL", ctx)}; }`];
   }
-  return [`${pad}try { new URL(${value}); ${target} = ${value}; } catch { ${err(`${key} must be a URL`, ctx)}; }`];
+  return [`${pad}try { new URL(${value}); ${target} = ${value}; } catch { ${errMsg(key, " must be a URL", ctx)}; }`];
 }
 
 function emitList(key, rule, pad, target, ctx) {
@@ -589,10 +620,11 @@ function emitSetList(key, rule, pad, target, ctx) {
   const n = `S${ctx.g.length}`;
   ctx.g.push(`const ${n}=new Set(${literal(item.values)});`);
   const out = segmentListHeader(rule, pad, ctx);
+  const keyAt = listKey(key);
   out.push(
-    `${pad}    if (a === z) ${err(`${key} item is required`, ctx)};`,
+    `${pad}    if (a === z) ${errMsg(keyAt, " is required", ctx)};`,
     `${pad}    else if (${n}.has(x = v.slice(a, z))) l[i] = x;`,
-    `${pad}    else ${err(`${key} item must be one of ${item.values.join(", ")}`, ctx)};`
+    `${pad}    else ${errMsg(keyAt, ` must be one of ${item.values.join(", ")}`, ctx)};`
   );
   return finishSegmentList(out, pad, target, ctx);
 }
@@ -600,14 +632,15 @@ function emitSetList(key, rule, pad, target, ctx) {
 function emitFastStrictIntList(key, rule, pad, target, ctx) {
   const item = rule.item;
   const out = segmentListHeader(rule, pad, ctx);
+  const keyAt = listKey(key);
   out.push(
-    `${pad}    if (a === z) ${"default" in item || item.optional ? `l[i] = ${literal(item.default)}` : err(`${key} item must be a strict integer`, ctx)};`,
+    `${pad}    if (a === z) ${"default" in item || item.optional ? `l[i] = ${literal(item.default)}` : errMsg(keyAt, " must be a strict integer", ctx)};`,
     `${pad}    else {`,
     `${pad}      let q = a;`,
     `${pad}      let c = v.charCodeAt(q);`,
     `${pad}      let g = 1;`,
     `${pad}      if (c === 43 || c === 45) { g = c === 45 ? -1 : 1; q++; }`,
-    `${pad}      if (q === z) ${err(`${key} item must be a strict integer`, ctx)};`,
+    `${pad}      if (q === z) ${errMsg(keyAt, " must be a strict integer", ctx)};`,
     `${pad}      else {`,
     `${pad}        let n = 0;`,
     `${pad}        for (; q < z; q++) {`,
@@ -615,13 +648,13 @@ function emitFastStrictIntList(key, rule, pad, target, ctx) {
     `${pad}          if (c < 48 || c > 57) break;`,
     `${pad}          n = n * 10 + c - 48;`,
     `${pad}        }`,
-    `${pad}        if (q !== z) ${err(`${key} item must be a strict integer`, ctx)};`,
+    `${pad}        if (q !== z) ${errMsg(keyAt, " must be a strict integer", ctx)};`,
     `${pad}        else {`,
     `${pad}          n *= g;`,
-    `${pad}          if ((n | 0) !== n) ${err(`${key} item must be an integer`, ctx)};`
+    `${pad}          if ((n | 0) !== n) ${errMsg(keyAt, " must be an integer", ctx)};`
   );
-  if (item.min != null) out.push(`${pad}          else if (n < ${num(item.min)}) ${err(`${key} item must be >= ${item.min}`, ctx)};`);
-  if (item.max != null) out.push(`${pad}          else if (n > ${num(item.max)}) ${err(`${key} item must be <= ${item.max}`, ctx)};`);
+  if (item.min != null) out.push(`${pad}          else if (n < ${num(item.min)}) ${errMsg(keyAt, ` must be >= ${item.min}`, ctx)};`);
+  if (item.max != null) out.push(`${pad}          else if (n > ${num(item.max)}) ${errMsg(keyAt, ` must be <= ${item.max}`, ctx)};`);
   out.push(
     `${pad}          else l[i] = n;`,
     `${pad}        }`,
@@ -637,26 +670,26 @@ function emitFastStrictIntList(key, rule, pad, target, ctx) {
 function emitSegmentStringList(key, rule, pad, target, ctx) {
   const item = rule.item;
   const out = segmentListHeader(rule, pad, ctx);
-  const label = `${key} item`;
+  const keyAt = listKey(key);
   const len = "z - a";
   let checked = false;
   if (item.min != null && !skipMin(item)) {
-    out.push(`${pad}    if (${len} < ${num(item.min)}) ${err(`${label} must have length >= ${item.min}`, ctx)};`);
+    out.push(`${pad}    if (${len} < ${num(item.min)}) ${errMsg(keyAt, ` must have length >= ${item.min}`, ctx)};`);
     checked = true;
   }
   if (item.max != null) {
-    out.push(`${checked ? pad + "    else " : pad + "    "}if (${len} > ${num(item.max)}) ${err(`${label} must have length <= ${item.max}`, ctx)};`);
+    out.push(`${checked ? pad + "    else " : pad + "    "}if (${len} > ${num(item.max)}) ${errMsg(keyAt, ` must have length <= ${item.max}`, ctx)};`);
     checked = true;
   }
   if (item.startsWith != null) {
     const prefix = literal(item.startsWith);
-    out.push(`${checked ? pad + "    else " : pad + "    "}if (${len} < ${item.startsWith.length} || !v.startsWith(${prefix}, a)) ${err(`${label} must start with ${item.startsWith}`, ctx)};`);
+    out.push(`${checked ? pad + "    else " : pad + "    "}if (${len} < ${item.startsWith.length} || !v.startsWith(${prefix}, a)) ${errMsg(keyAt, ` must start with ${item.startsWith}`, ctx)};`);
     checked = true;
   }
   if (item.includes != null) {
     const needle = literal(item.includes);
     const needleLen = item.includes.length;
-    out.push(`${checked ? pad + "    else " : pad + "    "}if (((x = v.indexOf(${needle}, a)) < 0) || x + ${needleLen} > z) ${err(`${label} must include ${item.includes}`, ctx)};`);
+    out.push(`${checked ? pad + "    else " : pad + "    "}if (((x = v.indexOf(${needle}, a)) < 0) || x + ${needleLen} > z) ${errMsg(keyAt, ` must include ${item.includes}`, ctx)};`);
     checked = true;
   }
   out.push(`${checked ? pad + "    else " : pad + "    "}l[i] = v.slice(a, z);`);
@@ -707,7 +740,7 @@ function listAssign(pad, target) {
 }
 
 function emitListItem(key, rule, pad, ctx) {
-  key = `${key} item`;
+  key = listKey(key);
   if (rule.optional || !simpleMissing(rule)) {
     const out = [`${pad}if (x === "") {`];
     emitMissing(key, rule, `${pad}  `, "l[i]", out, ctx);
@@ -721,7 +754,7 @@ function emitBool(key, pad, target, value, ctx) {
   return [
     `${pad}if (${value}==="true"||${value}==="1"||${value}==="yes"||${value}==="on") ${target} = true;`,
     `${pad}else if (${value}==="false"||${value}==="0"||${value}==="no"||${value}==="off") ${target} = false;`,
-    `${pad}else ${err(`${key} must be a boolean`, ctx)};`
+    `${pad}else ${errMsg(key, " must be a boolean", ctx)};`
   ];
 }
 
@@ -747,7 +780,20 @@ function innerTypeFor(rule) {
 }
 
 function err(message, ctx) {
-  return ctx.f ? `throw Error(${literal(`Invalid environment:\n- ${message}`)})` : `(r ??= []).push(${literal(message)})`;
+  return errExpr(literal(message), ctx);
+}
+
+function errMsg(key, suffix, ctx) {
+  return typeof key === "string" ? err(`${key}${suffix}`, ctx) : errExpr(`${key.expr}+${literal(suffix)}`, ctx);
+}
+
+function errExpr(message, ctx) {
+  envError(ctx);
+  return ctx.f ? `R([${message}])` : `(r ??= []).push(${message})`;
+}
+
+function listKey(key) {
+  return { expr: `${literal(key)}+"["+i+"]"` };
 }
 
 function literal(value) {

package/src/index.d.ts

@@ -7,7 +7,7 @@ export type Spec<T> = { readonly [specBrand]: T };
 export type InferSpec<T> = T extends Spec<infer V> ? V : never;
 export type InferEnv<T extends Record<string, Spec<unknown>>> = { readonly [K in keyof T]: InferSpec<T[K]> };
 export type EnvResult<T extends Record<string, Spec<unknown>>> = InferEnv<T>;
-type Output<T, O> = O extends { default: infer D } ? D : O extends { optional: true } ? T | undefined : T;
+type Output<T, O> = O extends { default: unknown } | { devDefault: unknown } | { testDefault: unknown } ? T : O extends { optional: true } ? T | undefined : T;
 export function defineEnv<T extends Record<string, Spec<unknown>>>(schema: T): Readonly<T>;
 export function str<O extends StringOptions | undefined = undefined>(options?: O): Spec<Output<string, O>>;
 export function int<O extends NumberOptions | undefined = undefined>(options?: O): Spec<Output<number, O>>;

package/src/index.js

@@ -26,23 +26,34 @@ export function defineEnv(schema) {
 }
 
 export function str(options) {
+  assertBaseOptions("str", options);
+  assertStringOptions("str", options);
   return spec(STR, options);
 }
 
 export function int(options) {
+  assertBaseOptions("int", options);
+  assertNumberOptions("int", options);
   return spec(INT, options);
 }
 
 export function num(options) {
+  assertBaseOptions("num", options);
+  assertNumberOptions("num", options);
   return spec(NUM, options);
 }
 
 export function bool(options) {
+  assertBaseOptions("bool", options);
   return spec(BOOL, options);
 }
 
 export function oneOf(values, options) {
   if (!Array.isArray(values) || !values.length) throw new TypeError("oneOf() expects a non-empty array");
+  if (values.some(v => typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean" || typeof v === "number" && !Number.isFinite(v))) {
+    throw new TypeError("oneOf() values must be strings, finite numbers, or booleans");
+  }
+  assertBaseOptions("oneOf", options);
   const mixed = values.some(v=>typeof v!="string");
   const strings = mixed ? values.map(String) : values.slice();
   const rule = {...options,values,strings};
@@ -51,15 +62,24 @@ export function oneOf(values, options) {
 }
 
 export function url(options) {
+  assertBaseOptions("url", options);
+  assertStringOptions("url", options);
+  if (options && H(options, "protocols") && (!Array.isArray(options.protocols) || options.protocols.some(p => typeof p !== "string" || p === "" || p.includes(":")))) {
+    throw new TypeError("url() protocols must be protocol names without \":\"");
+  }
   return spec(URL_T, options && H(options, "protocols") ? {...options,ps:options.protocols.map(p=>p+":")} : options);
 }
 
 export function json(options) {
+  assertBaseOptions("json", options);
   return spec(JSON_T, options);
 }
 
 export function list(item, options) {
   if (!isCelerySpec(item)) throw new TypeError("list() expects a celery-env spec item");
+  assertBaseOptions("list", options);
+  if (options && H(options, "separator") && typeof options.separator !== "string") throw new TypeError("list() separator must be a string");
+  if (options && H(options, "trim") && typeof options.trim !== "boolean") throw new TypeError("list() trim must be a boolean");
   return spec(LIST, {separator:",",...options,item});
 }
 
@@ -92,6 +112,34 @@ function schemaEntries(schema) {
   return entries;
 }
 
+function assertBaseOptions(name, options) {
+  if (options === undefined) return;
+  if (options === null || typeof options !== "object" || Array.isArray(options)) throw new TypeError(`${name}() options must be an object`);
+  if (H(options, "optional") && typeof options.optional !== "boolean") throw new TypeError(`${name}() optional must be a boolean`);
+  if (H(options, "requiredWhen") && options.requiredWhen != null && typeof options.requiredWhen !== "function") throw new TypeError(`${name}() requiredWhen must be a function`);
+  if (H(options, "desc") && typeof options.desc !== "string") throw new TypeError(`${name}() desc must be a string`);
+  if (H(options, "docs") && typeof options.docs !== "string") throw new TypeError(`${name}() docs must be a string`);
+}
+
+function assertStringOptions(name, options) {
+  if (!options) return;
+  assertLimit(name, options, "min");
+  assertLimit(name, options, "max");
+  if (H(options, "startsWith") && typeof options.startsWith !== "string") throw new TypeError(`${name}() startsWith must be a string`);
+  if (H(options, "includes") && typeof options.includes !== "string") throw new TypeError(`${name}() includes must be a string`);
+}
+
+function assertNumberOptions(name, options) {
+  if (!options) return;
+  assertLimit(name, options, "min");
+  assertLimit(name, options, "max");
+  if (H(options, "strict") && typeof options.strict !== "boolean") throw new TypeError(`${name}() strict must be a boolean`);
+}
+
+function assertLimit(name, options, key) {
+  if (H(options, key) && !Number.isFinite(options[key])) throw new TypeError(`${name}() ${key} must be a finite number`);
+}
+
 function readValue(key, rule, value, e, i, env) {
   if (value == null || value === "") {
     if (H(rule, "testDefault") || H(rule, "devDefault")) {