{"id":29436235,"url":"https://github.com/stone-foundation/stone-js-env","last_synced_at":"2025-09-02T11:36:48.306Z","repository":{"id":199798155,"uuid":"703779966","full_name":"stone-foundation/stone-js-env","owner":"stone-foundation","description":"Fluent and simple API to deal with .env file and env variable in node.js","archived":false,"fork":false,"pushed_at":"2025-08-17T06:51:22.000Z","size":442,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-23T04:03:19.327Z","etag":null,"topics":["context-aware","continuum-architecture","dotenv","javascript","official-stonejs","stone-foundation","stonejs","stonejs-core","typescript"],"latest_commit_sha":null,"homepage":"https://stonejs.dev","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/stone-foundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-11T22:50:42.000Z","updated_at":"2025-07-19T13:18:55.000Z","dependencies_parsed_at":"2024-05-11T23:25:56.461Z","dependency_job_id":"42efcc93-ebd7-436c-8210-3f3f3fe67e03","html_url":"https://github.com/stone-foundation/stone-js-env","commit_stats":null,"previous_names":["stonemjs/env","stone-foundation/stone-js-env"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/stone-foundation/stone-js-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stone-foundation","download_url":"https://codeload.github.com/stone-foundation/stone-js-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stone-foundation%2Fstone-js-env/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273278923,"owners_count":25077307,"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","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"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":["context-aware","continuum-architecture","dotenv","javascript","official-stonejs","stone-foundation","stonejs","stonejs-core","typescript"],"created_at":"2025-07-13T05:01:38.565Z","updated_at":"2025-09-02T11:36:48.290Z","avatar_url":"https://github.com/stone-foundation.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stone.js - Env\n\n[![npm](https://img.shields.io/npm/l/@stone-js/env)](https://opensource.org/licenses/MIT)\n[![npm](https://img.shields.io/npm/v/@stone-js/env)](https://www.npmjs.com/package/@stone-js/env)\n[![npm](https://img.shields.io/npm/dm/@stone-js/env)](https://www.npmjs.com/package/@stone-js/env)\n![Maintenance](https://img.shields.io/maintenance/yes/2025)\n[![Build Status](https://github.com/stone-foundation/stone-js-env/actions/workflows/main.yml/badge.svg)](https://github.com/stone-foundation/stone-js-env/actions/workflows/main.yml)\n[![Publish Package to npmjs](https://github.com/stone-foundation/stone-js-env/actions/workflows/release.yml/badge.svg)](https://github.com/stone-foundation/stone-js-env/actions/workflows/release.yml)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-env\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-env)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-env\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-env)\n[![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](./SECURITY.md)\n[![CodeQL](https://github.com/stone-foundation/stone-js-env/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/stone-foundation/stone-js-env/security/code-scanning)\n[![Dependabot Status](https://img.shields.io/badge/Dependabot-enabled-brightgreen.svg)](https://github.com/stone-foundation/stone-js-env/network/updates)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\nFluent and simple API to deal with .env file and env variables for both browser and node.js.\n\n---\n\n## Overview\n\nThe `@stone-js/env` library provides utility functions for managing environment variables in JavaScript and TypeScript applications. It helps developers retrieve, validate, and transform environment variables, supporting different data types such as strings, numbers, booleans, arrays, objects, and more. This ensures that the environment configuration is reliable and meets the expected requirements. This library is compatible with both vanilla JavaScript and TypeScript.\n\n## Installation\n\n```bash\nnpm i @stone-js/env\n# or\nyarn add @stone-js/env\n# or\npnpm add @stone-js/env\n```\n\n\u003e \\[!IMPORTANT]\n\u003e This package is **pure ESM**. Ensure your `package.json` includes `\"type\": \"module\"` or configure your bundler appropriately.\n\n```ts\nimport { getNumber, getEmail } from '@stone-js/env'\n```\n\n## Getting Started\n\nTo start using the `@stone-js/env` library, you need to import the functions you want to use in your project. Below is a simple example of how to use the library to retrieve environment variables and ensure they meet the necessary validation requirements.\n\n```typescript\nimport { get, getString, getNumber, getBoolean } from '@stone-js/env';\n\n// Retrieving an environment variable as a string\nconst apiUrl = getString('API_URL');\n\n// Retrieving an environment variable as a number\nconst port = getNumber('PORT', { default: 3000 });\n\n// Retrieving a boolean environment variable\nconst isProduction = getBoolean('IS_PRODUCTION', { default: false });\n```\n\n## Usage\n\nThe `@stone-js/env` library provides multiple functions to retrieve environment variables in different formats, allowing for strong validation and type safety. Below are the available functions and their descriptions:\n\n### Options Interface\n\nThe `Options` interface provides configuration options for retrieving environment variables. Below are the properties available in the `Options` interface:\n\n- **`type`** (`'number' | 'boolean' | 'array' | 'object' | 'json' | 'enum' | 'email' | 'host' | 'url' | 'string'`): Specifies the expected type of the environment variable.\n- **`format`** (`'url' | 'host' | 'email'`): Specifies the format of the value if it is a string.\n- **`enums`** (`string[]`): An array of possible values for enum validation.\n- **`optional`** (`boolean`): Indicates if the environment variable is optional.\n- **`default`** (`any`): The default value if the environment variable is not set.\n- **`separator`** (`string`): Separator for parsing array or object values (default is `','`).\n- **`tld`** (`boolean`): Indicates if a top-level domain is required for URLs or emails.\n- **`protocol`** (`boolean`): Indicates if a protocol is required for URLs.\n- **`version`** (`IPVersion`): Specifies the IP version if the type is `'host'`.\n\n### `get\u003cT\u003e(key: string, options?: Options | any): T`\n\nRetrieves the value of a specified environment variable.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options | any): Options for retrieving the value.\n- **Returns**: The value of the environment variable, with the expected type `T`.\n\n### `getString(key: string, options?: Options | string): string`\n\nRetrieves the specified environment variable value as a string.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options | string): Options for retrieving the value.\n- **Returns**: The value as a string.\n\n### `getNumber(key: string, options?: Options): number`\n\nRetrieves the specified environment variable value as a number.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as a number.\n\n### `getBoolean(key: string, options?: Options): boolean`\n\nRetrieves the specified environment variable value as a boolean.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as a boolean.\n\n### `getArray(key: string, options?: Options): string[]`\n\nRetrieves the specified environment variable value as an array of strings.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as an array of strings.\n\n### `getObject(key: string, options?: Options): Record\u003cstring, any\u003e`\n\nRetrieves the specified environment variable value as an object.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as an object.\n\n### `getJson(key: string, options?: Options): unknown`\n\nRetrieves the specified environment variable value as a JSON object.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as a JSON object.\n\n### `getEnum(key: string, enums: string[] | Options = [], defaultValue?: string, options?: Options): string`\n\nRetrieves the specified environment variable value as an enum.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `enums` (string[] | Options): Array of possible enum values or options.\n  - `defaultValue` (string, optional): Default value if not set.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as an enum.\n\n### `getEmail(key: string, options?: Options): string`\n\nRetrieves the specified environment variable value as an email address.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as an email address.\n\n### `getUrl(key: string, options?: Options): string`\n\nRetrieves the specified environment variable value as a URL.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as a URL.\n\n### `getHost(key: string, options?: Options): string`\n\nRetrieves the specified environment variable value as a host (IP or URL).\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `options` (Options): Options for retrieving the value.\n- **Returns**: The value as a host.\n\n### `custom(key: string, validator: (key: string, value: any, options: Options) =\u003e any, options?: Options | any): any`\n\nRetrieves and validates the value of the specified environment variable using a custom validator function.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n  - `validator` (function): A custom validation function.\n  - `options` (Options | any): Options for retrieving the value.\n- **Returns**: The validated value of the environment variable.\n\n### `clearCache(): void`\n\nClears the environment variable cache.\n\n- **Returns**: Nothing.\n\n### `is(env: string): boolean`\n\nDetermines if the current environment matches the given value.\n\n- **Parameters**:\n  - `env` (string): The environment to check.\n- **Returns**: `true` if the current environment matches the given value, otherwise `false`.\n\n### `isProduction(): boolean`\n\nDetermines if the current environment is production.\n\n- **Returns**: `true` if in a production environment, otherwise `false`.\n\n### `isNotProduction(): boolean`\n\nDetermines if the current environment is not production.\n\n- **Returns**: `true` if not in a production environment, otherwise `false`.\n\n### `isProd(): boolean`\n\nDetermines if the current environment is prod.\n\n- **Returns**: `true` if in a prod environment, otherwise `false`.\n\n### `isNotProd(): boolean`\n\nDetermines if the current environment is not prod.\n\n- **Returns**: `true` if not in a prod environment, otherwise `false`.\n\n### `isTesting(): boolean`\n\nDetermines if the current environment is testing.\n\n- **Returns**: `true` if in a testing environment, otherwise `false`.\n\n### `getEnv(key: string): string | undefined`\n\nRetrieves the value of a system environment variable. Works for both Node.js and browser environments.\n\n- **Parameters**:\n  - `key` (string): The environment variable key.\n- **Returns**: The value of the environment variable or `undefined` if not found.\n\n## Summary\n\nThe `@stone-js/env` library is a versatile tool for managing environment variables in both JavaScript and TypeScript projects. It provides robust validation and transformation capabilities for different data types, making it easy to ensure that environment configuration values are reliable and properly formatted. With support for custom validation, caching, and multiple data formats, this library simplifies environment management for modern web and server-side applications.\n\n## Learn More\n\nThis package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.\n\nExplore the full documentation: [https://stonejs.dev](https://stonejs.dev)\n\n## API documentation\n\n- [API](https://github.com/stone-foundation/stone-js-env/blob/main/docs/modules.md)\n\n## Contributing\n\nSee [Contributing Guide](https://github.com/stone-foundation/stone-js-env/blob/main/CONTRIBUTING.md).\n\n## Credits\n\nThanks to [valibot](https://valibot.dev) for the validation library used in this project.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstone-foundation%2Fstone-js-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstone-foundation%2Fstone-js-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstone-foundation%2Fstone-js-env/lists"}