{"_id":"@davidsneighbour/envx","_rev":"2-9b44b5e8e239381069cb7c7cc7dbb1a8","name":"@davidsneighbour/envx","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@davidsneighbour/envx","version":"0.0.1","author":{"url":"David's Neighbour","name":"Patrick Kollitsch"},"license":"MIT","_id":"@davidsneighbour/envx@0.0.1","maintainers":[{"name":"davidsneighbour","email":"pkollitsch@gmail.com"}],"homepage":"https://github.com/davidsneighbour/envx#readme","bugs":{"url":"https://github.com/davidsneighbour/envx/issues"},"bin":{"envx":"dist/bin/envx.mjs"},"dist":{"shasum":"5306b09dcbd51ab3494867622e115058ce3b3ddb","tarball":"https://registry.npmjs.org/@davidsneighbour/envx/-/envx-0.0.1.tgz","fileCount":7,"integrity":"sha512-b9juWTNg5J5LEOiogrJ8pBA8FBnbzTodQAamdmY07VCnFq4rMpo5BerORRu7aSjLwOwaY5xapGykmr0KydhWyQ==","signatures":[{"sig":"MEQCIHKGYnQIIqms4ROxye4hdukaR+q0zQQFCSfkUyjszQf4AiAb1vB0+wcoqUpwqTGYd3Fd6oxRY6btJzNIJ7W17JrMCw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22130},"type":"module","types":"dist/envx.d.ts","engines":{"node":">=18.17"},"exports":{".":{"types":"./dist/envx.d.ts","import":"./dist/envx.js"}},"gitHead":"8a1b1d5930cb505c15744de050b252d65c32bfc5","scripts":{"test":"node --test --test-reporter=spec \"test/**/*.js\"","build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepare":"npm run build","pretest":"npm run build","test:watch":"node --test --watch \"test/**/*.js\""},"_npmUser":{"name":"davidsneighbour","email":"pkollitsch@gmail.com"},"repository":{"url":"git+https://github.com/davidsneighbour/envx.git","type":"git"},"_npmVersion":"11.6.0","description":"Cross-runtime environment variable helper (Node.js, Deno, Bun). ESM-only, no deps (yet)","directories":{},"_nodeVersion":"24.4.1","_hasShrinkwrap":false,"devDependencies":{"@types/node":"22.7.4"},"_npmOperationalInternal":{"tmp":"tmp/envx_0.0.1_1758348887012_0.8499514533702233","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package has moved to @dnbhq/envx. Please update your dependency: npm install @dnbhq/envx"}},"time":{"created":"2025-09-20T06:14:46.880Z","modified":"2026-08-18T23:15:20.347Z","0.0.1":"2025-09-20T06:14:47.195Z"},"bugs":{"url":"https://github.com/davidsneighbour/envx/issues"},"author":{"url":"David's Neighbour","name":"Patrick Kollitsch"},"license":"MIT","homepage":"https://github.com/davidsneighbour/envx#readme","repository":{"url":"git+https://github.com/davidsneighbour/envx.git","type":"git"},"description":"Cross-runtime environment variable helper (Node.js, Deno, Bun). ESM-only, no deps (yet)","maintainers":[{"name":"davidsneighbour","email":"pkollitsch@gmail.com"}],"readme":"# envx - Cross‑runtime Environment Variable Helper (Node.js · Deno · Bun)\n\n`envx` is a lightweight yet powerful ESM utility to **check**, **validate**, **sanitize**, and **load** environment variables across Node.js, Deno, and Bun - with **no external dependencies**.\n\n## Features\n\n* Validate types: `string`, `integer`, `number`, `boolean`\n* Enforce constraints: min/max length, regex, enum array or function\n* Retrieve sanitized values with trimming and coercion\n* Provide optional defaults and optional/required semantics\n* Load `.env` from the current working directory and `$HOME` (opt‑in), without dotenv\n* Set global defaults once and apply them everywhere\n* Enable Boolean strict mode (`true|false` only)\n* Framework‑agnostic - works in CLIs and servers\n\n\n## Installation\n\n```bash\n# Node.js / Bun (ESM project)\nnpm install @davidsneighbour/envx\n\n# Deno: import directly from file path or hosted URL\nimport { getEnvVar } from \"./src/envx.ts\";\n```\n\n\n## Quick Start\n\n### ▶ Node.js / Bun\n\n```ts\nimport { configureDefaults, getEnvVar, validateEnvVar, checkEnvVar, loadEnv } from \"@davidsneighbour/envx\";\n\nconfigureDefaults({\n  verbose: true,\n  envFilePaths: [\"~/.env\", \".env\"],\n});\n\nawait loadEnv();\n\nconst PORT = getEnvVar(\"PORT\", { type: \"int\", default: 3000 });\nconst DEBUG = getEnvVar(\"DEBUG\", { type: \"boolean\", default: false });\n\nvalidateEnvVar(\"NODE_ENV\", { pattern: /^(development|production|test)$/ });\ncheckEnvVar(\"API_KEY\");\n```\n\n### ▶ Deno\n\n```ts\n// run with: deno run --allow-env --allow-read main.ts\nimport { configureDefaults, loadEnv, getEnvVar } from \"./src/envx.ts\";\n\nconfigureDefaults({ verbose: true });\n\nawait loadEnv({ paths: [\".env\"] });\n\nconst port = getEnvVar(\"PORT\", { type: \"int\", default: 8080 });\nconsole.log(\"Running on port\", port);\n```\n\n\n## API Reference\n\n### `configureDefaults(options)`\n\nSet global behaviour applied to all calls.\n\n```ts\nconfigureDefaults({\n  verbose: false,\n  exitOnError: false,\n  envFilePaths: [\".env\"],\n  trimValues: true,\n  coerceTypes: true,\n  booleanStrict: false,\n});\n```\n\n### `checkEnvVar(name, options?)`\n\nEnsure a variable exists (non‑empty unless `allowEmpty:true`). Throws on error.\n\n```ts\ncheckEnvVar(\"API_URL\", { allowEmpty: false, message: \"API_URL missing\" });\n```\n\n### `validateEnvVar(name, options?) => value`\n\nValidate constraints and **return a coerced value** on success. Throws on failure.\n\nExamples:\n\n```ts\n// integer\nenv.PORT = validateEnvVar(\"PORT\", { type: \"int\" });\n\n// regex enforced string\nenv.CODE = validateEnvVar(\"CODE\", { pattern: /^[A-Z0-9]{8}$/ });\n\n// strict boolean\nenv.DEBUG = validateEnvVar(\"DEBUG\", { type: \"boolean\", booleanStrict: true });\n```\n\n### `getEnvVar(name, options?) => value | undefined`\n\nRetrieve, trim, coerce, and validate. If missing and `default` provided (or `required:false`), return the default/undefined.\n\n```ts\nconst token = getEnvVar(\"TOKEN\", { pattern: /^[A-Za-z0-9_-]{20,}$/ });\nconst port  = getEnvVar(\"PORT\", { type: \"int\", default: 8080 });\nconst debug = getEnvVar(\"DEBUG\", { type: \"boolean\", required: false, default: false });\n```\n\n### `loadEnv(options?)`\n\nLoad `.env` files and populate the runtime environment.\n\n```ts\nawait loadEnv({ paths: [\"~/.env\", \".env\"], override: false });\n```\n\n\n## Boolean Strict Mode\n\nBy default, booleans accept flexible values: `true/false/1/0/yes/no/y/n/on/off`.\n\nEnable strict mode to accept only `true` and `false` (case‑insensitive):\n\n```ts\nconfigureDefaults({ booleanStrict: true });\n\n// or per call\ngetEnvVar(\"DEBUG\", { type: \"boolean\", booleanStrict: true });\n```\n\nCLI example:\n\n```bash\nnpx envx --var DEBUG --type boolean --boolean-strict\n```\n\n\n## CLI Usage\n\n### ▶ Node.js / Bun\n\n```bash\nnpx envx --var API_KEY --type string --pattern '^[A-Za-z0-9_-]{16,}$'\n\nnpx envx --var PORT --type int --default 8080\n\nnpx envx --var DEBUG --type boolean --boolean-strict\n```\n\n### ▶ Deno (no CLI binary)\n\nRun directly via `deno run` with the envx module:\n\n```bash\ndeno run --allow-env --allow-read main.ts\n```\n\n\n## Build & Publish (Node.js / Bun)\n\n```bash\nnpm run build\nnpm test\nnpm publish --access public\n```\n\n\n## Cross‑Runtime Notes\n\n* **Node.js**: uses `process.env`. Reads `.env` synchronously at startup. ESM only.\n* **Deno**: uses `Deno.env`. Requires `--allow-env` and `--allow-read`. Import directly from file/URL.\n* **Bun**: uses `process.env` or `Bun.env`. Bun automatically loads `.env*` files.\n* **Browsers**: not supported.\n\n\n## Testing\n\n### ▶ Node.js\n\n```bash\nnpm test\n```\n\n### ▶ Deno\n\n```bash\ndeno test --allow-env --allow-read --allow-write\n```\n\n### ▶ Bun\n\n```bash\nbun test\n```\n\n\n## Security & Logging\n\n* Errors include variable names but not values, preventing accidental leaks.\n* `verbose:true` writes errors to stderr. Throwing remains the primary failure mechanism.\n\n\n## License\n\nMIT\n","readmeFilename":"README.md"}