{"id":48410136,"url":"https://github.com/recursivefunk/good-env","last_synced_at":"2026-04-06T05:32:26.252Z","repository":{"id":38051107,"uuid":"66731240","full_name":"recursivefunk/good-env","owner":"recursivefunk","description":"⚙   Environment variable parsing for Twelve-Factor node apps","archived":false,"fork":false,"pushed_at":"2025-06-10T14:47:05.000Z","size":449,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-21T22:36:42.459Z","etag":null,"topics":["env","environment","environment-variables","server"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/recursivefunk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-27T19:12:51.000Z","updated_at":"2025-06-10T14:54:27.000Z","dependencies_parsed_at":"2023-02-16T11:10:49.585Z","dependency_job_id":"96c939b1-f141-4605-a849-4bf268ff26a7","html_url":"https://github.com/recursivefunk/good-env","commit_stats":{"total_commits":133,"total_committers":6,"mean_commits":"22.166666666666668","dds":0.4285714285714286,"last_synced_commit":"39634050327da0ab4c3180be5ddbfb5471ad3a7c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/recursivefunk/good-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivefunk%2Fgood-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivefunk%2Fgood-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivefunk%2Fgood-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivefunk%2Fgood-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/recursivefunk","download_url":"https://codeload.github.com/recursivefunk/good-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recursivefunk%2Fgood-env/sbom","scorecard":{"id":767341,"data":{"date":"2025-08-11","repo":{"name":"github.com/recursivefunk/good-env","commit":"10ffe5e6dbfda167ba8821a7ce1a66312b2ce40b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.7,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":9,"reason":"11 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 9","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/12 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":2,"reason":"dependency not pinned by hash detected -- score normalized to 2","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/recursivefunk/good-env/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/recursivefunk/good-env/ci.yml/main?enable=pin","Warn: npmCommand not pinned by hash: .github/workflows/ci.yml:19","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   1 out of   2 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 26 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-23T01:11:53.219Z","repository_id":38051107,"created_at":"2025-08-23T01:11:53.219Z","updated_at":"2025-08-23T01:11:53.219Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31461527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["env","environment","environment-variables","server"],"created_at":"2026-04-06T05:32:25.184Z","updated_at":"2026-04-06T05:32:26.246Z","avatar_url":"https://github.com/recursivefunk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# good-env\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./img/good-env-logo.svg\" alt=\"good-env-logo\" width=\"400\"/\u003e\n\u003c/p\u003e\n\n![workflow](https://github.com/recursivefunk/good-env/actions/workflows/ci.yml/badge.svg)\n\n[![js-semistandard-style](https://raw.githubusercontent.com/standard/semistandard/master/badge.svg)](https://github.com/standard/semistandard)\n\n🚨 v7 requires Node version 18.20.4 or higher! 🚨\n\n# good-env\n\nA more intuitive way to work with environment variables in Node.js applications.\n\n[![npm version](https://img.shields.io/npm/v/good-env.svg)](https://www.npmjs.com/package/good-env)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n## Why good-env?\n\nWhen building non-trivial applications, working with environment variables as raw strings can be limiting. `good-env` provides:\n\n- Type conversion (strings to numbers, booleans, lists, etc.)\n- Default values\n- Existence checking\n- Validation\n- No production dependencies\n\n## Installation\n\n```bash\nnpm install good-env --save\n```\n\n## Usage\n\n### Basic Usage\n\nImport the package:\n\n```javascript\nconst env = require('good-env');\n```\n\n### Getting Values\n\n#### Simple Values\n\n```javascript\n// Get a string (default behavior)\nenv.get('HOST');                    // 'localhost'\n\n// With a default value if not set\nenv.get('NOT_SET', 'default');      // 'default'\n```\n\n#### Type Conversion\n\n```javascript\n// Get as a number\nenv.getNumber('PORT');              // 8080 (as a number, not string)\nenv.num('PORT');                    // Shorthand for getNumber()\n\n// Get as a boolean\nenv.getBool('DEBUG');               // true (converts 'true' string to boolean)\nenv.bool('DEBUG');                  // Shorthand for getBool()\n\n// Get as a list\nenv.getList('ALLOWED_ORIGINS');     // ['localhost', 'example.com']\nenv.list('ALLOWED_ORIGINS');        // Shorthand for getList()\n\n// Get a numeric list\nenv.list('VALUES', { cast: 'number' }); // [1, 2, 3] (converts from '1,2,3')\n```\n\n#### URLs and IPs\n\n```javascript\n// Get as a URL object\n// API_ENDPOINT=https://api.example.com/v1\nconst apiUrl = env.getUrl('API_ENDPOINT');\n// Returns:\n// {\n//   httpOk: true,\n//   redisOk: false,\n//   pgOk: false,\n//   href: 'https://api.example.com/v1',\n//   raw: URL { ... }  // Native Node.js URL object\n// }\n\nenv.url('API_ENDPOINT');            // Shorthand for getUrl()\n\n// Supported protocols: http, https, redis, postgresql\n// DATABASE_URL=postgresql://user:pass@localhost:5432/mydb\nconst dbUrl = env.getUrl('DATABASE_URL');\n// Returns: { pgOk: true, redisOk: false, httpOk: false, href: '...', raw: URL {...} }\n\n// Get an IP address (with validation)\nenv.getIp('SERVER_IP', '127.0.0.1'); // Returns the IP if valid, or default\n```\n\n### Multiple Variables\n\n#### First Available Value\n\n```javascript\n// Use first available variable from a list\nenv.get(['PRIMARY_HOST', 'BACKUP_HOST', 'DEFAULT_HOST']);\n\n// With default fallback\nenv.get(['PRIMARY_HOST', 'BACKUP_HOST'], 'localhost');\n```\n\n#### Batch Operations\n\n```javascript\n// Get multiple values as an array\nenv.getAll(['SECRET', 'HOST', 'PORT']);\n\n// Get multiple values as an object with defaults\nenv.getAll({\n  API_KEY: null,         // null means no default\n  PORT: 3000,            // Default if not set\n  DEBUG: false\n});\n```\n\n### Validation\n\n#### Existence Checking\n\n```javascript\n// Check if variables exist\nenv.ok('HOST');                     // true if HOST exists\nenv.ok('HOST', 'PORT', 'API_KEY');  // true if ALL exist\n```\n\n#### Assertions\n\n```javascript\n// Validate variables (throws error if invalid)\nenv.assert(\n  // Simple existence check\n  'HOST',\n  \n  // Type checking\n  { PORT: { type: 'number' }},\n  \n  // Custom validation\n  { REFRESH_INTERVAL: { \n      type: 'number', \n      ok: val =\u003e val \u003e= 1000 \n    }\n  }\n);\n```\n\n#### Adding to the environment\n\n```javascript\nenv.set('NEW_ENV_VAR', 'newVal');\nprocess.env.NEW_ENV_VAR // 'newVal'\nenv.get('NEW_ENV_VAR'); // 'newVal'\n```\n\n### AWS Credentials\n\n```javascript\n// Get AWS credentials from standard environment variables\nconst {\n  awsKeyId,\n  awsSecretAccessKey,\n  awsSessionToken,\n  awsRegion\n} = env.getAWS();\n\n// With default region\nconst credentials = env.getAWS({ region: 'us-west-2' });\n```\n\n### AWS Secrets Manager Integration\n\nSome folks like to store secrets in AWS secrets manager in the form of a JSON object as opposed (or in addition) to environment variables. It's me, I'm some folks. Good Env now supports this pattern. To avoid introducing a dependency you'll have to bring your own instance of AWS Secrets Manager though. Be sure to specify your AWS region as an environment variable, otherwise, it'll default to `us-east-1`.\n\nNot only will your secrets be merged with the Good Env store, but they will also be stored in the underlying `process.env` object in case there are components that are still pulling from the environment directly.\n\nNote, if something goes wrong, this function _will_ throw an error.\n\n```javascript\nconst awsSecretsManager = require('@aws-sdk/client-secrets-manager');\n\n(async function() {\n  // Load secrets from AWS Secrets Manager\n  await env.use(awsSecretsManager, 'my-secret-id');\n\n  // The secret ID can also be specified via environment variables\n  // AWS_SECRET_ID or SECRET_ID\n  await env.use(awsSecretsManager);\n\n  // Secrets are automatically merged with existing environment variables\n  // and can be accessed using any of the standard methods\n  const secretValue = env.get('someSecretFromAWSSecretsManager');\n}());\n```\n\n## Important Behavior Notes\n\n### Boolean Existence vs Value\n\nWhen checking for the existence of a boolean environment variable:\n\n```javascript\n// If A_BOOL_VAL=false\nenv.ok('A_BOOL_VAL');   // Returns true (checking existence, not value)\nenv.getBool('A_BOOL_VAL'); // Returns false (actual value)\n```\n\n### URL Validation\n\n- `getUrl()` only supports 'http', 'https', 'redis', and 'postgresql' protocols\n- Invalid URLs return `null` instead of throwing errors\n- Using `getUrl()` ensures proper URL format\n\n## Examples\n\n### Complete Configuration Setup\n\n```javascript\n// app-config.js\nconst env = require('good-env');\n\n// Validate critical variables\nenv.assert(\n  'DATABASE_URL',\n  { PORT: { type: 'number' }}\n);\n\nmodule.exports = {\n  port: env.num('PORT', 3000),\n  database: env.url('DATABASE_URL'),\n  debug: env.bool('DEBUG', false),\n  allowedOrigins: env.list('ALLOWED_ORIGINS', 'localhost'),\n  cache: {\n    enabled: env.bool('CACHE_ENABLED', true),\n    ttl: env.num('CACHE_TTL', 3600)\n  }\n};\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecursivefunk%2Fgood-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecursivefunk%2Fgood-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecursivefunk%2Fgood-env/lists"}