apm-optima 0.0.1

package/dist/core/telemetry/logger.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("../../config");
+class Logger {
+    static RESET = '\x1b[0m';
+    static BOLD = '\x1b[1m';
+    static DIM = '\x1b[2m';
+    static COLORS = {
+        GET: '\x1b[32m', // Green
+        POST: '\x1b[36m', // Cyan
+        PUT: '\x1b[33m', // Yellow
+        DELETE: '\x1b[31m', // Red
+        PATCH: '\x1b[35m', // Magenta
+        SUCCESS: '\x1b[32m', // Green (2xx)
+        WARN: '\x1b[33m', // Yellow (4xx)
+        ERROR: '\x1b[31m' // Red (5xx)
+    };
+    static log(req, res, duration) {
+        if (!(0, config_1.getConfig)().consoleLog)
+            return;
+        const timestamp = new Date().toISOString().split('T')[1].slice(0, -1);
+        const timeFormatted = `${duration.toFixed(2)}ms`.padStart(8, ' ');
+        const methodColor = Logger.COLORS[req.method] || Logger.RESET;
+        const method = `${Logger.BOLD}${methodColor}${req.method.padEnd(7, ' ')}${Logger.RESET}`;
+        const status = res.statusCode;
+        let statusColor = Logger.COLORS.SUCCESS;
+        if (status >= 400 && status < 500)
+            statusColor = Logger.COLORS.WARN;
+        if (status >= 500)
+            statusColor = Logger.COLORS.ERROR;
+        const statusCode = `${Logger.BOLD}${statusColor}${status}${Logger.RESET}`;
+        let speedColor = Logger.RESET;
+        if (duration > 500)
+            speedColor = Logger.COLORS.ERROR;
+        else if (duration > 200)
+            speedColor = Logger.COLORS.WARN;
+        const timing = `${speedColor}${timeFormatted}${Logger.RESET}`;
+        console.log(`${Logger.DIM}[${timestamp}]${Logger.RESET} ` +
+            `${method} ` +
+            `${req.url.padEnd(35, ' ')} ` +
+            `•  ${statusCode}  • ` +
+            `${timing}`);
+    }
+    static debug(message) {
+        const timestamp = new Date().toISOString().split('T')[1].slice(0, -1);
+        console.log(`${Logger.DIM}[${timestamp}]${Logger.RESET} ${Logger.DIM}${message}${Logger.RESET}`);
+    }
+    static duration(message, duration) {
+        return; // Disable duration logging for now
+        const timestamp = new Date().toISOString().split('T')[1].slice(0, -1);
+        const timeFormatted = `${duration.toFixed(2)}ms`.padStart(8, ' ');
+        let speedColor = Logger.RESET;
+        if (duration > 500)
+            speedColor = Logger.COLORS.ERROR;
+        else if (duration > 200)
+            speedColor = Logger.COLORS.WARN;
+        const timing = `${speedColor}${timeFormatted}${Logger.RESET}`;
+        console.log(`${Logger.DIM}[${timestamp}]${Logger.RESET} ` +
+            `${message} ` +
+            `• ${timing}`);
+    }
+}
+exports.default = Logger;

package/dist/core/telemetry/telemetry.service.d.ts

@@ -0,0 +1,10 @@
+import type { TelemetryRequest } from '../domain';
+declare class TelemetryService {
+    private readonly storage;
+    constructor(storage?: {
+        record(request: TelemetryRequest): void;
+    });
+    private isPathExcluded;
+    record(data: Omit<TelemetryRequest, 'timestamp' | 'responseTime'>, startHrTime: bigint): TelemetryRequest | null;
+}
+export default TelemetryService;

package/dist/core/telemetry/telemetry.service.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const local_repository_1 = require("../storage/local.repository");
+const config_1 = require("../../config");
+class TelemetryService {
+    storage;
+    constructor(storage = local_repository_1.storage) {
+        this.storage = storage;
+    }
+    isPathExcluded(endpoint) {
+        const cleanPath = endpoint.split('?')[0];
+        const userConfig = (0, config_1.getConfig)();
+        const configuredPaths = userConfig?.excludePaths || [];
+        const allPatterns = [...configuredPaths];
+        return allPatterns.some(pattern => {
+            const cleanPattern = pattern.replace(/\*/g, '');
+            return cleanPath.includes(cleanPattern);
+        });
+    }
+    record(data, startHrTime) {
+        if (this.isPathExcluded(data.endpoint)) {
+            return null;
+        }
+        const endHrTime = process.hrtime.bigint();
+        const durationInMS = Number(endHrTime - startHrTime) / 1e6;
+        const durationInMSFixed = parseFloat(durationInMS.toFixed(2));
+        const telemetryRequest = {
+            ...data,
+            timestamp: Date.now(),
+            responseTime: durationInMSFixed,
+        };
+        this.storage.record(telemetryRequest);
+        return telemetryRequest;
+    }
+}
+exports.default = TelemetryService;

