payload-guard-filter 1.8.0 → 1.8.3

package/README.md

@@ -1,4 +1,4 @@
-# payload-guard
+# payload-guard-filter
 
 > Part of the [Professional Node.js Backend Toolkit](https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-)
 
@@ -45,7 +45,7 @@ graph LR
 ## 📦 Installation
 
 ```bash
-npm install payload-guard
+npm install payload-guard-filter
 ```
 
 ---
@@ -55,7 +55,7 @@ npm install payload-guard
 ### Basic Usage
 
 ```typescript
-import { guard } from 'payload-guard';
+import { guard } from 'payload-guard-filter';
 
 // Define a shape
 const userShape = guard.shape({
@@ -158,7 +158,7 @@ const userShape = guard.shape({
 });
 
 // Collect validation errors
-const { compile } = require('payload-guard');
+const { compile } = require('payload-guard-filter');
 const errors = [];
 const validator = compile(
   { email: { type: 'string', email: true } },
@@ -209,7 +209,7 @@ Creates a string builder with chained constraints:
 
 **Error Collection:**
 ```typescript
-const { compile } = require('payload-guard');
+const { compile } = require('payload-guard-filter');
 const errors = [];
 const validator = compile(shape, { collectErrors: true, _errors: errors });
 validator(data);

package/dist/core/buffer.d.ts

