@machb/fs-config v0.0.2-SNAPSHOT
@machb/fs-config / PropertiesConfigurator
Class: PropertiesConfigurator
Defined in: PropertiesConfigurator.ts:37
PropertiesConfigurator provides a simple configuration source that resolves values by checking environment variables first and falling back to a properties file.
It implements the Configurator interface and supports an optional prefixing scheme for property names (e.g., "env.myProp" when the configurator name is "env").
Resolution order: 1. process.env[fullPropName] 2. properties file value at fullPropName 3. provided default (when using optional/getArrayProp)
The properties file path is resolved from the environment variable env.filename
(value is a full path) or defaults to "config/
Remarks
- The class caches the loaded properties reader instance and avoids repeated attempts to read the file after a failure (using fileErrorState).
- File load errors are swallowed to allow the configurator to be used in environments where no file is present (e.g., in tests or containerized runs).
Examples
// Using the default prefixing behavior:
const cfg = new PropertiesConfigurator("env", true);
const host = cfg.optional("HOST", "localhost");
// Using no prefix:
const cfg2 = new PropertiesConfigurator("app", false);
const token = cfg2.required("AUTH_TOKEN");
Implements
Configurator
Constructors
Constructor
new PropertiesConfigurator(
name,usePrefix):PropertiesConfigurator
Defined in: PropertiesConfigurator.ts:50
Create a new PropertiesConfigurator.
Parameters
name
string = "env"
Logical name used as the prefix for properties (defaults to "env").
When usePrefix is true, property lookups become "
usePrefix
boolean = true
When true, property names are prefixed with the configurator name. When false, the provided property names are used verbatim.
Returns
PropertiesConfigurator
Methods
getArrayProp()
getArrayProp(
name,defaultValue):string[] |undefined
Defined in: PropertiesConfigurator.ts:111
Retrieve a configuration property and return it as an array of strings, or a default array.
Current behavior: - If a value is found (env or file), it is returned as a single-element string array: [value]. - Otherwise, the provided defaultValue is returned (may be undefined).
Parameters
name
string
The property name to retrieve.
defaultValue
Default array to return when no value exists.
string[] | undefined
Returns
string[] | undefined
A string array if a value exists or the provided default; otherwise undefined.
Remarks
This method does not attempt to split comma-separated values. If you need multi-value parsing, split the returned single-element string externally.
Implementation of
Configurator.getArrayProp
optional()
optional(
name,defaultValue):string|undefined
Defined in: PropertiesConfigurator.ts:65
Retrieve an optional configuration property.
Resolution order: 1. environment variable: process.env[fullPropName] 2. properties file value at the same fullPropName (if file exists and was loaded) 3. defaultValue (if provided)
Parameters
name
string
The property name (without prefix unless usePrefix was set to false).
defaultValue
Value to return when neither environment nor file contain the property.
string | undefined
Returns
string | undefined
The resolved value or undefined if none found and no default provided.
Implementation of
Configurator.optional
required()
required(
name):string
Defined in: PropertiesConfigurator.ts:79
Retrieve a required configuration property as an array of strings.
The current implementation treats a single string value as a one-element array. If no value is found, this method throws an Error.
Parameters
name
string
The property name to retrieve.
Returns
string
An array of strings representing the property value.
Throws
Error if the property cannot be resolved.
Implementation of
Configurator.required
requiredArray()
requiredArray(
name):string[]
Defined in: PropertiesConfigurator.ts:88
Retrieve a required configuration property as an array of strings. If the property is not found, this method throws an Error.
Parameters
name
string
The property name to retrieve.
Returns
string[]
An array of strings representing the property value.
Remarks
This method treats a single string value as a one-element array. Use this method when the property is expected to have multiple values.
Throws
Error if the property cannot be resolved.
Implementation of
Configurator.requiredArray