✅ Multi-source Loading - Automatically loads from environment variables, config files, systemd credentials, and Docker secrets
✅ Type-Safe - Full TypeScript support with comprehensive type definitions
✅ Flexible Formats - Supports .yml, .yaml, and .json configuration files
✅ Docker Ready - Built-in support for Docker secrets and secret.json files
✅ systemd Ready - Reads LoadCredential= / LoadCredentialEncrypted= credentials from $CREDENTIALS_DIRECTORY
✅ Async & Sync - Both synchronous and asynchronous variable retrieval
✅ Enforced Requirements - required: in qenv.yml is checked while constructing, with a typed error
✅ Strict Mode - Optional strict getter that throws for a missing variable
✅ Base64 Objects - Handle complex configuration objects with automatic encoding/decoding
✅ Dynamic Resolution - Support for async functions as environment variable sources

📦 Installation

# Using npm
npm install @push.rocks/qenv --save

# Using pnpm (recommended)
pnpm add @push.rocks/qenv

# Using yarn
yarn add @push.rocks/qenv

🎯 Quick Start

import { Qenv } from '@push.rocks/qenv';

// Create a new Qenv instance. Every name listed under `required:` in qenv.yml is resolved right
// here, and a missing one throws a QenvMissingRequiredEnvVarsError.
const qenv = new Qenv('./', './', true);

// Access environment variables
const dbHost = await qenv.getEnvVarOnDemand('DB_HOST');
const apiKey = await qenv.getEnvVarOnDemand('API_KEY');

// Use strict mode to ensure variables exist
const criticalVar = await qenv.getEnvVarOnDemandStrict('CRITICAL_CONFIG');
// Throws error if CRITICAL_CONFIG is not set!

📖 Configuration

Setting Up Your Environment Files

1. Define Required Variables (`qenv.yml`)

Create a qenv.yml file to specify which environment variables your application needs:

required:
  - DB_HOST
  - DB_USER
  - DB_PASSWORD
  - API_KEY
  - LOG_LEVEL

Every listed name is resolved while the Qenv instance is constructed. What is found lands in availableEnvVars and, as a string, in keyValueObject; what is missing lands in missingEnvVars and, unless you pass failOnMissing: false, makes the constructor throw.

With failOnMissing left at its default true, the qenv.yml itself is part of what is enforced: if there is none at the given path, the constructor throws QenvMissingQenvFileError and names the path it looked at. Without the file there is no required: list, so every check would pass by accident - a container image that forgot to ship its qenv.yml would look healthy while enforcing nothing. Ship qenv.yml with your deployable, next to the code that reads it. A qenv.yml whose required: cannot be read as a list of names - a scalar instead of a list, or an entry that is not a name - is refused the same way, with QenvInvalidQenvFileError.

A qenv.yml that requires nothing is legitimate and constructs: write required: [], or leave the required: key out altogether. Only the file's absence and an unreadable list are refused.

The CLI or library case that reads from wherever it happens to run passes failOnMissing: false:

// no qenv.yml expected here - resolve what is there, enforce nothing
const qenv = new Qenv(process.cwd(), undefined, false);

2. Provide Values (`env.yml` or `env.json`)

For local development, create an env.yml or env.json file:

env.yml:

DB_HOST: localhost
DB_USER: developer
DB_PASSWORD: supersecret123
API_KEY: dev-key-12345
LOG_LEVEL: debug

env.json:

{
  "DB_HOST": "localhost",
  "DB_USER": "developer", 
  "DB_PASSWORD": "supersecret123",
  "API_KEY": "dev-key-12345",
  "LOG_LEVEL": "debug"
}

💡 Pro Tip: Add env.yml and env.json to your .gitignore to keep secrets out of version control!

🔥 Advanced Usage

Loading Priority

Qenv loads variables in this order (first found wins):

Process environment variables - Already set in process.env
Configuration files - From env.yml or env.json
systemd credentials - From $CREDENTIALS_DIRECTORY/<NAME>, only when systemd set CREDENTIALS_DIRECTORY
Docker secrets - From /run/secrets/
Docker secret JSON - From /run/secrets/secret.json

systemd credentials rank directly above the Docker secrets: both are per-name files handed over by the process's supervisor, but CREDENTIALS_DIRECTORY is set for this very process by its unit, while /run/secrets is a fixed path that may exist for unrelated reasons. A service runs under one of the two, so in practice they never compete.

All five sources are synchronous, so getEnvVarOnDemand and getEnvVarOnDemandSync resolve a name identically. A required: entry is always a name; an async resolver function is a per-call source and never takes part in the requirement check.

