{"id":15636442,"url":"https://github.com/eniiju/safe-yaml-env","last_synced_at":"2026-02-12T18:01:56.157Z","repository":{"id":257807264,"uuid":"866373821","full_name":"eNiiju/safe-yaml-env","owner":"eNiiju","description":"Parse YAML files safely with schema validation, supporting environment variables and default values.","archived":false,"fork":false,"pushed_at":"2024-11-09T22:31:06.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-19T13:39:39.949Z","etag":null,"topics":["deno","environment-variables","yaml","zod"],"latest_commit_sha":null,"homepage":"https://jsr.io/@niiju/safe-yaml-env","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/eNiiju.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}},"created_at":"2024-10-02T06:24:50.000Z","updated_at":"2024-11-09T22:31:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"30866b94-867f-4441-8c63-3bd4ccce67af","html_url":"https://github.com/eNiiju/safe-yaml-env","commit_stats":{"total_commits":14,"total_committers":1,"mean_commits":14.0,"dds":0.0,"last_synced_commit":"ec8289d5e7d576e56a812b5fb7ac0269a0e71e8c"},"previous_names":["eniiju/safe-yaml-env"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eNiiju/safe-yaml-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eNiiju%2Fsafe-yaml-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eNiiju%2Fsafe-yaml-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eNiiju%2Fsafe-yaml-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eNiiju%2Fsafe-yaml-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eNiiju","download_url":"https://codeload.github.com/eNiiju/safe-yaml-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eNiiju%2Fsafe-yaml-env/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29375597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["deno","environment-variables","yaml","zod"],"created_at":"2024-10-03T11:04:02.206Z","updated_at":"2026-02-12T18:01:56.139Z","avatar_url":"https://github.com/eNiiju.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# safe-yaml-env\n\nParse YAML files safely with schema validation, supporting environment variables\nand default values.\n\nThis library uses [@std/yaml](https://jsr.io/@std/yaml) for the YAML parsing and\n[Zod](https://zod.dev) for the schema validation.\n\n## Usage\n\n### Load YAML Synchronously\n\n\u003e config.yaml\n\n```yaml\n---\nname: Loris Ipsum\nage: 25\n```\n\n\u003e main.ts\n\n```typescript\nimport { load } from \"@niiju/safe-yaml-env/zod\";\nimport { z } from \"zod\";\n\nconst schema = z.object({\n  name: z.string(),\n  age: z.number(),\n}).strict();\n\nconst data = load(\"./config.yaml\", schema);\nconsole.log(data); // { name: 'Loris Ipsum', age: 25 }\n```\n\n### Load YAML Asynchronously\n\n\u003e config.yaml\n\n```yaml\n---\nname: Loris Ipsum\nage: 25\n```\n\n\u003e main.ts\n\n```typescript\nimport { loadAsync } from \"@niiju/safe-yaml-env/zod\";\nimport { z } from \"zod\";\n\nconst schema = z.object({\n  name: z.string(),\n  age: z.number(),\n}).strict();\n\nconst data = await loadAsync(\"./config.yaml\", schema);\nconsole.log(data); // { name: 'Loris Ipsum', age: 25 }\n```\n\n### Environment Variables in YAML\n\nYAML files can include references to environment variables, like `${ENV_VAR}`,\nwhich will be replaced with their corresponding values from the environment (or\nthrow an error if it's not set).\n\n\u003e config.yaml\n\n```yaml\n---\nname: ${ENV_NAME} # ENV_NAME must be defined\nage: 25\n```\n\n\u003e main.ts\n\n```typescript\nconst data = load(\"./config.yaml\", schema);\nconsole.log(data); // { name: 'Loris Ipsum', age: 25 }\n```\n\n### Default environment variable values in the YAML file\n\nYou can provide a default value for an environment variable by using\n`${ENV_VAR:-default}`. If the environment variable is not set, the default value\nwill be used, and won't throw an error.\n\n\u003e config.yaml\n\n```yaml\n---\nname: ${ENV_NAME:-John Doe}\nage: 25\n```\n\n### Default values in the Zod schema\n\nYou can also provide a default value for an environment variable by using the\n`default` method of the Zod schema. If the environment variable is not set, the\ndefault value will be used, and won't throw an error.\n\n_Note: default values in the YAML file have precedence over default values in\nthe Zod schema._\n\n\u003e main.ts\n\n```typescript\nconst schema = z.object({\n  name: z.string().default(\"John Doe\"),\n  age: z.number(),\n}).strict();\n```\n\n#### Type coercion\n\nEnvironment variables are always of type `string`. If you want to parse them as\nanother type, you can use Zod's `coerce` as follows :\n\n\u003e main.ts\n\n```typescript\nconst schema = z.object({\n  name: z.string(),\n  age: z.coerce.number(), // This will try to convert the type to number\n}).strict();\n```\n\nNow, if the `age` property is referenced from an environment variable inside the\nYAML file, the type will be converted from `string` to `number` (if possible),\ninstead of throwing an error.\n\n## Error Handling\n\nThe following errors can be thrown:\n\n- `FileNotFoundError`: Thrown if the YAML file is not found.\n- `SyntaxError`: Thrown if the YAML file is invalid.\n- `MissingEnvVarError`: Thrown if an environment variable is referenced but not\n  set.\n- `ZodError`: Thrown if the data doesn't conform to the Zod schema.\n\n\u003e main.ts\n\n```typescript\nimport { load } from \"@niiju/safe-yaml-env/zod\";\nimport { FileNotFoundError, MissingEnvVarError } from \"@niiju/safe-yaml-env\";\nimport { ZodError } from \"zod\";\n\ntry {\n  load(\"./config.yaml\", schema);\n} catch (error) {\n  if (error instanceof FileNotFoundError) {\n    console.error(\"File not found\");\n  } else if (error instanceof SyntaxError) {\n    console.error(\"Invalid YAML\");\n  } else if (error instanceof MissingEnvVarError) {\n    console.error(\"Missing environment variable:\", error.envVarKey);\n  } else if (error instanceof ZodError) {\n    console.error(\"Invalid data:\", error.errors);\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feniiju%2Fsafe-yaml-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feniiju%2Fsafe-yaml-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feniiju%2Fsafe-yaml-env/lists"}