@transcommerce/cwm-shared 1.1.88 → 1.1.91

package/lib/components/external-navigation/external-navigation.component.d.ts

@@ -13,5 +13,5 @@ export declare class ExternalNavigationComponent implements AfterViewInit {
     navigateToExternalHref(): void;
     onKeyPress($event: KeyboardEvent): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<ExternalNavigationComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<ExternalNavigationComponent, "cwm-external-navigation", never, {}, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ExternalNavigationComponent, "cwm-external-navigation", never, {}, {}, never, never, true, never>;
 }

package/lib/components/navigate-to-route/navigate-to-route.component.d.ts

@@ -9,5 +9,5 @@ export declare class NavigateToRouteComponent implements AfterViewInit {
     navigateToRoute(): void;
     onKeyPress($event: KeyboardEvent): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<NavigateToRouteComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<NavigateToRouteComponent, "cwm-navigate-to-route", never, {}, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<NavigateToRouteComponent, "cwm-navigate-to-route", never, {}, {}, never, never, true, never>;
 }

package/lib/components/page-not-found/page-not-found.component.d.ts

@@ -12,5 +12,5 @@ export declare class PageNotFoundComponent implements OnInit, OnDestroy {
     ngOnDestroy(): void;
     private startRedirectTimer;
     static ɵfac: i0.ɵɵFactoryDeclaration<PageNotFoundComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<PageNotFoundComponent, "cwm-page-not-found", never, {}, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PageNotFoundComponent, "cwm-page-not-found", never, {}, {}, never, never, true, never>;
 }

package/lib/cwm-shared-standalone.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Standalone Angular architecture for cwm-shared library
+ * Export all standalone components, pipes, directives, and injectable services
+ */
+export { ExternalNavigationComponent } from './components/external-navigation/external-navigation.component';
+export { NavigateToRouteComponent } from './components/navigate-to-route/navigate-to-route.component';
+export { PageNotFoundComponent } from './components/page-not-found/page-not-found.component';
+export { SafeHtmlPipe } from './pipes/safe-html.pipe';
+export { BaseApiService } from './services/base-api.service';
+export type { IBaseApiService } from './services/ibase-api.service';
+export { ClassLoggerService } from './services/class-logger.service';
+export { ConfigService } from './services/config.service';
+export { InventoryApiService } from './services/inventory-api.service';
+export { LocalStorageService } from './services/local-storage.service';
+export { LogService } from './services/log.service';
+export { SubscriptionApiService } from './services/subscription-api.service';
+export { msalInstanceFactory } from './factories/msal.instance.factory';
+export { msalGuardConfigFactory } from './factories/msal.guard.config.factory';
+export { msalInterceptorConfigFactory } from './factories/msal-interceptor-config.factory';

package/lib/helpers/async-utils.d.ts

@@ -1,9 +1,20 @@
+/**
+ * @module async-utils
+ * @description Utility functions for working with asynchronous code and managing concurrent task execution.
+ * Provides utilities for delays, promise management, and synchronization primitives for controlling
+ * the execution of async tasks to ensure only one task executes at a time for a given lock name.
+ */
 /**
  * A wrapper around setTimeout which returns a promise. Useful for waiting for an amount of
  * time from an async function. e.g. await waitFor(1000);
  *
  * @param milliseconds The amount of time to wait.
  * @returns A promise that resolves once the given number of milliseconds has ellapsed.
+ *
+ * @example
+ * // Wait for 2 seconds before continuing
+ * await waitFor(2000);
+ * console.log('2 seconds have passed');
  */
 export declare function waitFor(milliseconds: number): Promise<void>;
 /**
@@ -14,8 +25,25 @@ export declare function waitFor(milliseconds: number): Promise<void>;
  * lock name for a group of tasks you can ensure the only one task will ever be in progress
  * at a given time.
  *
- * @param lockName The name of the lock to be obtained.
- * @param task The task to execute.
- * @returns The value returned by the task.
+ * Uses a queue-based locking mechanism where tasks are executed in FIFO order. Each task must
+ * complete (or throw an error) before the next task in the queue begins execution.
+ *
+ * @param lockName The name of the lock to be obtained. Tasks with the same lock name will be serialized.
+ * @param task The task to execute. Should return a Promise.
+ * @returns The value returned by the task. Rejects if the task throws an error.
+ *
+ * @example
+ * // Execute multiple API calls sequentially to prevent race conditions
+ * const result1 = await doWithLock('api-calls', async () => {
+ *   return await fetchUser(userId);
+ * });
+ *
+ * @example
+ * // Multiple locks can run in parallel, but tasks with the same lock name are serialized
+ * await Promise.all([
+ *   doWithLock('lock-a', () => slowTask1()),
+ *   doWithLock('lock-a', () => slowTask2()), // Waits for slowTask1 to complete
+ *   doWithLock('lock-b', () => otherTask()) // Runs in parallel with the lock-a tasks
+ * ]);
  */
 export declare function doWithLock<T>(lockName: string, task: () => Promise<T>): Promise<T>;

