@pawells/typescript-common 1.0.0

package/build/time/elapsed-time/elapsed-time.d.ts

@@ -0,0 +1,412 @@
+import { 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;
+    /** The total duration in milliseconds (always positive, sign stored in isNegative) */
+    private _TotalMilliseconds;
+    /** Cached total seconds value */
+    private _TotalSeconds;
+    /** Cached total minutes value */
+    private _TotalMinutes;
+    /** Cached total hours value */
+    private _TotalHours;
+    /** Cached total days value */
+    private _TotalDays;
+    /** Cached seconds component (excluding complete minutes) */
+    private _Seconds;
+    /** Cached minutes component (excluding complete hours) */
+    private _Minutes;
+    /** Cached hours component (excluding complete days) */
+    private _Hours;
+    /** Cached days component (excluding complete weeks) */
+    private _Days;
+    /** Cached weeks component */
+    private _Weeks;
+    /** Cached milliseconds component (excluding complete seconds) */
+    private _Milliseconds;
+    /** Flag to track whether cached values have been calculated */
+    private _ValuesCalculated;
+    /**
+     * Creates a new ElapsedTime instance.
+     * @param milliseconds The total number of milliseconds.
+     */
+    constructor(milliseconds: number);
+    /**
+     * Calculate all time unit values for efficient access.
+     * This method performs the core time decomposition calculations and caches
+     * the results to avoid redundant computation on subsequent property access.
+     *
+     * The calculation process:
+     * 1. Converts total milliseconds to larger units (seconds, minutes, hours, days)
+     * 2. Calculates component values using modulo operations
+     * 3. Caches all results with the _valuesCalculated flag
+     *
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - called automatically when accessing time properties
+     * const elapsed = new ElapsedTime(93784000);  // 26h 3m 4s
+     * // First access triggers calculation
+     * console.log(elapsed.Hours);     // 2 (26 % 24)
+     * console.log(elapsed.TotalHours); // 26
+     * ```
+     */
+    private _CalculateTimeValues;
+    /**
+     * Gets the number of weeks in the elapsed time.
+     */
+    get Weeks(): number;
+    /**
+     * Gets the number of days in the elapsed time (excluding complete weeks).
+     */
+    get Days(): number;
+    /**
+     * Gets the total number of days in the elapsed time.
+     */
+    get TotalDays(): number;
+    /**
+     * Gets the number of hours in the elapsed time (excluding complete days).
+     */
+    get Hours(): number;
+    /**
+     * Gets the hours component as a padded string.
+     * @param length The minimum length to pad to (default: 2).
+     * @returns The zero-padded string.
+     */
+    HoursPadded(length?: number): string;
+    /**
+     * Gets the total number of hours in the elapsed time.
+     */
+    get TotalHours(): number;
+    /**
+     * Gets the total hours as a padded string.
+     * @param length The minimum length to pad to (default: 2).
+     * @returns The zero-padded string.
+     */
+    TotalHoursPadded(length?: number): string;
+    /**
+     * Gets the number of minutes in the elapsed time (excluding complete hours).
+     */
+    get Minutes(): number;
+    /**
+     * Gets the minutes component as a padded string.
+     * @param length The minimum length to pad to (default: 2).
+     * @returns The zero-padded string.
+     */
+    MinutesPadded(length?: number): string;
+    /**
+     * Gets the total number of minutes in the elapsed time.
+     */
+    get TotalMinutes(): number;
+    /**
+     * Gets the total minutes as a padded string.
+     * @param length The minimum length to pad to (default: 2).
+     * @returns The zero-padded string.
+     */
+    TotalMinutesPadded(length?: number): string;
+    /**
+     * Gets the number of seconds in the elapsed time (excluding complete minutes).
+     */
+    get Seconds(): number;
+    /**
+     * Gets the seconds component as a padded string.
+     * @param length The minimum length to pad to (default: 2).
+     * @returns The zero-padded string.
+     */
+    SecondsPadded(length?: number): string;
+    /**
+     * Gets the total number of seconds in the elapsed time.
+     */
+    get TotalSeconds(): number;
+    /**
+     * Gets the total seconds as a padded string.
+     * @param length The minimum length to pad to (default: 2).
+     * @returns The zero-padded string.
+     */
+    TotalSecondsPadded(length?: number): string;
+    /**
+     * Gets the number of milliseconds in the elapsed time (excluding complete seconds).
+     */
+    get Milliseconds(): number;
+    /**
+     * Gets the milliseconds component as a padded string.
+     * @param length The minimum length to pad to (default: 3).
+     * @returns The zero-padded string.
+     */
+    MillisecondsPadded(length?: number): string;
+    /**
+     * Checks if the elapsed time represents a negative duration.
+     */
+    get IsNegative(): boolean;
+    /**
+     * Gets the total number of milliseconds in the elapsed time.
+     */
+    get TotalMilliseconds(): number;
+    /**
+     * Sets the total number of milliseconds in the elapsed time.
+     */
+    set TotalMilliseconds(value: number);
+    /**
+     * Get the total milliseconds as a padded string.
+     *
+     * @param length - The minimum length to pad to (default: 3)
+     * @returns The total milliseconds as a zero-padded string
+     *
+     * @example
+     * ```typescript
+     * const elapsed = new ElapsedTime(5750);
+     * console.log(elapsed.TotalMillisecondsPadded());   // "5750"
+     * console.log(elapsed.TotalMillisecondsPadded(6));  // "005750"
+     * ```
+     */
+    TotalMillisecondsPadded(length?: number): string;
+    /**
+     * Create a new ElapsedTime instance from start and stop timestamps.
+     * Convenience method for calculating elapsed time between two points in time.
+     *
+     * @param start - The start time in milliseconds (typically from Date.now() or performance.now())
+     * @param stop - The stop time in milliseconds
+     * @returns A new ElapsedTime instance representing the duration between start and stop
+     *
+     * @example
+     * ```typescript
+     * const start = Date.now();
+     * // ... some operation that takes time ...
+     * const end = Date.now();
+     * const duration = ElapsedTime.From(start, end);
+     * console.log(duration.Format('CONCISE')); // "1s 250ms"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Using with performance.now() for high precision
+     * const start = performance.now();
+     * await someAsyncOperation();
+     * const end = performance.now();
+     * const duration = ElapsedTime.From(start, end);
+     * console.log(duration.Format('MEDIUM')); // "1 sec 250 ms"
+     * ```
+     */
+    static From(start: number, stop: number): ElapsedTime;
+    /**
+     * Format a duration of time using static method convenience.
+     * Creates a temporary ElapsedTime instance and formats it in one operation.
+     *
+     * @param milliseconds - The total number of milliseconds to format
+     * @param format - The format string or predefined format name (default: 'CONCISE')
+     * @param options - Formatting options of type ITimeElapsedFormatOptions for customization
+     * @returns The formatted time string
+     *
+     * @example
+     * ```typescript
+     * // Quick formatting without creating an instance
+     * console.log(ElapsedTime.Format(3661000));           // "1h 1m 1s"
+     * console.log(ElapsedTime.Format(3661000, 'LONG'));   // "1 hour 1 minute 1 second"
+     *
+     * // With custom options
+     * const options = { maxUnits: 2, showZeroValues: false };
+     * console.log(ElapsedTime.Format(3661000, 'MEDIUM', options)); // "1 hour 1 min"
+     * ```
+     */
+    static Format(milliseconds: number, format?: TTimeElapsedFormats, options?: Partial<ITimeElapsedFormatOptions>): string;
+    /**
+     * Format the elapsed time according to the specified format and options.
+     * This is the primary formatting method that handles all predefined formats
+     * and custom formatting configurations.
+     *
+     * Available predefined formats:
+     * - **CONCISE**: "1h 30m 45s" - Ultra-compact with single-letter units
+     * - **SHORT**: "1hr 30min 45sec" - Abbreviated but readable units
+     * - **MEDIUM**: "1 hour 30 min 45 sec" - Balanced readability and length
+     * - **LONG**: "1 hour 30 minutes 45 seconds" - Full words with proper pluralization
+     * - **MOST_SIGNIFICANT**: Shows only the 2 most significant units
+     * - **TIME**: "1:30" - Clock-style hours:minutes format
+     * - **TIME_WITH_SECONDS**: "1:30:45" - Extended clock format with seconds
+     *
+     * @param format - The format string or predefined format name (default: 'CONCISE')
+     * @param options - Formatting options of type ITimeElapsedFormatOptions for fine-tuned control
+     * @returns The formatted time string
+     *
+     * @example
+     * ```typescript
+     * const elapsed = new ElapsedTime(5425000);  // 1h 30m 25s
+     *
+     * // Predefined formats
+     * elapsed.Format('CONCISE');         // "1h 30m 25s"
+     * elapsed.Format('SHORT');           // "1hr 30min 25sec"
+     * elapsed.Format('MEDIUM');          // "1 hour 30 min 25 sec"
+     * elapsed.Format('LONG');            // "1 hour 30 minutes 25 seconds"
+     * elapsed.Format('TIME');            // "1:30"
+     * elapsed.Format('TIME_WITH_SECONDS'); // "1:30:25"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom formatting with options
+     * const elapsed = new ElapsedTime(-5425000);  // Negative duration
+     *
+     * const options = {
+     *   negativeValueFormat: 'Parenthesis',
+     *   maxUnits: 2,
+     *   showZeroValues: false
+     * };
+     *
+     * elapsed.Format('MEDIUM', options); // "(1 hour 30 min)"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom labels
+     * const elapsed = new ElapsedTime(5425000);
+     *
+     * const customOptions = {
+     *   unitLabels: {
+     *     hour: 'hrs',
+     *     minute: 'mins',
+     *     second: 'secs'
+     *   }
+     * };
+     *
+     * elapsed.Format('CUSTOM', customOptions); // "1 hrs 30 mins 25 secs"
+     * ```
+     */
+    Format(format?: TTimeElapsedFormats, options?: Partial<ITimeElapsedFormatOptions>): string;
+    /**
+     * Special formatter for LONG format with proper pluralization.
+     * Handles the unique requirements of the LONG format which uses
+     * full English words with grammatically correct singular/plural forms.
+     *
+     * @param options - Formatting options with LONG-specific settings
+     * @returns Formatted string with proper pluralization (e.g., "1 hour 30 minutes")
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - called automatically for LONG format
+     * const elapsed = new ElapsedTime(3661000);  // 1 hour, 1 minute, 1 second
+     * elapsed.Format('LONG'); // "1 hour 1 minute 1 second" (all singular)
+     *
+     * const elapsed2 = new ElapsedTime(7322000); // 2 hours, 2 minutes, 2 seconds
+     * elapsed2.Format('LONG'); // "2 hours 2 minutes 2 seconds" (all plural)
+     * ```
+     */
+    private _FormatLong;
+    /**
+     * Format the elapsed time using the token-based formatting system.
+     * This is the main formatting engine that handles all predefined formats
+     * except LONG (which has special pluralization requirements).
+     *
+     * The method:
+     * 1. Creates an array of time units with their values
+     * 2. Filters and limits units based on options
+     * 3. Determines formatting approach (TIME vs standard formats)
+     * 4. Applies appropriate formatting and returns the result
+     *
+     * @param options - Complete formatting options with defaults applied
+     * @returns Formatted time string according to the specified format
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - handles formats like CONCISE, SHORT, MEDIUM, TIME, etc.
+     * // Called automatically by Format() method for most format types
+     * ```
+     */
+    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")
+     * @param units - Array of time units with their values
+     * @param unitLabels - Object containing label definitions for each time unit
+     * @returns Formatted time string with colons (e.g., "1:30:45")
+     * @private
+     */
+    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
+     * @returns Formatted time string according to the specified format style
+     * @private
+     */
+    private static _FormatStandardUnits;
+    /**
+     * Determine if the unit labels represent a time format with colons.
+     * Analyzes the unit label configuration to detect TIME and TIME_WITH_SECONDS
+     * formats which require special colon-separated formatting.
+     *
+     * @param unitLabels - The unit labels to analyze
+     * @returns True if this is a colon-based time format, false for standard formats
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - distinguishes between:
+     * // TIME format: "1:30" (colon-separated)
+     * // CONCISE format: "1h 30m" (space-separated with labels)
+     * ```
+     */
+    private static _ValidateTimeFormat;
+    /**
+     * Filter and limit time units based on formatting options.
+     * Applies showZeroValues and maxUnits options to determine which
+     * time components should be included in the final formatted output.
+     *
+     * @param units - All available time units with their calculated values
+     * @param options - Formatting options containing filtering rules
+     * @returns Filtered and limited array of time units for formatting
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - handles cases like:
+     * // showZeroValues: false -> filters out units with value 0
+     * // maxUnits: 2 -> keeps only the first 2 significant units
+     * // All zero values -> ensures at least "0 seconds" is shown
+     * ```
+     */
+    private static _FilterAndLimitUnits;
+    /**
+     * Apply negative value formatting based on user preferences.
+     * Wraps or modifies the formatted time string to indicate negative durations
+     * according to the specified negativeValueFormat option.
+     *
+     * @param output - The pre-formatted time string (positive representation)
+     * @param options - Formatting options containing negative value format preference
+     * @returns The formatted string with negative formatting applied if needed
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Internal usage - transforms positive format to negative representation:
+     * // NegativeSign: "1h 30m" -> "-1h 30m"
+     * // Parenthesis: "1h 30m" -> "(1h 30m)"
+     * // Brackets: "1h 30m" -> "[1h 30m]"
+     * // Empty: "1h 30m" -> "1h 30m" (no change)
+     * ```
+     */
+    private static _ApplyNegativeFormatting;
+}
+/**
+ * Formats elapsed time using the specified configuration.
+ * This is a simplified formatting function that uses IFormatConfig for basic formatting options.
+ *
+ * @param milliseconds - The total number of milliseconds to format
+ * @param options - Formatting configuration options
+ * @returns The formatted time string
+ *
+ * @example
+ * ```typescript
+ * import { FormatElapsedTime } from './elapsed-time';
+ *
+ * console.log(FormatElapsedTime(3661000)); // "1h 1m 1s"
+ * console.log(FormatElapsedTime(3661000, { maxUnits: 1 })); // "1h"
+ * ```
+ */
+export declare function FormatElapsedTime(milliseconds: number, options?: IFormatConfig): string;
+//# sourceMappingURL=elapsed-time.d.ts.map

package/build/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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"}