npm package: @jonloucks/variants-ts
Description: Node.js Typescript Configuration Library, normalize how configuration is loaded from various sources is retrieved.
Author: Jon Loucks
Latest version: 1.1.1

# @jonloucks/variants-ts

## Variants
[![CI](https://github.com/jonloucks/variants-ts/workflows/main-push/badge.svg)](https://github.com/jonloucks/variants-ts/actions)
[![npm version](https://raw.githubusercontent.com/jonloucks/variants-ts/refs/heads/badges/main-npm.svg)](https://www.npmjs.com/package/@jonloucks/variants-ts)
[![Coverage Badge](https://raw.githubusercontent.com/jonloucks/variants-ts/refs/heads/badges/main-coverage.svg)](https://jonloucks.github.io/variants-ts/lcov-report/)
[![Typedoc Badge](https://raw.githubusercontent.com/jonloucks/variants-ts/refs/heads/badges/main-typedoc.svg)](https://jonloucks.github.io/variants-ts/typedoc/)


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

## Documentation
* [Documentation](DOCUMENTATION.md)
* [License](LICENSE)
* [Contributing](CONTRIBUTING.md)
* [Code of conduct](CODE_OF_CONDUCT.md)
* [Coding standards](CODING_STANDARDS.md)
* [Security policy](SECURITY.md)
* [Pull request template](PULL_REQUEST_TEMPLATE.md)
* [TypeDoc API](https://jonloucks.github.io/variants-ts/typedoc/)
* [Test coverage report](https://jonloucks.github.io/variants-ts/lcov-report)

## Installation

```bash
npm install @jonloucks/variants-ts
```

## Usage 

<details markdown="1"><summary>Importing the Package</summary>

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

</details>

<details markdown="1"><summary>Importing the Convenience Package</summary>

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

</details>

<details markdown="1"><summary>Creating a Variant</summary>

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

<details markdown="1"><summary>Creating Sources</summary>

```typescript
const processSource = createProcessSource();
const recordSource = createRecordSource({ PORT: "8080" });
```
</details>

<details markdown="1"><summary>Using the Environment</summary>

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

const port = env.getVariance(portVariant);
```
</details>

## Development

<details markdown="1"><summary>Install dependencies</summary>

```bash
npm install
```
</details>

<details markdown="1"><summary>Build the project</summary>

```bash
npm run build
```
</details>

<details markdown="1"><summary>Run tests</summary>

```bash
npm test
```
</details>

<details markdown="1"><summary>Run tests in watch mode</summary>

```bash
npm run test:watch
```
</details>

<details markdown="1"><summary>Run test coverage</summary>

```bash
npm run test:coverage
```
</details>

<details markdown="1"><summary>Lint the code</summary>

```bash
npm run lint
```
</details>

<details markdown="1"><summary>Fix linting issues</summary>

```bash
npm run lint:fix
```
</details>

<details markdown="1"><summary>Generate documents</summary>

```bash
npm run docs
```
</details>

<details markdown="1"><summary>Project Structure</summary>

* 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
```
</details>

## GitHub Workflows

<details markdown="1"><summary>CI Workflow</summary>

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)

</details>

<details markdown="1"><summary>Publish Workflow</summary>

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](https://docs.npmjs.com/trusted-publishers))

To set up your own publishing:
1. Publishing this project as is intentionally disabled
2. You are welcome to fork this repository and publish where you want.
3. Run `npm pkg delete private` to remove the `private` flag from the package.
4. Change the `name` field in `package.json` to your desired package name.

</details>

## License

MIT