env-health 0.1.0

package/README.md

@@ -0,0 +1,309 @@
+# env-health
+
+Tiny runtime validator for `process.env` with great error messages and comprehensive utilities.
+
+## Features
+
+- ✅ **Type-safe** - Full TypeScript support with inference
+- ✅ **Great error messages** - Clear, actionable error messages with example `.env` files
+- ✅ **Multiple type parsers** - Supports `string`, `int`, `float`, `bool`, `url`, `json`, and `enum`
+- ✅ **Comprehensive utilities** - Helper functions for common env var operations
+- ✅ **Zero dependencies** - Lightweight and fast
+- ✅ **Flexible** - Works with any environment object, not just `process.env`
+
+## Install
+
+```bash
+npm i env-health
+```
+
+## Quick Start
+
+```ts
+import { envHealth } from "env-health";
+
+const env = envHealth({
+  PORT: "int",
+  DEBUG: "bool",
+  NODE_ENV: ["dev", "prod", "test"] as const,
+  DATABASE_URL: "url",
+});
+
+console.log(env.PORT); // number: 3000
+console.log(env.DEBUG); // boolean: true
+console.log(env.NODE_ENV); // "dev" | "prod" | "test"
+```
+
+## API Reference
+
+### `envHealth(schema, options?)`
+
+The main validation function. Validates and parses environment variables according to a schema.
+
+#### Schema Types
+
+**Primitive Types:**
+
+- `"string"` - String value (default)
+- `"int"` - Integer number
+- `"float"` - Floating point number
+- `"bool"` - Boolean (accepts: `true/false`, `1/0`, `yes/no`, `y/n`, `on/off`)
+- `"url"` - Valid URL string
+- `"json"` - Valid JSON (parsed to `unknown`)
+
+**Enum Types:**
+
+- Array of strings: `["dev", "prod"] as const`
+- Object with `type: "enum"` and `values` array
+
+**Detailed Spec:**
+
+```ts
+{
+  type: "int" | "float" | "bool" | "string" | "url" | "json",
+  optional?: true,
+  default?: string | number | boolean,
+  example?: string
+}
+```
+
+#### Examples
+
+```ts
+import { envHealth } from "env-health";
+
+// Simple types
+const env = envHealth({
+  PORT: "int",
+  DEBUG: "bool",
+  API_URL: "url",
+});
+
+// With defaults
+const env = envHealth({
+  PORT: { type: "int", default: 3000 },
+  TIMEOUT: { type: "int", default: 5000 },
+});
+
+// Optional variables
+const env = envHealth({
+  REQUIRED: "string",
+  OPTIONAL: { type: "string", optional: true },
+});
+
+// Enums
+const env = envHealth({
+  NODE_ENV: ["dev", "prod", "test"] as const,
+  LOG_LEVEL: {
+    type: "enum",
+    values: ["debug", "info", "warn", "error"],
+    default: "info",
+  },
+});
+
+// Custom environment object
+const env = envHealth(
+  {
+    PORT: "int",
+    DEBUG: "bool",
+  },
+  { env: { PORT: "3000", DEBUG: "true" } },
+);
+```
+
+#### Error Messages
+
+When validation fails, `envHealth` throws an `EnvHealthError` with:
+
+- List of missing required variables
+- List of invalid variables with expected vs received values
+- Example `.env` file showing the correct format
+
+```ts
+import { envHealth, EnvHealthError } from "env-health";
+
+try {
+  const env = envHealth({
+    DATABASE_URL: "url",
+    PORT: "int",
+  });
+} catch (err) {
+  if (err instanceof EnvHealthError) {
+    console.error(err.message);
+    // Environment validation failed:
+    //
+    // Missing required variables:
+    //   - DATABASE_URL (expected: url)
+    //
+    // Example .env:
+    // ------------
+    // DATABASE_URL=postgres://user:pass@localhost:5432/db
+    // PORT=3000
+  }
+}
+```
+
+### `requireEnv(key, env?)`
+
+Require an environment variable. Throws if missing.
+
+```ts
+import { requireEnv } from "env-health";
+
+const apiKey = requireEnv("API_KEY");
+// Throws if API_KEY is missing or empty
+```
+
+### `getEnv(key, options?)`
+
+Get an environment variable with optional default and type conversion.
+
+```ts
+import { getEnv } from "env-health";
+
+// String (default)
+const apiKey = getEnv("API_KEY", { default: "default-key" });
+
+// Integer
+const port = getEnv("PORT", { type: "int", default: 3000 });
+
+// Float
+const ratio = getEnv("RATIO", { type: "float", default: 0.5 });
+
+// Boolean
+const debug = getEnv("DEBUG", { type: "bool", default: false });
+
+// Custom environment
+const value = getEnv("KEY", { env: customEnv, default: "fallback" });
+```
+
+### `envExists(keys, env?)`
+
+Check if one or more environment variables exist.
+
+```ts
+import { envExists } from "env-health";
+
+// Single key
+if (envExists("API_KEY")) {
+  // API_KEY exists
+}
+
+// Multiple keys (all must exist)
+if (envExists(["DB_HOST", "DB_PORT", "DB_NAME"])) {
+  // All database vars exist
+}
+
+// Custom environment
+if (envExists("KEY", customEnv)) {
+  // ...
+}
+```
+
+### `envPrefix(prefix, options?)`
+
+Get all environment variables with a specific prefix.
+
+```ts
+import { envPrefix } from "env-health";
+
+// Get all DB_* vars
+const dbVars = envPrefix("DB_");
+// { DB_HOST: "localhost", DB_PORT: "5432", DB_NAME: "mydb" }
+
+// Strip prefix from keys
+const dbConfig = envPrefix("DB_", { stripPrefix: true });
+// { HOST: "localhost", PORT: "5432", NAME: "mydb" }
+
+// Custom environment
+const vars = envPrefix("PREFIX_", { env: customEnv });
+```
+
+### `mergeEnv(...sources)`
+
+Merge multiple environment sources. Later sources override earlier ones.
+
+```ts
+import { mergeEnv } from "env-health";
+
+const merged = mergeEnv(
+  { PORT: "3000" }, // defaults
+  process.env, // system env
+  { DEBUG: "true" }, // overrides
+);
+```
+
+### `envToObject(keys, options?)`
+
+Convert environment variables to a typed object, optionally with prefix handling.
+
+```ts
+import { envToObject } from "env-health";
+
+// Basic usage
+const config = envToObject(["HOST", "PORT", "NAME"], {
+  env: {
+    HOST: "localhost",
+    PORT: "5432",
+    NAME: "mydb",
+  },
+});
+// { HOST: "localhost", PORT: "5432", NAME: "mydb" }
+
+// With prefix
+const dbConfig = envToObject(["HOST", "PORT"], {
+  prefix: "DB_",
+  env: {
+    DB_HOST: "localhost",
+    DB_PORT: "5432",
+  },
+});
+// { HOST: "localhost", PORT: "5432" }
+
+// With required keys
+const config = envToObject(["HOST", "PORT"], {
+  prefix: "DB_",
+  required: ["HOST", "PORT"],
+  env: { DB_HOST: "localhost" },
+});
+// Throws: Missing required environment variable: DB_PORT
+```
+
+### `loadEnvFile(content)`
+
+Load and parse a `.env` file content string.
+
+```ts
+import { loadEnvFile } from "env-health";
+import { readFileSync } from "fs";
+
+const content = readFileSync(".env", "utf-8");
+const env = loadEnvFile(content);
+
+// Supports:
+// - KEY=value
+// - Comments (#)
+// - Quoted values ("value" or 'value')
+// - Empty lines
+```
+
+## TypeScript
+
+Full TypeScript support with type inference:
+
+```ts
+import { envHealth } from "env-health";
+
+const env = envHealth({
+  PORT: "int",
+  DEBUG: "bool",
+  NODE_ENV: ["dev", "prod"] as const,
+});
+
+// Type: { PORT: number; DEBUG: boolean; NODE_ENV: "dev" | "prod" }
+type EnvType = typeof env;
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,397 @@
+'use strict';
+
+// src/error.ts
+var EnvHealthError = class extends Error {
+  issues;
+  exampleEnv;
+  constructor(message, issues, exampleEnv) {
+    super(message);
+    this.name = "EnvHealthError";
+    this.issues = issues;
+    this.exampleEnv = exampleEnv;
+  }
+};
+
+// src/parse.ts
+var URL_RE = /^https?:\/\/.+/i;
+function parseIntStrict(raw) {
+  if (!/^-?\d+$/.test(raw.trim())) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+function parseFloatStrict(raw) {
+  const s = raw.trim();
+  if (s.length === 0) return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+function parseBoolStrict(raw) {
+  const v = raw.trim().toLowerCase();
+  if (["true", "1", "yes", "y", "on"].includes(v)) return true;
+  if (["false", "0", "no", "n", "off"].includes(v)) return false;
+  return null;
+}
+function parseUrlStrict(raw) {
+  const s = raw.trim();
+  if (!URL_RE.test(s)) return null;
+  try {
+    new URL(s);
+    return s;
+  } catch {
+    return null;
+  }
+}
+function parseJsonStrict(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// src/utils.ts
+function requireEnv(key, env = process.env) {
+  const value = env[key];
+  if (value == null || value === "") {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+  return value;
+}
+function getEnv(key, options) {
+  const env = options?.env ?? process.env;
+  const raw = env[key];
+  const defaultValue = options?.default;
+  if (raw == null || raw === "") {
+    if (defaultValue !== void 0) {
+      return defaultValue;
+    }
+    throw new Error(`Missing environment variable: ${key}`);
+  }
+  const type = options?.type ?? "string";
+  if (type === "string") {
+    return raw;
+  }
+  if (type === "int") {
+    const parsed = parseIntStrict(raw);
+    if (parsed === null) {
+      throw new Error(
+        `Invalid integer value for ${key}: "${raw}". Use a valid integer.`
+      );
+    }
+    return parsed;
+  }
+  if (type === "float") {
+    const parsed = parseFloatStrict(raw);
+    if (parsed === null) {
+      throw new Error(
+        `Invalid float value for ${key}: "${raw}". Use a valid number.`
+      );
+    }
+    return parsed;
+  }
+  if (type === "bool") {
+    const parsed = parseBoolStrict(raw);
+    if (parsed === null) {
+      throw new Error(
+        `Invalid boolean value for ${key}: "${raw}". Use true/false, 1/0, yes/no, y/n, or on/off.`
+      );
+    }
+    return parsed;
+  }
+  return raw;
+}
+function envExists(keys, env = process.env) {
+  const keysArray = Array.isArray(keys) ? keys : [keys];
+  return keysArray.every((key) => {
+    const value = env[key];
+    return value != null && value !== "";
+  });
+}
+function envPrefix(prefix, options) {
+  const env = options?.env ?? process.env;
+  const result = {};
+  const stripPrefix = options?.stripPrefix ?? false;
+  for (const [key, value] of Object.entries(env)) {
+    if (value != null && typeof value === "string" && key.startsWith(prefix) && value !== "") {
+      const newKey = stripPrefix ? key.slice(prefix.length) : key;
+      result[newKey] = value;
+    }
+  }
+  return result;
+}
+function mergeEnv(...sources) {
+  const result = {};
+  for (const source of sources) {
+    if (source) {
+      Object.assign(result, source);
+    }
+  }
+  return result;
+}
+function envToObject(keys, options) {
+  const env = options?.env ?? process.env;
+  const prefix = options?.prefix ?? "";
+  const stripPrefix = options?.stripPrefix ?? false;
+  const required = new Set(options?.required ?? []);
+  const result = {};
+  for (const key of keys) {
+    const envKey = prefix + key;
+    const value = env[envKey];
+    if (value == null || value === "") {
+      if (required.has(key)) {
+        throw new Error(`Missing required environment variable: ${envKey}`);
+      }
+      continue;
+    }
+    const resultKey = stripPrefix ? key : envKey;
+    result[resultKey] = value;
+  }
+  return result;
+}
+function loadEnvFile(content) {
+  const result = {};
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const equalIndex = trimmed.indexOf("=");
+    if (equalIndex === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, equalIndex).trim();
+    let value = trimmed.slice(equalIndex + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (!key) {
+      continue;
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+// src/index.ts
+function isArraySpec(spec) {
+  return Array.isArray(spec);
+}
+function isStringSpec(spec) {
+  return typeof spec === "string";
+}
+function isEnumDetailedSpec(spec) {
+  return spec.type === "enum";
+}
+function isPrimitiveDetailedSpec(spec) {
+  return spec.type !== "enum";
+}
+function expectedLabel(spec) {
+  if (isArraySpec(spec)) {
+    return `one of (${spec.join(", ")})`;
+  }
+  if (isStringSpec(spec)) {
+    return spec;
+  }
+  if (isEnumDetailedSpec(spec)) {
+    return `one of (${spec.values.join(", ")})`;
+  }
+  if (isPrimitiveDetailedSpec(spec)) {
+    return spec.type;
+  }
+  return "unknown";
+}
+function normalizeSpec(spec) {
+  if (isArraySpec(spec)) {
+    return { kind: "enum", values: spec, optional: false };
+  }
+  if (isStringSpec(spec)) {
+    return { kind: "primitive", type: spec, optional: false };
+  }
+  if (isEnumDetailedSpec(spec)) {
+    return {
+      kind: "enum",
+      values: spec.values,
+      optional: spec.optional === true,
+      defaultValue: spec.default,
+      example: spec.example ?? void 0
+    };
+  }
+  if (isPrimitiveDetailedSpec(spec)) {
+    return {
+      kind: "primitive",
+      type: spec.type,
+      optional: spec.optional === true,
+      defaultValue: spec.default,
+      example: spec.example ?? void 0
+    };
+  }
+  return { kind: "primitive", type: "string", optional: false };
+}
+var EXAMPLE_CACHE = /* @__PURE__ */ new Map();
+function suggestExample(key, spec) {
+  const cacheKey = `${key}:${JSON.stringify(spec)}`;
+  const cached = EXAMPLE_CACHE.get(cacheKey);
+  if (cached) return cached;
+  const n = normalizeSpec(spec);
+  let example;
+  if (n.example) {
+    example = n.example;
+  } else if (n.kind === "enum" && n.values && n.values.length > 0) {
+    example = String(n.values[0]);
+  } else {
+    const upperKey = key.toUpperCase();
+    switch (n.type) {
+      case "int":
+        example = "3000";
+        break;
+      case "float":
+        example = "0.5";
+        break;
+      case "bool":
+        example = "true";
+        break;
+      case "url":
+        example = upperKey.includes("DATABASE") && upperKey.includes("URL") ? "postgres://user:pass@localhost:5432/db" : "https://example.com";
+        break;
+      case "json":
+        example = '{"key":"value"}';
+        break;
+      default:
+        example = "your_value_here";
+    }
+  }
+  EXAMPLE_CACHE.set(cacheKey, example);
+  return example;
+}
+function parseByType(type, raw) {
+  switch (type) {
+    case "string":
+      return { ok: true, value: raw };
+    case "int": {
+      const n = parseIntStrict(raw);
+      return n === null ? { ok: false } : { ok: true, value: n };
+    }
+    case "float": {
+      const n = parseFloatStrict(raw);
+      return n === null ? { ok: false } : { ok: true, value: n };
+    }
+    case "bool": {
+      const b = parseBoolStrict(raw);
+      return b === null ? { ok: false } : { ok: true, value: b };
+    }
+    case "url": {
+      const u = parseUrlStrict(raw);
+      return u === null ? { ok: false } : { ok: true, value: u };
+    }
+    case "json": {
+      const j = parseJsonStrict(raw);
+      return j === null ? { ok: false } : { ok: true, value: j };
+    }
+  }
+}
+function buildExampleEnv(schema, opts) {
+  const lines = [];
+  for (const [key, spec] of Object.entries(schema)) {
+    const n = normalizeSpec(spec);
+    const example = opts.blankExampleValues ? "" : suggestExample(key, spec);
+    const optionalSuffix = n.optional ? "  # optional" : "";
+    lines.push(`${key}=${example}${optionalSuffix}`.trimEnd());
+  }
+  return lines.join("\n");
+}
+function envHealth(schema, options = {}) {
+  const env = options.env ?? process.env;
+  const issues = [];
+  const out = {};
+  for (const [key, spec] of Object.entries(schema)) {
+    const n = normalizeSpec(spec);
+    const expected = expectedLabel(spec);
+    const raw = env[key];
+    if (raw == null || raw === "") {
+      if (n.defaultValue !== void 0) {
+        out[key] = n.defaultValue;
+        continue;
+      }
+      if (n.optional) {
+        out[key] = void 0;
+        continue;
+      }
+      issues.push({ kind: "missing", key, expected });
+      continue;
+    }
+    if (n.kind === "enum") {
+      const values = n.values;
+      if (values && values.includes(raw)) {
+        out[key] = raw;
+      } else {
+        issues.push({ kind: "invalid", key, expected, received: raw });
+      }
+      continue;
+    }
+    const type = n.type ?? "string";
+    const parsed = parseByType(type, raw);
+    if (parsed.ok) {
+      out[key] = parsed.value;
+    } else {
+      issues.push({ kind: "invalid", key, expected, received: raw });
+    }
+  }
+  if (issues.length > 0) {
+    const exampleEnv = buildExampleEnv(schema, options);
+    const header = options.header ? `${options.header}
+` : "";
+    const lines = [
+      header ? `${header}Environment validation failed:
+` : "Environment validation failed:\n"
+    ];
+    const missing = [];
+    const invalid = [];
+    for (let i = 0; i < issues.length; i++) {
+      const issue = issues[i];
+      if (!issue) continue;
+      if (issue.kind === "missing") {
+        missing.push(issue);
+      } else {
+        invalid.push(issue);
+      }
+    }
+    if (missing.length > 0) {
+      lines.push("Missing required variables:");
+      for (let i = 0; i < missing.length; i++) {
+        const m = missing[i];
+        if (m) {
+          lines.push(`  - ${m.key} (expected: ${m.expected})`);
+        }
+      }
+      lines.push("");
+    }
+    if (invalid.length > 0) {
+      lines.push("Invalid variables:");
+      for (let i = 0; i < invalid.length; i++) {
+        const v = invalid[i];
+        if (v) {
+          lines.push(`  - ${v.key}="${v.received}" (expected: ${v.expected})`);
+        }
+      }
+      lines.push("");
+    }
+    lines.push("Example .env:");
+    lines.push("------------");
+    lines.push(exampleEnv);
+    throw new EnvHealthError(lines.join("\n"), issues, exampleEnv);
+  }
+  return out;
+}
+
+exports.EnvHealthError = EnvHealthError;
+exports.envExists = envExists;
+exports.envHealth = envHealth;
+exports.envPrefix = envPrefix;
+exports.envToObject = envToObject;
+exports.getEnv = getEnv;
+exports.loadEnvFile = loadEnvFile;
+exports.mergeEnv = mergeEnv;
+exports.requireEnv = requireEnv;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map