{"id":49414181,"url":"https://github.com/daemon-node-byte/ts-env-validator","last_synced_at":"2026-04-29T02:13:31.760Z","repository":{"id":348287178,"uuid":"1197425675","full_name":"daemon-node-byte/ts-env-validator","owner":"daemon-node-byte","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-31T15:52:22.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T16:06:35.255Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/daemon-node-byte.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":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-31T15:13:46.000Z","updated_at":"2026-03-31T15:48:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daemon-node-byte/ts-env-validator","commit_stats":null,"previous_names":["daemon-node-byte/ts-env-validator"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/daemon-node-byte/ts-env-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daemon-node-byte%2Fts-env-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daemon-node-byte%2Fts-env-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daemon-node-byte%2Fts-env-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daemon-node-byte%2Fts-env-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daemon-node-byte","download_url":"https://codeload.github.com/daemon-node-byte/ts-env-validator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daemon-node-byte%2Fts-env-validator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"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":[],"created_at":"2026-04-29T02:13:28.349Z","updated_at":"2026-04-29T02:13:31.755Z","avatar_url":"https://github.com/daemon-node-byte.png","language":"TypeScript","readme":"# ts-env-validator\n\nType-safe environment variable validation for Node.js applications.\n\n`ts-env-validator` validates your environment at runtime, coerces values into useful types, and gives you full TypeScript inference from the same schema.\n\n## Why use it?\n\nEnvironment variables are always strings, but your app usually expects real types:\n\n- numbers like `PORT`\n- booleans like feature flags\n- enums like `NODE_ENV`\n- URLs like `DATABASE_URL`\n- integers like retry counts\n- floats like latency thresholds\n- JSON payloads for structured config\n- string lists like host allowlists\n\nWithout validation, bad config leaks into runtime and fails late. `ts-env-validator` fails fast at startup with a single readable error.\n\n## Installation\n\n```bash\nnpm install ts-env-validator\n```\n\nNode.js `\u003e=18` is supported.\n\n## Quick start\n\n```ts\nimport {\n  array,\n  boolean,\n  createEnv,\n  enumOf,\n  float,\n  integer,\n  json,\n  number,\n  string,\n  url,\n} from \"ts-env-validator\";\n\nexport const env = createEnv({\n  ALLOWED_HOSTS: array(),\n  NODE_ENV: enumOf([\"development\", \"test\", \"production\"]),\n  PORT: number().min(1).max(65535).default(3000),\n  DATABASE_URL: url(),\n  JWT_SECRET: string().minLength(32),\n  ENABLE_CACHE: boolean().default(false),\n  MAX_RETRIES: integer().min(1).max(10).default(3),\n  LATENCY_THRESHOLD: float().min(0.1).max(2).default(0.75),\n  FEATURE_FLAGS: json\u003c{ enabled: boolean; limit: number }\u003e().optional(),\n  LOG_LEVEL: enumOf([\"debug\", \"info\", \"warn\", \"error\"]).optional(),\n});\n```\n\nInferred result:\n\n```ts\nenv.NODE_ENV;\n// \"development\" | \"test\" | \"production\"\n\nenv.PORT;\n// number\n\nenv.MAX_RETRIES;\n// number\n\nenv.LATENCY_THRESHOLD;\n// number\n\nenv.ENABLE_CACHE;\n// boolean\n\nenv.ALLOWED_HOSTS;\n// string[]\n\nenv.FEATURE_FLAGS;\n// { enabled: boolean; limit: number } | undefined\n\nenv.LOG_LEVEL;\n// \"debug\" | \"info\" | \"warn\" | \"error\" | undefined\n```\n\n## API\n\n### `createEnv(schema, options?)`\n\nCreates a validated environment object.\n\n```ts\nconst env = createEnv(schema, {\n  env: {\n    PORT: \"4000\",\n  },\n});\n```\n\nIf `options.env` is omitted, `createEnv` reads from `process.env`.\n\n### Validators\n\n#### `string()`\n\nReturns the raw string value.\n\n```ts\nAPI_KEY: string();\n```\n\nEmpty strings are allowed.\n\nBuilt-in string constraints:\n\n- `.nonempty()`\n- `.minLength(length)`\n- `.maxLength(length)`\n- `.pattern(regex, label?)`\n\n#### `number()`\n\nParses a string into a number.\n\n```ts\nPORT: number();\n```\n\n- Uses `parseFloat`\n- Rejects invalid numeric input\n- Rejects `NaN`, `Infinity`, and empty strings\n\nBuilt-in number constraints:\n\n- `.min(value)`\n- `.max(value)`\n\n#### `integer()`\n\nParses numeric strings whose resulting value is a finite integer.\n\n```ts\nMAX_RETRIES: integer();\n```\n\nAccepted examples:\n\n- `\"3\"`\n- `\"1e3\"`\n\nRejected examples:\n\n- `\"3.14\"`\n- `\"abc\"`\n\nSupports `.min(value)` and `.max(value)`.\n\n#### `float()`\n\nParses numeric strings intended for fractional or decimal-style values.\n\n```ts\nLATENCY_THRESHOLD: float();\n```\n\nAccepted examples:\n\n- `\"3.14\"`\n- `\"1.5e2\"`\n\nRejected examples:\n\n- `\"42\"`\n- `\"1e3\"`\n\nSupports `.min(value)` and `.max(value)`.\n\n#### `boolean()`\n\nParses exact string boolean values.\n\n```ts\nENABLE_CACHE: boolean();\n```\n\nAccepted values:\n\n- `\"true\"`\n- `\"false\"`\n- `\"1\"`\n- `\"0\"`\n\n#### `enumOf([...])`\n\nValidates exact case-sensitive string values.\n\n```ts\nNODE_ENV: enumOf([\"development\", \"test\", \"production\"]);\n```\n\n#### `url()`\n\nValidates using the built-in `URL` constructor and returns a normalized string.\n\n```ts\nDATABASE_URL: url();\n```\n\nFor example, `\"https://example.com\"` becomes `\"https://example.com/\"`.\n\n#### `json\u003cT\u003e()`\n\nParses any valid JSON and returns the caller-provided type.\n\n```ts\nFEATURE_FLAGS: json\u003c{ enabled: boolean; limit: number }\u003e();\n```\n\nThis validator accepts JSON objects, arrays, primitives, and `null`.\nTyping is compile-time only; runtime validation is still plain `JSON.parse`.\n\n#### `array(separator?)`\n\nSplits a string into a trimmed `string[]`.\n\n```ts\nALLOWED_HOSTS: array();\nSCOPES: array(\";\");\n```\n\n- Default separator is `\",\"`\n- Each item is trimmed\n- Empty items are rejected\n- Separators are treated literally\n\n### Custom validators\n\n#### `createValidator({ expected, parse })`\n\nCreates a custom validator that works with `createEnv`, type inference, and all existing modifiers.\n\n```ts\nimport { createValidator } from \"ts-env-validator\";\n\nconst port = createValidator\u003cnumber\u003e({\n  expected: \"port\",\n  parse: (input) =\u003e {\n    const value = Number.parseInt(input, 10);\n\n    if (!Number.isInteger(value) || value \u003c 1 || value \u003e 65535) {\n      return {\n        success: false,\n        message: `expected port, received ${JSON.stringify(input)}`,\n      };\n    }\n\n    return {\n      success: true,\n      value,\n    };\n  },\n});\n```\n\nUse it in schemas just like a built-in validator:\n\n```ts\nconst env = createEnv({\n  PORT: port.default(3000),\n});\n```\n\nParser contract:\n\n- `parse` receives the raw string value\n- return `{ success: true, value }` on success\n- return `{ success: false, message }` on failure\n- keep parsers synchronous\n- if `parse` throws an `Error`, its `message` is surfaced as the validation failure\n- if `parse` throws a non-`Error` value, `ts-env-validator` falls back to `expected ${expected}, received ...`\n\n### Modifiers\n\n#### `.optional()`\n\nMarks a variable as optional and returns `undefined` when missing.\n\n```ts\nLOG_LEVEL: enumOf([\"debug\", \"info\"]).optional();\n```\n\n#### `.default(value)`\n\nSupplies a default when the env key is missing.\n\n```ts\nPORT: number().default(3000);\n```\n\nDefaults win over `optional()`, so a defaulted field is always inferred as required.\n\n#### `.describe(text)`\n\nAdds extra context to error messages.\n\n```ts\nDATABASE_URL: url().describe(\"Primary database connection string\");\n```\n\n### Built-in constraint examples\n\n```ts\ncreateEnv({\n  PORT: number().min(1).max(65535).default(3000),\n  JWT_SECRET: string().minLength(32),\n  REQUEST_ID: string().pattern(/^[a-f0-9-]+$/i, \"UUID pattern\"),\n  MAX_RETRIES: integer().min(1).max(10).default(3),\n  LATENCY_THRESHOLD: float().min(0.1).max(2).default(0.75),\n});\n```\n\nConstraint modifiers are immutable and compose with `.optional()`, `.default()`, and `.describe()`.\nDefaults for constrained built-ins are validated immediately, so invalid defaults throw a `TypeError` during schema creation.\n\n## Error handling\n\nValidation failures are collected across the whole schema and thrown as one `EnvValidationError`.\n\n```txt\nEnvironment validation failed\n\nMissing required variables:\n- JWT_SECRET (Token signing secret)\n\nInvalid variables:\n- PORT (HTTP port): expected number, received \"abc\"\n- NODE_ENV: expected one of development | production, received \"prod\"\n```\n\nThe error instance exposes:\n\n- `error.missing`\n- `error.invalid`\n- `error.message`\n\n## Custom env objects\n\nPassing a custom env object is useful in tests, scripts, and edge runtimes:\n\n```ts\nconst env = createEnv(\n  {\n    PORT: number().default(3000),\n    ENABLE_CACHE: boolean(),\n  },\n  {\n    env: {\n      ENABLE_CACHE: \"true\",\n    },\n  },\n);\n```\n\n## Examples\n\n### Node.js\n\n```ts\nimport {\n  array,\n  createEnv,\n  float,\n  integer,\n  json,\n  number,\n  string,\n  url,\n} from \"ts-env-validator\";\n\nexport const env = createEnv({\n  ALLOWED_HOSTS: array(),\n  PORT: number().min(1).max(65535).default(3000),\n  DATABASE_URL: url(),\n  JWT_SECRET: string().minLength(32),\n  MAX_RETRIES: integer().min(1).max(10).default(3),\n  LATENCY_THRESHOLD: float().min(0.1).max(2).default(0.75),\n  SERVICE_METADATA: json\u003c{ region: string; team: string }\u003e().optional(),\n});\n```\n\n### Next.js\n\n```ts\nimport { array, createEnv, json, string } from \"ts-env-validator\";\n\nexport const env = createEnv({\n  NEXT_PUBLIC_ENABLED_LOCALES: array(),\n  NEXT_PUBLIC_API_URL: string().pattern(/^https?:\\/\\//, \"HTTP URL\"),\n  NEXT_PUBLIC_THEME_CONFIG: json\u003c{\n    accent: string;\n    compact: boolean;\n  }\u003e().optional(),\n});\n```\n\n## Development\n\n```bash\nnpm install\nnpm run lint\nnpm run typecheck\nnpm test\nnpm run build\n```\n\nMaintainers: pushing a version tag like `v0.4.0` runs the publish workflow, releasing `ts-env-validator` to npmjs and `@\u003crepository-owner\u003e/ts-env-validator` to GitHub Packages. The published npm tarball includes both `README.md` and `LICENSE`.\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaemon-node-byte%2Fts-env-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaemon-node-byte%2Fts-env-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaemon-node-byte%2Fts-env-validator/lists"}