Standard Schema

Validate an environment value through a Standard Schema validator like zod, valibot, or arktype, and get the schema's output type back.

parse validates an environment value through any Standard Schema validator, zod, valibot, arktype, or your own, and returns the schema's output type. envapt carries no schema library of its own; it reads the ~standard interface the validator already exposes, so there is no peer dependency.

const port = .('PORT', ..().().(1024).(65535));      
const port: number

The same schema works on the @Envapt decorator through the schema option:

class  extends  {
    @('PORT', { : ..().().(1024).(65535) })
    declare static readonly : number;
}

Any conformant validator, or none

Because envapt reads the Standard Schema interface, a hand-written validator works with no dependency at all. The return type is inferred from the schema's output.

const : <string, number> = {
    '~standard': {
        : 1,
        : 'app',
        () {
            const  = ();
            if (.() &&  > 0) return { :  };
            return { : [{ : 'must be a positive integer' }] };
        }
    }
};

const port = .('PORT', );      
const port: number

Fallbacks

parse takes an optional third argument. On a missing value it returns the fallback.

const port = .('PORT', , 3000);      
const port: number

NOTE

The fallback is returned as-is on a missing value; it does not pass through the schema. Make sure the fallback already satisfies the type you expect, since the schema never sees it.

WARNING

Passing a third argument at all counts as a fallback, even when that argument is undefined. So Envapter.parse('PORT', schema, undefined) returns undefined on a missing value instead of throwing. Omit the argument entirely when you want the missing-value throw.

What throws

parse throws EnvaptError in three cases:

The value is missing and you gave no fallback: code MissingEnvValue.
The schema reports validation issues: code SchemaValidationFailed. The error carries the validator's full issues array on its .issues property.
The schema's validate itself throws: code SchemaThrew, with the original error on .cause.

A ${VAR} template is expanded before validation, so the schema sees the resolved value.

DANGER

envapt validates at config-load time and accepts synchronous schemas only. A schema whose validate returns a Promise is a type error, and throws EnvaptError with code InvalidUserDefinedConfig if you force it past the types. schema and converter are mutually exclusive, since each one already turns the raw string into a typed value.

Standard Schema

Any conformant validator, or none

Fallbacks

What throws

On this page