@rb-games/core 0.1.0

package/dist/utils/ArrayUtils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Array prototype extensions for game utilities.
+ *
+ * ⚠️ WARNING: This file modifies Array.prototype globally.
+ * It must be imported early in the application lifecycle.
+ *
+ * Usage:
+ * - array.shuffle() - Returns shuffled copy
+ * - array.random() - Returns random element
+ * - array.clone() - Returns shallow copy
+ * - array.exclude(1, 2) - Returns array without indices 1, 2
+ */
+declare global {
+    interface Array<T> {
+        random(): T;
+        clone(): T[];
+        exclude(...indexToExclude: number[]): T[];
+        shuffle(): T[];
+        lastItem(): T | undefined;
+        firstItem(): T | undefined;
+    }
+}
+export declare const __arrayUtilsLoaded = true;
+//# sourceMappingURL=ArrayUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArrayUtils.d.ts","sourceRoot":"","sources":["../../utils/ArrayUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkDH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,KAAK,CAAC,CAAC;QACf,MAAM,IAAI,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,cAAc,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC,EAAE,CAAC;QACf,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;QAC1B,SAAS,IAAI,CAAC,GAAG,SAAS,CAAC;KAC5B;CACF;AAGD,eAAO,MAAM,kBAAkB,OAAO,CAAC"}

package/dist/utils/ColorUtils.d.ts

@@ -0,0 +1,34 @@
+import { Color, type ColorSource } from 'pixi.js';
+/**
+ * Lightens a color by a specified percentage.
+ *
+ * @param color - Color value (hex string, number, or any PixiJS ColorSource)
+ * @param amount - Amount to lighten (0-1, where 0.2 = 20% lighter)
+ * @returns Lightened color as PixiJS Color instance
+ *
+ * @example
+ * ```typescript
+ * const lighter = lightenColor('#4CAF50', 0.15);
+ * const lighter2 = lightenColor(0x4CAF50, 0.15);
+ * // Can be used directly with PixiJS: sprite.tint = lighter;
+ * // Or as hex string: lighter.toHex()
+ * ```
+ */
+export declare function lightenColor(color: ColorSource, amount: number): Color;
+/**
+ * Darkens a color by a specified percentage.
+ *
+ * @param color - Color value (hex string, number, or any PixiJS ColorSource)
+ * @param amount - Amount to darken (0-1, where 0.2 = 20% darker)
+ * @returns Darkened color as PixiJS Color instance
+ *
+ * @example
+ * ```typescript
+ * const darker = darkenColor('#4CAF50', 0.15);
+ * const darker2 = darkenColor(0x4CAF50, 0.15);
+ * // Can be used directly with PixiJS: sprite.tint = darker;
+ * // Or as hex string: darker.toHex()
+ * ```
+ */
+export declare function darkenColor(color: ColorSource, amount: number): Color;
+//# sourceMappingURL=ColorUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ColorUtils.d.ts","sourceRoot":"","sources":["../../utils/ColorUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAqDlD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAEtE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAErE"}

