@push.rocks/qenv 🔐

Smart Environment Variable Management for Node.js

Never hardcode secrets again. Load environment variables from multiple sources with ease and confidence.

🚀 Features

✅ Multi-source Loading - Automatically loads from environment variables, config files, 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
✅ 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):

1. Process environment variables - Already set in process.env
2. Configuration files - From env.yml or env.json
3. Docker secrets - From /run/secrets/
4. Docker secret JSON - From /run/secrets/secret.json

All four 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');

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 the constructor never throws: a missing qenv.yml is accepted and an unreadable required: is logged as a warning.

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 |

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.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.