builder
Option builder for handling CLI/config/default option precedence.
This utility provides a fluent interface for merging options from multiple sources (CLI, config file, defaults) with consistent precedence rules:
- CLI options (highest priority)
- Config file options
- Default values (lowest priority)
Precedence is enforced semantically via the setIfProvided() method, regardless of the order in which methods are called. Each value tracks its source, and only higher-precedence sources can override existing values.
Eliminates repetitive if/coalesce patterns throughout the codebase.
OptionBuilder
Defined in: core/src/options/builder.ts:49
Builder for constructing options from multiple sources with priority precedence.
Precedence is enforced semantically via source tracking, not by call order. CLI values always override config values, which always override defaults, regardless of the order in which methods are called.
Example
const options = new OptionBuilder<MyOptions>()
// Add in order: default -> config -> cli
.addDefault(false, "pretty")
.addFromConfig(undefined, "pretty")
.addFromCli(true, "pretty") // CLI overrides default
.addDefault("/", "baseURL")
.addFromConfig("/api", "baseURL") // Config overrides default
.addFromCli(undefined, "baseURL")
.build();
// Result: { pretty: true, baseURL: "/api" }
Type Parameters
T
T extends Record<string, unknown>
The type of the options object being built
Constructors
Constructor
new OptionBuilder<T>(): OptionBuilder<T>;
Returns
Methods
addDefault()
addDefault<K>(value, key): this;
Defined in: core/src/options/builder.ts:73
Adds a default value (lowest priority). Sets a value that can be overwritten by config or CLI options. This method can be called at any time; precedence is enforced semantically.
Type Parameters
K
K extends string | number | symbol
Parameters
value
Maybe<T[K]>
The default value
key
K
The key to store the value under
Returns
this
This builder for method chaining
Example
builder.addDefault(3000, "port");
addFromCli()
addFromCli<K>(value, key): this;
Defined in: core/src/options/builder.ts:109
Adds a value from CLI options if provided (highest priority). Can override both default and config values for this key. This method can be called at any time; precedence is enforced semantically.
Type Parameters
K
K extends string | number | symbol
Parameters
value
Maybe<T[K]>
The CLI option value
key
K
The key to store the value under
Returns
this
This builder for method chaining
Example
builder.addFromCli(cliOpts.port, "port");
addFromConfig()
addFromConfig<K>(value, key): this;
Defined in: core/src/options/builder.ts:91
Adds a value from config file if provided (medium priority). Can override default values if the config value exists. This method can be called at any time; precedence is enforced semantically.
Type Parameters
K
K extends string | number | symbol
Parameters
value
Maybe<T[K]>
The config file option value
key
K
The key to store the value under
Returns
this
This builder for method chaining
Example
builder.addFromConfig(config.port, "port");
build()
build(): Partial<T>;
Defined in: core/src/options/builder.ts:190
Returns the built options object with all accumulated values. The object contains all keys that were set during the building process.
Note: The returned object may be a partial object containing only the keys that were set. Callers should handle potentially missing properties. Returns a defensive copy of the object to prevent external mutations of internal state. Arrays and objects are shallow-copied to protect against external modifications.
Returns
Partial<T>
The constructed options object with type Partial<T> (may not have all properties of T)
get()
get<K>(key): T[K] | undefined;
Defined in: core/src/options/builder.ts:167
Gets the current value for a key without building. Useful for conditional logic during building. Returns a shallow copy for arrays and objects to prevent external mutations. Note: Nested objects and arrays are not deep copied.
Type Parameters
K
K extends string | number | symbol
Parameters
key
K
The key to get
Returns
T[K] | undefined
The current value for the key, or undefined if not set
transform()
transform<K>(key, fn): this;
Defined in: core/src/options/builder.ts:126
Transforms a value using a function if the key exists. Useful for processing values after they've been set.
Type Parameters
K
K extends string | number | symbol
Parameters
key
K
The key to transform
fn
(v) => T[K]
Function that transforms the current value
Returns
this
This builder for method chaining
Example
builder.transform("path", (p) => resolve(p));
transformIf()
transformIf<K>(
key,
predicate,
fn): this;
Defined in: core/src/options/builder.ts:147
Conditionally applies a transformation if a predicate is true. Useful for applying different transformations based on other values.
Type Parameters
K
K extends string | number | symbol
Parameters
key
K
The key to potentially transform
predicate
(merged) => boolean
Function that determines if transformation should apply
fn
(v) => T[K]
Function that transforms the value if predicate is true
Returns
this
This builder for method chaining
Example
builder.transformIf(
"path",
() => force,
(p) => resolve(p),
);