@knead-js/config

bun add @knead-js/core @knead-js/config

@knead-js/core is a peer dependency. You also need a schema library with Standard JSON Schema support: Zod 4.2+, ArkType 2.1.28+, or Valibot 1.5+ with @valibot/to-json-schema (bun add valibot @valibot/to-json-schema).

The package loads configuration once at startup from process.env, async loaders and code, validates it with your schema, and provides it as an injectable, deep-frozen Config that never prints its values. The configuration guide walks through it with examples.

#Defining configuration

#defineConfig()

defineConfig<S extends ConfigSchema>(schema: S, options?: { name?: string }): ConfigHandle<S>

Reads the schema's declared top-level properties (through ~standard.jsonSchema.input(), draft 2020-12) and returns a ConfigHandle for them.

Throws ConfigDefinitionError when:

• the schema has no ~standard.jsonSchema (the message names Zod 4.2+, ArkType 2.1.28+ and Valibot with toStandardJsonSchema());
• the JSON Schema conversion throws (Could not convert the config schema to JSON Schema., with the library's error as cause);
• the top level is not an object schema with a properties object (for example a $ref, allOf or anyOf);
• a key is not camelCase that a SCREAMING_SNAKE_CASE name converts to, such as DATABASE_URL, api_key or Port (the message suggests databaseUrl, apiKey, port).

#ConfigHandle

class ConfigHandle<S extends ConfigSchema> extends InjectionToken<Config<StandardSchemaV1.InferOutput<S>>> {
  readonly schema: S;
  readonly keys: ReadonlySet<string>;
}

The injection token for one configuration, returned by defineConfig(). inject(handle) returns a Config typed by the schema's output. schema is the schema you passed, keys the declared top-level keys, and description (from InjectionToken) the name option.

#ConfigSchema

type ConfigSchema = StandardSchemaV1 & StandardJSONSchemaV1;

A schema that implements both Standard Schema (validation) and Standard JSON Schema (key discovery).

#Registering configuration

#ConfigModule

A global module: once imported anywhere, every module can inject the handle. Each registration provides and exports exactly one handle; register several handles with several calls.

#ConfigModule.forRoot()

ConfigModule.forRoot<S extends ConfigSchema>(handle: ConfigHandle<S>, sources?: ConfigSources<S>): DynamicModule

Loads handle from process.env plus the given sources while the application is created. A loading or validation error rejects KneadFactory.create() (or compile() in tests).

#ConfigModule.forRootAsync()

ConfigModule.forRootAsync<S extends ConfigSchema>(handle: ConfigHandle<S>, options: ConfigModuleAsyncOptions<S>): DynamicModule

Like forRoot(), with the sources computed by a factory that can inject providers.

#ConfigModuleAsyncOptions

#ConfigSources

#ConfigLoader

type ConfigLoader = () => Readonly<Record<string, string | undefined>> | Promise<Readonly<Record<string, string | undefined>>>

A source of SCREAMING_SNAKE_CASE names and string values. Every loader is started outside the injection context, so inject() inside one throws InjectionContextError (reported as the cause of a ConfigLoaderError). A loader's function name appears in its error message.

#loadConfig()

loadConfig<S extends ConfigSchema>(handle: ConfigHandle<S>, sources?: ConfigSources<S>, env?: Readonly<Record<string, string | undefined>>): Promise<Config<StandardSchemaV1.InferOutput<S>>>

The loading step ConfigModule runs, usable on its own. env defaults to process.env. The steps:

1. Convert each source's names to camelCase and keep only declared keys. Names that are not SCREAMING_SNAKE_CASE (^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$) and undefined values are skipped; two names mapping to one key in the same source throw ConfigKeyCollisionError.
2. Merge env, then each loader result in order, then values, later sources winning per key.
3. Validate the merged object with the schema once; issues throw ConfigValidationError.
4. Wrap the output in a deep-frozen Config (see below for what freezing covers).

#Reading configuration

#Config

class Config<T> {
  constructor(data: T);
  get<K extends keyof T>(key: K): T[K];
  all(): Readonly<T>;
  toJSON(): Record<keyof T, '[redacted]'>;
}

The validated configuration. The constructor deep-freezes data in place (cycles are handled), so new Config({ ... }) is also how a test builds a replacement value. Freezing covers each object and array and the values of their own properties (string and symbol keys) at any depth; the contents of a Map, Set or Date (for example from a schema transform) are not properties, so they stay mutable. Binary data (a Uint8Array, Buffer, other typed array, DataView or ArrayBuffer) is kept as it is, since a typed array cannot be frozen: its bytes stay mutable.

#Errors

Every error class extends ConfigError, which extends core's KneadError; error.name is the class name.

Messages and issues never contain configuration values. Issues are deduplicated per name and key.

#ConfigIssue