Handling Complex Objects

Store and retrieve complex configuration objects:

# In env.yml
DATABASE_CONFIG:
  database:
    host: localhost
    port: 5432
    options:
      ssl: true
      poolSize: 10

// Qenv automatically handles base64 encoding
const dbConfig = await qenv.getEnvVarOnDemandAsObject('DATABASE_CONFIG');
console.log(dbConfig.database.options.poolSize); // 10

Dynamic Environment Variables

Load variables from external sources dynamically:

const qenv = new Qenv();

// Define an async function to fetch configuration
const fetchFromVault = async () => {
  const response = await fetch('https://vault.example.com/api/secret');
  const data = await response.json();
  return data.secret;
};

// Use the function as an environment variable source
const secret = await qenv.getEnvVarOnDemand(fetchFromVault);

The function form of TEnvVarRef is honoured by getEnvVarOnDemand and getEnvVarOnDemandStrict only. getEnvVarOnDemandSync cannot await, so it accepts names and takes no resolver function.

Working with Docker

Qenv seamlessly integrates with Docker secrets:

# docker-compose.yml
version: '3.7'
services:
  app:
    image: your-app
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    external: true
  api_key:
    external: true

Your application automatically reads from /run/secrets/:

const qenv = new Qenv();
// Automatically loads from /run/secrets/db_password
const dbPassword = await qenv.getEnvVarOnDemand('db_password');

Secret files are read under guards:

Name mapping - the file name is the variable name. A name that cannot be a single file name (empty, . or .., containing /, the platform path separator or NUL, longer than 255 bytes) never reaches /run/secrets, so a variable name can never read a file outside it.
Content - returned exactly as stored; a trailing newline is part of the value.
Absent - a missing /run/secrets, or no file for the name, continues to secret.json and then to "not set".
Links - a symbolic link is followed only when its fully resolved target lies inside the resolved secrets directory, which is the layout of a Kubernetes secret volume (NAME -> ..data/NAME, ..data -> ..<timestamp>). A link that resolves outside the directory, dangles or loops is refused.
Refusals - a secret file, or a file whose name contains secret.json, that is not a regular file, larger than 1 MiB, unreadable or an unhonoured link throws QenvDockerSecretError, and so do a /run/secrets that cannot be listed and a secret.json that does not parse. The limit is systemd's credential limit, which holds every Docker swarm secret (Docker caps those at 500 KiB). The error carries names, paths, the reason and the errno code, never the secret or a parser message quoting it.

Working with systemd

A process run as a systemd unit receives its secrets as credentials: never in the environment (so child processes do not inherit them) and never in systemctl show. Name the credential exactly like the variable:

[Service]
# plain file from /etc/credstore/API_KEY (systemd >= 250 searches the credstore without a path)
LoadCredential=API_KEY
# or sealed with `systemd-creds encrypt`, from /etc/credstore.encrypted/DB_PASSWORD
LoadCredentialEncrypted=DB_PASSWORD

const qenv = new Qenv();
// reads $CREDENTIALS_DIRECTORY/API_KEY
const apiKey = await qenv.getEnvVarOnDemand('API_KEY');

How the source behaves:

Name mapping - the file name is the variable name, unchanged. A name systemd cannot use as a credential ID (empty, . or .., containing / or :, non-printable or non-ASCII characters, longer than 255 characters) never reaches this source.
Content - returned exactly as stored, like a Docker secret. A trailing newline is part of the value, so write the file with printf '%s' rather than echo.
Absent credential - a directory without a file for the name is not an error; the name continues to the Docker secrets.
Refusals - once CREDENTIALS_DIRECTORY is set, a name that reaches this source throws QenvCredentialError instead of falling through when the variable is not an absolute, normalized path, the directory is missing, not a directory or not searchable, or the credential is a symbolic link, not a regular file, larger than systemd's 1 MiB credential limit, or unreadable. The error carries the name, the directory, the reason and the errno code, never the credential's content. It is thrown by the getters and by the constructor regardless of failOnMissing, because it reports a broken deployment, not a missing variable. A name answered by the process environment or the env file never touches the directory.

Handling Missing Variables

Control how your application handles missing environment variables:

import { Qenv, QenvMissingRequiredEnvVarsError } from '@push.rocks/qenv';

// Fail fast (default behaviour): the constructor throws
try {
  const qenvStrict = new Qenv('./', './', true);
} catch (error) {
  if (error instanceof QenvMissingRequiredEnvVarsError) {
    console.error('Missing variables:', error.missingEnvVars);
    console.error('Declared in:', error.qenvFilePathAbsolute);
  }
  throw error;
}