package/lib/helpers/jwt.d.ts

@@ -1,2 +1,37 @@
+/**
+ * Decodes a JWT (JSON Web Token) and returns the decoded claims as an object.
+ *
+ * JWT tokens consist of three Base64-encoded parts separated by dots: header.payload.signature.
+ * This function decodes all parts and merges them into a single object, returning the combined result.
+ *
+ * @param token The JWT token string to decode. Can be a complete token or any of its parts.
+ * @returns An object containing the decoded claims from the token parts, or undefined if the token is empty or invalid.
+ *
+ * @example
+ * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+ * const decoded = decodeToken(token);
+ * // Returns: { alg: 'HS256', typ: 'JWT', sub: '1234567890', name: 'John Doe', iat: 1516239022 }
+ */
 export declare function decodeToken(token: string): any;
+/**
+ * Validates whether a JWT token is still valid based on its expiration time.
+ *
+ * This function checks the 'exp' (expiration) claim of a JWT token. The expiration time is
+ * expected to be a Unix timestamp (seconds since epoch). If the current time is less than the
+ * expiration time, the token is considered valid.
+ *
+ * @param input Either a JWT token string (from which the expiration will be extracted) or
+ *              a Unix timestamp (expiration time in seconds). If invalid or undefined, returns false.
+ * @returns true if the token/timestamp has not yet expired, false otherwise.
+ *
+ * @example
+ * // Check if a token string is valid
+ * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjk5OTk5OTk5OTl9.xxx';
+ * const isValid = isTokenValid(token); // true if not expired
+ *
+ * @example
+ * // Check if an expiration timestamp is valid
+ * const futureTimestamp = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
+ * const isValid = isTokenValid(futureTimestamp); // true
+ */
 export declare function isTokenValid(input: string | number): boolean;

package/lib/helpers/time-span.d.ts

