{"id":13701363,"url":"https://github.com/cmseaton42/task-easy","last_synced_at":"2025-04-05T05:06:11.288Z","repository":{"id":31010059,"uuid":"126502324","full_name":"cmseaton42/task-easy","owner":"cmseaton42","description":"A simple, customizable, and lightweight priority queue for promises.","archived":false,"fork":false,"pushed_at":"2023-01-04T21:35:56.000Z","size":887,"stargazers_count":246,"open_issues_count":14,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-13T09:15:38.889Z","etag":null,"topics":["async","in-memory","javascript","lightweight","promise","queue","runner","task"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmseaton42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-23T15:12:31.000Z","updated_at":"2024-10-07T12:04:12.000Z","dependencies_parsed_at":"2023-01-14T18:09:46.577Z","dependency_job_id":null,"html_url":"https://github.com/cmseaton42/task-easy","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmseaton42%2Ftask-easy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmseaton42%2Ftask-easy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmseaton42%2Ftask-easy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmseaton42%2Ftask-easy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmseaton42","download_url":"https://codeload.github.com/cmseaton42/task-easy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289426,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["async","in-memory","javascript","lightweight","promise","queue","runner","task"],"created_at":"2024-08-02T20:01:32.904Z","updated_at":"2025-04-05T05:06:11.273Z","avatar_url":"https://github.com/cmseaton42.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\u003cimg width=\"280\" src=\"https://i.imgur.com/VwF0DyE.png\" alt=\"Task Easy Logo\"\u003e\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\u003ca href=\"https://www.npmjs.com/package/task-easy\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/task-easy.svg?style=flat-square\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/cmseaton42/task-easy/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/cmseaton42/task-easy.svg?style=flat-square\" alt=\"license\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/travis/cmseaton42/task-easy.svg?style=flat-square\" alt=\"Travis\" /\u003e\n  \u003cimg src=\"https://img.shields.io/coveralls/github/cmseaton42/task-easy.svg?style=flat-square\" alt=\"Coveralls github\" /\u003e\n  \u003ca href=\"https://github.com/cmseaton42/task-easy\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/cmseaton42/task-easy.svg?\u0026amp;style=social\u0026amp;logo=github\u0026amp;label=Stars\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n# Task Easy - Promise Queue Made Easy ✅\n\nA simple, customizable, and lightweight priority queue for promise based tasks.\n\n\u003e Now with types!!! Big thanks to [Emiliano Heyns](https://github.com/retorquere) :beers:\n\u003e\n\u003e -   See below example for typescript version\n\n## Getting Started\n\nInstall with npm\n\n```\nnpm install task-easy --save\n```\n\n## How it Works\n\n**TaskEasy** is built as an extension of a simple heap data structure. Tasks are queued by simply passing a task (function) to the `.schedule` method along with an array of arguments to be called as well as an object to describe the task's relative priority. The caller is returned a promise which will resolve once the scheduled task has ran. Priority determination is left up to the user via a function that accepts task priority object and returns a judgement.\n\n### Usage\n\nThe usage of **TaskEasy** is best given by example so that is the route we will take.\n\nIn this example, we will be passing priority objects to the scheduler that will be marked by the following signature.\n\n```js\n{\n    // An integer representing priority,\n    // the higher the number the higher the priority\n    priority: Number,\n\n    // A timestamp to illustrate when the task\n    // was scheduled, used as a 'tie-breaker' for\n    // tasks of the same priority\n    timestamp: Date\n}\n```\n\n\u003e **NOTE**\n\u003e\n\u003e The priority object's signature that you want to queue your items with is 100% up to you. 😄\n\nNow, let's create a function that will receive our priority objects and output a priority judgment so that _TaskEasy_ knows how to handle queued tasks. Our function will be passed two arguments (the priority objects of two scheduled tasks) and return a judgement indicating which task is of _higher_ priority. If we return `true`, then we are communicating to _TaskEasy_ that the first task is higher priority than the second task or vice versa\n\n```js\n// This function is passed to the TaskEasy contructor and will be used internally to determine tasks order.\nconst prioritize = (obj1, obj2) =\u003e {\n    return obj1.priority === obj2.priority\n        ? obj1.timestamp.getTime() \u003c obj2.timestamp.getTime() // Return true if task 1 is older than task 2\n        : obj1.priority \u003e obj2.priority; // return true if task 1 is higher priority than task 2\n};\n```\n\nNow, we can initialize a new _TaskEasy_ instance.\n\n```js\nconst { TaskEasy } = require(\"task-easy\");\n\nconst max_tasks = 200; // How many tasks will we allow to be queued at a time (defaults to 100)\nconst queue = new TaskEasy(prioritize, max_tasks);\n```\n\nNow, lets build an async function to demo the scheduler.\n\n```js\nconst delay = ms =\u003e new Promise(resolve =\u003e setTimeout(resolve, ms));\n```\n\n\u003e **NOTE**\n\u003e\n\u003e Scheduled tasks _MUST_ be functions that return _promises_. This works well with async functions or with ES2017 `ASYNC/AWAIT` functions.\n\nNow, that we have a task to schedule, let's schedule some tasks. The `.schedule` method takes three arguments, the task to call, an array of arguments, and a priority object that is associated with the scheduled task. It will return a promise that will resolve or reject once the task has been ran.\n\n```js\n// .schedule accepts the task signature,\n// an array or arguments, and a priority object\nconst task1 = queue\n    .schedule(delay, [100], { priority: 1, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 1 ran...\"));\n\nconst task2 = queue\n    .schedule(delay, [100], { priority: 1, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 2 ran...\"));\n\nconst task3 = queue\n    .schedule(delay, [100], { priority: 2, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 3 ran...\"));\n\nconst task4 = queue\n    .schedule(delay, [100], { priority: 1, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 4 ran...\"));\n\nconst task5 = queue\n    .schedule(delay, [100], { priority: 3, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 5 ran...\"));\n\n// OUTPUT\n// Task 1 ran...\n// Task 5 ran...\n// Task 3 ran...\n// Task 2 ran...\n// Task 4 ran...\n```\n\n\u003e **NOTE**\n\u003e\n\u003e In the above example, `task1` resolved first as it once put onto the queue first and was immediately called as it was the only task on the queue at that time.\n\n## Now with _Typescript_\n\n```typescript\nimport { TaskEasy } from \"task-easy\";\n\n// Define interface for priority\n//  objects to be used in the\n//  TaskEasy instance\ninterface IPriority {\n    priority: number;\n    timestamp: Date;\n}\n\n// Define delay function type\n// -\u003e Must extend  Task\u003cT\u003e: (...args) =\u003e Promise\u003cT\u003e\ntype delayFn = (ms: number) =\u003e Promise\u003cundefined\u003e;\n\n// Define delay function of type 'delayFn' defined above\nconst delay: delayFn = ms =\u003e new Promise(resolve =\u003e setTimeout(resolve, ms));\n\n// Define priority function\n// -\u003e Must extend (obj1: T, obj2: T) =\u003e\nconst prioritize = (obj1: IPriority, obj2: IPriority) =\u003e {\n    return obj1.priority === obj2.priority\n        ? obj1.timestamp.getTime() \u003c obj2.timestamp.getTime() // Return true if task 1 is older than task 2\n        : obj1.priority \u003e obj2.priority; // return true if task 1 is higher priority than task 2\n};\n\n// Initialize new queue\nconst queue = new TaskEasy(prioritize); // equivalent of TaskEasy\u003cIPriority\u003e(prioritize) via type inference\n\n// .schedule accepts the task signature,\n// an array or arguments, and a priority object\n// -\u003e with type inference\nconst task1 = queue\n    .schedule(delay, [100], { priority: 1, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 1 ran...\"));\n\nconst task2 = queue\n    .schedule(delay, [100], { priority: 1, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 2 ran...\"));\n\n// Definitely typed\nconst task3 = queue\n    .schedule\u003cundefined, delayFn\u003e(delay, [100], { priority: 2, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 3 ran...\"));\n\nconst task4 = queue\n    .schedule\u003cundefined, delayFn\u003e(delay, [100], { priority: 1, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 4 ran...\"));\n\nconst task5 = queue\n    .schedule\u003cundefined, delayFn\u003e(delay, [100], { priority: 3, timestamp: new Date() })\n    .then(() =\u003e console.log(\"Task 5 ran...\"));\n\n// OUTPUT\n// Task 1 ran...\n// Task 5 ran...\n// Task 3 ran...\n// Task 2 ran...\n// Task 4 ran...\n```\n\n## Built With\n\n-   [NodeJS](https://nodejs.org/en/) - The Engine\n-   [javascript - ES2017](https://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf) - The Language\n\n## Contributers\n\n-   **Canaan Seaton** - _Owner_ - [GitHub Profile](https://github.com/cmseaton42) - [Personal Website](http://www.canaanseaton.com/)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENCE](https://github.com/cmseaton42/task-easy/blob/master/LICENSE) file for details\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmseaton42%2Ftask-easy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmseaton42%2Ftask-easy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmseaton42%2Ftask-easy/lists"}