objectenvy / ObjectEnvyOptions

Interface: ObjectEnvyOptions<T>

Defined in: types.ts:132

Configuration options for objectify() — controls prefix filtering, env source, Zod schema validation, camelCase nesting behaviour, and include/exclude patterns.

Config

Remarks

Pass an ObjectEnvyOptions object to objectify() to customise how environment variables are parsed. All fields are optional; the defaults represent the most common use case (read process.env, coerce values, use single-underscore nesting).

When schema is provided, heuristic nesting is disabled — the schema structure governs nesting exactly. Zod schemas additionally validate the output and throw ZodError on failure.

Example

import { objectify } from 'objectenvy';
import { z } from 'zod';

const config = objectify({
  prefix: 'APP',
  schema: z.object({ port: z.number(), debug: z.boolean() }),
  coerce: true,
  delimiter: '_',
  exclude: ['secret', 'password']
});

See

objectify

Type Parameters

Type Parameter	Default type
T	ConfigObject

Properties

Property	Type	Description	Defined in
coerce?	boolean	Whether to automatically coerce values to numbers/booleans Default true	types.ts:155
defaults?	(raw) => Partial<Record<string, string | undefined>>	Factory for context-aware defaults. Receives the raw env object (before coercion or prefix stripping) and returns raw env-style key-value pairs that fill in missing or undefined keys. Actual env values always take precedence over factory defaults. Example objectify({ prefix: 'VITE', defaults: (env) => ({ VITE_WS_URL: env['MODE'] === 'production' ? 'wss://prod.example.com/ws' : 'ws://localhost:3001' }) });	types.ts:227
delimiter?	string	Delimiter used to indicate nesting depth. By default, each underscore creates a new nesting level. Set to '__' to use double underscores for nesting. Default '_'	types.ts:163
env?	EnvLike	Custom environment object. Defaults to process.env	types.ts:142
exclude?	string[]	Exclude environment variables matching these patterns. Matches against the normalized key (after prefix removal, in camelCase). Variables matching any pattern will be excluded. Example ['secret', 'password'] // Exclude SECRET_*, PASSWORD_* variables	types.ts:192
include?	string[]	Include only environment variables matching these patterns. Matches against the normalized key (after prefix removal, in camelCase). If specified, only variables matching at least one pattern will be included. Example ['database', 'port'] // Only DATABASE_*, PORT* variables	types.ts:184
nonNestingPrefixes?	string[]	Prefix segments that should not trigger nesting even when multiple entries share the prefix. For example, keys starting with 'max', 'min', 'is', 'enable', 'disable' will stay flat: MAX_CONNECTIONS, MAX_TIMEOUT -> { maxConnections, maxTimeout } IS_DEBUG, IS_VERBOSE -> { isDebug, isVerbose } Defaults to defaultNonNestingPrefixes. Extend it without repeating the defaults: nonNestingPrefixes: [...defaultNonNestingPrefixes, 'lsp', 'ws'] Default defaultNonNestingPrefixes	types.ts:176
prefix?	string	Filter environment variables by prefix. e.g., "APP" will only include variables starting with "APP_"	types.ts:137
schema?	T extends ConfigObject ? ZodObject<any, $strip> | T : never	Schema for validation and type inference. Can be either a Zod schema or a plain object with the same structure as your config. Zod schemas will validate, plain objects provide type inference only.	types.ts:149
transform?	(parsed) => T	Post-parse transform applied after the config has been built and validated. Receives the fully coerced, validated config object and may return a wider type — use dedicated objectify overloads to capture the return type when adding derived fields. Example // Adding a derived field not present in the schema: const config = objectify({ schema: z.object({ wsUrl: z.string() }), transform: (parsed) => ({ ...parsed, sessionUrl: deriveSessionUrl(parsed.wsUrl) }) }); // config.sessionUrl is typed as string	types.ts:210