![](\"media/logo-centered.png\"){kind=logo}
\n\n\nFast and consistently responsive apps using a single function call\n
\n\n\n\n
\n\n## Install\n\n```bash\nnpm install main-thread-scheduling\n```\n\n## Overview\n\nThe library lets you run computationally heavy tasks on the main thread while ensuring:\n- Your app's UI doesn't freeze.\n- Your users' computer fans don't spin.\n- Your [INP (Interaction to Next Paint)](https://web.dev/articles/inp) is in green.\n- It's easy to plug it into your existing codebase.\n\nA real world showcase of [searching in a folder with 10k notes, 200k+ lines of text, that take 50MB on disk](https://twitter.com/antoniostoilkov/status/1539576912498118656) and getting results instantly.\n\n## Use Cases\n\n- You want to turn a synchronous function into a non-blocking asynchronous function. **Avoids UI freezes.**\n- You want to render important elements first and less urgent ones second. **Improves perceived performance.**\n- You want to run a long background task that doesn't spin the fans after a while. **Avoids bad reputation.**\n- You want to run multiple backgrounds tasks that don't degrade your app performance with time. **Prevents death by a thousand cuts.**\n\n## How It Works\n\n- Uses `requestIdleCallback()` and `requestAfterFrame()` for scheduling.\n- Stops task execution when user interacts with the UI (if `navigator.scheduling.isInputPending()` API is available).\n- Global queue. Multiple tasks are executed one by one so increasing the number of tasks doesn't degrade performance linearly.\n- Sorts tasks by importance. Sorts by [strategy](#scheduling-strategies) and gives priority to tasks requested \n later.\n- Considerate about your existing code. Tasks with `idle` strategy are executed last so there \n isn't some unexpected work that slows down the main thread after the background task is finished.\n\n## Why\n\n- **Simple.** 90% of the time you only need the `yieldOrContinue(strategy)` function. The API has two more functions for more advanced cases.\n- **Not a weekend project.** Actively maintained for three years — see [contributors](https://github.com/astoilkov/main-thread-scheduling/graphs/contributors) page. I've been using it in my own products for over four years — [Nota](https://nota.md) and [iBar](https://ibar.app). [Flux.ai](https://flux.ai/) are also using it in their product (software for designing hardware circuits using web technologies).\n- **This is the future.** [Some browsers](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/postTask#browser_compatibility) have already implemented support for scheduling tasks on the main thread. This library tries even harder to improve user perceived performance — see [explanation](#alternatives) for details.\n- **High quality.** Aiming for high-quality with [my open-source principles](https://astoilkov.com/my-open-source-principles).\n\n## Example\n\nYou can see the library in action in [this CodeSandbox](https://codesandbox.io/s/main-thread-scheduling-example-qqef6?file=/src/App.js:1188-1361). Try removing the call to `yieldToContinue()` and then type in the input to see the difference.\n\n## API\n\n#### `yieldOrContinue(strategy: 'interactive' | 'smooth' | 'idle', signal?: AbortSignal)`\n\nThe complexity of the entire library is hidden behind this method. You can have great app performance by calling a single method.\n\n```ts\nasync function findInFiles(query: string) { \n for (const file of files) {\n await yieldOrContinue('interactive')\n \n for (const line of file.lines) {\n fuzzySearchLine(line, query)\n }\n }\n}\n```\n\n### More complex scenarios\n\nThe library has two more functions available:\n- `yieldControl(strategy: 'interactive' | 'smooth' | 'idle', signal?: AbortSignal)`\n- `isTimeToYield(strategy: 'interactive' | 'smooth' | 'idle', signal?: AbortSignal)`\n\nThese two functions are used together to handle more advanced use cases.\n\nA simple use case where you will need those two functions is when you want to render your view before yielding back control to the browser to continue its work:\n```ts\nasync function doHeavyWork() {\n for (const value of values) {\n if (isTimeToYield('interactive')) {\n render()\n await yieldControl('interactive')\n }\n \n computeHeavyWorkOnValue(value)\n }\n}\n```\n\n### Scheduling strategies\n\nThere are three scheduling strategies available. You can think about them more easily by completing the sentence with one of the three words: \"Scheduling the task keeps the page `interactive`/`smooth`/`idle`.\"\n\n- `interactive` – use this for things that need to display to the user as fast as possible. Every `interactive` task is run for 83ms – this gives you a nice cycle of doing heavy work and letting the browser render pending changes.\n- `smooth` — use this for things you want to display to the user quickly but you still want for animations to run smoothly for example. `smooth` runs for 13ms and then gives around 3ms to render the frame.\n- `idle` – use this for background tasks. Every idle task is run for 5ms.\n\n## Alternatives\n\n### Web Workers\n\nWeb Workers are a great fit if you have: 1) heavy algorithm (e.g. image processing), 2) heavy process (runs for a long time, big part of the app lifecycle). However, in reality, it's rare to see people using them. That's because they require significant investment of time due to the complexity that can't be avoided when working with CPU threads regardless of the programming language. This library can be used as a gateway before transitioning to Web Workers. In most cases, you would discover the doing it on the main thread is good enough.\n\n### `scheduler.postTask()`\n\n[`scheduler.postTask()`](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/postTask) is available in some browsers today. `postTask()` and `main-thread-scheduling` do similar things. You can think of `postTask()` as a lower level API — it might be the right choice in specific scenarios. Library owners might be interested in exploring the nuanced differences between the two. For most cases, `main-thread-scheduling` provides a `scheduleTask()` method that mimics that API of `postTask()` while providing the extra benefits of the library.\n\n## Need consulting help?\n\nNeed help with performance or consulting on how to integrate `main-thread-scheduling` in your project? Write to me at [hello@astoilkov.com](hello@astoilkov.com).\n\n\n","readmeFilename":"readme.md"}
![\"Gzipped](\"https://img.shields.io/bundlephobia/minzip/main-thread-scheduling\")
\n![\"Build](\"https://img.shields.io/github/actions/workflow/status/astoilkov/main-thread-scheduling/main.yml?branch=main\")
\n