luau-promise/lib/README.md

title

docs

Promise

desc types properties functions A Promise is an object that represents a value that will exist in the future, but doesn't right now. Promises allow you to then attach callbacks that can run once the value becomes available (known as *resolving*), or if an error has occurred (known as *rejecting*). name desc kind type PromiseStatus An enum value used to represent the Promise's status. enum Started Resolved Rejected Cancelled desc The Promise is executing, and not settled yet. desc The Promise finished successfully. desc The Promise was rejected. desc The Promise was cancelled before it finished. name tags type desc Status read only static enums PromiseStatus A table containing all members of the `PromiseStatus` enum, e.g., `Promise.Status.Resolved`. name tags desc static params returns new constructor Construct a new Promise that will be resolved or rejected with the given callbacks. ::: tip Generally, it is recommended to use Promise.async instead. You cannot directly yield inside the `executor` function of Promise.new. ::: If you `resolve` with a Promise, it will be chained onto. You may register an optional cancellation hook by using the `onCancel` argument. * This should be used to abort any ongoing operations leading up to the promise being settled. * Call the `onCancel` function with a function callback as its only argument to set a hook which will in turn be called when/if the promise is cancelled. * When a promise is cancelled, calls to `resolve` or `reject` will be ignored, regardless of if you set a cancellation hook or not. true name type executor kind params function name type resolve kind params returns function name type ... ...any? void name type reject kind params returns function name type ... ...any? void name type onCancel kind params returns function name kind abortHandler function void Promise name tags desc static params returns async constructor The same as Promise.new, except it implicitly uses `Promise.spawn` internally. Use this if you want to yield inside your Promise body. ::: tip Promises created with Promise.async are guaranteed to yield for at least one frame, even if the executor function doesn't yield itself. <a href="/roblox-lua-promise/lib/Details.html#yielding-in-promise-executor">Learn more</a> ::: true name type asyncExecutor kind params function name type resolve kind params returns function name type ... ...any? void name type reject kind params returns function name type ... ...any? void name type onCancel kind params returns function name kind abortHandler function void Promise name desc static params returns resolve Creates an immediately resolved Promise with the given value. true value: T Promise<T> name desc static params returns reject Creates an immediately rejected Promise with the given value. true value: T Promise<T> name desc static params returns all Accepts an array of Promises and returns a new promise that: * is resolved after all input promises resolve. * is rejected if ANY input promises reject. Note: Only the first return value from each promise will be present in the resulting array. true promises: array<Promise<T>> Promise<array<T>> name desc static params returns race Accepts an array of Promises and returns a new promise that is resolved or rejected as soon as any Promise in the array resolves or rejects. All other Promises that don't win the race will be cancelled. true promises: array<Promise<T>> Promise<T> name desc static params returns is Returns whether the given object is a Promise. true object: any type desc boolean `true` if the given `object` is a Promise. name desc static params spawn Spawns a thread with predictable timing. The callback will be called on the next `RunService.Heartbeat` event. true name type callback kind params function ...: ...any? name type ... ...any? name desc params returns overloads andThen Chains onto an existing Promise and returns a new Promise. Return a Promise from the success or failure handler and it will be chained onto. name type successHandler kind params returns function ...: ...any? ...any? name optional type failureHandler true kind params returns function ...: ...any? ...any? Promise<...any?> params returns name type successHandler kind params returns function ...: ...any? Promise<T> name optional type failureHandler true kind params returns function ...: ...any? Promise<T> Promise<T> name desc params returns overloads catch Shorthand for `Promise:andThen(nil, failureHandler)`. name type failureHandler kind params returns function ...: ...any? ...any? Promise<...any?> params returns name type failureHandler kind params returns function ...: ...any? Promise<T> Promise<T> name desc params returns overloads finally Set a handler that will be called regardless of the promise's fate. The handler is called when the promise is resolved, rejected, *or* cancelled. Returns a new promise chained from this promise. name type finallyHandler kind returns function ...any? Promise<...any?> params returns name type finallyHandler kind returns function Promise<T> Promise<T> name desc cancel Cancels this promise, preventing the promise from resolving or rejecting. Does not do anything if the promise is already settled. Cancellations will propagate upwards through chained promises. Promises will only be cancelled if all of their consumers are also cancelled. This is to say that if you call `andThen` twice on the same promise, and you cancel only one of the child promises, it will not cancel the parent promise until the other child promise is also cancelled. name desc returns await Yields the current thread until the given Promise completes. Returns `ok` as a bool, followed by the value that the promise returned. desc type Fate of the Promise. `true` if resolved, `false` if rejected, `nil` if cancelled. boolean | nil desc type The values that the Promise resolved or rejected with. ...any? name desc returns getStatus Returns the current Promise status. PromiseStatus