celery-env 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# celery-env
+
+<p align="center">
+  <img src="docs/assets/celery-mark.svg" alt="celery-env" width="96" height="96">
+</p>
+
+<p align="center">
+  <strong>Environment validation that compiles to tiny standalone JavaScript.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/celery-env"><img alt="npm" src="https://img.shields.io/npm/v/celery-env?color=0f766e"></a>
+  <a href="https://github.com/theaaravagarwal/celery-env/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/theaaravagarwal/celery-env/ci.yml?branch=main"></a>
+  <img alt="dependencies" src="https://img.shields.io/badge/dependencies-0-0f766e">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-black"></a>
+</p>
+
+Celery validates `process.env` with a schema you can read, then generates a
+small validator you can ship without a runtime dependency. It is built for app
+configuration: defaults, production-only secrets, typed output, good error
+messages, and fast startup.
+
+## Install
+
+```sh
+npm install -D celery-env
+```
+
+Other package managers:
+
+```sh
+pnpm add -D celery-env
+yarn add -D celery-env
+bun add -d celery-env
+```
+
+## 60-Second Setup
+
+Create a schema:
+
+```js
+// env.schema.mjs
+import { bool, defineEnv, int, oneOf, str, url } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: oneOf(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: url({ protocols: ["postgres"] }),
+  PORT: int({ default: 3000, min: 1, max: 65535 }),
+  DEBUG: bool({ default: false }),
+  SESSION_SECRET: str({
+    optional: true,
+    requiredWhen: (env) => env.NODE_ENV === "production"
+  })
+});
+```
+
+Generate the validator:
+
+```sh
+npx celery-env generate \
+  --schema env.schema.mjs \
+  --out src/env.mjs \
+  --types src/env.d.ts \
+  --example .env.example \
+  --minify
+```
+
+Use it at app startup:
+
+```js
+// src/config.js
+import { loadEnv } from "./env.mjs";
+
+export const env = loadEnv(process.env);
+```
+
+That is the main path: write `env.schema.mjs`, generate `src/env.mjs`, and use
+the typed result everywhere else.
+
+## When To Use Celery
+
+Use Celery when you want env validation to be:
+
+- focused on app configuration instead of general object validation;
+- generated once and cheap at startup;
+- dependency-free in production;
+- typed without hand-written config types;
+- strict about missing production secrets without printing secret values.
+
+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.
+
+## Why Use It
+
+- **Generated validator**: no schema walk during app startup.
+- **Zero runtime dependencies** in generated mode.
+- **Small output**: the measured small generated validator is 526 gzip bytes.
+- **Typed config** through generated `.d.ts` files or `InferEnv`.
+- **Env-specific rules** like `devDefault`, `testDefault`, and `requiredWhen`.
+- **Secret-safe errors** that do not print rejected secret values.
+- **Runtime mode** available when you do not want a build step.
+
+## Runtime Mode
+
+Generated mode is recommended for apps, but direct parsing is available:
+
+```js
+import { defineEnv, int, parseEnv, str } from "celery-env";
+
+const schema = defineEnv({
+  DATABASE_URL: str({ min: 1 }),
+  PORT: int({ default: 3000 })
+});
+
+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.
+
+## Documentation
+
+- [Getting Started](docs/GETTING_STARTED.md)
+- [Schema API](docs/SCHEMA.md)
+- [CLI](docs/CLI.md)
+- [TypeScript](docs/TYPESCRIPT.md)
+- [Runtime Mode](docs/RUNTIME.md)
+- [Comparison](docs/COMPARISON.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Benchmarks](docs/BENCHMARKS.md)
+- [Migration Guide](docs/MIGRATION.md)
+- [Security](SECURITY.md)
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,75 @@
+# Security
+
+`celery-env` is designed to keep the published package small and auditable:
+
+- The root package has zero runtime dependencies.
+- The package has no consumer install hooks or pack hooks. Its only publish
+  lifecycle script is `prepublishOnly`, which runs the local verification gate.
+- Runtime validation does not include rejected environment values in error messages.
+- Generated validators escape schema keys and validate generated function names.
+- Environment reads require own properties, so inherited object-prototype keys do
+  not masquerade as environment variables.
+- Generated `requiredWhen` predicates receive an own-property environment facade
+  instead of the raw inherited object.
+- `__proto__` schema keys are treated as data properties instead of prototype mutation.
+- Publish validation uses `npm pack --ignore-scripts`; local hardening checks
+  reject consumer install hooks, pack hooks, and unexpected publish hooks.
+- CLI generation refuses symlink outputs and only overwrites existing generated
+  files when `--force` is passed.
+
+## Audit Commands
+
+Run the local hardening checks before publishing:
+
+```sh
+npm run security:scan
+```
+
+The root package intentionally has no lockfile because it has no dependencies.
+`npm audit` requires a lockfile, so root-package supply-chain checks are covered
+by `scripts/security-scan.mjs` and `scripts/validate-publish.mjs`.
+
+CI runs the same root hardening scan on Node 18, 20, 22, and 26.
+
+## Hardening Findings
+
+The dependency audit did not find known vulnerable packages. The hardening pass
+did find code-level weakness classes before release, and they are now covered by
+tests:
+
+- Prototype-polluted option objects could make missing values optional or inject
+  defaults. Specs now use null-prototype rule objects and own-property checks.
+- `requiredWhen` predicates could observe inherited env properties. Predicates
+  now receive an own-property env facade.
+- Generated `json()` validation could be bypassed through inherited
+  object/array keys. JSON parse success no longer depends on target-slot
+  sentinel values.
+- Generated function names missed some strict-mode forbidden identifiers. Those
+  names are now rejected.
+- Non-expression `requiredWhen` functions could emit invalid generated code.
+  They are now rejected at generation time.
+- Non-JSON-stable `json()` defaults could diverge between runtime and generated
+  validators. They are now rejected for generated output.
+- CLI generation could overwrite requested output paths. It now requires
+  `--force` and refuses symlink outputs.
+
+## Trust Boundary
+
+Schema files and `requiredWhen` predicates are application code. The CLI imports
+the schema file you pass with `--schema`, and generated validators serialize
+`requiredWhen` function source. Only run generation against schema files and
+predicates you trust; do not generate validators from untrusted schema packages.
+
+Generated `.env.example` output is documentation. It escapes unsafe key/value
+line breaks, but it still reflects schema-provided `example`, `default`,
+`devDefault`, `testDefault`, `desc`, and `docs` metadata. Do not put real
+secrets in schema defaults or examples that you plan to publish.
+
+## Reporting
+
+Report security issues privately through GitHub Security Advisories:
+
+https://github.com/theaaravagarwal/celery-env/security/advisories/new
+
+Include a minimal reproduction, the affected version, and whether the issue
+affects runtime validation, generated validators, or CLI generation.

package/docs/BENCHMARKS.md

@@ -0,0 +1,44 @@
+# Benchmarks
+
+Benchmark dependencies are kept out of the root package so `celery-env` stays
+dependency-free. The public package ships the headline report and claim rules,
+not the local benchmark lab.
+
+## Current Headline
+
+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 |
+
+## What Is Measured
+
+- Synthetic small, medium, and large schemas.
+- Realistic API, web, worker, list-heavy, and JSON-heavy env schemas.
+- Frozen plain env objects and real `process.env`.
+- Invalid input with aggregate errors.
+- Cold import/setup/first validation.
+- Shipped gzip bundle size.
+
+## Competitors
+
+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.
+
+## Claim Rules
+
+Use precise benchmark claims:
+
+- Good: "1.50x over the best external competitor on the real-schema corpus."
+- Good: "526 gzip bytes for the measured small generated validator."
+- Avoid: "Celery is always 50x faster."
+
+Env validation is workload-dependent, especially when reading real
+`process.env`.

package/docs/CLI.md

@@ -0,0 +1,68 @@
+# CLI
+
+The CLI creates schemas and generated validator files.
+
+## Initialize A Schema
+
+```sh
+npx celery-env init --target node --schema env.schema.mjs
+```
+
+Use `init` when starting from scratch. It writes a small schema with common
+Node app variables.
+
+Targets:
+
+| Target | Use For |
+| --- | --- |
+| `node` | Regular Node apps and services. |
+| `next` | Next.js projects. |
+| `vite` | Vite projects and edge-style environments. |
+
+## Generate
+
+```sh
+npx celery-env generate \
+  --schema env.schema.mjs \
+  --out src/env.mjs \
+  --types src/env.d.ts \
+  --example .env.example
+```
+
+Use `generate` after editing `env.schema.mjs`.
+
+## Flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--schema <file>` | Schema module to import. |
+| `--out <file>` | Generated validator output path. |
+| `--types <file>` | Generated `.d.ts` output path. |
+| `--example <file>` | Generated `.env.example` output path. |
+| `--function-name <name>` | Generated function name. Default: `loadEnv`. |
+| `--no-process-default` | Do not default to `process.env` in generated output. |
+| `--minify` | Emit smaller generated JavaScript. |
+| `--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. |
+
+## Recommended App Command
+
+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"
+  }
+}
+```
+
+Run it whenever the schema changes:
+
+```sh
+npm run env:generate
+```
+
+Generated files are regular source files. Commit them when you want production
+deployments to run without the generator.

