Merge pull request #7589 from QwikDev/v2-use-async-computed

feat: implement useAsyncComputed$

Author: wmertens

.changeset/little-ways-deny.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/core': minor
+---
+
+feat: new hook - useAsyncComputed$ in replacement of useComputed$ with async operations

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

@@ -220,6 +220,48 @@
       "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: AsyncComputedCtx) => Promise<T>;\n```",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts",
+      "mdFile": "core.asynccomputedfn.md"
+    },
+    {
+      "name": "AsyncComputedReadonlySignal",
+      "id": "asynccomputedreadonlysignal",
+      "hierarchy": [
+        {
+          "name": "AsyncComputedReadonlySignal",
+          "id": "asynccomputedreadonlysignal"
+        }
+      ],
+      "kind": "Interface",
+      "content": "```typescript\nexport interface AsyncComputedReadonlySignal<T = unknown> extends ReadonlySignal<T> \n```\n**Extends:** [ReadonlySignal](#readonlysignal)<!-- -->&lt;T&gt;",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/signal.public.ts",
+      "mdFile": "core.asynccomputedreadonlysignal.md"
+    },
+    {
+      "name": "AsyncComputedReturnType",
+      "id": "asynccomputedreturntype",
+      "hierarchy": [
+        {
+          "name": "AsyncComputedReturnType",
+          "id": "asynccomputedreturntype"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type AsyncComputedReturnType<T> = T extends Promise<infer T> ? AsyncComputedReadonlySignal<T> : AsyncComputedReadonlySignal<T>;\n```\n**References:** [AsyncComputedReadonlySignal](#asynccomputedreadonlysignal)",
+      "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",
@@ -324,6 +366,20 @@
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-computed.ts",
       "mdFile": "core.computedfn.md"
     },
+    {
+      "name": "ComputedReturnType",
+      "id": "computedreturntype",
+      "hierarchy": [
+        {
+          "name": "ComputedReturnType",
+          "id": "computedreturntype"
+        }
+      ],
+      "kind": "TypeAlias",
+      "content": "```typescript\nexport type ComputedReturnType<T> = T extends Promise<any> ? never : ReadonlySignal<T>;\n```\n**References:** [ReadonlySignal](#readonlysignal)",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-computed.ts",
+      "mdFile": "core.computedreturntype.md"
+    },
     {
       "name": "ComputedSignal",
       "id": "computedsignal",
@@ -2060,7 +2116,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface TaskCtx \n```\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[track](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[Tracker](#tracker)\n\n\n</td><td>\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[cleanup(callback)](#)\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface TaskCtx \n```\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[cleanup](#)\n\n\n</td><td>\n\n\n</td><td>\n\n(callback: () =&gt; void) =&gt; void\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[track](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[Tracker](#tracker)\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-task.ts",
       "mdFile": "core.taskctx.md"
     },
@@ -2120,6 +2176,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_",
@@ -2130,7 +2200,7 @@
         }
       ],
       "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\nuseComputed$: <T>(qrl: ComputedFn<T>) => T extends Promise<any> ? never : ReadonlySignal<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[ComputedFn](#computedfn)<!-- -->&lt;T&gt;\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nT extends Promise&lt;any&gt; ? never : [ReadonlySignal](#readonlysignal)<!-- -->&lt;T&gt;",
+      "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\nuseComputed$: <T>(qrl: ComputedFn<T>) => ComputedReturnType<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[ComputedFn](#computedfn)<!-- -->&lt;T&gt;\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\n[ComputedReturnType](#computedreturntype)<!-- -->&lt;T&gt;",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-computed.ts",
       "mdFile": "core.usecomputed_.md"
     },

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

@@ -119,6 +119,37 @@ 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: AsyncComputedCtx) => Promise<T>;
+```
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts)
+
+## AsyncComputedReadonlySignal
+
+```typescript
+export interface AsyncComputedReadonlySignal<T = unknown> extends ReadonlySignal<T>
+```
+
+**Extends:** [ReadonlySignal](#readonlysignal)&lt;T&gt;
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/signal.public.ts)
+
+## AsyncComputedReturnType
+
+```typescript
+export type AsyncComputedReturnType<T> =
+  T extends Promise<infer T>
+    ? AsyncComputedReadonlySignal<T>
+    : AsyncComputedReadonlySignal<T>;
+```
+
+**References:** [AsyncComputedReadonlySignal](#asynccomputedreadonlysignal)
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async-computed.ts)
+
 ## cache
 
 ```typescript
