@pawells/typescript-common 2.0.0 → 2.1.6

package/{build → dist}/time/elapsed-time/elapsed-time.d.ts

@@ -1,34 +1,40 @@
-import { ITimeElapsedFormatOptions, TTimeElapsedFormats, IFormatConfig } from './types.js';
+import type { ITimeElapsedFormatOptions, TTimeElapsedFormats, IFormatConfig } from './types.js';
 /**
  * Represents a duration of time with formatting and calculation capabilities.
  */
 export declare class ElapsedTime {
     /** Whether the elapsed time represents a negative duration */
-    private _IsNegative;
+    private _isNegative;
     /** The total duration in milliseconds (always positive, sign stored in isNegative) */
-    private _TotalMilliseconds;
+    private _totalMilliseconds;
     /** Cached total seconds value */
-    private _TotalSeconds;
+    private _totalSeconds;
     /** Cached total minutes value */
-    private _TotalMinutes;
+    private _totalMinutes;
     /** Cached total hours value */
-    private _TotalHours;
+    private _totalHours;
     /** Cached total days value */
-    private _TotalDays;
+    private _totalDays;
     /** Cached seconds component (excluding complete minutes) */
-    private _Seconds;
+    private _seconds;
     /** Cached minutes component (excluding complete hours) */
-    private _Minutes;
+    private _minutes;
     /** Cached hours component (excluding complete days) */
-    private _Hours;
+    private _hours;
     /** Cached days component (excluding complete weeks) */
-    private _Days;
+    private _days;
     /** Cached weeks component */
-    private _Weeks;
+    private _weeks;
     /** Cached milliseconds component (excluding complete seconds) */
-    private _Milliseconds;
+    private _milliseconds;
     /** Flag to track whether cached values have been calculated */
-    private _ValuesCalculated;
+    private _valuesCalculated;
+    /**
+     * Cache object for computed property values when in stopped/paused state.
+     * Stores the last computed property value to avoid recalculation on repeated access.
+     * Cleared when TotalMilliseconds is set (instance becomes mutable again).
+     */
+    private _propertyCache;
     /**
      * Creates a new ElapsedTime instance.
      * @param milliseconds The total number of milliseconds.
@@ -55,7 +61,19 @@ export declare class ElapsedTime {
      * console.log(elapsed.TotalHours); // 26
      * ```
      */
-    private _CalculateTimeValues;
+    private _calculateTimeValues;
+    /**
+     * Get a cached property value, computing and caching it if necessary.
+     * For stopped/paused instances (where TotalMilliseconds doesn't change),
+     * this returns the cached value on subsequent accesses, avoiding repeated
+     * property getter indirection and computation.
+     *
+     * @param key - Cache key identifying the property
+     * @param getter - Function to compute the value if not cached
+     * @returns The cached or newly computed value
+     * @private
+     */
+    private _getCachedProperty;
     /**
      * Gets the number of weeks in the elapsed time.
      */
@@ -295,7 +313,7 @@ export declare class ElapsedTime {
      * elapsed2.Format('LONG'); // "2 hours 2 minutes 2 seconds" (all plural)
      * ```
      */
-    private _FormatLong;
+    private _formatLong;
     /**
      * Format the elapsed time using the token-based formatting system.
      * This is the main formatting engine that handles all predefined formats
@@ -317,7 +335,7 @@ export declare class ElapsedTime {
      * // Called automatically by Format() method for most format types
      * ```
      */
-    private _FormatUsingTokens;
+    private _formatUsingTokens;
     /**
      * Format time units for TIME and TIME_WITH_SECONDS formats
      * These formats use special formatting with colons for displaying time (e.g., "1:30:45")
@@ -326,16 +344,18 @@ export declare class ElapsedTime {
      * @returns Formatted time string with colons (e.g., "1:30:45")
      * @private
      */
-    private static _FormatTimeUnits;
+    private static _formatTimeUnits;
     /**
      * Format units for standard (non-time) formats
      * Handles different formatting styles including CONCISE, SHORT, MEDIUM, LONG, and custom formats
      * @param units - Array of time units with their values
      * @param unitLabels - Object containing label definitions for each time unit
+     * @param formatKey - The format key (concise, short, medium, etc.)
+     * @param hasCustomLabels - Whether custom labels were provided by the user
      * @returns Formatted time string according to the specified format style
      * @private
      */
-    private static _FormatStandardUnits;
+    private static _formatStandardUnits;
     /**
      * Filter and limit time units based on formatting options.
      * Applies showZeroValues and maxUnits options to determine which
@@ -354,7 +374,7 @@ export declare class ElapsedTime {
      * // All zero values -> ensures at least "0 seconds" is shown
      * ```
      */
-    private static _FilterAndLimitUnits;
+    private static _filterAndLimitUnits;
     /**
      * Apply negative value formatting based on user preferences.
      * Wraps or modifies the formatted time string to indicate negative durations
@@ -374,11 +394,12 @@ export declare class ElapsedTime {
      * // Empty: "1h 30m" -> "1h 30m" (no change)
      * ```
      */
-    private static _ApplyNegativeFormatting;
+    private static _applyNegativeFormatting;
 }
 /**
  * Formats elapsed time using the specified configuration.
- * This is a simplified formatting function that uses IFormatConfig for basic formatting options.
+ * Convenience wrapper equivalent to `ElapsedTime.Format(milliseconds, 'concise', options)`.
+ * For other format styles, use {@link ElapsedTime.Format} directly.
  *
  * @param milliseconds - The total number of milliseconds to format
  * @param options - Formatting configuration options
@@ -391,6 +412,37 @@ export declare class ElapsedTime {
  * console.log(FormatElapsedTime(3661000)); // "1h 1m 1s"
  * console.log(FormatElapsedTime(3661000, { maxUnits: 1 })); // "1h"
  * ```
+ *
+ * @see ElapsedTime.Format
+ */
+/**
+ * Format elapsed time using the concise format with optional customization.
+ * Convenience function that creates a temporary ElapsedTime instance and formats it.
+ * Always uses the 'concise' format (e.g., "1h 30m 45s") with optional overrides.
+ *
+ * @param milliseconds - The total number of milliseconds to format
+ * @param options - Optional formatting configuration to customize maxUnits and unitLabels
+ * @returns The formatted time string in concise format
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default concise format
+ * console.log(FormatElapsedTime(3661000));                // "1h 1m 1s"
+ * console.log(FormatElapsedTime(5425000));                // "1h 30m 25s"
+ *
+ * // With maxUnits option
+ * console.log(FormatElapsedTime(3661000, { maxUnits: 2 })); // "1h 1m"
+ *
+ * // With custom labels
+ * const options = {
+ *   unitLabels: {
+ *     hour: 'hrs',
+ *     minute: 'mins',
+ *     second: 'secs'
+ *   }
+ * };
+ * console.log(FormatElapsedTime(3661000, options)); // "1 hrs 1 mins 1 secs"
+ * ```
  */
 export declare function FormatElapsedTime(milliseconds: number, options?: IFormatConfig): string;
 //# sourceMappingURL=elapsed-time.d.ts.map

package/dist/time/elapsed-time/elapsed-time.d.ts.map

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