Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fumieval/evp-ts
simple environment variable parser for TypeScript
https://github.com/fumieval/evp-ts
Last synced: 2 months ago
JSON representation
simple environment variable parser for TypeScript
- Host: GitHub
- URL: https://github.com/fumieval/evp-ts
- Owner: fumieval
- License: mit
- Created: 2024-05-02T06:14:49.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2024-06-18T15:49:56.000Z (6 months ago)
- Last Synced: 2024-09-19T04:18:50.000Z (3 months ago)
- Language: TypeScript
- Size: 189 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# evp-ts: Environment Variable Parser for TypeScript
[](https://badge.fury.io/js/evp-ts)
evp-ts is a lightweight and easy-to-use library for parsing environment variables in TypeScript projects. It provides a simple way to collect and validate environment variables.
This package is inspired by [zod](https://zod.dev/) and [EVP](https://github.com/fumieval/EVP), an environment variable parser library for Haskell.
## Features
- 🧹 Clutter-free code
- 🌳 Supports nested structure
- 🧩 Well-typed interface
- 📝 Explicit logging of parsed environment variables
- 🔒 Hiding sensitive values (e.g. API keys) from logs
- 🛡️ Graceful handling of missing or invalid environment variables
## Usage
Here's an example of how to use evp-ts in your TypeScript project:
```typescript
import { EVP } from 'evp-ts';
const parser = EVP.object({
API_ENDPOINT: EVP.string(),
API_TOKEN: EVP.string().secret(),
HTTP_PORT: EVP.number(),
DEBUG_MODE: EVP.boolean().default(false),
});
type Config = EVP.TypeOf;
const result: Config = parser.parse();
console.log(result);
```
```
[EVP] API_ENDPOINT=https://example.com
[EVP] API_TOKEN=
[EVP] HTTP_PORT=8080
[EVP] DEBUG_MODE=false (default)
[EVP] MYSQL_HOST=localhost (default)
[EVP] MYSQL_PORT=3306 (default)
{
API_ENDPOINT: 'https://api.example.com',
API_TOKEN: '00000000-0000-0000-0000-000000000000',
HTTP_PORT: 3000,
DEBUG_MODE: false,
mysql: { host: 'localhost', port: '3306', user: 'root' }
}
```
In this example, we define a parser using the `EVP.object()` function, which takes an object describing the structure and types of the environment variables. Each key in the object represents an environment variable, and the corresponding value defines its type and any additional options (e.g. default values, secret flag).
The `exec()` method is then called on the parser to parse the environment variables and return an object with the parsed values. If any required environment variables are missing or have invalid values, evp-ts will log an error message but continue parsing the remaining variables to provide a comprehensive error report.
## Supported Types
evp-ts supports the following types for parsing environment variables:
- `EVP.string()`: Get the value as a string.
- `EVP.number()`: Parses the value as a number.
- `EVP.boolean()`: Parses the value as a boolean (`true`, `yes`, and `1` becomes `true` and `false`, `no`, `0` becomes `false`).
- `EVP.object()`: Defines a nested object structure for grouping related environment variables.
## Modifiers
evp-ts provides additional options for configuring the behavior of environment variable parsing:
- `.default(value)`: Specifies a default value to use if the environment variable is not set.
- `.secret()`: Marks the environment variable as sensitive, hiding its value from logs.
## Generating Help Text
`parser.describe()` generates a dotenv-style help text from the parser.
For this purpose, `.description(text)` and `.metavar(name)` methods are provided.
If `.metavar(name)` is not specified, the default value or the type name is used as the metavariable name.
```typescript
import { EVP } from 'evp-ts';
const parser = EVP.object({
API_ENDPOINT: EVP.string().description('The base URL of the API'),
API_TOKEN: EVP.string().secret().metavar('TOKEN'),
HTTP_PORT: EVP.number().description('The port number to listen on'),
DEBUG_MODE: EVP.boolean().default(false),
});
console.log(parser.describe());
```
```
# The base URL of the API
API_ENDPOINT=
API_TOKEN=TOKEN
# The port number to listen on
HTTP_PORT=
DEBUG_MODE=false
```
## Discriminated Unions
In the following example, the `DATABASE_BACKEND` environment variable is used to switch between different sets of environment variables for different database backends.
The `EVP.union()` function is used to define a union of different parsers.
The `options()` method is then used to define a set of parsers for each possible value of `DATABASE_BACKEND`.
The field specified by the `discriminator()` contains the value of `DATABASE_BACKEND`.
If `DATABASE_BACKEND` is not set, it will use the default option specified by the `.default()` method.
```typescript
import { EVP } from 'evp-ts';
const parser = EVP.object({
DATABASE_BACKEND: EVP.union()
.discriminator('backend')
.options({
mysql: EVP.object({
host: EVP.string('MYSQL_HOST').default('localhost'),
port: EVP.number('MYSQL_PORT').default(3306),
}).description('MySQL database connection settings'),
sqlite: EVP.object({
path: EVP.string('SQLITE_PATH'),
}),
})
// .default('sqlite'),
});
console.log(parser.describe());
console.log(parser.parse());
```
## Customising the logger
By default, evp-ts uses the `console` object to log messages. You can customize the logger by calling `.logger()` on the parser object.
```typescript
import { EVP } from 'evp-ts';
const parser = EVP.object({
API_ENDPOINT: EVP.string(),
}).logger({
success(key, value, useDefault){
console.log(`${key}=${useDefault ? `(default) ${value}` : value}`);
},
error(key, value, error){
console.error(`${key}=${value}: ${error.message}`);
},
});
parser.parse();
```
## License
evp-ts is open-source software licensed under the [MIT License](https://opensource.org/licenses/MIT).