@@ -1,32 +1,376 @@
+/**
+ * Represents an error that occurs when a TimeSpan operation would result in a value
+ * that exceeds the safe bounds of a number in JavaScript.
+ *
+ * This error is thrown when:
+ * - Creating a TimeSpan from a value that, when multiplied by a time scale (e.g., days, hours),
+ *   would exceed {@link TimeSpan.maxValue} or fall below {@link TimeSpan.minValue}
+ * - Adding or subtracting TimeSpan instances would result in overflow
+ * - Converting time components that would exceed safe integer bounds
+ *
+ * The safe bounds are defined by JavaScript's {@link Number.MAX_SAFE_INTEGER} and
+ * {@link Number.MIN_SAFE_INTEGER}.
+ *
+ * @example
+ * try {
+ *   // This will throw TimeSpanOverflowError
+ *   const hugeSpan = TimeSpan.fromDays(Number.MAX_SAFE_INTEGER);
+ * } catch (error) {
+ *   if (error instanceof TimeSpanOverflowError) {
+ *     console.log('TimeSpan duration exceeded safe bounds');
+ *   }
+ * }
+ */
+export declare class TimeSpanOverflowError extends Error {
+}
+/**
+ * Represents a time interval with support for days, hours, minutes, seconds, and milliseconds.
+ *
+ * The TimeSpan class provides a way to represent and work with time durations, similar to
+ * .NET's TimeSpan class. It stores time internally as milliseconds and provides various
+ * static factory methods to create instances from different time units.
+ *
+ * @example
+ * // Create a TimeSpan of 5 days
+ * const fiveDays = TimeSpan.fromDays(5);
+ *
+ * @example
+ * // Create a TimeSpan from specific time components
+ * const timespan = TimeSpan.fromTime(2, 30, 45); // 2 hours, 30 minutes, 45 seconds
+ *
+ * @example
+ * // Create a TimeSpan from a string representation
+ * const parsed = TimeSpan.fromString("5:30:45"); // 5 hours, 30 minutes, 45 seconds
+ */
 export declare class TimeSpan {
+    /** @private The number of milliseconds represented by this TimeSpan */
     private _millis;
+    /**
+     * @private
+     * Creates a TimeSpan from a value and time scale.
+     * Converts the value using the provided scale factor and rounds the result.
+     *
+     * @param value - The numeric value to convert
+     * @param scale - The scale factor (e.g., MILLIS_PER_DAY) to multiply by
+     * @returns A new TimeSpan instance
+     * @throws {Error} If value is NaN
+     * @throws {TimeSpanOverflowError} If the resulting milliseconds exceed safe integer bounds
+     */
     private static interval;
+    /**
+     * @private
+     * Rounds a number towards zero (floor for positive, ceil for negative).
+     *
+     * @param n - The number to round
+     * @returns The rounded number
+     */
     private static round;
+    /**
+     * @private
+     * Converts time components (hours, minutes, seconds) to milliseconds.
+     * Validates that the total does not exceed TimeSpan bounds.
+     *
+     * @param hour - The number of hours (0-23 for typical usage)
+     * @param minute - The number of minutes (0-59)
+     * @param second - The number of seconds (0-59)
+     * @returns The total milliseconds
+     * @throws {TimeSpanOverflowError} If the total seconds exceed safe bounds
+     */
     private static timeToMilliseconds;
+    /**
+     * Gets a TimeSpan instance representing zero duration.
+     *
+     * @returns A TimeSpan with 0 milliseconds
+     */
     static get zero(): TimeSpan;
+    /**
+     * Gets the maximum possible TimeSpan value.
+     * Uses JavaScript's MAX_SAFE_INTEGER as the underlying millisecond limit.
+     *
+     * @returns A TimeSpan with the maximum safe integer milliseconds
+     */
     static get maxValue(): TimeSpan;
+    /**
+     * Gets the minimum possible TimeSpan value.
+     * Uses JavaScript's MIN_SAFE_INTEGER as the underlying millisecond limit.
+     *
+     * @returns A TimeSpan with the minimum safe integer milliseconds
+     */
     static get minValue(): TimeSpan;
+    /**
+     * Creates a TimeSpan from a number of days.
+     *
+     * @param value - The number of days
+     * @returns A new TimeSpan instance representing the specified duration
+     * @throws {Error} If value is NaN
+     * @throws {TimeSpanOverflowError} If the result exceeds safe bounds
+     *
+     * @example
+     * const span = TimeSpan.fromDays(7); // 7 days
+     */
     static fromDays(value: number): TimeSpan;
+    /**
+     * Creates a TimeSpan from a number of hours.
+     *
+     * @param value - The number of hours
+     * @returns A new TimeSpan instance representing the specified duration
+     * @throws {Error} If value is NaN
+     * @throws {TimeSpanOverflowError} If the result exceeds safe bounds
+     *
+     * @example
+     * const span = TimeSpan.fromHours(24); // 24 hours = 1 day
+     */
     static fromHours(value: number): TimeSpan;
+    /**
+     * Creates a TimeSpan from a number of milliseconds.
+     *
+     * @param value - The number of milliseconds
+     * @returns A new TimeSpan instance representing the specified duration
+     * @throws {Error} If value is NaN
+     * @throws {TimeSpanOverflowError} If the result exceeds safe bounds
+     *
+     * @example
+     * const span = TimeSpan.fromMilliseconds(5000); // 5 seconds
+     */
     static fromMilliseconds(value: number): TimeSpan;
+    /**
+     * Creates a TimeSpan from a number of minutes.
+     *
+     * @param value - The number of minutes
+     * @returns A new TimeSpan instance representing the specified duration
+     * @throws {Error} If value is NaN
+     * @throws {TimeSpanOverflowError} If the result exceeds safe bounds
+     *
+     * @example
+     * const span = TimeSpan.fromMinutes(60); // 60 minutes = 1 hour
+     */
     static fromMinutes(value: number): TimeSpan;
+    /**
+     * Creates a TimeSpan from a number of seconds.
+     *
+     * @param value - The number of seconds
+     * @returns A new TimeSpan instance representing the specified duration
+     * @throws {Error} If value is NaN
+     * @throws {TimeSpanOverflowError} If the result exceeds safe bounds
+     *
+     * @example
+     * const span = TimeSpan.fromSeconds(300); // 300 seconds = 5 minutes
+     */
     static fromSeconds(value: number): TimeSpan;
+    /**
+     * Creates a TimeSpan from time components.
+     *
+     * This method has two overloads:
+     * 1. fromTime(hours, minutes, seconds) - Creates a TimeSpan with hours, minutes, and seconds
+     * 2. fromTime(days, hours, minutes, seconds, milliseconds) - Creates a TimeSpan with all components
+     *
+     * @overload
+     * @param hours - The number of hours (0-23 for typical usage)
+     * @param minutes - The number of minutes (0-59)
+     * @param seconds - The number of seconds (0-59)
+     * @returns A new TimeSpan instance representing the specified duration
+     *
+     * @overload
+     * @param days - The number of days
+     * @param hours - The number of hours (0-23 for typical usage)
+     * @param minutes - The number of minutes (0-59)
+     * @param seconds - The number of seconds (0-59)
+     * @param milliseconds - The number of milliseconds (0-999)
+     * @returns A new TimeSpan instance representing the specified duration
+     *
+     * @throws {TimeSpanOverflowError} If the total exceeds safe bounds
+     *
+     * @example
+     * // Create 2 hours, 30 minutes, 45 seconds
+     * const span1 = TimeSpan.fromTime(2, 30, 45);
+     *
+     * @example
+     * // Create 5 days, 2 hours, 30 minutes, 45 seconds, 500 milliseconds
+     * const span2 = TimeSpan.fromTime(5, 2, 30, 45, 500);
+     */
     static fromTime(hours: number, minutes: number, seconds: number): TimeSpan;
     static fromTime(days: number, hours: number, minutes: number, seconds: number, milliseconds: number): TimeSpan;
+    /**
+     * @private
+     * Creates a TimeSpan from hours, minutes, and seconds components.
+     *
+     * @param hours - The number of hours
+     * @param minutes - The number of minutes
+     * @param seconds - The number of seconds
+     * @returns A new TimeSpan instance
+     * @throws {TimeSpanOverflowError} If the total exceeds safe bounds
+     */
     private static fromTimeStartingFromHours;
+    /**
+     * @private
+     * Creates a TimeSpan from all time components (days through milliseconds).
+     *
+     * @param days - The number of days
+     * @param hours - The number of hours
+     * @param minutes - The number of minutes
+     * @param seconds - The number of seconds
+     * @param milliseconds - The number of milliseconds
+     * @returns A new TimeSpan instance
+     * @throws {TimeSpanOverflowError} If the total exceeds safe bounds
+     */
     private static fromTimeStartingFromDays;
+    /**
+     * Creates a new TimeSpan instance with the specified number of milliseconds.
+     *
+     * @param millis - The total number of milliseconds
+     *
+     * @example
+     * const span = new TimeSpan(5000); // 5 seconds
+     */
     constructor(millis: number);
+    /**
+     * Gets the day component of this TimeSpan (0-31+).
+     * This returns only the day portion, not the total days.
+     *
+     * @returns The number of whole days
+     * @example
+     * const span = TimeSpan.fromTime(1, 5, 30, 0); // 1 day, 5 hours, 30 minutes
+     * console.log(span.days); // 1
+     */
     get days(): number;
+    /**
+     * Gets the hours component of this TimeSpan (0-23).
+     * This returns only the hours portion within a day, not the total hours.
+     *
+     * @returns The number of hours (0-23)
+     * @example
+     * const span = TimeSpan.fromTime(25, 30, 0); // 25 hours, 30 minutes
+     * console.log(span.hours); // 1 (25 % 24)
+     */
     get hours(): number;
+    /**
+     * Gets the minutes component of this TimeSpan (0-59).
+     * This returns only the minutes portion within an hour, not the total minutes.
+     *
+     * @returns The number of minutes (0-59)
+     * @example
+     * const span = TimeSpan.fromTime(0, 90, 0); // 90 minutes
+     * console.log(span.minutes); // 30 (90 % 60)
+     */
     get minutes(): number;
+    /**
+     * Gets the seconds component of this TimeSpan (0-59).
+     * This returns only the seconds portion within a minute, not the total seconds.
+     *
+     * @returns The number of seconds (0-59)
+     * @example
+     * const span = TimeSpan.fromTime(0, 0, 90); // 90 seconds
+     * console.log(span.seconds); // 30 (90 % 60)
+     */
     get seconds(): number;
+    /**
+     * Gets the milliseconds component of this TimeSpan (0-999).
+     * This returns only the milliseconds portion within a second, not the total milliseconds.
+     *
+     * @returns The number of milliseconds (0-999)
+     * @example
+     * const span = TimeSpan.fromTime(0, 0, 0, 1, 500); // 1 second, 500 milliseconds
+     * console.log(span.milliseconds); // 500
+     */
     get milliseconds(): number;
+    /**
+     * Gets the total number of days in this TimeSpan.
+     * Unlike the {@link days} property, this returns the complete duration in days as a decimal.
+     *
+     * @returns The total duration in days
+     * @example
+     * const span = TimeSpan.fromHours(30); // 30 hours
+     * console.log(span.totalDays); // 1.25
+     */
     get totalDays(): number;
+    /**
+     * Gets the total number of hours in this TimeSpan.
+     * Unlike the {@link hours} property, this returns the complete duration in hours as a decimal.
+     *
+     * @returns The total duration in hours
+     * @example
+     * const span = TimeSpan.fromMinutes(90); // 90 minutes
+     * console.log(span.totalHours); // 1.5
+     */
     get totalHours(): number;
+    /**
+     * Gets the total number of minutes in this TimeSpan.
+     * Unlike the {@link minutes} property, this returns the complete duration in minutes as a decimal.
+     *
+     * @returns The total duration in minutes
+     * @example
+     * const span = TimeSpan.fromSeconds(150); // 150 seconds
+     * console.log(span.totalMinutes); // 2.5
+     */
     get totalMinutes(): number;
+    /**
+     * Gets the total number of seconds in this TimeSpan.
+     * Unlike the {@link seconds} property, this returns the complete duration in seconds as a decimal.
+     *
+     * @returns The total duration in seconds
+     * @example
+     * const span = TimeSpan.fromMilliseconds(5500); // 5500 milliseconds
+     * console.log(span.totalSeconds); // 5.5
+     */
     get totalSeconds(): number;
+    /**
+     * Gets the total number of milliseconds in this TimeSpan.
+     *
+     * @returns The total duration in milliseconds
+     * @example
+     * const span = TimeSpan.fromSeconds(2); // 2 seconds
+     * console.log(span.totalMilliseconds); // 2000
+     */
     get totalMilliseconds(): number;
+    /**
+     * Returns a new TimeSpan that represents the sum of this instance and the specified TimeSpan.
+     *
+     * @param ts - The TimeSpan to add
+     * @returns A new TimeSpan representing the sum
+     * @throws {TimeSpanOverflowError} If the result exceeds safe integer bounds
+     *
+     * @example
+     * const span1 = TimeSpan.fromHours(2);
+     * const span2 = TimeSpan.fromHours(3);
+     * const span3 = span1.add(span2);
+     * console.log(span3.totalHours); // 5
+     */
     add(ts: TimeSpan): TimeSpan;
+    /**
+     * Returns a new TimeSpan that represents the difference between this instance and the specified TimeSpan.
+     *
+     * @param ts - The TimeSpan to subtract
+     * @returns A new TimeSpan representing the difference
+     * @throws {TimeSpanOverflowError} If the result exceeds safe integer bounds
+     *
+     * @example
+     * const span1 = TimeSpan.fromHours(5);
+     * const span2 = TimeSpan.fromHours(2);
+     * const span3 = span1.subtract(span2);
+     * console.log(span3.totalHours); // 3
+     */
     subtract(ts: TimeSpan): TimeSpan;
+    /**
+     * Creates a TimeSpan from a string representation.
+     *
+     * Supports two string formats:
+     * 1. "HH:mm:ss" - Hours, minutes, seconds (e.g., "5:30:45")
+     * 2. "d.HH:mm:ss.fff" - Days, hours, minutes, seconds, milliseconds (e.g., "5.02:30:45.500")
+     *
+     * @param value - The string representation of a TimeSpan
+     * @returns A new TimeSpan instance parsed from the string
+     * @throws {Error} If the string format is invalid or values cannot be parsed as integers
+     *
+     * @example
+     * // Parse hours:minutes:seconds
+     * const span1 = TimeSpan.fromString("5:30:45");
+     * console.log(span1.totalSeconds); // 19845
+     *
+     * @example
+     * // Parse days.hours:minutes:seconds.milliseconds
+     * const span2 = TimeSpan.fromString("5.02:30:45.500");
+     * console.log(span2.days); // 5
+     * console.log(span2.milliseconds); // 500
+     */
     static fromString(value: string): TimeSpan;
 }