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",
@@ -2120,6 +2148,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
@@ -8433,6 +8454,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[];
 
@@ -74,6 +80,9 @@ export const componentQrl: <PROPS extends Record<any, any>>(componentQrl: QRL<On
 // @public (undocumented)
 export type ComputedFn<T> = () => T;
 
+// @public (undocumented)
+export type ComputedReturnType<T> = T extends Promise<infer T> ? ReadonlySignal<T> : ReadonlySignal<T>;
+
 // @public
 export interface ComputedSignal<T> extends ReadonlySignal<T> {
     force(): void;
@@ -243,9 +252,6 @@ class DomContainer extends _SharedContainer implements ClientContainer {
 export { DomContainer }
 export { DomContainer as _DomContainer }
 
-// @internal (undocumented)
-export const _dumpState: (state: unknown[], color?: boolean, prefix?: string, limit?: number | null) => string;
-
 // @internal (undocumented)
 export const _EFFECT_BACK_REF: unique symbol;
 
@@ -551,11 +557,6 @@ export const PrefetchServiceWorker: (opts: {
     nonce?: string;
 }) => JSXOutput;
 
-// Warning: (ae-forgotten-export) The symbol "DeserializeContainer" needs to be exported by the entry point index.d.ts
-//
-// @internal
-export function _preprocessState(data: unknown[], container: DeserializeContainer): void;
-
 // @public
 export type PropFunction<T> = QRL<T>;
 
@@ -1621,12 +1622,20 @@ export const untrack: <T>(fn: () => T) => T;
 export const unwrapStore: <T>(value: T) => T;
 
 // @public
-export const useComputed$: <T>(qrl: ComputedFn<T>) => T extends Promise<any> ? never : ReadonlySignal<T>;
+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>;
 
 // Warning: (ae-internal-missing-underscore) The name "useComputedQrl" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal (undocumented)
-export const useComputedQrl: <T>(qrl: QRL<ComputedFn<T>>) => T extends Promise<any> ? never : ReadonlySignal<T>;
+export const useComputedQrl: <T>(qrl: QRL<ComputedFn<T>>) => ComputedReturnType<T>;
 
 // @public
 export const useConstant: <T>(value: (() => T) | T) => T;
@@ -1779,9 +1788,6 @@ export type VisibleTaskStrategy = 'intersection-observer' | 'document-ready' | '
 // @internal (undocumented)
 export type _VNode = _ElementVNode | _TextVNode | _VirtualVNode;
 
-// @internal (undocumented)
-export function _vnode_toString(this: _VNode | null, depth?: number, offset?: string, materialize?: boolean, siblings?: boolean, colorize?: boolean): string;
-
 // @internal
 export const enum _VNodeFlags {
     // (undocumented)

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>
+      </>
+    );
+  });
+});