Configuration

Strata v2 removed the built-in configuration system. Instead, the StrataService and StrataClient constructors accept plain config objects. Where you get that object is up to you -- hardcode it, load it from a file, pull it from environment variables, or use the @strata-js/util-config utility.

Config Interfaces

All configuration flows through two TypeScript interfaces: StrataServiceConfig for services and StrataClientConfig for clients. Both are built from the same base StrataConfig type.

StrataServiceConfig

Used when constructing a StrataService. Requires service and backend.

import type { StrataServiceConfig } from '@strata-js/strata';

const config : StrataServiceConfig = {
    // Required: identifies this service group
    service: {
        serviceGroup: 'MyService',
    },

    // Required: which backend to use
    backend: {
        type: 'redis',
        redis: { host: 'localhost', port: 6379 },
    },
};

Full interface:

Property	Type	Required	Default	Description
service.serviceGroup	string	Yes	—	Name shared by all instances of this service. Determines which queue the service reads from.
service.concurrency	number	No	32	Maximum number of requests processed simultaneously.
service.defaultRequestTimeout	number	No	—	Default timeout (ms) for requests.
service.toobusy	TooBusyConfig	No	—	Dynamic concurrency control via node-toobusy.
backend	BackendConfig	Yes	—	Backend configuration. See Backend Configuration.
client	ClientConfig	No	—	Optional embedded client config.
logging	LoggerConfig	No	—	Logging config (level, prettyPrint).
aliases	Record<string, string>	No	—	Friendly names that map to service group names.
shutdownTimeout	number	No	—	How long (ms) to wait for graceful shutdown.
interruptsToForceShutdown	number	No	—	Number of SIGINT signals before forcing shutdown.

TooBusyConfig

Controls the node-toobusy event loop lag detection:

Property	Type	Default	Description
maxLag	number	70	Maximum event loop lag (ms) before refusing work.
interval	number	500	How often (ms) to check event loop lag.
smoothingFactorOnRise	number	1/3	Smoothing factor when lag is increasing.
smoothingFactorOnFall	number	1/3	Smoothing factor when lag is decreasing.

StrataClientConfig

Used when constructing a StrataClient. The service property is optional (and all its fields are optional if present). backend is required.

import type { StrataClientConfig } from '@strata-js/strata';

const config : StrataClientConfig = {
    // Optional: names this client
    client: {
        name: 'MyClient',
    },

    // Required: which backend to use
    backend: {
        type: 'redis',
        redis: { host: 'localhost', port: 6379 },
    },
};

Full interface:

Property	Type	Required	Default	Description
client.name	string	No	StrataClient.<hostname>	Name for this client. Used to identify the client in logs and the response queue.
client.id	string	No	auto-generated	Unique client ID. Usually you let Strata generate this.
backend	BackendConfig	Yes	—	Backend configuration. Same as service.
service	Partial<ServiceConfig>	No	—	Optional. If present, service.serviceGroup is used to derive a default client name.
logging	LoggerConfig	No	—	Logging config.
aliases	Record<string, string>	No	—	Friendly names that map to service group names.
shutdownTimeout	number	No	—	Graceful shutdown timeout.
interruptsToForceShutdown	number	No	—	Interrupts before force shutdown.

Shared Config

StrataServiceConfig is a superset of StrataClientConfig. If your service needs an embedded client, you can pass the same config object to both constructors. The service uses service.serviceGroup, the client uses client.name.

Backend Configuration

The backend object tells Strata which transport to use. The type field selects the backend; all other fields are backend-specific. For detailed descriptions of each built-in backend (Redis Streams, Redis Lists, Null), see the Backends reference.

Backend Config Reference