// Graceful handling
const qenvRelaxed = new Qenv('./', './', false);
// Application continues, you handle missing variables

// Check what's missing
if (qenvRelaxed.missingEnvVars.length > 0) {
  console.warn('Missing variables:', qenvRelaxed.missingEnvVars);
  // Implement fallback logic
}

qenv never ends the process: the caller decides what an incomplete environment means. Where two copies of qenv can end up in one dependency tree, instanceof is unreliable - match on the code instead:

if (error instanceof Error && 'code' in error && error.code === 'QENV_MISSING_REQUIRED_ENV_VARS') {
  // handle the incomplete environment
}

Strict Mode for Critical Variables

Use the new strict getter when you absolutely need a variable:

try {
  // This will throw if TOKEN is not set
  const token = await qenv.getEnvVarOnDemandStrict('TOKEN');

  // You can also check multiple fallback names
  const db = await qenv.getEnvVarOnDemandStrict(['DATABASE_URL', 'DB_CONNECTION']);
} catch (error) {
  // the message names every reference that could not be resolved
  console.error('Critical configuration missing:', error.message);
  throw error;
}

A name that qenv.yml already lists under required: is resolved at construction time, so the strict getter is for variables you look up on demand.

🏗️ CI/CD Integration

GitHub Actions

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy with secrets
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
        run: |
          npm install
          npm run deploy

GitLab CI

deploy:
  stage: deploy
  script:
    - npm install
    - npm run deploy
  variables:
    API_KEY: $CI_API_KEY
    DB_PASSWORD: $CI_DB_PASSWORD

🎭 Testing

For testing, create a separate test/assets/env.yml:

import { Qenv } from '@push.rocks/qenv';

describe('MyApp', () => {
  let qenv: Qenv;
  
  beforeEach(() => {
    qenv = new Qenv('./test/assets', './test/assets', false);
  });
  
  it('should load test configuration', async () => {
    const testVar = await qenv.getEnvVarOnDemand('TEST_VAR');
    expect(testVar).toBe('test-value');
  });
});

🔍 Debugging

Enable detailed logging to troubleshoot environment variable loading:

const qenv = new Qenv();

// Check what's loaded
console.log('Required vars:', qenv.requiredEnvVars);
console.log('Available vars:', qenv.availableEnvVars);
console.log('Missing vars:', qenv.missingEnvVars);

// Access the logger
qenv.logger.log('info', 'Custom log message');

📊 Real-World Example

Here's how you might use qenv in a production Node.js application:

import { Qenv, QenvMissingRequiredEnvVarsError } from '@push.rocks/qenv';
import { createServer } from './server';
import { connectDatabase } from './database';

async function bootstrap() {
  // Initialize environment: throws when qenv.yml requires something no source provides
  const qenv = new Qenv();
  
  // Load critical configuration
  const config = {
    port: await qenv.getEnvVarOnDemand('PORT') || '3000',
    dbUrl: await qenv.getEnvVarOnDemandStrict('DATABASE_URL'),
    apiKey: await qenv.getEnvVarOnDemandStrict('API_KEY'),
    logLevel: await qenv.getEnvVarOnDemand('LOG_LEVEL') || 'info',
    features: await qenv.getEnvVarOnDemandAsObject('FEATURE_FLAGS')
  };
  
  // Connect to database
  await connectDatabase(config.dbUrl);
  
  // Start server
  const server = createServer(config);
  server.listen(config.port, () => {
    console.log(`🚀 Server running on port ${config.port}`);
  });
}

bootstrap().catch(error => {
  if (error instanceof QenvMissingRequiredEnvVarsError) {
    console.error('Incomplete environment, missing:', error.missingEnvVars.join(', '));
  } else {
    console.error('Failed to start application:', error);
  }
  // exiting is the application's decision - qenv itself never calls process.exit
  process.exit(1);
});

🤝 API Reference

Class: `Qenv`

Constructor

new Qenv(
  qenvFileBasePathArg?: string,  // Path to qenv.yml (default: process.cwd())
  envFileBasePathArg?: string,   // Path to env.yml/json (default: same as qenv)
  failOnMissing?: boolean        // Throw on missing required vars (default: true)
)