package/docs/COMPARISON.md

@@ -0,0 +1,58 @@
+# Comparison
+
+Celery is not a replacement for general validation libraries. It is a focused
+tool for environment configuration.
+
+## Celery vs Zod
+
+Zod is excellent for general TypeScript validation: forms, API payloads,
+domain objects, JSON data, and reusable schemas across an app.
+
+Celery is narrower. It validates `process.env`, then can generate a standalone
+validator and declaration file for production startup.
+
+| Question | Celery | Zod |
+| --- | --- | --- |
+| Main job | Validate env config. | Validate general data. |
+| Schema shape | One key per env var. | Any object/data shape. |
+| Generated validator | Yes. | No. |
+| Production runtime dependency | None in generated mode. | `zod`. |
+| `.env.example` generation | Built in. | Build yourself. |
+| Env-specific defaults | Built in. | Build yourself. |
+| Secret-safe env errors | Built in. | Build yourself. |
+| Ecosystem size | Small and focused. | Large and mature. |
+
+Use Zod when you need general validation. Use Celery when the thing being
+validated is application configuration.
+
+## Celery vs Envalid / Envsafe / env-var
+
+These libraries are purpose-built for env validation and are good defaults for
+runtime validation.
+
+Celery's main difference is generated mode:
+
+- the schema stays in development code;
+- the generated validator can be committed;
+- production can run without loading the schema library;
+- TypeScript declarations can be generated from the same schema;
+- `.env.example` can be generated from schema metadata.
+
+## Choosing A Mode
+
+| Use Case | Recommended Mode |
+| --- | --- |
+| 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 |
+
+## What Celery Does Not Do
+
+- It does not load `.env` files. Use your platform, shell, or a dotenv loader.
+- It does not validate arbitrary request bodies or form data.
+- It does not validate the internal shape of `json()` values.
+- It does not make untrusted schema files safe to execute.
+
+Schema files are application code.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,134 @@
+# Getting Started
+
+This guide assumes you have a Node project and want one reliable place to define
+environment variables.
+
+## 1. Install
+
+```sh
+npm install -D celery-env
+```
+
+```sh
+pnpm add -D celery-env
+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`.
+
+## 2. Create A Schema
+
+Create `env.schema.mjs` in your project root:
+
+```js
+import { bool, defineEnv, int, oneOf, str, url } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: oneOf(["development", "test", "production"], {
+    default: "development"
+  }),
+
+  DATABASE_URL: url({
+    protocols: ["postgres"]
+  }),
+
+  PORT: int({
+    default: 3000,
+    min: 1,
+    max: 65535
+  }),
+
+  DEBUG: bool({
+    default: false
+  }),
+
+  SESSION_SECRET: str({
+    optional: true,
+    requiredWhen: (env) => env.NODE_ENV === "production",
+    desc: "Required in production."
+  })
+});
+```
+
+## 3. Generate The Validator
+
+```sh
+npx celery-env generate \
+  --schema env.schema.mjs \
+  --out src/env.mjs \
+  --types src/env.d.ts \
+  --example .env.example \
+  --minify
+```
+
+This creates:
+
+| File | Purpose |
+| --- | --- |
+| `src/env.mjs` | Runtime validator used by your app. |
+| `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:
+
+```json
+{
+  "scripts": {
+    "env:generate": "celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify"
+  }
+}
+```
+
+## 4. Load Env Once
+
+```js
+import { loadEnv } from "./env.mjs";
+
+export const env = loadEnv(process.env);
+```
+
+Use `env` everywhere else instead of reading `process.env` directly.
+
+## 5. Use A Nested App Config
+
+If your app already expects a nested config object, keep the generated env flat
+and adapt it in one small file:
+
+```js
+import { loadEnv } from "./env.mjs";
+
+export function loadConfig(source = process.env) {
+  const env = loadEnv(source);
+
+  return {
+    app: {
+      nodeEnv: env.NODE_ENV,
+      port: env.PORT
+    },
+    database: {
+      url: env.DATABASE_URL
+    }
+  };
+}
+```
+
+## What To Commit
+
+For most apps, commit all of these:
+
+- `env.schema.mjs`
+- `src/env.mjs`
+- `src/env.d.ts`
+- `.env.example`
+
+Committing generated files keeps deployments simple because production does not
+need to run the generator.
+
+## Next Steps
+
+- Read [Schema API](SCHEMA.md) when adding validators.
+- Read [TypeScript](TYPESCRIPT.md) if editor types do not look right.
+- Read [Troubleshooting](TROUBLESHOOTING.md) if generation or URL validation
+  fails.

package/docs/MIGRATION.md

@@ -0,0 +1,54 @@
+# Migration Guide
+
+Use this guide when adding Celery to an existing app.
+
+## Step 1. Find Env Reads
+
+Search for direct env access:
+
+```sh
+rg "process\\.env|env\\.[A-Z_]+"
+```
+
+The goal is one central module that reads env and exports validated config.
+
+## Step 2. Write A Flat Schema
+
+Keep schema keys close to actual env var names:
+
+```js
+import { defineEnv, int, oneOf, url } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: oneOf(["development", "test", "production"], { default: "development" }),
+  DATABASE_URL: url({ protocols: ["postgres"] }),
+  PORT: int({ default: 3000 })
+});
+```
+
+## Step 3. Generate
+
+```sh
+npx celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts --example .env.example --minify
+```
+
+## Step 4. Keep Your Existing Shape
+
+If your app already expects nested config, adapt once:
+
+```js
+import { loadEnv } from "./env.mjs";
+
+export function loadConfig(source = process.env) {
+  const env = loadEnv(source);
+
+  return {
+    app: { port: env.PORT },
+    database: { url: env.DATABASE_URL }
+  };
+}
+```
+
+## Step 5. Remove Direct Env Reads
+
+Use the validated config everywhere else.

package/docs/README.md

@@ -0,0 +1,15 @@
+# celery-env Documentation
+
+Start here if you are new to Celery or new to typed env validation.
+
+## Learning Path
+
+1. [Getting Started](GETTING_STARTED.md): install, write a schema, generate a validator.
+2. [Schema API](SCHEMA.md): every validator and option.
+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.
+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/RUNTIME.md

@@ -0,0 +1,43 @@
+# Runtime Mode
+
+Runtime mode validates with `parseEnv(schema, env)` directly. Use it when:
+
+- You do not want generated files.
+- Your app is small and startup cost is not critical.
+- You are prototyping before switching to generated mode.
+
+## Example
+
+```js
+import { defineEnv, int, parseEnv, str } from "celery-env";
+
+const schema = defineEnv({
+  DATABASE_URL: str({ min: 1 }),
+  PORT: int({ default: 3000 })
+});
+
+export const env = parseEnv(schema, process.env);
+```
+
+## Tradeoff
+
+Runtime mode is simpler, but generated mode is usually faster and can avoid a
+runtime dependency in production.
+
+| Mode | Build Step | Runtime Dependency | Best For |
+| --- | --- | --- | --- |
+| Generated | yes | no | production apps |
+| Runtime | no | yes | small apps, scripts, prototypes |
+
+## Errors
+
+Celery aggregates errors by default:
+
+```text
+Invalid environment:
+- DATABASE_URL is required
+- PORT must be an integer
+```
+
+Rejected values are not included in error messages, which helps avoid leaking
+secrets.