@pawells/typescript-common 2.0.0 → 2.1.5

package/dist/string/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * String validator function type.
+ *
+ * A validator function that tests if a string meets certain criteria.
+ *
+ * @param value - The string to validate
+ * @returns true if the string passes validation, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isLong: TStringValidator = (s) => s.length > 10;
+ * isLong('hello'); // false
+ * isLong('hello world'); // true
+ * ```
+ */
+export type TStringValidator = (value: string) => boolean;
+/**
+ * String formatter function type with optional parameters.
+ *
+ * A formatter function that transforms a string with optional formatting parameters.
+ *
+ * @param value - The string to format
+ * @param params - Optional formatting parameters
+ * @returns The formatted string
+ *
+ * @example
+ * ```typescript
+ * const uppercase: TStringFormatter = (s) => s.toUpperCase();
+ * uppercase('hello'); // 'HELLO'
+ * ```
+ */
+export type TStringFormatter = (value: string, ...params: unknown[]) => string;
+/**
+ * String transformer function type.
+ *
+ * A transformer function that converts input to a transformed string output.
+ *
+ * @param input - The input string
+ * @returns The transformed string
+ *
+ * @example
+ * ```typescript
+ * const reverse: TStringTransformer = (s) => Array.from(s).reverse().join('');
+ * reverse('hello'); // 'olleh'
+ * ```
+ */
+export type TStringTransformer = (input: string) => string;
+/**
+ * Case converter function type.
+ *
+ * A function that converts a string to a specific case format (camelCase, PascalCase, etc.).
+ *
+ * @param value - The string to convert
+ * @returns The string in the target case format
+ *
+ * @example
+ * ```typescript
+ * const toCamel: TCaseConverter = (s) => s.replace(/-(.)/g, (_, c) => c.toUpperCase());
+ * toCamel('hello-world'); // 'helloWorld'
+ * ```
+ */
+export type TCaseConverter = (value: string) => string;
+/**
+ * String predicate function type.
+ *
+ * A predicate function that tests if a string meets a specific condition.
+ *
+ * @param value - The string to test
+ * @returns true if the string passes the predicate, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isEmail: TStringPredicate = (s) => s.includes('@');
+ * isEmail('user@example.com'); // true
+ * isEmail('invalid'); // false
+ * ```
+ */
+export type TStringPredicate = (value: string) => boolean;
+/**
+ * Format parameter value types.
+ *
+ * Supported types for placeholder values in string formatting operations.
+ *
+ * @returns N/A - This is a type alias
+ *
+ * @example
+ * ```typescript
+ * const values: TFormatValue[] = [42, 'hello', true, null, undefined];
+ * ```
+ */
+export type TFormatValue = string | number | boolean | null | undefined;
+/**
+ * Format parameters as key-value pairs.
+ *
+ * Object structure for named placeholder substitution in string formatting.
+ *
+ * @returns N/A - This is a type alias
+ *
+ * @example
+ * ```typescript
+ * const params: TFormatParams = { name: 'World', count: 42 };
+ * ```
+ */
+export type TFormatParams = Record<string, TFormatValue>;
+/**
+ * Format parameters as positional array.
+ *
+ * Array structure for positional placeholder substitution in string formatting.
+ *
+ * @returns N/A - This is a type alias
+ *
+ * @example
+ * ```typescript
+ * const args: TFormatArgs = ['World', 42, true];
+ * ```
+ */
+export type TFormatArgs = TFormatValue[];
+//# sourceMappingURL=types.d.ts.map

package/dist/string/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/string/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAEvD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,EAAE,CAAC"}

package/dist/string/types.js

@@ -0,0 +1 @@
+export {};

package/{build → dist}/string/validation.js

