import type { Nullable } from '../types/misc.js';
/**
 * The idea here is to wrap a promise (or promise getter) so it will never throw natively, but still be able to provide success/fail results:
 * - `onSuccess` for handling successful result: like `then` but to be called only if there was no error
 * - `onError` for handling error: like `catch` but with extended error format
 * - `expectError` adds a specific Error sub-class caster and adds it to the error data; useful when expecting some kind of specific error
 *
 * Important: all methods are chainable however will return the same PromiseExtended instance,
 * while native Promise methods return a new Promise instance on each `then`/`catch`/`finally` call.
 * Internally it just replaces the promise reference.
 *
 * Usage example:
 *
 * ```ts
 * function doWork() {
 *    return PromiseExtended
 *      .run(async () => {
 *          // return 42;
 *          throw new Error('Some error');
 *     });
 * }
 *
 * dowWork()
 *   // if no error, will return 42
 *   .onSuccess(data => console.log('Success:', data))
 *   // if error, will return { error: 'Some error', source: Error }
 *   .onError(({ error, source }) => console.error('Error Message:', error, '; original:', source))
 *   // this is possible to be called only if handlers throw
 *   .catch(err => console.error('Really unexpected error:', err));
 *
 * ```
 *
 * NOTE: regular `then`/`catch` will still work, but they will go after `catch` in the chain,
 * so basically every `then` will be called unless some previous handler throws,
 * and every `catch` will NOT be called unless there was an error in any previous handler.
 *
 * If passed promise resolve is `PromiseExtended` instance, current instance will redirect everything to it.
 *
 */
export declare class PromiseExtended<T, TCustomErrors extends Record<string, unknown> = Record<never, unknown>> implements Promise<T> {
    protected _error: PromiseExtended.ErrorData | null;
    private _promise;
    private readonly _errorProcessors;
    private constructor();
    static run<T, TErrors extends Record<string, unknown> = Record<never, unknown>>(worker: Promise<T> | (() => Promise<T>)): PromiseExtended<T, TErrors>;
    static succeeded<T>(data: T): PromiseExtended<T>;
    static errored<T, TErrors extends Record<string, unknown>>(source: Error | Error[] | string): PromiseExtended<T, TErrors>;
    onError(cb: Nullable<(data: PromiseExtended.ErrorData & TCustomErrors) => void>): this;
    onSuccess(cb: Nullable<(data: T) => void>): this;
    expectError<TName extends string, TError2 extends Error>(config: PromiseExtended.ErrorConfig<TName, TError2, TCustomErrors>): PromiseExtended<T, TCustomErrors & Record<TName, TError2>>;
    expectError<TName extends string, TError2 extends Error>(name: TName, ErrCtor: new (...args: any[]) => TError2, processor?: (value: TError2) => void | Partial<TCustomErrors & Record<TName, TError2>>): PromiseExtended<T, TCustomErrors & Record<TName, TError2>>;
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseExtended<TResult1 | TResult2, TCustomErrors>;
    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): PromiseExtended<T | TResult, TCustomErrors>;
    finally(onfinally?: (() => void) | null): this;
    toSuccessPromise(): Promise<boolean>;
    get [Symbol.toStringTag](): string;
    private getError;
    private _catch;
    /** Adds to the end of chain special marker that allow outer PromiseExtended to correctly process this instance with its own onSuccess/onError callbacks.
     *
     * See `example for combining` test case for more details.
     */
    pop(): PromiseExtended<T, TCustomErrors>;
    protected onErrorCaught(data: PromiseExtended.ErrorData): void;
}
export declare namespace PromiseExtended {
    type ErrorData = {
        error: string;
        source: Error;
    };
    type ErrorConfig<TName extends string, TError2 extends Error, TPrevErrors> = {
        name: TName;
        ErrCtor: new (...args: any[]) => TError2;
        processor?: (value: TError2) => void | Partial<TPrevErrors & Record<TName, TError2>>;
    };
    namespace ErrorConfig {
        function createExpecter<TName extends string, TError2 extends Error>(config: Omit<ErrorConfig<TName, TError2, unknown>, 'processor'>): <T, TPrevErrors extends Record<string, unknown>>(promise: PromiseExtended<T, TPrevErrors>, processor?: (error: TError2) => void | Partial<TPrevErrors & Record<TName, TError2>>) => PromiseExtended<T, TPrevErrors & Record<TName, TError2>>;
    }
}