@@ -353,6 +384,17 @@ export type ComputedFn<T> = () => T;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-computed.ts)
 
+## ComputedReturnType
+
+```typescript
+export type ComputedReturnType<T> =
+  T extends Promise<any> ? never : ReadonlySignal<T>;
+```
+
+**References:** [ReadonlySignal](#readonlysignal)
+
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-computed.ts)
+
 ## ComputedSignal
 
 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.
@@ -8267,31 +8309,26 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-[track](#)
+[cleanup](#)
 
 </td><td>
 
 </td><td>
 
-[Tracker](#tracker)
+(callback: () =&gt; void) =&gt; void
 
 </td><td>
 
 </td></tr>
-</tbody></table>
-
-<table><thead><tr><th>
-
-Method
+<tr><td>
 
-</th><th>
+[track](#)
 
-Description
+</td><td>
 
-</th></tr></thead>
-<tbody><tr><td>
+</td><td>
 
-[cleanup(callback)](#)
+[Tracker](#tracker)
 
 </td><td>
 
@@ -8433,14 +8470,55 @@ 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.
 
 The function must be synchronous and must not have any side effects.
 
 ```typescript
-useComputed$: <T>(qrl: ComputedFn<T>) => T extends Promise<any> ? never : ReadonlySignal<T>
+useComputed$: <T>(qrl: ComputedFn<T>) => ComputedReturnType<T>;
 ```
 
 <table><thead><tr><th>
@@ -8470,7 +8548,7 @@ qrl
 </tbody></table>
 **Returns:**
 
-T extends Promise&lt;any&gt; ? never : [ReadonlySignal](#readonlysignal)&lt;T&gt;
+[ComputedReturnType](#computedreturntype)&lt;T&gt;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-computed.ts)
 

packages/qwik/public.d.ts

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

packages/qwik/src/core/index.ts

@@ -111,7 +111,7 @@ export type { UseStylesScoped } from './use/use-styles';
 export type { UseSignal } from './use/use-signal';
 export type { ContextId } from './use/use-context';
 export type { UseStoreOptions } from './use/use-store.public';
-export type { ComputedFn } from './use/use-computed';
+export type { ComputedFn, ComputedReturnType } from './use/use-computed';
 export { useComputedQrl } from './use/use-computed';
 export { useSerializerQrl, useSerializer$ } from './use/use-serializer';
 export type { OnVisibleTaskOptions, VisibleTaskStrategy } from './use/use-visible-task';
@@ -133,10 +133,13 @@ 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 {
   type ReadonlySignal,
+  type AsyncComputedReadonlySignal,
   type Signal,
   type ComputedSignal,
 } from './reactive-primitives/signal.public';

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

@@ -16,6 +16,18 @@ import { ValueOrPromise as ValueOrPromise_2 } from '..';
 // @public
 export const $: <T>(expression: T) => QRL<T>;
 
+// Warning: (ae-forgotten-export) The symbol "AsyncComputedCtx" needs to be exported by the entry point index.d.ts
+//
+// @public (undocumented)
+export type AsyncComputedFn<T> = (ctx: AsyncComputedCtx) => Promise<T>;
+
+// @public (undocumented)
+export interface AsyncComputedReadonlySignal<T = unknown> extends ReadonlySignal<T> {
+}
+
+// @public (undocumented)
+export type AsyncComputedReturnType<T> = T extends Promise<infer T> ? AsyncComputedReadonlySignal<T> : AsyncComputedReadonlySignal<T>;
+
 // @public
 export type ClassList = string | undefined | null | false | Record<string, boolean | string | number | null | undefined> | ClassList[];
 
@@ -74,6 +86,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<any> ? never : ReadonlySignal<T>;
+
 // @public
 export interface ComputedSignal<T> extends ReadonlySignal<T> {
     force(): void;
@@ -1582,7 +1597,7 @@ export const _task: (_event: Event, element: Element) => void;
 // @public (undocumented)
 export interface TaskCtx {
     // (undocumented)
-    cleanup(callback: () => void): void;
+    cleanup: (callback: () => void) => void;
     // (undocumented)
     track: Tracker;
 }
@@ -1620,12 +1635,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;