@push.rocks/qenv 7.0.0 → 8.1.0

package/readme.md

@@ -10,7 +10,8 @@
 ✅ **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  
-✅ **Strict Mode** - Optional strict mode that throws errors for missing variables  
+✅ **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  
 
@@ -32,7 +33,8 @@ yarn add @push.rocks/qenv
 ```typescript
 import { Qenv } from '@push.rocks/qenv';
 
-// Create a new Qenv instance
+// 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
@@ -61,6 +63,28 @@ required:
   - 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`:
+
+```typescript
+// 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:
@@ -97,6 +121,10 @@ Qenv loads variables in this order (first found wins):
 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:
@@ -134,6 +162,9 @@ const fetchFromVault = async () => {
 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:
@@ -168,9 +199,18 @@ const dbPassword = await qenv.getEnvVarOnDemand('db_password');
 Control how your application handles missing environment variables:
 
 ```typescript
-// Fail fast (default behavior)
-const qenvStrict = new Qenv('./', './', true);
-// Application exits if required variables are missing
+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);
@@ -183,6 +223,16 @@ if (qenvRelaxed.missingEnvVars.length > 0) {
 }
 ```
 
+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:
+
+```typescript
+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:
@@ -191,15 +241,19 @@ 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);
-  process.exit(1);
+  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
@@ -276,12 +330,12 @@ qenv.logger.log('info', 'Custom log message');
 Here's how you might use qenv in a production Node.js application:
 
 ```typescript
-import { Qenv } from '@push.rocks/qenv';
+import { Qenv, QenvMissingRequiredEnvVarsError } from '@push.rocks/qenv';
 import { createServer } from './server';
 import { connectDatabase } from './database';
 
 async function bootstrap() {
-  // Initialize environment
+  // Initialize environment: throws when qenv.yml requires something no source provides
   const qenv = new Qenv();
   
   // Load critical configuration
@@ -304,7 +358,12 @@ async function bootstrap() {
 }
 
 bootstrap().catch(error => {
-  console.error('Failed to start application:', 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);
 });
 ```
