@pawells/nestjs-shared 1.0.0-dev.4c8c698

package/build/common/utils/lazy-getter.types.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @pawells/nestjs-shared - Lazy Module Ref Pattern Utilities
+ *
+ * This file provides type definitions and utilities for implementing the lazy ModuleRef
+ * dependency injection pattern. This pattern enables deferred dependency resolution,
+ * reducing constructor complexity and enabling circular dependency handling.
+ *
+ * @see {@link .claude/skills/lazy-module-ref-pattern.md} - Comprehensive pattern guide
+ */
+import { ModuleRef } from '@nestjs/core';
+/**
+ * Type for a lazy-loaded getter that retrieves a dependency from ModuleRef
+ *
+ * @template T - The type of dependency being retrieved
+ *
+ * @example
+ * ```typescript
+ * public get Logger(): AppLogger {
+ *     return this.Module.get(AppLogger);
+ * }
+ * ```
+ */
+export type LazyGetter<T> = () => T;
+/**
+ * Type for an optional lazy-loaded getter that may return undefined
+ *
+ * @template T - The type of dependency being retrieved
+ *
+ * @example
+ * ```typescript
+ * public get OptionalConfig(): ConfigService | undefined {
+ *     try {
+ *         return this.Module.get(ConfigService, { strict: false });
+ *     } catch {
+ *         return undefined;
+ *     }
+ * }
+ * ```
+ */
+export type OptionalLazyGetter<T> = () => T | undefined;
+/**
+ * Type for a lazy-loaded getter using a string-based injection token
+ *
+ * @template T - The type of dependency being retrieved
+ *
+ * @example
+ * ```typescript
+ * public get PubSub(): PubSub {
+ *     return this.Module.get('PUB_SUB');
+ * }
+ * ```
+ */
+export type TokenLazyGetter<T> = (token: string) => T;
+/**
+ * Interface for a service using lazy ModuleRef pattern
+ *
+ * Services implementing this pattern should have ModuleRef as their only
+ * constructor dependency and provide typed getters for accessing other services.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class ExampleService implements LazyModuleRefService {
+ *     constructor(public readonly Module: ModuleRef) {}
+ *
+ *     public get SomeService(): SomeServiceType {
+ *         return this.Module.get(SomeServiceType);
+ *     }
+ * }
+ * ```
+ */
+export interface LazyModuleRefService {
+    /**
+     * The ModuleRef instance for lazy dependency resolution
+     * This should be the ONLY injected dependency
+     */
+    Module: ModuleRef;
+}
+/**
+ * Utility type to extract dependencies from a service with lazy getters
+ *
+ * Maps getter names to their return types for documentation and type inference.
+ *
+ * @template S - The service type with lazy getters
+ *
+ * @example
+ * ```typescript
+ * type AuthServiceDeps = LazyGetterDependencies<AuthService>;
+ * // Results in: { Config: ConfigService, Logger: AppLogger }
+ * ```
+ */
+export type LazyGetterDependencies<S> = {
+    [K in keyof S as S[K] extends LazyGetter<any> ? K : never]: S[K] extends LazyGetter<infer T> ? T : never;
+};
+/**
+ * Configuration for optional dependency resolution
+ * Used when a service may not be registered in the module
+ */
+export interface OptionalGetterConfig {
+    /**
+     * Set to false to return undefined instead of throwing if not found
+     * @default true
+     */
+    strict?: boolean;
+}
+/**
+ * Utility function to create a memoized lazy getter
+ * Caches the resolved dependency to avoid repeated lookups
+ *
+ * @template T - The type of dependency
+ * @param getterFn - Function that retrieves the dependency
+ * @returns A memoized getter function
+ *
+ * @example
+ * ```typescript
+ * private _cachedService: ServiceType | undefined;
+ *
+ * public get Service(): ServiceType {
+ *     if (!this._cachedService) {
+ *         this._cachedService = this.Module.get(ServiceType);
+ *     }
+ *     return this._cachedService;
+ * }
+ * ```
+ */
+export declare function CreateMemoizedLazyGetter<T>(getterFn: () => T): () => T;
+/**
+ * Utility function to create a lazy getter with error handling for optional dependencies
+ *
+ * @template T - The type of dependency
+ * @param module - The ModuleRef instance
+ * @param token - The dependency token
+ * @param config - Optional configuration
+ * @returns The dependency or undefined
+ *
+ * @example
+ * ```typescript
+ * public get OptionalService(): ServiceType | undefined {
+ *     return createOptionalLazyGetter(this.Module, ServiceType);
+ * }
+ * ```
+ */
+export declare function CreateOptionalLazyGetter<T>(module: ModuleRef, token: string | Function, config?: OptionalGetterConfig): T | undefined;
+/**
+ * Type guard to check if a value is a LazyModuleRefService
+ *
+ * @param value - The value to check
+ * @returns True if the value has a Module property of type ModuleRef
+ *
+ * @example
+ * ```typescript
+ * if (isLazyModuleRefService(service)) {
+ *     // service.Module is available
+ * }
+ * ```
+ */
+export declare function IsLazyModuleRefService(value: any): value is LazyModuleRefService;
+/**
+ * Pattern naming convention constants
+ * Use these as documentation helpers for your lazy getter implementations
+ */
+export declare const LazyGetterNamingConventions: {
+    /**
+     * Getter names should use PascalCase matching the service/type name
+     * Examples: Config, Logger, CacheService, OrderModel
+     */
+    NAMING_PATTERN: string;
+    /**
+     * Getter names should NOT include 'get' prefix or 'Service' suffix if redundant
+     * Example: public get Config() NOT public get getConfigService()
+     */
+    AVOID_REDUNDANCY: boolean;
+    /**
+     * For Mongoose models, use PascalCase + 'Model' suffix
+     * Example: public get OrderModel()
+     */
+    MODEL_SUFFIX: string;
+    /**
+     * For string-based tokens, use meaningful names representing the service
+     * Example: public get PubSub() for 'PUB_SUB' token
+     */
+    TOKEN_MAPPING: string;
+};
+/**
+ * Backwards compatibility aliases - exported functions use PascalCase per project conventions
+ */
+export declare const createMemoizedLazyGetter: typeof CreateMemoizedLazyGetter;
+export declare const createOptionalLazyGetter: typeof CreateOptionalLazyGetter;
+export declare const isLazyModuleRefService: typeof IsLazyModuleRefService;
+//# sourceMappingURL=lazy-getter.types.d.ts.map

