# extol

> Simple decorator-driven TypeScript externalization library

Latest version **1.4.5** (published 2026-10-27) · ISC license · 0 weekly downloads

## Install

```sh
npm install extol
pnpm add extol
yarn add extol
bun add extol
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.4.5 |
| Published | 2026-10-27 |
| First published | 2021-10-18 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 2 |
| Unpacked size | 17 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | Csaba Sulyok <csaba.sulyok@gmail.com> |
| Maintainers | csabasulyok |

## Links

- npm: https://www.npmjs.com/package/extol
- Repository: https://github.com/csabasulyok/extol
- npm.io page: https://npm.io/package/extol

## Dependencies (2)

- [dotenv](https://npm.io/package/dotenv.md) 17.4.2
- [change-case](https://npm.io/package/change-case.md) 5.4.4

## Recent versions

- 1.4.5 (latest) — 2026-10-27
- 1.4.4 — 2026-03-09
- 1.4.3 — 2026-03-09
- 1.4.2 — 2026-03-09
- 1.4.1 — 2026-03-09
- 1.4.0 — 2026-03-09
- 1.3.1 — 2023-11-19
- 1.3.0 — 2023-11-19
- 1.2.3 — 2022-09-30
- 1.2.2 — 2022-09-27
- 1.1.0 — 2022-09-25
- 1.0.3 — 2022-09-21
- 1.0.2 — 2022-01-23
- 1.0.1 — 2021-11-03
- 1.0.0 — 2021-10-18

## README

# extol

**Simple decorator-driven TypeScript externalization library.**

Install with:

```bash
npm i extol
```

## Functionalities

- Read environment variables, `.env` files (via the `dotenv` library) or regress to default values
- Type safety
- Read values either from file (for secrets)
- Read complex types from markup formats, e.g. JSON

## Usage

### Decorators

- run `npm run example:decorator`

```ts
import extol from 'extol';

/**
 * Example class to show automated externalization
 */
class ExampleConfiguration {
  /**
   * Value will be read from:
   * - HOST environment variable
   * - HOST entry in .env file
   * - default value given as parameter
   */
  @extol('localhost')
  host: string;

  /**
   * Numeric type is retained.
   */
  @extol(5672)
  port: number;

  /**
   * Override used environment variable,
   * otherwise it's deduced from property name.
   */
  @extol('guest', { envVarName: 'CUSTOM_USERNAME' })
  username: string;

  /**
   * Allow reading filename from *_FILE env var.
   * Here, if PASSWORD_FILE is set and points to a file, its content is used as the value.
   */
  @extol('guest', { fileVariant: true })
  password: string;

  /**
   * Assume JSON in env var or file, deserialize it automatically.
   */
  @extol(false, { json: true })
  rememberPassword: boolean;

  @extol({}, { json: true, fileVariant: true })
  extraArgs: { [key: string]: string };

  toString(): string {
    return `ExampleConfiguration {
      host: ${this.host}, type=${this.host?.constructor?.name},
      port: ${this.port}, type=${this.port?.constructor?.name},
      username: ${this.username}, type=${this.username?.constructor?.name},
      password: ${this.password}, type=${this.password?.constructor?.name},
      rememberPassword: ${this.rememberPassword}, type=${this.rememberPassword?.constructor?.name}
      extraArgs: ${JSON.stringify(this.extraArgs || {})}, type=${this.extraArgs?.constructor?.name},
    }`;
  }
}

/**
 * Default instance
 */
const c = new ExampleConfiguration();
console.log(c.toString());
```

### Simple

- run `npm run example:simple`

```ts
/**
 * Value will be read from:
 * - HOST environment variable
 * - HOST entry in .env file
 * - default value given as second parameter
 */
const host = load<string>('host', 'localhost');

/**
 * Numeric type is retained.
 */
const port = load<number>('port', 5672);

/**
 * Override used environment variable,
 * otherwise it's deduced from property name.
 */
const username = load<string>('username', 'guest', { envVarName: 'CUSTOM_USERNAME' });

/**
 * Allow reading filename from *_FILE env var.
 * Here, if PASSWORD_FILE is set and points to a file, its content is used as the value.
 */
const password = load<string>('password', 'guest', { fileVariant: true });

/**
 * Assume JSON in env var or file, deserialize it automatically.
 */
const rememberPassword = load<boolean>('rememberPassword', false, { json: true });

const extraArgs = load<{ [key: string]: string }>('extraArgs', {}, { json: true, fileVariant: true });

/**
 * Demonstrate
 */
console.log(`ExampleConfiguration {
  host: ${host}, type=${host?.constructor?.name},
  port: ${port}, type=${port?.constructor?.name},
  username: ${username}, type=${username?.constructor?.name},
  password: ${password}, type=${password?.constructor?.name},
  rememberPassword: ${rememberPassword}, type=${rememberPassword?.constructor?.name}
  extraArgs: ${JSON.stringify(extraArgs || {})}, type=${extraArgs?.constructor?.name},
}`);
```

---
_Source: https://npm.io/package/extol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._