With failOnMissing true the constructor throws QenvMissingQenvFileError when there is no qenv.yml at qenvFileBasePathArg, QenvInvalidQenvFileError when its required: cannot be read as a list of names, and QenvMissingRequiredEnvVarsError when a name listed under required: is not provided by any source. With failOnMissing false a missing qenv.yml is accepted and an unreadable required: is logged as a warning. QenvCredentialError and QenvDockerSecretError are thrown either way, by the constructor and by the getters, when a name reaches a systemd credential or a Docker secret, or their directory, that exists but cannot be honoured.

Methods

Method	Description	Returns
`getEnvVarOnDemand(name)`	Get environment variable value, resolver functions included	`Promise<string \| undefined>`
`getEnvVarOnDemandStrict(name)`	Get variable or throw error	`Promise<string>`
`getEnvVarOnDemandSync(name)`	Synchronously get variable, names only	`string \| undefined`
`getEnvVarOnDemandAsObject(name)`	Get variable as decoded object	`Promise<unknown>`

Properties

Property	Type	Description
`requiredEnvVars`	`string[]`	List of required variable names
`availableEnvVars`	`string[]`	List of found variable names
`missingEnvVars`	`string[]`	List of missing variable names
`keyValueObject`	`Record<string, string>`	Every available required variable as a resolved string
`qenvFilePathAbsolute`	`string`	Absolute path of the qenv.yml in use
`envFilePathAbsolute`	`string \| undefined`	Absolute path of the env file in use

Class: `QenvMissingRequiredEnvVarsError`

Thrown by the constructor when failOnMissing is true and a required variable has no source.

Member	Type	Description
`code`	`'QENV_MISSING_REQUIRED_ENV_VARS'`	Stable identifier, safe across duplicate installs
`missingEnvVars`	`string[]`	The required names no source provided
`requiredEnvVars`	`string[]`	Every name listed under `required:`
`qenvFilePathAbsolute`	`string`	The qenv.yml that declared them

Class: `QenvMissingQenvFileError`

Thrown by the constructor when failOnMissing is true and there is no qenv.yml to read the required: list from.

Member	Type	Description
`code`	`'QENV_MISSING_QENV_FILE'`	Stable identifier, safe across duplicate installs
`qenvFilePathAbsolute`	`string`	The qenv.yml path that was looked at
`qenvDir`	`string`	The resolved directory that should hold it

Class: `QenvInvalidQenvFileError`

Thrown by the constructor when failOnMissing is true and required: is not a list of names; logged as a warning with the same message when failOnMissing is false.

Member	Type	Description
`code`	`'QENV_INVALID_QENV_FILE'`	Stable identifier, safe across duplicate installs
`reason`	`'requiredNotAnArray' \| 'requiredEntryNotAString'`	Which rule the file broke
`invalidValueTypeName`	`string`	The type of the offending value, never the value itself
`qenvFilePathAbsolute`	`string`	The qenv.yml that declared it

Class: `QenvCredentialError`

Thrown by the constructor and the getters when a name reaches the systemd credentials source while CREDENTIALS_DIRECTORY is set and the directory, or the credential for that name, cannot be honoured.

Member	Type	Description
`code`	`'QENV_CREDENTIAL'`	Stable identifier, safe across duplicate installs
`reason`	`TQenvCredentialErrorReason`	`'directoryPathInvalid' \| 'directoryMissing' \| 'directoryNotADirectory' \| 'directoryUnreadable' \| 'credentialNotARegularFile' \| 'credentialTooLarge' \| 'credentialUnreadable'`
`credentialsDirectoryPath`	`string`	The value of `CREDENTIALS_DIRECTORY`
`envVarName`	`string`	The name being resolved
`systemErrorCode`	`string \| undefined`	The errno code of the failed system call, where one failed

Class: `QenvDockerSecretError`

Thrown by the constructor and the getters when a name reaches the Docker secrets and the secret file, a secret.json, or the secrets directory exists but cannot be honoured.

Member	Type	Description
`code`	`'QENV_DOCKER_SECRET'`	Stable identifier, safe across duplicate installs
`reason`	`TQenvDockerSecretErrorReason`	`'directoryUnreadable' \| 'secretNotARegularFile' \| 'secretLinkOutsideDirectory' \| 'secretLinkUnresolvable' \| 'secretTooLarge' \| 'secretUnreadable' \| 'secretJsonInvalid'`
`secretsDirectoryPath`	`string`	The secrets directory, `/run/secrets` in production
`secretFileName`	`string \| undefined`	The refused file, absent for a directory refusal
`envVarName`	`string`	The name being resolved
`systemErrorCode`	`string \| undefined`	The errno code of the failed system call, where one failed

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

@push.rocks/qenv 🔐

🚀 Features