feat(core): pass invalidate info to async signals

Author: wmertens

.changeset/two-years-teach.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/core': minor
+---
+
+FEAT: `asyncSignal.invalidate(info: unknown)` allows passing `info` to the calculation function. This can for example be used to request cache busting while reloading.

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

@@ -261,7 +261,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "An AsyncSignal holds the result of the given async function. If the function uses `track()` to track reactive state, and that state changes, the AsyncSignal is recalculated, and if the result changed, all tasks which are tracking the AsyncSignal will be re-run and all subscribers (components, tasks etc) that read the AsyncSignal will be updated.\n\nIf the async function throws an error, the AsyncSignal will capture the error and set the `error` property. The error can be cleared by re-running the async function successfully.\n\nWhile the async function is running, the `.loading` property will be set to `true`<!-- -->. Once the function completes, `loading` will be set to `false`<!-- -->.\n\nIf the value has not yet been resolved, reading the AsyncSignal will throw a Promise, which will retry the component or task once the value resolves.\n\nIf the value has been resolved, but the async function is re-running, reading the AsyncSignal will subscribe to it and return the last resolved value until the new value is ready. As soon as the new value is ready, the subscribers will be updated.\n\nIf the async function threw an error, reading the `.value` will throw that same error. Read from `.error` to check if there was an error.\n\n\n```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\nerror\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\ninterval\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\nStaleness/poll interval in ms. Writable and immediately effective.\n\n- \\*\\*Positive\\*\\*: Poll — re-compute after this many ms when subscribers exist. - \\*\\*Negative\\*\\*: Stale-only — mark stale after `|interval|` ms, no auto-recompute. - \\*\\*`0`<!-- -->\\*\\*: No staleness tracking or polling.\n\n\n</td></tr>\n<tr><td>\n\nloading\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</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(reason)](#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>",
+      "content": "An AsyncSignal holds the result of the given async function. If the function uses `track()` to track reactive state, and that state changes, the AsyncSignal is recalculated, and if the result changed, all tasks which are tracking the AsyncSignal will be re-run and all subscribers (components, tasks etc) that read the AsyncSignal will be updated.\n\nIf the async function throws an error, the AsyncSignal will capture the error and set the `error` property. The error can be cleared by re-running the async function successfully.\n\nWhile the async function is running, the `.loading` property will be set to `true`<!-- -->. Once the function completes, `loading` will be set to `false`<!-- -->.\n\nIf the value has not yet been resolved, reading the AsyncSignal will throw a Promise, which will retry the component or task once the value resolves.\n\nIf the value has been resolved, but the async function is re-running, reading the AsyncSignal will subscribe to it and return the last resolved value until the new value is ready. As soon as the new value is ready, the subscribers will be updated.\n\nIf the async function threw an error, reading the `.value` will throw that same error. Read from `.error` to check if there was an error.\n\n\n```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\nerror\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\ninterval\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\nStaleness/poll interval in ms. Writable and immediately effective.\n\n- \\*\\*Positive\\*\\*: Poll — re-compute after this many ms when subscribers exist. - \\*\\*Negative\\*\\*: Stale-only — mark stale after `|interval|` ms, no auto-recompute. - \\*\\*`0`<!-- -->\\*\\*: No staleness tracking or polling.\n\n\n</td></tr>\n<tr><td>\n\nloading\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</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(reason)](#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[invalidate(info)](#asyncsignal-invalidate)\n\n\n</td><td>\n\nUse this to force recalculation. If you pass `info`<!-- -->, it will be provided to the calculation function.\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"
     },
@@ -421,7 +421,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "A computed signal is a signal which is calculated from other signals. When the signals change, the computed signal is recalculated, and if the result changed, all tasks which are tracking the signal will be re-run and all components that read the signal will be re-rendered.\n\n\n```typescript\nexport interface ComputedSignal<T> extends Signal<T> \n```\n**Extends:** [Signal](#signal)<!-- -->&lt;T&gt;\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[force()](#computedsignal-force)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[invalidate()](#computedsignal-invalidate)\n\n\n</td><td>\n\nUse this to force recalculation.\n\n\n</td></tr>\n</tbody></table>",
+      "content": "A computed signal is a signal which is calculated from other signals. When the signals change, the computed signal is recalculated, and if the result changed, all tasks which are tracking the signal will be re-run and all components that read the signal will be re-rendered.\n\n\n```typescript\nexport interface ComputedSignal<T> extends Signal<T> \n```\n**Extends:** [Signal](#signal)<!-- -->&lt;T&gt;\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[force()](#computedsignal-force)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\ninvalidate()\n\n\n</td><td>\n\nUse this to force recalculation.\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.computedsignal.md"
     },