package/build/common/utils/lazy-getter.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-getter.types.d.ts","sourceRoot":"","sources":["../../../src/common/utils/lazy-getter.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,MAAM,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI;KACtC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GACzF,CAAC,GACD,KAAK;CACR,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACzC,QAAQ,EAAE,MAAM,CAAC,GACf,MAAM,CAAC,CAWT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACzC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GAAG,QAAQ,EACxB,MAAM,CAAC,EAAE,oBAAoB,GAC3B,CAAC,GAAG,SAAS,CAMf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,oBAAoB,CAEhF;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B;IACvC;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;CAEH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB,iCAA2B,CAAC;AACjE,eAAO,MAAM,wBAAwB,iCAA2B,CAAC;AACjE,eAAO,MAAM,sBAAsB,+BAAyB,CAAC"}

package/build/common/utils/lazy-getter.types.js

@@ -0,0 +1,114 @@
+/**
+ * @pawells/nestjs-shared - Lazy Module Ref Pattern Utilities
+ *
+ * This file provides type definitions and utilities for implementing the lazy ModuleRef
+ * dependency injection pattern. This pattern enables deferred dependency resolution,
+ * reducing constructor complexity and enabling circular dependency handling.
+ *
+ * @see {@link .claude/skills/lazy-module-ref-pattern.md} - Comprehensive pattern guide
+ */
+import { ModuleRef } from '@nestjs/core';
+/**
+ * Utility function to create a memoized lazy getter
+ * Caches the resolved dependency to avoid repeated lookups
+ *
+ * @template T - The type of dependency
+ * @param getterFn - Function that retrieves the dependency
+ * @returns A memoized getter function
+ *
+ * @example
+ * ```typescript
+ * private _cachedService: ServiceType | undefined;
+ *
+ * public get Service(): ServiceType {
+ *     if (!this._cachedService) {
+ *         this._cachedService = this.Module.get(ServiceType);
+ *     }
+ *     return this._cachedService;
+ * }
+ * ```
+ */
+export function CreateMemoizedLazyGetter(getterFn) {
+    let cached;
+    let initialized = false;
+    return () => {
+        if (!initialized) {
+            cached = getterFn();
+            initialized = true;
+        }
+        return cached;
+    };
+}
+/**
+ * Utility function to create a lazy getter with error handling for optional dependencies
+ *
+ * @template T - The type of dependency
+ * @param module - The ModuleRef instance
+ * @param token - The dependency token
+ * @param config - Optional configuration
+ * @returns The dependency or undefined
+ *
+ * @example
+ * ```typescript
+ * public get OptionalService(): ServiceType | undefined {
+ *     return createOptionalLazyGetter(this.Module, ServiceType);
+ * }
+ * ```
+ */
+export function CreateOptionalLazyGetter(module, token, config) {
+    try {
+        return module.get(token, { strict: config?.strict ?? true });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Type guard to check if a value is a LazyModuleRefService
+ *
+ * @param value - The value to check
+ * @returns True if the value has a Module property of type ModuleRef
+ *
+ * @example
+ * ```typescript
+ * if (isLazyModuleRefService(service)) {
+ *     // service.Module is available
+ * }
+ * ```
+ */
+export function IsLazyModuleRefService(value) {
+    return !!(value && typeof value === 'object' && 'Module' in value && value.Module instanceof ModuleRef);
+}
+/**
+ * Pattern naming convention constants
+ * Use these as documentation helpers for your lazy getter implementations
+ */
+export const LazyGetterNamingConventions = {
+    /**
+     * Getter names should use PascalCase matching the service/type name
+     * Examples: Config, Logger, CacheService, OrderModel
+     */
+    NAMING_PATTERN: 'PascalCase (matching service/type name)',
+    /**
+     * Getter names should NOT include 'get' prefix or 'Service' suffix if redundant
+     * Example: public get Config() NOT public get getConfigService()
+     */
+    AVOID_REDUNDANCY: true,
+    /**
+     * For Mongoose models, use PascalCase + 'Model' suffix
+     * Example: public get OrderModel()
+     */
+    MODEL_SUFFIX: 'Model',
+    /**
+     * For string-based tokens, use meaningful names representing the service
+     * Example: public get PubSub() for 'PUB_SUB' token
+     */
+    TOKEN_MAPPING: 'Meaningful name for token string',
+};
+/**
+ * Backwards compatibility aliases - exported functions use PascalCase per project conventions
+ */
+export const createMemoizedLazyGetter = CreateMemoizedLazyGetter;
+export const createOptionalLazyGetter = CreateOptionalLazyGetter;
+export const isLazyModuleRefService = IsLazyModuleRefService;
+//# sourceMappingURL=lazy-getter.types.js.map

package/build/common/utils/lazy-getter.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-getter.types.js","sourceRoot":"","sources":["../../../src/common/utils/lazy-getter.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAyGzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,wBAAwB,CACvC,QAAiB;IAEjB,IAAI,MAAqB,CAAC;IAC1B,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,OAAO,GAAG,EAAE;QACX,IAAI,CAAC,WAAW,EAAE,CAAC;YAClB,MAAM,GAAG,QAAQ,EAAE,CAAC;YACpB,WAAW,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,OAAO,MAAW,CAAC;IACpB,CAAC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CACvC,MAAiB,EACjB,KAAwB,EACxB,MAA6B;IAE7B,IAAI,CAAC;QACJ,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAU;IAChD,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,YAAY,SAAS,CAAC,CAAC;AACzG,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IAC1C;;;OAGG;IACH,cAAc,EAAE,yCAAyC;IAEzD;;;OAGG;IACH,gBAAgB,EAAE,IAAI;IAEtB;;;OAGG;IACH,YAAY,EAAE,OAAO;IAErB;;;OAGG;IACH,aAAa,EAAE,kCAAkC;CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,wBAAwB,CAAC;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,wBAAwB,CAAC;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC"}

package/build/common/utils/module.utils.d.ts

@@ -0,0 +1,33 @@
+import type { InjectionToken, OptionalFactoryDependency, Provider, Type } from '@nestjs/common';
+/**
+ * Generic shape for forRootAsync() options.
+ *
+ * F is the factory interface (e.g. NatsOptionsFactory, QdrantModuleOptionsFactory).
+ * T is the resolved options type.
+ */
+export interface AsyncModuleOptions<T, F = unknown> {
+    useFactory?: (...args: unknown[]) => T | Promise<T>;
+    useClass?: Type<F>;
+    useExisting?: Type<F>;
+    inject?: Array<InjectionToken | OptionalFactoryDependency>;
+}
+/**
+ * Creates the single async options provider (the injection-token → resolved-options
+ * mapping) for a forRootAsync() module.
+ *
+ * @param options    The async options passed to forRootAsync()
+ * @param token      Injection token to provide the resolved options under
+ * @param factoryFn  Calls the factory method on the options-factory instance,
+ *                   e.g. `(f) => f.createNatsOptions()`
+ */
+export declare function createAsyncOptionsProvider<T, F>(options: AsyncModuleOptions<T, F>, token: InjectionToken, factoryFn: (factory: F) => T | Promise<T>): Provider<T>;
+/**
+ * Creates the full provider array for a forRootAsync() module — the options
+ * provider plus an optional self-binding for useClass.
+ *
+ * @param options    The async options passed to forRootAsync()
+ * @param token      Injection token to provide the resolved options under
+ * @param factoryFn  Calls the factory method on the options-factory instance
+ */
+export declare function createAsyncProviders<T, F>(options: AsyncModuleOptions<T, F>, token: InjectionToken, factoryFn: (factory: F) => T | Promise<T>): Provider[];
+//# sourceMappingURL=module.utils.d.ts.map

package/build/common/utils/module.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.utils.d.ts","sourceRoot":"","sources":["../../../src/common/utils/module.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,yBAAyB,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO;IACjD,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,WAAW,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,CAAC,EAAE,KAAK,CAAC,cAAc,GAAG,yBAAyB,CAAC,CAAC;CAC3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,CAAC,EAC9C,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EACjC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvC,QAAQ,CAAC,CAAC,CAAC,CAmBb;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EACxC,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EACjC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvC,QAAQ,EAAE,CAaZ"}

package/build/common/utils/module.utils.js

@@ -0,0 +1,48 @@
+/**
+ * Creates the single async options provider (the injection-token → resolved-options
+ * mapping) for a forRootAsync() module.
+ *
+ * @param options    The async options passed to forRootAsync()
+ * @param token      Injection token to provide the resolved options under
+ * @param factoryFn  Calls the factory method on the options-factory instance,
+ *                   e.g. `(f) => f.createNatsOptions()`
+ */
+export function createAsyncOptionsProvider(options, token, factoryFn) {
+    if (options.useFactory !== undefined) {
+        return {
+            provide: token,
+            useFactory: options.useFactory,
+            inject: (options.inject ?? []),
+        };
+    }
+    const factoryToken = options.useExisting ?? options.useClass;
+    if (factoryToken === undefined) {
+        throw new Error('Invalid async module options: must specify useFactory, useClass, or useExisting.');
+    }
+    return {
+        provide: token,
+        useFactory: factoryFn,
+        inject: [factoryToken],
+    };
+}
+/**
+ * Creates the full provider array for a forRootAsync() module — the options
+ * provider plus an optional self-binding for useClass.
+ *
+ * @param options    The async options passed to forRootAsync()
+ * @param token      Injection token to provide the resolved options under
+ * @param factoryFn  Calls the factory method on the options-factory instance
+ */
+export function createAsyncProviders(options, token, factoryFn) {
+    if (options.useExisting !== undefined || options.useFactory !== undefined) {
+        return [createAsyncOptionsProvider(options, token, factoryFn)];
+    }
+    if (options.useClass !== undefined) {
+        return [
+            createAsyncOptionsProvider(options, token, factoryFn),
+            { provide: options.useClass, useClass: options.useClass },
+        ];
+    }
+    throw new Error('Invalid async module options: must specify useFactory, useClass, or useExisting.');
+}
+//# sourceMappingURL=module.utils.js.map

package/build/common/utils/module.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.utils.js","sourceRoot":"","sources":["../../../src/common/utils/module.utils.ts"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACzC,OAAiC,EACjC,KAAqB,EACrB,SAAyC;IAEzC,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO;YACN,OAAO,EAAE,KAAK;YACd,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,MAAM,EAAE,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAsD;SACnF,CAAC;IACH,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAC7D,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACd,kFAAkF,CAClF,CAAC;IACH,CAAC;IACD,OAAO;QACN,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,SAAS;QACrB,MAAM,EAAE,CAAC,YAAY,CAAC;KACtB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CACnC,OAAiC,EACjC,KAAqB,EACrB,SAAyC;IAEzC,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAC3E,OAAO,CAAC,0BAA0B,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO;YACN,0BAA0B,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC;YACrD,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE;SACzD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACd,kFAAkF,CAClF,CAAC;AACH,CAAC"}

package/build/common/utils/sanitization.utils.d.ts

@@ -0,0 +1,69 @@
+import { Logger } from '@nestjs/common';
+/**
+ * Maximum recursion depth for sanitization operations.
+ * Prevents stack overflow attacks and infinite loops on circular references.
+ */
+export declare const MAX_SANITIZE_DEPTH = 20;
+/**
+ * Escapes newline characters and other special characters that could be used for log injection attacks.
+ * Replaces newlines with \n literal strings to prevent log forging where an attacker might inject
+ * a newline to create fake log entries.
+ *
+ * @param str The string to escape
+ * @returns String with newlines and carriage returns escaped
+ *
+ * @example
+ * ```typescript
+ * escapeNewlines('Hello\nWorld') // Returns: 'Hello\\nWorld'
+ * escapeNewlines('foo\rbar') // Returns: 'foo\\rbar'
+ * ```
+ */
+export declare function escapeNewlines(str: string): string;
+/**
+ * Recursively sanitizes object keys to prevent MongoDB injection attacks.
+ * This function only sanitizes keys (property names), not values, to prevent
+ * destruction of legitimate data like email addresses or S3 paths.
+ *
+ * CRITICAL: This function must be applied to the complete root request object.
+ * Extracting a sub-object and passing it separately bypasses sanitization for
+ * parent levels. Always sanitize at the entry point (request body, params, query).
+ *
+ * Behavior at max depth: Throws an error to prevent bypass of sanitization.
+ * A highly nested object may indicate an attack or data structure issue.
+ *
+ * @param value The value to sanitize (keys only)
+ * @param depth Current recursion depth (internal use)
+ * @param logger Optional logger instance for warnings
+ * @returns Sanitized value with dangerous characters in keys replaced
+ * @throws Error if maximum sanitization depth is exceeded
+ *
+ * @example
+ * ```typescript
+ * // CORRECT: Sanitize at entry point
+ * app.use((req, res, next) => {
+ *   req.body = sanitizeObject(req.body);
+ *   next();
+ * });
+ *
+ * // WRONG: Don't extract sub-object and sanitize separately
+ * const user = sanitizeObject(req.body.user); // Misses req.body itself
+ *
+ * // CORRECT: Sanitize complete object first
+ * const sanitized = sanitizeObject(req.body);
+ * const user = sanitized.user; // Now safe
+ * ```
+ */
+export declare function sanitizeObject(value: any, depth?: number, logger?: Logger): any;
+/**
+ * Recursively sanitizes object values to prevent XSS attacks.
+ * Strips dangerous HTML tags, JavaScript event handlers, and protocol handlers
+ * from string values while preserving legitimate data.
+ *
+ * Uses the xss library for server-side HTML string sanitization.
+ *
+ * @param value The value to sanitize (strings and nested objects)
+ * @param logger Optional logger instance for warnings
+ * @returns Sanitized value with XSS vectors removed
+ */
+export declare function sanitizeXss(value: unknown, logger?: Logger): unknown;
+//# sourceMappingURL=sanitization.utils.d.ts.map

package/build/common/utils/sanitization.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitization.utils.d.ts","sourceRoot":"","sources":["../../../src/common/utils/sanitization.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAIxC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQlD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,GAAE,MAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,CAyClF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAqCpE"}

package/build/common/utils/sanitization.utils.js

@@ -0,0 +1,141 @@
+import xss from 'xss';
+import { getErrorMessage } from './error.utils.js';
+/**
+ * Maximum recursion depth for sanitization operations.
+ * Prevents stack overflow attacks and infinite loops on circular references.
+ */
+export const MAX_SANITIZE_DEPTH = 20;
+/**
+ * Escapes newline characters and other special characters that could be used for log injection attacks.
+ * Replaces newlines with \n literal strings to prevent log forging where an attacker might inject
+ * a newline to create fake log entries.
+ *
+ * @param str The string to escape
+ * @returns String with newlines and carriage returns escaped
+ *
+ * @example
+ * ```typescript
+ * escapeNewlines('Hello\nWorld') // Returns: 'Hello\\nWorld'
+ * escapeNewlines('foo\rbar') // Returns: 'foo\\rbar'
+ * ```
+ */
+export function escapeNewlines(str) {
+    if (typeof str !== 'string') {
+        return String(str);
+    }
+    return str
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+}
+/**
+ * Recursively sanitizes object keys to prevent MongoDB injection attacks.
+ * This function only sanitizes keys (property names), not values, to prevent
+ * destruction of legitimate data like email addresses or S3 paths.
+ *
+ * CRITICAL: This function must be applied to the complete root request object.
+ * Extracting a sub-object and passing it separately bypasses sanitization for
+ * parent levels. Always sanitize at the entry point (request body, params, query).
+ *
+ * Behavior at max depth: Throws an error to prevent bypass of sanitization.
+ * A highly nested object may indicate an attack or data structure issue.
+ *
+ * @param value The value to sanitize (keys only)
+ * @param depth Current recursion depth (internal use)
+ * @param logger Optional logger instance for warnings
+ * @returns Sanitized value with dangerous characters in keys replaced
+ * @throws Error if maximum sanitization depth is exceeded
+ *
+ * @example
+ * ```typescript
+ * // CORRECT: Sanitize at entry point
+ * app.use((req, res, next) => {
+ *   req.body = sanitizeObject(req.body);
+ *   next();
+ * });
+ *
+ * // WRONG: Don't extract sub-object and sanitize separately
+ * const user = sanitizeObject(req.body.user); // Misses req.body itself
+ *
+ * // CORRECT: Sanitize complete object first
+ * const sanitized = sanitizeObject(req.body);
+ * const user = sanitized.user; // Now safe
+ * ```
+ */
+export function sanitizeObject(value, depth = 0, logger) {
+    if (depth >= MAX_SANITIZE_DEPTH) {
+        if (logger) {
+            logger.error(`Sanitization depth limit exceeded at depth ${MAX_SANITIZE_DEPTH}`);
+        }
+        throw new Error(`Input object exceeds maximum sanitization depth of ${MAX_SANITIZE_DEPTH}. Deeply nested objects may be malicious.`);
+    }
+    if (typeof value === 'object' && value !== null) {
+        if (Array.isArray(value)) {
+            return value.map(item => sanitizeObject(item, depth + 1, logger));
+        }
+        const sanitized = {};
+        for (const [key, val] of Object.entries(value)) {
+            // Sanitize keys to prevent MongoDB operator injection
+            // MongoDB operators start with '$', and command expressions with 'eval', 'function', etc.
+            // Replace dangerous key patterns: $ at start, eval, function in keys
+            let sanitizedKey = key;
+            // Prevent MongoDB operators (e.g., $where, $regex, etc.)
+            if (sanitizedKey.startsWith('$')) {
+                sanitizedKey = '_' + sanitizedKey.slice(1);
+            }
+            // Prevent arbitrary code execution patterns in key names
+            const dangerousKeyPatterns = ['eval', 'function', '__proto__', 'constructor', 'prototype'];
+            for (const pattern of dangerousKeyPatterns) {
+                if (sanitizedKey.toLowerCase().includes(pattern)) {
+                    sanitizedKey = sanitizedKey.replace(new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi'), '_redacted_');
+                }
+            }
+            // Recursively sanitize nested objects/arrays, but preserve string values
+            sanitized[sanitizedKey] = typeof val === 'object' ? sanitizeObject(val, depth + 1, logger) : val;
+        }
+        return sanitized;
+    }
+    return value;
+}
+/**
+ * Recursively sanitizes object values to prevent XSS attacks.
+ * Strips dangerous HTML tags, JavaScript event handlers, and protocol handlers
+ * from string values while preserving legitimate data.
+ *
+ * Uses the xss library for server-side HTML string sanitization.
+ *
+ * @param value The value to sanitize (strings and nested objects)
+ * @param logger Optional logger instance for warnings
+ * @returns Sanitized value with XSS vectors removed
+ */
+export function sanitizeXss(value, logger) {
+    if (typeof value === 'string') {
+        // Use xss library for server-side HTML string sanitization
+        // Removes common XSS patterns: script tags, event handlers, dangerous protocols
+        // Static import ensures dependency is resolved at module load time and fails fast if missing
+        let sanitized = value;
+        try {
+            // xss is statically imported at module top to ensure TypeScript and bundlers
+            // can properly resolve the dependency at build time
+            sanitized = xss(sanitized);
+        }
+        catch (error) {
+            if (logger) {
+                logger.warn(`XSS sanitization (xss library) failed: ${getErrorMessage(error)}`);
+            }
+        }
+        // Final protocol stripping as defense-in-depth
+        sanitized = sanitized
+            .replace(/javascript:/gi, '')
+            .replace(/vbscript:/gi, '');
+        return sanitized;
+    }
+    if (Array.isArray(value)) {
+        return value.map(v => sanitizeXss(v, logger));
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, sanitizeXss(v, logger)]));
+    }
+    return value;
+}
+//# sourceMappingURL=sanitization.utils.js.map

