{"id":"morgann1/promise-luau","name":"promise-luau","scope":"morgann1","platform":"roblox","description":"Promise implementation for Roblox","version":"4.1.0","latest":"4.1.0","versions":["4.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"942aa3501edb0e307948c10002de56f3e18a081bf411537b0dbdcd90c4d538da","likes":0,"downloads":0,"install":"forest install morgann1/promise-luau","url":"https://forest.dev/p/roblox/morgann1/promise-luau","files":"https://api.forest.dev/ai/package/roblox/morgann1/promise-luau/files","readme":"\n 🤝\n
\n Roblox Lua Promise\n
\n\n\n\n [](https://morgann1.github.io/promise-luau/)\n [](https://morgann1.github.io/promise-luau/changelog)\n [](https://wally.run/package/morgann1/promise-luau)\n [](https://github.com/morgann1/promise-luau/releases)\n
\n\nAn implementation of `Promise` similar to Promise/A+.\n\n\n\n\n## Why you should use Promises\n\nThe way Roblox models asynchronous operations by default is by yielding (stopping) the thread and then resuming it when the future value is available. This model is not ideal because:\n\n- Functions you call can yield without warning, or only yield sometimes, leading to unpredictable and surprising results. Accidentally yielding the thread is the source of a large class of bugs and race conditions that Roblox developers run into.\n- It is difficult to deal with running multiple asynchronous operations concurrently and then retrieve all of their values at the end without extraneous machinery.\n- When an asynchronous operation fails or an error is encountered, Lua functions usually either raise an error or return a success value followed by the actual value. Both of these methods lead to repeating the same tired patterns many times over for checking if the operation was successful.\n- Yielding lacks easy access to introspection and the ability to cancel an operation if the value is no longer needed.\n\nThis Promise implementation attempts to satisfy these traits:\n\n* An object that represents a unit of asynchronous work\n* Composability\n* Predictable timing\n\n## Types\n\n`Promise.new`, `Promise.resolve`, `Promise.fromEvent`, and `Promise.delay` return a `Promise`. Handlers passed to its methods get typed parameters, and `expect` returns `T...`. Methods that keep the values, such as `tap`, `finally`, `timeout`, and `now`, keep `T...`.\n\n`andThen`, `catch`, and the list functions such as `Promise.all` return an `AnyPromise`. Luau can't type an alias that refers to itself with different arguments, and a handler can return a Promise that gets chained onto. Cast to type the result again:\n\n```luau\nlocal Promise = require(path.to.Promise)\n\nlocal function fetchName(userId: number): Promise.Promise\n\treturn fetchUser(userId):andThen(function(user)\n\t\treturn user.name\n\tend) :: Promise.Promise\nend\n```\n\n`await` returns `(boolean, ...any)`, since a rejection resolves with the error instead. Use `expect` for typed values, or annotate: `local ok, name: string = fetchName(1):await()`.\n\n## Development\n\nInstall the toolchain with [Rokit](https://github.com/rojo-rbx/rokit), then the dev packages:\n\n```bash\nrokit install\nlute scripts/install.luau\n```\n\n| Command | Purpose |\n| --- | --- |\n| `lute scripts/test.luau` | Runs the Jest specs in Roblox Studio through run-in-roblox. Studio must be installed and signed in. |\n| `lute scripts/analyze.luau` | Type-checks `src` and `scripts` with luau-lsp. |\n| `lute scripts/lint.luau` | Runs Selene and StyLua. |\n| `lute scripts/release.luau ` | Creates the GitHub release with that version's changelog section as notes. Pushing a `v*` tag runs it in CI. |\n\nSpecs live next to the code as `*.spec.luau`.\n","readmeTruncated":false}