@rbxts/wait-for/out/index.d.ts

Wait for instances to exist

/// <reference types="@rbxts/types" />
/// <reference types="@rbxts/compiler-types" />
export declare enum WaitForError {
    Destroyed = "Destroyed"
}
/**
 * Wait for a child of a given name to exist within a parent. The promise will be rejected if the
 * parent is destroyed or the timeout is reached.
 *
 * ```ts
 * waitForChild(parent, "ChildName").then((child) => {
 * 	print(child.GetFullName());
 * });
 * ```
 *
 * @param parent The parent to look within.
 * @param childName The name of the child.
 * @param recursive Defaults to `false`. If `true`, will find within all descendants of the parent.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns Promise containing the found instance.
 */
export declare function waitForChild<T extends Instance = Instance>(parent: Instance, childName: string, recursive?: boolean, timeout?: number): Promise<T>;
/**
 * Wait for a child of a given superclass to exist within a parent. The promise will be rejected if the
 * parent is destroyed or the timeout is reached.
 *
 * ```ts
 * waitForChildWhichIsA(parent, "BasePart").then((part) => {
 * 	print(part.GetFullName());
 * });
 * ```
 *
 * @param parent The parent to look within.
 * @param className The superclass name.
 * @param recursive Defaults to `false`. If `true`, will find within all descendants of the parent.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns Promise containing the found instance.
 */
export declare function waitForChildWhichIsA<T extends keyof Instances>(parent: Instance, className: T, recursive?: boolean, timeout?: number): Promise<Instances[T]>;
/**
 * Wait for a child of a given class to exist within a parent. The promise will be rejected if the
 * parent is destroyed or the timeout is reached.
 *
 * ```ts
 * waitForChildOfClass(parent, "PointLight").then((light) => {
 * 	print(light.GetFullName());
 * });
 * ```
 *
 * @param parent The parent to look within.
 * @param className The class name.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns Promise containing the found instance.
 */
export declare function waitForChildOfClass<T extends keyof Instances>(parent: Instance, className: T, timeout?: number): Promise<Instances[T]>;
/**
 * Waits for all children in a parent to exist.
 *
 * ```ts
 * waitForChildren(parent, ["LeftWheel", "RightWheel"]).then((children) => {
 * 	const leftWheel = children[0];
 * 	const rightWheel = children[1];
 * });
 * ```
 *
 * @param parent The parent to look within.
 * @param childrenNames The names of the children instances to find.
 * @param recursive Defaults to `false`. If `true`, will find within all descendants of the parent.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns A promise containing an array of all the children in order of which they appear in the `childrenNames` array.
 */
export declare function waitForChildren(parent: Instance, childrenNames: string[], recursive?: boolean, timeout?: number): Promise<Instance[]>;
/**
 * Waits for the PrimaryPart of a model to exist.
 *
 * ```ts
 * waitForPrimaryPart(model).then((primaryPart) => {
 * 	print(primaryPart.GetFullName());
 * });
 * ```
 *
 * @param model The model to await the PrimaryPart.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns A promise containing the PrimaryPart.
 */
export declare function waitForPrimaryPart(model: Model, timeout?: number): Promise<BasePart>;
/**
 * Waits for the value of an ObjectValue to exist (i.e. not be `nil`).
 *
 * ```ts
 * waitForObjectValue(objectValue).then((value) => {
 * 	print(value);
 * });
 * ````
 *
 * @param objectValue The ObjectValue to await its Value to not be `nil`.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns A promise containing the ObjectValue's Value.
 */
export declare function waitForObjectValue<T extends Instance = Instance>(objectValue: ObjectValue, timeout?: number): Promise<T>;
export declare function waitForAttribute<T extends AttributeValue>(instance: Instance, attributeName: string, timeout?: number): Promise<T>;
/**
 * Waits for the given predicate function to return a non-undefined value.
 *
 * The predicate function is called every `RunService.Heartbeat`. As long
 * as the predicate returns `undefined`, it will continue to be called every
 * Heartbeat. Once the predicate returns a non-undefined value of type `T`,
 * the predicate will stop being called and will resolve the promise with the
 * given value.
 *
 * This can be used for more complex waiting strategies that the other `waitFor`
 * functions do not cover.
 *
 * ```ts
 * // e.g. wait for a specific player
 * waitForCustom(() => {
 * 	const me = Players.FindFirstChild("MyUsername") as Player | undefined;
 * 	return me;
 * }).then((me) => {
 * 	print(me);
 * });
 * ```
 *
 * @param predicate A function that will be called every Heartbeat & should return `undefined` until the
 * expected value is available, in which case the predicate should return the value.
 * @param timeout Seconds to wait before timing out. Defaults to 60 seconds.
 * @returns A promise containing the value returned by the predicate function.
 */
export declare function waitForCustom<T>(predicate: () => T | undefined, timeout?: number): Promise<T>;