config-contract

Configuration contract enforcement for Node.js applications.

config-contract ensures that applications start only when their configuration is complete, valid, and appropriate for the current environment.

Why

Misconfigured environment variables are a common cause of runtime failures in production.

This library prevents such failures by enforcing an explicit configuration contract at startup.

Features

• Required and optional configuration
• Type validation (string, number, boolean)
• Environment-specific rules
• Optional strict mode
• Fail-fast behavior
• Returns resolved, typed configuration

Installation

npm install config-contract

Basic Usage

import { enforceContract } from "config-contract";

const config = enforceContract({
  DB_URL: { type: "string", required: true },
  PORT: { type: "number", required: true },
});

console.log(config.PORT); // number

Environment-Aware Rules

enforceContract(
  {
    DEBUG: { type: "boolean", allowedEnvs: ["development"] },
    PORT: { type: "number", requiredEnvs: ["production"] },
  },
  { env: "production" }
);

Environment resolution order

1. options.env
2. process.env.NODE_ENV
3. Defaults to "development"

Strict Mode

Enable strict mode to disallow undeclared configuration values:

enforceContract(contract, { strict: true });

This will fail if unexpected environment variables are present.

Silent Mode

Suppress console output (useful for tests or CI):

enforceContract(contract, { silent: true });

Error Handling

If validation fails, the process exits immediately with a clear, actionable error message.

This behavior is intentional and designed to prevent unsafe startup.

License

MIT