package/dist/core/utility/base-math.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @param value - The value to be clamped.
+ * @param min - The minimum value to clamp to.
+ * @param max - The maximum value to clamp to.
+ * @returns The clamped value, guaranteed to be between min and max.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Clamps a given value to ensure it falls within the range of 0 to 100.
+ * @param value - The value to be clamped, typically representing a percentage.
+ * @param total - The total value used to calculate the percentage.
+ * @returns The clamped percentage value, guaranteed to be between 0 and 100.
+ */
+export declare function toPercentage(value: number, total: number): number;

package/dist/core/utility/base-math.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clamp = clamp;
+exports.toPercentage = toPercentage;
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @param value - The value to be clamped.
+ * @param min - The minimum value to clamp to.
+ * @param max - The maximum value to clamp to.
+ * @returns The clamped value, guaranteed to be between min and max.
+ */
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Clamps a given value to ensure it falls within the range of 0 to 100.
+ * @param value - The value to be clamped, typically representing a percentage.
+ * @param total - The total value used to calculate the percentage.
+ * @returns The clamped percentage value, guaranteed to be between 0 and 100.
+ */
+function toPercentage(value, total) {
+    if (total === 0) {
+        return 0; // Avoid division by zero
+    }
+    return clamp((value / total) * 100, 0, 100);
+}

package/dist/core/utility/conversion.d.ts

@@ -0,0 +1,31 @@
+type SizeUnit = 'MB' | 'KB' | 'GB';
+type TimeUnit = 'ms' | 's';
+/**
+ * Converts bytes to the specified size unit (MB, KB, GB).
+ * @param bytes The number of bytes to convert.
+ * @param unit The unit to convert to.
+ * @returns The equivalent number in the specified unit.
+ */
+export declare function convertBytes(bytes: number, unit: SizeUnit): number;
+/**
+ * Converts a value in the specified size unit (MB, KB, GB) to bytes.
+ * @param value The value to convert.
+ * @param unit The unit of the value (MB, KB, GB).
+ * @returns The equivalent number of bytes.
+ */
+export declare function convertToBytes(value: number, unit: SizeUnit): number;
+/**
+ * Converts a value in nanoseconds to the specified time unit (milliseconds or seconds).
+ * @param value The value in nanoseconds to convert.
+ * @param unit The unit to convert to ('ms' for milliseconds, 's' for seconds).
+ * @returns The equivalent number in the specified unit.
+ */
+export declare function convertNanoseconds(value: number, unit: TimeUnit): number;
+/**
+ * Converts a value in the specified time unit (milliseconds or seconds) to nanoseconds.
+ * @param value The value to convert.
+ * @param unit The unit of the value ('ms' for milliseconds, 's' for seconds).
+ * @returns The equivalent number of nanoseconds.
+ */
+export declare function convertToNanoseconds(value: number, unit: TimeUnit): number;
+export {};

