# @x12i/env-tokens

> Resolve {{ENV.*}} tokens in strings using environment variables with case-insensitive and camel-to-snake lookup.

Latest version **1.0.0** (published 2026-05-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/env-tokens
pnpm add @x12i/env-tokens
yarn add @x12i/env-tokens
bun add @x12i/env-tokens
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-05-22 |
| First published | 2026-05-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 51.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |
| Keywords | env, environment, tokens, template, substitution |

## Links

- npm: https://www.npmjs.com/package/@x12i/env-tokens
- npm.io page: https://npm.io/package/@x12i/env-tokens

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 1.0.0 (latest) — 2026-05-22

## README

# @x12i/env-tokens

Resolve `{{ENV.*}}` tokens in strings using environment variables, with flexible key matching (exact, case-insensitive, and camelCase → snake_case).

## Install

```bash
npm install @x12i/env-tokens
```

## Usage

```ts
import { resolveEnvTokens } from "@x12i/env-tokens";

const output = resolveEnvTokens(
  "mongodb://{{ENV.dbUser}}:{{ENV.dbPassword}}@{{ENV.sourceDatabaseHost}}/{{ENV.sourceDatabaseName}}",
  {
    env: {
      DB_USER: "admin",
      DB_PASSWORD: "secret",
      SOURCE_DATABASE_HOST: "mongo.example.com",
      SOURCE_DATABASE_NAME: "production_db",
    },
  }
);
// mongodb://admin:secret@mongo.example.com/production_db
```

By default, `env` is `process.env` and missing tokens throw `MissingEnvTokenError`.

## Token format

Only tokens in this form are resolved:

```txt
{{ENV.variableName}}
```

Examples: `{{ENV.sourceDatabaseName}}`, `{{ENV.API_KEY}}`

Not supported: expressions, nested paths, or other namespaces (`{{CONFIG.x}}`).

## Lookup order

For `{{ENV.sourceDatabaseName}}`, the package tries:

1. `sourceDatabaseName` (exact)
2. `sourceDatabaseName` (case-insensitive)
3. `source_database_name` (camel → snake, exact)
4. `source_database_name` (camel → snake, case-insensitive)

So env keys like `SOURCE_DATABASE_NAME`, `source_database_name`, and `SourceDatabaseName` all work.

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `env` | `process.env` | Environment source |
| `onMissing` | `"throw"` | `"keep"`, `"empty"`, or `"throw"` |
| `allowEmpty` | `true` | Treat `""` as a valid value |
| `trimTokenName` | `true` | Trim whitespace inside `{{ENV. … }}` |
| `caseInsensitive` | `true` | Case-insensitive key matching |
| `camelToSnake` | `true` | Fallback via snake_case keys |

## Detailed diagnostics

```ts
import { resolveEnvTokensDetailed } from "@x12i/env-tokens";

const result = resolveEnvTokensDetailed("DB={{ENV.sourceDatabaseName}}", {
  env: { SOURCE_DATABASE_NAME: "prod" },
});

console.log(result.output);
console.log(result.tokens);
console.log(result.missing);
```

## Lower-level API

```ts
import {
  resolveEnvValue,
  camelToSnake,
  findEnvTokens,
} from "@x12i/env-tokens";

resolveEnvValue("apiKey", { API_KEY: "secret" });
camelToSnake("sourceDatabaseName"); // "source_database_name"
findEnvTokens("Hello {{ENV.name}}");
```

## License

MIT

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