celery-env 0.1.0

package/docs/SCHEMA.md

@@ -0,0 +1,149 @@
+# Schema API
+
+Schemas are plain JavaScript modules. Each key describes one env var.
+
+```js
+import { defineEnv, int, str } from "celery-env";
+
+export default defineEnv({
+  DATABASE_URL: str({ min: 1 }),
+  PORT: int({ default: 3000 })
+});
+```
+
+Think of the schema as executable documentation for your configuration. The key
+is the env var name, the validator describes the accepted string format, and
+options describe defaults, examples, and environment-specific behavior.
+
+## Validators
+
+| Validator | Output | Use For |
+| --- | --- | --- |
+| `str(options)` | `string` | Text, secrets, tokens. |
+| `int(options)` | `number` | Whole numbers like ports and limits. |
+| `num(options)` | `number` | Decimal numbers. |
+| `bool(options)` | `boolean` | Feature flags. |
+| `oneOf(values, options)` | union | Enums like `NODE_ENV`. |
+| `url(options)` | `string` | URLs with optional protocols. |
+| `json(options)` | `unknown` | JSON strings parsed with `JSON.parse`. |
+| `list(item, options)` | `readonly T[]` | Comma-separated lists. |
+
+## Common Options
+
+| Option | Meaning |
+| --- | --- |
+| `default` | Value used when the env var is missing. |
+| `devDefault` | Value used when `NODE_ENV` is not `production`. |
+| `testDefault` | Value used when `NODE_ENV` is `test`. |
+| `optional` | Allows the value to be missing. |
+| `requiredWhen` | Function that can make a value required. |
+| `desc` | Description used in generated `.env.example`. |
+| `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.
+
+## Missing Values
+
+Empty strings are treated as missing. If a value is missing, Celery checks
+options in this order:
+
+1. `testDefault` when `NODE_ENV` is `test`.
+2. `devDefault` when `NODE_ENV` is not `production`.
+3. `default`.
+4. `optional`.
+5. Otherwise, the variable is required.
+
+## Strings
+
+```js
+str({ min: 8, max: 128 })
+str({ startsWith: "sk_" })
+str({ includes: "@" })
+```
+
+## Numbers
+
+```js
+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:
+
+```js
+int({ strict: true })
+num({ strict: true })
+```
+
+## Booleans
+
+Accepted true values:
+
+```text
+true, 1, yes, on
+```
+
+Accepted false values:
+
+```text
+false, 0, no, off
+```
+
+## Enums
+
+```js
+oneOf(["development", "test", "production"], {
+  default: "development"
+})
+```
+
+Values can be strings, numbers, or booleans.
+
+## URLs
+
+```js
+url({ protocols: ["https"] })
+url({ protocols: ["postgres", "postgresql"] })
+```
+
+Write protocols without the colon. Use `postgres`, not `postgres:`.
+
+## JSON
+
+```js
+json()
+```
+
+Celery validates that the value is valid JSON. It does not validate the object
+shape inside that JSON.
+
+## Lists
+
+```js
+list(str())
+list(int({ strict: true }))
+list(url({ protocols: ["https"] }))
+```
+
+Options:
+
+```js
+list(str(), { separator: ",", trim: true })
+```
+
+`separator` defaults to `","`. `trim` defaults to `true`.
+
+## Conditional Required Values
+
+```js
+SESSION_SECRET: str({
+  optional: true,
+  requiredWhen: (env) => env.NODE_ENV === "production"
+})
+```
+
+Generated validators serialize `requiredWhen` with `Function#toString()`.
+Keep the function self-contained and do not close over local variables.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,74 @@
+# Troubleshooting
+
+## The CLI Refuses To Overwrite A File
+
+Generation does not overwrite existing files unless you pass `--force`.
+
+```sh
+npx celery-env generate \
+  --schema env.schema.mjs \
+  --out src/env.mjs \
+  --types src/env.d.ts \
+  --force
+```
+
+## TypeScript Cannot Find The Generated Types
+
+Generate declarations with `--types` and import the generated module path:
+
+```sh
+npx celery-env generate --schema env.schema.mjs --out src/env.mjs --types src/env.d.ts
+```
+
+```ts
+import { loadEnv } from "./env.mjs";
+```
+
+The `.d.ts` file must sit next to the generated `.mjs` file with the same base
+name.
+
+## A URL Protocol Is Rejected
+
+Write protocols without the colon:
+
+```js
+url({ protocols: ["postgres"] })
+```
+
+Use `postgres`, not `postgres:`.
+
+## A Production Secret Is Missing
+
+Use `requiredWhen` for values that are optional in development but required in
+production:
+
+```js
+SESSION_SECRET: str({
+  optional: true,
+  requiredWhen: (env) => env.NODE_ENV === "production"
+})
+```
+
+Keep `requiredWhen` self-contained. Generated validators serialize the function
+source, so it should not close over local variables.
+
+## `json()` Is Typed As `unknown`
+
+Celery only checks that the env value is valid JSON. It does not validate the
+object shape inside the JSON string. Narrow or validate the parsed value in your
+app before using fields from it.
+
+## Generated Mode Feels Like Too Much
+
+Use runtime mode:
+
+```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);
+```

