{"id":"trheliad/typed-luau-promise","name":"typed-luau-promise","scope":"trheliad","platform":"roblox","description":"Type wrapper for roblox-lua-promise","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":["The package archive does not include its license text; the license is declared in its manifest metadata."],"licenseVerified":false,"dependencies":{},"integrity":"b128b2f4b3776cb64b6929b838ff78393e27a988717344c5d75b73a9b36c1d3a","likes":0,"downloads":0,"install":"forest install trheliad/typed-luau-promise","url":"https://forest.dev/p/roblox/trheliad/typed-luau-promise","files":"https://api.forest.dev/ai/package/roblox/trheliad/typed-luau-promise/files","readme":"# Typed Roblox Promises\r\n\r\nThis is a wrapper that adds full Luau type support for\r\n[roblox-lua-promise](https://github.com/evaera/roblox-lua-promise). It does this\r\nusing some fancy Luau type trickery. The result is a way more pleasant\r\nexperience when using Promises in luau where everything is fully typed, even\r\nwhen you chain promises.\r\n\r\n## Installation\r\n\r\nTo install, simply copy the Promise.lua script into your project and modify the\r\n`game.ReplicatedStorage.Packages.UntypedPromise` at the bottom with the path to\r\nroblox-lua-promise.\r\n\r\n## Usage\r\n\r\nYou can simply use this typed wrapper the same way you'd use\r\n`roblox-lua-promise` itself. This is a drop-in replacement that you will\r\nimmediately reap the benefits of in your existing code.\r\n\r\n## What's so special about this?\r\n\r\nThis wrapper fully supports chaining promises, which most other wrappers are\r\nunable to. It does this by repeating the type definition of Promise multiple\r\ntimes. This is because recursive types are not supported in Luau, making this\r\nneccessary to have a correct definition for promises.\r\n![image](https://github.com/fewkz/typed-luau-promise/assets/83943819/8fec9389-1ca3-407b-ae0e-b2dc19278fdd)\r\n\r\n## Why is there a generation script?\r\n\r\nInstead of having to manually write out a repeated type definition 10 times,\r\nthere's a `generate-promise.ts` script that does this for us, making it very\r\neasy to modify the definition without having to make the change multiple times.\r\nTo run the generation script, simply do\r\n`deno run generate-promise.ts > Promise.lua`\r\n\r\n## Things you may run into\r\n\r\n### Incomplete definition\r\n\r\nThis wrapper doesn't define every single function in roblox-lua-promise because\r\nI never got around to it. Adding new ones is relatively straight forward, and\r\nmay be added whenever I run into the need. Feel free to contribute a pull\r\nrequest adding any missing definitions.\r\n\r\n### Promise.all\r\n\r\nThe definition of `Promise.all` requires all of the promises passed in to have\r\nthe same non-variable return type. This is so that the output promise can be\r\ntyped as `Promise<{ T }>`. It will cause issues if you have code like this:\r\n\r\n```lua\r\nlocal pA = fetchA() -- returns `string`\r\nlocal pB = fetchB() -- returns `number`\r\nlocal pC = fetchC() -- returns `boolean`\r\nlocal a, b, c = unpack(Promise.all({pA, pB, pC}):expect()) -- errors since promise types aren't uniform\r\n```\r\n\r\nYou should ideally rewrite the code to look this instead:\r\n\r\n```lua\r\nlocal pA = fetchA()\r\nlocal pB = fetchB()\r\nlocal pC = fetchC()\r\nlocal a = pA:expect()\r\nlocal b = pB:expect()\r\nlocal c = pC:expect()\r\n```\r\n\r\n### Generic variable type\r\n\r\nFor cases where a variable may need to store a generic promise, you can use the\r\n`AnyPromise` type. This stores any promise, however you don't get any type info\r\nabout what the promise will return.\r\n\r\n```lua\r\nlocal p: Promise.AnyPromise\r\n\r\np = Promise.resolve(\"hello\")\r\np = Promise.resolve(5)\r\np = p:andThen(function(r) -- r is typed as `any`\r\n    return r\r\nend)\r\n```\r\n","readmeTruncated":false}