/// <reference types="node" />
import { EventEmitter } from "events";
import { Stream } from "stream";
/**
 * An error that can be thrown by {@link failOnTimeout}.
 */
export declare class TimeoutError extends Error {
    constructor(message?: string);
}
/**
 * An error that can be thrown by {@link failOnResolve}.
 */
export declare class UnexpectedResolveError extends Error {
    constructor(message?: string);
}
/**
 * Causes a rejection if the given promise resolves before the timeout elapses.
 * <p>
 * If the original promise resolves within the timeout, the new promise rejects with an
 * {@link UnexpectedResolveError}. If the original promise rejects within the timeout, the new promise
 * rejects with the same result. Otherwise, the new promise resolves with no value.
 *
 * @param promise any promise
 * @param timeoutMilliseconds how long to wait
 * @param failureMessage optional message that will be included in the UnexpectedResolveError
 * @returns a promise that resolves only if the original promise neither resolved nor rejected
 */
export declare function failOnResolve<T>(promise: Promise<T>, timeoutMilliseconds: number, failureMessage?: string): Promise<void>;
/**
 * Causes a rejection if the timeout elapses before the given promise resolves.
 * <p>
 * If the original promise resolves or rejects within the timeout, the new promise resolves or rejects with the
 * same result. If the timeout elapses first, the new promise rejects with a {@link TimeoutError}.
 * <p>
 * Test frameworks such as Jest also allow you to set an overall timeout for a test. The difference between
 * doing that and using failOnTimeout is that failOnTimeout allows you to be more specific about which step
 * in the test has the timing requirement, and also allows you to customize the failure message to provide better
 * clues to what failed (since the stacktrace may not be useful in async code).
 *
 * @param promise any promise
 * @param timeoutMilliseconds how long to wait
 * @param failureMessage optional message that will be included in the TimeoutError
 * @returns a promise that behaves the same as the original promise unless a timeout occurs
 */
export declare function failOnTimeout<T>(promise: Promise<T>, timeoutMilliseconds: number, failureMessage?: string): Promise<T>;
/**
 * Converts a function whose last parameter is a Node-style callback `(err, result)` into a function
 * with one fewer argument that returns a Promise.
 *
 * This is equivalent to `util.promisify`, but since Node 6 does not provide `promisify`, it is
 * reimplemented here for projects that need to support Node 6. Note that it currently does not
 * type-check the arguments.
 *
 * ```
 *     function someFunction(param1, param2, callback) { callback(err, result); }
 *     var result = await promisify(someFunction)(param1, param2);
 * ```
 *
 * @param functionWithErrorAndValueCallback
 *   An asynchronously implemented function whose last parameter is an error-and-value callback.
 * @returns
 *   An equivalent function that returns a Promise. The Promise will be resolved if the original
 *   function calls its callback with no error `(null, returnValue)`, or rejected if it was called
 *   with an error (or if the original function threw an exception).
 */
export declare function promisify(functionWithErrorAndValueCallback: (...args: any[]) => void): (...args: any[]) => Promise<any>;
/**
 * Similar to [[promisify]], but for functions whose callback takes only a single parameter `(result)`
 * instead of the typical Node style `(err, result)`.
 *
 * ```
 *     function someFunction(param1, param2, callback) { callback(result); }
 *     var result = await promisify(someFunction)(param1, param2);
 * ```
 *
 * @param functionWithSingleValueCallback
 *   An asynchronously implemented function whose last parameter is a single-value callback.
 * @returns
 *   An equivalent function that returns a Promise. The Promise will be resolved if the original
 *   function calls its callback with a value, or rejected if the original function threw an exception.
 */
export declare function promisifySingle(functionWithSingleValueCallback: (...args: any[]) => void): (...args: any[]) => Promise<any>;
/**
 * Creates an [[AsyncQueue]] that will receive events. The value of each queue item is the value
 * associated with the event, or an array if there were multiple values.
 *
 * ```
 *     const receivedErrors = eventSink(client, "error");
 *     const firstError = await receivedErrors.take();
 *     const secondError = await receivedErrors.take();
 * ```
 *
 * @param emitter
 *   An event emitter.
 * @param name
 *   The event name.
 * @returns
 *   A Promise that is resolved the first time the event is raised. It will contain the value that
 *   was provided with the event, if any-- or, if there were multiple values, an array of them.
 */
export declare function eventSink(emitter: EventEmitter, name: string): AsyncQueue<any>;
/**
 * Helper class for creating a Promise that is paired with a single-value callback.
 *
 * ```
 *     const pvc = new PromiseAndValueCallback<string>();
 *     pvc.callback("a");
 *     const result = await pvc.promise; // returns "a"
 * ```
 */