@@ -318,18 +377,24 @@ bootstrap().catch(error => {
 new Qenv(
   qenvFileBasePathArg?: string,  // Path to qenv.yml (default: process.cwd())
   envFileBasePathArg?: string,   // Path to env.yml/json (default: same as qenv)
-  failOnMissing?: boolean        // Exit on missing vars (default: true)
+  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 | `Promise<string \| undefined>` |
+| `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 | `string \| undefined` |
-| `getEnvVarOnDemandAsObject(name)` | Get variable as decoded object | `Promise<any>` |
+| `getEnvVarOnDemandSync(name)` | Synchronously get variable, names only | `string \| undefined` |
+| `getEnvVarOnDemandAsObject(name)` | Get variable as decoded object | `Promise<unknown>` |
 
 #### Properties
 
@@ -338,7 +403,47 @@ new Qenv(
 | `requiredEnvVars` | `string[]` | List of required variable names |
 | `availableEnvVars` | `string[]` | List of found variable names |
 | `missingEnvVars` | `string[]` | List of missing variable names |
-| `keyValueObject` | `object` | All loaded variables as key-value pairs |
+| `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/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/qenv',
-  version: '7.0.0',
+  version: '8.1.0',
   description: 'A module for easily handling environment variables in Node.js projects with support for .yml and .json configuration.'
 }

package/ts/index.ts

@@ -1 +1,4 @@
 export * from './qenv.classes.qenv.js';
+export * from './qenv.classes.invalidqenvfileerror.js';
+export * from './qenv.classes.missingqenvfileerror.js';
+export * from './qenv.classes.missingrequiredenvvarserror.js';

package/ts/qenv.classes.invalidqenvfileerror.ts

@@ -0,0 +1,43 @@
+/** which rule of the `required:` list a qenv.yml broke */
+export type TQenvInvalidQenvFileReason = 'requiredNotAnArray' | 'requiredEntryNotAString';
+
+export interface IQenvInvalidQenvFileErrorOptions {
+  qenvFilePathAbsolute: string;
+  reason: TQenvInvalidQenvFileReason;
+  /** the type name of the offending value, never the value itself */
+  invalidValueTypeName: string;
+}
+
+const reasonDescriptions: Record<TQenvInvalidQenvFileReason, (typeNameArg: string) => string> = {
+  requiredNotAnArray: (typeNameArg) =>
+    `"required:" is of type ${typeNameArg} instead of a list of environment variable names`,
+  requiredEntryNotAString: (typeNameArg) =>
+    `"required:" contains an entry of type ${typeNameArg} instead of an environment variable name`,
+};
+
+/**
+ * Thrown when qenv.yml declares a `required:` that qenv cannot read as a list of names. Such a
+ * declaration silently enforced nothing, which is the same fail-open as a missing qenv.yml.
+ * A file without any `required:` key, and one with an empty list, legitimately require nothing
+ * and never reach this error.
+ */
+export class QenvInvalidQenvFileError extends Error {
+  public readonly code = 'QENV_INVALID_QENV_FILE';
+  public readonly qenvFilePathAbsolute: string;
+  public readonly reason: TQenvInvalidQenvFileReason;
+  public readonly invalidValueTypeName: string;
+
+  constructor(optionsArg: IQenvInvalidQenvFileErrorOptions) {
+    super(
+      `The qenv.yml at ${optionsArg.qenvFilePathAbsolute} declares an unreadable requirement: ` +
+        `${reasonDescriptions[optionsArg.reason](optionsArg.invalidValueTypeName)}. ` +
+        `Write "required:" as a list of environment variable names, or omit it to require nothing.`
+    );
+    this.name = 'QenvInvalidQenvFileError';
+    this.qenvFilePathAbsolute = optionsArg.qenvFilePathAbsolute;
+    this.reason = optionsArg.reason;
+    // only the type is carried and rendered: a malformed qenv.yml can hold a value where a name
+    // belongs, and a value may be a secret
+    this.invalidValueTypeName = optionsArg.invalidValueTypeName;
+  }
+}

package/ts/qenv.classes.missingqenvfileerror.ts

@@ -0,0 +1,28 @@
+export interface IQenvMissingQenvFileErrorOptions {
+  qenvFilePathAbsolute: string;
+  qenvDir: string;
+}
+
+/**
+ * Thrown when a Qenv that is set to fail on missing variables finds no qenv.yml at all.
+ * Without the file there is no `required:` list to enforce, so every check would pass by
+ * accident - a deployable that forgot to ship its qenv.yml would look healthy. `code` identifies
+ * the refusal even when two copies of qenv end up in one tree, which makes `instanceof` unreliable.
+ */
+export class QenvMissingQenvFileError extends Error {
+  public readonly code = 'QENV_MISSING_QENV_FILE';
+  public readonly qenvFilePathAbsolute: string;
+  public readonly qenvDir: string;
+
+  constructor(optionsArg: IQenvMissingQenvFileErrorOptions) {
+    super(
+      `qenv found no qenv.yml at ${optionsArg.qenvFilePathAbsolute}. It was constructed to fail ` +
+        `on missing required environment variables, and without qenv.yml there is no "required:" ` +
+        `list to enforce, so nothing would be checked. Ship qenv.yml with your deployable, or ` +
+        `construct Qenv with failOnMissing set to false.`
+    );
+    this.name = 'QenvMissingQenvFileError';
+    this.qenvFilePathAbsolute = optionsArg.qenvFilePathAbsolute;
+    this.qenvDir = optionsArg.qenvDir;
+  }
+}

package/ts/qenv.classes.missingrequiredenvvarserror.ts

@@ -0,0 +1,30 @@
+export interface IQenvMissingRequiredEnvVarsErrorOptions {
+  missingEnvVars: string[];
+  requiredEnvVars: string[];
+  qenvFilePathAbsolute: string;
+}
+
+/**
+ * Thrown when a variable listed under `required:` in qenv.yml is not provided by any source.
+ * The names are carried as data so a caller can report or branch on them without parsing the
+ * message, and `code` identifies the refusal even when two copies of qenv end up in one tree,
+ * which makes `instanceof` unreliable.
+ */
+export class QenvMissingRequiredEnvVarsError extends Error {
+  public readonly code = 'QENV_MISSING_REQUIRED_ENV_VARS';
+  public readonly missingEnvVars: string[];
+  public readonly requiredEnvVars: string[];
+  public readonly qenvFilePathAbsolute: string;
+
+  constructor(optionsArg: IQenvMissingRequiredEnvVarsErrorOptions) {
+    super(
+      `qenv is missing required environment variables: ${optionsArg.missingEnvVars.join(', ')}. ` +
+        `They are listed under "required:" in ${optionsArg.qenvFilePathAbsolute} and were found ` +
+        `neither in the process environment, nor in the env file, nor in the Docker secrets.`
+    );
+    this.name = 'QenvMissingRequiredEnvVarsError';
+    this.missingEnvVars = [...optionsArg.missingEnvVars];
+    this.requiredEnvVars = [...optionsArg.requiredEnvVars];
+    this.qenvFilePathAbsolute = optionsArg.qenvFilePathAbsolute;
+  }
+}