[RFC] ConfigModule (Resolver-Based, Type-Safe, Group-Friendly, Refreshable)

[Evanion]

[RFC] ConfigModule for NexusDI (Resolver-Based, Type-Safe, Group-Friendly, Refreshable)

Overview

The ConfigModule provides centralized, type-safe, and environment-aware configuration for NexusDI projects. It is designed around a resolver pattern (for pluggable config sources) and supports grouping/namespacing, schema validation, seamless integration with DI and dynamic module configuration, and refreshable/dynamic config for providers like Azure AppConfig, AWS AppConfig, or Kubernetes ConfigMaps.

Motivation

• Centralized config: Avoid scattered config logic and magic strings throughout the codebase.
• Type safety: Enable type-checked configuration objects for better DX and fewer runtime errors.
• Environment awareness: Support for environment-specific config (dev, prod, test, etc.).
• Integration: Allow modules and plugins to declare and consume config via DI or via .config/.configAsync.
• Secrets management: Optionally support loading secrets from files, env, or secret managers.
• Provider-agnostic: Easily swap config sources (env, files, AWS, Kubernetes, etc.) by changing resolvers.
• Grouping: Support for config groups/namespaces for modular, maintainable config.
• Refreshable config: Support for dynamic config sources that can be refreshed or emit change events.

Proposed Features

• Load config from one or more resolvers: .env, JSON/YAML files, AWS SSM/Secrets Manager, Kubernetes, Azure AppConfig, etc.
• Support for config schemas (e.g., Zod, Joi, TypeScript interfaces) for validation and type safety.
• Provide a ConfigService (or similar) that can be injected into any provider.
• Support for environment-specific overrides (e.g., config.dev.json, config.prod.json).
• Support for config grouping/namespacing and group injection.
• Support for dynamic module configuration via .config and .configAsync using the config module.
• Optionally support secret resolution (e.g., from AWS Secrets Manager, Vault, etc.).
• CLI utilities for validating and printing config.
• Refreshable config: Resolvers can implement refresh() or onChange(); ConfigService exposes refresh() and onChange() for runtime updates.

Example Workflow

1. Define config files:

   • config.json (base config)
   • config.dev.json (development overrides)
   • config.prod.json (production overrides)
   • .env (environment variables)

2. Define a config schema (optional but recommended):

   // config/schema.ts
   import { z } from 'zod';
   
   export const AppConfigSchema = z.object({
     port: z.number().default(3000),
     db: z.object({
       url: z.string(),
       poolSize: z.number().optional(),
     }),
     sentryDsn: z.string().optional(),
     user: z.object({
       minPasswordLength: z.number().default(8),
       requireEmailVerification: z.boolean().default(true),
     }),
   });
   
   export type AppConfig = z.infer<typeof AppConfigSchema>;

3. Register the config module with resolvers and schema:

   import { ConfigPlugin } from '@nexusdi/config';
   import { AppConfigSchema } from './config/schema';
   import { envResolver, jsonResolver, azureAppConfigResolver } from '@nexusdi/config/resolvers';
   
   container.use(ConfigPlugin, {
     resolvers: [
       envResolver(),
       jsonResolver({ file: 'config.json' }),
       jsonResolver({ file: `config.${process.env.NODE_ENV}.json`, optional: true }),
       azureAppConfigResolver({ connectionString: process.env.AZURE_APPCONFIG }),
     ],
     schema: AppConfigSchema,
   });

4. Inject and use the config service or config groups:

   import { InjectConfig } from '@nexusdi/config';
   import type { AppConfig } from './config/schema';
   
   class DatabaseService {
     constructor(@InjectConfig('db') private dbConfig: AppConfig['db']) {}
   
     connect() {
       // dbConfig.url, dbConfig.poolSize, etc.
     }
   }
   
   class AppService {
     constructor(@InjectConfig() private config: AppConfig) {}
   }

5. Use in dynamic module config (sync and async):

   // Synchronous config
   import { UserModule } from './user/user.module';
   import { ConfigService } from '@nexusdi/config';
   
   const userConfig = container.get(ConfigService).get('user');
   container.set(UserModule.config(userConfig));
   
   // Async config (e.g., if config is loaded from a remote source)
   const userModule = await UserModule.configAsync(async () => {
     const configService = container.get(ConfigService);
     return await configService.getAsync('user');
   });
   container.set(userModule);
   
   // Or inline:
   container.set(
     await UserModule.configAsync(async () => {
       const configService = container.get(ConfigService);
       return await configService.getAsync('user');
     })
   );

6. Refreshable Config: Manual and Event-Driven

   // Manual refresh (e.g., on a timer or webhook)
   setInterval(() => {
     configService.refresh();
   }, 60000);
   
   // React to changes
   configService.onChange(() => {
     // Reload or update dependent services, clear caches, etc.
   });

Refreshable Config: Design Details

• Resolver API:
  Resolvers can optionally implement a refresh() method or emit a change event.

  export interface ConfigResolver {
    resolve(key: string): Promise<any>;
    refresh?(): Promise<void>;
    onChange?(callback: () => void): void;
  }

• ConfigService API:

  • refresh(): Manually trigger a refresh across all resolvers.
  • onChange(callback): Subscribe to config changes.
  • On refresh or change, config is re-merged, re-validated, and change events are emitted.

• Consumer Usage:

  • Use configService.refresh() for manual refresh (e.g., polling, webhooks).
  • Use configService.onChange() for event-driven updates.

• Injection:

  • By default, injected config is an immutable snapshot.
  • Optionally, support live/observable config for advanced use cases.

Open Questions

• Should we support both schema-based (Zod/Joi) and interface-based (TypeScript) config validation?
• How should secrets be resolved and injected (e.g., via special keys, plugins, or config sections)?
• Should config be immutable at runtime, or support hot reload/updates?
• How to best support config for plugins and modules (namespacing, merging, etc.)?
• Should we provide CLI tools for config validation, printing, and environment checks?
• Should we support chaining/merging of multiple resolvers, and in what order?
• How should conflicts/overrides be handled (last-wins, priority, etc.)?
• Should injected config be immutable or live-updating by default?
• Should we provide built-in support for event-driven config refresh (e.g., via webhooks, push notifications)?

API Sketch

// Register config module with resolvers and schema
container.use(ConfigPlugin, {
  resolvers: [
    envResolver(),
    jsonResolver({ file: 'config.json' }),
    jsonResolver({ file: `config.${process.env.NODE_ENV}.json`, optional: true }),
    azureAppConfigResolver({ connectionString: process.env.AZURE_APPCONFIG }),
  ],
  schema: AppConfigSchema,
});

// Inject config group
class MyService {
  constructor(@InjectConfig('user') private userConfig: AppConfig['user']) {}
}

// Use in dynamic module config (async)
const userModule = await UserModule.configAsync(async () => {
  const configService = container.get(ConfigService);
  return await configService.getAsync('user');
});
container.set(userModule);

// Refreshable config
await configService.refresh();
configService.onChange(() => {
  // React to config changes
});

Call for Feedback

• What config sources/resolvers do you use or want supported?
• Would you use config grouping/namespacing in your projects?
• What DX improvements would make config management easier for you?
• Any pain points with config in other frameworks?
• Should we support both schema-based and interface-based validation?
• Do you need live/dynamic config in your projects?
• Would you prefer manual refresh, event-driven, or both?
• Should injected config be immutable or live-updating by default?
• Any other features or utilities you’d want?