@x12i/env-tokens

@x12i/env-tokens

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

Install

npm install @x12i/env-tokens

Usage

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:

{{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

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

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

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

License

MIT