@@ -0,0 +1,157 @@
+/**
+ * payload-guard — Async Buffering System
+ * Batch payload processing for reduced overhead
+ *
+ * @packageDocumentation
+ */
+import type { ValidationMetrics } from './types';
+/**
+ * Async Buffer for batching payload validations
+ * Reduces overhead by processing multiple payloads together
+ */
+export declare class AsyncBuffer<T = unknown> {
+    private buffer;
+    private maxSize;
+    private maxTime;
+    private flushCallback;
+    private timer;
+    private isFlushing;
+    private pendingResolves;
+    constructor(options?: {
+        maxSize?: number;
+        maxTime?: number;
+        flushCallback?: (items: T[]) => Promise<void>;
+    });
+    /**
+     * Add item to buffer
+     * Returns promise that resolves when item is processed
+     */
+    add(item: T, priority?: number): Promise<void>;
+    /**
+     * Force flush the buffer
+     */
+    flush(): Promise<void>;
+    /**
+     * Get current buffer size
+     */
+    size(): number;
+    /**
+     * Clear buffer without processing
+     */
+    clear(): void;
+    /**
+     * Get buffer statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        isFlushing: boolean;
+        avgWaitTime: number;
+    };
+    private startTimer;
+    private stopTimer;
+    private generateId;
+}
+/**
+ * Circular Buffer for memory-efficient storage
+ * Fixed size, overwrites oldest entries when full
+ */
+export declare class CircularBuffer<T> {
+    private buffer;
+    private capacity;
+    private head;
+    private tail;
+    private size;
+    constructor(capacity?: number);
+    /**
+     * Add item to buffer
+     * Overwrites oldest item if full
+     */
+    push(item: T): void;
+    /**
+     * Get all items in order (oldest to newest)
+     */
+    toArray(): T[];
+    /**
+     * Get item at index (0 = oldest)
+     */
+    get(index: number): T | null;
+    /**
+     * Get latest item
+     */
+    latest(): T | null;
+    /**
+     * Get oldest item
+     */
+    oldest(): T | null;
+    /**
+     * Clear buffer
+     */
+    clear(): void;
+    /**
+     * Get current size
+     */
+    length(): number;
+    /**
+     * Check if buffer is full
+     */
+    isFull(): boolean;
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Get buffer statistics
+     */
+    getStats(): {
+        capacity: number;
+        size: number;
+        utilization: number;
+    };
+}
+/**
+ * Validation result buffer item
+ */
+interface ValidationBufferItem {
+    path: string;
+    method: string;
+    inputSize: number;
+    outputSize: number;
+    filteredFields: string[];
+    duration: number;
+    timestamp: number;
+}
+/**
+ * Metrics buffer for batching validation metrics
+ */
+export declare class MetricsBuffer {
+    private buffer;
+    private asyncBuffer;
+    private metricsCallback;
+    constructor(capacity?: number, metricsCallback?: (metrics: ValidationMetrics) => void);
+    /**
+     * Record a validation result
+     */
+    record(result: {
+        path: string;
+        method: string;
+        inputSize: number;
+        outputSize: number;
+        filteredFields: string[];
+        duration: number;
+    }): void;
+    /**
+     * Get aggregated metrics
+     */
+    getMetrics(): ValidationMetrics;
+    /**
+     * Get recent validation results
+     */
+    getRecent(limit?: number): ValidationBufferItem[];
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    private recordBatch;
+}
+export {};

package/dist/core/buffer.js

@@ -0,0 +1,312 @@
+"use strict";
+/**
+ * payload-guard — Async Buffering System
+ * Batch payload processing for reduced overhead
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsBuffer = exports.CircularBuffer = exports.AsyncBuffer = void 0;
+/**
+ * Async Buffer for batching payload validations
+ * Reduces overhead by processing multiple payloads together
+ */
+class AsyncBuffer {
+    constructor(options = {}) {
+        this.buffer = [];
+        this.timer = null;
+        this.isFlushing = false;
+        this.pendingResolves = [];
+        this.maxSize = options.maxSize ?? 100;
+        this.maxTime = options.maxTime ?? 1000; // 1 second
+        this.flushCallback = options.flushCallback ?? (async () => { });
+    }
+    /**
+     * Add item to buffer
+     * Returns promise that resolves when item is processed
+     */
+    add(item, priority = 0) {
+        return new Promise((resolve) => {
+            const bufferItem = {
+                data: item,
+                timestamp: Date.now(),
+                priority,
+                id: this.generateId(),
+            };
+            this.buffer.push(bufferItem);
+            this.pendingResolves.push(resolve);
+            // Start timer if not already running
+            if (!this.timer && this.buffer.length > 0) {
+                this.startTimer();
+            }
+            // Flush if buffer is full
+            if (this.buffer.length >= this.maxSize) {
+                this.flush();
+            }
+        });
+    }
+    /**
+     * Force flush the buffer
+     */
+    async flush() {
+        if (this.isFlushing || this.buffer.length === 0) {
+            return;
+        }
+        this.isFlushing = true;
+        this.stopTimer();
+        // Sort by priority (higher first)
+        this.buffer.sort((a, b) => b.priority - a.priority);
+        // Extract data
+        const items = this.buffer.map(item => item.data);
+        const resolves = this.pendingResolves;
+        // Clear buffer
+        this.buffer = [];
+        this.pendingResolves = [];
+        try {
+            // Process in background
+            await this.flushCallback(items);
+        }
+        catch (error) {
+            console.error('[AsyncBuffer] Flush error:', error);
+        }
+        finally {
+            // Resolve all pending promises
+            resolves.forEach(resolve => resolve());
+            this.isFlushing = false;
+        }
+    }
+    /**
+     * Get current buffer size
+     */
+    size() {
+        return this.buffer.length;
+    }
+    /**
+     * Clear buffer without processing
+     */
+    clear() {
+        this.buffer = [];
+        this.pendingResolves = [];
+        this.stopTimer();
+    }
+    /**
+     * Get buffer statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const avgWaitTime = this.buffer.length > 0
+            ? this.buffer.reduce((sum, item) => sum + (now - item.timestamp), 0) / this.buffer.length
+            : 0;
+        return {
+            size: this.buffer.length,
+            maxSize: this.maxSize,
+            isFlushing: this.isFlushing,
+            avgWaitTime,
+        };
+    }
+    startTimer() {
+        this.timer = setTimeout(() => {
+            this.flush();
+        }, this.maxTime);
+    }
+    stopTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    generateId() {
+        return `buf_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
+    }
+}
+exports.AsyncBuffer = AsyncBuffer;
+/**
+ * Circular Buffer for memory-efficient storage
+ * Fixed size, overwrites oldest entries when full
+ */
+class CircularBuffer {
+    constructor(capacity = 1000) {
+        this.capacity = capacity;
+        this.buffer = new Array(capacity).fill(null);
+        this.head = 0;
+        this.tail = 0;
+        this.size = 0;
+    }
+    /**
+     * Add item to buffer
+     * Overwrites oldest item if full
+     */
+    push(item) {
+        this.buffer[this.tail] = item;
+        this.tail = (this.tail + 1) % this.capacity;
+        if (this.size === this.capacity) {
+            // Buffer is full, move head forward
+            this.head = (this.head + 1) % this.capacity;
+        }
+        else {
+            this.size++;
+        }
+    }
+    /**
+     * Get all items in order (oldest to newest)
+     */
+    toArray() {
+        const result = [];
+        for (let i = 0; i < this.size; i++) {
+            const index = (this.head + i) % this.capacity;
+            const item = this.buffer[index];
+            if (item !== null) {
+                result.push(item);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get item at index (0 = oldest)
+     */
+    get(index) {
+        if (index < 0 || index >= this.size) {
+            return null;
+        }
+        const idx = (this.head + index) % this.capacity;
+        return this.buffer[idx];
+    }
+    /**
+     * Get latest item
+     */
+    latest() {
+        if (this.size === 0)
+            return null;
+        const idx = (this.tail - 1 + this.capacity) % this.capacity;
+        return this.buffer[idx];
+    }
+    /**
+     * Get oldest item
+     */
+    oldest() {
+        if (this.size === 0)
+            return null;
+        return this.buffer[this.head];
+    }
+    /**
+     * Clear buffer
+     */
+    clear() {
+        this.buffer = new Array(this.capacity).fill(null);
+        this.head = 0;
+        this.tail = 0;
+        this.size = 0;
+    }
+    /**
+     * Get current size
+     */
+    length() {
+        return this.size;
+    }
+    /**
+     * Check if buffer is full
+     */
+    isFull() {
+        return this.size === this.capacity;
+    }
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty() {
+        return this.size === 0;
+    }
+    /**
+     * Get buffer statistics
+     */
+    getStats() {
+        return {
+            capacity: this.capacity,
+            size: this.size,
+            utilization: this.size / this.capacity,
+        };
+    }
+}
+exports.CircularBuffer = CircularBuffer;
+/**
+ * Metrics buffer for batching validation metrics
+ */
+class MetricsBuffer {
+    constructor(capacity = 1000, metricsCallback) {
+        this.buffer = new CircularBuffer(capacity);
+        this.metricsCallback = metricsCallback ?? (() => { });
+        this.asyncBuffer = new AsyncBuffer({
+            maxSize: 50,
+            maxTime: 5000,
+            flushCallback: async (items) => {
+                this.recordBatch(items);
+            }
+        });
+    }
+    /**
+     * Record a validation result
+     */
+    record(result) {
+        const item = {
+            ...result,
+            timestamp: Date.now(),
+        };
+        this.buffer.push(item);
+        this.asyncBuffer.add(item);
+    }
+    /**
+     * Get aggregated metrics
+     */
+    getMetrics() {
+        const items = this.buffer.toArray();
+        const totalValidations = items.length;
+        if (totalValidations === 0) {
+            return {
+                totalValidations: 0,
+                totalFiltered: 0,
+                avgInputSize: 0,
+                avgOutputSize: 0,
+                avgReductionPercent: 0,
+                avgDuration: 0,
+                slowestDuration: 0,
+            };
+        }
+        const totalFiltered = items.filter(i => i.filteredFields.length > 0).length;
+        const totalInputSize = items.reduce((sum, i) => sum + i.inputSize, 0);
+        const totalOutputSize = items.reduce((sum, i) => sum + i.outputSize, 0);
+        const totalDuration = items.reduce((sum, i) => sum + i.duration, 0);
+        const slowestDuration = Math.max(...items.map(i => i.duration));
+        const avgInputSize = totalInputSize / totalValidations;
+        const avgOutputSize = totalOutputSize / totalValidations;
+        const avgReductionPercent = ((totalInputSize - totalOutputSize) / totalInputSize) * 100;
+        const avgDuration = totalDuration / totalValidations;
+        return {
+            totalValidations,
+            totalFiltered,
+            avgInputSize,
+            avgOutputSize,
+            avgReductionPercent,
+            avgDuration,
+            slowestDuration,
+        };
+    }
+    /**
+     * Get recent validation results
+     */
+    getRecent(limit = 10) {
+        const items = this.buffer.toArray();
+        return items.slice(-limit);
+    }
+    /**
+     * Clear all metrics
+     */
+    clear() {
+        this.buffer.clear();
+        this.asyncBuffer.clear();
+    }
+    recordBatch(items) {
+        // Aggregate batch metrics
+        const metrics = this.getMetrics();
+        this.metricsCallback(metrics);
+    }
+}
+exports.MetricsBuffer = MetricsBuffer;

package/dist/core/sampler.d.ts

@@ -0,0 +1,125 @@
+/**
+ * payload-guard — Adaptive Sampling System
+ * Dynamic sampling rate adjustment based on traffic
+ *
+ * @packageDocumentation
+ */
+/**
+ * Sampling result
+ */
+export interface SamplingResult {
+    shouldSample: boolean;
+    rate: number;
+    reason: string;
+}
+/**
+ * Adaptive Sampler
+ * Automatically adjusts sampling rate based on traffic volume
+ */
+export declare class AdaptiveSampler {
+    private baseRate;
+    private currentRate;
+    private minRate;
+    private maxRate;
+    private requestCounts;
+    private windowSize;
+    private lastAdjustment;
+    private adjustmentInterval;
+    constructor(options?: {
+        baseRate?: number;
+        minRate?: number;
+        maxRate?: number;
+        windowSize?: number;
+        adjustmentInterval?: number;
+    });
+    /**
+     * Check if a request should be sampled
+     */
+    shouldSample(priority?: number): SamplingResult;
+    /**
+     * Record a request
+     */
+    recordRequest(sampled: boolean): void;
+    /**
+     * Get current sampling rate
+     */
+    getRate(): number;
+    /**
+     * Get request statistics
+     */
+    getStats(): {
+        currentRate: number;
+        baseRate: number;
+        avgRequestsPerWindow: number;
+        totalRequests: number;
+    };
+    /**
+     * Reset to base rate
+     */
+    reset(): void;
+    /**
+     * Manually set sampling rate
+     */
+    setRate(rate: number): void;
+    private getWindowIndex;
+    private adjustRate;
+}
+/**
+ * Time-based sampler
+ * Samples requests at specific time intervals
+ */
+export declare class TimeBasedSampler {
+    private interval;
+    private lastSample;
+    private sampleDuration;
+    constructor(options?: {
+        interval?: number;
+        sampleDuration?: number;
+    });
+    /**
+     * Check if currently in sampling window
+     */
+    shouldSample(): boolean;
+    /**
+     * Get time until next sample
+     */
+    getTimeUntilNextSample(): number;
+}
+/**
+ * Error-based sampler
+ * Increases sampling rate when errors are detected
+ */
+export declare class ErrorBasedSampler {
+    private baseRate;
+    private errorRate;
+    private errorMultiplier;
+    private errorCount;
+    private requestCount;
+    private windowMs;
+    private windowStart;
+    constructor(options?: {
+        baseRate?: number;
+        errorMultiplier?: number;
+        windowMs?: number;
+    });
+    /**
+     * Check if should sample
+     */
+    shouldSample(): SamplingResult;
+    /**
+     * Record a request
+     */
+    recordRequest(isError: boolean): void;
+    /**
+     * Get error statistics
+     */
+    getStats(): {
+        errorRate: number;
+        baseRate: number;
+        errorCount: number;
+        requestCount: number;
+        errorPercent: number;
+    };
+    private checkWindow;
+    private updateErrorRate;
+}