@briskforge/envcheck

Tiny environment-variable validator. Walks a schema, checks each value, coerces numeric/boolean/json kinds, throws one error per call that lists every problem.

Install

npm i @briskforge/envcheck

Usage

import envcheck from '@briskforge/envcheck';

// Server / Node — reads from process.env when no source is passed.
const env = envcheck({
  PORT: 'integer',
  NODE_ENV: 'string',
  DATABASE_URL: 'url',
  ENABLE_CACHE: 'boolean',
});

// Vite / Webpack — pass the bundler's env map.
const clientEnv = envcheck(
  {
    VITE_RPC_ETH: 'url',
    VITE_RPC_POLYGON: 'url',
    VITE_WALLETCONNECT_PROJECT_ID: 'string',
  },
  import.meta.env,
);

If a key is missing or fails its kind check, the call throws:

Error: envcheck failed:
  - PORT: not an integer
  - DATABASE_URL: missing

(err.errors carries the same list as a string array.)

API

envcheck<S>(schema: S, env?: Record<string, string | undefined>): { [K in keyof S]: unknown }

Schema entries

Each entry is either a kind or a spec object:

type Kind =
  | 'string'    // any non-empty string
  | 'url'       // must include a protocol (https://...)
  | 'number'    // any finite number
  | 'integer'   // integer only
  | 'boolean'   // accepts true|false|1|0
  | 'email'
  | 'json'      // parsed via JSON.parse

type Spec = { kind: Kind, optional?: boolean, default?: unknown }

envcheck({
  HOSTNAME: 'string',
  RETRIES: { kind: 'integer', default: 3 },
  SENTRY_DSN: { kind: 'url', optional: true },
});

Source argument

• Omit it on Node and envcheck reads process.env.
• Pass import.meta.env for Vite or process.env for Webpack-injected.
• Pass any plain object for tests.

Helpers

envcheck.KINDS       // string[] — all accepted kinds
envcheck.isURL(s)    // boolean — same check as the 'url' kind uses
envcheck.isEmail(s)  // boolean — same check as the 'email' kind uses

License

MIT.