feat: implement useAsyncComputed$

Author: Varixo

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

@@ -220,6 +220,34 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/shared/qrl/qrl.public.ts",
       "mdFile": "core._.md"
     },
+    {
+      "name": "AsyncComputedFn",
+      "id": "asynccomputedfn",
+      "hierarchy": [
+        {
+          "name": "AsyncComputedFn",
+          "id": "asynccomputedfn"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type AsyncComputedFn<T> = (ctx: TaskCtx) => Promise<T>;\n```\n**References:** [TaskCtx](#taskctx)",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts",
+      "mdFile": "core.asynccomputedfn.md"
+    },
+    {
+      "name": "AsyncComputedReturnType",
+      "id": "asynccomputedreturntype",
+      "hierarchy": [
+        {
+          "name": "AsyncComputedReturnType",
+          "id": "asynccomputedreturntype"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type AsyncComputedReturnType<T> = T extends Promise<infer T> ? ReadonlySignal<T> : ReadonlySignal<T>;\n```\n**References:** [ReadonlySignal](#readonlysignal)",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts",
+      "mdFile": "core.asynccomputedreturntype.md"
+    },
     {
       "name": "cache",
       "id": "resourcectx-cache",
@@ -2134,6 +2162,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/impl/store.ts",
       "mdFile": "core.unwrapstore.md"
     },
+    {
+      "name": "useAsyncComputed$",
+      "id": "useasynccomputed_",
+      "hierarchy": [
+        {
+          "name": "useAsyncComputed$",
+          "id": "useasynccomputed_"
+        }
+      ],
+      "kind": "Function",
+      "content": "Creates a computed signal which is calculated from the given function. 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\nThe function must be synchronous and must not have any side effects.\n\n\n```typescript\nuseAsyncComputed$: <T>(qrl: AsyncComputedFn<T>) => AsyncComputedReturnType<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[AsyncComputedFn](#asynccomputedfn)<!-- -->&lt;T&gt;\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\n[AsyncComputedReturnType](#asynccomputedreturntype)<!-- -->&lt;T&gt;",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts",
+      "mdFile": "core.useasynccomputed_.md"
+    },
     {
       "name": "useComputed$",
       "id": "usecomputed_",

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

@@ -119,6 +119,27 @@ 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)
 
+## AsyncComputedFn
+
+```typescript
+export type AsyncComputedFn<T> = (ctx: TaskCtx) => Promise<T>;
+```
+
+**References:** [TaskCtx](#taskctx)
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts)
+
+## AsyncComputedReturnType
+
+```typescript
+export type AsyncComputedReturnType<T> =
+  T extends Promise<infer T> ? ReadonlySignal<T> : ReadonlySignal<T>;
+```
+
+**References:** [ReadonlySignal](#readonlysignal)
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts)
+
 ## cache
 
 ```typescript
@@ -8444,6 +8465,47 @@ T
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/impl/store.ts)
 
+## useAsyncComputed$
+
+Creates a computed signal which is calculated from the given function. 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.
+
+The function must be synchronous and must not have any side effects.
+
+```typescript
+useAsyncComputed$: <T>(qrl: AsyncComputedFn<T>) => AsyncComputedReturnType<T>;
+```
+
+<table><thead><tr><th>
+
+Parameter
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody><tr><td>
+
+qrl
+
+</td><td>
+
+[AsyncComputedFn](#asynccomputedfn)&lt;T&gt;
+
+</td><td>
+
+</td></tr>
+</tbody></table>
+**Returns:**
+
+[AsyncComputedReturnType](#asynccomputedreturntype)&lt;T&gt;
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts)
+
 ## useComputed$
 
 Creates a computed signal which is calculated from the given function. 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.

packages/qwik/public.d.ts

@@ -56,6 +56,7 @@ export {
   TaskCtx,
   // TODO do we really want to export this?
   untrack,
+  useAsyncComputed$,
   useComputed$,
   useConstant,
   useContext,

packages/qwik/src/core/index.ts

@@ -133,6 +133,8 @@ export { useTaskQrl } from './use/use-task';
 export { useTask$ } from './use/use-task-dollar';
 export { useVisibleTask$ } from './use/use-visible-task-dollar';
 export { useComputed$ } from './use/use-computed';
+export type { AsyncComputedFn, AsyncComputedReturnType } from './use/use-async-computed';
+export { useAsyncComputedQrl, useAsyncComputed$ } from './use/use-async-computed';
 export { useErrorBoundary } from './use/use-error-boundary';
 export type { ErrorBoundaryStore } from './shared/error/error-handling';
 export {

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

@@ -16,6 +16,12 @@ import { ValueOrPromise as ValueOrPromise_2 } from '..';
 // @public
 export const $: <T>(expression: T) => QRL<T>;
 
+// @public (undocumented)
+export type AsyncComputedFn<T> = (ctx: TaskCtx) => Promise<T>;
+
+// @public (undocumented)
+export type AsyncComputedReturnType<T> = T extends Promise<infer T> ? ReadonlySignal<T> : ReadonlySignal<T>;
+
 // @public
 export type ClassList = string | undefined | null | false | Record<string, boolean | string | number | null | undefined> | ClassList[];
 
@@ -1615,6 +1621,14 @@ export const untrack: <T>(fn: () => T) => T;
 // @public
 export const unwrapStore: <T>(value: T) => T;
 
+// @public
+export const useAsyncComputed$: <T>(qrl: AsyncComputedFn<T>) => AsyncComputedReturnType<T>;
+
+// Warning: (ae-internal-missing-underscore) The name "useAsyncComputedQrl" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal (undocumented)
+export const useAsyncComputedQrl: <T>(qrl: QRL<AsyncComputedFn<T>>) => AsyncComputedReturnType<T>;
+
 // @public
 export const useComputed$: <T>(qrl: ComputedFn<T>) => ComputedReturnType<T>;
 

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

@@ -97,6 +97,8 @@ export const triggerEffects = (
         let choreType = ChoreType.TASK;
         if (consumer.$flags$ & TaskFlags.VISIBLE_TASK) {
           choreType = ChoreType.VISIBLE;
+        } else if (consumer.$flags$ & TaskFlags.ASYNC_COMPUTED) {
+          choreType = ChoreType.ASYNC_COMPUTED;
         }
         container.$scheduler$(choreType, consumer);
       } else if (consumer instanceof SignalImpl) {

packages/qwik/src/core/shared/scheduler.ts

@@ -122,6 +122,7 @@ import type { ValueOrPromise } from './utils/types';
 import type { NodePropPayload } from '../reactive-primitives/subscription-data';
 import type { ComputedSignalImpl } from '../reactive-primitives/impl/computed-signal-impl';
 import type { WrappedSignalImpl } from '../reactive-primitives/impl/wrapped-signal-impl';
+import { runAsyncComputed } from '../use/use-async-computed';
 
 // Turn this on to get debug output of what the scheduler is doing.
 const DEBUG: boolean = false;
@@ -186,7 +187,10 @@ export const createScheduler = (
     host: HostElement | null,
     target: Signal
   ): ValueOrPromise<void>;
-  function schedule(type: ChoreType.TASK | ChoreType.VISIBLE, task: Task): ValueOrPromise<void>;
+  function schedule(
+    type: ChoreType.TASK | ChoreType.VISIBLE | ChoreType.ASYNC_COMPUTED,
+    task: Task
+  ): ValueOrPromise<void>;
   function schedule(
     type: ChoreType.RUN_QRL,
     host: HostElement,
@@ -225,7 +229,10 @@ export const createScheduler = (
     const runLater: boolean =
       type !== ChoreType.WAIT_FOR_ALL && !isComponentSsr && type !== ChoreType.RUN_QRL;
     const isTask =
-      type === ChoreType.TASK || type === ChoreType.VISIBLE || type === ChoreType.CLEANUP_VISIBLE;
+      type === ChoreType.TASK ||
+      type === ChoreType.VISIBLE ||
+      type === ChoreType.ASYNC_COMPUTED ||
+      type === ChoreType.CLEANUP_VISIBLE;
     const isClientOnly =
       type === ChoreType.JOURNAL_FLUSH ||
       type === ChoreType.NODE_DIFF ||
@@ -400,6 +407,7 @@ export const createScheduler = (
           break;
         case ChoreType.TASK:
         case ChoreType.VISIBLE:
+        case ChoreType.ASYNC_COMPUTED:
           {
             const payload = chore.$payload$ as DescriptorBase;
             if (payload.$flags$ & TaskFlags.RESOURCE) {
@@ -411,6 +419,8 @@ export const createScheduler = (
               // Awaiting on the client also causes a deadlock.
               // In any case, the resource will never throw.
               returnValue = isServer ? result : null;
+            } else if (chore.$type$ === ChoreType.ASYNC_COMPUTED) {
+              returnValue = runAsyncComputed(payload as Task<TaskFn, TaskFn>, container, host);
             } else {
               returnValue = runTask(payload as Task<TaskFn, TaskFn>, container, host);
             }

packages/qwik/src/core/shared/util-chore-type.ts

@@ -7,6 +7,7 @@ export const enum ChoreType {
   /** Ensure that the QRL promise is resolved before processing next chores in the queue */
   QRL_RESOLVE /* ********************** */ = 1,
   RUN_QRL,
+  ASYNC_COMPUTED,
   TASK,
   NODE_DIFF,
   NODE_PROP,

packages/qwik/src/core/shared/utils/markers.ts

@@ -56,7 +56,7 @@ export const SVG_NS = 'http://www.w3.org/2000/svg';
 export const MATH_NS = 'http://www.w3.org/1998/Math/MathML';
 
 export const ResourceEvent = 'qResource';
-export const ComputedEvent = 'qComputed';
+export const AsyncComputedEvent = 'qAsyncComputed';
 export const RenderEvent = 'qRender';
 export const TaskEvent = 'qTask';
 

packages/qwik/src/core/tests/use-async-computed.spec.tsx

@@ -0,0 +1,70 @@
+import { Fragment as Signal, component$, useSignal } from '@qwik.dev/core';
+import { domRender, ssrRenderToDom, trigger } from '@qwik.dev/core/testing';
+import { describe, expect, it } from 'vitest';
+import { useAsyncComputed$ } from '../use/use-async-computed';
+
+const debug = false; //true;
+Error.stackTraceLimit = 100;
+
+describe.each([
+  { render: ssrRenderToDom }, //
+  { render: domRender }, //
+])('$render.name: useComputed', ({ render }) => {
+  it('should resolve promise in computed result', async () => {
+    const Counter = component$(() => {
+      const count = useSignal(1);
+      const doubleCount = useAsyncComputed$(({ track }) =>
+        Promise.resolve(track(() => count.value * 2))
+      );
+      return <button onClick$={() => count.value++}>{doubleCount.value}</button>;
+    });
+    const { vNode, container } = await render(<Counter />, { debug });
+    expect(vNode).toMatchVDOM(
+      <>
+        <button>
+          <Signal ssr-required>{'2'}</Signal>
+        </button>
+      </>
+    );
+    await trigger(container.element, 'button', 'click');
+    expect(vNode).toMatchVDOM(
+      <>
+        <button>
+          <Signal ssr-required>{'4'}</Signal>
+        </button>
+      </>
+    );
+  });
+
+  it('should resolve delayed promise in computed result', async () => {
+    const Counter = component$(() => {
+      const count = useSignal(1);
+      const doubleCount = useAsyncComputed$(
+        ({ track }) =>
+          new Promise<number>((resolve) => {
+            setTimeout(() => {
+              resolve(track(() => count.value * 2));
+            });
+          })
+      );
+      return <button onClick$={() => count.value++}>{doubleCount.value}</button>;
+    });
+    const { vNode, container } = await render(<Counter />, { debug });
+
+    expect(vNode).toMatchVDOM(
+      <>
+        <button>
+          <Signal ssr-required>{'2'}</Signal>
+        </button>
+      </>
+    );
+    await trigger(container.element, 'button', 'click');
+    expect(vNode).toMatchVDOM(
+      <>
+        <button>
+          <Signal ssr-required>{'4'}</Signal>
+        </button>
+      </>
+    );
+  });
+});