package/docs/TYPESCRIPT.md

@@ -0,0 +1,105 @@
+# TypeScript
+
+You do not need to be a TypeScript expert to use Celery. The main idea is:
+
+1. Write a schema.
+2. Generate `src/env.d.ts`.
+3. Import `env` or `loadEnv` and let your editor infer the types.
+
+## Generated Types
+
+Generate both JavaScript and declarations:
+
+```sh
+npx celery-env generate \
+  --schema env.schema.mjs \
+  --out src/env.mjs \
+  --types src/env.d.ts
+```
+
+Then import the generated module:
+
+```ts
+import { loadEnv } from "./env.mjs";
+
+const env = loadEnv(process.env);
+
+env.PORT;
+//  ^ number
+
+env.DATABASE_URL;
+//  ^ string
+```
+
+## Optional Values
+
+```js
+import { defineEnv, url } from "celery-env";
+
+export default defineEnv({
+  SENTRY_DSN: url({ optional: true })
+});
+```
+
+TypeScript sees:
+
+```ts
+env.SENTRY_DSN;
+// string | undefined
+```
+
+## Defaults Remove Undefined
+
+```js
+import { defineEnv, int } from "celery-env";
+
+export default defineEnv({
+  PORT: int({ default: 3000 })
+});
+```
+
+TypeScript sees:
+
+```ts
+env.PORT;
+// number
+```
+
+## Inferring From A Schema
+
+If you use runtime mode or want a named type:
+
+```ts
+import type { InferEnv } from "celery-env";
+import schema from "../env.schema.mjs";
+
+export type Env = InferEnv<typeof schema>;
+```
+
+## JSON Types
+
+Generated declarations type `json()` values as `unknown`, because Celery only
+validates JSON syntax.
+
+```js
+import { defineEnv, json } from "celery-env";
+
+const schema = defineEnv({
+  RATE_LIMIT_JSON: json()
+});
+```
+
+Narrow the value in your app after parsing:
+
+```ts
+const rateLimit = env.RATE_LIMIT_JSON;
+
+if (
+  rateLimit &&
+  typeof rateLimit === "object" &&
+  "windowMs" in rateLimit &&
+  "max" in rateLimit
+) {
+  // rateLimit has the fields you checked for here.
+}
+```

package/docs/assets/celery-mark.svg

