@itwin/ecschema-metadata/lib/esm/DelayedPromise.d.ts

ECObjects core concepts in typescript

/** @packageDocumentation
 * @module Utils
 */
/**
 * Similar to a normal Promise, a DelayedPromise represents the eventual completion (or failure)
 * and resulting value of an asynchronous operation ***that has not yet started***.
 *
 * The asynchronous operation behind a DelayedPromise will start when any of the following occurs:
 *  - The DelayedPromise is `await`ed.
 *  - A callback is attached via `.then()` or `.catch(() => { })`.
 *  - The asynchronous operation is explicitly started via `.start()`
 *
 * Just as normal Promises will never return to their pending state once fulfilled or rejected,
 * a DelayedPromise will never re-execute its asynchronous operation more than **once**.
 *
 * Ultimately, a DelayedPromise is nothing more than some syntactic sugar that allows you to
 * represent an (asynchronously) lazily-loaded value as an instance property instead of a method.
 * You could also accomplish something similar by defining an async function as a property getter.
 * However, since a property defined as a DelayedPromise will not start simply by being accessed,
 * additional (non-lazily-loaded) "nested" properties can be added.
 *
 * [!alert text="*Remember:* Unlike regular Promises in JavaScript, DelayedPromises represent processes that **may not** already be happening." kind="warning"]
 * @internal
 */
export declare class DelayedPromise<T> implements Promise<T> {
    /**
     * Constructs a DelayedPromise object.
     * @param startCallback The asynchronous callback to execute when this DelayedPromise should be "started".
     */
    constructor(startCallback: () => Promise<T>);
    readonly [Symbol.toStringTag]: "Promise";
    /**
     * Explicitly starts the asynchronous operation behind this DelayedPromise (if it hasn't started already).
     */
    start: () => Promise<T>;
    /**
     * Attaches callbacks for the resolution and/or rejection of the Promise.
     * @param onfulfilled The callback to execute when the Promise is resolved.
     * @param onrejected The callback to execute when the Promise is rejected.
     * @return A Promise for the completion of which ever callback is executed.
     */
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
    /**
     * Attaches a callback for only the rejection of the Promise.
     * @param onrejected The callback to execute when the Promise is rejected.
     * @return A Promise for the completion of the callback.
     */
    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
    /**
     * Attaches a callback for only the finally clause of the Promise.
     * @param onrejected The callback to execute when the Promise is finalized.
     * @return A Promise for the completion of the callback.
     */
    finally(onFinally?: (() => void) | undefined | null): Promise<T>;
}
/**
 * @internal
 */
export interface NoDelayedPromiseMethods {
    [propName: string]: any;
    start?: never;
    then?: never;
    catch?: never;
}
/**
 * @internal
 */
export interface DelayedPromiseWithPropsConstructor {
    /**
     * Constructs a DelayedPromiseWithProps object, which is at once both:
     *  - A DelayedPromise object representing the eventual completion (or failure)
     *    of an asynchronous operation returning a value of type `TPayload`
     *  - _and_ a readonly "wrapper" around an instance of type `TProps`
     *
     * @param props An object with properties and methods that will be accessible
     *              as if they were readonly properties of the DelayedPromiseWithProps object being constructed.
     * @param startCallback The asynchronous callback to execute when as soon as this DelayedPromise should be "started".
     */
    new <TProps extends NoDelayedPromiseMethods, TPayload>(props: TProps, startCallback: () => Promise<TPayload>): TProps & DelayedPromise<TPayload>;
}
/**
 * @internal
 */
export declare const DelayedPromiseWithProps: DelayedPromiseWithPropsConstructor;
/**
 * Define the type of a DelayedPromiseWithProps instance
 * @internal
 */
export type DelayedPromiseWithProps<TProps, TPayload> = TProps & DelayedPromise<TPayload>;
//# sourceMappingURL=DelayedPromise.d.ts.map