12factor-env 0.1.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,8 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,128 +1,233 @@
-# 12factor
+# 12factor-env
 
-Secrets meant for usage with docker-based applications.
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
 
-Uses envalid under the hood, but considers secrets for true integration of 12factor apps.
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+  <a href="https://www.npmjs.com/package/12factor-env">
+    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=packages%2F12factor-env%2Fpackage.json"/>
+  </a>
+</p>
 
-# default secret path
+> Environment variable validation with secret file support for 12-factor apps
 
-defaults to `/run/secrets/<secret_name>`
+A TypeScript library for validating environment variables with built-in support for Docker/Kubernetes secret files. Built on top of [envalid](https://github.com/af/envalid) with additional features for reading secrets from files.
 
-You must set `process.env.ENV_SECRETS_PATH` to change this, for example, 
+## Installation
 
-```js
-process.env.ENV_SECRETS_PATH='/var/run/your/secrets/folder/';
+```bash
+npm install 12factor-env
 ```
 
-or
+## Usage
 
-```sh
-ENV_SECRETS_PATH='/var/run/your/secrets/folder/' node yourapp.js
-```
-
-# Recommended Usage
+```ts
+import { env, str, num, bool, port, email, host } from '12factor-env';
 
-Using `_FILE` convention, include `SECRET_NAME_FILE` as a config var
-
-```js
-const myEnv = env(
-  process.env
+const config = env(
+  process.env,
   {
-    // put all secrets here
-    SECRET_NAME: str()
+    // Required environment variables
+    DATABASE_URL: str(),
+    API_KEY: str()
   },
   {
-    // all config vars here
-    PORT: port({ default: 10101 })
+    // Optional environment variables with defaults
+    PORT: port({ default: 3000 }),
+    DEBUG: bool({ default: false }),
+    LOG_LEVEL: str({ default: 'info' })
   }
 );
+
+console.log(config.DATABASE_URL); // Validated string
+console.log(config.PORT);         // Validated number
 ```
 
-If you haven't specified the value, you can enter it inside of a `secret()` call
+## Secret File Support
 
+This library supports reading secrets from files, which is useful for Docker secrets and Kubernetes secrets that are mounted as files.
 
-```js
-const myEnv = env(
-  process.env
-  {
-    // put all secrets here
-    SECRET_NAME: secret('secret.txt') // will look in /run/secrets/secret.txt
-  },
-  {
-    // all config vars here
-    PORT: port({ default: 10101 })
-  }
-);
+### Direct Secret Files
+
+Secrets can be read from `/run/secrets/` (or a custom path via `ENV_SECRETS_PATH`):
+
+```ts
+import { env, str } from '12factor-env';
+
+// If /run/secrets/DATABASE_PASSWORD exists, it will be read automatically
+const config = env(process.env, {
+  DATABASE_PASSWORD: str()
+});
 ```
 
-# Examples
+### _FILE Suffix Pattern
 
-## basic usage with envalid
+You can also use the `_FILE` suffix pattern commonly used with Docker:
 
-if you use the `_FILE` standard:
+```bash
+# Set the path to the secret file
+export DATABASE_PASSWORD_FILE=/run/secrets/db-password
+```
 
-```js
-  const myEnv = cleanEnv(
-  process.env,
-  {
-    PORT: port({ default: 10101 }),
-    GITHUB_TOKEN: secret(process.env.GITHUB_TOKEN_FILE)
-  });
+```ts
+import { env, str } from '12factor-env';
+
+// Will read from the file specified in DATABASE_PASSWORD_FILE
+const config = env(process.env, {
+  DATABASE_PASSWORD: str()
+});
 ```
 
-or you can specify the name of the secret file as it is stored
+### Custom Secrets Path
 
-```js
-  const myEnv = cleanEnv(
-  process.env,
-  {
-    PORT: port({ default: 10101 }),
-    GITHUB_TOKEN: secret('github_token.txt')
-  });
+Set `ENV_SECRETS_PATH` to change the default secrets directory:
+
+```bash
+export ENV_SECRETS_PATH=/custom/secrets/path
 ```
 
-Better yet, just ensure that you use the `env` shortcut and it handles it for you
+## Validators
 
-```js
-const myEnv = env(
-  {
-    GITHUB_TOKEN_FILE: process.env.GITHUB_TOKEN_FILE
-  },
-  {
-    GITHUB_TOKEN: str()
-  },
-  {
-    PORT: port({ default: 10101 })
-  }
-);
+All validators from [envalid](https://github.com/af/envalid) are re-exported:
+
+| Validator | Description |
+|-----------|-------------|
+| `str()` | String value |
+| `bool()` | Boolean (`true`, `false`, `1`, `0`) |
+| `num()` | Number |
+| `port()` | Port number (1-65535) |
+| `host()` | Hostname or IP address |
+| `url()` | Valid URL |
+| `email()` | Valid email address |
+| `json()` | JSON string (parsed) |
 
-const { GITHUB_TOKEN, PORT } = myEnv;
+### Validator Options
+
+All validators accept options:
+
+```ts
+import { str, num } from '12factor-env';
+
+const config = env(process.env, {
+  API_KEY: str({ desc: 'API key for external service' }),
+  TIMEOUT: num({ default: 5000, desc: 'Request timeout in ms' })
+});
 ```
 
+## API
+
+### `env(inputEnv, secrets, vars)`
 
-## env shortcut
+Main function to validate environment variables.
 
-Here `env()` expects 2 args, secrets and env vars.
+- `inputEnv` - The environment object (usually `process.env`)
+- `secrets` - Required environment variables
+- `vars` - Optional environment variables
 
-In this example, it will look for `/var/run/secrets/MAILGUN_KEY`, and populate the final env with everything in one object.
+### `secret(envFile)`
 
-```js
-  const myEnv = env(
-    process.env,
-    { MAILGUN_KEY: str() },
-    { PORT: port({ default: 10101 }) }
-  );
+Create a validator for a secret file:
+
+```ts
+import { env, secret } from '12factor-env';
+
+const config = env(process.env, {
+  DB_PASSWORD: secret('DATABASE_PASSWORD')
+});
+```
+
+### `getSecret(name)`
+
+Read a secret from a file:
+
+```ts
+import { getSecret } from '12factor-env';
+
+const password = getSecret('DATABASE_PASSWORD');
 ```
 
-## secret field
+### `secretPath(name)`
+
+Resolve the full path to a secret file:
 
-The `secret` object let's you specify the secret name as it is saved in the `/var/run/secrets` folder.
+```ts
+import { secretPath } from '12factor-env';
 
-```js
-  const myEnv = env(
-    process.env,
-    { MAILGUN_KEY: secret('MAILGUN_KEY') },
-    { PORT: port({ default: 10101 }) }
-  );
+const path = secretPath('DATABASE_PASSWORD');
+// Returns: /run/secrets/DATABASE_PASSWORD
 ```
 
+## Re-exports from envalid
+
+The following are re-exported from envalid for convenience:
+
+- `cleanEnv` - Low-level env cleaning function
+- `makeValidator` - Create custom validators
+- `EnvError` - Error class for validation errors
+- `EnvMissingError` - Error class for missing required vars
+- `testOnly` - Helper for test-only defaults
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,54 @@
+import { makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email } from 'envalid';
+import type { ValidatorSpec, CleanedEnv, CleanOptions } from 'envalid';
+/**
+ * Wrapper around envalid's cleanEnv that uses a throwing reporter by default
+ * This prevents process.exit from being called on validation errors
+ */
+declare const cleanEnv: <S extends Record<string, ValidatorSpec<unknown>>>(environment: Record<string, string | undefined>, specs: S, options?: CleanOptions<S>) => CleanedEnv<S>;
+/**
+ * Resolve the full path to a secret file
+ */
+declare const secretPath: (name: string) => string;
+/**
+ * Read a secret from a file
+ * @param secret - The secret file name or path
+ * @returns The secret value or undefined if not found
+ */
+declare const getSecret: (secret: string | undefined) => string | undefined;
+/**
+ * Read secrets from files based on the secret props configuration
+ * Supports both direct secret files and _FILE suffix pattern
+ */
+declare const secretEnv: <T extends Record<string, ValidatorSpec<unknown>>>(inputEnv: Record<string, string | undefined>, secretProps: T) => Record<string, string>;
+/**
+ * Create a validator for a secret file
+ * @param envFile - The environment variable name for the secret file
+ */
+declare const secret: (envFile?: string) => ValidatorSpec<string>;
+type Specs = Record<string, ValidatorSpec<unknown>>;
+/**
+ * Validate environment variables with secret file support
+ *
+ * @param inputEnv - The environment object (usually process.env)
+ * @param secrets - Required environment variables (validated with envalid)
+ * @param vars - Optional environment variables (validated with envalid)
+ * @returns Validated and cleaned environment object
+ *
+ * @example
+ * ```ts
+ * const config = env(
+ *   process.env,
+ *   {
+ *     DATABASE_URL: str(),
+ *     API_KEY: str()
+ *   },
+ *   {
+ *     PORT: port({ default: 3000 }),
+ *     DEBUG: bool({ default: false })
+ *   }
+ * );
+ * ```
+ */
+declare const env: <S extends Specs, V extends Specs>(inputEnv: Record<string, string | undefined>, secrets?: S, vars?: V) => CleanedEnv<S & V>;
+export { env, secretEnv, secret, getSecret, secretPath, cleanEnv, makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email };
+export type { ValidatorSpec, CleanedEnv };

package/esm/index.js

@@ -0,0 +1,112 @@
+import { cleanEnv as envalidCleanEnv, makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email } from 'envalid';
+import { readFileSync } from 'fs';
+import { resolve, join } from 'path';
+/**
+ * Custom reporter that throws an error instead of calling process.exit
+ * This allows errors to be caught and handled properly in tests and applications
+ */
+const throwingReporter = ({ errors }) => {
+    const errorKeys = Object.keys(errors);
+    if (errorKeys.length > 0) {
+        const missingVars = errorKeys.map((key) => `${String(key)}: ${errors[key]?.message ?? 'unknown error'}`);
+        throw new EnvError(`Missing or invalid environment variables:\n  ${missingVars.join('\n  ')}`);
+    }
+};
+/**
+ * Wrapper around envalid's cleanEnv that uses a throwing reporter by default
+ * This prevents process.exit from being called on validation errors
+ */
+const cleanEnv = (environment, specs, options) => {
+    return envalidCleanEnv(environment, specs, {
+        reporter: throwingReporter,
+        ...options
+    });
+};
+/**
+ * Default path for secret files (Docker/Kubernetes secrets)
+ */
+const ENV_SECRETS_PATH = process.env.ENV_SECRETS_PATH ?? '/run/secrets/';
+/**
+ * Resolve the full path to a secret file
+ */
+const secretPath = (name) => name.startsWith('/') ? name : resolve(join(ENV_SECRETS_PATH, name));
+/**
+ * Read a secret from a file
+ * @param secret - The secret file name or path
+ * @returns The secret value or undefined if not found
+ */
+const getSecret = (secret) => {
+    if (!secret)
+        return undefined;
+    try {
+        const value = readFileSync(secretPath(secret), 'utf-8');
+        return value.trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Read secrets from files based on the secret props configuration
+ * Supports both direct secret files and _FILE suffix pattern
+ */
+const secretEnv = (inputEnv, secretProps) => {
+    return Object.keys(secretProps).reduce((m, k) => {
+        // Try to read secret directly from file
+        const secret = getSecret(k);
+        if (secret) {
+            m[k] = secret;
+        }
+        else {
+            // Try _FILE suffix pattern (e.g., DATABASE_PASSWORD_FILE)
+            const secretFileKey = `${k}_FILE`;
+            if (Object.prototype.hasOwnProperty.call(inputEnv, secretFileKey)) {
+                const secretFileValue = getSecret(inputEnv[secretFileKey]);
+                if (secretFileValue) {
+                    m[k] = secretFileValue;
+                }
+            }
+        }
+        return m;
+    }, {});
+};
+/**
+ * Create a validator for a secret file
+ * @param envFile - The environment variable name for the secret file
+ */
+const secret = (envFile) => str({ default: getSecret(envFile) });
+/**
+ * Validate environment variables with secret file support
+ *
+ * @param inputEnv - The environment object (usually process.env)
+ * @param secrets - Required environment variables (validated with envalid)
+ * @param vars - Optional environment variables (validated with envalid)
+ * @returns Validated and cleaned environment object
+ *
+ * @example
+ * ```ts
+ * const config = env(
+ *   process.env,
+ *   {
+ *     DATABASE_URL: str(),
+ *     API_KEY: str()
+ *   },
+ *   {
+ *     PORT: port({ default: 3000 }),
+ *     DEBUG: bool({ default: false })
+ *   }
+ * );
+ * ```
+ */
+const env = (inputEnv, secrets = {}, vars = {}) => {
+    // First pass: validate optional vars
+    const varEnv = cleanEnv(inputEnv, vars);
+    // Read secrets from files
+    const _secrets = secretEnv(varEnv, secrets);
+    // Second pass: validate secrets with file values merged in
+    const mergedEnv = { ...varEnv, ..._secrets };
+    return cleanEnv(mergedEnv, secrets);
+};
+export { env, secretEnv, secret, getSecret, secretPath, 
+// Re-export from envalid
+cleanEnv, makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email };

package/index.d.ts

@@ -0,0 +1,54 @@
+import { makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email } from 'envalid';
+import type { ValidatorSpec, CleanedEnv, CleanOptions } from 'envalid';
+/**
+ * Wrapper around envalid's cleanEnv that uses a throwing reporter by default
+ * This prevents process.exit from being called on validation errors
+ */
+declare const cleanEnv: <S extends Record<string, ValidatorSpec<unknown>>>(environment: Record<string, string | undefined>, specs: S, options?: CleanOptions<S>) => CleanedEnv<S>;
+/**
+ * Resolve the full path to a secret file
+ */
+declare const secretPath: (name: string) => string;
+/**
+ * Read a secret from a file
+ * @param secret - The secret file name or path
+ * @returns The secret value or undefined if not found
+ */
+declare const getSecret: (secret: string | undefined) => string | undefined;
+/**
+ * Read secrets from files based on the secret props configuration
+ * Supports both direct secret files and _FILE suffix pattern
+ */
+declare const secretEnv: <T extends Record<string, ValidatorSpec<unknown>>>(inputEnv: Record<string, string | undefined>, secretProps: T) => Record<string, string>;
+/**
+ * Create a validator for a secret file
+ * @param envFile - The environment variable name for the secret file
+ */
+declare const secret: (envFile?: string) => ValidatorSpec<string>;
+type Specs = Record<string, ValidatorSpec<unknown>>;
+/**
+ * Validate environment variables with secret file support
+ *
+ * @param inputEnv - The environment object (usually process.env)
+ * @param secrets - Required environment variables (validated with envalid)
+ * @param vars - Optional environment variables (validated with envalid)
+ * @returns Validated and cleaned environment object
+ *
+ * @example
+ * ```ts
+ * const config = env(
+ *   process.env,
+ *   {
+ *     DATABASE_URL: str(),
+ *     API_KEY: str()
+ *   },
+ *   {
+ *     PORT: port({ default: 3000 }),
+ *     DEBUG: bool({ default: false })
+ *   }
+ * );
+ * ```
+ */
+declare const env: <S extends Specs, V extends Specs>(inputEnv: Record<string, string | undefined>, secrets?: S, vars?: V) => CleanedEnv<S & V>;
+export { env, secretEnv, secret, getSecret, secretPath, cleanEnv, makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email };
+export type { ValidatorSpec, CleanedEnv };

package/index.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.email = exports.url = exports.port = exports.host = exports.json = exports.str = exports.num = exports.bool = exports.testOnly = exports.EnvMissingError = exports.EnvError = exports.makeValidator = exports.cleanEnv = exports.secretPath = exports.getSecret = exports.secret = exports.secretEnv = exports.env = void 0;
+const envalid_1 = require("envalid");
+Object.defineProperty(exports, "makeValidator", { enumerable: true, get: function () { return envalid_1.makeValidator; } });
+Object.defineProperty(exports, "EnvError", { enumerable: true, get: function () { return envalid_1.EnvError; } });
+Object.defineProperty(exports, "EnvMissingError", { enumerable: true, get: function () { return envalid_1.EnvMissingError; } });
+Object.defineProperty(exports, "testOnly", { enumerable: true, get: function () { return envalid_1.testOnly; } });
+Object.defineProperty(exports, "bool", { enumerable: true, get: function () { return envalid_1.bool; } });
+Object.defineProperty(exports, "num", { enumerable: true, get: function () { return envalid_1.num; } });
+Object.defineProperty(exports, "str", { enumerable: true, get: function () { return envalid_1.str; } });
+Object.defineProperty(exports, "json", { enumerable: true, get: function () { return envalid_1.json; } });
+Object.defineProperty(exports, "host", { enumerable: true, get: function () { return envalid_1.host; } });
+Object.defineProperty(exports, "port", { enumerable: true, get: function () { return envalid_1.port; } });
+Object.defineProperty(exports, "url", { enumerable: true, get: function () { return envalid_1.url; } });
+Object.defineProperty(exports, "email", { enumerable: true, get: function () { return envalid_1.email; } });
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Custom reporter that throws an error instead of calling process.exit
+ * This allows errors to be caught and handled properly in tests and applications
+ */
+const throwingReporter = ({ errors }) => {
+    const errorKeys = Object.keys(errors);
+    if (errorKeys.length > 0) {
+        const missingVars = errorKeys.map((key) => `${String(key)}: ${errors[key]?.message ?? 'unknown error'}`);
+        throw new envalid_1.EnvError(`Missing or invalid environment variables:\n  ${missingVars.join('\n  ')}`);
+    }
+};
+/**
+ * Wrapper around envalid's cleanEnv that uses a throwing reporter by default
+ * This prevents process.exit from being called on validation errors
+ */
+const cleanEnv = (environment, specs, options) => {
+    return (0, envalid_1.cleanEnv)(environment, specs, {
+        reporter: throwingReporter,
+        ...options
+    });
+};
+exports.cleanEnv = cleanEnv;
+/**
+ * Default path for secret files (Docker/Kubernetes secrets)
+ */
+const ENV_SECRETS_PATH = process.env.ENV_SECRETS_PATH ?? '/run/secrets/';
+/**
+ * Resolve the full path to a secret file
+ */
+const secretPath = (name) => name.startsWith('/') ? name : (0, path_1.resolve)((0, path_1.join)(ENV_SECRETS_PATH, name));
+exports.secretPath = secretPath;
+/**
+ * Read a secret from a file
+ * @param secret - The secret file name or path
+ * @returns The secret value or undefined if not found
+ */
+const getSecret = (secret) => {
+    if (!secret)
+        return undefined;
+    try {
+        const value = (0, fs_1.readFileSync)(secretPath(secret), 'utf-8');
+        return value.trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.getSecret = getSecret;
+/**
+ * Read secrets from files based on the secret props configuration
+ * Supports both direct secret files and _FILE suffix pattern
+ */
+const secretEnv = (inputEnv, secretProps) => {
+    return Object.keys(secretProps).reduce((m, k) => {
+        // Try to read secret directly from file
+        const secret = getSecret(k);
+        if (secret) {
+            m[k] = secret;
+        }
+        else {
+            // Try _FILE suffix pattern (e.g., DATABASE_PASSWORD_FILE)
+            const secretFileKey = `${k}_FILE`;
+            if (Object.prototype.hasOwnProperty.call(inputEnv, secretFileKey)) {
+                const secretFileValue = getSecret(inputEnv[secretFileKey]);
+                if (secretFileValue) {
+                    m[k] = secretFileValue;
+                }
+            }
+        }
+        return m;
+    }, {});
+};
+exports.secretEnv = secretEnv;
+/**
+ * Create a validator for a secret file
+ * @param envFile - The environment variable name for the secret file
+ */
+const secret = (envFile) => (0, envalid_1.str)({ default: getSecret(envFile) });
+exports.secret = secret;
+/**
+ * Validate environment variables with secret file support
+ *
+ * @param inputEnv - The environment object (usually process.env)
+ * @param secrets - Required environment variables (validated with envalid)
+ * @param vars - Optional environment variables (validated with envalid)
+ * @returns Validated and cleaned environment object
+ *
+ * @example
+ * ```ts
+ * const config = env(
+ *   process.env,
+ *   {
+ *     DATABASE_URL: str(),
+ *     API_KEY: str()
+ *   },
+ *   {
+ *     PORT: port({ default: 3000 }),
+ *     DEBUG: bool({ default: false })
+ *   }
+ * );
+ * ```
+ */
+const env = (inputEnv, secrets = {}, vars = {}) => {
+    // First pass: validate optional vars
+    const varEnv = cleanEnv(inputEnv, vars);
+    // Read secrets from files
+    const _secrets = secretEnv(varEnv, secrets);
+    // Second pass: validate secrets with file values merged in
+    const mergedEnv = { ...varEnv, ..._secrets };
+    return cleanEnv(mergedEnv, secrets);
+};
+exports.env = env;

package/package.json

@@ -1,67 +1,50 @@
 {
   "name": "12factor-env",
-  "version": "0.1.0",
-  "description": "12factor env vars and secrets",
-  "author": "Dan Lynch <pyramation@gmail.com>",
-  "homepage": "https://github.com/pyramation/12factor-env#readme",
-  "license": "SEE LICENSE IN LICENSE",
-  "main": "main/index.js",
-  "module": "module/index.js",
-  "directories": {
-    "lib": "src",
-    "test": "__tests__"
-  },
-  "files": [
-    "main",
-    "module"
-  ],
-  "scripts": {
-    "build:main": "cross-env BABEL_ENV=production babel src --out-dir main --delete-dir-on-start",
-    "build:module": "cross-env MODULE=true babel src --out-dir module --delete-dir-on-start",
-    "build": "npm run build:module && npm run build:main",
-    "prepublish": "npm run build",
-    "dev": "cross-env NODE_ENV=development babel-node src/index",
-    "watch": "cross-env NODE_ENV=development babel-watch src/index",
-    "lint": "eslint src --fix",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:debug": "node --inspect node_modules/.bin/jest --runInBand"
-  },
+  "version": "1.0.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Environment variable validation with secret file support for 12-factor apps",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "directory": "dist"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pyramation/12factor-env"
+    "url": "https://github.com/constructive-io/constructive"
   },
-  "keywords": [],
   "bugs": {
-    "url": "https://github.com/pyramation/12factor-env/issues"
+    "url": "https://github.com/constructive-io/constructive/issues"
   },
-  "devDependencies": {
-    "@babel/cli": "7.11.6",
-    "@babel/core": "7.11.6",
-    "@babel/node": "^7.10.5",
-    "@babel/plugin-proposal-class-properties": "7.10.4",
-    "@babel/plugin-proposal-export-default-from": "7.10.4",
-    "@babel/plugin-proposal-object-rest-spread": "7.11.0",
-    "@babel/plugin-transform-runtime": "7.11.5",
-    "@babel/preset-env": "7.11.5",
-    "babel-core": "7.0.0-bridge.0",
-    "babel-eslint": "10.1.0",
-    "babel-jest": "25.1.0",
-    "babel-watch": "^7.0.0",
-    "cross-env": "^7.0.2",
-    "eslint": "6.8.0",
-    "eslint-config-prettier": "^6.10.0",
-    "eslint-plugin-prettier": "^3.1.2",
-    "jest": "^24.5.0",
-    "jest-in-case": "^1.0.2",
-    "prettier": "^2.1.2",
-    "regenerator-runtime": "^0.13.7"
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@babel/runtime": "^7.11.2",
-    "envalid": "^6.0.2"
-  }
+    "envalid": "^8.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "makage": "^0.1.10",
+    "ts-node": "^10.9.2"
+  },
+  "keywords": [
+    "environment",
+    "env",
+    "validation",
+    "12factor",
+    "secrets",
+    "kubernetes",
+    "docker",
+    "constructive"
+  ],
+  "gitHead": "390f4dd57fc158554518ec454bf2a4856d550552"
 }

package/main/index.js

@@ -1,163 +0,0 @@
-"use strict";
-
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "cleanEnv", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.cleanEnv;
-  }
-});
-Object.defineProperty(exports, "makeValidator", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.makeValidator;
-  }
-});
-Object.defineProperty(exports, "EnvError", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.EnvError;
-  }
-});
-Object.defineProperty(exports, "EnvMissingError", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.EnvMissingError;
-  }
-});
-Object.defineProperty(exports, "testOnly", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.testOnly;
-  }
-});
-Object.defineProperty(exports, "bool", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.bool;
-  }
-});
-Object.defineProperty(exports, "num", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.num;
-  }
-});
-Object.defineProperty(exports, "str", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.str;
-  }
-});
-Object.defineProperty(exports, "json", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.json;
-  }
-});
-Object.defineProperty(exports, "host", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.host;
-  }
-});
-Object.defineProperty(exports, "port", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.port;
-  }
-});
-Object.defineProperty(exports, "url", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.url;
-  }
-});
-Object.defineProperty(exports, "email", {
-  enumerable: true,
-  get: function get() {
-    return _envalid.email;
-  }
-});
-exports.secret = exports.secretEnv = exports.env = void 0;
-
-var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
-
-var _envalid = require("envalid");
-
-var _fs = require("fs");
-
-var _path = require("path");
-
-function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); keys.push.apply(keys, symbols); } return keys; }
-
-function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { (0, _defineProperty2["default"])(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
-
-var ENV_SECRETS_PATH = process.env.ENV_SECRETS_PATH ? process.env.ENV_SECRETS_PATH : '/run/secrets/';
-
-var secretPath = function secretPath(name) {
-  return name.startsWith('/') ? name : (0, _path.resolve)((0, _path.join)(ENV_SECRETS_PATH, name));
-};
-
-var getSecret = function getSecret(secret) {
-  if (!secret) return;
-
-  try {
-    var value = (0, _fs.readFileSync)(secretPath(secret), 'utf-8');
-    return value;
-  } catch (e) {
-    return;
-  }
-};
-
-var secretEnv = function secretEnv(env, secretProps) {
-  return Object.keys(secretProps).reduce(function (m, k) {
-    var secret = getSecret(k);
-
-    if (secret) {
-      m[k] = secret;
-    } else {
-      var secretFileKey = k + '_FILE';
-
-      if (env.hasOwnProperty(secretFileKey)) {
-        var secretFileValue = getSecret(env[secretFileKey]);
-
-        if (secretFileValue) {
-          m[k] = secretFileValue;
-        }
-      }
-    }
-
-    return m;
-  }, {});
-};
-
-exports.secretEnv = secretEnv;
-
-var secret = function secret(ENV_FILE) {
-  return (0, _envalid.str)({
-    "default": getSecret(ENV_FILE)
-  });
-};
-
-exports.secret = secret;
-
-var env = function env(inputEnv) {
-  var secrets = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-  var vars = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-  var varEnv = (0, _envalid.cleanEnv)(inputEnv, _objectSpread({}, vars), {
-    dotEnvPath: null
-  });
-
-  var _secrets = secretEnv(varEnv, secrets);
-
-  return (0, _envalid.cleanEnv)(_objectSpread(_objectSpread({}, varEnv), _secrets), _objectSpread({}, secrets), {
-    dotEnvPath: null
-  });
-};
-
-exports.env = env;

package/module/index.js

@@ -1,65 +0,0 @@
-import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
-
-function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); keys.push.apply(keys, symbols); } return keys; }
-
-function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
-
-import { cleanEnv, makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email } from 'envalid';
-import { readFileSync } from 'fs';
-import { resolve, join } from 'path';
-const ENV_SECRETS_PATH = process.env.ENV_SECRETS_PATH ? process.env.ENV_SECRETS_PATH : '/run/secrets/';
-
-const secretPath = name => name.startsWith('/') ? name : resolve(join(ENV_SECRETS_PATH, name));
-
-const getSecret = secret => {
-  if (!secret) return;
-
-  try {
-    const value = readFileSync(secretPath(secret), 'utf-8');
-    return value;
-  } catch (e) {
-    return;
-  }
-};
-
-const secretEnv = (env, secretProps) => {
-  return Object.keys(secretProps).reduce((m, k) => {
-    const secret = getSecret(k);
-
-    if (secret) {
-      m[k] = secret;
-    } else {
-      const secretFileKey = k + '_FILE';
-
-      if (env.hasOwnProperty(secretFileKey)) {
-        const secretFileValue = getSecret(env[secretFileKey]);
-
-        if (secretFileValue) {
-          m[k] = secretFileValue;
-        }
-      }
-    }
-
-    return m;
-  }, {});
-};
-
-const secret = ENV_FILE => str({
-  default: getSecret(ENV_FILE)
-});
-
-const env = (inputEnv, secrets = {}, vars = {}) => {
-  const varEnv = cleanEnv(inputEnv, _objectSpread({}, vars), {
-    dotEnvPath: null
-  });
-
-  const _secrets = secretEnv(varEnv, secrets);
-
-  return cleanEnv(_objectSpread(_objectSpread({}, varEnv), _secrets), _objectSpread({}, secrets), {
-    dotEnvPath: null
-  });
-};
-
-export { env, secretEnv, secret
-/* envalid */
-, cleanEnv, makeValidator, EnvError, EnvMissingError, testOnly, bool, num, str, json, host, port, url, email };