From 101b10f941f875ca453edc599fe71ecce44ebdd9 Mon Sep 17 00:00:00 2001
From: Dor Shtaif <dorshtaif@gmail.com>
Date: Thu, 13 Feb 2025 12:10:09 +0200
Subject: [PATCH] add explanations and demonstrations for canceling jobs
 mid-operation into readme

---
 README.md | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 673b96a..3ad7833 100644
--- a/README.md
+++ b/README.md
@@ -191,7 +191,7 @@ q({
 
 #### `signal`:
 
-An optional [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for de-queing a pending job(s) that hasn't started yet. When aborted by the user, the promise from the job's queueing will immediately reject with the abort [reason](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/reason) as an error value. *(default: `undefined`)*
+An optional [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for de-queing a pending job that hasn't started yet ([what if the job had already started?](#aborting-a-job-that-had-already-started)). When aborted by the user, the promise from the job's queueing will immediately reject with the abort [reason](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/reason) as an error value. *(default: `undefined`)*
 
 ```ts
 const q = new Qyu({ concurrency: 1 });
@@ -212,6 +212,50 @@ abortCtl.abort(); // aborting the second job
 await promise; // now `promise` will reject with the default "AbortError" error (or optionally a custom error if was provided in `abortCtl.abort(...)`)
 ```
 
+<span id="aborting-a-job-that-had-already-started">Aborting a job that had may or may not have already kicked off is up to you - you just need to set it up to support it.</span>
+
+For example, if your job wraps a usage of an API that itself happens to support cancellation with `AbortSignal` as well, e.g [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) - then in such case you could simply pass the same `AbortSignal` you provide to Qyu while queueing the job ___also___ directly to that API inside the job function. Let's see this illustrated:
+
+```ts
+const q = new Qyu({ concurrency: myConcurrency });
+
+const abortCtl = new AbortController();
+
+q({
+  fn: async () => {
+    await fetch('https://...', { signal: abortCtl.signal });
+    // ...
+  },
+  signal: abortCtl.signal
+});
+
+// later...
+
+abortCtl.abort(); // Aborts the job, dequeuing it if still pending or canceling it mid-operation
+```
+
+In other cases, utilize `AbortSignal` being a generic API connecting it manually to any other available mechanism of stopping or cancelling your asynchronous job function _(refer to [`AbortSignal`'s API](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) or [`AbortController`'s API](oller) as needed)_.
+
+```ts
+const q = new Qyu({ concurrency: myConcurrency });
+
+const abortCtl = new AbortController();
+
+q({
+  fn: async () => {
+    abortCtl.signal.addEventListener('abort', () => {
+      cancelDoingMyHomework();
+    });
+    await doMyHomework();
+  },
+  signal: abortCtl.signal
+});
+
+// later...
+
+abortCtl.abort(); // Aborts the job, dequeuing it if still pending or canceling it mid-operation
+```
+
 # API
 
 ### instance(`jobs`)