# @toa.io/extensions.configuration

> Toa Configuration

Latest version **0.24.0-alpha.0** (published 2023-11-16) · 0 weekly downloads

## Install

```sh
npm install @toa.io/extensions.configuration
pnpm add @toa.io/extensions.configuration
yarn add @toa.io/extensions.configuration
bun add @toa.io/extensions.configuration
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high maintenance score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.24.0-alpha.0 |
| Published | 2023-11-16 |
| First published | 2023-03-11 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 84.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | temich |
| Maintainers | agurtovoi |

## Links

- npm: https://www.npmjs.com/package/@toa.io/extensions.configuration
- Repository: https://github.com/toa-io/toa
- Homepage: https://github.com/toa-io/toa#readme
- Issues: https://github.com/toa-io/toa/issues
- npm.io page: https://npm.io/package/@toa.io/extensions.configuration

## Dependencies (3)

- [@toa.io/core](https://npm.io/package/@toa.io/core.md) 0.24.0-alpha.0
- [@toa.io/generic](https://npm.io/package/@toa.io/generic.md) 0.24.0-alpha.0
- [@toa.io/schemas](https://npm.io/package/@toa.io/schemas.md) 0.24.0-alpha.0

## Recent versions

- 0.24.0-alpha.0 (latest) — 2023-11-16
- 1.0.0-alpha.344 (alpha) — 2026-11-04
- 1.0.2-alpha.56 (canary) — 2023-05-30
- 0.4.0-dev.9 (dev) — 2023-04-10
- 1.0.0-alpha.343 — 2026-10-29
- 1.0.0-alpha.342 — 2026-10-28
- 1.0.0-alpha.341 — 2026-10-28
- 1.0.0-alpha.340 — 2026-10-28
- 1.0.0-alpha.339 — 2026-10-28
- 1.0.0-alpha.338 — 2026-10-28
- 1.0.0-alpha.337 — 2026-10-28
- 1.0.0-alpha.336 — 2026-10-26
- 1.0.0-alpha.335 — 2026-10-26
- 1.0.0-alpha.333 — 2026-10-26
- 1.0.0-alpha.332 — 2026-10-23
- … 296 more at https://npm.io/package/@toa.io/extensions.configuration/versions

## README

# Toa Configuration

## TL;DR

### Define

```yaml
# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: string
    bar: number
  defaults:
    foo: bar
    bar: 1
```

### Use

```javascript
function transition (input, entity, context) {
  const { foo, bar } = context.configuration

  // ...
}
```

### Override

```yaml
# context.toa.yaml
configuration:
  dummies.dummy:
    foo: qux          # override default value
    foo@staging: quux # deployment environment discriminator
    bar: $BAZ_VALUE   # secret
```

### Deploy secrets

```shell
$ toa conceal configuration BAZ_VALUE=$ecr3t
```

---

## Problem Definition

- Components should be runnable in different deployment environments.
- Some algorithm's parameters should be deployed secretly.
- Components should be reusable in different contexts.

## Manifest

Component's configuration is declared using `configuration` manifest,
containing `schema` and optionnaly `defaults` properties.

### Schema

Configuration schema is declared with [COS](/libraries/concise).

```yaml
# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: string
    bar: number
```

> Introducing non-backward compatible changes to a configuration schema will result in a loss of
> compatibility with existing contexts and deployment environments.
> Therefore, configuration schema changes are subject to component versioning.

If `configuration` object doesn't contain property `schema`, then it is considered to be schema.

```yaml
# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  foo: string
  bar: number
```

### Defaults

The default configuration value can be provided using the `defaults` property, which should conform
to the configuration schema.

```yaml
# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: string
    bar: number
  defaults:
    foo: hello
    bar: 0
```

#### Schema defaults hint

The configuration schema itself can contain default primitive values using the COS syntax.

```yaml
# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: hello
    bar: 0
```

## Annotation

A component's configuration can be overridden using the configuration context annotation.

```yaml
# context.toa.yaml
configuration:
  dummies.dummy:
    foo: bye
    bar: 1
    bar@staging: 2
```

## Secrets

Configuration annotation top-level values which are uppercase strings prefixed with `$` considered as secrets.

```yaml
# context.toa.yaml
configuration:
  payments.gateway:
    api-key: $STRIPE_API_KEY
```

Secrets are not being deployed with context
deployment ([`toa deploy`](/runtime/cli/readme.md#deploy)), thus must be deployed separately at
least once for each deployment environment
manually ([`toa conceal`](/runtime/cli/readme.md#conceal)).

Deployed kubernetes secret's name is predefined as `configuration`.

```shell
$ toa conceal configuration STRIPE_API_KEY=xxxxxxxx
```

## Aspect

Component's configuration values are available as a well-known Aspect `configuration`.

```javascript
function transition (input, entity, context) {
  const foo = context.configiuration.foo

  // ...
}
```

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