feat(untrack): accept signals/stores directly, pass arguments

Author: wmertens

.changeset/petite-garlics-shop.md

@@ -0,0 +1,5 @@
+---
+'@builder.io/qwik': minor
+---
+
+FEAT: `untrack()` now accepts signals and stores directly, as well as accepting arguments when you pass a function. This makes retrieving values without subscribing to them more efficient.

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

@@ -3006,7 +3006,7 @@
         }
       ],
       "kind": "Function",
-      "content": "Don't track listeners for this callback\n\n\n```typescript\nuntrack: <T>(fn: () => T) => 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\nfn\n\n\n</td><td>\n\n() =&gt; T\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nT",
+      "content": "Get the value of the expression without tracking listeners. A function will be invoked, signals will return their value, and stores will be unwrapped (they return the backing object).\n\nWhen you pass a function, you can also pass additional arguments that the function will receive.\n\nNote that stores are not unwrapped recursively.\n\n\n```typescript\nuntrack: <T, A extends any[]>(expr: ((...args: A) => T) | Signal<T> | T, ...args: A) => 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\nexpr\n\n\n</td><td>\n\n((...args: A) =&gt; T) \\| [Signal](#signal)<!-- -->&lt;T&gt; \\| T\n\n\n</td><td>\n\nThe function or object to evaluate without tracking.\n\n\n</td></tr>\n<tr><td>\n\nargs\n\n\n</td><td>\n\nA\n\n\n</td><td>\n\nAdditional arguments to pass when `expr` is a function.\n\n\n</td></tr>\n</tbody></table>\n\n**Returns:**\n\nT",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/use/use-core.ts",
       "mdFile": "qwik.untrack.md"
     },

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

@@ -10078,10 +10078,17 @@ export interface TrackHTMLAttributes<T extends Element> extends Attrs<'track', T
 
 ## untrack
 
-Don't track listeners for this callback
+Get the value of the expression without tracking listeners. A function will be invoked, signals will return their value, and stores will be unwrapped (they return the backing object).
+
+When you pass a function, you can also pass additional arguments that the function will receive.
+
+Note that stores are not unwrapped recursively.
 
 ```typescript
-untrack: <T>(fn: () => T) => T;
+untrack: <T, A extends any[]>(
+  expr: ((...args: A) => T) | Signal<T> | T,
+  ...args: A
+) => T;
 ```
 
 <table><thead><tr><th>
@@ -10099,14 +10106,29 @@ Description
 </th></tr></thead>
 <tbody><tr><td>
 
-fn
+expr
+
+</td><td>
+
+((...args: A) =&gt; T) \| [Signal](#signal)&lt;T&gt; \| T
+
+</td><td>
+
+The function or object to evaluate without tracking.
+
+</td></tr>
+<tr><td>
+
+args
 
 </td><td>
 
-() =&gt; T
+A
 
 </td><td>
 
+Additional arguments to pass when `expr` is a function.
+
 </td></tr>
 </tbody></table>
 

packages/qwik-city/src/runtime/src/link-component.tsx

@@ -32,18 +32,15 @@ export const Link = component$<LinkProps>((props) => {
     scroll,
     ...linkProps
   } = (() => props)();
-  const clientNavPath = untrack(() => getClientNavPath({ ...linkProps, reload }, loc));
+  const clientNavPath = untrack(getClientNavPath, { ...linkProps, reload }, loc);
   linkProps.href = clientNavPath || originalHref;
 
-  const prefetchData = untrack(
-    () => (!!clientNavPath && prefetchProp !== false && prefetchProp !== 'js') || undefined
-  );
+  const prefetchData =
+    (!!clientNavPath && prefetchProp !== false && prefetchProp !== 'js') || undefined;
 
-  const prefetch = untrack(
-    () =>
-      prefetchData ||
-      (!!clientNavPath && prefetchProp !== false && shouldPreload(clientNavPath, loc))
-  );
+  const prefetch =
+    prefetchData ||
+    (!!clientNavPath && prefetchProp !== false && untrack(shouldPreload, clientNavPath, loc));
 
   const handlePrefetch = prefetch
     ? $((_: any, elm: HTMLAnchorElement) => {

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

@@ -1635,7 +1635,7 @@ export interface TrackHTMLAttributes<T extends Element> extends Attrs<'track', T
 }
 
 // @public
-export const untrack: <T>(fn: () => T) => T;
+export const untrack: <T, A extends any[]>(expr: ((...args: A) => T) | Signal<T> | T, ...args: A) => T;
 
 // @public
 export const unwrapStore: <T>(proxy: T) => T;

packages/qwik/src/core/use/use-core.ts

@@ -20,7 +20,8 @@ import { seal } from '../util/qdev';
 import { isArray } from '../util/types';
 import { setLocale } from './use-locale';
 import type { Subscriber } from '../state/common';
-import type { Signal } from '../state/signal';
+import { isSignal, type Signal, type SignalInternal } from '../state/signal';
+import { unwrapStore } from '..';
 
 declare const document: QwikDocument;
 
@@ -142,7 +143,7 @@ export function useBindInvokeContext<FN extends (...args: any) => any>(
 }
 
 /** Call a function with the given InvokeContext and given arguments. */
-export function invoke<FN extends (...args: any) => any>(
+export function invoke<FN extends (...args: any[]) => any>(
   this: unknown,
   context: InvokeContext | undefined,
   fn: FN,
@@ -220,12 +221,28 @@ export const getWrappingContainer = (el: QwikElement): Element | null => {
 };
 
 /**
- * Don't track listeners for this callback
+ * Get the value of the expression without tracking listeners. A function will be invoked, signals
+ * will return their value, and stores will be unwrapped (they return the backing object).
  *
+ * When you pass a function, you can also pass additional arguments that the function will receive.
+ *
+ * Note that stores are not unwrapped recursively.
+ *
+ * @param expr - The function or object to evaluate without tracking.
+ * @param args - Additional arguments to pass when `expr` is a function.
  * @public
  */
-export const untrack = <T>(fn: () => T): T => {
-  return invoke(undefined, fn);
+export const untrack = <T, A extends any[]>(
+  expr: ((...args: A) => T) | Signal<T> | T,
+  ...args: A
+): T => {
+  if (typeof expr === 'function') {
+    return invoke(undefined, expr as (...args: A) => T, ...args);
+  }
+  if (isSignal(expr)) {
+    return (expr as SignalInternal<T>).untrackedValue;
+  }
+  return unwrapStore(expr);
 };
 
 const trackInvocation = /*#__PURE__*/ newInvokeContext(