package/build/common/utils/sanitization.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitization.utils.js","sourceRoot":"","sources":["../../../src/common/utils/sanitization.utils.ts"],"names":[],"mappings":"AACA,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,GAAG;SACR,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,cAAc,CAAC,KAAU,EAAE,QAAgB,CAAC,EAAE,MAAe;IAC5E,IAAI,KAAK,IAAI,kBAAkB,EAAE,CAAC;QACjC,IAAI,MAAM,EAAE,CAAC;YACZ,MAAM,CAAC,KAAK,CAAC,8CAA8C,kBAAkB,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,sDAAsD,kBAAkB,2CAA2C,CAAC,CAAC;IACtI,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,SAAS,GAAQ,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChD,sDAAsD;YACtD,0FAA0F;YAC1F,qEAAqE;YACrE,IAAI,YAAY,GAAG,GAAG,CAAC;YAEvB,yDAAyD;YACzD,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,YAAY,GAAG,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC5C,CAAC;YAED,yDAAyD;YACzD,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;YAC3F,KAAK,MAAM,OAAO,IAAI,oBAAoB,EAAE,CAAC;gBAC5C,IAAI,YAAY,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;oBAClD,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC;gBACrH,CAAC;YACF,CAAC;YAED,yEAAyE;YACzE,SAAS,CAAC,YAAY,CAAC,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QAClG,CAAC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,MAAe;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,2DAA2D;QAC3D,gFAAgF;QAChF,6FAA6F;QAE7F,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,IAAI,CAAC;YACJ,6EAA6E;YAC7E,oDAAoD;YACpD,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC,0CAA0C,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjF,CAAC;QACF,CAAC;QAED,+CAA+C;QAC/C,SAAS,GAAG,SAAS;aACnB,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;aAC5B,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QAE7B,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,MAAM,CAAC,WAAW,CACxB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAClE,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC"}

package/build/config/config.module.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration Module.
+ * Provides configuration services with environment variable access, validation, and logging.
+ * MUST be imported before CommonModule in your application.
+ *
+ * Exports:
+ * - ConfigService: Typed configuration accessor
+ * - ValidationService: Configuration validation utilities
+ *
+ * @remarks
+ * - ConfigService is required by CommonModule and other @pawells packages
+ * - Initializes logging for configuration operations
+ * - Import order critical: ConfigModule must come BEFORE CommonModule
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [
+ *     ConfigModule,              // FIRST
+ *     CommonModule,              // SECOND (depends on ConfigModule)
+ *     MetricsModule.forRoot(),
+ *     // ... other modules
+ *   ]
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class ConfigModule {
+}
+//# sourceMappingURL=config.module.d.ts.map

package/build/config/config.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.module.d.ts","sourceRoot":"","sources":["../../src/config/config.module.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qBAOa,YAAY;CAAG"}