ml-cache 1.0.0

package/dist/utils/helpers.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * @fileoverview Helper utilities for ml-cache SDK
+ * @module ml-cache/utils/helpers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEventId = generateEventId;
+exports.generateTimestamp = generateTimestamp;
+exports.generateBatchId = generateBatchId;
+exports.createEventMetadata = createEventMetadata;
+exports.enrichEvent = enrichEvent;
+exports.generateS3Key = generateS3Key;
+exports.generateGlacierDescription = generateGlacierDescription;
+exports.serializeEventsToNDJSON = serializeEventsToNDJSON;
+exports.deserializeEventsFromNDJSON = deserializeEventsFromNDJSON;
+exports.calculateEventsSize = calculateEventsSize;
+exports.calculateRetryDelay = calculateRetryDelay;
+exports.sleep = sleep;
+exports.chunk = chunk;
+exports.deepClone = deepClone;
+exports.safeStringify = safeStringify;
+const crypto_1 = require("crypto");
+const constants_1 = require("../constants");
+/**
+ * Generates a unique event ID using UUID v4
+ * @returns {string} Unique event ID
+ */
+function generateEventId() {
+    return (0, crypto_1.randomUUID)();
+}
+/**
+ * Generates an ISO 8601 timestamp for the current time
+ * @returns {string} ISO 8601 timestamp
+ */
+function generateTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Generates a unique batch ID
+ * @returns {string} Unique batch ID
+ */
+function generateBatchId() {
+    return `batch_${Date.now()}_${(0, crypto_1.randomUUID)().slice(0, 8)}`;
+}
+/**
+ * Creates event metadata
+ * @param {Object} options - Metadata options
+ * @param {string} [options.sourceApp] - Source application name
+ * @param {string} [options.environment] - Environment name
+ * @param {string} [options.batchId] - Batch ID
+ * @param {number} [options.retryCount] - Retry attempt count
+ * @returns {EventMetadata} Event metadata object
+ */
+function createEventMetadata(options) {
+    return {
+        sdkVersion: constants_1.SDK_VERSION,
+        sourceApp: options.sourceApp,
+        environment: options.environment,
+        batchId: options.batchId,
+        retryCount: options.retryCount,
+    };
+}
+/**
+ * Enriches an event with auto-generated fields
+ * @param {MLCacheEvent} event - Event to enrich
+ * @param {Object} options - Enrichment options
+ * @param {string} [options.sourceApp] - Source application name
+ * @param {string} [options.environment] - Environment name
+ * @returns {MLCacheEvent} Enriched event
+ */
+function enrichEvent(event, options = {}) {
+    return {
+        ...event,
+        eventId: event.eventId || generateEventId(),
+        timestamp: event.timestamp || generateTimestamp(),
+        metadata: {
+            ...createEventMetadata(options),
+            ...event.metadata,
+        },
+    };
+}
+/**
+ * Generates an S3 object key for an event or batch
+ * @param {Object} options - Key generation options
+ * @param {string} [options.prefix] - S3 prefix
+ * @param {Date} [options.date] - Date for partitioning
+ * @param {string} [options.eventId] - Event ID
+ * @param {string} [options.batchId] - Batch ID
+ * @param {string} [options.extension] - File extension
+ * @returns {string} S3 object key
+ */
+function generateS3Key(options) {
+    const prefix = options.prefix || constants_1.DEFAULT_S3_PREFIX;
+    const date = options.date || new Date();
+    const extension = options.extension || 'ndjson';
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    const hour = String(date.getUTCHours()).padStart(2, '0');
+    const identifier = options.batchId || options.eventId || generateEventId();
+    return `${prefix}/${year}/${month}/${day}/${hour}/${identifier}.${extension}`;
+}
+/**
+ * Generates a Glacier archive description
+ * @param {Object} options - Description options
+ * @param {string} [options.batchId] - Batch ID
+ * @param {number} [options.eventCount] - Number of events in archive
+ * @param {Date} [options.date] - Archive date
+ * @returns {string} Archive description
+ */
+function generateGlacierDescription(options) {
+    const date = options.date || new Date();
+    const parts = [
+        'ml-cache-events',
+        date.toISOString().slice(0, 10),
+        options.batchId || generateBatchId(),
+    ];
+    if (options.eventCount !== undefined) {
+        parts.push(`count:${options.eventCount}`);
+    }
+    return parts.join('_');
+}
+/**
+ * Serializes events to NDJSON format
+ * @param {MLCacheEvent[]} events - Events to serialize
+ * @returns {string} NDJSON string
+ */
+function serializeEventsToNDJSON(events) {
+    return events.map((event) => JSON.stringify(event)).join('\n');
+}
+/**
+ * Deserializes events from NDJSON format
+ * @param {string} ndjson - NDJSON string
+ * @returns {MLCacheEvent[]} Parsed events
+ */
+function deserializeEventsFromNDJSON(ndjson) {
+    return ndjson
+        .split('\n')
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Calculates the size of serialized events in bytes
+ * @param {MLCacheEvent[]} events - Events to measure
+ * @returns {number} Size in bytes
+ */
+function calculateEventsSize(events) {
+    const serialized = serializeEventsToNDJSON(events);
+    return Buffer.byteLength(serialized, 'utf8');
+}
+/**
+ * Calculates retry delay with optional exponential backoff
+ * @param {number} attempt - Current attempt number (0-indexed)
+ * @param {number} initialDelayMs - Initial delay in milliseconds
+ * @param {number} maxDelayMs - Maximum delay in milliseconds
+ * @param {boolean} exponential - Use exponential backoff
+ * @returns {number} Delay in milliseconds
+ */
+function calculateRetryDelay(attempt, initialDelayMs, maxDelayMs, exponential) {
+    if (!exponential) {
+        return Math.min(initialDelayMs, maxDelayMs);
+    }
+    const delay = initialDelayMs * Math.pow(2, attempt);
+    const jitter = Math.random() * 0.1 * delay;
+    return Math.min(delay + jitter, maxDelayMs);
+}
+/**
+ * Sleeps for a specified duration
+ * @param {number} ms - Duration in milliseconds
+ * @returns {Promise<void>} Promise that resolves after the delay
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Chunks an array into smaller arrays
+ * @template T
+ * @param {T[]} array - Array to chunk
+ * @param {number} size - Chunk size
+ * @returns {T[][]} Array of chunks
+ */
+function chunk(array, size) {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+}
+/**
+ * Deep clones an object
+ * @template T
+ * @param {T} obj - Object to clone
+ * @returns {T} Cloned object
+ */
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+/**
+ * Safely stringifies an object, handling circular references
+ * @param {unknown} obj - Object to stringify
+ * @returns {string} JSON string
+ */
+function safeStringify(obj) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (_key, value) => {
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                return '[Circular]';
+            }
+            seen.add(value);
+        }
+        return value;
+    });
+}
+//# sourceMappingURL=helpers.js.map

