@pawells/typescript-common 2.0.0 → 2.1.5

package/{build → dist}/time/elapsed-time/elapsed-time.js

@@ -7,44 +7,55 @@ const MINUTES_PER_HOUR = 60;
 const HOURS_PER_DAY = 24;
 const DAYS_PER_WEEK = 7;
 const PRECISION_DECIMAL_PLACES = 3;
+// Format key aliases for case-insensitive matching
+const FORMAT_ALIASES = {
+    mostsignificant: 'mostSignificant',
+    timewithseconds: 'timeWithSeconds',
+};
 /**
  * Represents a duration of time with formatting and calculation capabilities.
  */
 export class ElapsedTime {
     /** Whether the elapsed time represents a negative duration */
-    _IsNegative = false;
+    _isNegative = false;
     /** The total duration in milliseconds (always positive, sign stored in isNegative) */
-    _TotalMilliseconds = 0;
+    _totalMilliseconds = 0;
     // Cached calculations for better performance - computed on-demand
     /** Cached total seconds value */
-    _TotalSeconds = 0;
+    _totalSeconds = 0;
     /** Cached total minutes value */
-    _TotalMinutes = 0;
+    _totalMinutes = 0;
     /** Cached total hours value */
-    _TotalHours = 0;
+    _totalHours = 0;
     /** Cached total days value */
-    _TotalDays = 0;
+    _totalDays = 0;
     /** Cached seconds component (excluding complete minutes) */
-    _Seconds = 0;
+    _seconds = 0;
     /** Cached minutes component (excluding complete hours) */
-    _Minutes = 0;
+    _minutes = 0;
     /** Cached hours component (excluding complete days) */
-    _Hours = 0;
+    _hours = 0;
     /** Cached days component (excluding complete weeks) */
-    _Days = 0;
+    _days = 0;
     /** Cached weeks component */
-    _Weeks = 0;
+    _weeks = 0;
     /** Cached milliseconds component (excluding complete seconds) */
-    _Milliseconds = 0;
+    _milliseconds = 0;
     /** Flag to track whether cached values have been calculated */
-    _ValuesCalculated = false;
+    _valuesCalculated = false;
+    /**
+     * 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).
+     */
+    _propertyCache = {};
     /**
      * Creates a new ElapsedTime instance.
      * @param milliseconds The total number of milliseconds.
      */
     constructor(milliseconds) {
-        this._TotalMilliseconds = Math.abs(milliseconds);
-        this._IsNegative = milliseconds < 0;
+        this._totalMilliseconds = Math.abs(milliseconds);
+        this._isNegative = milliseconds < 0;
     }
     /**
      * Calculate all time unit values for efficient access.
@@ -68,47 +79,76 @@ export class ElapsedTime {
      * ```
      */
     _CalculateTimeValues() {
-        if (this._ValuesCalculated)
+        if (this._valuesCalculated)
             return;
-        this._TotalSeconds = Math.floor(this._TotalMilliseconds / MS_PER_SECOND);
-        this._TotalMinutes = Math.floor(this._TotalSeconds / SECONDS_PER_MINUTE);
-        this._TotalHours = Math.floor(this._TotalMinutes / MINUTES_PER_HOUR);
-        this._TotalDays = Math.floor(this._TotalHours / HOURS_PER_DAY);
-        this._Weeks = Math.floor(this._TotalDays / DAYS_PER_WEEK);
-        this._Days = this._TotalDays % DAYS_PER_WEEK;
-        this._Hours = this._TotalHours % HOURS_PER_DAY;
-        this._Minutes = this._TotalMinutes % MINUTES_PER_HOUR;
-        this._Seconds = this._TotalSeconds % SECONDS_PER_MINUTE;
-        this._Milliseconds = this._TotalMilliseconds % MS_PER_SECOND;
-        this._ValuesCalculated = true;
+        this._totalSeconds = Math.floor(this._totalMilliseconds / MS_PER_SECOND);
+        this._totalMinutes = Math.floor(this._totalSeconds / SECONDS_PER_MINUTE);
+        this._totalHours = Math.floor(this._totalMinutes / MINUTES_PER_HOUR);
+        this._totalDays = Math.floor(this._totalHours / HOURS_PER_DAY);
+        this._weeks = Math.floor(this._totalDays / DAYS_PER_WEEK);
+        this._days = this._totalDays % DAYS_PER_WEEK;
+        this._hours = this._totalHours % HOURS_PER_DAY;
+        this._minutes = this._totalMinutes % MINUTES_PER_HOUR;
+        this._seconds = this._totalSeconds % SECONDS_PER_MINUTE;
+        this._milliseconds = this._totalMilliseconds % MS_PER_SECOND;
+        this._valuesCalculated = true;
+    }
+    /**
+     * 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
+     */
+    _getCachedProperty(key, getter) {
+        // Check if value is already cached
+        if (key in this._propertyCache) {
+            return this._propertyCache[key];
+        }
+        // Compute and cache the value
+        const value = getter();
+        this._propertyCache[key] = value;
+        return value;
     }
     /**
      * Gets the number of weeks in the elapsed time.
      */
     get Weeks() {
-        this._CalculateTimeValues();
-        return this._Weeks;
+        return this._getCachedProperty('weeks', () => {
+            this._CalculateTimeValues();
+            return this._weeks;
+        });
     }
     /**
      * Gets the number of days in the elapsed time (excluding complete weeks).
      */
     get Days() {
-        this._CalculateTimeValues();
-        return this._Days;
+        return this._getCachedProperty('days', () => {
+            this._CalculateTimeValues();
+            return this._days;
+        });
     }
     /**
      * Gets the total number of days in the elapsed time.
      */
     get TotalDays() {
-        this._CalculateTimeValues();
-        return this._TotalDays;
+        return this._getCachedProperty('totalDays', () => {
+            this._CalculateTimeValues();
+            return this._totalDays;
+        });
     }
     /**
      * Gets the number of hours in the elapsed time (excluding complete days).
      */
     get Hours() {
-        this._CalculateTimeValues();
-        return this._Hours;
+        return this._getCachedProperty('hours', () => {
+            this._CalculateTimeValues();
+            return this._hours;
+        });
     }
     static _pad(value, length) {
         return value.toString().padStart(length, '0');
@@ -125,8 +165,10 @@ export class ElapsedTime {
      * Gets the total number of hours in the elapsed time.
      */
     get TotalHours() {
-        this._CalculateTimeValues();
-        return this._TotalHours;
+        return this._getCachedProperty('totalHours', () => {
+            this._CalculateTimeValues();
+            return this._totalHours;
+        });
     }
     /**
      * Gets the total hours as a padded string.
@@ -140,8 +182,10 @@ export class ElapsedTime {
      * Gets the number of minutes in the elapsed time (excluding complete hours).
      */
     get Minutes() {
-        this._CalculateTimeValues();
-        return this._Minutes;
+        return this._getCachedProperty('minutes', () => {
+            this._CalculateTimeValues();
+            return this._minutes;
+        });
     }
     /**
      * Gets the minutes component as a padded string.
@@ -155,8 +199,10 @@ export class ElapsedTime {
      * Gets the total number of minutes in the elapsed time.
      */
     get TotalMinutes() {
-        this._CalculateTimeValues();
-        return this._TotalMinutes;
+        return this._getCachedProperty('totalMinutes', () => {
+            this._CalculateTimeValues();
+            return this._totalMinutes;
+        });
     }
     /**
      * Gets the total minutes as a padded string.
@@ -170,8 +216,10 @@ export class ElapsedTime {
      * Gets the number of seconds in the elapsed time (excluding complete minutes).
      */
     get Seconds() {
-        this._CalculateTimeValues();
-        return this._Seconds;
+        return this._getCachedProperty('seconds', () => {
+            this._CalculateTimeValues();
+            return this._seconds;
+        });
     }
     /**
      * Gets the seconds component as a padded string.
@@ -185,8 +233,10 @@ export class ElapsedTime {
      * Gets the total number of seconds in the elapsed time.
      */
     get TotalSeconds() {
-        this._CalculateTimeValues();
-        return this._TotalSeconds;
+        return this._getCachedProperty('totalSeconds', () => {
+            this._CalculateTimeValues();
+            return this._totalSeconds;
+        });
     }
     /**
      * Gets the total seconds as a padded string.
@@ -200,8 +250,10 @@ export class ElapsedTime {
      * Gets the number of milliseconds in the elapsed time (excluding complete seconds).
      */
     get Milliseconds() {
-        this._CalculateTimeValues();
-        return this._Milliseconds;
+        return this._getCachedProperty('milliseconds', () => {
+            this._CalculateTimeValues();
+            return this._milliseconds;
+        });
     }
     /**
      * Gets the milliseconds component as a padded string.
@@ -215,21 +267,22 @@ export class ElapsedTime {
      * Checks if the elapsed time represents a negative duration.
      */
     get IsNegative() {
-        return this._IsNegative;
+        return this._isNegative;
     }
     /**
      * Gets the total number of milliseconds in the elapsed time.
      */
     get TotalMilliseconds() {
-        return this._TotalMilliseconds;
+        return this._totalMilliseconds;
     }
     /**
      * Sets the total number of milliseconds in the elapsed time.
      */
     set TotalMilliseconds(value) {
-        this._IsNegative = value < 0;
-        this._TotalMilliseconds = Math.abs(value);
-        this._ValuesCalculated = false;
+        this._isNegative = value < 0;
+        this._totalMilliseconds = Math.abs(value);
+        this._valuesCalculated = false;
+        this._propertyCache = {};
     }
     /**
      * Get the total milliseconds as a padded string.
@@ -367,10 +420,6 @@ export class ElapsedTime {
         this._CalculateTimeValues();
         let resolvedOptions = { ...options };
         // Handle predefined formats
-        const FORMAT_ALIASES = {
-            mostsignificant: 'mostSignificant',
-            timewithseconds: 'timeWithSeconds',
-        };
         let formatKey = '';
         if (typeof format === 'string') {
             const stripped = format.toLowerCase().replace(/_/g, '');
@@ -384,7 +433,7 @@ export class ElapsedTime {
         if (formatKey === 'long') {
             return this._FormatLong(appliedOptions);
         }
-        return this._FormatUsingTokens(appliedOptions, formatKey);
+        return this._FormatUsingTokens(appliedOptions, formatKey, options);
     }
     /**
      * Special formatter for LONG format with proper pluralization.
@@ -408,23 +457,23 @@ export class ElapsedTime {
     _FormatLong(options) {
         const parts = [];
         // Process each time unit in order of significance
-        if (this._Weeks > 0 || options.showZeroValues) {
-            parts.push(`${this._Weeks} ${this._Weeks === 1 ? 'week' : 'weeks'}`);
+        if (this._weeks > 0 || options.showZeroValues) {
+            parts.push(`${this._weeks} ${this._weeks === 1 ? 'week' : 'weeks'}`);
         }
-        if (this._Days > 0 || options.showZeroValues) {
-            parts.push(`${this._Days} ${this._Days === 1 ? 'day' : 'days'}`);
+        if (this._days > 0 || options.showZeroValues) {
+            parts.push(`${this._days} ${this._days === 1 ? 'day' : 'days'}`);
         }
-        if (this._Hours > 0 || options.showZeroValues) {
-            parts.push(`${this._Hours} ${this._Hours === 1 ? 'hour' : 'hours'}`);
+        if (this._hours > 0 || options.showZeroValues) {
+            parts.push(`${this._hours} ${this._hours === 1 ? 'hour' : 'hours'}`);
         }
-        if (this._Minutes > 0 || options.showZeroValues) {
-            parts.push(`${this._Minutes} ${this._Minutes === 1 ? 'minute' : 'minutes'}`);
+        if (this._minutes > 0 || options.showZeroValues) {
+            parts.push(`${this._minutes} ${this._minutes === 1 ? 'minute' : 'minutes'}`);
         }
-        if (this._Seconds > 0 || options.showZeroValues) {
-            parts.push(`${this._Seconds} ${this._Seconds === 1 ? 'second' : 'seconds'}`);
+        if (this._seconds > 0 || options.showZeroValues) {
+            parts.push(`${this._seconds} ${this._seconds === 1 ? 'second' : 'seconds'}`);
         }
-        if (this._Milliseconds > 0 || options.showZeroValues) {
-            parts.push(`${this._Milliseconds} ${this._Milliseconds === 1 ? 'millisecond' : 'milliseconds'}`);
+        if (this._milliseconds > 0 || options.showZeroValues) {
+            parts.push(`${this._milliseconds} ${this._milliseconds === 1 ? 'millisecond' : 'milliseconds'}`);
         }
         // Handle case where no parts were added
         if (parts.length === 0) {
@@ -462,7 +511,7 @@ export class ElapsedTime {
      * // Called automatically by Format() method for most format types
      * ```
      */
-    _FormatUsingTokens(options, formatKey = '') {
+    _FormatUsingTokens(options, formatKey = '', originalOptions = {}) {
         // Define all available time units
         const units = [
             { unit: 'week', value: this.Weeks },
@@ -475,6 +524,8 @@ export class ElapsedTime {
         // Filter and limit units based on options
         const filteredUnits = ElapsedTime._FilterAndLimitUnits(units, options);
         const unitLabels = options.unitLabels ?? DEFAULT_UNIT_LABELS.medium;
+        // Determine if custom labels were explicitly provided by the user (not from format defaults)
+        const hasCustomLabels = originalOptions.unitLabels !== undefined;
         // Determine the formatting approach based on the resolved format key.
         // TIME and TIME_WITH_SECONDS use a colon-separated layout; all other
         // predefined and custom formats use the standard token layout.
@@ -485,7 +536,7 @@ export class ElapsedTime {
         }
         else {
             // Handle different format types
-            formatted = ElapsedTime._FormatStandardUnits(filteredUnits, unitLabels);
+            formatted = ElapsedTime._FormatStandardUnits(filteredUnits, unitLabels, formatKey, hasCustomLabels);
         }
         return this.IsNegative ? ElapsedTime._ApplyNegativeFormatting(formatted, options) : formatted;
     }
@@ -510,10 +561,12 @@ export class ElapsedTime {
      * 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
      */
-    static _FormatStandardUnits(units, unitLabels) {
+    static _FormatStandardUnits(units, unitLabels, formatKey = '', hasCustomLabels = false) {
         // Function-based labels: invoke each label function with the value (e.g. pluralization)
         if (Object.values(unitLabels).some((label) => typeof label === 'function')) {
             return units.map(({ unit, value }) => {
@@ -524,15 +577,25 @@ export class ElapsedTime {
                 return `${value} ${label}`;
             }).join(' ');
         }
-        // For CONCISE and SHORT formats (e.g., "1h 30m" or "1hr 30min")
-        if (unitLabels === DEFAULT_UNIT_LABELS.concise || unitLabels === DEFAULT_UNIT_LABELS.short) {
+        // Detect the format style from the labels object or fall back to formatKey.
+        // This check is more robust than reference equality: it works even if a copy
+        // of the DEFAULT_UNIT_LABELS object is passed by external code.
+        const labelStyle = unitLabels.style;
+        const style = labelStyle || formatKey;
+        // Check if these are truly custom labels (not from DEFAULT_UNIT_LABELS or a copy thereof).
+        // If the labels have a recognized style property, treat them as default-style labels.
+        const isDefaultStyle = labelStyle !== undefined && ['concise', 'short', 'medium', 'long'].includes(labelStyle);
+        const hasActuallyCustomLabels = hasCustomLabels && !isDefaultStyle;
+        // For CONCISE and SHORT formats with default labels (no custom override)
+        // No space between value and label (e.g., "1h 30m" or "1hr 30min")
+        if (!hasActuallyCustomLabels && (style === 'concise' || style === 'short')) {
             return units.map(({ unit, value }) => `${value}${unitLabels[unit]}`).join(' ');
         }
         // For MEDIUM format (e.g., "1 hour 30 min")
-        if (unitLabels === DEFAULT_UNIT_LABELS.medium) {
+        if (style === 'medium' || style === '') {
             return units.map(({ unit, value }) => `${value} ${unitLabels[unit]}`).join(' ');
         }
-        // Custom labels: join with a space so units are properly separated.
+        // Custom labels or other formats: join with a space so units are properly separated.
         return units.map(({ unit, value }) => {
             const label = unitLabels[unit];
             if (typeof label === 'undefined')
@@ -612,7 +675,8 @@ export class ElapsedTime {
 }
 /**
  * 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
@@ -625,6 +689,37 @@ export 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 function FormatElapsedTime(milliseconds, options) {
     const elapsedTime = new ElapsedTime(milliseconds);
@@ -639,4 +734,3 @@ export function FormatElapsedTime(milliseconds, options) {
     }
     return elapsedTime.Format('concise', formatOptions);
 }
-//# sourceMappingURL=elapsed-time.js.map