truthenv 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lino Brendler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# truthenv
+
+Tiny zero-dependency helper for safely reading boolean environment flags.
+
+```js
+import envFlag from 'truthenv';
+
+if (envFlag('FEATURE_AI_SEARCH')) {
+  console.log('enabled');
+}
+```
+
+Why? Because this common JavaScript pattern is buggy:
+
+```js
+if (process.env.FEATURE_AI_SEARCH) {
+  // This also runs when FEATURE_AI_SEARCH="false"
+}
+```
+
+`truthenv` understands the values developers actually write in `.env`, CI and hosting dashboards:
+
+| true | false |
+| --- | --- |
+| `true` | `false` |
+| `1` | `0` |
+| `yes` | `no` |
+| `on` | `off` |
+| `enabled` | `disabled` |
+| `active` | `inactive` |
+| `ok` | `nope` |
+
+## Install
+
+```bash
+npm install truthenv
+```
+
+## Usage
+
+```js
+import { envFlag, toFlag } from 'truthenv';
+
+const debug = envFlag('DEBUG');
+const billingEnabled = envFlag('BILLING_ENABLED', { default: true });
+const strictFeature = envFlag('FEATURE_X', { strict: true });
+
+console.log(toFlag('off')); // false
+console.log(toFlag('YES')); // true
+```
+
+CommonJS also works:
+
+```js
+const envFlag = require('truthenv');
+
+if (envFlag('DEBUG')) {
+  console.log('debug mode');
+}
+```
+
+## API
+
+### `envFlag(name, options?)`
+
+Reads a value from `process.env` and returns a real boolean.
+
+Options:
+
+- `default`: value returned when the env var is missing or unknown. Default: `false`.
+- `strict`: when `true`, unknown values throw a `TypeError`.
+- `env`: custom env object for tests, edge runtimes or non-Node environments.
+
+### `toFlag(value, fallback?)`
+
+Converts a raw value to a boolean without reading `process.env`.
+
+## License
+
+MIT

package/index.cjs

@@ -0,0 +1,42 @@
+'use strict';
+
+const TRUE_VALUES = new Set(['1', 'true', 't', 'yes', 'y', 'on', 'enabled', 'enable', 'active', 'ok']);
+const FALSE_VALUES = new Set(['0', 'false', 'f', 'no', 'n', 'off', 'disabled', 'disable', 'inactive', 'nope', '']);
+
+function toFlag(value, fallback = false) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (Number.isNaN(value)) return fallback;
+    return value !== 0;
+  }
+
+  const normalized = String(value).trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+
+  return fallback;
+}
+
+function envFlag(name, options = {}) {
+  const env = options.env ?? (typeof process !== 'undefined' ? process.env : {});
+  const fallback = options.default ?? false;
+  const value = env?.[name];
+
+  if (options.strict && value !== undefined && value !== null) {
+    const normalized = String(value).trim().toLowerCase();
+    if (!TRUE_VALUES.has(normalized) && !FALSE_VALUES.has(normalized)) {
+      throw new TypeError(
+        `Invalid boolean env flag ${name}=${JSON.stringify(value)}. ` +
+          'Use true/false, 1/0, yes/no, on/off, or enabled/disabled.'
+      );
+    }
+  }
+
+  return toFlag(value, fallback);
+}
+
+module.exports = envFlag;
+module.exports.envFlag = envFlag;
+module.exports.toFlag = toFlag;
+module.exports.default = envFlag;

package/index.d.ts

@@ -0,0 +1,12 @@
+export type EnvFlagOptions = {
+  /** Custom env object. Defaults to process.env when available. */
+  env?: Record<string, string | boolean | number | null | undefined>;
+  /** Returned when the variable is missing or unrecognized. Defaults to false. */
+  default?: boolean;
+  /** Throw on unrecognized values instead of returning the default. */
+  strict?: boolean;
+};
+
+export function toFlag(value: unknown, fallback?: boolean): boolean;
+export function envFlag(name: string, options?: EnvFlagOptions): boolean;
+export default envFlag;

package/index.js

@@ -0,0 +1,37 @@
+const TRUE_VALUES = new Set(['1', 'true', 't', 'yes', 'y', 'on', 'enabled', 'enable', 'active', 'ok']);
+const FALSE_VALUES = new Set(['0', 'false', 'f', 'no', 'n', 'off', 'disabled', 'disable', 'inactive', 'nope', '']);
+
+export function toFlag(value, fallback = false) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (Number.isNaN(value)) return fallback;
+    return value !== 0;
+  }
+
+  const normalized = String(value).trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+
+  return fallback;
+}
+
+export function envFlag(name, options = {}) {
+  const env = options.env ?? (typeof process !== 'undefined' ? process.env : {});
+  const fallback = options.default ?? false;
+  const value = env?.[name];
+
+  if (options.strict && value !== undefined && value !== null) {
+    const normalized = String(value).trim().toLowerCase();
+    if (!TRUE_VALUES.has(normalized) && !FALSE_VALUES.has(normalized)) {
+      throw new TypeError(
+        `Invalid boolean env flag ${name}=${JSON.stringify(value)}. ` +
+          'Use true/false, 1/0, yes/no, on/off, or enabled/disabled.'
+      );
+    }
+  }
+
+  return toFlag(value, fallback);
+}
+
+export default envFlag;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "truthenv",
+  "version": "1.0.0",
+  "description": "Tiny zero-dependency helper for safely reading boolean environment flags.",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "index.js",
+    "index.cjs",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "env",
+    "environment",
+    "boolean",
+    "flag",
+    "dotenv",
+    "config",
+    "zero-dependency"
+  ],
+  "author": "Lino Brendler",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  }
+}