https://github.com/ymonb1291/cfg
Configuration handler for deno with support for .env and scopes
https://github.com/ymonb1291/cfg
cfg configuration deno dotenv
Last synced: 4 months ago
JSON representation
Configuration handler for deno with support for .env and scopes
- Host: GitHub
- URL: https://github.com/ymonb1291/cfg
- Owner: ymonb1291
- License: mit
- Created: 2020-07-27T13:51:31.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2021-06-18T15:16:29.000Z (about 5 years ago)
- Last Synced: 2025-10-20T17:50:57.523Z (8 months ago)
- Topics: cfg, configuration, deno, dotenv
- Language: TypeScript
- Homepage:
- Size: 85 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Cfg
[](https://doc.deno.land/https/deno.land/x/cfg/mod.ts)
[](https://nest.land/package/cfg)
Configuration handler for **Deno** with support for `.env` and `scopes`.
Some features require access to the file system and the environment. Please run
your project with the flags `--allow-read` and `--allow-env`.
# Getting started
Import the latest release.
```
// From Deno.land
import { Cfg } from "https://deno.land/x/cfg/mod.ts";
// From Nest.land
import { Cfg } from "https://x.nest.land/cfg/mod.ts";
// From Denopkg
import { Cfg } from "https://denopkg.com/ymonb1291/cfg/mod.ts";
// From Github
import { Cfg } from "https://raw.githubusercontent.com/ymonb1291/cfg/master/mod.ts";
```
Create and import the configuration
```
// Create
const myConfig = {fruit: "Orange"};
// Import
const cfg = Cfg([myConfig]);
```
Access properties
```
console.log(cfg.get("fruit")); // -> "Orange"
```
# Cfg function
`Cfg()` is an overloaded function with the following signature:
```
function Cfg(): Config;
function Cfg(scope: string): Config;
function Cfg(load: Source[]): Config;
function Cfg(scope: string, load: Source[]): Config;
function Cfg(options: Options): Config;
```
### Calling `Cfg()` without argument
Calling `Cfg()` without argument is used to access the `Config` registered on
the default scope. If the default scope has not been initialized, an
`UnknownScopeError` is thrown.
### Calling `Cfg()` with a scope
Calling `Cfg(scope: string)` is used to access the `Config` registered on a
non-default scope. If the scope has not been initialized, an `UnknownScopeError`
is thrown.
### Calling `Cfg()` with sources
Calling `Cfg(load: Source[])` is used to register a `Config` on the default
scope. If the default scope has already been registed, a `ScopeOverwriteError`
is thrown.
### Calling `Cfg()` with a scope and sources
Calling `Cfg(scope: string, load: Source[])` is used to register a `Config` on a
non-default scope. If the scope has already been registed, a
`ScopeOverwriteError` is thrown.
### Calling `Cfg()` with options
Calling `Cfg(options: Options)` is used to register a `Config` with an option
object. Initialization with `Options` is typically used if you want to use an
`.env` file. If the scope has already been registed, a `ScopeOverwriteError` is
thrown.
# Persistance & scopes
All configurations are persistant, they are stored by `Cfg` in the background
and can be accessed from anywhere in your application. They are not private and
can be accessed by other modules.
Scopes are like namespaces. They allow the developper to segregate
configurations. When developping a module, you should use scopes!
# Methods
## Cfg.prototype.get(...props: string[])
This method returns the configuration or one of its properties. Don't forget the
type parameters when calling `Cfg()` or you might have errors.
`Cfg.prototype.get()` allows up to 4 parameters.
## Cfg.prototype.getp(path: string)
This method returns the configuration just like `Config.prototype.get()`. But it
accepts a path as parameter with the syntax `a.b.c` or `a[b][c]`. This method
will always return a value with type unknown. Type parameters are not required
when using `getp()`
## Cfg.prototype.env(prop: string)
`Config.prototype.env()` is similar to `Config.prototype.get()` except that it
accepts only one parameter and returns environment variables.
# Options
The `Option` interfaces describes an object that can be used to configure `Cfg`.
```
interface Options {
env?: boolean | EnvOptions;
load?: Source | Source[];
scope?: string | symbol;
}
```
| Property | Type | Default | Description |
| -------- | --------------------- | ----------------- | -------------------------------------------------------------------------------------- |
| `env` | boolean \| EnvOptions | false | Allows to use `.env` files |
| `load` | Source \| Source[] | [] | Specifies the configurations to be loaded. Can be objects, functions or external files |
| `scope` | string | Symbol("DEFAULT") | Specifies the scope |
The `EnvOptions` interface describes the configuration for `.env` files.
```
interface EnvOptions {
export?: boolean;
infer?: boolean;
load?: string | Conf | (string | Conf)[]
safe?: boolean;
}
```
| Property | Type | Default | Description |
| -------- | ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `export` | boolean | false | All key/value pairs will be exported to `Deno.env` |
| `infer` | boolean | false | By default, all values are string. When `true`, the parser will try to convert numbers and booleans to their primitive types. |
| `load` | string \| Conf \| (string \| Conf)[] | ".env" | Specifies the path to the `.env` file(s) to be loaded. |
| `safe` | boolean | true | If `export` is enabled, this option will prevent overwriting in ``Deno.env` |
# Contributions
PRs are welcome!