Class: ConfigBound<TSchema>

Defined in: packages/core/src/configBound.ts:101

A ConfigBound is the top level object that contains all the Sections and Binds. It is used to retrieve the values of the Elements from its binds.

The optional TSchema generic parameter enables schema-driven type inference for all read methods. When supplied, get(), getOrThrow(), getFromCache(), and getOrThrowFromCache() accept only valid section/element names from the schema and return the corresponding inferred value type.

Type Parameters

Type Parameter	Default type
TSchema extends ConfigSchema	ConfigSchema

Implements

• ConfigValueProvider

Constructors

Constructor

new ConfigBound<TSchema>(
   name, 
   binds?, 
   sections?, 
logger?): ConfigBound<TSchema>;

Defined in: packages/core/src/configBound.ts:120

Parameters

Parameter	Type	Default value
name	string	undefined
binds	Bind[]	[]
sections	Section[]	[]
logger?	Logger	undefined

Returns

ConfigBound<TSchema>

Properties

Property	Modifier	Type	Defined in
name	readonly	string	packages/core/src/configBound.ts:102

Accessors

binds

Get Signature

get binds(): readonly Bind[];

Defined in: packages/core/src/configBound.ts:111

Configured binds in resolution order.

Returns

readonly Bind[]

---

sections

Get Signature

get sections(): readonly Section[];

Defined in: packages/core/src/configBound.ts:116

Configured sections.

Returns

readonly Section[]

Methods

addBind()

addBind(bind): void;

Defined in: packages/core/src/configBound.ts:153

Adds a Bind to the ConfigBound

Parameters

Parameter	Type	Description
bind	Bind	The Bind to add

Returns

void

---

addSection()

addSection(section): void;

Defined in: packages/core/src/configBound.ts:163

Adds a Section to the ConfigBound

Parameters

Parameter	Type	Description
section	Section	The Section to add

Returns

void

---

get()

Call Signature

get<K, E>(sectionName, elementName): Promise<
  | InferConfigType<TSchema>[K][E]
| undefined>;

Defined in: packages/core/src/configBound.ts:201

Resolves a configuration value from binds/defaults.

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter
K extends string
E extends string

Parameters

Parameter	Type	Description
sectionName	K	The name of the section
elementName	E	The name of the element

Returns

Promise< | InferConfigType<TSchema>[K][E] | undefined>

The value of the element, or undefined if not found

Throws

SectionNotFoundException If section doesn't exist

Throws

ElementNotFoundException If element doesn't exist in section

Throws

ConfigInvalidException If value fails validation

See

• SectionNotFoundException
• ElementNotFoundException
• ConfigInvalidException

Implementation of

ConfigValueProvider.get

Call Signature

get<V>(sectionName, elementName): Promise<V | undefined>;

Defined in: packages/core/src/configBound.ts:205

Resolves a configuration value from binds/defaults.

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter	Default type
V	unknown

Parameters

Parameter	Type	Description
sectionName	string	The name of the section
elementName	string	The name of the element

Returns

Promise<V | undefined>

The value of the element, or undefined if not found

Throws

SectionNotFoundException If section doesn't exist

Throws

ElementNotFoundException If element doesn't exist in section

Throws

ConfigInvalidException If value fails validation

See

• SectionNotFoundException
• ElementNotFoundException
• ConfigInvalidException

Implementation of

ConfigValueProvider.get

---

getFromCache()

Call Signature

getFromCache<K, E>(sectionName, elementName): 
  | InferConfigType<TSchema>[K][E]
  | undefined;

Defined in: packages/core/src/configBound.ts:299

Gets a cached element value without querying binds.

Returns the value captured by the most recent populateCache call. This method is synchronous and safe to call in contexts that cannot await, such as class constructors.

The returned value reflects the state of the configuration at the time populateCache() last ran — it is not updated by subsequent get calls. Call populateCache() again to refresh the snapshot (e.g. after FileBind.reload()).

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter
K extends string
E extends string

Parameters

Parameter	Type	Description
sectionName	K	Section name containing the element.
elementName	E	Element name to read from cache.

Returns

| InferConfigType<TSchema>[K][E] | undefined

The cached value, or undefined when the element had no value at population time.

Throws

SectionNotFoundException If the section does not exist.

Throws

ElementNotFoundException If the element does not exist in the section.

Throws

ConfigInvalidException If the cache is not ready or the element had a validation error at population time.

Call Signature

getFromCache<V>(sectionName, elementName): V | undefined;

Defined in: packages/core/src/configBound.ts:303

Gets a cached element value without querying binds.

Returns the value captured by the most recent populateCache call. This method is synchronous and safe to call in contexts that cannot await, such as class constructors.

The returned value reflects the state of the configuration at the time populateCache() last ran — it is not updated by subsequent get calls. Call populateCache() again to refresh the snapshot (e.g. after FileBind.reload()).

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter	Default type
V	unknown

Parameters

Parameter	Type	Description
sectionName	string	Section name containing the element.
elementName	string	Element name to read from cache.

Returns

V | undefined

The cached value, or undefined when the element had no value at population time.

Throws

SectionNotFoundException If the section does not exist.

Throws

ElementNotFoundException If the element does not exist in the section.

Throws

ConfigInvalidException If the cache is not ready or the element had a validation error at population time.

---

getOrThrow()

Call Signature

getOrThrow<K, E>(sectionName, elementName): Promise<InferConfigType<TSchema>[K][E]>;