package/dist/utils/helpers.js.map

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

package/dist/utils/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Utils barrel export
+ * @module ml-cache/utils
+ */
+export { Logger, defaultLogger } from './logger';
+export { ValidationError, validateConfig, validateEvent, validateEventType, validateEventProperties, isValidTimestamp, isValidUUID } from './validator';
+export { generateEventId, generateTimestamp, generateBatchId, createEventMetadata, enrichEvent, generateS3Key, generateGlacierDescription, serializeEventsToNDJSON, deserializeEventsFromNDJSON, calculateEventsSize, calculateRetryDelay, sleep, chunk, deepClone, safeStringify, } from './helpers';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxJ,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,0BAA0B,EAC1B,uBAAuB,EACvB,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,EACL,KAAK,EACL,SAAS,EACT,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @fileoverview Utils barrel export
+ * @module ml-cache/utils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeStringify = exports.deepClone = exports.chunk = exports.sleep = exports.calculateRetryDelay = exports.calculateEventsSize = exports.deserializeEventsFromNDJSON = exports.serializeEventsToNDJSON = exports.generateGlacierDescription = exports.generateS3Key = exports.enrichEvent = exports.createEventMetadata = exports.generateBatchId = exports.generateTimestamp = exports.generateEventId = exports.isValidUUID = exports.isValidTimestamp = exports.validateEventProperties = exports.validateEventType = exports.validateEvent = exports.validateConfig = exports.ValidationError = exports.defaultLogger = exports.Logger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+Object.defineProperty(exports, "defaultLogger", { enumerable: true, get: function () { return logger_1.defaultLogger; } });
+var validator_1 = require("./validator");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return validator_1.ValidationError; } });
+Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return validator_1.validateConfig; } });
+Object.defineProperty(exports, "validateEvent", { enumerable: true, get: function () { return validator_1.validateEvent; } });
+Object.defineProperty(exports, "validateEventType", { enumerable: true, get: function () { return validator_1.validateEventType; } });
+Object.defineProperty(exports, "validateEventProperties", { enumerable: true, get: function () { return validator_1.validateEventProperties; } });
+Object.defineProperty(exports, "isValidTimestamp", { enumerable: true, get: function () { return validator_1.isValidTimestamp; } });
+Object.defineProperty(exports, "isValidUUID", { enumerable: true, get: function () { return validator_1.isValidUUID; } });
+var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "generateEventId", { enumerable: true, get: function () { return helpers_1.generateEventId; } });
+Object.defineProperty(exports, "generateTimestamp", { enumerable: true, get: function () { return helpers_1.generateTimestamp; } });
+Object.defineProperty(exports, "generateBatchId", { enumerable: true, get: function () { return helpers_1.generateBatchId; } });
+Object.defineProperty(exports, "createEventMetadata", { enumerable: true, get: function () { return helpers_1.createEventMetadata; } });
+Object.defineProperty(exports, "enrichEvent", { enumerable: true, get: function () { return helpers_1.enrichEvent; } });
+Object.defineProperty(exports, "generateS3Key", { enumerable: true, get: function () { return helpers_1.generateS3Key; } });
+Object.defineProperty(exports, "generateGlacierDescription", { enumerable: true, get: function () { return helpers_1.generateGlacierDescription; } });
+Object.defineProperty(exports, "serializeEventsToNDJSON", { enumerable: true, get: function () { return helpers_1.serializeEventsToNDJSON; } });
+Object.defineProperty(exports, "deserializeEventsFromNDJSON", { enumerable: true, get: function () { return helpers_1.deserializeEventsFromNDJSON; } });
+Object.defineProperty(exports, "calculateEventsSize", { enumerable: true, get: function () { return helpers_1.calculateEventsSize; } });
+Object.defineProperty(exports, "calculateRetryDelay", { enumerable: true, get: function () { return helpers_1.calculateRetryDelay; } });
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return helpers_1.sleep; } });
+Object.defineProperty(exports, "chunk", { enumerable: true, get: function () { return helpers_1.chunk; } });
+Object.defineProperty(exports, "deepClone", { enumerable: true, get: function () { return helpers_1.deepClone; } });
+Object.defineProperty(exports, "safeStringify", { enumerable: true, get: function () { return helpers_1.safeStringify; } });
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,mCAAiD;AAAxC,gGAAA,MAAM,OAAA;AAAE,uGAAA,aAAa,OAAA;AAC9B,yCAAwJ;AAA/I,4GAAA,eAAe,OAAA;AAAE,2GAAA,cAAc,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,8GAAA,iBAAiB,OAAA;AAAE,oHAAA,uBAAuB,OAAA;AAAE,6GAAA,gBAAgB,OAAA;AAAE,wGAAA,WAAW,OAAA;AAClI,qCAgBmB;AAfjB,0GAAA,eAAe,OAAA;AACf,4GAAA,iBAAiB,OAAA;AACjB,0GAAA,eAAe,OAAA;AACf,8GAAA,mBAAmB,OAAA;AACnB,sGAAA,WAAW,OAAA;AACX,wGAAA,aAAa,OAAA;AACb,qHAAA,0BAA0B,OAAA;AAC1B,kHAAA,uBAAuB,OAAA;AACvB,sHAAA,2BAA2B,OAAA;AAC3B,8GAAA,mBAAmB,OAAA;AACnB,8GAAA,mBAAmB,OAAA;AACnB,gGAAA,KAAK,OAAA;AACL,gGAAA,KAAK,OAAA;AACL,oGAAA,SAAS,OAAA;AACT,wGAAA,aAAa,OAAA"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Logger utility for ml-cache SDK
+ * @module ml-cache/utils/logger
+ */
+import type { LogLevel, LogConfig, LoggerFunction } from '../types';
+/**
+ * Logger class for SDK internal logging
+ * @class Logger
+ */
+export declare class Logger {
+    /** @private */
+    private config;
+    /** @private */
+    private prefix;
+    /**
+     * Creates a new Logger instance
+     * @param {Partial<LogConfig>} [config] - Logger configuration
+     * @param {string} [prefix] - Log message prefix
+     */
+    constructor(config?: Partial<LogConfig>, prefix?: string);
+    /**
+     * Checks if a log level should be output
+     * @private
+     * @param {LogLevel} level - Log level to check
+     * @returns {boolean} Whether the level should be logged
+     */
+    private shouldLog;
+    /**
+     * Formats a log message with timestamp and prefix
+     * @private
+     * @param {LogLevel} level - Log level
+     * @param {string} message - Log message
+     * @returns {string} Formatted message
+     */
+    private formatMessage;
+    /**
+     * Outputs a log message
+     * @private
+     * @param {LogLevel} level - Log level
+     * @param {string} message - Log message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    private log;
+    /**
+     * Gets the appropriate console method for a log level
+     * @private
+     * @param {LogLevel} level - Log level
+     * @returns {Function} Console method
+     */
+    private getConsoleMethod;
+    /**
+     * Logs a debug message
+     * @param {string} message - Debug message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Logs an info message
+     * @param {string} message - Info message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    info(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Logs a warning message
+     * @param {string} message - Warning message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Logs an error message
+     * @param {string} message - Error message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    error(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Updates logger configuration
+     * @param {Partial<LogConfig>} config - New configuration
+     */
+    setConfig(config: Partial<LogConfig>): void;
+    /**
+     * Sets the log level
+     * @param {LogLevel} level - New log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Enables logging
+     */
+    enable(): void;
+    /**
+     * Disables logging
+     */
+    disable(): void;
+    /**
+     * Sets a custom logger function
+     * @param {LoggerFunction} logger - Custom logger function
+     */
+    setCustomLogger(logger: LoggerFunction): void;
+    /**
+     * Creates a child logger with a new prefix
+     * @param {string} childPrefix - Additional prefix for child logger
+     * @returns {Logger} New logger instance
+     */
+    child(childPrefix: string): Logger;
+}
+/**
+ * Default logger instance
+ * @constant
+ */
+export declare const defaultLogger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAepE;;;GAGG;AACH,qBAAa,MAAM;IACjB,eAAe;IACf,OAAO,CAAC,MAAM,CAAY;IAE1B,eAAe;IACf,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,GAAE,MAAqB;IAKtE;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAOjB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAKrB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG;IAwBX;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI;IAI3C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAI7C;;;;OAIG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;CAGnC;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAe,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * @fileoverview Logger utility for ml-cache SDK
+ * @module ml-cache/utils/logger
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultLogger = exports.Logger = void 0;
+const constants_1 = require("../constants");
+/**
+ * Log level priority map (lower = more verbose)
+ * @constant
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+/**
+ * Logger class for SDK internal logging
+ * @class Logger
+ */
+class Logger {
+    /**
+     * Creates a new Logger instance
+     * @param {Partial<LogConfig>} [config] - Logger configuration
+     * @param {string} [prefix] - Log message prefix
+     */
+    constructor(config, prefix = '[ml-cache]') {
+        this.config = { ...constants_1.DEFAULT_LOG_CONFIG, ...config };
+        this.prefix = prefix;
+    }
+    /**
+     * Checks if a log level should be output
+     * @private
+     * @param {LogLevel} level - Log level to check
+     * @returns {boolean} Whether the level should be logged
+     */
+    shouldLog(level) {
+        if (!this.config.enabled) {
+            return false;
+        }
+        return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[this.config.level];
+    }
+    /**
+     * Formats a log message with timestamp and prefix
+     * @private
+     * @param {LogLevel} level - Log level
+     * @param {string} message - Log message
+     * @returns {string} Formatted message
+     */
+    formatMessage(level, message) {
+        const timestamp = new Date().toISOString();
+        return `${timestamp} ${this.prefix} [${level.toUpperCase()}] ${message}`;
+    }
+    /**
+     * Outputs a log message
+     * @private
+     * @param {LogLevel} level - Log level
+     * @param {string} message - Log message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    log(level, message, data) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        if (this.config.customLogger) {
+            this.config.customLogger(level, message, data);
+            return;
+        }
+        const formattedMessage = this.formatMessage(level, message);
+        const consoleMethod = this.getConsoleMethod(level);
+        if (data) {
+            consoleMethod(formattedMessage, data);
+        }
+        else {
+            consoleMethod(formattedMessage);
+        }
+    }
+    /**
+     * Gets the appropriate console method for a log level
+     * @private
+     * @param {LogLevel} level - Log level
+     * @returns {Function} Console method
+     */
+    getConsoleMethod(level) {
+        switch (level) {
+            case 'debug':
+                return console.debug.bind(console);
+            case 'info':
+                return console.info.bind(console);
+            case 'warn':
+                return console.warn.bind(console);
+            case 'error':
+                return console.error.bind(console);
+            default:
+                return console.log.bind(console);
+        }
+    }
+    /**
+     * Logs a debug message
+     * @param {string} message - Debug message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    /**
+     * Logs an info message
+     * @param {string} message - Info message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    /**
+     * Logs a warning message
+     * @param {string} message - Warning message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    /**
+     * Logs an error message
+     * @param {string} message - Error message
+     * @param {Record<string, unknown>} [data] - Additional data
+     */
+    error(message, data) {
+        this.log('error', message, data);
+    }
+    /**
+     * Updates logger configuration
+     * @param {Partial<LogConfig>} config - New configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Sets the log level
+     * @param {LogLevel} level - New log level
+     */
+    setLevel(level) {
+        this.config.level = level;
+    }
+    /**
+     * Enables logging
+     */
+    enable() {
+        this.config.enabled = true;
+    }
+    /**
+     * Disables logging
+     */
+    disable() {
+        this.config.enabled = false;
+    }
+    /**
+     * Sets a custom logger function
+     * @param {LoggerFunction} logger - Custom logger function
+     */
+    setCustomLogger(logger) {
+        this.config.customLogger = logger;
+    }
+    /**
+     * Creates a child logger with a new prefix
+     * @param {string} childPrefix - Additional prefix for child logger
+     * @returns {Logger} New logger instance
+     */
+    child(childPrefix) {
+        return new Logger(this.config, `${this.prefix}:${childPrefix}`);
+    }
+}
+exports.Logger = Logger;
+/**
+ * Default logger instance
+ * @constant
+ */
+exports.defaultLogger = new Logger();
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/validator.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Validation utilities for ml-cache SDK
+ * @module ml-cache/utils/validator
+ */
+import type { MLCacheConfig, MLCacheEvent, S3Config, GlacierConfig, AWSCredentials } from '../types';
+/**
+ * Validation error class
+ * @class ValidationError
+ * @extends Error
+ */
+export declare class ValidationError extends Error {
+    /** Error code */
+    code: string;
+    /** Field that failed validation */
+    field?: string;
+    /**
+     * Creates a new ValidationError
+     * @param {string} message - Error message
+     * @param {string} [field] - Field that failed validation
+     */
+    constructor(message: string, field?: string);
+}
+/**
+ * Validates AWS credentials
+ * @param {AWSCredentials} credentials - AWS credentials to validate
+ * @throws {ValidationError} If credentials are invalid
+ */
+export declare function validateCredentials(credentials: AWSCredentials): void;
+/**
+ * Validates S3 configuration
+ * @param {S3Config} config - S3 configuration to validate
+ * @throws {ValidationError} If configuration is invalid
+ */
+export declare function validateS3Config(config: S3Config): void;
+/**
+ * Validates Glacier configuration
+ * @param {GlacierConfig} config - Glacier configuration to validate
+ * @throws {ValidationError} If configuration is invalid
+ */
+export declare function validateGlacierConfig(config: GlacierConfig): void;
+/**
+ * Validates complete SDK configuration
+ * @param {MLCacheConfig} config - SDK configuration to validate
+ * @throws {ValidationError} If configuration is invalid
+ */
+export declare function validateConfig(config: MLCacheConfig): void;
+/**
+ * Validates an event type string
+ * @param {string} eventType - Event type to validate
+ * @throws {ValidationError} If event type is invalid
+ */
+export declare function validateEventType(eventType: string): void;
+/**
+ * Validates event properties
+ * @param {Record<string, unknown>} properties - Properties to validate
+ * @throws {ValidationError} If properties are invalid
+ */
+export declare function validateEventProperties(properties: Record<string, unknown>): void;
+/**
+ * Validates a complete event
+ * @param {MLCacheEvent} event - Event to validate
+ * @throws {ValidationError} If event is invalid
+ */
+export declare function validateEvent(event: MLCacheEvent): void;
+/**
+ * Checks if a value is a valid ISO 8601 timestamp
+ * @param {string} timestamp - Timestamp to validate
+ * @returns {boolean} Whether the timestamp is valid
+ */
+export declare function isValidTimestamp(timestamp: string): boolean;
+/**
+ * Checks if a value is a valid UUID
+ * @param {string} uuid - UUID to validate
+ * @returns {boolean} Whether the UUID is valid
+ */
+export declare function isValidUUID(uuid: string): boolean;
+//# sourceMappingURL=validator.d.ts.map

package/dist/utils/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/utils/validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,cAAc,EACf,MAAM,UAAU,CAAC;AASlB;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IAEb,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAM5C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,cAAc,GAAG,IAAI,CA+BrE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAsBvD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAkBjE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CA8E1D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAqBzD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,IAAI,CAoBN;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAkBvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQjD"}