Property	Type	Default	Description
type	string	—	Backend name: 'redis', 'redis-streams', 'null', or a custom registered name.
redis	RedisOptions	—	ioredis connection options. Required for Redis backends.
validateEnvelopes	boolean	true	Validate message envelope structure at runtime. See Envelope Validation.
isolateCommands	boolean	false	Use a separate Redis connection for commands (Redis Streams only).
discovery.enabled	boolean	true	Enable service discovery.
discovery.interval	number	30	How often (seconds) to refresh the discovery key (Redis only).
discovery.ttl	number	90	TTL (seconds) for the discovery key (Redis only).
discovery.db	number	0	Redis DB number for discovery data (Redis only).

YAML Config Files with @strata-js/util-config

The recommended way to manage configuration is with @strata-js/util-config, a simple file loader that supports YAML, JSON, and JSON5.

npm install @strata-js/util-config

Loading a Config File

import configUtil from '@strata-js/util-config';

// Load config from a YAML file
configUtil.load('./config/local.yml');

// Retrieve the parsed config object
const config = configUtil.get<StrataServiceConfig>();

load() reads the file, performs environment variable substitution, and stores the result under a name (defaults to 'default'). get() retrieves it.

You can store multiple configs under different names:

configUtil.load('./config/service.yml', 'service');
configUtil.load('./config/client.yml', 'client');

const serviceConfig = configUtil.get<StrataServiceConfig>('service');
const clientConfig = configUtil.get<StrataClientConfig>('client');

Complete YAML Example

# config/local.yml

# Logging
logging:
  level: debug
  prettyPrint: true

# Service
service:
  serviceGroup: "MyService.$HOSTNAME"
  concurrency: 16

# Client (optional, for embedded clients)
client:
  name: "MyServiceClient"

# Aliases
aliases:
  orders: "OrderService.$HOSTNAME"
  users: "UserService.$HOSTNAME"

# Backend
backend:
  type: "redis-streams"
  validateEnvelopes: true
  redis:
    host: "localhost"
    port: 6379
  discovery:
    enabled: true
    interval: 30
    ttl: 90

Production Example

# config/production.yml

logging:
  level: info
  prettyPrint: false

service:
  serviceGroup: "MyService"
  concurrency: 64

aliases:
  orders: "OrderService"
  users: "UserService"

backend:
  type: "redis-streams"
  redis:
    host: "$REDIS_HOST"
    port: 6379
    password: "$REDIS_PASSWORD"
  discovery:
    enabled: true

Environment Variable Substitution

When @strata-js/util-config loads a file, it replaces environment variable references with their runtime values. Three syntaxes are supported:

Syntax	Example
$VAR	$HOSTNAME
${VAR}	${REDIS_HOST}

If an environment variable is not set, the reference is left as-is in the string. This means you should set all referenced variables before calling configUtil.load().

A common pattern is to set defaults before loading config:

import { hostname } from 'node:os';

process.env.HOSTNAME = process.env.HOSTNAME ?? hostname();
process.env.ENVIRONMENT = process.env.ENVIRONMENT ?? 'local';

const env = process.env.ENVIRONMENT;
configUtil.load(`./config/${ env }.yml`);

File Includes

Config files can include other config files using the include key. Included files are merged into the base config (included values are overridden by the base file's values):

# config/base.yml
backend:
  type: "redis-streams"
  redis:
    host: "localhost"
    port: 6379

# config/local.yml
include: "base.yml"

service:
  serviceGroup: "MyService.$HOSTNAME"

logging:
  level: debug
  prettyPrint: true

Multiple includes are supported as an array:

include:
  - "base.yml"
  - "logging-defaults.yml"

Include resolution goes up to 10 levels deep by default. Set the INCLUDE_DEPTH environment variable to change this limit.

Envelope Validation

All backends validate message envelopes by default. This catches malformed messages before they reach your handlers. The performance overhead is negligible (under 2% in benchmarks).

To disable validation:

backend: {
    type: 'redis',
    validateEnvelopes: false,
    redis: { host: 'localhost', port: 6379 },
}

For details on what gets validated and how to handle validation errors, see the Envelope Validation guide.