{"id":26409083,"url":"https://github.com/absxn/process-env-parser","last_synced_at":"2025-03-17T19:18:46.904Z","repository":{"id":44102611,"uuid":"199249185","full_name":"absxn/process-env-parser","owner":"absxn","description":"Purpose-built utility to parse environment variables into safe runtime types in your TypeScript Node application","archived":false,"fork":false,"pushed_at":"2023-01-04T21:56:05.000Z","size":1024,"stargazers_count":17,"open_issues_count":13,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-14T05:05:01.494Z","etag":null,"topics":["environment-variables","library","node","npm","package","parser","process","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@absxn/process-env-parser","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/absxn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-28T06:03:51.000Z","updated_at":"2023-01-31T02:52:30.000Z","dependencies_parsed_at":"2023-02-02T21:16:13.572Z","dependency_job_id":null,"html_url":"https://github.com/absxn/process-env-parser","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absxn%2Fprocess-env-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absxn%2Fprocess-env-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absxn%2Fprocess-env-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/absxn%2Fprocess-env-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/absxn","download_url":"https://codeload.github.com/absxn/process-env-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244094273,"owners_count":20397020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["environment-variables","library","node","npm","package","parser","process","typescript"],"created_at":"2025-03-17T19:18:46.213Z","updated_at":"2025-03-17T19:18:46.892Z","avatar_url":"https://github.com/absxn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# process-env-parser\n\nType-safe environment variable validation, parsing, and debugging for `node`\napplications, with zero added dependencies.\n\nSimply mandating and reading a set of variables as strings:\n\n```typescript\nconst result = requireEnvironmentVariables(\n  \"API_KEY\",\n  \"DATABASE_URL\",\n  \"LISTEN_PORT\",\n  \"SERVICE_NAME\"\n);\n```\n\nAdvanced declarative syntax for type safe parsers, default values, and masking:\n\n```typescript\nconst result = parseEnvironmentVariables({\n  API_KEY: { mask: true, default: null },\n  DATABASE_URL: { parser: s =\u003e new URL(s), mask: Mask.url(\"password\") },\n  LISTEN_PORT: { parser: parseInt, default: 3000 },\n  SERVICE_NAME: {}\n});\n\nif (result.success) {\n  // Sample success output\n  console.table(result.envPrintable);\n  // ┌──────────────┬─────────────────────────────────────────────────────┐\n  // │   (index)    │                       Values                        │\n  // ├──────────────┼─────────────────────────────────────────────────────┤\n  // │   API_KEY    │                     '\u003cmasked\u003e'                      │\n  // │ DATABASE_URL │ '\u003cmasked: \"mysql://user:*****@localhost:3306/app\"\u003e' │\n  // │ LISTEN_PORT  │                       '8080'                        │\n  // │ SERVICE_NAME │                      '\"app\"'                        │\n  // └──────────────┴─────────────────────────────────────────────────────┘\n\n  // Inferred type for successfully parsed environment\n  // {\n  //   API_KEY: string | null\n  //   DATABASE_URL: URL\n  //   LISTEN_PORT: number\n  //   SERVICE_NAME: string\n  // }\n  return result.env;\n} else {\n  // Sample formatted output\n  console.log(Formatter.multiLine(result));\n  // API_KEY = \u003cmasked\u003e\n  // DATABASE_URL = \u003cparser: \"Invalid URL: localhost\"\u003e\n  // LISTEN_PORT = 3000 (default)\n  // SERVICE_NAME = \u003cmissing\u003e\n\n  throw new Error(\"Could not parse environment variables\");\n}\n```\n\n## Contents\n\n- [Rationale](#rationale)\n- [Installation and usage](#installation-and-usage)\n- [Examples](#examples)\n  - [`requireEnvironmentVariables()`: Simple usage with mandatory variables](#success-simple-usage-with-mandatory-variables)\n  - [`parseEnvironmentVariables()`: Optional and parsed variables](#success-optional-and-parsed-variables)\n  - [Fail: Variable missing](#fail-variable-missing)\n  - [Fail: Parser throwing](#fail-parser-throwing)\n  - [Configuration files (`.env`, `dotfiles`)](#configuration-files)\n- [Mask](#mask) – `v1.1.0` (mask function)\n  - [`url()`](#url)\n  - [`urlPassword`](#urlpassword)\n  - [`urlUsernameAndPassword`](#urlusernameandpassword)\n- [Combine](#combine)\n  - [Non-nullable](#non-nullable)\n- [Formatter](#formatter)\n  - [`console.table()`](#consoletable)\n  - [Oneliner](#oneliner)\n  - [Multi-line](#multi-line)\n\n## Rationale\n\nAt the start of every process there are two sources of inputs that can affect\nthe process execution: the program arguments, and the environment variables.\n\n```sh\n$ ENV_VAR_A=Hello ENV_VAR_B=World node app.js arg1 arg2 --arg3\n```\n\nIn order to build reliable software, and minimize runtime surprises, you'll\nwant to follow the [fail-fast design](https://en.wikipedia.org/wiki/Fail-fast)\nand _ensure that your program inputs are correct as early on as possible_.\nEverything the program does afterwards is be based on these inputs.\n\nFor example, ensuring that a required database URL is correctly passed to the\nprocess at the very beginning will alert the user clearly of a possible issue,\ninstead of the the app crashing 30 minutes later when the database connection\nis done the first time.\n\nThis library tries to provide useful tooling for handling the environment\nvariable part of startup.\n\n## Installation and usage\n\n```sh\n$ npm install --save @absxn/process-env-parser\n```\n\n```typescript\nimport {\n  parseEnvironmentVariables,\n  requireEnvironmentVariables\n} from \"@absxn/process-env-parser\";\n```\n\nBoth functions return the same `Success | Fail` object:\n\n```typescript\n// Types roughly as follows, read code and inline documentation for details\n\ntype Success = {\n  success: true;\n  env: {\n    [variableName: string]:\n      | InferredParserFunctionReturnType // If `parser` option used\n      | InferredDefaultValueType // If `default` option used\n      | string; // No options used\n  };\n  envPrintable: {\n    // Human readable results for logging and debugging\n    // E.g. `ENV_VAR_A=\u003cmissing\u003e, ENV_VAR_B=\"World\", PASSWORD=\u003cmasked\u003e`\n    [variableName: string]: string;\n  };\n};\n\ntype Fail = {\n  success: false;\n  // Same as for Success\n  envPrintable: { [variableName: string]: string };\n};\n```\n\n## Examples\n\n### Success: Simple usage with mandatory variables\n\nEasiest way to read the variables is to use\n`requireEnvironmentVariables(...variableNames: string[])`. It reads given\nvariables, must find them all, and returns their values as strings.\n\nTo succeed, all listed variables must exist in the environment\n\n#### Process startup\n\n```sh\n$ A=hello B=world node app\n```\n\n#### Code\n\n```typescript\n// Type: Success | Fail\nconst result = requireEnvironmentVariables(\"A\", \"B\");\n\nif (result.success) {\n  console.table(result.envPrintable);\n  // ┌─────────┬───────────┐\n  // │ (index) │  Values   │\n  // ├─────────┼───────────┤\n  // │    A    │ '\"hello\"' │\n  // │    B    │ '\"world\"' │\n  // └─────────┴───────────┘\n\n  // Type: { A: string, B: string }\n  // Value: { A: \"hello\", B: \"world\" }\n  return result.env;\n} else {\n  // Wont get here since we gave both A and B in the startup\n}\n```\n\n### Success: Optional and parsed variables\n\nIf you have a more complex setup for the variables, you can use\n`parseEnvironmentVariables(config: Config)`. This allows you to handle each\nvariable individually with additional functionality.\n\nThe `config` object has variable names as keys, and the value is an object\nspecifying how to handle that variable.\n\nThe available options are:\n\n```typescript\ninterface Configuration {\n  // Each expected environment variable has its own options, the key is the name\n  // of the environment variable\n  [variableName: string]: EnvironmentVariableOptions;\n}\n\ninterface EnvironmentVariableOptions\u003cDefault = any, Parser = any\u003e {\n  // If variable is not found, use this as its value. If `default` not given,\n  // variable is mandatory, in which case, a missing variable leads to Fail\n  // being returned. If default value was used, envPrintable will have\n  // \" (default)\" appended to the printable value.\n  default?: Default;\n  // When variable is read, its value is passed first to the parser function.\n  // Return value of the parser is used as the variable value in the output. If\n  // the parser throws, the function will return a Fail object.\n  parser?: (value: string) =\u003e Parser;\n  // If `true`, the value of the variable is never shown in plain text in the\n  // `envPrintable` fields of the return object. Value is indicated as\n  // `\u003cmasked\u003e`.\n  //\n  // If function, the argument is:\n  //\n  //   1) Return value of the parser if variable set and parser is given\n  //   2) The environment variable value (string) if set and no parser given\n  //   3) Default value if environment variable is not set\n  //\n  // Return value of the function is the value to be shown in `envPrintable`,\n  // formatted as \u003cmasked: \"value\"\u003e.\n  mask?: boolean | ((value: Parser | string | Default) =\u003e string);\n}\n```\n\nTo succeed:\n\n- All varibales with no `default` given must exist in the environment\n  - Empty string `\"\"` is considered as non-existing!\n- No `parser` or `mask` function may throw\n  - Parser exceptions turn result into `Fail` and the exception message is\n    captured in the `envPrintable` fields. See examples below.\n\nDefault value is used as is, also when parser is given, i.e. default value is\nnot passed to parser when used.\n\n#### Process startup\n\n```sh\n$ REQUIRED=value PARSED=12345 node app\n```\n\n#### Code\n\n```typescript\n// Ensure we return only valid numbers\nfunction parser(s: string): number {\n  const p = parseInt(s);\n\n  if (isNaN(p)) {\n    throw new Error(\"Not a number\");\n  } else {\n    return p;\n  }\n}\n\nconst result = parseEnvironmentVariables({\n  REQUIRED: {},\n  PARSED: { parser },\n  OPTIONAL: { default: \"OPTIONAL\" }\n});\n\nif (result.success) {\n  console.table(result.envPrintable);\n  // ┌──────────┬────────────────────────┐\n  // │ (index)  │         Values         │\n  // ├──────────┼────────────────────────┤\n  // │ REQUIRED │       '\"value\"'        │\n  // │  PARSED  │         '1234'         │\n  // │ OPTIONAL │ '\"OPTIONAL\" (default)' │\n  // └──────────┴────────────────────────┘\n\n  // Type: { REQUIRED: string, PARSER: number, OPTIONAL: \"OPTIONAL\" | string }\n  // Value: { REQUIRED: \"value\", PARSED: 1234, OPTIONAL: \"OPTIONAL\" }\n  return result.env;\n} else {\n  // Will not get here\n}\n```\n\n### Fail: Variable missing\n\n#### Process startup\n\n```sh\n$ VAR_A=value VAR_B= VAR_C=\"${X} ${Y} ${Z}\" node app\n```\n\nWARNING – Special cases for \"meaningless\" strings:\n\n- Empty string: `VAR_B` is also considered as missing. I.e. `process.env.VAR_B`\n  does exist, but the parser considers `\"\"` equal to not set.\n- Blank string: `VAR_C` is also considered not set. In this case, `X`, `Y`, `Z`\n  are all `\"\"`, so the resulting value of `VAR_C` is two spaces,\n  `\" \"`. If value is surrounded by spaces, e.g. `\" A \"`, the spaces are\n  preserved as is through the parser.\n\n#### Code\n\n```typescript\nconst result = requireEnvironmentVariables(\"VAR_A\", \"VAR_B\", \"VAR_C\", \"VAR_D\");\n\nif (result.success) {\n  // Won't get there\n} else {\n  console.table(result.envPrintable);\n  //  ┌─────────┬─────────────┐\n  //  │ (index) │   Values    │\n  //  ├─────────┼─────────────┤\n  //  │  VAR_A  │  '\"value\"'  │\n  //  │  VAR_B  │ '\u003cmissing\u003e' │\n  //  │  VAR_C  │ '\u003cmissing\u003e' │\n  //  │  VAR_D  │ '\u003cmissing\u003e' │\n  //  └─────────┴─────────────┘\n}\n```\n\n### Fail: Parser throwing\n\n#### Process startup\n\n```sh\n$ NOT_ACTUAL_NUMBER=xyz node app\n```\n\n#### Code\n\n```typescript\nfunction parser(s: string): number {\n  const p = parseInt(s);\n\n  if (isNaN(p)) {\n    throw new Error(\"Not a number\");\n  } else {\n    return p;\n  }\n}\n\nconst result = parseEnvironmentVariables({\n  NOT_ACTUAL_NUMBER: { parser }\n});\n\nif (result.success) {\n  // Won't get there\n} else {\n  console.table(result.envPrintable);\n  // ┌───────────────────┬────────────────────────────┐\n  // │      (index)      │           Values           │\n  // ├───────────────────┼────────────────────────────┤\n  // │ NOT_ACTUAL_NUMBER │ '\u003cparser: \"Not a number\"\u003e' │\n  // └───────────────────┴────────────────────────────┘\n}\n```\n\n### Configuration files\n\nIf you are reading environment variables from configuration files, for example,\nparsing `.env` file using the [`dotenv` library](https://www.npmjs.com/package/dotenv),\nbe sure to load the file BEFORE parsing. This way same validation and parsing\nrules can be applied to the merged environment variables.\n\nEasy way to avoid unsafe code is to never to access `process.env` directly, as\nit should never change after parsing. Parsing should have to be done only once.\n\n```sh\n# .env file\nHOST=localhost\n```\n\n```typescript\nimport { parseEnvironmentVariables } from \"@absxn/process-env-parser\";\n\n// Merge startup variables from .env\nrequire(\"dotenv\").config();\n\n// Account for startup variables and .env variables\nconst result = parseEnvironmentVariables({ HOST: {} });\n```\n\n## Mask\n\nHelpers for masking parts of variables for output.\n\n```typescript\nimport { Mask } from \"@absxn/process-env-parser\";\n```\n\n### `url()`\n\nA function that returns a function that applies the mask to given URL parts.\nValid URL parts are `\"hash\"`, `\"hostname\"`, `\"password\"`, `\"pathname\"`,\n`\"port\"`, `\"protocol\"`, `\"search\"`, and `\"username\"`. Can handle both URL\nstrings and URL objects (from `parser` or `default`).\n\n```typescript\nconst result = parseEnvironmentVariables({\n  API_URL: { parser: s =\u003e new URL(s), mask: Mask.url(\"password\", \"pathname\") }\n});\n```\n\nFor `API_URL=https://user:pass@1.2.3.4/api/path`, the `envPrintable` would\ncontain `{ API_URL: \"https://user:*****@1.2.3.4/*****\" }`.\n\n### `urlPassword`\n\nSame as `url(\"password\")`, resulting in\n`\"protocol://user:*****@hostname/api/path\"`\n\n### `urlUsernameAndPassword`\n\nSame as `url(\"username\", \"password\")`, resulting in\n`\"protocol://*****:*****@hostname/api/path\"`.\n\n## Combine\n\nHelpers for manipulating parser results.\n\n```typescript\nimport { Combine } from \"@absxn/process-env-parser\";\n```\n\n### Non-nullable\n\nIf you have a subset of environment variables that depend on each other, i.e.\nyou either need all of them, or none of them, this function helps to ensure\nthat.\n\n\"Nullable\" is here defined by TypeScript's `NonNullable\u003cT\u003e`, that is, `null` or\n`undefined`.\n\nLets assume we have this setup:\n\n```typescript\nfunction getConfig() {\n  // For parsing purposes, both USERNAME and PASSWORD are optional...\n  const result = parseEnvironmentVariables({\n    DATABASE: {},\n    USERNAME: { default: null },\n    PASSWORD: { default: null }\n  });\n\n  if (!result.success) {\n    return null;\n  }\n\n  const { DATABASE, USERNAME, PASSWORD } = result.env;\n\n  return {\n    // ... but for actual authentication, you need both\n    auth: Combine.nonNullable({ USERNAME, PASSWORD }),\n    db: DATABASE\n  };\n}\n```\n\nWe would get the following results with given startup parameters:\n\n```\n$ DATABASE=db USERNAME=user PASSWORD=pass node app\ngetConfig() -\u003e { auth: { USERNAME: \"user\", PASSWORD: \"pass\" }, db: \"db\" }\n\n$ DATABASE=db node app\ngetConfig() -\u003e { auth: null, db: \"db\" }\n\n$ DATABASE=db USERNAME=user node app\ngetConfig() -\u003e new Error(\"Mix of non-nullable (USERNAME) and nullable (PASSWORD) values\")\n\n$ node app\ngetConfig() -\u003e null\n```\n\nIf the object is returned, the return type has nullability removed from each\nvalue:\n\n```typescript\n// Type before: { a: string | null, b: number | undefined }\nconst nullableValues = {\n  a: Math.random() \u003e 0.5 ? \"X\" : null,\n  b: Math.random() \u003e 0.5 ? 1 : undefined\n};\n// Type after: {a: string, b: number} | null\nconst nonNullableValues = Combine.nonNullable(nullableTypes);\n```\n\n## Formatter\n\nThe library contains additional helper functions for printing out the parser\nresults. These can be useful for storing the startup configuration into logs\nor printing out startup failure reasons.\n\nImporting `Formatter` from the package:\n\n```typescript\nimport { Formatter } from \"@absxn/process-env-parser\";\n```\n\n### `console.table()`\n\nAs a built-in, `console.table()` is the easiest way to get a readable dump from\nthe parser results.\n\n```typescript\nconst result = requireEnvironmentVariables(\"VARIABLE\" /*, ...*/);\n\nconsole.table(result.envPrintable);\n// ┌──────────┬─────────┐\n// │ (index)  │ Values  │\n// ├──────────┼─────────┤\n// │ VARIABLE │ 'value' │\n// │   ...    │   ...   │\n// └──────────┴─────────┘\n```\n\n### Oneliner\n\nUsing the data from the first example:\n\n```typescript\nconst result = parseEnvironmentVariables({\n  API_KEY: { mask: true, default: null },\n  DATABASE_URL: { parser: s =\u003e new URL(s).toString() },\n  LISTEN_PORT: { parser: parseInt, default: 3000 },\n  SERVICE_NAME: {}\n});\n\nconsole.log(Formatter.oneliner(result));\n// if (result.success === true):\n// \u003e API_KEY=\u003cmasked\u003e, DATABASE_URL=\"mysql://localhost:3306/app\", LISTEN_PORT=8080, SERVICE_NAME=\"app\"\n// else:\n// \u003e API_KEY=\u003cmasked\u003e, DATABASE_URL=\u003cparser: \"Invalid URL: localhost\"\u003e, LISTEN_PORT=3000, SERVICE_NAME=\u003cmissing\u003e\n```\n\n### Multi-line\n\nOutput using same data as above example:\n\n```typescript\nconsole.log(Formatter.multiLine(result));\n// if (result.success === true):\n// \u003e API_KEY = \u003cmasked\u003e\n//   DATABASE_URL = \"mysql://localhost:3306/app\"\n//   LISTEN_PORT = 8080\n//   SERVICE_NAME = \"app\"\n// else:\n// \u003e API_KEY = \u003cmasked\u003e (default)\n//   DATABASE_URL = \u003cparser: \"Invalid URL: localhost\"\u003e\n//   LISTEN_PORT = 3000 (default)\n//   SERVICE_NAME = \u003cmissing\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsxn%2Fprocess-env-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabsxn%2Fprocess-env-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabsxn%2Fprocess-env-parser/lists"}