scenv-zod

library0.4.0jsnpmunverified

scenv-zod is a utility library that integrates the Zod schema validation library with scenv, a package for managing environment variables and configuration. It provides a `parser` function that allows developers to define robust validation and coercion rules for their configuration variables using Zod schemas. This ensures type safety and data integrity when reading values from environment variables, CLI arguments, or default settings within scenv. Currently at version 0.4.0, it's a relatively new and actively developed package, primarily focused on enhancing `scenv`'s parsing capabilities. It differentiates itself by leveraging Zod's powerful schema definition language for parsing, offering granular control over data types, transformations (e.g., string to number/boolean), and comprehensive error handling. This makes it a strong choice for applications requiring strict and predictable configuration validation, reducing runtime errors caused by malformed environment variables. Its concise API simplifies complex validation logic, promoting cleaner and more maintainable configuration codebases.

serialization http-networking

npm install scenv-zod

github ↗package ↗

INSTALL

IMPORT

SIG · SCENV-ZOD

scenv-zod

serializationjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser

✓ import { parser } from 'scenv-zod';

✗ const { parser } = require('scenv-zod');

The primary named export from scenv-zod for creating scenv-compatible Zod parsers.

scenv

✓ import { scenv } from 'scenv';

✗ const scenv = require('scenv');

scenv is a peer dependency and must be imported separately for variable definition.

✓ import { z } from 'zod';

✗ const z = require('zod');

Zod is a peer dependency and its schema builder 'z' must be imported separately to define validation schemas.

Demonstrates defining environment variables with Zod validation, coercing strings to numbers and booleans, and handling potential errors during parsing using `scenv` and `scenv-zod`.

import { scenv } from "scenv"; import { parser } from "scenv-zod"; import { z } from "zod"; const port = scenv("Port", { key: "port", env: "PORT", default: 3000, parser: parser(z.coerce.number().min(1).max(65535)) }); const debug = scenv("Debug", { key: "debug", env: "DEBUG", default: false, parser: parser( z.union([z.boolean(), z.literal("true"), z.literal("false")]) .transform((v) => v === true || v === "true") ) }); // Simulate environment variables for demonstration process.env.PORT = process.env.PORT ?? '8080'; process.env.DEBUG = process.env.DEBUG ?? 'true'; async function runConfig() { try { const portNum = await port.get(); // number const isDebug = await debug.get(); // boolean console.log(`Application Port: ${portNum} (Type: ${typeof portNum})`); console.log(`Debug Mode: ${isDebug} (Type: ${typeof isDebug})`); } catch (error) { if (error instanceof z.ZodError) { console.error('Validation failed:', error.errors); } else { console.error('An unexpected error occurred:', error); } } } runConfig();

Debug

Known issues

gotchaEnvironment variables, CLI arguments, and context values are always read as strings by `scenv`. Direct Zod schema validation for non-string types (e.g., `z.number()`, `z.boolean()`) will fail unless proper coercion is applied.

fix

Always use Zod's `z.coerce.<type>()` methods (e.g., `z.coerce.number()`, `z.coerce.boolean()`) or explicit `.transform()` to convert string inputs to the desired type within your schema.

affects: >=0.1.0

gotchaThe `.get()` method from `scenv` (when using a scenv-zod parser) will throw a `ZodError` if validation fails. This can lead to unhandled promise rejections if not caught.

fix

Use a `try...catch` block around `await variable.get()` to handle validation failures, or prefer `await variable.safeGet()` which returns a `{ success: boolean, data?, error? }` object, allowing for explicit error checking without exceptions.

affects: >=0.1.0

breakingMajor version updates of `zod` itself may introduce breaking changes to schema definition or validation behavior that could impact existing `scenv-zod` parsers.

fix

Regularly review the `zod` migration guide when upgrading its major version. Thoroughly test all configuration variable parsers after any `zod` or `scenv-zod` update.

affects: >=0.1.0

Errors

Common errors & fixes

ZodError: Invalid input

The value retrieved for a configuration variable (from env, CLI, or default) does not conform to the defined Zod schema.

fix

Inspect the `error.errors` array in the `ZodError` for specific validation issues. Ensure string inputs are correctly coerced (e.g., `z.coerce.number()`) and that all rules (e.g., `min`, `max`, `email`) are met by the provided value.

Error: Cannot find module 'scenv' or 'zod'

The peer dependencies `scenv` or `zod` are not installed in the project, or they are not resolvable.

fix

Install the required peer dependencies using your package manager: `npm install scenv zod` or `pnpm add scenv zod`.

TypeError: Cannot read properties of undefined (reading 'get')

The `scenv` function or variable definition was not correctly executed or imported, resulting in an undefined variable object when `.get()` is called.

fix

Verify that `import { scenv } from 'scenv';` is present and that the `scenv()` function is called with valid arguments, returning a variable object before `.get()` is invoked.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

scenvrequiredCore dependency for defining and managing environment variables.

zodrequiredCore dependency for schema definition, validation, and parsing.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/PKWadsy/scenv ↗

packagehttps://www.npmjs.com/package/scenv-zod ↗