@haskou/ddd-kernel 1.1.0 → 1.2.0

package/dist/{RetryPredicate-DAv_7ve2.d.ts → RetryPredicate-Bl3SMnbL.d.ts}

@@ -1,4 +1,4 @@
-import { a as ConsumerExecutionContext } from './ShutdownHook-3Gc1yyHI.js';
+import { a as ConsumerExecutionContext } from './ShutdownHook-B03Mcke-.js';
 
 interface IdempotencyStore {
     claim?(key: string): Promise<boolean> | boolean;

package/dist/{RetryPredicate-CBlnBUDO.d.cts → RetryPredicate-ZjioTYXn.d.cts}

@@ -1,4 +1,4 @@
-import { a as ConsumerExecutionContext } from './ShutdownHook-BUvR2Ii7.cjs';
+import { a as ConsumerExecutionContext } from './ShutdownHook-BsEGvnEf.cjs';
 
 interface IdempotencyStore {
     claim?(key: string): Promise<boolean> | boolean;

package/dist/{ShutdownHook-3Gc1yyHI.d.ts → ShutdownHook-B03Mcke-.d.ts}

@@ -27,19 +27,49 @@ interface KernelDependencyInjectionOptions {
     readonly sourceDirectory?: string;
 }
 
-interface KernelEnvironmentVariablesOptions {
+type KernelDefaultEnvironment = NodeJS.ProcessEnv;
+
+type KernelEnvironmentVariableType = 'boolean' | 'number' | 'string';
+
+type KernelEnvironmentVariablePrimitive<TType extends KernelEnvironmentVariableType> = TType extends 'boolean' ? boolean : TType extends 'number' ? number : string;
+
+interface KernelEnvironmentVariableDefinition<TType extends KernelEnvironmentVariableType = KernelEnvironmentVariableType, TRequired extends boolean = boolean> {
+    readonly defaultValue?: KernelEnvironmentVariablePrimitive<TType>;
+    readonly required?: TRequired;
+    readonly type: TType;
+}
+
+type KernelEnvironmentSchema = Readonly<Record<string, KernelEnvironmentVariableDefinition>>;
+
+type KernelEnvironmentValue = boolean | number | string;
+
+type KernelEnvironmentVariable<TDefinition extends KernelEnvironmentVariableDefinition> = TDefinition extends KernelEnvironmentVariableDefinition<infer TType extends KernelEnvironmentVariableType, infer TRequired extends boolean> ? TDefinition extends {
+    readonly defaultValue: unknown;
+} ? KernelEnvironmentVariablePrimitive<TType> : TRequired extends true ? KernelEnvironmentVariablePrimitive<TType> : KernelEnvironmentVariablePrimitive<TType> | undefined : never;
+
+type KernelEnvironment<TSchema extends KernelEnvironmentSchema> = {
+    readonly [key: string]: KernelEnvironmentValue | undefined;
+} & {
+    readonly [TKey in keyof TSchema]: KernelEnvironmentVariable<TSchema[TKey]>;
+};
+
+type KernelEnvironmentForSchema<TSchema extends KernelEnvironmentSchema | undefined> = TSchema extends KernelEnvironmentSchema ? KernelEnvironment<TSchema> : KernelDefaultEnvironment;
+
+interface KernelEnvironmentVariablesOptions<TSchema extends KernelEnvironmentSchema | undefined = undefined> {
     readonly override?: boolean;
     readonly path?: string;
+    readonly schema?: TSchema;
 }
 
-interface KernelOptions {
+interface KernelOptions<TEnvironmentSchema extends KernelEnvironmentSchema | undefined = undefined> {
     readonly di?: DependencyInjection;
+    readonly environmentSchema?: TEnvironmentSchema;
     readonly logger?: KernelLogger;
     readonly servicesYamlPath?: string;
     readonly sourceDirectory?: string;
 }
 
-declare class Kernel {
+declare class Kernel<TEnvironmentSchema extends KernelEnvironmentSchema | undefined = undefined> {
     private readonly options;
     private static readonly stateKey;
     private readonly consumerMiddlewares;
@@ -49,6 +79,7 @@ declare class Kernel {
     private readonly schedulersList;
     private readonly shutdownHooks;
     private dependencyInjectionInstance;
+    private environmentVariables;
     private static get state();
     static get configDirectory(): string;
     static get consumers(): Consumer[];
@@ -56,15 +87,20 @@ declare class Kernel {
     static get di(): DependencyInjection;
     static get environment(): NodeJS.ProcessEnv;
     static get logger(): KernelLogger;
-    static get active(): Kernel;
+    static get active(): Kernel<KernelEnvironmentSchema | undefined>;
     static get rootDirectory(): string;
     static get routes(): ServiceClass<Route>[];
     static get schedulers(): Scheduler[];
     static get sourceDirectory(): string;
     private static getActiveKernel;
+    private static assertRequiredEnvironmentVariable;
     private static getEnvironmentVariablesPath;
-    static loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions): DotenvConfigOutput;
-    constructor(options?: KernelOptions);
+    private static parseBooleanEnvironmentVariable;
+    private static parseNumberEnvironmentVariable;
+    private static parseEnvironmentVariable;
+    private static validateEnvironmentVariables;
+    static loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions<KernelEnvironmentSchema | undefined>): DotenvConfigOutput;
+    constructor(options?: KernelOptions<TEnvironmentSchema>);
     private closeCandidate;
     private getConsumerFromClass;
     private getInitializerFromClass;
@@ -73,13 +109,13 @@ declare class Kernel {
     get consumers(): Consumer[];
     get consumerMiddleware(): ConsumerMiddleware[];
     get di(): DependencyInjection;
-    get environment(): NodeJS.ProcessEnv;
+    get environment(): KernelEnvironmentForSchema<TEnvironmentSchema>;
     get logger(): KernelLogger;
     get routes(): ServiceClass<Route>[];
     get schedulers(): Scheduler[];
     private getDependencyInjectionOptions;
     dependencyInjection(options?: KernelDependencyInjectionOptions): Promise<void>;
-    loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions): DotenvConfigOutput;
+    loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions<KernelEnvironmentSchema | undefined>): DotenvConfigOutput;
     getRoutes(): ServiceClass<Route>[];
     registerConsumerMiddleware(...middlewares: ConsumerMiddleware[]): void;
     registerConsumers(...ClassDefinitions: ServiceClass<Consumer>[]): void;
@@ -98,7 +134,7 @@ declare class Kernel {
     runSchedulers(): Promise<void>;
     shutdown(): Promise<void>;
 }
-declare function createKernel(options?: KernelOptions): Kernel;
+declare function createKernel<TEnvironmentSchema extends KernelEnvironmentSchema | undefined = undefined>(options?: KernelOptions<TEnvironmentSchema>): Kernel<TEnvironmentSchema>;
 
 interface ConsumerExecutionContext {
     readonly causationId?: string;
@@ -106,7 +142,7 @@ interface ConsumerExecutionContext {
     readonly eventId: string;
     readonly eventName: string;
     readonly exchange: string;
-    readonly kernel: Kernel;
+    readonly kernel: Kernel<KernelEnvironmentSchema | undefined>;
     readonly metadata: Readonly<Record<string, unknown>>;
     readonly rawMessage?: unknown;
     readonly queueName: string;
@@ -120,4 +156,4 @@ interface ConsumerMiddleware {
 
 type ShutdownHook = () => Promise<void> | void;
 
-export { Consumer as C, Kernel as K, type ShutdownHook as S, type ConsumerExecutionContext as a, type ConsumerMiddleware as b, type ConsumerNext as c, type KernelDependencyInjectionOptions as d, type KernelEnvironmentVariablesOptions as e, type KernelOptions as f, createKernel as g };
+export { Consumer as C, Kernel as K, type ShutdownHook as S, type ConsumerExecutionContext as a, type ConsumerMiddleware as b, type ConsumerNext as c, type KernelDefaultEnvironment as d, type KernelDependencyInjectionOptions as e, type KernelEnvironment as f, type KernelEnvironmentForSchema as g, type KernelEnvironmentSchema as h, type KernelEnvironmentValue as i, type KernelEnvironmentVariableDefinition as j, type KernelEnvironmentVariablePrimitive as k, type KernelEnvironmentVariableType as l, type KernelEnvironmentVariablesOptions as m, type KernelOptions as n, createKernel as o };

package/dist/{ShutdownHook-BUvR2Ii7.d.cts → ShutdownHook-BsEGvnEf.d.cts}

@@ -27,19 +27,49 @@ interface KernelDependencyInjectionOptions {
     readonly sourceDirectory?: string;
 }
 
-interface KernelEnvironmentVariablesOptions {
+type KernelDefaultEnvironment = NodeJS.ProcessEnv;
+
+type KernelEnvironmentVariableType = 'boolean' | 'number' | 'string';
+
+type KernelEnvironmentVariablePrimitive<TType extends KernelEnvironmentVariableType> = TType extends 'boolean' ? boolean : TType extends 'number' ? number : string;
+
+interface KernelEnvironmentVariableDefinition<TType extends KernelEnvironmentVariableType = KernelEnvironmentVariableType, TRequired extends boolean = boolean> {
+    readonly defaultValue?: KernelEnvironmentVariablePrimitive<TType>;
+    readonly required?: TRequired;
+    readonly type: TType;
+}
+
+type KernelEnvironmentSchema = Readonly<Record<string, KernelEnvironmentVariableDefinition>>;
+
+type KernelEnvironmentValue = boolean | number | string;
+
+type KernelEnvironmentVariable<TDefinition extends KernelEnvironmentVariableDefinition> = TDefinition extends KernelEnvironmentVariableDefinition<infer TType extends KernelEnvironmentVariableType, infer TRequired extends boolean> ? TDefinition extends {
+    readonly defaultValue: unknown;
+} ? KernelEnvironmentVariablePrimitive<TType> : TRequired extends true ? KernelEnvironmentVariablePrimitive<TType> : KernelEnvironmentVariablePrimitive<TType> | undefined : never;
+
+type KernelEnvironment<TSchema extends KernelEnvironmentSchema> = {
+    readonly [key: string]: KernelEnvironmentValue | undefined;
+} & {
+    readonly [TKey in keyof TSchema]: KernelEnvironmentVariable<TSchema[TKey]>;
+};
+
+type KernelEnvironmentForSchema<TSchema extends KernelEnvironmentSchema | undefined> = TSchema extends KernelEnvironmentSchema ? KernelEnvironment<TSchema> : KernelDefaultEnvironment;
+
+interface KernelEnvironmentVariablesOptions<TSchema extends KernelEnvironmentSchema | undefined = undefined> {
     readonly override?: boolean;
     readonly path?: string;
+    readonly schema?: TSchema;
 }
 
-interface KernelOptions {
+interface KernelOptions<TEnvironmentSchema extends KernelEnvironmentSchema | undefined = undefined> {
     readonly di?: DependencyInjection;
+    readonly environmentSchema?: TEnvironmentSchema;
     readonly logger?: KernelLogger;
     readonly servicesYamlPath?: string;
     readonly sourceDirectory?: string;
 }
 
-declare class Kernel {
+declare class Kernel<TEnvironmentSchema extends KernelEnvironmentSchema | undefined = undefined> {
     private readonly options;
     private static readonly stateKey;
     private readonly consumerMiddlewares;
@@ -49,6 +79,7 @@ declare class Kernel {
     private readonly schedulersList;
     private readonly shutdownHooks;
     private dependencyInjectionInstance;
+    private environmentVariables;
     private static get state();
     static get configDirectory(): string;
     static get consumers(): Consumer[];
@@ -56,15 +87,20 @@ declare class Kernel {
     static get di(): DependencyInjection;
     static get environment(): NodeJS.ProcessEnv;
     static get logger(): KernelLogger;
-    static get active(): Kernel;
+    static get active(): Kernel<KernelEnvironmentSchema | undefined>;
     static get rootDirectory(): string;
     static get routes(): ServiceClass<Route>[];
     static get schedulers(): Scheduler[];
     static get sourceDirectory(): string;
     private static getActiveKernel;
+    private static assertRequiredEnvironmentVariable;
     private static getEnvironmentVariablesPath;
-    static loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions): DotenvConfigOutput;
-    constructor(options?: KernelOptions);
+    private static parseBooleanEnvironmentVariable;
+    private static parseNumberEnvironmentVariable;
+    private static parseEnvironmentVariable;
+    private static validateEnvironmentVariables;
+    static loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions<KernelEnvironmentSchema | undefined>): DotenvConfigOutput;
+    constructor(options?: KernelOptions<TEnvironmentSchema>);
     private closeCandidate;
     private getConsumerFromClass;
     private getInitializerFromClass;
@@ -73,13 +109,13 @@ declare class Kernel {
     get consumers(): Consumer[];
     get consumerMiddleware(): ConsumerMiddleware[];
     get di(): DependencyInjection;
-    get environment(): NodeJS.ProcessEnv;
+    get environment(): KernelEnvironmentForSchema<TEnvironmentSchema>;
     get logger(): KernelLogger;
     get routes(): ServiceClass<Route>[];
     get schedulers(): Scheduler[];
     private getDependencyInjectionOptions;
     dependencyInjection(options?: KernelDependencyInjectionOptions): Promise<void>;
-    loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions): DotenvConfigOutput;
+    loadEnvironmentVariables(environment?: string, options?: KernelEnvironmentVariablesOptions<KernelEnvironmentSchema | undefined>): DotenvConfigOutput;
     getRoutes(): ServiceClass<Route>[];
     registerConsumerMiddleware(...middlewares: ConsumerMiddleware[]): void;
     registerConsumers(...ClassDefinitions: ServiceClass<Consumer>[]): void;
@@ -98,7 +134,7 @@ declare class Kernel {
     runSchedulers(): Promise<void>;
     shutdown(): Promise<void>;
 }
-declare function createKernel(options?: KernelOptions): Kernel;
+declare function createKernel<TEnvironmentSchema extends KernelEnvironmentSchema | undefined = undefined>(options?: KernelOptions<TEnvironmentSchema>): Kernel<TEnvironmentSchema>;
 
 interface ConsumerExecutionContext {
     readonly causationId?: string;
@@ -106,7 +142,7 @@ interface ConsumerExecutionContext {
     readonly eventId: string;
     readonly eventName: string;
     readonly exchange: string;
-    readonly kernel: Kernel;
+    readonly kernel: Kernel<KernelEnvironmentSchema | undefined>;
     readonly metadata: Readonly<Record<string, unknown>>;
     readonly rawMessage?: unknown;
     readonly queueName: string;
@@ -120,4 +156,4 @@ interface ConsumerMiddleware {
 
 type ShutdownHook = () => Promise<void> | void;
 
-export { Consumer as C, Kernel as K, type ShutdownHook as S, type ConsumerExecutionContext as a, type ConsumerMiddleware as b, type ConsumerNext as c, type KernelDependencyInjectionOptions as d, type KernelEnvironmentVariablesOptions as e, type KernelOptions as f, createKernel as g };
+export { Consumer as C, Kernel as K, type ShutdownHook as S, type ConsumerExecutionContext as a, type ConsumerMiddleware as b, type ConsumerNext as c, type KernelDefaultEnvironment as d, type KernelDependencyInjectionOptions as e, type KernelEnvironment as f, type KernelEnvironmentForSchema as g, type KernelEnvironmentSchema as h, type KernelEnvironmentValue as i, type KernelEnvironmentVariableDefinition as j, type KernelEnvironmentVariablePrimitive as k, type KernelEnvironmentVariableType as l, type KernelEnvironmentVariablesOptions as m, type KernelOptions as n, createKernel as o };

package/dist/adapters/index.cjs

@@ -365,6 +365,14 @@ var DependencyInjection = class _DependencyInjection {
   }
 };
 
+// src/kernel/KernelEnvironmentValidationError.ts
+var KernelEnvironmentValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KernelEnvironmentValidationError";
+  }
+};
+
 // src/Kernel.ts
 var Kernel = class _Kernel {
   constructor(options = {}) {
@@ -384,6 +392,7 @@ var Kernel = class _Kernel {
   schedulersList = [];
   shutdownHooks = [];
   dependencyInjectionInstance;
+  environmentVariables = process.env;
   static get state() {
     const stateContainer = globalThis;
     stateContainer[_Kernel.stateKey] = stateContainer[_Kernel.stateKey] ?? {};
@@ -428,18 +437,82 @@ var Kernel = class _Kernel {
     }
     return _Kernel.state.activeKernel;
   }
+  static assertRequiredEnvironmentVariable(name, value, schema) {
+    if (schema[name]?.required === true && value === void 0) {
+      throw new KernelEnvironmentValidationError(
+        `Missing required environment variable "${name}".`
+      );
+    }
+  }
   static getEnvironmentVariablesPath(environment, options) {
     return import_node_path2.default.resolve(
       _Kernel.rootDirectory,
       options.path ?? (environment ? `.env.${environment}` : ".env")
     );
   }
+  static parseBooleanEnvironmentVariable(name, value) {
+    if (["1", "true", "yes", "on"].includes(value.toLowerCase())) {
+      return true;
+    }
+    if (["0", "false", "no", "off"].includes(value.toLowerCase())) {
+      return false;
+    }
+    throw new KernelEnvironmentValidationError(
+      `Environment variable "${name}" must be a boolean.`
+    );
+  }
+  static parseNumberEnvironmentVariable(name, value) {
+    if (value.trim() === "") {
+      throw new KernelEnvironmentValidationError(
+        `Environment variable "${name}" must be a number.`
+      );
+    }
+    const parsedValue = Number(value);
+    if (Number.isFinite(parsedValue)) {
+      return parsedValue;
+    }
+    throw new KernelEnvironmentValidationError(
+      `Environment variable "${name}" must be a number.`
+    );
+  }
+  static parseEnvironmentVariable(name, value, schema) {
+    const definition = schema[name];
+    if (definition.type === "boolean") {
+      return _Kernel.parseBooleanEnvironmentVariable(name, value);
+    }
+    if (definition.type === "number") {
+      return _Kernel.parseNumberEnvironmentVariable(name, value);
+    }
+    return value;
+  }
+  static validateEnvironmentVariables(schema) {
+    const environmentVariables = {};
+    for (const [name, definition] of Object.entries(schema)) {
+      const value = process.env[name] ?? definition.defaultValue?.toString();
+      _Kernel.assertRequiredEnvironmentVariable(name, value, schema);
+      if (value !== void 0) {
+        environmentVariables[name] = _Kernel.parseEnvironmentVariable(
+          name,
+          value,
+          schema
+        );
+      }
+    }
+    return {
+      ...process.env,
+      ...environmentVariables
+    };
+  }
   static loadEnvironmentVariables(environment, options = {}) {
     const environmentName = environment ?? process.env.NODE_ENV ?? "local";
-    return import_dotenv.default.config({
+    const result = import_dotenv.default.config({
       override: options.override,
       path: _Kernel.getEnvironmentVariablesPath(environmentName, options)
     });
+    if (options.schema) {
+      _Kernel.validateEnvironmentVariables(options.schema);
+    }
+    return result;
   }
   async closeCandidate(candidate) {
     if (candidate.shutdown) {
@@ -483,7 +556,7 @@ var Kernel = class _Kernel {
     return this.dependencyInjectionInstance;
   }
   get environment() {
-    return _Kernel.environment;
+    return this.environmentVariables;
   }
   get logger() {
     return this.loggerInstance;
@@ -511,7 +584,12 @@ var Kernel = class _Kernel {
     _Kernel.state.activeKernel = this;
   }
   loadEnvironmentVariables(environment, options = {}) {
-    return _Kernel.loadEnvironmentVariables(environment, options);
+    const result = _Kernel.loadEnvironmentVariables(environment, {
+      ...options,
+      schema: options.schema ?? this.options.environmentSchema
+    });
+    this.environmentVariables = this.options.environmentSchema ? _Kernel.validateEnvironmentVariables(this.options.environmentSchema) : process.env;
+    return result;
   }
   getRoutes() {
     return this.routes;