@@ -879,20 +879,20 @@
     },
     {
       "name": "invalidate",
-      "id": "computedsignal-invalidate",
+      "id": "asyncsignal-invalidate",
       "hierarchy": [
         {
-          "name": "ComputedSignal",
-          "id": "computedsignal-invalidate"
+          "name": "AsyncSignal",
+          "id": "asyncsignal-invalidate"
         },
         {
           "name": "invalidate",
-          "id": "computedsignal-invalidate"
+          "id": "asyncsignal-invalidate"
         }
       ],
       "kind": "MethodSignature",
-      "content": "Use this to force recalculation.\n\n\n```typescript\ninvalidate(): void;\n```\n**Returns:**\n\nvoid",
-      "mdFile": "core.computedsignal.invalidate.md"
+      "content": "Use this to force recalculation. If you pass `info`<!-- -->, it will be provided to the calculation function.\n\n\n```typescript\ninvalidate(info?: unknown): void;\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\ninfo\n\n\n</td><td>\n\nunknown\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nvoid",
+      "mdFile": "core.asyncsignal.invalidate.md"
     },
     {
       "name": "isSignal",

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

@@ -288,6 +288,15 @@ Abort the current computation and run cleanups if needed.
 </td></tr>
 <tr><td>
 
+[invalidate(info)](#asyncsignal-invalidate)
+
+</td><td>
+
+Use this to force recalculation. If you pass `info`, it will be provided to the calculation function.
+
+</td></tr>
+<tr><td>
+
 [promise()](#asyncsignal-promise)
 
 </td><td>
@@ -783,7 +792,7 @@ Description
 </td></tr>
 <tr><td>
 
-[invalidate()](#computedsignal-invalidate)
+invalidate()
 
 </td><td>
 
@@ -2032,14 +2041,42 @@ interface IntrinsicElements extends LenientQwikElements
 
 **Extends:** LenientQwikElements
 
-<h2 id="computedsignal-invalidate">invalidate</h2>
+<h2 id="asyncsignal-invalidate">invalidate</h2>
 
-Use this to force recalculation.
+Use this to force recalculation. If you pass `info`, it will be provided to the calculation function.
 
 ```typescript
-invalidate(): void;
+invalidate(info?: unknown): void;
 ```
 
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+info
+
+</td><td>
+
+unknown
+
+</td><td>
+
+_(Optional)_
+
+</td></tr>
+</tbody></table>
+
 **Returns:**
 
 void

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

@@ -26,6 +26,7 @@ export interface AsyncSignal<T = unknown> extends ComputedSignal<T> {
     abort(reason?: any): void;
     error: Error | undefined;
     interval: number;
+    invalidate(info?: unknown): void;
     loading: boolean;
     promise(): Promise<void>;
 }

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

@@ -43,7 +43,11 @@ class AsyncJob<T> implements AsyncCtx<T> {
   $cleanups$: Parameters<AsyncCtx<T>['cleanup']>[0][] | undefined;
   $abortController$: AbortController | undefined;
 
-  constructor(readonly $signal$: AsyncSignalImpl<T>) {}
+  constructor(
+    readonly $signal$: AsyncSignalImpl<T>,
+    readonly info: unknown,
+    readonly $infoVersion$: number
+  ) {}
 
   get track(): AsyncCtx<T>['track'] {
     return (this.$track$ ||= trackFn(this.$signal$, this.$signal$.$container$));
@@ -97,6 +101,8 @@ export class AsyncSignalImpl<T>
   $concurrency$: number = 1;
   $interval$: number = 0;
   $timeoutMs$: number | undefined;
+  $info$: unknown = undefined;
+  $infoVersion$: number = 0;
   declare $pollTimeoutId$: ReturnType<typeof setTimeout> | undefined;
   declare $computationTimeoutId$: ReturnType<typeof setTimeout> | undefined;
 
@@ -265,9 +271,13 @@ export class AsyncSignalImpl<T>
   }
 
   /** Invalidates the signal, causing it to re-compute its value. */
-  override async invalidate() {
+  override async invalidate(info?: unknown) {
     this.$flags$ |= SignalFlags.INVALID;
     this.$clearNextPoll$();
+    if (arguments.length > 0) {
+      this.$info$ = info;
+      this.$infoVersion$++;
+    }
     if (this.$effects$?.size || this.$loadingEffects$?.size || this.$errorEffects$?.size) {
       // compute in next microtask
       await true;
@@ -339,7 +349,8 @@ export class AsyncSignalImpl<T>
     this.$flags$ &= ~SignalFlags.INVALID;
 
     // We put the actual computation in a separate method so we can easily retain the promise
-    const running = new AsyncJob(this);
+    const infoVersion = this.$infoVersion$;
+    const running = new AsyncJob(this, this.$info$, infoVersion);
     this.$current$ = running;
     this.$jobs$.push(running);
     running.$promise$ = this.$runComputation$(running);
@@ -393,6 +404,9 @@ export class AsyncSignalImpl<T>
 
     if (isCurrent()) {
       clearTimeout(this.$computationTimeoutId$);
+      if (running.$infoVersion$ === this.$infoVersion$) {
+        this.$info$ = undefined;
+      }
 
       if (this.$flags$ & SignalFlags.INVALID) {
         DEBUG && log('Computation finished but signal is invalid, re-running');

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

@@ -125,6 +125,7 @@ describe('signal types', () => {
     expectTypeOf(signal.untrackedValue).toEqualTypeOf<number>();
     expectTypeOf(signal.abort()).toEqualTypeOf<void>();
     expectTypeOf(signal.invalidate()).toEqualTypeOf<void>();
+    expectTypeOf(signal.invalidate('info')).toEqualTypeOf<void>();
   });
 });
 
@@ -333,6 +334,72 @@ describe('signal', () => {
         });
       });
 
+      it('should expose invalidate info to the next computation', async () => {
+        await withContainer(async () => {
+          const infos: unknown[] = [];
+          const signal = createAsync$(
+            async ({ info }) => {
+              infos.push(info);
+              return infos.length;
+            },
+            { initial: 0 }
+          ) as AsyncSignalImpl<number>;
+
+          effect$(() => signal.value);
+          await signal.promise();
+
+          signal.invalidate('refresh');
+          await signal.promise();
+
+          expect(infos).toEqual([undefined, 'refresh']);
+        });
+      });
+
+      it('should reset invalidate info after computation completes', async () => {
+        await withContainer(async () => {
+          const infos: unknown[] = [];
+          const signal = createAsync$(
+            async ({ info }) => {
+              infos.push(info);
+              return infos.length;
+            },
+            { initial: 0 }
+          ) as AsyncSignalImpl<number>;
+
+          effect$(() => signal.value);
+          await signal.promise();
+
+          signal.invalidate(true);
+          await signal.promise();
+          signal.invalidate();
+          await signal.promise();
+
+          expect(infos).toEqual([undefined, true, undefined]);
+        });
+      });
+
+      it('should use the latest invalidate info before recalculation starts', async () => {
+        await withContainer(async () => {
+          const infos: unknown[] = [];
+          const signal = createAsync$(
+            async ({ info }) => {
+              infos.push(info);
+              return infos.length;
+            },
+            { initial: 0 }
+          ) as AsyncSignalImpl<number>;
+
+          effect$(() => signal.value);
+          await signal.promise();
+
+          signal.invalidate('first');
+          signal.invalidate('second');
+          await signal.promise();
+
+          expect(infos).toEqual([undefined, 'second']);
+        });
+      });
+
       it('should poll', async () => {
         await withContainer(async () => {
           const interval = 1;

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

@@ -114,6 +114,11 @@ export interface AsyncSignal<T = unknown> extends ComputedSignal<T> {
   promise(): Promise<void>;
   /** Abort the current computation and run cleanups if needed. */
   abort(reason?: any): void;
+  /**
+   * Use this to force recalculation. If you pass `info`, it will be provided to the calculation
+   * function.
+   */
+  invalidate(info?: unknown): void;
 }
 
 /**

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

@@ -41,6 +41,8 @@ export type AsyncCtx<T = unknown> = {
   readonly abortSignal: AbortSignal;
   /** The result of the previous computation, if any */
   readonly previous: T | undefined;
+  /** Extra info passed to `invalidate(info)` for this computation, if any. */
+  readonly info: unknown;
 };
 export type AsyncQRL<T> = QRLInternal<AsyncFn<T>>;