{"id":41797425,"url":"https://github.com/schie/queue","last_synced_at":"2026-01-25T05:32:26.175Z","repository":{"id":329072293,"uuid":"1117993982","full_name":"schie/queue","owner":"schie","description":"A simple task queue implementation in TypeScript.","archived":false,"fork":false,"pushed_at":"2026-01-19T20:32:31.000Z","size":450,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-20T02:20:44.476Z","etag":null,"topics":["queue","typescript"],"latest_commit_sha":null,"homepage":"http://queue.schie.io/","language":"TypeScript","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/schie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-17T05:36:50.000Z","updated_at":"2026-01-19T20:32:18.000Z","dependencies_parsed_at":"2025-12-20T19:01:50.230Z","dependency_job_id":null,"html_url":"https://github.com/schie/queue","commit_stats":null,"previous_names":["schie/queue"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/schie/queue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schie%2Fqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schie%2Fqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schie%2Fqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schie%2Fqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schie","download_url":"https://codeload.github.com/schie/queue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schie%2Fqueue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28744429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T05:12:38.112Z","status":"ssl_error","status_checked_at":"2026-01-25T05:04:50.338Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["queue","typescript"],"created_at":"2026-01-25T05:32:25.457Z","updated_at":"2026-01-25T05:32:26.170Z","avatar_url":"https://github.com/schie.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @schie/queue\n\nA tiny, promise-based task queue that runs jobs sequentially with explicit pause/resume and cancellation controls. Designed to keep a single consumer in-order, surface errors deterministically, and make queue status observable for UI or orchestration hooks.\n\n## Features\n\n- ✅ Single runner, in-order task execution (no accidental parallelism)\n- ⏸️ Explicit pause/resume with backpressure-friendly blocking\n- 🛑 Cancellation that flushes pending work and blocks stale generations from changing state\n- 🚨 Optional `pauseOnError` flow that captures the last task error and waits for a resume signal\n- 🕹️ Status callbacks for wiring into logs, metrics, or UI (`Idle` → `Processing` → `Paused/Cancelled`)\n- 📦 Zero dependencies, ESM + CJS builds, typed with TypeScript\n\n## Installation\n\n```bash\nnpm install @schie/queue\n```\n\nRequires Node.js 20+.\n\n## Quick Start\n\n```typescript\nimport { Queue, QueueStatus } from '@schie/queue'\n\nconst queue = new Queue({\n  onStatusChange: (status) =\u003e console.log('status:', QueueStatus[status])\n})\n\nqueue.addTask(async () =\u003e {\n  await doWork('first')\n})\n\nqueue.addTask(async () =\u003e {\n  await doWork('second')\n})\n\n// Pause new work mid-flight\nqueue.pauseQueue()\n\nsetTimeout(() =\u003e {\n  // Clear any previous error and resume processing\n  queue.resumeQueue()\n}, 500)\n```\n\n### Handling errors with `pauseOnError`\n\n```typescript\nconst queue = new Queue({\n  onStatusChange: (status) =\u003e console.log('status:', QueueStatus[status]),\n  pauseOnError: true\n})\n\nqueue.addTask(async () =\u003e {\n  throw new Error('oops')\n})\n\nqueue.addTask(async () =\u003e doWork('after error')) // waits until resume\n\n// When a task fails:\n// - status flips to Paused\n// - lastTaskError is set\n// - processing waits until resumeQueue() is called\n\nif (queue.lastTaskError) {\n  console.error('last error:', queue.lastTaskError.message)\n  queue.clearLastError()\n  queue.resumeQueue()\n}\n```\n\n### Cancellation and auto-resurrection\n\n```typescript\nqueue.addTask(async () =\u003e doWork('maybe cancel me'))\nqueue.cancelQueue() // clears pending tasks and sets status Cancelled\n\n// Later, adding a task resurrects the queue into a fresh generation\nqueue.addTask(async () =\u003e doWork('fresh start')) // status returns to Idle → Processing\n```\n\n## API\n\n### `Queue` constructor\n\n```typescript\ntype QueueOptions = {\n  onStatusChange?: (status: QueueStatus) =\u003e void;\n  pauseOnError?: boolean;\n};\n\nnew Queue(options?: QueueOptions);\n```\n\n- `onStatusChange` fires only on real status transitions.\n- `pauseOnError` toggles whether task errors pause the queue and are surfaced via `lastTaskError` (defaults to `false`).\n\n### Methods\n\n- `addTask(task: () =\u003e Promise\u003cvoid\u003e, dedupeKey?: string)` — enqueue a task; if `dedupeKey` matches the last pending task key, skip enqueueing; auto-starts if idle and auto-resurrects after cancellation.\n- `pauseQueue()` — transition to `Paused` if currently processing.\n- `resumeQueue()` — clears `lastTaskError`, transitions back to `Processing`, and unblocks paused processing. Also restarts if idle with pending work.\n- `cancelQueue()` — set status to `Cancelled`, flush pending tasks, and invalidate any in-flight runner.\n- `clearQueue()` — remove pending tasks; leaves status `Idle` when not processing/paused/cancelled.\n- `clearLastError()` — reset `lastTaskError` without changing status.\n- `addNextTask(task: () =\u003e Promise\u003cvoid\u003e)` — enqueue a task to run before other pending tasks (after the current in-flight task); auto-starts if idle and auto-resurrects after cancellation.\n\n### Properties\n\n- `status: QueueStatus` — current lifecycle state (`Idle`, `Processing`, `Paused`, `Cancelled`).\n- `isProcessing | isPaused | isCancelled | isIdle` — boolean helpers.\n- `size: number` — pending task count.\n- `lastTaskError: Error | null` — most recent error when `pauseOnError` is enabled.\n\n### Invariants and behavior\n\n- Single runner: tasks execute sequentially; the queue never introduces parallelism.\n- Generation guard: cancellation increments an internal version so stale runners cannot revert status later.\n- Draining: when the queue empties (and not cancelled), status returns to `Idle`.\n- Pausing: while paused, processing blocks until `resumeQueue` is called.\n\n## Scripts and Testing\n\n- `npm test -- --watchman=false` — run the Jest suite with coverage (keep it at 100%).\n- `npm run build` — emit ESM/CJS builds and types.\n- `npm run lint` — lint the repo (plus lockfile validation).\n\n## Contributing\n\nPRs are welcome. Please:\n\n- Keep behavior changes aligned with the TypeScript source and this README.\n- Preserve the single-consumer, in-order contract and status integrity.\n- Add or update tests to maintain 100% coverage.\n- Use the provided `npm` scripts instead of bespoke commands.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschie%2Fqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschie%2Fqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschie%2Fqueue/lists"}