feat(async): abort signal support

Author: wmertens

packages/docs/src/routes/api/qwik/api.json

@@ -220,6 +220,23 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/qrl/qrl.public.ts",
       "mdFile": "core._.md"
     },
+    {
+      "name": "abort",
+      "id": "asyncsignal-abort",
+      "hierarchy": [
+        {
+          "name": "AsyncSignal",
+          "id": "asyncsignal-abort"
+        },
+        {
+          "name": "abort",
+          "id": "asyncsignal-abort"
+        }
+      ],
+      "kind": "MethodSignature",
+      "content": "Abort the current computation and run cleanups if needed.\n\n\n```typescript\nabort(): void;\n```\n**Returns:**\n\nvoid",
+      "mdFile": "core.asyncsignal.abort.md"
+    },
     {
       "name": "AsyncFn",
       "id": "asyncfn",
@@ -244,7 +261,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface AsyncSignal<T = unknown> extends ComputedSignal<T> \n```\n**Extends:** [ComputedSignal](#computedsignal)<!-- -->&lt;T&gt;\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[error](#)\n\n\n</td><td>\n\n\n</td><td>\n\nError \\| undefined\n\n\n</td><td>\n\nThe error that occurred while computing the signal, if any. This will be cleared when the signal is successfully computed.\n\n\n</td></tr>\n<tr><td>\n\n[loading](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\nWhether the signal is currently loading. This will trigger lazy loading of the signal, so you can use it like this:\n\n```tsx\nsignal.loading ? <Loading /> : signal.error ? <Error /> : <Component\nvalue={signal.value} />\n```\n\n\n</td></tr>\n<tr><td>\n\n[pollMs](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\nPoll interval in ms. Writable and immediately effective when the signal has consumers. If set to `0`<!-- -->, polling stops.\n\n\n</td></tr>\n</tbody></table>\n\n\n<table><thead><tr><th>\n\nMethod\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[promise()](#asyncsignal-promise)\n\n\n</td><td>\n\nA promise that resolves when the value is computed or rejected.\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface AsyncSignal<T = unknown> extends ComputedSignal<T> \n```\n**Extends:** [ComputedSignal](#computedsignal)<!-- -->&lt;T&gt;\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[error](#)\n\n\n</td><td>\n\n\n</td><td>\n\nError \\| undefined\n\n\n</td><td>\n\nThe error that occurred while computing the signal, if any. This will be cleared when the signal is successfully computed.\n\n\n</td></tr>\n<tr><td>\n\n[loading](#)\n\n\n</td><td>\n\n\n</td><td>\n\nboolean\n\n\n</td><td>\n\nWhether the signal is currently loading. This will trigger lazy loading of the signal, so you can use it like this:\n\n```tsx\nsignal.loading ? <Loading /> : signal.error ? <Error /> : <Component\nvalue={signal.value} />\n```\n\n\n</td></tr>\n<tr><td>\n\n[pollMs](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\nPoll interval in ms. Writable and immediately effective when the signal has consumers. If set to `0`<!-- -->, polling stops.\n\n\n</td></tr>\n</tbody></table>\n\n\n<table><thead><tr><th>\n\nMethod\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[abort()](#asyncsignal-abort)\n\n\n</td><td>\n\nAbort the current computation and run cleanups if needed.\n\n\n</td></tr>\n<tr><td>\n\n[promise()](#asyncsignal-promise)\n\n\n</td><td>\n\nA promise that resolves when the value is computed or rejected.\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/signal.public.ts",
       "mdFile": "core.asyncsignal.md"
     },
@@ -446,7 +463,7 @@
         }
       ],
       "kind": "Function",
-      "content": "Create a signal holding a `.value` which is calculated from the given async function (QRL). The standalone version of `useAsync$`<!-- -->.\n\n\n```typescript\ncreateAsync$: <T>(qrl: () => Promise<T>, options?: AsyncSignalOptions<T>) => AsyncSignal<T>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nqrl\n\n\n</td><td>\n\n() =&gt; Promise&lt;T&gt;\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\noptions\n\n\n</td><td>\n\nAsyncSignalOptions&lt;T&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\n[AsyncSignal](#asyncsignal)<!-- -->&lt;T&gt;",
+      "content": "Create a signal holding a `.value` which is calculated from the given async function (QRL). The standalone version of `useAsync$`<!-- -->.\n\n\n```typescript\ncreateAsync$: <T>(qrl: (arg: AsyncCtx) => Promise<T>, options?: AsyncSignalOptions<T>) => AsyncSignal<T>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nqrl\n\n\n</td><td>\n\n(arg: AsyncCtx) =&gt; Promise&lt;T&gt;\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\noptions\n\n\n</td><td>\n\nAsyncSignalOptions&lt;T&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\n[AsyncSignal](#asyncsignal)<!-- -->&lt;T&gt;",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/signal.public.ts",
       "mdFile": "core.createasync_.md"
     },

