{"id":19356910,"url":"https://github.com/alexfigliolia/task-queue","last_synced_at":"2026-02-08T17:31:35.428Z","repository":{"id":181708250,"uuid":"666920665","full_name":"alexfigliolia/task-queue","owner":"alexfigliolia","description":"A basic queue for handling prioritized and scheduled tasks","archived":false,"fork":false,"pushed_at":"2025-01-13T19:19:59.000Z","size":280,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T10:46:45.389Z","etag":null,"topics":["priority-queue","queue","task-queue"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@figliolia/task-queue","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexfigliolia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-07-16T03:24:18.000Z","updated_at":"2025-01-13T19:20:03.000Z","dependencies_parsed_at":"2025-04-23T10:47:00.204Z","dependency_job_id":null,"html_url":"https://github.com/alexfigliolia/task-queue","commit_stats":null,"previous_names":["alexfigliolia/task-queue"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexfigliolia/task-queue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfigliolia%2Ftask-queue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfigliolia%2Ftask-queue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfigliolia%2Ftask-queue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfigliolia%2Ftask-queue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexfigliolia","download_url":"https://codeload.github.com/alexfigliolia/task-queue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfigliolia%2Ftask-queue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29238279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T14:18:14.570Z","status":"ssl_error","status_checked_at":"2026-02-08T14:18:14.071Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["priority-queue","queue","task-queue"],"created_at":"2024-11-10T07:05:49.020Z","updated_at":"2026-02-08T17:31:35.412Z","avatar_url":"https://github.com/alexfigliolia.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Task Queue\nTask prioritization and scheduling made easy!\n\n# Getting Started\n\n## Installation\n```bash\nnpm install --save @figliolia/task-queue\n# or\nyarn add @figliolia/task-queue\n```\n\n## Basic Usage\n\n### Scheduling Tasks using Prioritized Execution\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = new TaskQueue({ priorities: 4 });\n// This TaskQueue will have 4 priority levels for\n// registering tasks\n\nconst task1 = () =\u003e {};\nconst task2 = () =\u003e {};\nconst task3 = () =\u003e {};\nconst task4 = () =\u003e {};\n\nTQ.registerTask(task1, 4); // Priority 4\nTQ.registerTask(task2, 3); // Priority 3\nTQ.registerTask(task3, 2); // Priority 2\nTQ.registerTask(task4, 1); // Priority 1\n\nconst cancelFN = TQ.executeAll();\n// The execution order =\u003e task4, task3, task2, task1\n\n// Calling cancelFN() will cancel task execution at any point\n```\n\n\n### Scheduling Tasks using deferrals\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = new TaskQueue();\n\nconst cancelFN = TQ.deferTask(() =\u003e {\n  // This task will execute after 1000ms\n  // and won't leak memory if canceled\n}, 1000);\n\n// Optionally calling `cancelFN()` will prevent the\n// task from being executed\n```\n## API\n### Task Queue\n\n#### `constructor(options): TaskQueue`\nThe constructor can accept an `options` argument with the following keys and default values\n```typescript\nconst TQ = new TaskQueue({\n  // The number of priority-levels your queue will have\n  priorities: 1,\n  // Whether or not your queue will auto-run tasks as they're added\n  // to the queue\n  autoRun: false,\n  // The number of milliseconds to elapse between tasks. For all \n  // TaskQueue methods that accept a taskSeparation argument its \n  // value defaults to the one provided by this parameter\n  taskSeparation: 0,\n  // When using this module in the browser and user-interaction \n  // is detected, this argument represents the number of \n  // milliseconds to pause the tasks queue and yield to the main \n  // thread\n  mainThreadYieldTime: 5,\n})\n```\n\n#### `registerTask(task: Task, priority: number): CancelFN`\nRegisters a function to execute at a certain priority level. Returns a cancel function that, if called, will remove the task from the queue\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst N = 3;\n\nconst TQ = TaskQueue({ priorities: N });\n\nconst cancelFN = TQ.registerTask(() =\u003e {}, 1)\n```\n#### `deferTask(task: Task, delay: number): CancelFN`\nRegisters a task to execute after a specified delay. Returns a cancel function that, if called, will remove the task from the queue\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = TaskQueue();\n\nconst cancelFN = TQ.deferTask(() =\u003e {}, 1000);\n```\n#### `executeAll(onComplete?: Task, taskSeparation?: number): CancelFN`\nExecutes all prioritized tasks registered using `registerTask()`. Tasks are executed based on the priority levels that they were registered with and dispersed along the call stack using the `taskSeparation`. \n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = TaskQueue({ priorities: 3 });\n\n// Register any number of tasks\nTQ.registerTask(() =\u003e {}, 1);\nTQ.registerTask(() =\u003e {}, 2);\nTQ.registerTask(() =\u003e {}, 3);\n\nconst cancelFN = TQ.executeAll(() =\u003e {\n  console.log('Complete!');\n}, 35 /* task separation */);\n```\nThe `taskSeparation` parameter can be used to disperse registered tasks along the call stack. `taskSeparation` = the number of milliseconds to elapse between tasks. It's set to 0 by default. This is designed to prevent the creation of long blocking tasks when the Task Queue has several entries.\n\nInvoking the returned cancel function will pause the execution of the remaining tasks in the queue until `executeAll()` is called again.\n\n##### `executeTasksWithPriority(): CancelFN`\nExecutes all tasks registered at a specified priority level. Returns a cancel function\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = TaskQueue({ priorities: 3 });\n// Register any number of tasks\n\nconst cancelFN = TQ.executeTasksWithPriority(\n  1, // Priority \n  0, // Task Separation MS\n  () =\u003e { // On complete function\n  console.log(\"Complete!\");\n});\n// Executes all tasks registered with priority level 1\n```\nCalling the returned cancel function will pause the execution of tasks. \n\nUsing `executeTasksWithPriority()` can allow developers to organize tasks based on arbitrary means and identify them using their priority. This can be useful if managing the execution of registered tasks based on arbitrary categorization. Let's look at an example using application routing:\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = new TaskQueue({ priorities: 3 });\n\n// Let's map our application routes to a priority level\nenum RouteMap {\n  \"home\" = 1,\n  \"about\" = 2,\n  \"profile\" = 3\n}\n\n// Next lets register a data loading task for\n// each route\nTQ.registerTask(() =\u003e {\n  // Tasks to execute when navigating to home\n  void fetchGreeting();\n}, RouteMap.home);\n\nTQ.registerTask(() =\u003e {\n  // Tasks to execute when navigating to about\n  void fetchUserData();\n}, RouteMap.about);\n\nTQ.registerTask(() =\u003e {\n  // Tasks to execute when navigating to profile\n  void fetchProfile();\n}, RouteMap.profile);\n\n// Listen for routing changes using hashchange or pushstate\nwindow.addEventListener(\"hashchange\", () =\u003e {\n  const nextRoute = window.location.hash.slice(1);\n  if(nextRoute in RouteMap) {\n    // Execute data loader for matched routes!\n    TQ.executeTasksWithPriority(routeMap[nextRoute]);\n  }\n});\n```\nIn the above example, the `TaskQueue's` priority levels are used for categorizing data preloading tasks based on the route they correspond with. When the browser routes to a supported route found in the `routeMap`, the tasks corresponding with the route are executed as early as possible.\n\n#### `clearPendingTasks(): void`\nRemoves all pending tasks from the task `TaskQueue`. This includes both prioritized tasks registered using `TaskQueue.registerTask()` and deferred tasks registered using `TaskQueue.deferTask()`\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = TaskQueue({ priorities: 3 });\n\nTQ.registerTask(() =\u003e {}, 1);\nTQ.registerTask(() =\u003e {}, 2);\nTQ.registerTask(() =\u003e {}, 3);\nTQ.deferTask(() =\u003e {}, 1000);\n\nTQ.clearPendingTasks(); \n// Resets the Queue removing all registered tasks\n```\n\n#### `clearDeferredTasks(): void`\nRemoves all pending tasks registered using `TaskQueue.deferTask()`. These tasks are released, cancelled and forgotten by the `TaskQueue`\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = TaskQueue();\n\nTQ.deferTask(() =\u003e {}, 1000);\nTQ.deferTask(() =\u003e {}, 2000);\nTQ.deferTask(() =\u003e {}, 3000);\n\nTQ.clearDeferredTasks(); \n// Cancels all currently pending deferred tasks\n```\n\n#### `getCancelFN(): CancelFN | void`\nReturns the current cancel token if the `TaskQueue` is executing or undefined if the `TaskQueue` is idol.\n```typescript\nimport { TaskQueue } from \"@figliolia/task-queue\";\n\nconst TQ = TaskQueue({ priorities: 3 });\n\n// Register any number of tasks\nTQ.registerTask(() =\u003e {}, 1);\nTQ.registerTask(() =\u003e {}, 2);\nTQ.registerTask(() =\u003e {}, 3);\n\nTQ.executeAll();\n\nconst cancel = TQ.getCancelFN(); \n// Returns a CancelFN during execution\ncancel \u0026\u0026 cancel()\n```\n\n## Advanced Usage\n\n### Using `autoRun`\nThe `autoRun` option is designed to make your `TaskQueues` run at all times. This option will cause registered tasks to `auto-execute` as soon as they're enqueued. Tasks will continue to execute at their appropriate priority levels, but allow lower priority tasks to execute immediately if the Queue is empty!\n```typescript\nconst TQ = new TaskQueue({ \n  priorities: 3, \n  autoRun: true,\n  taskSeparation: 10,\n  mainThreadYieldTime: 5,\n});\n\nconst task1 = () =\u003e {};\nconst task2 = () =\u003e {};\nconst task3 = () =\u003e {}\n\nTQ.registerTask(task3, 3);\nTQ.registerTask(task2, 2);\nTQ.registerTask(task1, 1);\n\n// The above tasks will execute without calling `TQ.executeAll()`\n\n// The execution order will be task1 =\u003e task2 =\u003e task3 with 10ms \n// elapsing between each task\n\n// To cancel task execution at any point\nconst cancel = TQ.getCancelFN();\ncancel \u0026\u0026 cancel();\n\n// To begin execution again\nTQ.executeAll()\n```\nUsing the `autoRun` option is great prioritizing the execution of startup tasks in complex frontend apps or responsibly managing request handling on the server","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexfigliolia%2Ftask-queue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexfigliolia%2Ftask-queue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexfigliolia%2Ftask-queue/lists"}