ml-cache 1.0.0

package/dist/esm/constants.js

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Constants and default values for ml-cache SDK
+ * @module ml-cache/constants
+ */
+/* ============================================================================
+ * SDK Information
+ * ============================================================================ */
+/**
+ * Current SDK version
+ * @constant
+ */
+export const SDK_VERSION = '1.0.0';
+/**
+ * SDK name identifier
+ * @constant
+ */
+export const SDK_NAME = 'ml-cache';
+/* ============================================================================
+ * Default Configurations
+ * ============================================================================ */
+/**
+ * Default batch configuration
+ * @constant
+ */
+export const DEFAULT_BATCH_CONFIG = {
+    /** Maximum 100 events per batch */
+    maxSize: 100,
+    /** Flush every 30 seconds */
+    maxWaitMs: 30000,
+    /** Batching enabled by default */
+    enabled: true,
+};
+/**
+ * Default retry configuration
+ * @constant
+ */
+export const DEFAULT_RETRY_CONFIG = {
+    /** Maximum 3 retry attempts */
+    maxRetries: 3,
+    /** Start with 1 second delay */
+    initialDelayMs: 1000,
+    /** Maximum 30 second delay */
+    maxDelayMs: 30000,
+    /** Use exponential backoff */
+    exponentialBackoff: true,
+};
+/**
+ * Default logging configuration
+ * @constant
+ */
+export const DEFAULT_LOG_CONFIG = {
+    /** Default to info level */
+    level: 'info',
+    /** Logging enabled by default */
+    enabled: true,
+    /** No custom logger by default */
+    customLogger: undefined,
+};
+/**
+ * Default S3 storage class for long-term ML data storage
+ * @constant
+ */
+export const DEFAULT_S3_STORAGE_CLASS = 'GLACIER';
+/**
+ * Default Glacier account ID (uses current account)
+ * @constant
+ */
+export const DEFAULT_GLACIER_ACCOUNT_ID = '-';
+/* ============================================================================
+ * Storage Constants
+ * ============================================================================ */
+/**
+ * Maximum size of a single event payload in bytes (256 KB)
+ * @constant
+ */
+export const MAX_EVENT_SIZE_BYTES = 256 * 1024;
+/**
+ * Maximum size of a batch payload in bytes (5 MB for S3 PutObject)
+ * @constant
+ */
+export const MAX_BATCH_SIZE_BYTES = 5 * 1024 * 1024;
+/**
+ * Minimum size for S3 multipart upload (5 MB)
+ * @constant
+ */
+export const S3_MULTIPART_THRESHOLD_BYTES = 5 * 1024 * 1024;
+/**
+ * Glacier archive description prefix
+ * @constant
+ */
+export const GLACIER_ARCHIVE_PREFIX = 'ml-cache-events';
+/**
+ * S3 object key date format
+ * @constant
+ */
+export const S3_KEY_DATE_FORMAT = 'YYYY/MM/DD';
+/**
+ * Default S3 object prefix
+ * @constant
+ */
+export const DEFAULT_S3_PREFIX = 'ml-cache-events';
+/* ============================================================================
+ * Event Constants
+ * ============================================================================ */
+/**
+ * Reserved event property names that cannot be overwritten
+ * @constant
+ */
+export const RESERVED_EVENT_PROPERTIES = [
+    'eventId',
+    'timestamp',
+    'eventType',
+    'metadata',
+];
+/**
+ * Valid event type pattern (alphanumeric with underscores)
+ * @constant
+ */
+export const EVENT_TYPE_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/**
+ * Maximum event type length
+ * @constant
+ */
+export const MAX_EVENT_TYPE_LENGTH = 128;
+/**
+ * Maximum property key length
+ * @constant
+ */
+export const MAX_PROPERTY_KEY_LENGTH = 256;
+/* ============================================================================
+ * Timing Constants
+ * ============================================================================ */
+/**
+ * Health check interval in milliseconds (5 minutes)
+ * @constant
+ */
+export const HEALTH_CHECK_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * Connection timeout in milliseconds (30 seconds)
+ * @constant
+ */
+export const CONNECTION_TIMEOUT_MS = 30000;
+/**
+ * Request timeout in milliseconds (2 minutes)
+ * @constant
+ */
+export const REQUEST_TIMEOUT_MS = 2 * 60 * 1000;
+/**
+ * Shutdown grace period in milliseconds (10 seconds)
+ * @constant
+ */
+export const SHUTDOWN_GRACE_PERIOD_MS = 10000;
+/* ============================================================================
+ * Error Codes
+ * ============================================================================ */
+/**
+ * SDK error codes
+ * @constant
+ */
+export const ERROR_CODES = {
+    /** Configuration error */
+    CONFIG_ERROR: 'ML_CACHE_CONFIG_ERROR',
+    /** Validation error */
+    VALIDATION_ERROR: 'ML_CACHE_VALIDATION_ERROR',
+    /** S3 storage error */
+    S3_ERROR: 'ML_CACHE_S3_ERROR',
+    /** Glacier storage error */
+    GLACIER_ERROR: 'ML_CACHE_GLACIER_ERROR',
+    /** Network error */
+    NETWORK_ERROR: 'ML_CACHE_NETWORK_ERROR',
+    /** Timeout error */
+    TIMEOUT_ERROR: 'ML_CACHE_TIMEOUT_ERROR',
+    /** Queue full error */
+    QUEUE_FULL_ERROR: 'ML_CACHE_QUEUE_FULL_ERROR',
+    /** Event too large error */
+    EVENT_TOO_LARGE_ERROR: 'ML_CACHE_EVENT_TOO_LARGE_ERROR',
+    /** Batch error */
+    BATCH_ERROR: 'ML_CACHE_BATCH_ERROR',
+    /** Shutdown error */
+    SHUTDOWN_ERROR: 'ML_CACHE_SHUTDOWN_ERROR',
+    /** Unknown error */
+    UNKNOWN_ERROR: 'ML_CACHE_UNKNOWN_ERROR',
+};
+/* ============================================================================
+ * Queue Constants
+ * ============================================================================ */
+/**
+ * Maximum queue size (number of events)
+ * @constant
+ */
+export const MAX_QUEUE_SIZE = 10000;
+/**
+ * Queue warning threshold (80% of max)
+ * @constant
+ */
+export const QUEUE_WARNING_THRESHOLD = 0.8;
+/* ============================================================================
+ * Content Types
+ * ============================================================================ */
+/**
+ * Content type for stored events (NDJSON)
+ * @constant
+ */
+export const CONTENT_TYPE_NDJSON = 'application/x-ndjson';
+/**
+ * Content type for compressed events
+ * @constant
+ */
+export const CONTENT_TYPE_GZIP = 'application/gzip';
+/* ============================================================================
+ * Environment Variables
+ * ============================================================================ */
+/**
+ * Environment variable names for configuration
+ * @constant
+ */
+export const ENV_VARS = {
+    /** AWS access key ID */
+    AWS_ACCESS_KEY_ID: 'AWS_ACCESS_KEY_ID',
+    /** AWS secret access key */
+    AWS_SECRET_ACCESS_KEY: 'AWS_SECRET_ACCESS_KEY',
+    /** AWS session token */
+    AWS_SESSION_TOKEN: 'AWS_SESSION_TOKEN',
+    /** AWS region */
+    AWS_REGION: 'AWS_REGION',
+    /** S3 bucket name */
+    ML_CACHE_S3_BUCKET: 'ML_CACHE_S3_BUCKET',
+    /** Glacier vault name */
+    ML_CACHE_GLACIER_VAULT: 'ML_CACHE_GLACIER_VAULT',
+    /** Debug mode */
+    ML_CACHE_DEBUG: 'ML_CACHE_DEBUG',
+};
+//# sourceMappingURL=constants.js.map

