From 538fd0a0384d85a13771df4cefa01e3b6eef1779 Mon Sep 17 00:00:00 2001 From: Samrith Shankar Date: Wed, 6 Dec 2023 17:26:49 +0530 Subject: [PATCH] docs: update `README` and introduction --- README.md | 268 +++--------------- docs/src/content/docs/index.mdx | 2 +- .../docs/introduction/done-callback.mdx | 2 - docs/src/content/docs/introduction/index.mdx | 2 +- 4 files changed, 44 insertions(+), 230 deletions(-) diff --git a/README.md b/README.md index 1f60ec2..a1b58f4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Concurrent Tasks +# 🏃‍♀️ Concurrent Tasks [![npm][npm_v]][npm_package] [![size][size_img]][size] @@ -9,254 +9,70 @@ A simple task runner which will run all tasks till completion, while maintaining concurrency limits. -The following is a quick reference guide to help you get friendly with **Concurrent Tasks**. Visit [the website][website] for a detailed documentation. +> Read the full documentation at the [website][website] -# Table of Contents +# 👋🏼 Introduction -- [👋🏼 Introduction](#introduction) -- [🎬 Getting Started](#getting-started) -- [🏁 The Done Callback](#the-done-callback) -- [⚒ Configuration](#configuration) -- [🕹 API](#api) - - [add](#api-add) - - [addFirst](#api-add-first) - - [addMultiple](#api-add-multiple) - - [addMultipleFirst](#api-add-multiple-first) - - [remove](#api-remove) - - [removeRange](#api-remove-range) - - [removeAt](#api-remove-at) - - [removeAll](#api-remove-all) - - [start](#api-start) - - [setConcurrency](#api-set-concurrency) - - [isBusy](#api-is-busy) -- [💪🏼 Powered by Concurrent Tasks](#powered-by-concurrent-tasks) -- [👩🏻‍💻 Contributing](#contributing) -- [🧐 Issues](#issues) -- [🗺 Roadmap](#roadmap) -- [🔑 License](#license) +Concurrent Tasks mimics a queue by using JavaScript's inbuilt array data type. Each task is a function which signals completion back to the runner. -# 👋🏼 Introduction +The minimalism of Concurrent Tasks makes it an easy-to-use solution across any framework or flavour of JavaScript. It has **ZERO dependencies** and can be used virtually in any scenario. With a **minified and gzipped size of 2.7kB**, it is the ultimate lightweight tool for your concurrency needs. -Concurrent Tasks mimics a priority queue by using JavaScript's inbuilt array data type. Each task is a function which signals completion back to the `TaskRunner`. Once tasks are added, the instance starts executing them until the concurrency criteria is met. Once even a single task is complete (it calls the `done` callback), the next task in the queue is picked up. +- [x] Vanilla JavaScript +- [x] Frontend Frameworks (React, Vue, Angular, etc) +- [x] Backend Frameworks (Express, Hapi, Koa, etc) +- [x] NPM Module +- [x] Node CLI Application -### What can I use it with? +### Browser -The minimalism of Concurrent Tasks makes it an easy-to-use solution across any framework or flavour of JavaScript. It has ZERO dependencies and can be used virtually in any scenario. - -- ✅ Vanilla JavaScript -- ✅ Frontend Frameworks (React, Vue, Angular, etc) -- ✅ Backend Frameworks (Express, Hapi, Koa, etc) -- ✅ NPM Module -- ✅ Node CLI Application - -# 🎬 Getting Started - -Via NPM - -``` -npm install concurrent-tasks -``` - -Or the script tag - -``` - -``` - -### Usage - -```javascript -import TaskRunner from 'concurrent-tasks'; -​ -const runner = new TaskRunner(); -​ -function generateTasks() { - const tasks = []; - let count = 1000; - while(count) { - tasks.push(done => { - setTimeout(() => { - done(); - }, Math.random() * 1000) - }); - count--; - } - return tasks; -} -​ -runner.addMultiple(generateTasks()); -``` - -**Important:** Each task passed to the task runner, necessarily has to call the done function. If not, your queue won't process properly. - -# 🏁 The Done Callback - -In JavaScript, it gets very difficult for tasks to talk to each other. A lot of times, we need to maintain a map of running tasks and call a function which will update the value and call the next task. - -**Concurrent Tasks** is a JavaScript module, which runs multiple tasks concurrently until all the tasks are complete. It needs a way to figure out when a particular task has been completed. - -### Solution - -Gulp solves this problem by either accepting a return of a Gulp task, or by calling a function done. Similarly, to solve the exact same problem, each task passed to the TaskRunner has access to a special function called done (ingenuity max). - -### Purpose - -The purpose of this function is simple: Tell the instance when a particular task is complete! Internally, the done function does a fair amount of work. It: - -- Makes a free slot available for the internal runner. -- Updates completion counts and calls the internal runner. -- Updates the time elapsed from start, until the function calling `done`'s completion. -- Calls the internal runner to pick up the next task in the priority queue. - -### Examples - -For some examples on how you can use the callback, head over to the [docs](https://concurrent-tasks.js.org/the-done-callback#examples). - -# ⚒ Configuration - -| Property | Type | Default | Description | -| ----------- | ---------- | ------------------------- | ------------------------------------------------------------ | -| concurrency | `Number` | `3` | Set the batch size of the task runner. | -| autoStart | `Boolean` | `true` | Decides whether to start executing tasks automatically. | -| name | `String` | `Runner ` | A unique name to identify the `TaskRunner` instance. | -| onAdd | `Function` | `undefined` | Fired every time `add` is called. | -| onStart | `Function` | `undefined` | Fired every time the runner goes from idle to working state. | -| onDone | `Function` | `undefined` | Fired each time a task calls `done` callback. | -| onEnd | `Function` | `undefined` | Fired every time the runner goes from working to idle state. | - -# 🕹 API - -The following methods are provided by **Concurrent Tasks** to help you in manipulating your task list and get the most out of the module. - -### add - -Adds a task to the task list. - -```javascript -add(task: Function, [first: Boolean]) -``` - -### addFirst - -Adds a task to the beginning of the task list. - -```javascript -addFirst(task: Function, [first: Boolean]) +```html + ``` -### addMultiple +### Bun -Adds a collection of tasks to the task list. - -```javascript -addMultiple(tasks: Array.Function, [first: Boolean]) -``` - -### addMultipleFirst - -Adds a collection of tasks to the beginning task list. - -```javascript -addMultipleFirst(tasks: Array.Function) -``` - -### remove - -Remove a task from the task list. - -```javascript -remove([first: Boolean]) -``` - -### removeFirst - -Remove the first task from the task list. - -```javascript -removeFirst(); -``` - -### removeAt - -Remove a task at a particular index from the task list. - -```javascript -removeAt(index: Number) +```bash +bun install concurrent-tasks ``` -### removeAll - -Removes all tasks in the task list. +### Deno -```javascript -removeAll(); +```ts +import { TaskRunner } from "https://cdn.jsdelivr.net/npm/concurrent-tasks/src/index.ts"; ``` -### start - -Programmatically start processing the first batch of tasks from the task list. - -```javascript -start(); -``` +### Usage -### setConcurrency +> **Important:** Each task passed to the task runner, necessarily has to call the done function. If not, your queue won't process properly. -Set the concurrency limit on an already-running or a idle instance. +```typescript +import TaskRunner from "concurrent-tasks"; -```javascript -setConcurrency(concurrency: Number) -``` +const runner = new TaskRunner(); -### isBusy +function generateTasks() { + const tasks = []; + let count = 1000; + while (count) { + tasks.push((done) => { + setTimeout(() => { + done(); + }, Math.random() * 1000); + }); + count--; + } + return tasks; +} -Get the current state of the instance (idle or busy). +runner.addMultiple(generateTasks()); -```javascript -isBusy(); +runner.start(); ``` -# 💪🏼 Powered by Concurrent Tasks - -If you'd like to showcase any: - -- Website -- Package -- Framework -- API - -That's been powered by **Concurrent Tasks**, you can get in touch on [Twitter](https://twitter.com/tueieo) or just use [#poweredByConcurrentTasks](https://twitter.com/search?f=tweets&q=%23poweredByConcurrentTasks&src=typd) and it'll be featured here! - -# 👩🏻‍💻 Contributing - -We ❤️ contributions! We are looking for people who echo our sentiments and share the same idea about **Concurrent Tasks**. Check out the [contributing guidelines](https://github.com/samrith-s/concurrent-tasks/blob/master/CONTRIBUTING.md). - -# 🧐 Issues - -For any issues or queries you might have about the table, please feel free to create one in the [issues section](https://github.com/samrith-s/concurrent-tasks/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). - -# 🗺 Roadmap - -- ✅ Custom concurrency. -- ✅ Events for task addition, idle state change, `done` callback firing. -- ✅ Programmatic and automatic start. -- ✅ Different kinds of addition and removal. -- ❌ Priority value for each task. -- ❌ Storing tasks as a map of priorities. -- ❌ Adding/removing tasks to/from an existing priority. -- ❌ Adding/removing multiple tasks to/from an existing priority. -- ❌ Adding tasks to a new priority. -- ❌ Adding multiple tasks to a new priority. -- ❌ Removal of a priority. - -# 🔑 License - -This project is under the [MIT License](https://opensource.org/licenses/MIT). You can checkout the project's [license](https://github.com/samrith-s/concurrent-tasks/blob/master/LICENSE) for more info. - -Copyright © 2018. - [website]: https://concurrent-tasks.js.org -[icon]: https://raw.githubusercontent.com/samrith-s/concurrent-tasks/master/icons/icon-x64.png [size]: https://bundlephobia.com/result?p=concurrent-tasks [size_img]: https://badgen.net/bundlephobia/minzip/concurrent-tasks [npm_package]: https://www.npmjs.com/package/concurrent-tasks diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 3185456..7233d1f 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -46,7 +46,7 @@ import { Card, CardGrid, Tabs, TabItem } from "@astrojs/starlight/components"; CT contains **ZERO** runtime dependencies. - A minified and gzipped size of **1.6Kb**, making it super lightweight even + A minified and gzipped size of **2.7kB**, making it super lightweight even in high-latency scenarios. diff --git a/docs/src/content/docs/introduction/done-callback.mdx b/docs/src/content/docs/introduction/done-callback.mdx index e074c87..3005c07 100644 --- a/docs/src/content/docs/introduction/done-callback.mdx +++ b/docs/src/content/docs/introduction/done-callback.mdx @@ -9,8 +9,6 @@ What is the `done` callback and why is it important? ## Problem -In JavaScript, it gets very difficult for tasks to talk to each other. A lot of times, we need to maintain a map of running tasks and call a function which will update the value and call the next task. - Concurrent Tasks is a JavaScript module, which runs multiple tasks concurrently until all the tasks are complete. It needs a way to figure out when a particular task has been completed. ## Solution diff --git a/docs/src/content/docs/introduction/index.mdx b/docs/src/content/docs/introduction/index.mdx index ac366fc..64ecf2c 100644 --- a/docs/src/content/docs/introduction/index.mdx +++ b/docs/src/content/docs/introduction/index.mdx @@ -18,7 +18,7 @@ Concurrent Tasks aims to solve this by providing a simplistic queue. The queue n ## What can I use it with? -The minimalism of Concurrent Tasks makes it an easy-to-use solution across any framework or flavour of JavaScript. It has **ZERO dependencies** and can be used virtually in any scenario. With a **minified and gzipped size of 1.6kB**, it is the ultimate lightweight tool for your concurrency needs. +The minimalism of Concurrent Tasks makes it an easy-to-use solution across any framework or flavour of JavaScript. It has **ZERO dependencies** and can be used virtually in any scenario. With a **minified and gzipped size of 2.7kB**, it is the ultimate lightweight tool for your concurrency needs. - [x] Vanilla JavaScript - [x] Frontend Frameworks (React, Vue, Angular, etc)