{"id":23773522,"url":"https://github.com/beenotung/fair-task-pool","last_synced_at":"2025-06-11T14:38:42.328Z","repository":{"id":240520337,"uuid":"802814160","full_name":"beenotung/fair-task-pool","owner":"beenotung","description":"Fairly schedule async tasks and prevent any since user/subject from monopolizing the system resources.","archived":false,"fork":false,"pushed_at":"2024-06-11T21:00:50.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-02T07:40:40.794Z","etag":null,"topics":["async","concurrent","fair-scheduling","per-user-queue","queue","rate-limiting","task-queue","typescript-library"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/fair-task-pool","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beenotung.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-19T10:48:58.000Z","updated_at":"2024-06-11T21:00:54.000Z","dependencies_parsed_at":"2024-05-19T14:29:45.818Z","dependency_job_id":"edf76e53-2430-4c69-8ba7-d060f337c170","html_url":"https://github.com/beenotung/fair-task-pool","commit_stats":null,"previous_names":["beenotung/fair-task-pool"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Ffair-task-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Ffair-task-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Ffair-task-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Ffair-task-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beenotung","download_url":"https://codeload.github.com/beenotung/fair-task-pool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beenotung%2Ffair-task-pool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259280882,"owners_count":22833471,"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","concurrent","fair-scheduling","per-user-queue","queue","rate-limiting","task-queue","typescript-library"],"created_at":"2025-01-01T05:41:02.605Z","updated_at":"2025-06-11T14:38:42.287Z","avatar_url":"https://github.com/beenotung.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fair-task-pool\n\nFairly schedule async tasks and prevent any since user/subject from monopolizing the system resources.\n\n[![npm Package Version](https://img.shields.io/npm/v/fair-task-pool)](https://www.npmjs.com/package/fair-task-pool)\n\n## Description\n\nThe \"fair-task-pool\" library provides a robust and efficient mechanism for managing task queues on a per-key basis. This library is especially useful in scenarios where you need to maintain separate queues for different users or tasks, ensuring fair resource allocation and preventing any single queue from monopolizing the task processing system. Each key (which can be a string or number) gets its own queue, and tasks are processed asynchronously in the order they are received.\n\n## Features\n\n- **Per-Key Queues**: Manage separate task queues for each unique key.\n- **Configurable Capacity**: Set a maximum number of pending tasks per queue, with an option for unlimited capacity.\n- **In-memory implementation**: Lightweight and not requiring external services.\n- **Automatic Queue Flushing**: Optionally, automatically delete queues when they become empty to free up resources.\n- **Error Handling**: The library ensures that task processing does not break due to task errors, and throw a specific error (`TaskQueueFullError`) when a task cannot be added to a full queue.\n\nThis library is ideal for applications requiring fair and efficient task management across multiple entities or resources.\n\n## Installation\n\n```bash\nnpm install fair-task-pool\n```\n\n## Usage Example\n\nSome of the details are omitted for simplicity, complete example see: [example/app.ts](./example/app.ts)\n\n```typescript\nimport { FairTaskPool } from 'fair-task-pool'\nimport { Request, Response, NextFunction } from 'express'\n\nlet MaxQueueSize = 20\n\nlet fairTaskPool = new FairTaskPool({\n  capacity: MaxQueueSize,\n  flushQueueWhenEmpty: true,\n})\n\nfunction createThread(req: Request, res: Response, next: NextFunction) {\n  let { user_id } = getJWTPayload(req)\n  res.setHeader('X-RateLimit-Limit', MaxQueueSize)\n  res.setHeader(\n    'X-RateLimit-Remaining',\n    MaxQueueSize - fairTaskPool.getPendingTaskCount(user_id),\n  )\n  fairTaskPool.enqueue(user_id, async () =\u003e {\n    try {\n      let input = createThreadParser.parse(req.body)\n      let result = await service.createThread({\n        user_id,\n        content: input.content,\n      })\n      res.json(result)\n    } catch (error) {\n      next(error)\n    }\n  })\n}\n\nfunction getThread(req: Request, res: Response, next: NextFunction) {\n  let queue_key: number | string\n  try {\n    let payload = getJWTPayload(req)\n    queue_key = payload.user_id\n  } catch {\n    // all non authenticated users share the same quota\n    queue_key = 'guest'\n  }\n  res.setHeader('X-RateLimit-Limit', MaxQueueSize)\n  res.setHeader(\n    'X-RateLimit-Remaining',\n    MaxQueueSize - fairTaskPool.getPendingTaskCount(queue_key),\n  )\n  fairTaskPool.enqueue(queue_key, async () =\u003e {\n    try {\n      let input = getThreadParser.parse(req.params)\n      let result = await service.getThread({ id: input.id })\n      res.json(result)\n    } catch (error) {\n      next(error)\n    }\n  })\n}\n```\n\n## Typescript Signature\n\nTypes for main class `FairTaskPool`:\n\n```typescript\n/** @description can be used for per-user task queue */\nexport class FairTaskPool {\n  constructor(options?: {\n    /**\n     * @description max number of pending tasks per-key\n     * @default unlimited if undefined\n     * */\n    capacity?: number\n\n    /** @default false */\n    flushQueueWhenEmpty?: boolean\n  })\n\n  /**\n   * @description dispatch the task to corresponding TaskQueue partitioned by the `key`\n   * @throws TaskQueueFullError when exceed\n   * */\n  enqueue\u003cT\u003e(key: Key, task: Task\u003cT\u003e): Promise\u003cT\u003e\n\n  getPendingTaskCount(key: Key): number\n\n  getQueueSize(): number\n}\n\ntype Key = string | number\n\n/** @description the task should not throw errors. */\nexport type Task\u003cT\u003e = () =\u003e T | Promise\u003cT\u003e\n\nexport class TaskQueueFullError extends Error {\n  capacity: number\n}\n```\n\nTypes for helper class `TaskQueue`:\n\n```typescript\nexport interface TaskQueue {\n  pendingTaskCount: number\n  onEmpty?: () =\u003e void\n  /** @throws TaskQueueFullError when exceed */\n  enqueue\u003cT\u003e(task: Task\u003cT\u003e): Promise\u003cT\u003e\n}\n\nexport class UnlimitedTaskQueue implements TaskQueue {\n  constructor(options: { onEmpty?: () =\u003e void })\n}\n\nexport class LimitedTaskQueue extends UnlimitedTaskQueue implements TaskQueue {\n  capacity: number\n  constructor(options: { onEmpty?: () =\u003e void; capacity: number })\n}\n```\n\n## License\n\nThis project is licensed with [BSD-2-Clause](./LICENSE)\n\nThis is free, libre, and open-source software. It comes down to four essential freedoms [[ref]](https://seirdy.one/2021/01/27/whatsapp-and-the-domestication-of-users.html#fnref:2):\n\n- The freedom to run the program as you wish, for any purpose\n- The freedom to study how the program works, and change it so it does your computing as you wish\n- The freedom to redistribute copies so you can help others\n- The freedom to distribute copies of your modified versions to others\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeenotung%2Ffair-task-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeenotung%2Ffair-task-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeenotung%2Ffair-task-pool/lists"}