@pawells/nestjs-shared 1.0.0-dev.3052c75

package/build/common/decorators/instrument.decorator.js

@@ -0,0 +1,165 @@
+import { performance } from 'node:perf_hooks';
+/**
+ * Module-level singleton holder for InstrumentationRegistry.
+ *
+ * The @Instrument() decorator uses this holder to access the registry
+ * without requiring direct DI into every decorated method.
+ *
+ * Set during application bootstrap by CommonModule.onModuleInit().
+ *
+ * @example
+ * ```typescript
+ * // In CommonModule.onModuleInit()
+ * InstrumentationRegistryHolder.setInstance(this.registry);
+ * ```
+ */
+export class InstrumentationRegistryHolder {
+    /**
+     * Singleton instance of InstrumentationRegistry
+     * @private
+     */
+    static instance = null;
+    /**
+     * Set the singleton instance.
+     * Called during application bootstrap.
+     *
+     * @param registry - The InstrumentationRegistry instance
+     */
+    static setInstance(registry) {
+        InstrumentationRegistryHolder.instance = registry;
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The InstrumentationRegistry instance, or null if not yet set
+     */
+    static getInstance() {
+        return InstrumentationRegistryHolder.instance;
+    }
+}
+/**
+ * Method decorator for automatic metrics instrumentation.
+ *
+ * Automatically records method timing (histogram), success counters, and error counters
+ * using the InstrumentationRegistry. Metric descriptors are auto-registered on first use.
+ *
+ * Supports both synchronous and asynchronous (Promise-returning) methods.
+ *
+ * @param options - Instrumentation configuration (timing, counters, errorCounters, labels)
+ * @returns MethodDecorator
+ *
+ * @throws Error if a metric name is not registered (only if registry is available)
+ * @throws The original error if the decorated method throws/rejects
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Instrument({
+ *     timing: 'user_service_create_duration_seconds',
+ *     counters: ['user_service_create_total'],
+ *     errorCounters: ['user_service_create_errors'],
+ *     labels: { service: 'user' },
+ *   })
+ *   async create(userData: CreateUserDto): Promise<User> {
+ *     return this.repository.save(userData);
+ *   }
+ *
+ *   @Instrument({
+ *     timing: 'user_service_find_by_id_duration_seconds',
+ *     counters: ['user_service_find_by_id_total'],
+ *     errorCounters: ['user_service_find_by_id_errors'],
+ *     labels: (id: string) => ({ userId: id }),
+ *   })
+ *   async findById(id: string): Promise<User | null> {
+ *     return this.repository.findOne(id);
+ *   }
+ * }
+ * ```
+ */
+export function Instrument(options) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        descriptor.value = function instrumentMethod(...args) {
+            // Resolve labels: static object or computed from arguments
+            const labels = typeof options.labels === 'function'
+                ? options.labels(...args)
+                : options.labels ?? {};
+            // Get registry from singleton holder
+            const registry = InstrumentationRegistryHolder.getInstance();
+            // If registry not available (e.g., during early bootstrap), just call original
+            if (!registry) {
+                return originalMethod.apply(this, args);
+            }
+            // Auto-register metric descriptors on first invocation
+            if (options.timing) {
+                registry.registerDescriptor({
+                    name: options.timing,
+                    type: 'histogram',
+                    help: `Duration of ${String(propertyKey)}`,
+                    labelNames: Object.keys(labels),
+                    unit: 'seconds',
+                });
+            }
+            for (const counterName of options.counters ?? []) {
+                registry.registerDescriptor({
+                    name: counterName,
+                    type: 'counter',
+                    help: `${String(propertyKey)} invocation count`,
+                    labelNames: Object.keys(labels),
+                });
+            }
+            for (const errorCounterName of options.errorCounters ?? []) {
+                registry.registerDescriptor({
+                    name: errorCounterName,
+                    type: 'counter',
+                    help: `${String(propertyKey)} error count`,
+                    labelNames: Object.keys(labels),
+                });
+            }
+            // Record start time
+            const startTime = performance.now();
+            /**
+             * Handle successful completion.
+             * Records timing and success counters.
+             */
+            const handleSuccess = () => {
+                // eslint-disable-next-line no-magic-numbers
+                const durationSeconds = (performance.now() - startTime) / 1000; // Convert to seconds
+                if (options.timing) {
+                    registry.recordMetric(options.timing, durationSeconds, labels);
+                }
+                for (const counterName of options.counters ?? []) {
+                    registry.recordMetric(counterName, 1, labels);
+                }
+            };
+            /**
+             * Handle error.
+             * Records error counters and rethrows the error.
+             */
+            const handleError = (err) => {
+                for (const errorCounterName of options.errorCounters ?? []) {
+                    registry.recordMetric(errorCounterName, 1, labels);
+                }
+                throw err; // Always rethrow original error
+            };
+            try {
+                const result = originalMethod.apply(this, args);
+                // Check if result is a Promise (async method)
+                if (result instanceof Promise) {
+                    return result.then((value) => {
+                        handleSuccess();
+                        return value;
+                    }, (err) => handleError(err));
+                }
+                // Synchronous method
+                handleSuccess();
+                return result;
+            }
+            catch (err) {
+                return handleError(err);
+            }
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=instrument.decorator.js.map

package/build/common/decorators/instrument.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.decorator.js","sourceRoot":"","sources":["../../../src/common/decorators/instrument.decorator.ts"],"names":[],"mappings":"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"}

package/build/common/decorators/metric.decorators.d.ts

@@ -0,0 +1,42 @@
+import { Counter, Gauge, Histogram, Summary } from 'prom-client';
+/**
+ * Metric decorators for easy injection of Prometheus metrics
+ */
+/**
+ * Inject a Counter metric
+ */
+export declare const InjectCounter: (name: string) => ParameterDecorator;
+/**
+ * Inject a Gauge metric
+ */
+export declare const InjectGauge: (name: string) => ParameterDecorator;
+/**
+ * Inject a Histogram metric
+ */
+export declare const InjectHistogram: (name: string) => ParameterDecorator;
+/**
+ * Inject a Summary metric
+ */
+export declare const InjectSummary: (name: string) => ParameterDecorator;
+/**
+ * Metric creation utilities
+ */
+export declare class MetricFactory {
+    /**
+     * Create a counter metric
+     */
+    static createCounter(name: string, help: string, labelNames?: string[]): Counter<string>;
+    /**
+     * Create a gauge metric
+     */
+    static createGauge(name: string, help: string, labelNames?: string[]): Gauge<string>;
+    /**
+     * Create a histogram metric
+     */
+    static createHistogram(name: string, help: string, labelNames?: string[], buckets?: number[]): Histogram<string>;
+    /**
+     * Create a summary metric
+     */
+    static createSummary(name: string, help: string, labelNames?: string[], percentiles?: number[]): Summary<string>;
+}
+//# sourceMappingURL=metric.decorators.d.ts.map

package/build/common/decorators/metric.decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.decorators.d.ts","sourceRoot":"","sources":["../../../src/common/decorators/metric.decorators.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEjE;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,kBAA2D,CAAC;AAEzG;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,kBAAyD,CAAC;AAErG;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,kBAA6D,CAAC;AAE7G;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,kBAA2D,CAAC;AAEzG;;GAEG;AACH,qBAAa,aAAa;IACzB;;OAEG;WACW,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAW/F;;OAEG;WACW,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;IAW3F;;OAEG;WACW,eAAe,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,OAAO,CAAC,EAAE,MAAM,EAAE,GAChB,SAAS,CAAC,MAAM,CAAC;IAcpB;;OAEG;WACW,aAAa,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,WAAW,CAAC,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,MAAM,CAAC;CAalB"}

package/build/common/decorators/metric.decorators.js

@@ -0,0 +1,85 @@
+import { Inject } from '@nestjs/common';
+import { Counter, Gauge, Histogram, Summary } from 'prom-client';
+/**
+ * Metric decorators for easy injection of Prometheus metrics
+ */
+/**
+ * Inject a Counter metric
+ */
+export const InjectCounter = (name) => Inject(`PROM_METRIC_COUNTER_${name}`);
+/**
+ * Inject a Gauge metric
+ */
+export const InjectGauge = (name) => Inject(`PROM_METRIC_GAUGE_${name}`);
+/**
+ * Inject a Histogram metric
+ */
+export const InjectHistogram = (name) => Inject(`PROM_METRIC_HISTOGRAM_${name}`);
+/**
+ * Inject a Summary metric
+ */
+export const InjectSummary = (name) => Inject(`PROM_METRIC_SUMMARY_${name}`);
+/**
+ * Metric creation utilities
+ */
+export class MetricFactory {
+    /**
+     * Create a counter metric
+     */
+    static createCounter(name, help, labelNames) {
+        const config = {
+            name,
+            help,
+        };
+        if (labelNames !== undefined) {
+            config.labelNames = labelNames;
+        }
+        return new Counter(config);
+    }
+    /**
+     * Create a gauge metric
+     */
+    static createGauge(name, help, labelNames) {
+        const config = {
+            name,
+            help,
+        };
+        if (labelNames !== undefined) {
+            config.labelNames = labelNames;
+        }
+        return new Gauge(config);
+    }
+    /**
+     * Create a histogram metric
+     */
+    static createHistogram(name, help, labelNames, buckets) {
+        const config = {
+            name,
+            help,
+        };
+        if (labelNames !== undefined) {
+            config.labelNames = labelNames;
+        }
+        if (buckets !== undefined) {
+            config.buckets = buckets;
+        }
+        return new Histogram(config);
+    }
+    /**
+     * Create a summary metric
+     */
+    static createSummary(name, help, labelNames, percentiles) {
+        const config = {
+            name,
+            help,
+        };
+        if (labelNames !== undefined) {
+            config.labelNames = labelNames;
+        }
+        if (percentiles !== undefined) {
+            config.percentiles = percentiles;
+        }
+        return new Summary(config);
+    }
+}
+//# sourceMappingURL=metric.decorators.js.map

package/build/common/decorators/metric.decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.decorators.js","sourceRoot":"","sources":["../../../src/common/decorators/metric.decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEjE;;GAEG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAsB,EAAE,CAAC,MAAM,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;AAEzG;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAsB,EAAE,CAAC,MAAM,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC;AAErG;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAsB,EAAE,CAAC,MAAM,CAAC,yBAAyB,IAAI,EAAE,CAAC,CAAC;AAE7G;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAsB,EAAE,CAAC,MAAM,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC;AAEzG;;GAEG;AACH,MAAM,OAAO,aAAa;IACzB;;OAEG;IACI,MAAM,CAAC,aAAa,CAAC,IAAY,EAAE,IAAY,EAAE,UAAqB;QAC5E,MAAM,MAAM,GAA0D;YACrE,IAAI;YACJ,IAAI;SACJ,CAAC;QACF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;QAChC,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,WAAW,CAAC,IAAY,EAAE,IAAY,EAAE,UAAqB;QAC1E,MAAM,MAAM,GAA0D;YACrE,IAAI;YACJ,IAAI;SACJ,CAAC;QACF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;QAChC,CAAC;QACD,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,eAAe,CAC5B,IAAY,EACZ,IAAY,EACZ,UAAqB,EACrB,OAAkB;QAElB,MAAM,MAAM,GAA8E;YACzF,IAAI;YACJ,IAAI;SACJ,CAAC;QACF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;QAChC,CAAC;QACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;QAC1B,CAAC;QACD,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,aAAa,CAC1B,IAAY,EACZ,IAAY,EACZ,UAAqB,EACrB,WAAsB;QAEtB,MAAM,MAAM,GAAkF;YAC7F,IAAI;YACJ,IAAI;SACJ,CAAC;QACF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,CAAC,UAAU,GAAG,UAAU,CAAC;QAChC,CAAC;QACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC/B,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;CACD"}

package/build/common/decorators/request-property.decorator.d.ts

@@ -0,0 +1,65 @@
+import type { AppLogger } from '../services/logger.service.js';
+/**
+ * Options for the RequestProperty decorator
+ */
+export interface RequestPropertyOptions {
+    /**
+    * Default value to return if the property is not found
+    */
+    defaultValue?: any;
+    /**
+    * Whether to throw an error if the property is not found (overrides defaultValue)
+    */
+    required?: boolean;
+    /**
+    * Transform function to apply to the extracted value
+    */
+    transform?: (value: any) => any;
+    /**
+    * Fallback paths to try if the primary path is not found
+    */
+    fallbackPaths?: string[];
+    /**
+    * Whether to log missing properties (for debugging)
+    */
+    logMissing?: boolean;
+}
+/**
+ * Sets the AppLogger instance for use in the decorator
+ * This should be called during module initialization
+ * @param logger - The AppLogger instance
+ * @internal
+ */
+export declare function SetRequestPropertyDecoratorLogger(logger: AppLogger): void;
+/**
+ * Generic Request Property Decorator Factory
+ *
+ * Extracts any property from the HTTP request object using dot notation paths.
+ * Supports nested property access, type safety, and transformations.
+ *
+ * @param path - Dot-notation path to the property (e.g., 'user', 'query.id', 'body.data.name')
+ * @param options - Configuration options
+ * @returns Parameter decorator function
+ *
+ * @example
+ * // Extract user from request
+ * @Get()
+ * getProfile(@RequestProperty('user') user: User) {}
+ *
+ * @example
+ * // Extract nested property with default
+ * @Get()
+ * getData(@RequestProperty('query.limit', { defaultValue: 10 }) limit: number) {}
+ *
+ * @example
+ * // Extract with transformation
+ * @Post()
+ * createItem(@RequestProperty('body', { transform: (data) => validateData(data) }) data: ValidatedData) {}
+ *
+ * @example
+ * // Required property (throws if missing)
+ * @Get()
+ * getUser(@RequestProperty('user', { required: true }) user: User) {}
+ */
+export declare function RequestProperty<T = any>(path: string, options?: RequestPropertyOptions): ParameterDecorator;
+//# sourceMappingURL=request-property.decorator.d.ts.map

package/build/common/decorators/request-property.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-property.decorator.d.ts","sourceRoot":"","sources":["../../../src/common/decorators/request-property.decorator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAU/D;;GAEG;AAEH,MAAM,WAAW,sBAAsB;IACtC;;MAEK;IACL,YAAY,CAAC,EAAE,GAAG,CAAC;IAEnB;;MAEK;IACL,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;MAEK;IACL,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;IAEhC;;MAEK;IACL,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;MAEK;IACL,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAEzE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,GAAG,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GAClC,kBAAkB,CA+CpB"}

package/build/common/decorators/request-property.decorator.js

@@ -0,0 +1,102 @@
+import { createParamDecorator, Logger } from '@nestjs/common';
+import { ObjectGetPropertyByPath } from '@pawells/typescript-common';
+import { getErrorMessage } from '../utils/error.utils.js';
+// Logger instance for decorator warnings
+// Note: We can't use AppLogger directly here since decorators don't have DI context
+// Instead, we use a Logger instance from @nestjs/common
+const logger = new Logger('RequestPropertyDecorator');
+let appLogger;
+/**
+ * Sets the AppLogger instance for use in the decorator
+ * This should be called during module initialization
+ * @param logger - The AppLogger instance
+ * @internal
+ */
+export function SetRequestPropertyDecoratorLogger(logger) {
+    appLogger = logger;
+}
+/**
+ * Logs a warning message using AppLogger if available, falls back to NestJS Logger
+ * This ensures observability capture when AppLogger is initialized
+ * @param message - The message to log
+ */
+function logWarning(message) {
+    // Try to use AppLogger if available, otherwise use NestJS Logger
+    if (appLogger) {
+        appLogger.warn(message);
+    }
+    else {
+        // Fallback to NestJS Logger when AppLogger is not yet initialized
+        logger.warn(message);
+    }
+}
+/**
+ * Generic Request Property Decorator Factory
+ *
+ * Extracts any property from the HTTP request object using dot notation paths.
+ * Supports nested property access, type safety, and transformations.
+ *
+ * @param path - Dot-notation path to the property (e.g., 'user', 'query.id', 'body.data.name')
+ * @param options - Configuration options
+ * @returns Parameter decorator function
+ *
+ * @example
+ * // Extract user from request
+ * @Get()
+ * getProfile(@RequestProperty('user') user: User) {}
+ *
+ * @example
+ * // Extract nested property with default
+ * @Get()
+ * getData(@RequestProperty('query.limit', { defaultValue: 10 }) limit: number) {}
+ *
+ * @example
+ * // Extract with transformation
+ * @Post()
+ * createItem(@RequestProperty('body', { transform: (data) => validateData(data) }) data: ValidatedData) {}
+ *
+ * @example
+ * // Required property (throws if missing)
+ * @Get()
+ * getUser(@RequestProperty('user', { required: true }) user: User) {}
+ */
+export function RequestProperty(path, options = {}) {
+    return createParamDecorator((_data, ctx) => {
+        const request = ctx.switchToHttp().getRequest();
+        // Try primary path first
+        let value = ObjectGetPropertyByPath(request, path);
+        // Try fallback paths if primary path didn't work
+        if (value === undefined && options.fallbackPaths) {
+            for (const fallbackPath of options.fallbackPaths) {
+                value = ObjectGetPropertyByPath(request, fallbackPath);
+                if (value !== undefined) {
+                    if (options.logMissing) {
+                        logWarning(`RequestProperty: Primary path '${path}' not found, using fallback '${fallbackPath}'`);
+                    }
+                    break;
+                }
+            }
+        }
+        // Handle missing values
+        if (value === undefined) {
+            if (options.required) {
+                throw new Error(`Required property '${path}' not found in HTTP request`);
+            }
+            if (options.logMissing) {
+                logWarning(`RequestProperty: Property '${path}' not found, using default value`);
+            }
+            value = options.defaultValue;
+        }
+        // Apply transformation if provided
+        if (options.transform && value !== undefined) {
+            try {
+                value = options.transform(value);
+            }
+            catch (error) {
+                throw new Error(`RequestProperty transform failed for path '${path}': ${getErrorMessage(error)}`, { cause: error });
+            }
+        }
+        return value;
+    })();
+}
+//# sourceMappingURL=request-property.decorator.js.map

package/build/common/decorators/request-property.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-property.decorator.js","sourceRoot":"","sources":["../../../src/common/decorators/request-property.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAoB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,yCAAyC;AACzC,oFAAoF;AACpF,wDAAwD;AACxD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,0BAA0B,CAAC,CAAC;AACtD,IAAI,SAAgC,CAAC;AAiCrC;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,MAAiB;IAClE,SAAS,GAAG,MAAM,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,OAAe;IAClC,iEAAiE;IACjE,IAAI,SAAS,EAAE,CAAC;QACf,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACP,kEAAkE;QAClE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,eAAe,CAC9B,IAAY,EACZ,UAAkC,EAAE;IAEpC,OAAO,oBAAoB,CAC1B,CAAC,KAAc,EAAE,GAAqB,EAAK,EAAE;QAC5C,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,CAAC;QAEhD,yBAAyB;QACzB,IAAI,KAAK,GAAG,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAEnD,iDAAiD;QACjD,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;YAClD,KAAK,MAAM,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;gBAClD,KAAK,GAAG,uBAAuB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;gBACvD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACzB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;wBACxB,UAAU,CAAC,kCAAkC,IAAI,gCAAgC,YAAY,GAAG,CAAC,CAAC;oBACnG,CAAC;oBACD,MAAM;gBACP,CAAC;YACF,CAAC;QACF,CAAC;QAED,wBAAwB;QACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,6BAA6B,CAAC,CAAC;YAC1E,CAAC;YACD,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACxB,UAAU,CAAC,8BAA8B,IAAI,kCAAkC,CAAC,CAAC;YAClF,CAAC;YACD,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC;QAC9B,CAAC;QAED,mCAAmC;QACnC,IAAI,OAAO,CAAC,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9C,IAAI,CAAC;gBACJ,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,IAAI,KAAK,CACd,8CAA8C,IAAI,MAAM,eAAe,CAAC,KAAK,CAAC,EAAE,EAChF,EAAE,KAAK,EAAE,KAAK,EAAE,CAChB,CAAC;YACH,CAAC;QACF,CAAC;QAED,OAAO,KAAU,CAAC;IACnB,CAAC,CACD,EAAE,CAAC;AACL,CAAC"}

package/build/common/errors/base-application-error.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Base Application Error
+ *
+ * Provides a standardized error structure for NestJS applications with consistent
+ * properties and methods for error handling, serialization, and context management.
+ *
+ * @example
+ * ```typescript
+ * throw new BaseApplicationError('User not found', {
+ *   code: 'USER_NOT_FOUND',
+ *   statusCode: 404,
+ *   context: { userId: '123' }
+ * });
+ * ```
+ */
+export declare class BaseApplicationError extends Error {
+    /**
+     * The HTTP status code associated with this error
+     */
+    readonly statusCode: number;
+    /**
+     * The error code for programmatic error identification
+     */
+    readonly code: string;
+    /**
+     * Additional context information for debugging and logging
+     */
+    readonly context: Record<string, any>;
+    /**
+     * Timestamp when the error was created
+     */
+    readonly timestamp: Date;
+    /**
+     * Creates a new BaseApplicationError instance
+     *
+     * @param message - The error message
+     * @param options - Configuration options for the error
+     * @param options.code - The error code (defaults to 'INTERNAL_SERVER_ERROR')
+     * @param options.statusCode - The HTTP status code (defaults to 500)
+     * @param options.context - Additional context information (defaults to empty object)
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        statusCode?: number;
+        context?: Record<string, any>;
+    });
+    /**
+     * Serializes the error to a plain object for JSON responses or logging
+     *
+     * @returns A plain object representation of the error
+     *
+     * @example
+     * ```typescript
+     * const error = new BaseApplicationError('Test error');
+     * console.log(error.toJSON());
+     * // {
+     * //   name: 'BaseApplicationError',
+     * //   message: 'Test error',
+     * //   code: 'INTERNAL_SERVER_ERROR',
+     * //   statusCode: 500,
+     * //   context: {},
+     * //   timestamp: '2023-01-01T00:00:00.000Z'
+     * // }
+     * ```
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Creates a new error instance with additional context merged into the existing context.
+     * Note: Returns a new instance, not the same instance, so instanceof checks will still work.
+     *
+     * @param additionalContext - Additional context to merge
+     * @returns A new error instance of the same type with merged context
+     *
+     * @example
+     * ```typescript
+     * const error = new BaseApplicationError('User error', { code: 'USER_ERROR' });
+     * const errorWithContext = error.withContext({ userId: '123', action: 'login' });
+     * // errorWithContext is a new instance but still instanceof BaseApplicationError
+     * // errorWithContext.context = { userId: '123', action: 'login' }
+     * ```
+     */
+    withContext(additionalContext: Record<string, any>): this;
+    /**
+     * Creates a new error instance with a different message
+     *
+     * @param newMessage - The new error message
+     * @returns A new error instance with the updated message
+     *
+     * @example
+     * ```typescript
+     * const error = new BaseApplicationError('Generic error');
+     * const specificError = error.withMessage('User not found');
+     * // specificError.message = 'User not found'
+     * ```
+     */
+    withMessage(newMessage: string): this;
+}
+//# sourceMappingURL=base-application-error.d.ts.map

package/build/common/errors/base-application-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-application-error.d.ts","sourceRoot":"","sources":["../../../src/common/errors/base-application-error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE7C;;OAEG;IACH,SAAgB,SAAS,EAAE,IAAI,CAAC;IAEhC;;;;;;;;OAQG;gBAEF,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KACzB;IAkBP;;;;;;;;;;;;;;;;;;OAkBG;IACI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAapC;;;;;;;;;;;;;;OAcG;IACI,WAAW,CAAC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAchE;;;;;;;;;;;;OAYG;IACI,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAY5C"}