Variants TS Documentation

@jonloucks/variants-ts

Variants

TypeScript configuration library that normalizes how values are loaded from multiple sources.

Documentation

Installation

npm install @jonloucks/variants-ts

Usage

Importing the Package

import {
  BOOTSTRAPPED,
  VERSION,
  createInstaller,
  type Installer,
  type InstallerConfig
} from '@jonloucks/variants-ts';

Importing the Convenience Package

import {
  createEnvironment,
  createProcessSource,
  createRecordSource,
  createVariant,
  CONTRACTS
} from "@jonloucks/variants-ts/auxiliary/Convenience";

Creating a Variant

const portVariant = createVariant<string>({
  name: "server.port",
  keys: ["PORT"],
  fallback: "3000"
});

Creating Sources

const processSource = createProcessSource();
const recordSource = createRecordSource({ PORT: "8080" });

Using the Environment

const env = createEnvironment({
  sources: [processSource, recordSource]
});

const port = env.getVariance(portVariant);

Development

Install dependencies

npm install

Build the project

npm run build

Run tests

npm test

Run tests in watch mode

npm run test:watch

Run test coverage

npm run test:coverage

Lint the code

npm run lint

Fix linting issues

npm run lint:fix

Generate documents

npm run docs

Project Structure

All tests must have suffix of -test.ts or -spec.ts
Tests that validate supported APIs go in src/test
Tests that validate internal implementation details go in src/impl

variants-ts
├── .github/
│   └── workflows/
│       ├── main-pull-request-matrix.yml
│       ├── main-pull-request-smoke.yml
│       ├── main-pull-request.yml
│       ├── main-push-smoke.yml
│       ├── main-push.yml
│       ├── main-release-smoke.yml
│       └── main-release.yml
├── CODE_OF_CONDUCT.md
├── CODING_STANDARDS.md
├── CONTRIBUTING.md
├── .editorconfig
├── eslint.config.mjs
├── LICENSE
├── package-lock.json
├── package.json
├── PULL_REQUEST_TEMPLATE.md
├── README.md
├── SECURITY.md
├── DOCUMENTATION.md
├── notes/
├── src/
│   ├── api/
│   ├── auxiliary/
│   ├── data/
│   ├── impl/
│   ├── test/
│   ├── index.ts
│   └── version.ts
├── tsconfig.json
└── typedoc.json

GitHub Workflows

CI Workflow

The CI workflow runs on every push and pull request to main branch. It:

Tests against Node.js versions 16.x, 18.x, 20.x, 22.x, and 24.x
Runs linting
Builds the project
Runs tests with coverage
Uploads coverage to Codecov (optional)

Publish Workflow

The publish workflow creates an official release package.

Publish is gated by main-release-smoke and runs only when the smoke matrix completes successfully.
Publishing authentication is done using (OIDC trusted publishing)

To set up your own publishing:

Publishing this project as is intentionally disabled
You are welcome to fork this repository and publish where you want.
Run npm pkg delete private to remove the private flag from the package.
Change the name field in package.json to your desired package name.

License

MIT