ng-lock/index.d.ts

Angular decorator for lock a function and user interface while a task running.

import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpContextToken, HttpContext } from '@angular/common/http';
import { Observable, MonoTypeOperatorFunction, Subscriber } from 'rxjs';
import * as i0 from '@angular/core';
import { OnInit, ElementRef, DestroyRef, Signal, EnvironmentProviders } from '@angular/core';

type NgLockElementFunction = (...args: any[]) => NgLockElementFinder;
type NgLockElementFinder = (self: any, args: any[]) => Element;
type NgLockFunction = (...args: any[]) => any;
declare const NG_UNLOCK_CALLBACK = "ngUnlockCallback";
declare const NG_IS_LOCK_CALLBACK = "ngIsLockCallback";
declare const NG_LOCK_SIGNAL = "ngLockSignal";
declare const NG_LOCK_SUBJECT = "ngLockSubject";
declare const NG_LOCK_OPTION = "ngLockOption";
type NG_CALLBACKS = typeof NG_UNLOCK_CALLBACK | typeof NG_IS_LOCK_CALLBACK | typeof NG_LOCK_SIGNAL | typeof NG_LOCK_SUBJECT | typeof NG_LOCK_OPTION;
declare const NG_LOCK_LOCKED_CLASS = "ng-lock-locked";
/**
 * All ngLock options
 * @see NgLockOption
 */
interface NgLockAllOption {
    maxCall: number;
    unlockTimeout: number | null;
    lockElementFunction: NgLockElementFinder;
    lockClass: string;
    returnLastResultWhenLocked: boolean;
    unlockOnPromiseResolve: boolean;
    unlockOnObservableChanges: boolean;
    debug: boolean;
}
/**
 * ngLock options
 *  - maxCall: Max number of the calls beyond which the method is locked
 *  - unlockTimeout: Max time (in millisecond) to lock function
 *  - lockElementFunction: function for find the HTMLElement for apply the lockClass
 *  - lockClass: CSS class applied when the method is locked
 *  - returnLastResultWhenLocked: if true, when the method is locked the last result is returned, otherwise return undefined
 *  - unlockOnPromiseResolve: if true, when a locked method return a Promise, the method is automatically unlock when the Promise is resolved
 *  - unlockOnObservableChanges: if true, when a locked method return a subscription, the method is automatically unlock when the observable changes
 *  - debug: if true, the decorator log into the console some info
 * @see NgLockDefaultOption for the default value
 */
type NgLockOption = Partial<NgLockAllOption>;

/**
 * ngLock default options
 * @see NgLockOption
 */
declare const NgLockDefaultOption: NgLockAllOption;
/**
 * Lock the decorated function
 * @param {NgLockOption} options (optional) NgLockOption
 * @return {MethodDecorator} Return a MethodDecorator
 */
declare function ngLock(options?: NgLockOption): MethodDecorator;

declare class NgLockInterceptorService implements HttpInterceptor {
    intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgLockInterceptorService, never>;
    static ɵprov: i0.ɵɵInjectableDeclaration<NgLockInterceptorService>;
}

/**
 * Unlock the given method on HTTP response
 */
declare const NG_LOCK_CONTEXT: HttpContextToken<NgLockFunction>;
/**
 * Return HttpContextToken for unlock the given method on HTTP response
 * @param {NgLockFunction} methodToUnlock the method to unlock
 * @param {HttpContext} context current context
 * @returns {HttpContext}
 */
declare const withNgLockContext: (methodToUnlock: NgLockFunction, context?: HttpContext) => HttpContext;

/**
 * @ngModule NgLockModule
 *
 * @description
 *
 * The `ngLock` directive it's a Angular directive lock html element when a decorated method with `@ngLock` is running a task.
 *
 * @usageNotes
 *
 * ### Usage
 *
 * ```html
 * <input [ngLock]="myMethod" /><button (click)="myMethod($event)">Send</button>
 * ```
 * ```ts
 * @ngLock()
 * myMethod(event: MouseEvent){
 *  return new Promise(resolve => setTimeout(resolve, 5000));
 * }
 * ```
 */
declare class NgLockDirective implements OnInit {
    private eleRef;
    private destroyRef;
    /**
     * @ngModule NgLockModule
     *
     * @description
     *
     * The `ngLock` directive it's a Angular directive lock html element when a decorated method with `@ngLock` is running a task.
     *
     * @usageNotes
     *
     * ### Usage
     *
     * ```html
     * <input [ngLock]="myMethod" /><button (click)="myMethod($event)">Send</button>
     * ```
     * ```ts
     * @ngLock()
     * myMethod(event: MouseEvent){
     *  return new Promise(resolve => setTimeout(resolve, 5000));
     * }
     * ```
     */
    ngLock: NgLockFunction;
    constructor(eleRef: ElementRef<HTMLElement>, destroyRef: DestroyRef);
    ngOnInit(): void;
    static ɵfac: i0.ɵɵFactoryDeclaration<NgLockDirective, never>;
    static ɵdir: i0.ɵɵDirectiveDeclaration<NgLockDirective, "[ngLock]", never, { "ngLock": { "alias": "ngLock"; "required": true; }; }, {}, never, never, true, never>;
}

