Validating with a schema

A converter that can't convert returns undefined, with no reason attached. A rule like "an integer from 1 to 100" became an if inside your function, so a DATABASE_POOL_SIZE outside the range returned the fallback without saying which rule failed. A schema carries the rule itself. Pass one to getAs to have envapt validate the value, return the schema's output type, and throw with the schema's own issues if the value fails. An issue is one { message, path } entry, and envapt starts every path with the env key. getRequired, getRequiredAll, and the decorator's schema option take a schema too.

Zod, valibot, arktype, and others implement Standard Schema, a shared interface under the key ~standard. envapt reads that interface and imports none of them, so the validator is the only package you install. If a token like Converters.Port already covers the rule, you don't need a schema.

const poolSize = Envapter.getAs('DATABASE_POOL_SIZE', z.coerce.number().int().min(1).max(100));
        
const poolSize: number | undefined

poolSize is number | undefined because an unset DATABASE_POOL_SIZE returns undefined. A fallback as the third argument removes that case. Your schema receives the value as a string, so each one turns it into a number (z.coerce.number(), v.transform(Number), string.integer.parse).

The schema must be synchronousCopy Anchor Link

Every reader returns its value directly, and a decorated field is a getter. Neither can wait on a Promise. If a schema's validate returns only a Promise, TypeScript rejects the call. If you bypass the type check, the read throws InvalidUserDefinedConfig (302). The cost is that a check needing I/O, like asking a database whether a tenant id exists, can't run in the schema. Run that check in your own code once config has loaded.

const tenantRule = {
    '~standard': {
        version: 1 as const,
        vendor: 'app',
        validate: async (value: unknown) => ({ value: String(value) })
    }
};

const tenantId = Envapter.getAs('TENANT_ID', tenantRule);
No overload matches this call.
  The last overload gave the following error.
    Argument of type '{ '~standard': { version: 1; vendor: string; validate: (value: unknown) => Promise<{ value: string; }>; }; }' is not assignable to parameter of type 'ConverterFunction<unknown>'.
      Type '{ '~standard': { version: 1; vendor: string; validate: (value: unknown) => Promise<{ value: string; }>; }; }' is not assignable to type '(raw: string) => unknown'.
        Type '{ '~standard': { version: 1; vendor: string; validate: (value: unknown) => Promise<{ value: string; }>; }; }' provides no match for the signature '(raw: string): unknown'.

tenantRule's validate is async, so it returns a Promise. The last line fails to compile.

Zod types validate as returning a result or a Promise of a result, so that type passes the check and the failure is the 302 when the read runs. An async refine throws 302. A .transform that throws does too, because zod returns a rejected Promise for the throw. The 302 doesn't carry your original error. Set Envapter.debug = 'warn' to log the error the schema threw.

Fallbacks skip the schemaCopy Anchor Link

A missing or empty value returns the fallback, or undefined without one. The schema runs only on a value that is set, so the fallback never goes through it. A default on the schema, like zod's .default(), never applies either. TypeScript checks the fallback's type against the schema's output, but nothing checks the value at runtime. A token's fallback is different, because envapt checks it against the token.

const poolSize = Envapter.getAs('DATABASE_POOL_SIZE', z.coerce.number().int().min(1).max(100), 500);
        
const poolSize: number

500 is above the schema's max(100), yet an unset DATABASE_POOL_SIZE returns it, so write a fallback that already passes. If a value is set and fails the schema, the read throws SchemaValidationFailed (208), even when you pass a fallback.

What throwsCopy Anchor Link

A 208 message lists only the key, because an issue message can quote the value. Valibot's message reads Received "abc", and arktype's ends in (was "abc"). A 209 message includes the text of the error your schema threw, which can quote the value too. Required values shows how to log a failure without the values.

A ${VAR} template expands before validation, so the schema receives the expanded value.

To require the value, or to check a group of variables in one call, pass the schema to getRequired or getRequiredAll. Required values covers both. In getRequired, getRequiredAll, and a decorator with required: true, a failing schema throws InvalidEnvValue (210), and so does a schema whose validate throws, with the message as an issue. A schema that returns a Promise still throws 302.

In a decoratorCopy Anchor Link

@Envapt takes the schema through its schema option. Its converter option already accepts functions, and an arktype type is a function, so a schema in converter would look like a custom converter. envapt checks for a schema there and throws.

class Config extends Envapter {
    @Envapt('LOG_LEVEL', { schema: z.enum(['debug', 'info', 'warn', 'error']), fallback: 'info' })
    static accessor logLevel: 'debug' | 'info' | 'warn' | 'error';
}

Any conformant validator, or noneCopy Anchor Link

Any synchronous validator with a ~standard interface works, including one you write by hand. A team with its own validation rules can write one by hand, as in the sample below, and get the list of issues that a converter can't produce. Annotate the object as StandardSchemaV1<Input, Output> to give the read the output type.

const positiveInt: StandardSchemaV1<string, number> = {
    '~standard': {
        version: 1,
        vendor: 'app',
        validate(value) {
            const n = Number(value);
            if (Number.isInteger(n) && n > 0) return { value: n };
            return { issues: [{ message: 'must be a positive integer' }] };
        }
    }
};

const maxConnections = Envapter.getAs('MAX_CONNECTIONS', positiveInt, 10);
           
const maxConnections: number

validate returns { value } on success and { issues } on failure. maxConnections is a number because the schema's output is a number.