package/dist/core/utility/conversion.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertBytes = convertBytes;
+exports.convertToBytes = convertToBytes;
+exports.convertNanoseconds = convertNanoseconds;
+exports.convertToNanoseconds = convertToNanoseconds;
+/**
+ * Converts bytes to the specified size unit (MB, KB, GB).
+ * @param bytes The number of bytes to convert.
+ * @param unit The unit to convert to.
+ * @returns The equivalent number in the specified unit.
+ */
+function convertBytes(bytes, unit) {
+    switch (unit) {
+        case 'MB':
+            return Math.round(bytes / 1024 / 1024);
+        case 'KB':
+            return Math.round(bytes / 1024);
+        case 'GB':
+            return Math.round(bytes / 1024 / 1024 / 1024);
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+}
+/**
+ * Converts a value in the specified size unit (MB, KB, GB) to bytes.
+ * @param value The value to convert.
+ * @param unit The unit of the value (MB, KB, GB).
+ * @returns The equivalent number of bytes.
+ */
+function convertToBytes(value, unit) {
+    switch (unit) {
+        case 'MB':
+            return value * 1024 * 1024;
+        case 'KB':
+            return value * 1024;
+        case 'GB':
+            return value * 1024 * 1024 * 1024;
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+}
+/**
+ * Converts a value in nanoseconds to the specified time unit (milliseconds or seconds).
+ * @param value The value in nanoseconds to convert.
+ * @param unit The unit to convert to ('ms' for milliseconds, 's' for seconds).
+ * @returns The equivalent number in the specified unit.
+ */
+function convertNanoseconds(value, unit) {
+    switch (unit) {
+        case 'ms':
+            return value / 1e6; // Convert nanoseconds to milliseconds
+        case 's':
+            return value / 1e9; // Convert nanoseconds to seconds
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+}
+/**
+ * Converts a value in the specified time unit (milliseconds or seconds) to nanoseconds.
+ * @param value The value to convert.
+ * @param unit The unit of the value ('ms' for milliseconds, 's' for seconds).
+ * @returns The equivalent number of nanoseconds.
+ */
+function convertToNanoseconds(value, unit) {
+    switch (unit) {
+        case 'ms':
+            return value * 1e6; // Convert milliseconds to nanoseconds
+        case 's':
+            return value * 1e9; // Convert seconds to nanoseconds
+        default:
+            throw new Error(`Unsupported unit: ${unit}`);
+    }
+}

package/dist/core/utility/index.d.ts

@@ -0,0 +1,4 @@
+export * from './base-math';
+export * from './conversion';
+export * from './pagination';
+export * from './statistics';

package/dist/core/utility/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base-math"), exports);
+__exportStar(require("./conversion"), exports);
+__exportStar(require("./pagination"), exports);
+__exportStar(require("./statistics"), exports);

package/dist/core/utility/mocking.d.ts

@@ -0,0 +1,21 @@
+export declare function mockArray(length: number, min: number, max: number, force?: number): number[];
+export declare function mockDistributionEntry(endpoint: string, p50Min: number, p50Max: number, p95Min: number, p95Max: number, p99Min: number, p99Max: number): {
+    endpoint: string;
+    p50: number;
+    p95: number;
+    p99: number;
+};
+export declare function mockDistribution(endpoints: string[], p50Min: number, p50Max: number, p95Min: number, p95Max: number, p99Min: number, p99Max: number): {
+    endpoint: string;
+    p50: number;
+    p95: number;
+    p99: number;
+}[];
+export declare function mockVolumeEntry(endpoint: string, volumeMin: number, volumeMax: number): {
+    endpoint: string;
+    volume: number;
+};
+export declare function mockVolume(endpoints: string[], volumeMin: number, volumeMax: number): {
+    endpoint: string;
+    volume: number;
+}[];

package/dist/core/utility/mocking.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockArray = mockArray;
+exports.mockDistributionEntry = mockDistributionEntry;
+exports.mockDistribution = mockDistribution;
+exports.mockVolumeEntry = mockVolumeEntry;
+exports.mockVolume = mockVolume;
+function mockArray(length, min, max, force) {
+    const arr = [];
+    for (let i = 0; i < length; i++) {
+        if (force !== undefined) {
+            if (Math.random() < 0.7) {
+                arr.push(force);
+                continue;
+            }
+        }
+        arr.push(Math.floor(Math.random() * (max - min + 1)) + min);
+    }
+    return arr;
+}
+function mockDistributionEntry(endpoint, p50Min, p50Max, p95Min, p95Max, p99Min, p99Max) {
+    return {
+        endpoint,
+        p50: Math.floor(Math.random() * (p50Max - p50Min + 1)) + p50Min,
+        p95: Math.floor(Math.random() * (p95Max - p95Min + 1)) + p95Min,
+        p99: Math.floor(Math.random() * (p99Max - p99Min + 1)) + p99Min,
+    };
+}
+function mockDistribution(endpoints, p50Min, p50Max, p95Min, p95Max, p99Min, p99Max) {
+    return endpoints.map((endpoint) => mockDistributionEntry(endpoint, p50Min, p50Max, p95Min, p95Max, p99Min, p99Max));
+}
+function mockVolumeEntry(endpoint, volumeMin, volumeMax) {
+    return {
+        endpoint,
+        volume: Math.floor(Math.random() * (volumeMax - volumeMin + 1)) + volumeMin,
+    };
+}
+function mockVolume(endpoints, volumeMin, volumeMax) {
+    return endpoints.map((endpoint) => mockVolumeEntry(endpoint, volumeMin, volumeMax));
+}

package/dist/core/utility/pagination.d.ts

@@ -0,0 +1,9 @@
+import type { PaginationMeta } from "../domain";
+export declare function constructData<T>(items: T[], page: number, pageSize: number): T[];
+export declare function constructMeta(total: number, page: number, pageSize: number): PaginationMeta;
+type PaginationResult<T> = {
+    data: T[];
+    meta: PaginationMeta;
+};
+export declare function paginate<T>(items: T[], page: number, pageSize: number): PaginationResult<T>;
+export {};

package/dist/core/utility/pagination.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructData = constructData;
+exports.constructMeta = constructMeta;
+exports.paginate = paginate;
+function constructData(items, page, pageSize) {
+    const start = (page - 1) * pageSize;
+    return items.slice(start, start + pageSize);
+}
+function constructMeta(total, page, pageSize) {
+    return {
+        page,
+        pageSize,
+        perPageCount: Math.min(pageSize, total),
+        totalCount: total,
+    };
+}
+function paginate(items, page, pageSize) {
+    return {
+        data: constructData(items, page, pageSize),
+        meta: constructMeta(items.length, page, pageSize),
+    };
+}

package/dist/core/utility/statistics.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Generates a hash code for a given value. This function converts the value to a JSON string and computes a hash code based on its characters.
+ * @param value The value to be hashed. It can be of any type that can be serialized to JSON.
+ * @returns The hash code for the given value.
+ */
+export declare function hash(value: NonNullable<unknown>): number;
+/**
+ * Calculates the rate as a percentage of accounted over total.
+ * @param accounted The number of items accounted for.
+ * @param total The total number of items.
+ * @returns The rate as a percentage.
+ */
+export declare function rate(accounted: number, total: number): number;
+/**
+ * Calculates the mean (average) of a dataset.
+ * @param data - An array of numbers representing the dataset.
+ * @returns The mean of the dataset.
+ */
+export declare function mean(data: number[]): number;
+/**
+ * Calculates the specified percentile of a dataset. (e.g., p95, p99)
+ * @param data - An array of numbers representing the dataset.
+ * @param percentile - The desired percentile (between 0 and 1, e.g., 0.95 for p95).
+ * @returns The value at the specified percentile of the dataset.
+ */
+export declare function percentile(data: number[], percentile: number): number;
+/**
+ * Calculates the specified percentile of a histogram represented by counters and limits.
+ * This function is useful for determining latency percentiles from histogram data.
+ * @param counters An array of counts representing the number of occurrences in each histogram bucket.
+ * @param totalCount The total number of occurrences across all histogram buckets.
+ * @param percentile The desired percentile (between 0 and 1, e.g., 0.95 for p95).
+ * @param limits An array of upper limits for each histogram bucket, corresponding to the counters.
+ * @returns The value at the specified percentile of the histogram.
+ */
+export declare function percentileHistogram(counters: Uint32Array, totalCount: number, percentile: number, limits: number[]): number;
+/**
+ * Calculates the median (p50) of a dataset.
+ * @param data - An array of numbers representing the dataset.
+ * @returns The median of the dataset.
+ */
+export declare function median(data: number[]): number;
+/**
+ * Calculates the required sample size for estimating a population proportion with a specified margin of error and confidence level.
+ * The formula used is based on the normal approximation to the binomial distribution.
+ * @param marginOfError The desired margin of error (e.g., 0.05 for ±5%).
+ * @param confidenceLevel The desired confidence level (default is 0.95 for 95% confidence).
+ * @returns The required sample size to achieve the specified margin of error and confidence level.
+ */
+export declare function calculateSampleSizeProportion(marginOfError: number, confidenceLevel?: number): number;
+/**
+ * Calculates the Pearson correlation coefficient (r) between two datasets.
+ * The correlation coefficient measures the strength and direction of the linear relationship between two variables.
+ * The value of r ranges from -1 to 1, where:
+ * - r = 1 indicates a perfect positive correlation,
+ * - r = -1 indicates a perfect negative correlation,
+ * - r = 0 indicates no correlation.
+ *
+ * The function also provides an interpretation of the correlation strength and assigns a color class for visualization purposes.
+ * @param x The first dataset (X values) as an array of numbers.
+ * @param y The second dataset (Y values) as an array of numbers.
+ * @returns The Pearson correlation coefficient (r).
+ */
+export declare function pearsonCorrelation(x: number[], y: number[]): number;
+/**
+ * Calculates the Spearman rank correlation coefficient (ρ) between two datasets.
+ * @param x An array of numbers representing the first dataset.
+ * @param y An array of numbers representing the second dataset.
+ * @returns The Spearman rank correlation coefficient (ρ).
+ */
+export declare function spearmanCorrelation(x: number[], y: number[]): number;
+/**
+ * Calculates the coefficient of determination (R²) and the coefficient of alienation (1 - R²) based on the Pearson correlation coefficient (r).
+ * The coefficient of determination (R²) indicates the proportion of the variance in the dependent variable that is predictable from the independent variable.
+ * The coefficient of alienation (1 - R²) indicates the proportion of the variance that is not explained by the model.
+ *
+ * @param pearsonR The Pearson correlation coefficient (r) between two datasets.
+ * @returns An object containing the coefficient of determination (R²) and the coefficient of alienation (1 - R²).
+ */
+export declare function determinationAndAlienation(pearsonR: number): {
+    determination: number;
+    alienation: number;
+};
+/**
+ * Calculates the standard deviation of a dataset.
+ * The standard deviation is a measure of the amount of variation or dispersion in a set of values.
+ * @param data An array of numbers representing the dataset.
+ * @returns The standard deviation of the dataset.
+ */
+export declare function standardDeviation(data: number[]): number;
+/**
+ * Calculates the standard deviation from histogram data.
+ * The standard deviation is a measure of the amount of variation or dispersion in a set of values.
+ * This function uses the total count, total sum, and total sum of squares to compute the standard deviation.
+ * @param totalCount The total number of occurrences across all histogram buckets.
+ * @param totalSum The total sum of all values across the histogram buckets.
+ * @param totalSumOfSquares The total sum of squares of all values across the histogram buckets.
+ * @returns The standard deviation of the histogram data.
+ */
+export declare function standardDeviationHistogram(totalCount: number, totalSum: number, totalSumOfSquares: number): number;
+/**
+ * Calculates the z-score for a given value based on the mean and standard deviation of a dataset.
+ * The z-score indicates how many standard deviations a value is from the mean.
+ * A positive z-score indicates the value is above the mean, while a negative z-score indicates it is below the mean.
+ * @param value The value for which the z-score is to be calculated.
+ * @param data An array of numbers representing the dataset.
+ * @returns The z-score of the value. If the dataset is empty or has zero standard deviation, the function returns 0.
+ */
+export declare function zScore(value: number, data: number[]): number;
+/**
+ * Calculates the z-score for a given value based on histogram data.
+ * The z-score indicates how many standard deviations a value is from the mean.
+ * A positive z-score indicates the value is above the mean, while a negative z-score indicates it is below the mean.
+ * @param value The value for which the z-score is to be calculated.
+ * @param totalCount The total number of occurrences across all histogram buckets.
+ * @param totalSum The total sum of all values across the histogram buckets.
+ * @param totalSumOfSquares The total sum of squares of all values across the histogram buckets.
+ * @returns The z-score of the value. If the histogram is empty or has zero standard deviation, the function returns 0.
+ */
+export declare function zScoreHistogram(value: number, totalCount: number, totalSum: number, totalSumOfSquares: number): number;
+/**
+ * Determines if a given value is an anomaly based on its z-score relative to a dataset.
+ * A value is considered an anomaly if its z-score exceeds the specified threshold.
+ * @param value The value to be evaluated for anomaly detection.
+ * @param data An array of numbers representing the dataset against which the value is compared.
+ * @param threshold The z-score threshold beyond which a value is considered an anomaly. Default is 3.
+ * @returns A boolean indicating whether the value is an anomaly (true) or not (false).
+ */
+export declare function isDataAnomaly(value: number, data: number[], threshold?: number): boolean;
+/**
+ * Determines if a given value is an anomaly based on its z-score relative to histogram data.
+ * A value is considered an anomaly if its z-score exceeds the specified threshold.
+ * @param value The value to be evaluated for anomaly detection.
+ * @param totalCount The total number of occurrences across all histogram buckets.
+ * @param totalSum The total sum of all values across the histogram buckets.
+ * @param totalSumOfSquares The total sum of squares of all values across the histogram buckets.
+ * @param threshold The z-score threshold beyond which a value is considered an anomaly. Default is 3.
+ * @returns A boolean indicating whether the value is an anomaly (true) or not (false).
+ */
+export declare function isDataAnomalyHistogram(value: number, totalCount: number, totalSum: number, totalSumOfSquares: number, threshold?: number): boolean;