envshape

Validate environment variables and dotenv files against a compact typed schema before your application starts.

Package: @theworker02/envshape · Docs: GitHub Pages · Source: theworker02/envshape

Highlights

• Typed string, number, and bool environment schemas.
• Dotenv parsing and schema-file loading.
• Strict mode for unexpected environment variables.
• Fully documented JSR API with explicit TypeScript declarations.
• Trusted publishing from GitHub Actions with provenance.
• Zero runtime dependencies.

Add from JSR

deno add jsr:@theworker02/envshape

Then import the library API:

import { checkEnv, ENV_TYPES, PACKAGE } from "@theworker02/envshape";

const result = checkEnv(
  { PORT: "number", NAME: "string" },
  { PORT: "8080", NAME: "api" },
);

console.log(result.ok, ENV_TYPES, PACKAGE.version);

Public API

Validation

• checkEnv(schema, env, options) — validate an environment object.
• checkSchemaFile(path, env, options) — load a JSON schema and validate in one call.
• validateValue(type, value) — validate one primitive value.
• isEnvType(value) — type guard for supported schema primitive names.

Parsing and utilities

• parseDotenv(text) — parse dotenv-formatted text.
• loadDotenvFile(path) — read and parse a dotenv file.
• loadSchema(path) — read a JSON schema from disk.
• exampleFromSchema(schema) — create an empty dotenv template.
• formatHuman(result) — render terminal-friendly validation output.

Symbols and types

• PACKAGE — package identity and version metadata.
• ENV_TYPES — supported primitive names.
• TYPES — primitive validator table.
• EnvType, EnvSchema, EnvCheckResult, EnvCheckOptions, EnvError, PackageMetadata.

CLI

The repository still ships the existing Node CLI for source checkouts:

git clone https://github.com/theworker02/envshape.git
cd envshape
node src/cli.js --help

Example:

printf '{ "PORT": "number", "NAME": "string" }\n' > schema.json
PORT=8080 NAME=api node src/cli.js schema.json

Development

node --test

Publishing

Releases are published to JSR through GitHub Actions using OIDC trusted publishing. The canonical package is @theworker02/envshape.

Documentation

• JSR package and generated API docs
• Project site
• Source repository

Contributing

See CONTRIBUTING.md. Open pull requests against main.

Security

See SECURITY.md.

License

Source-available proprietary — evaluation under LICENSE; commercial / production use via COMMERCIAL.md. See LICENSE_TRANSITION_NOTICE.md and NOTICE.