ml-cache 1.0.0

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

@@ -0,0 +1,337 @@
+/**
+ * @fileoverview Type definitions and interfaces for ml-cache SDK
+ * @module ml-cache/types
+ */
+/**
+ * AWS credentials configuration
+ * @interface AWSCredentials
+ */
+export interface AWSCredentials {
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /** Optional AWS session token for temporary credentials */
+    sessionToken?: string;
+}
+/**
+ * S3 storage configuration
+ * @interface S3Config
+ */
+export interface S3Config {
+    /** S3 bucket name for event storage */
+    bucket: string;
+    /** AWS region (e.g., 'us-east-1', 'eu-west-1') */
+    region: string;
+    /** Optional prefix/folder path for stored objects */
+    prefix?: string;
+    /** Optional S3 storage class (defaults to GLACIER) */
+    storageClass?: S3StorageClass;
+}
+/**
+ * Glacier storage configuration
+ * @interface GlacierConfig
+ */
+export interface GlacierConfig {
+    /** Glacier vault name */
+    vaultName: string;
+    /** AWS region for Glacier vault */
+    region: string;
+    /** Account ID (use '-' for current account) */
+    accountId?: string;
+}
+/**
+ * S3 storage class options
+ * @typedef S3StorageClass
+ */
+export type S3StorageClass = 'STANDARD' | 'REDUCED_REDUNDANCY' | 'STANDARD_IA' | 'ONEZONE_IA' | 'INTELLIGENT_TIERING' | 'GLACIER' | 'DEEP_ARCHIVE' | 'GLACIER_IR';
+/**
+ * Base event properties that all events must have
+ * @interface BaseEvent
+ */
+export interface BaseEvent {
+    /** Unique event identifier (auto-generated if not provided) */
+    eventId?: string;
+    /** Event timestamp (auto-generated if not provided) */
+    timestamp?: string;
+    /** Event type/name (e.g., 'page_view', 'purchase', 'signup') */
+    eventType: string;
+}
+/**
+ * User context information
+ * @interface UserContext
+ */
+export interface UserContext {
+    /** Unique user identifier */
+    userId?: string;
+    /** Anonymous/session identifier */
+    anonymousId?: string;
+    /** User traits/attributes */
+    traits?: Record<string, unknown>;
+}
+/**
+ * Device and browser context
+ * @interface DeviceContext
+ */
+export interface DeviceContext {
+    /** User agent string */
+    userAgent?: string;
+    /** IP address */
+    ip?: string;
+    /** Device type (mobile, desktop, tablet) */
+    deviceType?: string;
+    /** Operating system */
+    os?: string;
+    /** Browser name */
+    browser?: string;
+    /** Screen resolution */
+    screenResolution?: string;
+    /** Viewport size */
+    viewport?: string;
+    /** Device locale/language */
+    locale?: string;
+    /** Timezone */
+    timezone?: string;
+}
+/**
+ * Page/screen context
+ * @interface PageContext
+ */
+export interface PageContext {
+    /** Current page URL */
+    url?: string;
+    /** Page path */
+    path?: string;
+    /** Page title */
+    title?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Search/query string */
+    search?: string;
+}
+/**
+ * Campaign/UTM tracking context
+ * @interface CampaignContext
+ */
+export interface CampaignContext {
+    /** Campaign name (utm_campaign) */
+    name?: string;
+    /** Campaign source (utm_source) */
+    source?: string;
+    /** Campaign medium (utm_medium) */
+    medium?: string;
+    /** Campaign term (utm_term) */
+    term?: string;
+    /** Campaign content (utm_content) */
+    content?: string;
+}
+/**
+ * Complete event context
+ * @interface EventContext
+ */
+export interface EventContext {
+    /** User information */
+    user?: UserContext;
+    /** Device/browser information */
+    device?: DeviceContext;
+    /** Page/screen information */
+    page?: PageContext;
+    /** Campaign/marketing information */
+    campaign?: CampaignContext;
+    /** Application information */
+    app?: {
+        /** Application name */
+        name?: string;
+        /** Application version */
+        version?: string;
+        /** Build number */
+        build?: string;
+    };
+    /** Custom context properties */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Complete ML Cache event
+ * @interface MLCacheEvent
+ */
+export interface MLCacheEvent extends BaseEvent {
+    /** Event context (user, device, page, etc.) */
+    context?: EventContext;
+    /** Event properties/payload (business data) */
+    properties?: Record<string, unknown>;
+    /** Event metadata */
+    metadata?: EventMetadata;
+}
+/**
+ * Event metadata for internal tracking
+ * @interface EventMetadata
+ */
+export interface EventMetadata {
+    /** SDK version that generated the event */
+    sdkVersion: string;
+    /** Event batch ID (if batched) */
+    batchId?: string;
+    /** Number of retry attempts */
+    retryCount?: number;
+    /** Source application identifier */
+    sourceApp?: string;
+    /** Environment (production, staging, development) */
+    environment?: string;
+}
+/**
+ * Stored event with additional storage metadata
+ * @interface StoredEvent
+ */
+export interface StoredEvent extends MLCacheEvent {
+    /** Storage location (S3 key or Glacier archive ID) */
+    storageLocation: string;
+    /** Storage timestamp */
+    storedAt: string;
+    /** Storage type used */
+    storageType: 'S3' | 'GLACIER';
+}
+/**
+ * Batching configuration for event collection
+ * @interface BatchConfig
+ */
+export interface BatchConfig {
+    /** Maximum number of events per batch */
+    maxSize: number;
+    /** Maximum time (ms) to wait before flushing batch */
+    maxWaitMs: number;
+    /** Enable/disable batching */
+    enabled: boolean;
+}
+/**
+ * Retry configuration for failed requests
+ * @interface RetryConfig
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Initial delay between retries (ms) */
+    initialDelayMs: number;
+    /** Maximum delay between retries (ms) */
+    maxDelayMs: number;
+    /** Enable exponential backoff */
+    exponentialBackoff: boolean;
+}
+/**
+ * Logging configuration
+ * @interface LogConfig
+ */
+export interface LogConfig {
+    /** Log level */
+    level: LogLevel;
+    /** Enable/disable logging */
+    enabled: boolean;
+    /** Custom logger function */
+    customLogger?: LoggerFunction;
+}
+/**
+ * Log levels
+ * @typedef LogLevel
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Custom logger function type
+ * @typedef LoggerFunction
+ */
+export type LoggerFunction = (level: LogLevel, message: string, data?: Record<string, unknown>) => void;
+/**
+ * Storage mode configuration
+ * @typedef StorageMode
+ */
+export type StorageMode = 'S3' | 'GLACIER' | 'S3_TO_GLACIER';
+/**
+ * Complete SDK configuration
+ * @interface MLCacheConfig
+ */
+export interface MLCacheConfig {
+    /** AWS credentials */
+    credentials: AWSCredentials;
+    /** S3 configuration (required if using S3 or S3_TO_GLACIER mode) */
+    s3?: S3Config;
+    /** Glacier configuration (required if using GLACIER mode) */
+    glacier?: GlacierConfig;
+    /** Storage mode */
+    storageMode: StorageMode;
+    /** Batching configuration */
+    batch?: Partial<BatchConfig>;
+    /** Retry configuration */
+    retry?: Partial<RetryConfig>;
+    /** Logging configuration */
+    log?: Partial<LogConfig>;
+    /** Source application identifier */
+    sourceApp?: string;
+    /** Environment name */
+    environment?: string;
+    /** Enable debug mode */
+    debug?: boolean;
+}
+/**
+ * Result of a track operation
+ * @interface TrackResult
+ */
+export interface TrackResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Event ID */
+    eventId: string;
+    /** Storage location (if immediately stored) */
+    storageLocation?: string;
+    /** Whether event was queued for batching */
+    queued: boolean;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Result of a flush operation
+ * @interface FlushResult
+ */
+export interface FlushResult {
+    /** Whether the flush was successful */
+    success: boolean;
+    /** Number of events flushed */
+    eventCount: number;
+    /** Storage locations of flushed events */
+    storageLocations: string[];
+    /** Failed event IDs */
+    failedEventIds: string[];
+    /** Errors encountered */
+    errors: string[];
+}
+/**
+ * SDK health status
+ * @interface HealthStatus
+ */
+export interface HealthStatus {
+    /** Overall health status */
+    healthy: boolean;
+    /** S3 connection status */
+    s3Connected: boolean;
+    /** Glacier connection status */
+    glacierConnected: boolean;
+    /** Number of events in queue */
+    queueSize: number;
+    /** Last successful flush timestamp */
+    lastFlush?: string;
+    /** Last error message */
+    lastError?: string;
+}
+/**
+ * Event callback function type
+ * @typedef EventCallback
+ */
+export type EventCallback = (event: MLCacheEvent) => void;
+/**
+ * Error callback function type
+ * @typedef ErrorCallback
+ */
+export type ErrorCallback = (error: Error, event?: MLCacheEvent) => void;
+/**
+ * Flush callback function type
+ * @typedef FlushCallback
+ */
+export type FlushCallback = (result: FlushResult) => void;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/esm/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Type definitions and interfaces for ml-cache SDK
+ * @module ml-cache/types
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/esm/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/utils/helpers.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Helper utilities for ml-cache SDK
+ * @module ml-cache/utils/helpers
+ */
+import type { MLCacheEvent, EventMetadata } from '../types';
+/**
+ * Generates a unique event ID using UUID v4
+ * @returns {string} Unique event ID
+ */
+export declare function generateEventId(): string;
+/**
+ * Generates an ISO 8601 timestamp for the current time
+ * @returns {string} ISO 8601 timestamp
+ */
+export declare function generateTimestamp(): string;
+/**
+ * Generates a unique batch ID
+ * @returns {string} Unique batch ID
+ */
+export declare function generateBatchId(): string;
+/**
+ * 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
+ */
+export declare function createEventMetadata(options: {
+    sourceApp?: string;
+    environment?: string;
+    batchId?: string;
+    retryCount?: number;
+}): EventMetadata;
+/**
+ * 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
+ */
+export declare function enrichEvent(event: MLCacheEvent, options?: {
+    sourceApp?: string;
+    environment?: string;
+}): MLCacheEvent;
+/**
+ * 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
+ */
+export declare function generateS3Key(options: {
+    prefix?: string;
+    date?: Date;
+    eventId?: string;
+    batchId?: string;
+    extension?: string;
+}): string;
+/**
+ * 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
+ */
+export declare function generateGlacierDescription(options: {
+    batchId?: string;
+    eventCount?: number;
+    date?: Date;
+}): string;
+/**
+ * Serializes events to NDJSON format
+ * @param {MLCacheEvent[]} events - Events to serialize
+ * @returns {string} NDJSON string
+ */
+export declare function serializeEventsToNDJSON(events: MLCacheEvent[]): string;
+/**
+ * Deserializes events from NDJSON format
+ * @param {string} ndjson - NDJSON string
+ * @returns {MLCacheEvent[]} Parsed events
+ */
+export declare function deserializeEventsFromNDJSON(ndjson: string): MLCacheEvent[];
+/**
+ * Calculates the size of serialized events in bytes
+ * @param {MLCacheEvent[]} events - Events to measure
+ * @returns {number} Size in bytes
+ */
+export declare function calculateEventsSize(events: MLCacheEvent[]): number;
+/**
+ * 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
+ */
+export declare function calculateRetryDelay(attempt: number, initialDelayMs: number, maxDelayMs: number, exponential: boolean): number;
+/**
+ * Sleeps for a specified duration
+ * @param {number} ms - Duration in milliseconds
+ * @returns {Promise<void>} Promise that resolves after the delay
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Chunks an array into smaller arrays
+ * @template T
+ * @param {T[]} array - Array to chunk
+ * @param {number} size - Chunk size
+ * @returns {T[][]} Array of chunks
+ */
+export declare function chunk<T>(array: T[], size: number): T[][];
+/**
+ * Deep clones an object
+ * @template T
+ * @param {T} obj - Object to clone
+ * @returns {T} Cloned object
+ */
+export declare function deepClone<T>(obj: T): T;
+/**
+ * Safely stringifies an object, handling circular references
+ * @param {unknown} obj - Object to stringify
+ * @returns {string} JSON string
+ */
+export declare function safeStringify(obj: unknown): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/esm/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/utils/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5D;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,aAAa,CAQhB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,YAAY,CAUd;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAaT;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,IAAI,CAAC;CACb,GAAG,MAAM,CAaT;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAGlE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,GACnB,MAAM,CAQR;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAMxD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAWlD"}

package/dist/esm/utils/helpers.js

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview Helper utilities for ml-cache SDK
+ * @module ml-cache/utils/helpers
+ */
+import { randomUUID } from 'crypto';
+import { SDK_VERSION, DEFAULT_S3_PREFIX } from '../constants';
+/**
+ * Generates a unique event ID using UUID v4
+ * @returns {string} Unique event ID
+ */
+export function generateEventId() {
+    return randomUUID();
+}
+/**
+ * Generates an ISO 8601 timestamp for the current time
+ * @returns {string} ISO 8601 timestamp
+ */
+export function generateTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Generates a unique batch ID
+ * @returns {string} Unique batch ID
+ */
+export function generateBatchId() {
+    return `batch_${Date.now()}_${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
+ */
+export function createEventMetadata(options) {
+    return {
+        sdkVersion: 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
+ */
+export 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
+ */
+export function generateS3Key(options) {
+    const prefix = options.prefix || 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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