@@ -0,0 +1,7 @@
+<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"/>
+</svg>

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "celery-env",
+  "version": "0.1.0",
+  "description": "Zero-dependency environment validation with generated standalone validators.",
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./compiler": {
+      "types": "./src/compiler.d.ts",
+      "import": "./src/compiler.js",
+      "default": "./src/compiler.js"
+    }
+  },
+  "bin": {
+    "celery-env": "src/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theaaravagarwal/celery-env.git"
+  },
+  "bugs": {
+    "url": "https://github.com/theaaravagarwal/celery-env/issues"
+  },
+  "homepage": "https://github.com/theaaravagarwal/celery-env#readme",
+  "files": [
+    "src/index.js",
+    "src/compiler.js",
+    "src/index.d.ts",
+    "src/compiler.d.ts",
+    "src/cli.js",
+    "docs/assets/celery-mark.svg",
+    "docs/BENCHMARKS.md",
+    "docs/CLI.md",
+    "docs/COMPARISON.md",
+    "docs/GETTING_STARTED.md",
+    "docs/MIGRATION.md",
+    "docs/README.md",
+    "docs/RUNTIME.md",
+    "docs/SCHEMA.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/TYPESCRIPT.md",
+    "SECURITY.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "ci": "npm run security:scan",
+    "test": "node --test test/*.mjs",
+    "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",
+    "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",
+    "environment",
+    "config",
+    "schema",
+    "typescript",
+    "serverless",
+    "zod",
+    "dotenv",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { constants } from "node:fs";
+import { mkdir, open, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const NOFOLLOW = constants.O_NOFOLLOW || 0;
+
+const args = parseArgs(process.argv.slice(2));
+
+if (args.help) usage(0);
+
+if (args.command === "init") {
+  await init(args);
+} else {
+  await generate(args);
+}
+
+async function generate(args) {
+  if (!args.schema || !args.out) usage(1);
+
+  const schemaPath = resolve(args.schema);
+  const mod = await import(pathToFileURL(schemaPath).href);
+  const schema = mod.default || mod.schema;
+
+  if (!schema) {
+    throw new Error(`No default export or named "schema" export found in ${schemaPath}`);
+  }
+
+  const outPath = resolve(args.out);
+  const { generateExample, generateTypes, generateValidator } = await import("./compiler.js");
+  await mkdir(dirname(outPath), { recursive: true });
+  const options = { functionName: args.functionName, processDefault: args.processDefault, minify: args.minify, failFast: args.failFast, optimize: args.optimize };
+  await writeOutput(outPath, generateValidator(schema, options), args.force);
+
+  if (args.types) {
+    const typesPath = resolve(args.types);
+    await mkdir(dirname(typesPath), { recursive: true });
+    await writeOutput(typesPath, generateTypes(schema, options), args.force);
+  }
+
+  if (args.example) {
+    const examplePath = resolve(args.example);
+    await mkdir(dirname(examplePath), { recursive: true });
+    await writeOutput(examplePath, generateExample(schema), args.force);
+  }
+}
+
+async function init(args) {
+  if (!args.schema) usage(1);
+  const target = args.target || "node";
+  const source = template(target);
+  const schemaPath = resolve(args.schema);
+  await mkdir(dirname(schemaPath), { recursive: true });
+  await writeFile(schemaPath, source, { encoding: "utf8", flag: "wx" });
+}
+
+function parseArgs(argv) {
+  const out = { command: "generate", functionName: "loadEnv" };
+  if (argv[0] === "generate" || argv[0] === "init") out.command = argv.shift();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") out.help = 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];
+    else if (arg === "--types") out.types = argv[++i];
+    else if (arg === "--example") out.example = argv[++i];
+    else if (arg === "--function-name") out.functionName = argv[++i];
+    else if (arg === "--no-process-default") out.processDefault = false;
+    else if (arg === "--minify") out.minify = true;
+    else if (arg === "--fail-fast") out.failFast = true;
+    else if (arg === "--force") out.force = true;
+    else if (arg === "--optimize") out.optimize = argv[++i];
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+async function writeOutput(path, source, force) {
+  const flags = constants.O_WRONLY | constants.O_CREAT | NOFOLLOW | (force ? constants.O_TRUNC : constants.O_EXCL);
+  let file;
+  try {
+    file = await open(path, flags, 0o666);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error(`${path} already exists; pass --force to overwrite`);
+    if (error.code === "ELOOP") throw new Error(`${path} is a symlink; refusing to write`);
+    throw error;
+  }
+  try {
+    await file.writeFile(source, "utf8");
+  } finally {
+    await file.close();
+  }
+}
+
+function template(target) {
+  if (target === "node") return `import { bool, defineEnv, int, str } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: str({ default: "development", desc: "Current runtime environment." }),
+  DATABASE_URL: str({ min: 1, desc: "Primary database connection string.", example: "postgres://user:pass@localhost:5432/app" }),
+  PORT: int({ default: 3000, min: 1, max: 65535 }),
+  DEBUG: bool({ default: false })
+});
+`;
+  if (target === "next") return `import { bool, defineEnv, str } from "celery-env";
+
+export default defineEnv({
+  NODE_ENV: str({ default: "development" }),
+  DATABASE_URL: str({ min: 1, desc: "Server-only database connection string." }),
+  NEXT_PUBLIC_API_URL: str({ min: 1, startsWith: "https://", desc: "Browser-visible API origin.", example: "https://api.example.com" }),
+  NEXT_PUBLIC_ENABLE_ANALYTICS: bool({ default: false })
+});
+`;
+  if (target === "vite") return `import { bool, defineEnv, str } from "celery-env";
+
+export default defineEnv({
+  MODE: str({ default: "development" }),
+  VITE_API_URL: str({ min: 1, startsWith: "https://", desc: "Browser-visible API origin.", example: "https://api.example.com" }),
+  VITE_ENABLE_SEARCH: bool({ default: false })
+});
+`;
+  throw new Error(`Unknown init target: ${target}`);
+}
+
+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`);
+  process.exit(code);
+}

package/src/compiler.d.ts

@@ -0,0 +1,7 @@
+import type { Spec } from "./index.js";
+export type GenerateValidatorOptions = { functionName?: string; processDefault?: boolean; minify?: boolean; failFast?: boolean; optimize?: "default" | "speed"; splitLarge?: boolean; splitLargeThreshold?: number };
+export type GenerateJsonSchemaOptions = { title?: string; additionalProperties?: boolean };
+export function generateValidator(schema: Record<string, Spec<unknown>>, options?: GenerateValidatorOptions): string;
+export function generateTypes(schema: Record<string, Spec<unknown>>, options?: { functionName?: string; processDefault?: boolean }): string;
+export function generateExample(schema: Record<string, Spec<unknown>>): string;
+export function generateJsonSchema(schema: Record<string, Spec<unknown>>, options?: GenerateJsonSchemaOptions): Record<string, unknown>;