@@ -36,4 +36,3 @@ const HEX_PATTERN = /^(?<prefix>#|0x)?(?<hex>[0-9a-f]+)$/iu;
 export function IsHexString(value) {
     return HEX_PATTERN.test(value);
 }
-//# sourceMappingURL=validation.js.map

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

@@ -0,0 +1,36 @@
+import type { IDefaultUnitLabels, IFormats } from './types.js';
+/**
+ * Default unit label sets for all predefined formatting styles.
+ * Provides pre-defined label configurations for concise, short, medium, and long time formats.
+ *
+ * Each style object maps time units (week, day, hour, minute, second, millisecond) to their labels.
+ * Labels can be static strings (concise, short, medium) or functions that handle pluralization (long).
+ * All label sets include a `style` property for runtime identification.
+ *
+ * @example
+ * ```typescript
+ * // Using concise labels: single-character abbreviations
+ * const conciseLabel = DEFAULT_UNIT_LABELS.concise.hour;  // "h"
+ *
+ * // Using long labels: function-based with pluralization
+ * const longLabel = DEFAULT_UNIT_LABELS.long.hour(1);     // "hour"
+ * const longLabel2 = DEFAULT_UNIT_LABELS.long.hour(2);    // "hours"
+ *
+ * // Using medium labels: readable abbreviations
+ * const mediumLabel = DEFAULT_UNIT_LABELS.medium.hour;    // "hour"
+ * ```
+ */
+export declare const DEFAULT_UNIT_LABELS: IDefaultUnitLabels;
+/**
+ * Predefined format configurations for elapsed time formatting.
+ * Each configuration provides unitLabels and optional display options for a specific format style.
+ *
+ * @remarks
+ * The `long` format configuration defines pluralization logic for unit labels (e.g., "hour" vs "hours").
+ * This logic is duplicated in the `ElapsedTime._FormatLong()` private method, which handles the special
+ * formatting requirements of the long format with its own pluralization. Both locations must be kept in
+ * sync when modifying singular/plural unit names. This duplication exists because the FORMATS constant
+ * provides label templates while _FormatLong() handles the actual runtime transformation.
+ */
+export declare const FORMATS: IFormats;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/time/elapsed-time/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,kBAuCxB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,OAAO,EAAE,QAkEZ,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/time/elapsed-time/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,EAAE,kBAqCxB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,EAAE,QA4DZ,CAAC"}

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

@@ -1,8 +1,27 @@
 /**
- * Default unit labels for different formatting styles.
+ * Default unit label sets for all predefined formatting styles.
+ * Provides pre-defined label configurations for concise, short, medium, and long time formats.
+ *
+ * Each style object maps time units (week, day, hour, minute, second, millisecond) to their labels.
+ * Labels can be static strings (concise, short, medium) or functions that handle pluralization (long).
+ * All label sets include a `style` property for runtime identification.
+ *
+ * @example
+ * ```typescript
+ * // Using concise labels: single-character abbreviations
+ * const conciseLabel = DEFAULT_UNIT_LABELS.concise.hour;  // "h"
+ *
+ * // Using long labels: function-based with pluralization
+ * const longLabel = DEFAULT_UNIT_LABELS.long.hour(1);     // "hour"
+ * const longLabel2 = DEFAULT_UNIT_LABELS.long.hour(2);    // "hours"
+ *
+ * // Using medium labels: readable abbreviations
+ * const mediumLabel = DEFAULT_UNIT_LABELS.medium.hour;    // "hour"
+ * ```
  */
 export const DEFAULT_UNIT_LABELS = {
     concise: {
+        style: 'concise',
         day: 'd',
         hour: 'h',
         millisecond: 'ms',
@@ -11,6 +30,7 @@ export const DEFAULT_UNIT_LABELS = {
         week: 'w',
     },
     long: {
+        style: 'long',
         day: (value) => `${value === 1 ? 'day' : 'days'}`,
         hour: (value) => `${value === 1 ? 'hour' : 'hours'}`,
         millisecond: (value) => `${value === 1 ? 'millisecond' : 'milliseconds'}`,
@@ -19,6 +39,7 @@ export const DEFAULT_UNIT_LABELS = {
         week: (value) => `${value === 1 ? 'week' : 'weeks'}`,
     },
     medium: {
+        style: 'medium',
         day: 'day',
         hour: 'hour',
         millisecond: 'ms',
@@ -27,6 +48,7 @@ export const DEFAULT_UNIT_LABELS = {
         week: 'week',
     },
     short: {
+        style: 'short',
         day: 'd',
         hour: 'hr',
         millisecond: 'ms',
@@ -36,7 +58,15 @@ export const DEFAULT_UNIT_LABELS = {
     },
 };
 /**
- * Predefined formatter styles with comprehensive formatting options.
+ * Predefined format configurations for elapsed time formatting.
+ * Each configuration provides unitLabels and optional display options for a specific format style.
+ *
+ * @remarks
+ * The `long` format configuration defines pluralization logic for unit labels (e.g., "hour" vs "hours").
+ * This logic is duplicated in the `ElapsedTime._FormatLong()` private method, which handles the special
+ * formatting requirements of the long format with its own pluralization. Both locations must be kept in
+ * sync when modifying singular/plural unit names. This duplication exists because the FORMATS constant
+ * provides label templates while _FormatLong() handles the actual runtime transformation.
  */
 export const FORMATS = {
     /**
@@ -93,4 +123,3 @@ export const FORMATS = {
         },
     },
 };
-//# sourceMappingURL=constants.js.map

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.
@@ -56,6 +62,18 @@ export declare class ElapsedTime {
      * ```
      */
     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.
      */
@@ -332,6 +350,8 @@ export declare 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
      */
@@ -378,7 +398,8 @@ export declare 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
@@ -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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"}