package/dist/utils/DataInjector.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Injects data into a nested object path.
+ *
+ * DataInjector is a utility function for safely modifying nested object properties.
+ * It creates a deep clone of the original object and injects data at the specified path.
+ *
+ * ## Features
+ *
+ * - **Deep Cloning**: Original object is never mutated
+ * - **Nested Path Support**: Use dot notation (e.g., 'ui.button.color')
+ * - **Merge or Replace**: Choose to merge with existing data or replace it
+ * - **Type-Safe**: Preserves TypeScript types
+ *
+ * ## Usage with Skins
+ *
+ * Commonly used to patch skin data with specific values while keeping the rest intact.
+ *
+ * @typeParam T - The type of the object being modified
+ * @param obj - Source object to modify
+ * @param path - Dot-notation path to the property (e.g., 'options.buttonSkin.up')
+ * @param data - Data to inject at the path
+ * @param replace - If true, replaces the value; if false, merges with existing (default: false)
+ * @returns New object with injected data
+ *
+ * @example
+ * Merge data (default):
+ * ```typescript
+ * const skinData = {
+ *   button: { color: 0xFF0000, size: 100 },
+ *   text: { fontSize: 24 }
+ * };
+ *
+ * const updated = DataInjector(skinData, 'button', { size: 150 });
+ * // Result: { button: { color: 0xFF0000, size: 150 }, text: { fontSize: 24 } }
+ * ```
+ *
+ * @example
+ * Replace data:
+ * ```typescript
+ * const updated = DataInjector(skinData, 'button', { size: 150 }, true);
+ * // Result: { button: { size: 150 }, text: { fontSize: 24 } }
+ * // Note: color is removed because we replaced the entire button object
+ * ```
+ *
+ * @example
+ * Real-world example:
+ * ```typescript
+ * let autoplaySkin = defaultAutoplayMenuSkin;
+ *
+ * // Inject checkbox textures
+ * autoplaySkin = DataInjector(autoplaySkin, 'options.buttonSkin', {
+ *   up: { background: { texture: 'btn_checkbox_up' } },
+ *   over: { background: { texture: 'btn_checkbox_over' } },
+ *   down: { background: { texture: 'btn_checkbox_down' } }
+ * });
+ *
+ * // Inject slider textures
+ * autoplaySkin = DataInjector(autoplaySkin, 'count.sliderSkin', {
+ *   up: { knob: { texture: 'icon_autoplay_slider_up' } },
+ *   over: { knob: { texture: 'icon_autoplay_slider_over' } }
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function DataInjector<T extends object>(obj: T, path: string, data: unknown, replace?: boolean): T;
+//# sourceMappingURL=DataInjector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DataInjector.d.ts","sourceRoot":"","sources":["../../utils/DataInjector.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,UAAQ,GACd,CAAC,CAgBH"}

package/dist/utils/Logger.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Log levels for filtering log output.
+ *
+ * Lower numeric values have higher priority.
+ * Setting a log level will show that level and all higher priority levels.
+ *
+ * @example
+ * ```typescript
+ * // Set to INFO level
+ * logger.setLevel(LogLevel.INFO);
+ * // Will show: ERROR, WARN, INFO
+ * // Will hide: DEBUG, TRACE
+ * ```
+ *
+ * @public
+ */
+export declare enum LogLevel {
+    /** Critical errors (always shown) */
+    ERROR = 0,
+    /** Warnings (shown at WARN level and above) */
+    WARN = 1,
+    /** Informational messages (shown at INFO level and above) */
+    INFO = 2,
+    /** Debug messages (shown at DEBUG level and above) */
+    DEBUG = 3,
+    /** Trace messages (most verbose, shown only at TRACE level) */
+    TRACE = 4
+}
+export type LoggerFilterMatcher = string | RegExp;
+export interface LoggerFilterConfig {
+    contexts?: LoggerFilterMatcher[];
+    messages?: LoggerFilterMatcher[];
+    mode?: 'include' | 'exclude';
+}
+/**
+ * Configuration options for the Logger.
+ *
+ * @public
+ */
+export interface LoggerConfig {
+    /** Minimum log level to display */
+    level: LogLevel;
+    /** Whether logging is enabled */
+    enabled: boolean;
+    /** Whether to show timestamps in logs */
+    showTimestamp: boolean;
+    /** Whether to show colors in logs */
+    showColors: boolean;
+    filter?: LoggerFilterConfig;
+}
+/**
+ * Singleton logger for centralized logging.
+ *
+ * Logger provides a unified logging system with:
+ * - Multiple log levels (ERROR, WARN, INFO, DEBUG, TRACE)
+ * - Colored output (browser and terminal)
+ * - Timestamps
+ * - Context-based sub-loggers
+ * - Environment detection (browser vs Node.js)
+ *
+ * ## Features
+ *
+ * - **Singleton Pattern**: Single instance across the application
+ * - **Log Levels**: Filter logs by severity
+ * - **Colored Output**: CSS colors in browser, ANSI colors in terminal
+ * - **Context Loggers**: Create sub-loggers with context prefixes
+ * - **Timestamps**: Optional ISO timestamp display
+ * - **Environment Aware**: Automatically detects browser vs Node.js
+ *
+ * ## Log Levels
+ *
+ * - **ERROR** (0): Critical errors
+ * - **WARN** (1): Warnings
+ * - **INFO** (2): Informational messages (default)
+ * - **DEBUG** (3): Debug information
+ * - **TRACE** (4): Detailed trace information
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * import { logger, LogLevel } from '@rb-games/core/utils';
+ *
+ * // Configure logger
+ * logger.configure({
+ *   level: LogLevel.DEBUG,
+ *   showTimestamp: true,
+ *   showColors: true
+ * });
+ *
+ * // Log messages
+ * logger.error('Critical error occurred');
+ * logger.warn('This is a warning');
+ * logger.info('Application started');
+ * logger.debug('Debug information', { data: 'value' });
+ * logger.trace('Detailed trace');
+ * ```
+ *
+ * @example
+ * Context loggers (used in plugins):
+ * ```typescript
+ * class MyPlugin {
+ *   private logger = logger.createContextLogger('MyPlugin');
+ *
+ *   initialize() {
+ *     this.logger.info('Plugin initialized');
+ *     // Output: [2024-01-01T12:00:00.000Z] [INFO] [MyPlugin] Plugin initialized
+ *   }
+ *
+ *   doSomething() {
+ *     this.logger.debug('Doing something', { value: 42 });
+ *     // Output: [2024-01-01T12:00:00.000Z] [DEBUG] [MyPlugin] Doing something { value: 42 }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Production configuration:
+ * ```typescript
+ * // In production, only show errors and warnings
+ * if (process.env.NODE_ENV === 'production') {
+ *   logger.setLevel(LogLevel.WARN);
+ * } else {
+ *   logger.setLevel(LogLevel.DEBUG);
+ * }
+ * ```
+ *
+ * @example
+ * Disable logging:
+ * ```typescript
+ * logger.setEnabled(false);
+ * ```
+ *
+ * @category Utils
+ * @public
+ */
+export declare class Logger {
+    private static instance;
+    private config;
+    private readonly terminalColors;
+    private readonly browserColors;
+    private readonly levelLabels;
+    private readonly levelColors;
+    private readonly levelBrowserColors;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Get the singleton instance of the Logger
+     */
+    static getInstance(): Logger;
+    /**
+     * Configure the logger
+     * @param config Configuration options
+     */
+    configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Enable or disable logging
+     * @param enabled Whether logging is enabled
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Set the log level
+     * @param level The log level to set
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Log an error message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    error(message: string, ...args: any[]): void;
+    /**
+     * Log a warning message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Log an info message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Log a debug message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Log a trace message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    trace(message: string, ...args: any[]): void;
+    /**
+     * Log a message with a specific log level
+     * @param level The log level
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    private log;
+    private extractContext;
+    private matchesFilter;
+    private shouldLogMessage;
+    /**
+     * Log a message in terminal/node environment
+     */
+    private logTerminal;
+    /**
+     * Log a message in browser environment with CSS styling
+     */
+    private logBrowser;
+    /**
+     * Creates a context-specific logger.
+     *
+     * Context loggers automatically prefix all log messages with a context tag.
+     * Commonly used in plugins and classes to identify log sources.
+     *
+     * @param context - Context name (e.g., 'MyPlugin', 'SceneManager')
+     * @returns ContextLogger instance
+     *
+     * @example
+     * ```typescript
+     * class DisplayPlugin {
+     *   private logger = logger.createContextLogger('DisplayPlugin');
+     *
+     *   initialize() {
+     *     this.logger.info('Initializing display');
+     *     // Output: [INFO] [DisplayPlugin] Initializing display
+     *   }
+     * }
+     * ```
+     */
+    createContextLogger(context: string): ContextLogger;
+}
+/**
+ * Context-specific logger that prefixes all messages.
+ *
+ * ContextLogger wraps the main Logger and automatically adds a context prefix
+ * to all log messages. This makes it easy to identify which component or plugin
+ * generated a log message.
+ *
+ * ## Usage
+ *
+ * Create context loggers using `logger.createContextLogger(context)`.
+ * All log methods (error, warn, info, debug, trace) are available.
+ *
+ * @example
+ * ```typescript
+ * class ResourcePlugin {
+ *   private logger = logger.createContextLogger('ResourcePlugin');
+ *
+ *   async loadAssets() {
+ *     this.logger.info('Loading assets...');
+ *     // Output: [INFO] [ResourcePlugin] Loading assets...
+ *
+ *     try {
+ *       await this.load();
+ *       this.logger.info('Assets loaded successfully');
+ *     } catch (error) {
+ *       this.logger.error('Failed to load assets', error);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @category Utils
+ * @public
+ */
+export declare class ContextLogger {
+    private logger;
+    private context;
+    constructor(logger: Logger, context: string);
+    /**
+     * Log an error message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    error(message: string, ...args: any[]): void;
+    /**
+     * Log a warning message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Log an info message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Log a debug message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Log a trace message
+     * @param message The message to log
+     * @param args Additional arguments to log
+     */
+    trace(message: string, ...args: any[]): void;
+}
+export declare const logger: Logger;
+/**
+ * Get or create a cached context logger.
+ * Same context string always returns the same instance.
+ *
+ * Preferred over class property pattern for easier tree-shaking
+ * and production stripping.
+ *
+ * @param context - Context name (e.g., 'MyPlugin', 'SceneManager')
+ * @returns Cached ContextLogger instance
+ *
+ * @example
+ * ```typescript
+ * import { getLogger } from '@rb-games/core/utils';
+ *
+ * // No class property needed - use inline
+ * getLogger('MyClass').info('message');
+ * getLogger('MyClass').debug('data', { x: 1 });
+ * ```
+ */
+export declare function getLogger(context: string): ContextLogger;
+//# sourceMappingURL=Logger.d.ts.map

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

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

package/dist/utils/NumberFormatter.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Configuration options for NumberFormatter.
+ *
+ * @public
+ */
+export interface NumberFormatterConfig {
+    /** Number format mask (e.g., '$ #,##0.##', '#,##0.00 TL') */
+    mask: string;
+    /** Denomination multiplier for currency conversion */
+    denom: number;
+    /** Threshold for express mode (values above this will be shortened) */
+    expressThreshold: number;
+    /** Units for express mode (K, M, B, T, etc.) */
+    expressUnits: string[];
+    /** Decimal precision for express mode */
+    decimalPrecision: number;
+    /** Symbol to show when number is rounded in express mode */
+    roundedSymbol: string;
+}
+/**
+ * Options for format and express methods.
+ *
+ * @public
+ */
+export interface FormatOptions {
+    /** Prefix to add before the formatted number */
+    prefix?: string;
+    /** Force showing decimal places even for whole numbers */
+    forceDecimals?: boolean;
+    /** Ignore denomination multiplier */
+    ignoreDenom?: boolean;
+    /** Custom threshold for express mode (overrides config) */
+    threshold?: number;
+}
+export declare class NumberFormatter {
+    private static instance;
+    private config;
+    private maskCache;
+    /**
+     * Private constructor for singleton pattern
+     */
+    private constructor();
+    /**
+     * Configure the NumberFormatter singleton.
+     *
+     * @param config - Configuration options
+     * @returns NumberFormatter instance
+     */
+    static configure(config: Partial<NumberFormatterConfig>): NumberFormatter;
+    /**
+     * Get the singleton instance.
+     *
+     * If not configured yet, initializes with default configuration.
+     *
+     * @returns NumberFormatter instance
+     */
+    static getInstance(): NumberFormatter;
+    /**
+     * Format a number using the configured mask.
+     *
+     * @param value - Number to format
+     * @param options - Optional formatting options
+     * @returns Formatted string
+     *
+     * @example
+     * ```typescript
+     * formatter.format(1500); // "$ 15.00"
+     * formatter.format(1500, { forceDecimals: true }); // "$ 15.00"
+     * formatter.format(1500, { ignoreDenom: true }); // "$ 1,500.00"
+     * ```
+     */
+    format(value: number, options?: FormatOptions): string;
+    /**
+     * Format a number in express mode (shortened with K/M/B/T).
+     *
+     * @param value - Number to format
+     * @param options - Optional formatting options
+     * @returns Formatted string with unit suffix
+     *
+     * @example
+     * ```typescript
+     * formatter.express(150000); // "$ 1.5K"
+     * formatter.express(2500000); // "$ 2.5M"
+     * formatter.express(500, { threshold: 100 }); // "$ 0.5K"
+     * ```
+     */
+    express(value: number, options?: FormatOptions): string;
+    /**
+     * Parse a mask string into its components.
+     *
+     * @param mask - Mask string to parse
+     * @returns Parsed mask information
+     * @internal
+     */
+    private parseMask;
+    /**
+     * Apply a mask to a number value.
+     *
+     * @param mask - Mask pattern
+     * @param value - Number to format
+     * @returns Formatted string
+     * @internal
+     */
+    private applyMask;
+    /**
+     * Decimal/group separators and fraction length from the configured mask.
+     * Use for free-form numeric inputs (e.g. bet multipliers) that are not currency amounts.
+     */
+    getMaskLocale(): {
+        decimal: string;
+        group: string;
+        decimalPlaces: number;
+    };
+    /**
+     * Format a number using only the numeric portion of the mask (no prefix/suffix, no denom).
+     * Suitable for multipliers and limits (e.g. autoplay 10.5× bet).
+     */
+    formatPlainNumber(value: number, options?: Pick<FormatOptions, 'forceDecimals'>): string;
+    /**
+     * Get current configuration.
+     *
+     * @returns Current configuration
+     */
+    getConfig(): Readonly<NumberFormatterConfig>;
+}
+//# sourceMappingURL=NumberFormatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NumberFormatter.d.ts","sourceRoot":"","sources":["../../utils/NumberFormatter.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,yCAAyC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwID,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAAsC;IAEvD;;OAEG;IACH,OAAO;IAIP;;;;;OAKG;WACW,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,eAAe;IAahF;;;;;;OAMG;WACW,WAAW,IAAI,eAAe;IAO5C;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM;IAcjE;;;;;;;;;;;;;OAaG;IACI,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM;IAyClE;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IA8CjB;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAyDjB;;;OAGG;IACI,aAAa,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAUjF;;;OAGG;IACI,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,eAAe,CAAM,GAAG,MAAM;IAUnG;;;;OAIG;IACI,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC;CAGpD"}

package/dist/utils/ObjectUtils.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Utility functions for object manipulation and property access.
+ */
+/**
+ * Gets a nested property value from an object using a dot-separated path.
+ *
+ * @param obj - The source object
+ * @param path - Dot-separated path to the nested property (e.g., 'user.profile.name')
+ * @returns The value at the specified path, or undefined if any part of the path doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const obj = { user: { profile: { name: 'John' } } };
+ * const name = getNestedValue(obj, 'user.profile.name'); // Returns 'John'
+ * const age = getNestedValue(obj, 'user.profile.age'); // Returns undefined
+ * ```
+ */
+export declare function getNestedValue(obj: any, path: string): any;
+/**
+ * Sets a nested property value in an object using a dot-separated path.
+ * Creates intermediate objects if they don't exist.
+ *
+ * @param obj - The target object
+ * @param path - Dot-separated path to the nested property (e.g., 'user.profile.name')
+ * @param value - The value to set
+ *
+ * @example
+ * ```typescript
+ * const obj = {};
+ * setNestedValue(obj, 'user.profile.name', 'John');
+ * // Result: { user: { profile: { name: 'John' } } }
+ * ```
+ */
+export declare function setNestedValue(obj: any, path: string, value: any): void;
+/**
+ * Checks if a nested property exists in an object using a dot-separated path.
+ *
+ * @param obj - The object to check
+ * @param path - Dot-separated path to the nested property
+ * @returns true if the property exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const obj = { user: { profile: { name: 'John' } } };
+ * const hasName = hasNestedProperty(obj, 'user.profile.name'); // Returns true
+ * const hasAge = hasNestedProperty(obj, 'user.profile.age'); // Returns false
+ * ```
+ */
+export declare function hasNestedProperty(obj: any, path: string): boolean;
+/**
+ * Deep clones an object using structured cloning.
+ *
+ * @param obj - The object to clone
+ * @returns A deep copy of the object
+ *
+ * @example
+ * ```typescript
+ * const original = { user: { profile: { name: 'John' } } };
+ * const cloned = deepClone(original);
+ * cloned.user.profile.name = 'Jane'; // Doesn't affect original
+ * ```
+ */
+export declare function deepClone<T>(obj: T): T;
+//# sourceMappingURL=ObjectUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObjectUtils.d.ts","sourceRoot":"","sources":["../../utils/ObjectUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAE1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAUvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAEtC"}