packages/docs/src/routes/api/qwik/index.mdx

@@ -120,6 +120,18 @@ Expression which should be lazy loaded
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/qrl/qrl.public.ts)
 
+## abort
+
+Abort the current computation and run cleanups if needed.
+
+```typescript
+abort(): void;
+```
+
+**Returns:**
+
+void
+
 ## AsyncFn
 
 ```typescript
@@ -221,6 +233,15 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
+[abort()](#asyncsignal-abort)
+
+</td><td>
+
+Abort the current computation and run cleanups if needed.
+
+</td></tr>
+<tr><td>
+
 [promise()](#asyncsignal-promise)
 
 </td><td>
@@ -847,8 +868,10 @@ Description
 Create a signal holding a `.value` which is calculated from the given async function (QRL). The standalone version of `useAsync$`.
 
 ```typescript
-createAsync$: <T>(qrl: () => Promise<T>, options?: AsyncSignalOptions<T>) =>
-  AsyncSignal<T>;
+createAsync$: <T>(
+  qrl: (arg: AsyncCtx) => Promise<T>,
+  options?: AsyncSignalOptions<T>,
+) => AsyncSignal<T>;
 ```
 
 <table><thead><tr><th>
@@ -870,7 +893,7 @@ qrl
 
 </td><td>
 
-() =&gt; Promise&lt;T&gt;
+(arg: AsyncCtx) =&gt; Promise&lt;T&gt;
 
 </td><td>
 

packages/qwik/src/core/qwik.core.api.md

@@ -19,6 +19,7 @@ export type AsyncFn<T> = (ctx: AsyncCtx) => Promise<T>;
 
 // @public (undocumented)
 export interface AsyncSignal<T = unknown> extends ComputedSignal<T> {
+    abort(): void;
     error: Error | undefined;
     loading: boolean;
     pollMs: number;
@@ -193,7 +194,7 @@ export interface CorrectedToggleEvent extends Event {
 // Warning: (ae-forgotten-export) The symbol "AsyncSignalOptions" needs to be exported by the entry point index.d.ts
 //
 // @public
-export const createAsync$: <T>(qrl: () => Promise<T>, options?: AsyncSignalOptions<T>) => AsyncSignal<T>;
+export const createAsync$: <T>(qrl: (arg: AsyncCtx) => Promise<T>, options?: AsyncSignalOptions<T>) => AsyncSignal<T>;
 
 // Warning: (ae-forgotten-export) The symbol "AsyncSignalImpl" needs to be exported by the entry point index.d.ts
 // Warning: (ae-internal-missing-underscore) The name "createAsyncQrl" should be prefixed with an underscore because the declaration is marked as @internal

packages/qwik/src/core/reactive-primitives/impl/async-signal-impl.ts

@@ -24,12 +24,6 @@ import { setupSignalValueAccess } from './signal-impl';
  *
  * - `eagerCleanup`: boolean - whether to run cleanups eagerly when there are no more subscribers, or
  *   to wait until the next computation/destroy.
- * - AbortOnInvalidate: boolean (default false) - whether to abort the current computation when the
- *   signal is invalidated. This requires the compute function to accept an AbortSignal and handle
- *   it properly, so it's opt-in. When true, if the signal is invalidated while a computation is
- *   running, the current computation will be aborted (if possible) and a new computation will be
- *   started according to the concurrency limit.
- * - Abort: the callback receives an AbortSignal which is aborted when the signal is invalidated. The
  */
 
 const DEBUG = false;
@@ -45,13 +39,18 @@ class AsyncJob<T> implements AsyncCtx {
   $canWrite$: boolean = true;
   $track$: AsyncCtx['track'] | undefined;
   $cleanups$: Parameters<AsyncCtx['cleanup']>[0][] | undefined;
+  $abortController$: AbortController | undefined;
 
   constructor(readonly $signal$: AsyncSignalImpl<T>) {}
 
   get track(): AsyncCtx['track'] {
     return (this.$track$ ||= trackFn(this.$signal$, this.$signal$.$container$));
   }
 
+  get abortSignal(): AbortSignal {
+    return (this.$abortController$ ||= new AbortController()).signal;
+  }
+
   cleanup(callback: () => void) {
     if (typeof callback === 'function') {
       (this.$cleanups$ ||= []).push(callback);
@@ -172,6 +171,13 @@ export class AsyncSignalImpl<T> extends ComputedSignalImpl<T, AsyncQRL<T>> imple
     }
   }
 
+  /** Abort the current computation and run cleanups if needed. */
+  abort(): void {
+    if (this.$current$) {
+      this.$requestCleanups$(this.$current$);
+    }
+  }
+
   /** Returns a promise resolves when the signal finished computing. */
   async promise(): Promise<void> {
     this.$computeIfNeeded$();
@@ -305,6 +311,7 @@ export class AsyncSignalImpl<T> extends ComputedSignalImpl<T, AsyncQRL<T>> imple
     }
     DEBUG && log('Requesting cleanups for job', job);
     job.$cleanupRequested$ = true;
+    job.$abortController$?.abort();
     job.$promise$ = Promise.resolve(job.$promise$).then(
       () => (job.$promise$ = this.$runCleanups$(job))
     );

packages/qwik/src/core/reactive-primitives/impl/signal.unit.tsx

@@ -390,6 +390,179 @@ describe('signal', () => {
         });
       });
 
+      it('should provide abortSignal that is aborted on cleanup', async () => {
+        await withContainer(async () => {
+          const dep = createSignal(0);
+          const ref = { aborted: false };
+
+          const signal = (await retryOnPromise(() =>
+            createAsyncQrl(
+              $(async ({ track, abortSignal }: AsyncCtx) => {
+                track(() => dep.value);
+                abortSignal.addEventListener('abort', () => {
+                  ref.aborted = true;
+                });
+                return dep.value;
+              })
+            )
+          )) as AsyncSignalImpl<number>;
+
+          await retryOnPromise(() => {
+            effect$(() => signal.value);
+          });
+
+          expect(signal.value).toBe(0);
+          expect(ref.aborted).toBe(false);
+
+          // Trigger re-computation which should run cleanup and abort
+          dep.value = 1;
+          await signal.promise();
+
+          expect(signal.value).toBe(1);
+          expect(ref.aborted).toBe(true);
+        });
+      });
+
+      it('should lazily create abortController only when accessed', async () => {
+        await withContainer(async () => {
+          const signal = (await retryOnPromise(() =>
+            createAsyncQrl(
+              $(async () => {
+                return 42;
+              })
+            )
+          )) as AsyncSignalImpl<number>;
+
+          await retryOnPromise(() => {
+            effect$(() => signal.value);
+          });
+
+          // AbortController should not be created if abortSignal is never accessed
+          const job = signal.$current$;
+          expect(job).toBeTruthy();
+          expect(job?.$abortController$).toBeUndefined();
+        });
+      });
+
+      it('should create abortController when abortSignal is accessed', async () => {
+        await withContainer(async () => {
+          const ref = { capturedSignal: undefined as AbortSignal | undefined };
+
+          const signal = (await retryOnPromise(() =>
+            createAsyncQrl(
+              $(async ({ abortSignal }: AsyncCtx) => {
+                ref.capturedSignal = abortSignal;
+                return 42;
+              })
+            )
+          )) as AsyncSignalImpl<number>;
+
+          await retryOnPromise(() => {
+            effect$(() => signal.value);
+          });
+
+          // AbortController should be created when abortSignal is accessed
+          const job = signal.$current$;
+          expect(job).toBeTruthy();
+          expect(job?.$abortController$).toBeInstanceOf(AbortController);
+          expect(ref.capturedSignal).toBeInstanceOf(AbortSignal);
+          expect(ref.capturedSignal?.aborted).toBe(false);
+        });
+      });
+
+      it('should abort current computation via signal.abort()', async () => {
+        await withContainer(async () => {
+          const ref = {
+            aborted: false,
+            resolve: undefined as ((value: number) => void) | undefined,
+          };
+
+          const signal = createAsync$(
+            async ({ abortSignal }) => {
+              abortSignal.addEventListener('abort', () => {
+                ref.aborted = true;
+              });
+              return new Promise<number>((resolve) => {
+                ref.resolve = resolve;
+              });
+            },
+            { initial: 0 }
+          ) as AsyncSignalImpl<number>;
+
+          effect$(() => signal.value);
+
+          await new Promise((resolve) => setTimeout(resolve, 10));
+          expect(ref.resolve).toBeDefined();
+
+          signal.abort();
+
+          expect(ref.aborted).toBe(true);
+
+          ref.resolve?.(1);
+          await delay(0);
+        });
+      });
+
+      it('should abort immediately in $requestCleanups$ before waiting for task promise', async () => {
+        await withContainer(async () => {
+          const ref = {
+            abortedBeforeTaskComplete: false,
+            taskResolve: undefined as ((value: number) => void) | undefined,
+          };
+
+          const signal = createAsync$(async ({ abortSignal }) => {
+            // Listen for abort
+            abortSignal.addEventListener('abort', () => {
+              // Check if task is still running (taskResolve exists)
+              if (ref.taskResolve) {
+                ref.abortedBeforeTaskComplete = true;
+              }
+            });
+
+            // Create a long-running task
+            return new Promise<number>((resolve) => {
+              ref.taskResolve = resolve;
+            });
+          }) as AsyncSignalImpl<number>;
+          // Subscribe with initial value to avoid promise throw
+          const signal2 = (await retryOnPromise(() =>
+            createAsync$(async () => 0, { initial: 0 })
+          )) as AsyncSignalImpl<number>;
+
+          effect$(() => {
+            // Read signal2 to establish effect without throwing
+            return signal2.value;
+          });
+
+          // Manually trigger computation for signal
+          signal.$computeIfNeeded$();
+
+          // Wait for task to start using a simple timeout
+          await new Promise((resolve) => setTimeout(resolve, 10));
+
+          // Verify task is running
+          expect(ref.taskResolve).toBeDefined();
+
+          // Request cleanup while task is still running
+          const job = signal.$current$;
+          expect(job).toBeTruthy();
+          if (job) {
+            signal.$requestCleanups$(job);
+          }
+
+          // Abort should be called immediately, before task completes
+          expect(ref.abortedBeforeTaskComplete).toBe(true);
+
+          // Clean up by resolving the task
+          if (ref.taskResolve) {
+            ref.taskResolve(99);
+          }
+
+          // Wait for cleanup to complete
+          await delay(10);
+        });
+      });
+
       it('should allow concurrent computations and apply newest completed value', async () => {
         await withContainer(async () => {
           const ref = {

packages/qwik/src/core/reactive-primitives/signal.public.ts

@@ -1,5 +1,5 @@
 import { implicit$FirstArg } from '../shared/qrl/implicit_dollar';
-import type { AsyncSignalOptions, ComputedOptions, SerializerArg } from './types';
+import type { AsyncCtx, AsyncSignalOptions, ComputedOptions, SerializerArg } from './types';
 import {
   createSignal as _createSignal,
   createComputedSignal as createComputedQrl,
@@ -38,6 +38,8 @@ export interface AsyncSignal<T = unknown> extends ComputedSignal<T> {
   pollMs: number;
   /** A promise that resolves when the value is computed or rejected. */
   promise(): Promise<void>;
+  /** Abort the current computation and run cleanups if needed. */
+  abort(): void;
 }
 
 /**
@@ -123,7 +125,7 @@ export { createComputedQrl };
  * @public
  */
 export const createAsync$: <T>(
-  qrl: () => Promise<T>,
+  qrl: (arg: AsyncCtx) => Promise<T>,
   options?: AsyncSignalOptions<T>
 ) => AsyncSignal<T> = /*#__PURE__*/ implicit$FirstArg(createAsyncQrl as any);
 export { createAsyncQrl };

packages/qwik/src/core/reactive-primitives/types.ts

@@ -37,6 +37,7 @@ export type ComputeQRL<T> = QRLInternal<ComputedFn<T>>;
 export type AsyncCtx = {
   track: Tracker;
   cleanup: (callback: () => void | Promise<void>) => void;
+  abortSignal: AbortSignal;
 };
 export type AsyncQRL<T> = QRLInternal<AsyncFn<T>>;