madapes
Repositories
7
 Projects Packages

@aurora/runtime-config (0.3.3)

Published 2025-12-27 10:44:38 +00:00 by vlad

Installation

@aurora:registry=
npm install @aurora/runtime-config@0.3.3
"@aurora/runtime-config": "0.3.3"

About this package

@aurora/runtime-config

Runtime configuration management for Aurora applications with environment variables and file support.

Overview

Aurora config package provides:

  • Zod-based schema validation
  • Environment variable support with AURORA_ prefix
  • JSON and YAML config file support
  • Config merging (defaults < file < env < CLI args)
  • Helpful error messages

Installation

bun add @aurora/runtime-config

Usage

Define Config Schema

import { defineConfig, z } from "@aurora/runtime-config";

const configSchema = defineConfig({
  server: {
    port: z.number().min(1).max(65535).default(3000),
    host: z.string().default("0.0.0.0"),
  },
  nats: {
    url: z.string().url().default("nats://localhost:4222"),
    maxReconnects: z.number().default(10),
  },
  storage: {
    path: z.string().default("./data"),
    hotRetentionDays: z.number().default(90),
  },
  sharding: {
    totalShards: z.number().default(10),
    ownedShards: z.array(z.string()).default([]),
  },
  logging: {
    level: z.enum(["debug", "info", "warn", "error"]).default("info"),
  },
});

export type AuroraConfig = z.infer<typeof configSchema>;

Load Config

import { loadConfig } from "@aurora/runtime-config";
import { configSchema } from "./config";

const config = loadConfig(configSchema);

console.log(config.server.port);      // 3000
console.log(config.nats.url);         // nats://localhost:4222
console.log(config.storage.path);      // ./data

Config Priority

Configuration is merged in this order (later overrides earlier):

  1. Defaults - From schema .default()
  2. Config file - From aurora.config.json or aurora.config.yaml
  3. Environment variables - AURORA_* prefixed
  4. CLI arguments - Passed programmatically

Environment Variables

# Set via environment
export AURORA_SERVER_PORT=3001
export AURORA_NATS_URL=nats://localhost:4223
export AURORA_STORAGE_PATH=/var/data/aurora
export AURORA_LOGGING_LEVEL=debug

Nested config uses double underscores:

# Nested: server.port
export AURORA_SERVER__PORT=3001

# Deep nesting: sharding.ownedShards[0]
export AURORA_SHARDING__OWNED_SHARDS__0=shard-1

Config Files

JSON:

{
  "server": {
    "port": 3001,
    "host": "localhost"
  },
  "nats": {
    "url": "nats://production-nats:4222"
  },
  "storage": {
    "path": "/var/data/aurora",
    "hotRetentionDays": 180
  }
}

YAML:

server:
  port: 3001
  host: localhost

nats:
  url: nats://production-nats:4222
  maxReconnects: 20

storage:
  path: /var/data/aurora
  hotRetentionDays: 180

logging:
  level: debug

Custom File Path

import { loadConfig } from "@aurora/runtime-config";

const config = loadConfig(configSchema, {
  configFile: "./config/production.yaml",
});

CLI Override

import { loadConfig } from "@aurora/runtime-config";

const config = loadConfig(configSchema, {
  cliArgs: {
    "server.port": 3002,
    "logging.level": "error",
  },
});

Validation

Schema Validation

import { z } from "@aurora/runtime-config";

const configSchema = defineConfig({
  port: z.number().min(1024).max(65535),
  url: z.string().url(),
  email: z.string().email(),
});

// Throws on invalid config
const config = loadConfig(configSchema);

Error Messages

// Invalid config
export AURORA_SERVER_PORT=99999

// Error:
// Config validation failed:
// - server.port: Number must be less than or equal to 65535

Optional Fields

const configSchema = defineConfig({
  optionalField: z.string().optional(),
  optionalWithDefault: z.number().default(42),
});

Advanced Usage

Custom Parser

import { loadConfig } from "@aurora/runtime-config";

const config = loadConfig(configSchema, {
  parsers: {
    custom: (value: string) => {
      // Custom parsing logic
      return JSON.parse(value);
    },
  },
});

Environment Prefix

const config = loadConfig(configSchema, {
  envPrefix: "MYAPP_",  // Instead of AURORA_
});

export MYAPP_SERVER_PORT=3001

Config Watcher

import { watchConfig } from "@aurora/runtime-config";

const watcher = watchConfig(configSchema, "./aurora.config.yaml");

watcher.on("change", (newConfig) => {
  console.log("Config updated:", newConfig);
  // Reload services with new config
});

watcher.on("error", (error) => {
  console.error("Config error:", error);
});

Testing

import { test, expect } from "bun:test";
import { loadConfig } from "@aurora/runtime-config";

test("config loads with defaults", () => {
  const config = loadConfig(configSchema);
  
  expect(config.server.port).toBe(3000);
  expect(config.nats.url).toBe("nats://localhost:4222");
});

test("env vars override defaults", () => {
  process.env.AURORA_SERVER_PORT = 4000;
  
  const config = loadConfig(configSchema);
  
  expect(config.server.port).toBe(4000);
  
  delete process.env.AURORA_SERVER_PORT;
});

License

MIT

Dependencies

Dependencies

ID Version
js-yaml ^4.1.0
zod ^3.22.4

Development Dependencies

ID Version
@types/js-yaml ^4.0.9
Details
npm
2025-12-27 10:44:38 +00:00
3
latest
5.3 KiB
Assets (1)
runtime-config-0.3.3.tgz 5.3 KiB
Versions (3) View all
0.3.3 2025-12-27
0.3.2 2025-12-27
0.3.1 2025-12-27