package/dist/esm/constants.js.map

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

package/dist/esm/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview ML Cache SDK - Store business events for future ML training
+ * @module ml-cache
+ * @description
+ * ML Cache is a TypeScript SDK designed to collect and store business/product events
+ * in cold storage (Amazon S3 Glacier) for future machine learning model training.
+ *
+ * The core idea is simple: ML training costs are decreasing exponentially, but data
+ * collection opportunities are fleeting. Store your data now, train your models later.
+ *
+ * @example
+ * ```typescript
+ * import { MLCacheClient } from 'ml-cache';
+ *
+ * const client = new MLCacheClient({
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ *   s3: {
+ *     bucket: 'my-ml-data-bucket',
+ *     region: 'us-east-1',
+ *     storageClass: 'GLACIER',
+ *   },
+ *   storageMode: 'S3',
+ *   sourceApp: 'my-app',
+ *   environment: 'production',
+ * });
+ *
+ * // Track events
+ * await client.track({
+ *   eventType: 'purchase',
+ *   properties: {
+ *     productId: 'SKU-123',
+ *     amount: 99.99,
+ *     currency: 'USD',
+ *   },
+ *   context: {
+ *     user: { userId: 'user-456' },
+ *   },
+ * });
+ *
+ * // Graceful shutdown
+ * await client.shutdown();
+ * ```
+ *
+ * @author Nicolas Mondain
+ * @license MIT
+ * @see {@link https://github.com/nicolasmondain/ml-cache}
+ */
+export { MLCacheClient } from './client';
+export type { AWSCredentials, S3Config, GlacierConfig, S3StorageClass, BaseEvent, UserContext, DeviceContext, PageContext, CampaignContext, EventContext, MLCacheEvent, EventMetadata, StoredEvent, BatchConfig, RetryConfig, LogConfig, LogLevel, LoggerFunction, StorageMode, MLCacheConfig, TrackResult, FlushResult, HealthStatus, EventCallback, ErrorCallback, FlushCallback, } from './types';
+export { SDK_VERSION, SDK_NAME, DEFAULT_BATCH_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_LOG_CONFIG, DEFAULT_S3_STORAGE_CLASS, MAX_EVENT_SIZE_BYTES, MAX_BATCH_SIZE_BYTES, MAX_QUEUE_SIZE, ERROR_CODES, ENV_VARS, } from './constants';
+export { Logger, ValidationError, validateConfig, validateEvent, generateEventId, generateTimestamp, generateBatchId, enrichEvent, serializeEventsToNDJSON, deserializeEventsFromNDJSON, } from './utils';
+export { S3Storage, type S3StorageResult } from './storage/s3-storage';
+export { GlacierStorage, type GlacierStorageResult } from './storage/glacier-storage';
+export { EventQueue, type BatchReadyCallback } from './queue';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAMzC,YAAY,EAEV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,cAAc,EAGd,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EAGX,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACR,cAAc,EACd,WAAW,EACX,aAAa,EAGb,WAAW,EACX,WAAW,EACX,YAAY,EAGZ,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAC;AAMjB,OAAO,EACL,WAAW,EACX,QAAQ,EACR,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,QAAQ,GACT,MAAM,aAAa,CAAC;AAMrB,OAAO,EACL,MAAM,EACN,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAMjB,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAMtF,OAAO,EAAE,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC"}

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;kFAEkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA4CzC;;kFAEkF;AAElF,OAAO,EACL,WAAW,EACX,QAAQ,EACR,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,QAAQ,GACT,MAAM,aAAa,CAAC;AAErB;;kFAEkF;AAElF,OAAO,EACL,MAAM,EACN,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAEjB;;kFAEkF;AAElF,OAAO,EAAE,SAAS,EAAwB,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,cAAc,EAA6B,MAAM,2BAA2B,CAAC;AAEtF;;kFAEkF;AAElF,OAAO,EAAE,UAAU,EAA2B,MAAM,SAAS,CAAC"}

package/dist/esm/queue.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Event queue for batching and buffering
+ * @module ml-cache/queue
+ */
+import type { MLCacheEvent, BatchConfig } from './types';
+import { Logger } from './utils';
+/**
+ * Batch ready callback type
+ * @typedef BatchReadyCallback
+ */
+export type BatchReadyCallback = (events: MLCacheEvent[], batchId: string) => Promise<void>;
+/**
+ * Event queue for batching events before storage
+ * @class EventQueue
+ */
+export declare class EventQueue {
+    /** @private */
+    private queue;
+    /** @private */
+    private config;
+    /** @private */
+    private logger;
+    /** @private */
+    private flushTimer;
+    /** @private */
+    private onBatchReady;
+    /** @private */
+    private isFlushing;
+    /**
+     * Creates a new EventQueue instance
+     * @param {Partial<BatchConfig>} [config] - Batch configuration
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config?: Partial<BatchConfig>, logger?: Logger);
+    /**
+     * Sets the callback for when a batch is ready
+     * @param {BatchReadyCallback} callback - Callback function
+     */
+    setOnBatchReady(callback: BatchReadyCallback): void;
+    /**
+     * Adds an event to the queue
+     * @param {MLCacheEvent} event - Event to add
+     * @returns {boolean} Whether the event was added successfully
+     */
+    enqueue(event: MLCacheEvent): boolean;
+    /**
+     * Checks if a flush should be triggered
+     * @private
+     */
+    private checkFlush;
+    /**
+     * Starts the flush timer
+     * @private
+     */
+    private startFlushTimer;
+    /**
+     * Stops the flush timer
+     * @private
+     */
+    private stopFlushTimer;
+    /**
+     * Flushes the queue
+     * @returns {Promise<MLCacheEvent[]>} Flushed events
+     */
+    flush(): Promise<MLCacheEvent[]>;
+    /**
+     * Gets the current queue size
+     * @returns {number} Queue size
+     */
+    size(): number;
+    /**
+     * Checks if the queue is empty
+     * @returns {boolean} Whether the queue is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if the queue is full
+     * @returns {boolean} Whether the queue is full
+     */
+    isFull(): boolean;
+    /**
+     * Gets all events without removing them
+     * @returns {MLCacheEvent[]} All events in queue
+     */
+    peek(): MLCacheEvent[];
+    /**
+     * Clears the queue
+     * @returns {MLCacheEvent[]} Cleared events
+     */
+    clear(): MLCacheEvent[];
+    /**
+     * Updates the batch configuration
+     * @param {Partial<BatchConfig>} config - New configuration
+     */
+    setConfig(config: Partial<BatchConfig>): void;
+    /**
+     * Gets the current batch configuration
+     * @returns {BatchConfig} Current configuration
+     */
+    getConfig(): BatchConfig;
+    /**
+     * Destroys the queue
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/esm/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAE,MAAM,EAAmB,MAAM,SAAS,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,YAAY,EAAE,EACtB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;;GAGG;AACH,qBAAa,UAAU;IACrB,eAAe;IACf,OAAO,CAAC,KAAK,CAAsB;IAEnC,eAAe;IACf,OAAO,CAAC,MAAM,CAAc;IAE5B,eAAe;IACf,OAAO,CAAC,MAAM,CAAS;IAEvB,eAAe;IACf,OAAO,CAAC,UAAU,CAA+B;IAEjD,eAAe;IACf,OAAO,CAAC,YAAY,CAAmC;IAEvD,eAAe;IACf,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;OAIG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;IAK1D;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAInD;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IA8BrC;;;OAGG;IACH,OAAO,CAAC,UAAU;IASlB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAcvB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IA4CtC;;;OAGG;IACH,IAAI,IAAI,MAAM;IAId;;;OAGG;IACH,OAAO,IAAI,OAAO;IAIlB;;;OAGG;IACH,MAAM,IAAI,OAAO;IAIjB;;;OAGG;IACH,IAAI,IAAI,YAAY,EAAE;IAItB;;;OAGG;IACH,KAAK,IAAI,YAAY,EAAE;IAOvB;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAI7C;;;OAGG;IACH,SAAS,IAAI,WAAW;IAIxB;;OAEG;IACH,OAAO,IAAI,IAAI;CAKhB"}

package/dist/esm/queue.js

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview Event queue for batching and buffering
+ * @module ml-cache/queue
+ */
+import { DEFAULT_BATCH_CONFIG, MAX_QUEUE_SIZE, QUEUE_WARNING_THRESHOLD } from './constants';
+import { Logger, generateBatchId } from './utils';
+/**
+ * Event queue for batching events before storage
+ * @class EventQueue
+ */
+export class EventQueue {
+    /**
+     * Creates a new EventQueue instance
+     * @param {Partial<BatchConfig>} [config] - Batch configuration
+     * @param {Logger} [logger] - Logger instance
+     */
+    constructor(config, logger) {
+        /** @private */
+        this.queue = [];
+        /** @private */
+        this.flushTimer = null;
+        /** @private */
+        this.onBatchReady = null;
+        /** @private */
+        this.isFlushing = false;
+        this.config = { ...DEFAULT_BATCH_CONFIG, ...config };
+        this.logger = logger || new Logger();
+    }
+    /**
+     * Sets the callback for when a batch is ready
+     * @param {BatchReadyCallback} callback - Callback function
+     */
+    setOnBatchReady(callback) {
+        this.onBatchReady = callback;
+    }
+    /**
+     * Adds an event to the queue
+     * @param {MLCacheEvent} event - Event to add
+     * @returns {boolean} Whether the event was added successfully
+     */
+    enqueue(event) {
+        if (this.queue.length >= MAX_QUEUE_SIZE) {
+            this.logger.error('Queue is full, dropping event', {
+                eventId: event.eventId,
+                queueSize: this.queue.length,
+            });
+            return false;
+        }
+        this.queue.push(event);
+        if (this.queue.length / MAX_QUEUE_SIZE >= QUEUE_WARNING_THRESHOLD) {
+            this.logger.warn('Queue is approaching capacity', {
+                queueSize: this.queue.length,
+                maxSize: MAX_QUEUE_SIZE,
+            });
+        }
+        this.logger.debug('Event enqueued', {
+            eventId: event.eventId,
+            queueSize: this.queue.length,
+        });
+        if (this.config.enabled) {
+            this.checkFlush();
+        }
+        return true;
+    }
+    /**
+     * Checks if a flush should be triggered
+     * @private
+     */
+    checkFlush() {
+        if (this.queue.length >= this.config.maxSize) {
+            this.logger.debug('Queue reached max size, triggering flush');
+            void this.flush();
+        }
+        else if (!this.flushTimer && this.queue.length > 0) {
+            this.startFlushTimer();
+        }
+    }
+    /**
+     * Starts the flush timer
+     * @private
+     */
+    startFlushTimer() {
+        if (this.flushTimer) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            if (this.queue.length > 0) {
+                this.logger.debug('Flush timer triggered');
+                void this.flush();
+            }
+        }, this.config.maxWaitMs);
+    }
+    /**
+     * Stops the flush timer
+     * @private
+     */
+    stopFlushTimer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /**
+     * Flushes the queue
+     * @returns {Promise<MLCacheEvent[]>} Flushed events
+     */
+    async flush() {
+        if (this.isFlushing) {
+            this.logger.debug('Flush already in progress');
+            return [];
+        }
+        if (this.queue.length === 0) {
+            this.logger.debug('Queue is empty, nothing to flush');
+            return [];
+        }
+        this.isFlushing = true;
+        this.stopFlushTimer();
+        const eventsToFlush = this.queue.splice(0, this.config.maxSize);
+        const batchId = generateBatchId();
+        this.logger.info('Flushing queue', {
+            batchId,
+            eventCount: eventsToFlush.length,
+            remainingInQueue: this.queue.length,
+        });
+        try {
+            if (this.onBatchReady) {
+                await this.onBatchReady(eventsToFlush, batchId);
+            }
+        }
+        catch (error) {
+            this.logger.error('Error in batch ready callback', {
+                batchId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.queue.unshift(...eventsToFlush);
+        }
+        finally {
+            this.isFlushing = false;
+            if (this.queue.length > 0 && this.config.enabled) {
+                this.startFlushTimer();
+            }
+        }
+        return eventsToFlush;
+    }
+    /**
+     * Gets the current queue size
+     * @returns {number} Queue size
+     */
+    size() {
+        return this.queue.length;
+    }
+    /**
+     * Checks if the queue is empty
+     * @returns {boolean} Whether the queue is empty
+     */
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+    /**
+     * Checks if the queue is full
+     * @returns {boolean} Whether the queue is full
+     */
+    isFull() {
+        return this.queue.length >= MAX_QUEUE_SIZE;
+    }
+    /**
+     * Gets all events without removing them
+     * @returns {MLCacheEvent[]} All events in queue
+     */
+    peek() {
+        return [...this.queue];
+    }
+    /**
+     * Clears the queue
+     * @returns {MLCacheEvent[]} Cleared events
+     */
+    clear() {
+        this.stopFlushTimer();
+        const events = this.queue.splice(0);
+        this.logger.info('Queue cleared', { eventCount: events.length });
+        return events;
+    }
+    /**
+     * Updates the batch configuration
+     * @param {Partial<BatchConfig>} config - New configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Gets the current batch configuration
+     * @returns {BatchConfig} Current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Destroys the queue
+     */
+    destroy() {
+        this.stopFlushTimer();
+        this.queue = [];
+        this.onBatchReady = null;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/esm/queue.js.map

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