fix(core): useSignal docs, useAsync type

Author: wmertens

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

@@ -128,17 +128,6 @@ export type AsyncFn<T> = (ctx: AsyncCtx) => Promise<T>;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async.ts)
 
-## AsyncReturnType
-
-```typescript
-export type AsyncReturnType<T> =
-  T extends Promise<infer T> ? AsyncSignal<T> : AsyncSignal<T>;
-```
-
-**References:** [AsyncSignal](#asyncsignal)
-
-[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async.ts)
-
 ## AsyncSignal
 
 ```typescript
@@ -172,7 +161,7 @@ Description
 
 </td><td>
 
-Error \| null
+Error \| undefined
 
 </td><td>
 
@@ -331,11 +320,11 @@ export interface CounterProps {
   step?: number;
 }
 export const Counter = component$((props: CounterProps) => {
-  const state = useStore({ count: props.initialValue || 0 });
+  const state = useSignal(props.initialValue || 0);
   return (
     <div>
-      <span>{state.count}</span>
-      <button onClick$={() => (state.count += props.step || 1)}>+</button>
+      <span>{state.value}</span>
+      <button onClick$={() => (state.value += props.step || 1)}>+</button>
     </div>
   );
 });
@@ -836,7 +825,7 @@ The QRL must be a function which returns the value of the signal. The function m
 
 ```typescript
 createAsync$: <T>(qrl: () => Promise<T>, options?: ComputedOptions) =>
-  AsyncReturnType<T>;
+  AsyncSignal<T>;
 ```
 
 <table><thead><tr><th>
@@ -880,7 +869,7 @@ _(Optional)_
 
 **Returns:**
 
-[AsyncReturnType](#asyncreturntype)&lt;T&gt;
+[AsyncSignal](#asyncsignal)&lt;T&gt;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/reactive-primitives/signal.public.ts)
 
@@ -8878,6 +8867,8 @@ const Cmp = component$(() => {
   useTask$(({ track }) => {
     // Any signals or stores accessed inside the task will be tracked
     const count = track(() => store.count);
+    // For stores you can also pass the store and specify the property
+    track(store, "count");
     // You can also pass a signal to track() directly
     const signalCount = track(signal);
     store.doubleCount = count + signalCount;
@@ -9010,9 +9001,7 @@ T
 
 ## useAsync$
 
-Creates an AsyncSignal which is calculated from the given async function. If the function uses 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 components that read the AsyncSignal will be re-rendered.
-
-The function must not have any side effects, as it can run multiple times.
+Creates an AsyncSignal which 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.
 
 If 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.
 
@@ -9024,7 +9013,7 @@ If the value has been resolved, but the async function is re-running, reading th
 
 ```typescript
 useAsync$: <T>(qrl: AsyncFn<T>, options?: ComputedOptions | undefined) =>
-  AsyncReturnType<T>;
+  AsyncSignal<T>;
 ```
 
 <table><thead><tr><th>
@@ -9068,7 +9057,7 @@ _(Optional)_
 
 **Returns:**
 
-[AsyncReturnType](#asyncreturntype)&lt;T&gt;
+[AsyncSignal](#asyncsignal)&lt;T&gt;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-async.ts)
 
@@ -9706,6 +9695,43 @@ T \| undefined
 
 ## useSignal
 
+Creates an object with a single reactive `.value` property, that Qwik can track across serializations.
+
+Use it to create state for your application. The object has a getter and setter to track reads and writes of the `.value` property. When the value changes, any functions that read from it will re-run.
+
+Prefer `useSignal` over `useStore` when possible, as it is more efficient.
+
+### Example
+
+```tsx
+const Signals = component$(() => {
+  const counter = useSignal(1);
+  const text = useSignal('changeme');
+  const toggle = useSignal(false);
+
+  // useSignal() can also accept a function to calculate the initial value
+  const state = useSignal(() => {
+    return expensiveInitialValue();
+  });
+
+  return (
+    <div>
+      <button onClick$={() => counter.value++}>Counter: {counter.value}</button>
+      {
+        // pass signal values as the value, the optimizer will make it pass the signal
+      }
+      <Child state={state.value} />
+      {
+        // signals can be bound to inputs. A property named `bind:x` implies that the property
+is a signal
+      }
+      <input type="text" bind:value={text} />
+      <input type="checkbox" bind:checked={toggle} />
+    </div>
+  );
+});
+```
+
 ```typescript
 useSignal: UseSignal;
 ```
@@ -9714,6 +9740,43 @@ useSignal: UseSignal;
 
 ## UseSignal
 
+Creates an object with a single reactive `.value` property, that Qwik can track across serializations.
+
+Use it to create state for your application. The object has a getter and setter to track reads and writes of the `.value` property. When the value changes, any functions that read from it will re-run.
+
+Prefer `useSignal` over `useStore` when possible, as it is more efficient.
+
+### Example
+
+```tsx
+const Signals = component$(() => {
+  const counter = useSignal(1);
+  const text = useSignal('changeme');
+  const toggle = useSignal(false);
+
+  // useSignal() can also accept a function to calculate the initial value
+  const state = useSignal(() => {
+    return expensiveInitialValue();
+  });
+
+  return (
+    <div>
+      <button onClick$={() => counter.value++}>Counter: {counter.value}</button>
+      {
+        // pass signal values as the value, the optimizer will make it pass the signal
+      }
+      <Child state={state.value} />
+      {
+        // signals can be bound to inputs. A property named `bind:x` implies that the property
+is a signal
+      }
+      <input type="text" bind:value={text} />
+      <input type="checkbox" bind:checked={toggle} />
+    </div>
+  );
+});
+```
+
 ```typescript
 useSignal: UseSignal;
 ```
@@ -9722,9 +9785,13 @@ useSignal: UseSignal;
 
 ## useStore
 
-Creates an object that Qwik can track across serializations.
+Creates a reactive object that Qwik can track across serialization.
+
+Use it to create state for your application. The returned object is a Proxy that tracks reads and writes. When any of the properties change, the functions that read those properties will re-run.
+
+`Store`s are deep by default, meaning that any objects assigned to properties will also become `Store`s. This includes arrays.
 
-Use `useStore` to create a state for your application. The returned object is a proxy that has a unique ID. The ID of the object is used in the `QRL`s to refer to the store.
+Prefer `useSignal` over `useStore` when possible, as it is more efficient.
 
 ### Example
 

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

@@ -15,7 +15,6 @@ import { useStyles$, useStylesScoped$ } from './use/use-styles';
 import { useTask$ } from './use/use-task-dollar';
 import { useVisibleTask$ } from './use/use-visible-task-dollar';
 import { implicit$FirstArg } from './shared/qrl/implicit_dollar';
-import { isServer, isBrowser } from '../build';
 
 //////////////////////////////////////////////////////////
 //////////////////////////////////////////////////////////
@@ -30,11 +29,11 @@ export interface CounterProps {
   step?: number;
 }
 export const Counter = component$((props: CounterProps) => {
-  const state = useStore({ count: props.initialValue || 0 });
+  const state = useSignal(props.initialValue || 0);
   return (
     <div>
-      <span>{state.count}</span>
-      <button onClick$={() => (state.count += props.step || 1)}>+</button>
+      <span>{state.value}</span>
+      <button onClick$={() => (state.value += props.step || 1)}>+</button>
     </div>
   );
 });
@@ -215,6 +214,8 @@ export const CmpInline = component$(() => {
     useTask$(({ track }) => {
       // Any signals or stores accessed inside the task will be tracked
       const count = track(() => store.count);
+      // For stores you can also pass the store and specify the property
+      track(store, 'count');
       // You can also pass a signal to track() directly
       const signalCount = track(signal);
       store.doubleCount = count + signalCount;
@@ -240,102 +241,6 @@ export const CmpInline = component$(() => {
   return Cmp;
 };
 
-() => {
-  let db: any;
-  // <docs anchor="use-server-mount">
-  const Cmp = component$(() => {
-    const store = useStore({
-      users: [],
-    });
-
-    useTask$(async () => {
-      if (isServer) {
-        // This code will ONLY run once in the server, when the component is mounted
-        store.users = await db.requestUsers();
-      }
-    });
-
-    return (
-      <div>
-        {store.users.map((user) => (
-          <User user={user} />
-        ))}
-      </div>
-    );
-  });
-
-  interface User {
-    name: string;
-  }
-  function User(props: { user: User }) {
-    return <div>Name: {props.user.name}</div>;
-  }
-  // </docs>
-  return Cmp;
-};
-
-() => {
-  // <docs anchor="use-client-mount">
-  const Cmp = component$(() => {
-    useTask$(async () => {
-      if (isBrowser) {
-        // This code will ONLY run once in the client, when the component is mounted
-      }
-    });
-
-    return <div>Cmp</div>;
-  });
-  // </docs>
-  return Cmp;
-};
-
-() => {
-  // <docs anchor="use-mount">
-  const Cmp = component$(() => {
-    const store = useStore({
-      temp: 0,
-    });
-
-    useTask$(async () => {
-      // This code will run once whenever a component is mounted in the server, or in the client
-      const res = await fetch('weather-api.example');
-      const json = (await res.json()) as any;
-      store.temp = json.temp;
-    });
-
-    return (
-      <div>
-        <p>The temperature is: ${store.temp}</p>
-      </div>
-    );
-  });
-  // </docs>
-  return Cmp;
-};
-
-() => {
-  // <docs anchor="use-client-effect">
-  const Timer = component$(() => {
-    const store = useStore({
-      count: 0,
-    });
-
-    useVisibleTask$(() => {
-      // Only runs in the client
-      const timer = setInterval(() => {
-        store.count++;
-      }, 500);
-      return () => {
-        clearInterval(timer);
-      };
-    });
-
-    return <div>{store.count}</div>;
-  });
-  // </docs>
-  return Timer;
-};
-
 () => {
   // <docs anchor="use-store">
   const Stores = component$(() => {
@@ -394,6 +299,45 @@ export const CmpInline = component$(() => {
   return Stores;
 };
 
+() => {
+  // <docs anchor="use-signal">
+  const Signals = component$(() => {
+    const counter = useSignal(1);
+    const text = useSignal('changeme');
+    const toggle = useSignal(false);
+
+    // useSignal() can also accept a function to calculate the initial value
+    const state = useSignal(() => {
+      return expensiveInitialValue();
+    });
+
+    return (
+      <div>
+        <button onClick$={() => counter.value++}>Counter: {counter.value}</button>
+        {
+          // pass signal values as the value, the optimizer will make it pass the signal
+        }
+        <Child state={state.value} />
+        {
+          // signals can be bound to inputs. A property named `bind:x` implies that the property is a signal
+        }
+        <input type="text" bind:value={text} />
+        <input type="checkbox" bind:checked={toggle} />
+      </div>
+    );
+  });
+  // </docs>
+
+  function expensiveInitialValue() {
+    return 42;
+  }
+
+  function Child(_props: any) {
+    return <div />;
+  }
+  return Signals;
+};
+
 //
 // <docs anchor="context">
 // Declare the Context type.

packages/qwik/src/core/examples.tsx

@@ -159,7 +159,7 @@ 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 { AsyncFn, AsyncReturnType } from './use/use-async';
+export type { AsyncFn } from './use/use-async';
 export { useAsyncQrl, useAsync$ } from './use/use-async';
 export { useErrorBoundary } from './use/use-error-boundary';
 export type { ErrorBoundaryStore } from './shared/error/error-handling';