ngx-lift 1.10.3 → 19.0.0

package/fesm2022/ngx-lift.mjs

@@ -1,29 +1,46 @@
 import { startWith, Subject, combineLatest, pipe, tap, map, catchError, of, Observable, expand, EMPTY, reduce, timer, isObservable, merge, exhaustMap, from, share, switchMap, fromEvent, throttleTime, identity, distinctUntilChanged, exhaustAll, concatAll, mergeAll, switchAll } from 'rxjs';
 import { toObservable, toSignal } from '@angular/core/rxjs-interop';
 import * as i0 from '@angular/core';
-import { Pipe, inject, LOCALE_ID, makeEnvironmentProviders, NgModule, Optional, Injectable, assertInInjectionContext, isSignal, untracked, computed, DestroyRef, signal, effect } from '@angular/core';
+import { Pipe, inject, LOCALE_ID, makeEnvironmentProviders, NgModule, Injectable, assertInInjectionContext, isSignal, untracked, computed, DestroyRef, signal, effect } from '@angular/core';
 import { Validators, FormArray } from '@angular/forms';
 import { ActivatedRoute } from '@angular/router';
 
 /**
  * Combines multiple observables into a single observable emitting an array or dictionary
  * of the latest values from each source observable.
- * Adds startWith(null) for each Subject in combineLatest when the second parameter startWithNullForAll is false.
- * When startWithNullForAll is true, each observable will startWith null.
+ *
+ * This operator is similar to RxJS `combineLatest`, but with additional behavior:
+ * - When `startWithNullForAll` is `false` (default), only `Subject` instances get `startWith(null)`
+ * - When `startWithNullForAll` is `true`, all observables get `startWith(null)`
+ *
+ * This ensures that `combineLatest` emits immediately with initial values, even if some
+ * observables haven't emitted yet.
  *
  * @template T - The type of the data in the observables.
  *
- * @param {Array<Observable<T>> | Record<string, Observable<T>>} sources -
- *   An array of observables or a dictionary of observables to be combined.
+ * @param sources - An array of observables or a dictionary (object) of observables to be combined.
+ * @param startWithNullForAll - When `true`, all observables will start with `null`.
+ *   When `false` (default), only `Subject` instances will start with `null`.
+ * @returns An observable emitting an array or dictionary of the latest values from each source observable.
+ *   Values may be `null` initially if `startWithNullForAll` is `true` or for `Subject` instances.
  *
- * @param {boolean} [startWithNullForAll=false] -
- *   Determines whether to start each observable with a `null` value.
+ * @throws {Error} Throws an error if the provided argument is not an array of observables or a dictionary of observables.
+ *
+ * @example
+ * ```typescript
+ * // Array of observables
+ * const combined$ = combineLatestEager([obs1$, obs2$, obs3$]);
  *
- * @returns {Observable<Array<T | null> | Record<string, T | null>>} -
- *   An observable emitting an array or dictionary of the latest values from each source observable.
+ * // Dictionary of observables
+ * const combined$ = combineLatestEager({
+ *   users: users$,
+ *   posts: posts$,
+ *   comments: comments$
+ * });
  *
- * @throws {Error} -
- *   Throws an error if the provided argument is not an array of observables or a dictionary of observables.
+ * // Start all with null
+ * const combined$ = combineLatestEager([obs1$, obs2$], true);
+ * ```
  */
 function combineLatestEager(sources, startWithNullForAll = false) {
     function observableMapper(observable) {
@@ -199,17 +216,35 @@ function distinctOnChange(onChangeCallback, comparator = (prev, curr) => prev ==
  * ******************************************************************
  */
 /**
- * Fetches paginated Kubernetes resources by continually making requests
- * until all pages have been retrieved, and aggregates the items from all pages
- * into a single KubernetesList.
- *
- * @template T The type of the items contained within the KubernetesList.
- * @param http The HttpClient instance used to make the HTTP requests.
- * @param endpoint The API endpoint to fetch the resources from.
- * @param initialParams Optional initial parameters to include in the request.
- *                      Can include query parameters like filters and pagination settings.
- * `limit` and `continue` parameters are parameters for kubernetes
- * @returns An observable that emits a single KubernetesList containing all items from all pages.
+ * Creates an RxJS operator that fetches paginated Kubernetes resources by continually making requests
+ * until all pages have been retrieved, and aggregates the items from all pages into a single KubernetesList.
+ *
+ * This operator uses Kubernetes' pagination mechanism with the `continue` token. It:
+ * - Starts with the initial request
+ * - Checks for a `continue` token in the response metadata
+ * - Makes subsequent requests with the `continue` token until no more pages exist
+ * - Aggregates all items from all pages into a single KubernetesList
+ *
+ * @template T - The type of Kubernetes objects in the list. Must extend `KubernetesObject`.
+ * @param http - The HttpClient instance used to make the HTTP requests.
+ * @param endpoint - The API endpoint to fetch the resources from.
+ * @param initialParams - Optional initial parameters to include in the request.
+ *   Can include query parameters like filters and pagination settings.
+ *   Note: `limit` and `continue` are Kubernetes-specific pagination parameters.
+ * @returns An RxJS operator function that transforms a source Observable into an Observable
+ *   that emits a single KubernetesList containing all aggregated items from all pages.
+ *
+ * @example
+ * ```typescript
+ * // Use as an operator
+ * this.http.get<KubernetesList<Pod>>('/api/v1/pods')
+ *   .pipe(
+ *     aggregatePaginatedKubernetesResources(this.http, '/api/v1/pods', { limit: 100 })
+ *   )
+ *   .subscribe(list => {
+ *     console.log(`Total pods: ${list.items.length}`);
+ *   });
+ * ```
  */
 function aggregatePaginatedKubernetesResources(http, endpoint, initialParams = {}) {
     return (source$) => {
@@ -231,16 +266,33 @@ function aggregatePaginatedKubernetesResources(http, endpoint, initialParams = {
     };
 }
 /**
- * Fetches paginated Kubernetes resources by continually making requests
- * until all pages have been retrieved.
- *
- * @template T The type of the items contained within the KubernetesList.
- * @param http The HttpClient instance used to make the HTTP requests.
- * @param endpoint The API endpoint to fetch the resources from.
- * @param initialParams Optional initial parameters to include in the request.
- *                      Can include query parameters like filters and pagination settings.
- * `limit` and `continue` parameters are parameters for kubernetes
- * @returns An observable that emits a single KubernetesList containing all items from all pages.
+ * Fetches paginated Kubernetes resources by continually making requests until all pages have been retrieved.
+ *
+ * This function is a convenience wrapper that combines the initial HTTP request with pagination handling.
+ * It automatically handles Kubernetes pagination using the `continue` token mechanism.
+ *
+ * Unlike `aggregatePaginatedKubernetesResources`, this function makes the initial request itself
+ * rather than being used as an operator on an existing Observable.
+ *
+ * @template T - The type of Kubernetes objects in the list. Must extend `KubernetesObject`.
+ * @param http - The HttpClient instance used to make the HTTP requests.
+ * @param endpoint - The API endpoint to fetch the resources from.
+ * @param initialParams - Optional initial parameters to include in the request.
+ *   Can include query parameters like filters and pagination settings.
+ *   Note: `limit` and `continue` are Kubernetes-specific pagination parameters.
+ * @returns An Observable that emits a single KubernetesList containing all aggregated items from all pages.
+ *
+ * @example
+ * ```typescript
+ * // Fetch all pods across all pages
+ * fetchPaginatedKubernetesResources<Pod>(
+ *   this.http,
+ *   '/api/v1/pods',
+ *   { limit: 100 }
+ * ).subscribe(list => {
+ *   console.log(`Total pods: ${list.items.length}`);
+ * });
+ * ```
  */
 function fetchPaginatedKubernetesResources(http, endpoint, initialParams = {}) {
     const initialRequest$ = http.get(endpoint, { params: initialParams });
@@ -270,17 +322,50 @@ const loggerFunctions = {
     table: console.table.bind(console),
 };
 /**
- * Logger operator for RxJS observables.
+ * RxJS operator that logs values emitted by an observable using various console methods.
+ * Useful for debugging and monitoring observable streams during development.
  *
- * @param loggerType The type of logger to be used: 'count', 'debug', 'dir', 'log', 'table'.
- *                   Defaults to 'log' if not provided or if an unknown type is specified.
+ * @template T - The type of values emitted by the observable.
+ * @param loggerType - The type of logger to be used. Options:
+ *   - `'log'`: Standard console.log (default)
+ *   - `'debug'`: Console.debug for debug messages
+ *   - `'dir'`: Console.dir for object inspection
+ *   - `'count'`: Console.count for counting emissions
+ *   - `'table'`: Console.table for tabular data display
  * @returns An RxJS operator function that logs values using the specified console function.
+ *
+ * @example
+ * ```typescript
+ * // Log all values
+ * source$.pipe(logger()).subscribe();
+ *
+ * // Use debug logger
+ * source$.pipe(logger('debug')).subscribe();
+ *
+ * // Display objects in table format
+ * users$.pipe(logger('table')).subscribe();
+ * ```
  */
 const logger = (loggerType = 'log') => pipe(tap((value) => {
     const logFunction = loggerFunctions[loggerType] || console.log.bind(console);
     logFunction(value);
 }));
 
+/**
+ * Type guard that checks if a value is a Promise.
+ *
+ * @param obj - The value to check.
+ * @returns `true` if the value is a Promise (has a `then` method), `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const promise = Promise.resolve(42);
+ * isPromise(promise); // true
+ *
+ * const notPromise = 42;
+ * isPromise(notPromise); // false
+ * ```
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function isPromise$1(obj) {
     return !!obj && typeof obj.then === 'function';
@@ -323,12 +408,28 @@ function poll(options) {
 }
 
 /**
- * Operator that taps into a callback before the source Observable starts emitting values.
+ * RxJS operator that executes a callback function before the source Observable starts emitting values.
+ * This operator is useful for triggering side effects (like logging, state updates, or initialization)
+ * before the main Observable begins emitting.
  *
- * This operator is useful for triggering a side effect before the main Observable starts emitting.
+ * @template T - The type of values emitted by the observable.
+ * @param callback - A function to be executed synchronously before the source Observable emits its first value.
+ * @returns An RxJS operator function that executes the callback and then returns the source Observable unchanged.
+ *
+ * @example
+ * ```typescript
+ * // Log before starting
+ * data$.pipe(
+ *   startWithTap(() => console.log('Starting data fetch...')),
+ *   switchMap(() => this.http.get('/api/data'))
+ * ).subscribe();
  *
- * @param callback A function to be executed before the source Observable emits its first value.
- * @returns An RxJS operator function that taps into the callback and then switchMaps to the source Observable.
+ * // Update loading state
+ * data$.pipe(
+ *   startWithTap(() => this.loading.set(true)),
+ *   finalize(() => this.loading.set(false))
+ * ).subscribe();
+ * ```
  */
 function startWithTap(callback) {
     return (source) => {
@@ -368,7 +469,28 @@ function switchMapWithAsyncState(project) {
     return (source) => source.pipe(switchMap((value, index) => project(value, index).pipe(createAsyncState())));
 }
 
+/**
+ * Angular pipe that joins array elements into a string using a specified separator.
+ *
+ * @example
+ * ```html
+ * <!-- Join array with default comma separator -->
+ * <div>{{ ['apple', 'banana', 'cherry'] | arrayJoin }}</div>
+ * <!-- Output: "apple,banana,cherry" -->
+ *
+ * <!-- Join array with custom separator -->
+ * <div>{{ ['apple', 'banana', 'cherry'] | arrayJoin: ' - ' }}</div>
+ * <!-- Output: "apple - banana - cherry" -->
+ * ```
+ */
 class ArrayJoinPipe {
+    /**
+     * Transforms an array into a string by joining its elements with a separator.
+     *
+     * @param value - The array to join. If not an array, returns the value as-is.
+     * @param separator - The separator string to use between array elements. Defaults to ','.
+     * @returns A string containing the joined array elements, or the original value if not an array
+     */
     transform(value, separator = ',') {
         if (Array.isArray(value)) {
             return value.join(separator);
@@ -376,50 +498,57 @@ class ArrayJoinPipe {
         // For non-array cases or unexpected types, return the value as is
         return value;
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: ArrayJoinPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe }); }
-    static { this.ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "18.2.13", ngImport: i0, type: ArrayJoinPipe, isStandalone: true, name: "arrayJoin" }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ArrayJoinPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: ArrayJoinPipe, isStandalone: true, name: "arrayJoin" });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: ArrayJoinPipe, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ArrayJoinPipe, decorators: [{
             type: Pipe,
             args: [{
                     name: 'arrayJoin',
-                    standalone: true,
                 }]
         }] });
 
 /**
+ * Angular pipe that converts a number of bytes into a human-readable string format
+ * (e.g., "1.5 MB", "2.3 GB") with locale-aware formatting.
+ *
+ * Supports multiple locales including English, French, Chinese, Japanese, and more.
+ * The pipe uses the application's LOCALE_ID to determine the appropriate unit translations.
+ *
+ * @example
+ * ```html
+ * <!-- Convert bytes to human-readable format -->
+ * <div>{{ 1024 | byteConverter }}</div>
+ * <!-- Output: "1 KB" (English) or "1 Ko" (French) -->
+ *
+ * <div>{{ 1048576 | byteConverter }}</div>
+ * <!-- Output: "1 MB" (English) or "1 Mo" (French) -->
+ * ```
+ *
+ * @example
+ * To use locale-specific formatting, configure LOCALE_ID in your app:
+ * ```typescript
  * import { LOCALE_ID, NgModule } from '@angular/core';
- * import { BrowserModule } from '@angular/platform-browser';
- * import { AppComponent } from './app.component';
  * import { registerLocaleData } from '@angular/common';
- *
  * import localeEn from '@angular/common/locales/en';
  * import localeFr from '@angular/common/locales/fr';
  *
- * // Register locales
  * registerLocaleData(localeEn);
  * registerLocaleData(localeFr);
  *
  * @NgModule({
- *   declarations: [AppComponent],
- *   imports: [BrowserModule],
  *   providers: [
  *     {
  *       provide: LOCALE_ID,
- *       useFactory: () => {
- *         // Use the browser's language or a default language
- *         return navigator.language || 'en';
- *       },
+ *       useFactory: () => navigator.language || 'en',
  *     },
  *   ],
- *   bootstrap: [AppComponent],
  * })
  * export class AppModule {}
+ * ```
  */
 class ByteConverterPipe {
-    constructor() {
-        this.locale = inject(LOCALE_ID);
-    }
+    locale = inject(LOCALE_ID);
     transform(value) {
         if (value === null || value === undefined || isNaN(value)) {
             return null;
@@ -435,16 +564,17 @@ class ByteConverterPipe {
         return this.formatNumber(value) + ' ' + translationObject[key];
     }
     formatNumber(value) {
-        return new Intl.NumberFormat(this.locale, { maximumFractionDigits: 2 }).format(value);
+        return new Intl.NumberFormat(this.locale, {
+            maximumFractionDigits: 2,
+        }).format(value);
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: ByteConverterPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe }); }
-    static { this.ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "18.2.13", ngImport: i0, type: ByteConverterPipe, isStandalone: true, name: "byteConverter" }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ByteConverterPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: ByteConverterPipe, isStandalone: true, name: "byteConverter" });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: ByteConverterPipe, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: ByteConverterPipe, decorators: [{
             type: Pipe,
             args: [{
                     name: 'byteConverter',
-                    standalone: true,
                 }]
         }] });
 const translations = {
@@ -614,8 +744,44 @@ function composeValidators(control, validatorFn) {
     return Validators.compose(validatorFns)?.(control) || null;
 }
 
+/**
+ * Configuration options for the idle detection service.
+ * Used to customize the idle duration and timeout duration for user inactivity detection.
+ */
 class IdleDetectionConfig {
+    /**
+     * The duration in seconds before the user is considered idle.
+     * After this duration, the idle detection phase ends and countdown begins.
+     * Defaults to 19 minutes (1140 seconds) if not provided.
+     */
+    idleDurationInSeconds;
+    /**
+     * The duration in seconds for the countdown phase after idle detection.
+     * During this phase, the user can still interact to reset the timer.
+     * After this duration, the timeout event is emitted.
+     * Defaults to 1 minute (60 seconds) if not provided.
+     */
+    timeoutDurationInSeconds;
 }
+/**
+ * Provides configuration for the idle detection service.
+ * This function should be used in the application's providers array to configure idle detection.
+ *
+ * @param config - The idle detection configuration object.
+ * @returns Environment providers for the idle detection configuration.
+ *
+ * @example
+ * ```typescript
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideIdleDetectionConfig({
+ *       idleDurationInSeconds: 15 * 60, // 15 minutes
+ *       timeoutDurationInSeconds: 60 // 1 minute
+ *     })
+ *   ]
+ * };
+ * ```
+ */
 function provideIdleDetectionConfig(config) {
     return makeEnvironmentProviders([{ provide: IdleDetectionConfig, useValue: config }]);
 }
@@ -631,69 +797,77 @@ class IdleDetectionModule {
             providers: [provideIdleDetectionConfig(config)],
         };
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
-    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionModule }); }
-    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionModule }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionModule });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionModule });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionModule, decorators: [{
             type: NgModule,
-            args: [{
-                    imports: [],
-                }]
+            args: [{}]
         }] });
 
 /**
  * Service for detecting user idle time and implementing a countdown.
  */
 class IdleDetectionService {
+    /**
+     * The list of interruption events that will end the idle detection.
+     */
+    interruptionEvents = [
+        'click',
+        'keydown',
+        'keypress',
+        'mousemove',
+        'mousedown',
+        'scroll',
+        'wheel',
+        'touchmove',
+        'pointermove',
+        'resize',
+    ];
+    interruptionSubscription;
+    /**
+     * The default idle duration in seconds (19 minutes).
+     */
+    idleDuration = 19 * 60;
+    /**
+     * The default timeout duration in seconds (1 minute).
+     */
+    timeoutDuration = 60;
+    /**
+     * Timer for idle detection.
+     */
+    idleTimer;
+    /**
+     * Timer for countdown.
+     */
+    countdownTimer;
+    /**
+     * Flag to indicate if countdown is in progress.
+     */
+    isCountingDown = false;
+    /**
+     * The current countdown value.
+     */
+    countdown = this.timeoutDuration;
+    /**
+     * Subject to emit when idle period ends.
+     */
+    idleEndSubject = new Subject();
+    /**
+     * Subject to emit the countdown value.
+     */
+    countdownSubject = new Subject();
+    /**
+     * Subject to emit when countdown ends.
+     */
+    countdownEndSubject = new Subject();
     /**
      * Constructs the IdleDetectionService.
      * @param config - Optional configuration for idle and timeout durations.
      */
-    constructor(config) {
-        /**
-         * The list of interruption events that will end the idle detection.
-         */
-        this.interruptionEvents = [
-            'click',
-            'keydown',
-            'keypress',
-            'mousemove',
-            'mousedown',
-            'scroll',
-            'wheel',
-            'touchmove',
-            'pointermove',
-            'resize',
-        ];
-        /**
-         * The default idle duration in seconds (19 minutes).
-         */
-        this.idleDuration = 19 * 60;
-        /**
-         * The default timeout duration in seconds (1 minute).
-         */
-        this.timeoutDuration = 60;
-        /**
-         * Flag to indicate if countdown is in progress.
-         */
-        this.isCountingDown = false;
-        /**
-         * The current countdown value.
-         */
-        this.countdown = this.timeoutDuration;
-        /**
-         * Subject to emit when idle period ends.
-         */
-        this.idleEndSubject = new Subject();
-        /**
-         * Subject to emit the countdown value.
-         */
-        this.countdownSubject = new Subject();
-        /**
-         * Subject to emit when countdown ends.
-         */
-        this.countdownEndSubject = new Subject();
+    constructor() {
+        const config = inject(IdleDetectionConfig, { optional: true });
         if (config) {
             this.setConfig(config);
         }
@@ -728,7 +902,7 @@ class IdleDetectionService {
     setupInterruptionEvents() {
         if (!this.interruptionSubscription) {
             const throttledInterruptionEvents = this.interruptionEvents.map((eventName) => fromEvent(document, eventName).pipe(throttleTime(1000)));
-            this.interruptionSubscription = merge(...throttledInterruptionEvents).subscribe(() => this.resetTimer());
+            this.interruptionSubscription = merge(...throttledInterruptionEvents).subscribe(() => this.resetTimer(true));
         }
     }
     /**
@@ -801,6 +975,8 @@ class IdleDetectionService {
     clearTimers() {
         clearTimeout(this.idleTimer);
         clearInterval(this.countdownTimer);
+        this.idleTimer = undefined;
+        this.countdownTimer = undefined;
         this.interruptionSubscription?.unsubscribe();
         this.interruptionSubscription = undefined;
     }
@@ -816,19 +992,33 @@ class IdleDetectionService {
             this.countdown = this.timeoutDuration = config.timeoutDurationInSeconds;
         }
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionService, deps: [{ token: IdleDetectionConfig, optional: true }], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionService, providedIn: 'root' }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionService, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IdleDetectionService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IdleDetectionService, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
                 }]
-        }], ctorParameters: () => [{ type: IdleDetectionConfig, decorators: [{
-                    type: Optional
-                }] }] });
+        }], ctorParameters: () => [] });
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Type guard that checks if a value is array-like (has a numeric length property).
+ * Array-like objects include arrays, strings, NodeLists, and similar structures.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is array-like, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * isArrayLike([1, 2, 3]); // true
+ * isArrayLike('string'); // true
+ * isArrayLike({length: 5}); // true
+ * isArrayLike(null); // false
+ * isArrayLike(() => {}); // false
+ * ```
+ */
 function isArrayLike(value) {
     return (value != null &&
         typeof value !== 'function' &&
@@ -836,6 +1026,20 @@ function isArrayLike(value) {
         value.length >= 0 &&
         value.length <= Number.MAX_SAFE_INTEGER);
 }
+/**
+ * Checks if a value is a prototype object.
+ * A prototype object is an object that is the prototype property of a constructor function.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value is a prototype object, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * isPrototype(Array.prototype); // true
+ * isPrototype(Object.prototype); // true
+ * isPrototype({}); // false
+ * ```
+ */
 function isPrototype(value) {
     const Ctor = value?.constructor;
     return Ctor && Ctor.prototype === value;
@@ -968,73 +1172,197 @@ function range(start, end, step, fromRight = false) {
     return result;
 }
 
-// https://regex101.com/library/mX1xW0
+/**
+ * Regular expression pattern for validating email addresses.
+ * Supports standard email formats including subdomains and various TLDs.
+ *
+ * @see {@link https://regex101.com/library/mX1xW0 | Regex Pattern Reference}
+ *
+ * @example
+ * ```typescript
+ * emailPattern.test('user@example.com'); // true
+ * emailPattern.test('invalid-email'); // false
+ * ```
+ */
 const emailPattern = /^([\w-]+(?:\.[\w-]+)*)@((?:[\w-]+\.)*\w[\w-]{0,66})\.([a-z]{2,6}(?:\.[a-z]{2})?)$/;
+/**
+ * Regular expression pattern for validating HTTP and HTTPS URLs.
+ * Supports URLs with or without www subdomain, various protocols, and query parameters.
+ *
+ * @example
+ * ```typescript
+ * urlPattern.test('https://example.com'); // true
+ * urlPattern.test('http://www.example.com/path?query=1'); // true
+ * urlPattern.test('invalid-url'); // false
+ * ```
+ */
 const urlPattern = /^https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b(?:[-a-zA-Z0-9()@:%_+.~#?&/=]*)$/;
+/**
+ * Regular expression pattern for validating HTTPS URLs only.
+ * Similar to `urlPattern` but requires the HTTPS protocol.
+ *
+ * @example
+ * ```typescript
+ * httpsPattern.test('https://example.com'); // true
+ * httpsPattern.test('http://example.com'); // false
+ * ```
+ */
 const httpsPattern = /^https:\/\/(?:www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b(?:[-a-zA-Z0-9()@:%_+.~#?&/=]*)$/;
-// https://regex101.com/library/dT0vT3?orderBy=RELEVANCE&search=ip
+/**
+ * Regular expression pattern for validating IPv4 addresses.
+ * Supports all valid IPv4 address ranges (0.0.0.0 to 255.255.255.255).
+ *
+ * @see {@link https://regex101.com/library/dT0vT3?orderBy=RELEVANCE&search=ip | Regex Pattern Reference}
+ *
+ * @example
+ * ```typescript
+ * ipRegex.test('192.168.1.1'); // true
+ * ipRegex.test('256.1.1.1'); // false
+ * ipRegex.test('not-an-ip'); // false
+ * ```
+ */
 const ipRegex = /^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
-// A fully qualified domain name (FQDN) is a domain name that specifies its exact location in the tree hierarchy of the Domain Name System (DNS)
-// https://www.regextester.com/103452
+/**
+ * Regular expression pattern for validating Fully Qualified Domain Names (FQDN).
+ * A FQDN is a domain name that specifies its exact location in the tree hierarchy of the Domain Name System (DNS).
+ * The pattern validates domain names between 4 and 253 characters with proper formatting.
+ *
+ * @see {@link https://www.regextester.com/103452 | Regex Pattern Reference}
+ *
+ * @example
+ * ```typescript
+ * fqdnRegex.test('example.com'); // true
+ * fqdnRegex.test('subdomain.example.com'); // true
+ * fqdnRegex.test('invalid..domain'); // false
+ * ```
+ */
 const fqdnRegex = /(?=^.{4,253}$)(^((?!-)[a-zA-Z0-9-]{0,62}[a-zA-Z0-9]\.)+[a-zA-Z]{2,63}$)/;
 
 /**
- * Check if hostname is IP
- * @param hostname new URL(your-url).hostname
- * @returns true if hostname is a IP
+ * Checks if a hostname is a valid IP address (IPv4 or IPv6).
+ *
+ * @param hostname - The hostname to check. Should be extracted from `new URL(url).hostname`
+ * @returns `true` if the hostname is a valid IP address, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const url = new URL('http://192.168.1.1');
+ * isIP(url.hostname); // true
+ *
+ * const url2 = new URL('http://example.com');
+ * isIP(url2.hostname); // false
+ * ```
  */
 function isIP(hostname) {
     return ipRegex.test(hostname);
 }
 /**
- * Check if hostname is FQDN
- * @param hostname new URL(your-url).hostname
- * @returns true if hostname is a FQDN
+ * Checks if a hostname is a valid Fully Qualified Domain Name (FQDN).
+ *
+ * @param hostname - The hostname to check. Should be extracted from `new URL(url).hostname`
+ * @returns `true` if the hostname is a valid FQDN, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const url = new URL('http://example.com');
+ * isFQDN(url.hostname); // true
+ *
+ * const url2 = new URL('http://192.168.1.1');
+ * isFQDN(url2.hostname); // false
+ * ```
  */
 function isFQDN(hostname) {
     return fqdnRegex.test(hostname);
 }
 /**
- * Check if url is valid
- * @param url
- * @returns true if valid
+ * Checks if a string is a valid URL.
+ *
+ * @param url - The URL string to validate
+ * @returns `true` if the string is a valid URL, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isURL('https://example.com'); // true
+ * isURL('not-a-url'); // false
+ * ```
  */
 function isURL(url) {
     return urlPattern.test(url);
 }
 /**
- * Check if a url starts with https, the url must be a valid url.
- * @param url
- * @returns true if it's a https valid url
+ * Checks if a URL string uses the HTTPS protocol.
+ * The URL must be a valid URL format.
+ *
+ * @param url - The URL string to check
+ * @returns `true` if the URL is valid and uses HTTPS protocol, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isHttps('https://example.com'); // true
+ * isHttps('http://example.com'); // false
+ * ```
  */
 function isHttps(url) {
     return httpsPattern.test(url);
 }
 
+/**
+ * Angular pipe that checks if a URL string uses the HTTPS protocol.
+ *
+ * @example
+ * ```html
+ * <!-- Check if URL is HTTPS -->
+ * <div>{{ 'https://example.com' | isHttps }}</div>
+ * <!-- Output: true -->
+ *
+ * <div>{{ 'http://example.com' | isHttps }}</div>
+ * <!-- Output: false -->
+ * ```
+ */
 class IsHttpsPipe {
+    /**
+     * Transforms a URL string into a boolean indicating whether it uses HTTPS.
+     *
+     * @param value - The URL string to check
+     * @returns `true` if the URL uses HTTPS protocol, `false` otherwise
+     */
     transform(value) {
         return isHttps(value);
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IsHttpsPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe }); }
-    static { this.ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "18.2.13", ngImport: i0, type: IsHttpsPipe, isStandalone: true, name: "isHttps" }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IsHttpsPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: IsHttpsPipe, isStandalone: true, name: "isHttps" });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: IsHttpsPipe, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: IsHttpsPipe, decorators: [{
             type: Pipe,
             args: [{
                     name: 'isHttps',
-                    standalone: true,
                 }]
         }] });
 
 const unmaskNumber = 6;
 const maskChar = '*';
+/**
+ * Angular pipe that masks sensitive string data by replacing characters with asterisks,
+ * while preserving a configurable number of characters at the beginning and end.
+ *
+ * @example
+ * ```html
+ * <!-- Mask a credit card number -->
+ * <div>{{ '1234567890123456' | mask }}</div>
+ * <!-- Output: "123456******3456" -->
+ *
+ * <!-- Custom masking options -->
+ * <div>{{ '1234567890123456' | mask: { unmaskedPrefixLength: 4, unmaskedSuffixLength: 4 } }}</div>
+ * <!-- Output: "1234********3456" -->
+ * ```
+ */
 class MaskPipe {
     /**
      * Transforms the input string by masking characters based on the provided options.
      *
-     * @param {string} value - The input string to be masked.
-     * @param {MaskOptions} [options={}] - Options for customizing the masking behavior.
-     * @returns {string} - The masked string.
+     * @param value - The input string to be masked
+     * @param options - Options for customizing the masking behavior
+     * @returns The masked string, or the original string if masking is disabled or the string is too short
      */
     transform(value, options = {}) {
         const { unmaskedPrefixLength = unmaskNumber, unmaskedSuffixLength = unmaskNumber, masked = true } = options;
@@ -1049,62 +1377,102 @@ class MaskPipe {
             .map((char, i) => (i < unmaskedPrefixLength || i > value.length - unmaskedSuffixLength - 1 ? char : maskChar))
             .join('');
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: MaskPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe }); }
-    static { this.ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "18.2.13", ngImport: i0, type: MaskPipe, isStandalone: true, name: "mask" }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: MaskPipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: MaskPipe, isStandalone: true, name: "mask" });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: MaskPipe, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: MaskPipe, decorators: [{
             type: Pipe,
             args: [{
                     name: 'mask',
-                    standalone: true,
                 }]
         }] });
 
+/**
+ * Angular pipe that generates an array of numbers within a specified range.
+ *
+ * @example
+ * ```html
+ * <!-- Generate array from 0 to 4 -->
+ * <div *ngFor="let i of [5] | range">{{ i }}</div>
+ *
+ * <!-- Generate array from 1 to 5 -->
+ * <div *ngFor="let i of [1, 5] | range">{{ i }}</div>
+ *
+ * <!-- Generate array from 0 to 10 with step 2 -->
+ * <div *ngFor="let i of [0, 10, 2] | range">{{ i }}</div>
+ * ```
+ */
 class RangePipe {
     transform(value) {
         const input = value;
         return range(...input);
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: RangePipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe }); }
-    static { this.ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "18.2.13", ngImport: i0, type: RangePipe, isStandalone: true, name: "range" }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: RangePipe, deps: [], target: i0.ɵɵFactoryTarget.Pipe });
+    static ɵpipe = i0.ɵɵngDeclarePipe({ minVersion: "14.0.0", version: "20.3.15", ngImport: i0, type: RangePipe, isStandalone: true, name: "range" });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.13", ngImport: i0, type: RangePipe, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: RangePipe, decorators: [{
             type: Pipe,
             args: [{
                     name: 'range',
-                    standalone: true,
                 }]
         }] });
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /**
- * Combines multiple `Observable` or `Signal` sources into a `Signal` that emits their values. It's like combineLatest.
+ * Combines multiple `Observable` or `Signal` sources into a `Signal` that emits their combined values.
+ * This function is similar to RxJS `combineLatest`, but works with both Observables and Signals,
+ * and returns a Signal instead of an Observable.
+ *
+ * The function supports:
+ * - Array of sources: Returns a Signal of an array
+ * - Object of sources: Returns a Signal of an object with the same keys
+ * - Optional RxJS operator: Apply transformations to the combined values
+ * - Optional initial value: Provide an initial value for the Signal
  *
- * @param {ObservableSignalInputTuple} sources - Array or object of `Observable` or `Signal` values
- * @param {OperatorFunction} [operator] - Operator to apply to the combined values
- * @param {CombineFromOptions} [options] - Options including `initialValue` and `injector`
- * @returns Signal emitting the combined values
+ * @template Input - The type of the input sources (array or object).
+ * @template Output - The type of the output Signal (defaults to Input).
+ *
+ * @param sources - Array or object of `Observable` or `Signal` values to combine.
+ * @param operator - Optional RxJS operator function to transform the combined values.
+ * @param options - Optional configuration object:
+ *   - `initialValue`: Initial value for the Signal (required if sources don't emit synchronously)
+ *   - `injector`: Angular injector to use for signal conversion
+ * @returns A Signal that emits the combined values from all sources.
  *
  * @example
- * ```ts
+ * ```typescript
+ * // Array of sources
  * export class Component {
- *  private readonly userService = inject(UserService);
- *  page = signal(2);
- *
- *  data = combineFrom(
- *    [this.page, this.userService.users$],
- *    pipe(
- *      switchMap(([page, users]) => this.dataService.getData(page, users)),
- *      startWith([])
- *    )
- *  );
+ *   private readonly userService = inject(UserService);
+ *   page = signal(2);
+ *
+ *   data = combineFrom(
+ *     [this.page, this.userService.users$],
+ *     pipe(
+ *       switchMap(([page, users]) => this.dataService.getData(page, users)),
+ *       startWith([])
+ *     )
+ *   );
  * }
+ *
+ * // Object of sources
+ * const vm = combineFrom({
+ *   users: users$,
+ *   filters: filtersSignal,
+ *   page: pageSignal
+ * });
+ *
+ * // With initial value
+ * const data = combineFrom(
+ *   [source1$, source2$],
+ *   { initialValue: [null, null] }
+ * );
  * ```
  */
 function combineFrom(...args) {
     assertInInjectionContext(combineFrom);
     const { normalizedSources, hasInitValue, operator, options } = normalizeArgs(args);
-    const ret = hasInitValue
+    const ret = hasInitValue && options?.initialValue !== undefined
         ? toSignal(combineLatest(normalizedSources).pipe(operator), {
             initialValue: options.initialValue,
             injector: options?.injector,
@@ -1139,20 +1507,24 @@ function normalizeArgs(args) {
             try {
                 initialValue = untracked(source);
             }
-            catch (e) {
+            catch {
                 // If the input is not set, skip startWith or provide a fallback
                 initialValue = undefined;
             }
             // toObservable doesn't immediately emit initialValue of the signal
-            acc[keyOrIndex] = toObservable(source, { injector: options?.injector }).pipe(startWith(initialValue));
+            acc[keyOrIndex] = toObservable(source, {
+                injector: options?.injector,
+            }).pipe(startWith(initialValue));
         }
         else if (isObservable(source)) {
             acc[keyOrIndex] = source.pipe(distinctUntilChanged());
         }
         else if (typeof source === 'function') {
             // seldom use: pass function like () => 5
-            const computedRes = computed(source);
-            acc[keyOrIndex] = toObservable(computedRes, { injector: options?.injector }).pipe(startWith(source()));
+            const computedRes = computed(source, ...(ngDevMode ? [{ debugName: "computedRes" }] : []));
+            acc[keyOrIndex] = toObservable(computedRes, {
+                injector: options?.injector,
+            }).pipe(startWith(source()));
         }
         else {
             // seldom use: pass promise, Map, array, etc that from accepts
@@ -1168,7 +1540,7 @@ function computedAsync(computeFn, options = {}) {
     const destroyRef = inject(DestroyRef);
     const sourceSubject = new Subject();
     const source$ = flattenObservable(sourceSubject, options.behavior || 'switch');
-    const sourceValue = signal(options.initialValue);
+    const sourceValue = signal(options.initialValue, ...(ngDevMode ? [{ debugName: "sourceValue" }] : []));
     const sourceResult = source$.subscribe({
         next: (value) => sourceValue.set(value),
         error: (error) => {
@@ -1224,12 +1596,43 @@ function isPromise(value) {
     return value && typeof value.then === 'function';
 }
 
+/**
+ * Creates a trigger signal that can be used to manually trigger updates or side effects.
+ * The trigger maintains an internal counter that increments each time `next()` is called.
+ *
+ * @returns An object containing:
+ *   - `next()`: A function to trigger an update (increments the internal counter)
+ *   - `value`: A readonly signal that emits the current counter value
+ *
+ * @example
+ * ```typescript
+ * export class MyComponent {
+ *   private refreshTrigger = createTrigger();
+ *
+ *   // Use the trigger to refresh data
+ *   refreshData() {
+ *     this.refreshTrigger.next();
+ *   }
+ *
+ *   // React to trigger changes
+ *   data$ = toObservable(this.refreshTrigger.value).pipe(
+ *     switchMap(() => this.dataService.getData())
+ *   );
+ * }
+ * ```
+ */
 function createTrigger() {
-    const sourceSignal = signal(0);
+    const sourceSignal = signal(0, ...(ngDevMode ? [{ debugName: "sourceSignal" }] : []));
     return {
+        /**
+         * Triggers an update by incrementing the internal counter.
+         */
         next: () => {
             sourceSignal.update((v) => v + 1);
         },
+        /**
+         * A readonly signal that emits the current counter value.
+         */
         value: sourceSignal.asReadonly(),
     };
 }
@@ -1316,26 +1719,46 @@ function injectQueryParams(keyOrParamsTransform, options = {}) {
 
 // No object inputs
 /**
- * merge multiple `Observable` or `Signal` sources into a `Signal` that emits the last value. It's like merge.
+ * Merges multiple `Observable` or `Signal` sources into a `Signal` that emits values from any source.
+ * This function is similar to RxJS `merge`, but works with both Observables and Signals,
+ * and returns a Signal instead of an Observable.
  *
- * @param {ObservableSignalInputTuple} sources - Array of `Observable` or `Signal` values
- * @param {OperatorFunction} [operator] - Operator to apply to the merge
- * @param {MergeFromOptions} [options] - Options including `initialValue` and `injector`
- * @returns Signal emitting the latest merge result
+ * When any source emits a value, the Signal will emit that value. This is useful for
+ * combining multiple event streams or reactive sources.
+ *
+ * @template Input - The type of values in the input sources array.
+ * @template Output - The type of the output Signal (defaults to Input[number]).
+ *
+ * @param sources - Array of `Observable` or `Signal` values to merge.
+ * @param operator - Optional RxJS operator function to transform the merged values.
+ * @param options - Optional configuration object:
+ *   - `initialValue`: Initial value for the Signal
+ *   - `injector`: Angular injector to use for signal conversion
+ * @returns A Signal that emits values from any of the merged sources.
  *
  * @example
- * ```ts
+ * ```typescript
  * export class Component {
  *   e$ = of(1).pipe(delay(1000));
  *   f = signal(2);
  *
+ *   // Merge with operator
  *   data = mergeFrom(
  *     [this.e$, this.f],
  *     pipe(
- *       switchMap((res) => of(`${res} is coming~`)),
+ *       map((res) => `${res} is coming~`),
  *       startWith(0),
  *     ),
  *   );
+ *
+ *   // Simple merge
+ *   merged = mergeFrom([source1$, source2$, sourceSignal]);
+ *
+ *   // With initial value
+ *   merged = mergeFrom(
+ *     [source1$, source2$],
+ *     { initialValue: null }
+ *   );
  * }
  * ```
  */
@@ -1383,10 +1806,45 @@ function parseArgs(args) {
 }
 
 /**
- * Validates a date against a specified date range.
+ * Creates a validator function that validates a date against a specified date range.
+ *
+ * The validator checks if the form control's date value falls within the specified range.
+ * It supports:
+ * - Minimum and maximum date constraints
+ * - Inclusive or exclusive boundary comparisons
+ * - Time-aware or date-only comparisons
+ *
+ * @param options - The options for the date range validation.
+ * @returns A validator function that validates a FormControl and returns an error object if the date is out of range,
+ *   or `null` if the date is valid. Error objects contain:
+ *   - `minDate`: ISO string of the minimum date (if value is too early)
+ *   - `maxDate`: ISO string of the maximum date (if value is too late)
+ *   - `invalidDate`: `true` (if the value cannot be parsed as a date)
  *
- * @param {DateRangeOptions} options - The options for the date range validation.
- * @returns {ValidatorFn} A function that validates a FormControl and returns an error if the date is out of range.
+ * @example
+ * ```typescript
+ * // Date range with inclusive boundaries
+ * const form = new FormGroup({
+ *   startDate: new FormControl('', [
+ *     dateRangeValidator({
+ *       minDate: new Date('2024-01-01'),
+ *       maxDate: new Date('2024-12-31'),
+ *       minInclusive: true,
+ *       maxInclusive: true
+ *     })
+ *   ])
+ * });
+ *
+ * // Date-only comparison (ignores time)
+ * const form = new FormGroup({
+ *   appointment: new FormControl('', [
+ *     dateRangeValidator({
+ *       minDate: '2024-01-01',
+ *       compareTime: false
+ *     })
+ *   ])
+ * });
+ * ```
  */
 function dateRangeValidator(options) {
     return (control) => {
@@ -1440,11 +1898,30 @@ function dateRangeValidator(options) {
 }
 
 /**
- * A custom validator function that checks for intersection between two form controls. The two controls' values must be arrays.
+ * Creates a validator function that checks for intersection between two form controls within a FormGroup.
+ * Both controls' values must be arrays. The validator sets an error on both controls if they have any common values.
+ *
+ * This is useful for scenarios where you need to ensure two arrays don't share any elements,
+ * such as preventing duplicate selections in multi-select scenarios.
+ *
+ * @template T - The type of elements in the arrays (defaults to `string`).
+ * @param controlName1 - The name of the first form control in the FormGroup.
+ * @param controlName2 - The name of the second form control in the FormGroup.
+ * @returns A validator function that validates the FormGroup and returns an error object with `intersection: true`
+ *   if there is an intersection between the two arrays, or `null` if there is no intersection.
+ *
+ * @example
+ * ```typescript
+ * const form = new FormGroup({
+ *   selectedUsers: new FormControl(['user1', 'user2']),
+ *   excludedUsers: new FormControl(['user3', 'user4']),
+ * }, {
+ *   validators: [intersectionValidator('selectedUsers', 'excludedUsers')]
+ * });
  *
- * @param {string} controlName1 - The name of the first form control.
- * @param {string} controlName2 - The name of the second form control.
- * @returns {ValidatorFn} A function that validates the form group and returns an error if there is an intersection.
+ * // If selectedUsers contains 'user1' and excludedUsers also contains 'user1',
+ * // both controls will have an error: { intersection: true }
+ * ```
  */
 function intersectionValidator(controlName1, controlName2) {
     return (formGroup) => {
@@ -1478,15 +1955,47 @@ function intersectionValidator(controlName1, controlName2) {
  *
  * This validator can be applied to a FormArray or FormGroup containing the controls to be validated.
  * It ensures that each control's value is unique among all other controls within the array or group.
+ *
+ * When duplicate values are found, the validator sets a `notUnique` error on all affected controls.
+ * The error is automatically removed when the value becomes unique again.
+ *
+ * @example
+ * ```typescript
+ * // FormArray with unique values
+ * const formArray = new FormArray([
+ *   new FormControl('value1'),
+ *   new FormControl('value2'),
+ *   new FormControl('value1') // This will have notUnique error
+ * ], [UniqueValidator.unique()]);
+ *
+ * // FormArray with custom key selector
+ * const formArray = new FormArray([
+ *   new FormGroup({
+ *     id: new FormControl(1),
+ *     name: new FormControl('Item 1')
+ *   }),
+ *   new FormGroup({
+ *     id: new FormControl(2),
+ *     name: new FormControl('Item 2')
+ *   })
+ * ], [UniqueValidator.unique(control => control.get('id'))]);
+ * ```
  */
 class UniqueValidator {
     /**
-     * Validator function to be attached to a FormArray or FormGroup.
+     * Creates a validator function that checks for uniqueness of values across controls in a FormArray or FormGroup.
      *
-     * This validator checks for uniqueness of each control's value within the array or group.
+     * The validator:
+     * - Compares values using the provided key selector function
+     * - Sets `notUnique` error on controls with duplicate values
+     * - Automatically removes errors when values become unique
+     * - Ignores null, undefined, empty strings, and 'NaN' values
      *
-     * @param keySelector A function to select the key control for comparison (default is the control itself).
-     * @typeparam T The type of the control value.
+     * @template T - The type of the control value.
+     * @param keySelector - A function to select the key control for comparison.
+     *   Defaults to the control itself if not provided.
+     *   This is useful when validating FormGroups where you want to check uniqueness of a specific field.
+     * @returns A validator function that can be attached to a FormArray or FormGroup.
      */
     static unique(keySelector = (control) => control) {
         return (formArray) => {
@@ -1536,14 +2045,40 @@ class UniqueValidator {
     }
 }
 
+/**
+ * Validator function that checks if a form control value is a valid URL.
+ *
+ * @param control - The form control to validate
+ * @returns `null` if the value is a valid URL, or an error object with `invalidUrl: true` if invalid
+ *
+ * @example
+ * ```typescript
+ * const form = new FormGroup({
+ *   website: new FormControl('', urlValidator)
+ * });
+ * ```
+ */
 function urlValidator(control) {
-    if (!urlPattern.test(control.value)) {
+    if (!control.value || !urlPattern.test(control.value)) {
         return { invalidUrl: true };
     }
     return null;
 }
+/**
+ * Validator function that checks if a form control value is a valid HTTPS URL.
+ *
+ * @param control - The form control to validate
+ * @returns `null` if the value is a valid HTTPS URL, or an error object with `invalidUrl: true` if invalid
+ *
+ * @example
+ * ```typescript
+ * const form = new FormGroup({
+ *   secureUrl: new FormControl('', httpsValidator)
+ * });
+ * ```
+ */
 function httpsValidator(control) {
-    if (!httpsPattern.test(control.value)) {
+    if (!control.value || !httpsPattern.test(control.value)) {
         return { invalidUrl: true };
     }
     return null;