declare class NgLockModule {
    static ɵfac: i0.ɵɵFactoryDeclaration<NgLockModule, never>;
    static ɵmod: i0.ɵɵNgModuleDeclaration<NgLockModule, never, [typeof NgLockDirective], [typeof NgLockDirective]>;
    static ɵinj: i0.ɵɵInjectorDeclaration<NgLockModule>;
}

/**
 * Unlock the method when Observable changes
 * @param {NgLockFunction} methodToUnlock method to unlock
 * @returns {MonoTypeOperatorFunction<T>}
 */
declare const ngLockChanges: <T>(methodToUnlock: NgLockFunction) => MonoTypeOperatorFunction<T>;

/**
 * Unlock a locked function by ngLock() decorator
 * @param {NgLockFunction} methodToUnlock The function to unlock
 * @param {string} reason The reason for the log
 * @return {void}
 * @throws Error
 */
declare function ngUnlock(methodToUnlock: NgLockFunction, reason?: string): void;
/**
 * Unlock all locked functions by ngLock() decorator
 * @param {any} component The component instance (this)
 * @return {void}
 */
declare function ngUnlockAll(component: any): void;
/**
 * Return true if the provided function is locked
 * @param {NgLockFunction} methodToCheck The method to check
 * @return {boolean}
 * @throws Error
 */
declare function ngIsLock(methodToCheck: NgLockFunction): boolean;
/**
 * Return a Signal for the given function on the lock status (locked/unlocked)
 * @param {NgLockFunction} method The function
 * @return {Signal<boolean>}
 */
declare function ngLockSignal(method: NgLockFunction): Signal<boolean>;
/**
 * Return the option for the given function
 * @param {NgLockFunction} method The function
 * @return {NgLockAllOption}
 */
declare function ngLockOption(method: NgLockFunction): NgLockAllOption;
/**
 * Return an Observable for the given function on the lock status (locked/unlocked)
 * @param {NgLockFunction} method - The function
 * @return {Observable<boolean>}
 */
declare function ngLockObservable(method: NgLockFunction): Observable<boolean>;
/**
 * Return the provided NG_CALLBACKS
 * @param {NgLockFunction} method The function to return the unlock callback
 * @param {NG_CALLBACKS} callback The NG_CALLBACKS
 * @return {NgLockFunction} Return the NG_CALLBACKS
 * @throws Error
 */
declare function ngCallbacks(method: NgLockFunction, callback: NG_CALLBACKS): NgLockFunction;
/**
 * Add class and attribute on HTML element
 * @param {Element} elementToLock
 * @param {NgLockOption} options
 */
declare const ngLockHtmlElement: (elementToLock: Element | null, options: NgLockOption) => void;
/**
 * Remove class and attribute from HTML element
 * @param {Element} elementToLock
 * @param {NgLockOption} options
 */
declare const ngUnLockHtmlElement: (elementToLock: Element | null, options: NgLockOption) => void;
/**
 * Check if value is a Promise
 */
declare const isPromise: (value: any) => value is Promise<unknown>;
/**
 * Check if value is a destination partialObserver
 */
declare const isObserver: (value: any) => value is {
    destination: {
        partialObserver: Subscriber<unknown>;
    };
};

/**
 * Uses the provided "selector" to find with "querySelector()" and apply the lockClass on the founded element.
 * @param {string} selector A DOMString containing a selector to match.
 * @returns {NgLockElementFinder} Return a NgLockElementFinder function
 * @throws Error
 */
declare const ngLockElementByQuerySelector: NgLockElementFunction;
/**
 * Uses a function argument for apply the lockClass. If provided a argsIndex use the specific argument, otherwise
 * search an argument with a target property that is a HTMLElement
 * @param {number} argsIndex (optional) index of the argument that is HTMLElement or contains target property (also a HTMLElement)
 * @returns {NgLockElementFinder} Return a NgLockElementFinder function
 * @throws Error
 */
declare const ngLockElementByTargetEventArgument: NgLockElementFunction;
/**
 * Apply lockClass to a component property that must be a HTMLElement or element with Angular nativeElement (also a HTMLElement)
 * @param {string} property The property name of the component
 * @returns {NgLockElementFinder} Return a NgLockElementFinder function
 * @throws Error
 */
declare const ngLockElementByComponentProperty: NgLockElementFunction;

declare function provideNgLock(): EnvironmentProviders[];

export { NG_IS_LOCK_CALLBACK, NG_LOCK_CONTEXT, NG_LOCK_LOCKED_CLASS, NG_LOCK_OPTION, NG_LOCK_SIGNAL, NG_LOCK_SUBJECT, NG_UNLOCK_CALLBACK, NgLockDefaultOption, NgLockDirective, NgLockInterceptorService, NgLockModule, isObserver, isPromise, ngCallbacks, ngIsLock, ngLock, ngLockChanges, ngLockElementByComponentProperty, ngLockElementByQuerySelector, ngLockElementByTargetEventArgument, ngLockHtmlElement, ngLockObservable, ngLockOption, ngLockSignal, ngUnLockHtmlElement, ngUnlock, ngUnlockAll, provideNgLock, withNgLockContext };
export type { NG_CALLBACKS, NgLockAllOption, NgLockElementFinder, NgLockElementFunction, NgLockFunction, NgLockOption };