Defined in: packages/core/src/configBound.ts:265

Resolves a configuration value and throws when it is undefined.

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter
K extends string
E extends string

Parameters

Parameter	Type	Description
sectionName	K	The name of the section
elementName	E	The name of the element

Returns

Promise<InferConfigType<TSchema>[K][E]>

The value of the element (never undefined)

Throws

SectionNotFoundException If section doesn't exist

Throws

ElementNotFoundException If element doesn't exist in the section

Throws

ConfigUnsetException If the element exists but has no value and no default

Throws

ConfigInvalidException If value fails validation

Call Signature

getOrThrow<V>(sectionName, elementName): Promise<V>;

Defined in: packages/core/src/configBound.ts:269

Resolves a configuration value and throws when it is undefined.

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter	Default type
V	unknown

Parameters

Parameter	Type	Description
sectionName	string	The name of the section
elementName	string	The name of the element

Returns

Promise<V>

The value of the element (never undefined)

Throws

SectionNotFoundException If section doesn't exist

Throws

ElementNotFoundException If element doesn't exist in the section

Throws

ConfigUnsetException If the element exists but has no value and no default

Throws

ConfigInvalidException If value fails validation

---

getOrThrowFromCache()

Call Signature

getOrThrowFromCache<K, E>(sectionName, elementName): InferConfigType<TSchema>[K][E];

Defined in: packages/core/src/configBound.ts:330

Gets a cached element value and throws when the value is undefined.

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter
K extends string
E extends string

Parameters

Parameter	Type	Description
sectionName	K	Section name containing the element.
elementName	E	Element name to read from cache.

Returns

InferConfigType<TSchema>[K][E]

The cached value.

Throws

SectionNotFoundException If the section does not exist.

Throws

ElementNotFoundException If the element does not exist in the section.

Throws

ConfigUnsetException If the element exists but has no cached value.

Throws

ConfigInvalidException If the cache is not ready.

Throws

Error Re-throws a cached validation error for this element, when present.

Call Signature

getOrThrowFromCache<V>(sectionName, elementName): V;

Defined in: packages/core/src/configBound.ts:334

Gets a cached element value and throws when the value is undefined.

When the schema generic TSchema is specified, sectionName and elementName are constrained to valid keys and the return type is inferred from the schema.

Type Parameters

Type Parameter	Default type
V	unknown

Parameters

Parameter	Type	Description
sectionName	string	Section name containing the element.
elementName	string	Element name to read from cache.

Returns

V

The cached value.

Throws

SectionNotFoundException If the section does not exist.

Throws

ElementNotFoundException If the element does not exist in the section.

Throws

ConfigUnsetException If the element exists but has no cached value.

Throws

ConfigInvalidException If the cache is not ready.

Throws

Error Re-throws a cached validation error for this element, when present.

---

getSections()

getSections(): readonly Section[];

Defined in: packages/core/src/configBound.ts:181

Gets the Sections of the ConfigBound

Returns

readonly Section[]

The Sections

---

getValidationErrors()

getValidationErrors(): Promise<object[]>;

Defined in: packages/core/src/configBound.ts:410

Gets all validation errors for the current configuration without throwing. Useful for collecting all errors at once or implementing custom error handling.

Returns

Promise<object[]>

Array of validation errors with path and message

---

isCacheReady()

isCacheReady(): boolean;

Defined in: packages/core/src/configBound.ts:379

Indicates whether the cache has been populated and is ready for cached reads.

Returns

boolean

true when cache population has completed; otherwise false.

---

populateCache()

populateCache(options?): Promise<void>;

Defined in: packages/core/src/configBound.ts:352

Populates the cache for all known elements.

Parameters

Parameter	Type	Description
options?	CacheRefreshOptions	Cache population options.

Returns

Promise<void>

A promise that resolves when cache population is complete.

Throws

ConfigInvalidException When an element value is invalid and ignoreInvalid is not enabled.

Throws

SectionNotFoundException If a section lookup fails during population.

Throws

ElementNotFoundException If an element lookup fails during population.

---

validate()

validate(): Promise<void>;

Defined in: packages/core/src/configBound.ts:391

Validates all configuration values eagerly without retrieving them. This allows you to catch configuration errors at startup rather than at first access.

Returns

Promise<void>

Throws

ConfigInvalidException if any value fails validation

See

• getValidationErrors for information about how validation errors are returned
• ConfigInvalidException

---

createConfig()

static createConfig<T>(schema, options?): Promise<ConfigBound<T>>;

Defined in: packages/core/src/configBound.ts:533

Creates a ConfigBound instance from a declarative schema with full type safety. This is the recommended way to create configuration objects.

Type Parameters

Type Parameter
T extends ConfigSchema<Record<string, unknown>>

Parameters

Parameter	Type	Description
schema	T	Declarative configuration schema.
options?	ConfigBoundCreateOptions	Optional name, binds, logger, and cache mode.

Returns

Promise<ConfigBound<T>>

A fully initialized TypedConfigBound instance typed to the provided schema.

Example

const config = await ConfigBound.createConfig(
  {
    port: {
      default: 3000,
      validator: z.number(),
      description: 'Server port'
    },
    database: {
      properties: {
        host: { default: 'localhost', validator: z.string() },
        port: { default: 5432, validator: z.number() }
      }
    }
  },
  {
    binds: [await EnvVarBind.create()]
  }
);

const port = await config.get('app', 'port'); // Fully type-safe with autocomplete!