export declare class PromiseAndValueCallback<T> {
    /**
     * A Promise that will be resolved when `callback` is called.
     */
    promise: Promise<T>;
    /**
     * A callback function taking a single value; when it is called, `promise` is resolved with that value.
     */
    callback: (value: T) => void;
    constructor();
}
/**
 * Helper class for creating a Promise that is paired with an error-and-value callback.
 *
 * ```
 *     const pvc1 = new PromiseAndErrorValueCallback<string>();
 *     pvc1.callback(null, "a");
 *     const result = await pvc1.promise; // returns "a"
 *
 *     const pvc2 = new PromiseAndErrorValueCallback<string>();
 *     pvc2.callback(new Error("sorry"));
 *     await pvc2.promise; // throws error
 * ```
 */
export declare class PromiseAndErrorValueCallback<T> {
    /**
     * A Promise that will be resolved when `callback` is called without an error, or rejected if `callback` is
     * called with an error.
     */
    promise: Promise<T>;
    /**
     * A callback function that takes an error value and/or a result value; when it is called, `promise` is
     * resolved or rejected.
     */
    callback: (err: any, value: T) => void;
    constructor();
}
/**
 * Fully reads a stream.
 *
 * @param stream
 *   The stream to read.
 * @returns
 *   A Promise that is resolved with the full content.
 */
export declare function readAllStream(stream: Stream): Promise<string>;
/**
 * Returns a Promise based on `setTimeout()`.
 *
 * ```
 *     await sleepAsync(5000);
 * ```
 *
 * @param milliseconds
 *   The length of the delay.
 * @returns
 *   A Promise that is resolved after the delay. It is never rejected.
 */
export declare function sleepAsync(milliseconds: number): Promise<void>;
/**
 * Interface for any object that has a `close()` method. Used by [[withCloseable]].
 */
export interface Closeable {
    /**
     * Releases any resources held by the object when it will no longer be used.
     */
    close: () => void;
}
/**
 * Ensures that an object"s close() method is called after executing a callback, even if an error occurs.
 *
 * ```
 *     await withCloseable(myExistingObject, async o => doSomething(o));
 *     await withCloseable(() => makeNewObject(), async o => doSomething(o));
 *     await withCloseable(async () => await makeObjectAsync(), async o => doSomething(o));
 * ```
 *
 * @param entityOrCreateFn
 *   Either the object itself, or a function (sync or async) that will create it. If this is null or
 *   undefined, you will receive a rejected Promise.
 * @param asyncCallback
 *   An async function to execute with the object as a parameter.
 * @returns
 *   A Promise that resolves with the return value of the callback.
 */
export declare function withCloseable<T extends Closeable, U>(entityOrCreateFn: T | (() => T) | (() => Promise<T>), asyncCallback: (entity: T) => Promise<U>): Promise<U>;
/**
 * A Promise-based blocking queue.
 */
export declare class AsyncQueue<T> {
    private static closedError;
    private items;
    private awaiters;
    private closed;
    constructor();
    /**
     * Adds an item at the end of a queue. If the queue was empty and there are any pending requests from
     * `take()`, the first one receives the item. If the queue has been closed, nothing happens.
     *
     * @param item
     *   The item to add.
     */
    add(item: T): void;
    /**
     * Attempts to consume an item from the queue in FIFO order, waiting until there is one, unless the
     * queue is closed.
     *
     * @returns
     *   A Promise that is resolved with the first item in the queue once it is available, removing the
     *   item. If the queue is empty and has been closed with `close()`, the Promise is rejected instad.
     */
    take(): Promise<T>;
    /**
     * Tests whether the queue is empty.
     *
     * @returns
     *   True if the queue is empty.
     */
    isEmpty(): boolean;
    /**
     * Returns the current number of items in the queue.
     *
     * @returns
     *   The length of the queue.
     */
    length(): number;
    /**
     * Signals that the queue ends permanently after its current position. After calling `close()`,
     * `take()` will still consume any items that already exist in the queue, but once it is empty,
     * `take()` returns an error. No more items can be added.
     */
    close(): void;
}
/**
 * A simple asynchronous lock that can be held by one task at a time.
 *
 * This is a naive implementation that is meant for simple cases where two pieces of async test
 * logic must not be run in parallel because they use the same resource.
 */
export declare class AsyncMutex {
    private held;
    private awaiters;
    constructor();
    /**
     * Acquires the lock as soon as possible.
     *
     * @returns a Promise that resolves once the lock has been acquired
     */
    acquire(): Promise<void>;
    /**
     * Releases the lock. If someone else was waiting on an [[acquire]], they will now acquire it
     * (first come first served). This simple implementation does not verify that you were the
     * one who had actually acquired the lock.
     */
    release(): void;
    /**
     * Acquires the lock, awaits an asynchronous action, and ensures that the lock is released.
     * @param action an asynchronous function
     * @returns the function's return value.
     */
    do<T>(action: () => Promise<T>): Promise<T>;
}