westay-config

A lightweight, file-based configuration library for Node.js backend services using .properties format. It supports:

• ✅ In-memory config loading
• ✅ File change detection using chokidar
• ✅ Type-safe value access
• ✅ Auto-refresh without service restart

Designed for teams who want Git-based config flows without needing to build/maintain heavyweight cloud-native solutions.

Installation

npm install westay-config

Quick Start

1. Create a properties file

Create hotels-service.properties:

# Feature flags
ws.hotels.amadeus.supplier.enabled=true
ws.hotels.expedia.supplier.enabled=false

# Pricing configuration
ws.hotels.expedia.supplier.markup.percentage=6
ws.hotels.api.timeout.ms=5000

# Supported currencies
ws.hotels.supported.currencies=AED,SAR,USD

# Maintenance mode
ws.hotels.maintenance.mode=false

2. Initialize in your service

import config from 'westay-config';

// Initialize on service startup
config.init({
  filePath: '/etc/westay/config/hotels-service.properties',
  watch: true,
  onReload: () => {
    console.log('Configuration reloaded');
  }
});

// Use configuration values
const isAmadeusEnabled = config.getBool('ws.hotels.amadeus.supplier.enabled');
const markupPercentage = config.getFloat('ws.hotels.expedia.supplier.markup.percentage');
const currencies = config.getArray('ws.hotels.supported.currencies');
const timeout = config.getInt('ws.hotels.api.timeout.ms');

API Reference

init(options: InitOptions)

Initialize the configuration system.

config.init({
  filePath: string,        // Path to .properties file (required)
  watch?: boolean,         // Enable file watching (default: true)
  onReload?: () => void    // Callback when config is reloaded (optional)
});

get(key: string): string | undefined

Get a string value by key.

const apiKey = config.get('api.key');

getBool(key: string): boolean

Get a boolean value by key. Returns false if key doesn't exist or value is invalid.

Accepts: "true", "1", "yes", "on" → true All other values → false

const enabled = config.getBool('feature.enabled');

getInt(key: string): number

Get an integer value by key. Returns 0 if key doesn't exist or value is invalid.

const retryCount = config.getInt('retry.count');

getFloat(key: string): number

Get a float value by key. Returns 0.0 if key doesn't exist or value is invalid.

const margin = config.getFloat('price.margin');

getArray(key: string, separator?: string): string[]

Get an array of strings by key. Splits by separator (default: comma).

const ips = config.getArray('allowed.ips');
const items = config.getArray('list.items', '|'); // Custom separator

has(key: string): boolean

Check if a key exists in the configuration.

if (config.has('api.key')) {
  // Use the key
}

reload(): boolean

Manually reload configuration from file. Returns true if successful.

const success = config.reload();

Properties File Format

The library supports standard .properties format:

# Comments start with # or !
key=value
another.key=another value

# Multi-line values (with backslash continuation)
description=This is a long \
description that spans \
multiple lines

# Special characters are supported
path=/usr/local/bin

Supported features:

• Comments (# or !)
• Empty lines (ignored)
• Escaped characters (\n, \t, \\, etc.)
• Multi-line values (with \ continuation)

Error Handling

• On initialization: If the config file doesn't exist, init() will throw an error (fail fast).
• On reload: If reload fails, previous configuration is retained and an error is logged.
• Invalid lines: Lines that can't be parsed are logged as warnings and skipped.

Auto-Refresh

When watch: true (default), the library automatically reloads configuration when the file changes. This happens without requiring a service restart.

config.init({
  filePath: '/path/to/config.properties',
  watch: true,  // Enable auto-refresh
  onReload: () => {
    console.log('Config updated!');
  }
});

Usage in Multiple Services

Each service initializes with its own config file:

hotels-service:

config.init({
  filePath: '/etc/westay/config/hotels-service.properties'
});

flights-service:

config.init({
  filePath: '/etc/westay/config/flights-service.properties'
});

Deployment

• Config files typically live outside containers (e.g., /etc/westay/config/)
• Updated via GitLab pipeline or S3 sync
• No need to rebuild containers to update configs

Security Notes

⚠️ Avoid putting secrets in .properties files. Use Secrets Manager for secrets. Only use westay-config for non-sensitive operational configs.

License

ISC