feat(qrl): add resolved

packages/qwik/src/core/api.md

@@ -465,6 +465,7 @@ export interface QRL<TYPE = any> {
     // (undocumented)
     getSymbol(): string;
     resolve(): Promise<TYPE>;
+    resolved: undefined | TYPE;
 }
 
 // @public

packages/qwik/src/core/qrl/qrl-class.ts

@@ -30,6 +30,8 @@ export interface QRLInternalMethods<TYPE> {
   $captureRef$: any[] | null;
   dev: QRLDev | null;
 
+  resolved: undefined | TYPE;
+
   resolve(): Promise<TYPE>;
   getSymbol(): string;
   getHash(): string;
@@ -66,6 +68,12 @@ export const createQRL = <TYPE>(
 
   let _containerEl: Element | undefined;
 
+  const qrl = async function (this: any, ...args: any) {
+    const fn = invokeFn.call(this, tryGetInvokeContext());
+    const result = await fn(...args);
+    return result;
+  } as unknown as QRLInternal<TYPE>;
+
   const setContainer = (el: Element | undefined) => {
     if (!_containerEl) {
       _containerEl = el;
@@ -81,11 +89,11 @@ export const createQRL = <TYPE>(
       return symbolRef;
     }
     if (symbolFn !== null) {
-      return (symbolRef = symbolFn().then((module) => (symbolRef = module[symbol])));
+      return (symbolRef = symbolFn().then((module) => (qrl.resolved = symbolRef = module[symbol])));
     } else {
       const symbol2 = getPlatform().importSymbol(_containerEl, chunk, symbol);
       return (symbolRef = then(symbol2, (ref) => {
-        return (symbolRef = ref);
+        return (qrl.resolved = symbolRef = ref);
       }));
     }
   };
@@ -110,7 +118,7 @@ export const createQRL = <TYPE>(
           const baseContext = createOrReuseInvocationContext(currentCtx);
           const context: InvokeContext = {
             ...baseContext,
-            $qrl$: QRL as QRLInternal<any>,
+            $qrl$: qrl as QRLInternal<any>,
           };
           if (context.$event$ === undefined) {
             context.$event$ = this;
@@ -133,16 +141,10 @@ export const createQRL = <TYPE>(
     }
   };
 
-  const invokeQRL = async function (this: any, ...args: any) {
-    const fn = invokeFn.call(this, tryGetInvokeContext());
-    const result = await fn(...args);
-    return result;
-  };
   const resolvedSymbol = refSymbol ?? symbol;
   const hash = getSymbolHash(resolvedSymbol);
 
-  const QRL: QRLInternal<TYPE> = invokeQRL as any;
-  const methods: QRLInternalMethods<TYPE> = {
+  Object.assign(qrl, {
     getSymbol: () => resolvedSymbol,
     getHash: () => hash,
     getCaptured: () => captureRef,
@@ -158,8 +160,8 @@ export const createQRL = <TYPE>(
     $capture$: capture,
     $captureRef$: captureRef,
     dev: null,
-  };
-  const qrl = Object.assign(invokeQRL, methods);
+    resolved: undefined,
+  });
   seal(qrl);
   return qrl as any;
 };

packages/qwik/src/core/qrl/qrl.public.ts

@@ -82,6 +82,11 @@ import { createQRL } from './qrl-class';
  * NOTE: `element` is needed because `QRL`s are relative and need a base location to resolve
  * against. The base location is encoded in the HTML in the form of `<div q:base="/url">`.
  *
+ * ## `QRL.resolved`
+ *
+ * Once `QRL.resolve()` returns, the value is stored under `QRL.resolved`. This allows the value
+ * to be used without having to await `QRL.resolve()` again.
+ *
  * ## Question: Why not just use `import()`?
  *
  * At first glance, `QRL` serves the same purpose as `import()`. However, there are three subtle
@@ -132,7 +137,7 @@ export interface QRL<TYPE = any> {
   __brand__QRL__: TYPE;
 
   /**
-   * Resolve the QRL of closure and invoke it.
+   * Resolve the QRL of closure and invoke it. The signal is used to abort the invocation.
    * @param signal - An AbortSignal object.
    * @param args - Closure arguments.
    * @returns A promise of the return value of the closure.
@@ -151,10 +156,10 @@ export interface QRL<TYPE = any> {
     ...args: TYPE extends (...args: infer ARGS) => any ? ARGS : never
   ): Promise<TYPE extends (...args: any[]) => infer RETURN ? Awaited<RETURN> : never>;
 
-  /**
-   * Resolve the QRL and return the actual value.
-   */
+  /** Resolve the QRL and return the actual value. */
   resolve(): Promise<TYPE>;
+  /** The resolved value, once `resolve()` returns. */
+  resolved: undefined | TYPE;
   getCaptured(): any[] | null;
   getSymbol(): string;
   getHash(): string;

packages/qwik/src/core/qrl/qrl.unit.ts

@@ -7,7 +7,11 @@ import { equal } from 'uvu/assert';
 const qrlSuite = suite('serialization');
 
 qrlSuite('should parse', () => {
-  matchProps(parseQRL('./chunk#default'), { $chunk$: './chunk', $symbol$: 'default' });
+  matchProps(parseQRL('./chunk#default'), {
+    $chunk$: './chunk',
+    $symbol$: 'default',
+    resolved: undefined,
+  });
   matchProps(parseQRL('./chunk#mySymbol'), {
     $chunk$: './chunk',
     $symbol$: 'mySymbol',
@@ -75,6 +79,13 @@ qrlSuite('should parse reference', () => {
 });
 qrlSuite('should parse self-reference', () => {});
 
+qrlSuite('should store resolved value', async () => {
+  const q = qrl(() => Promise.resolve({ hi: 'hello' }), 'hi');
+  equal(q.resolved, undefined);
+  await q.resolve();
+  equal(q.resolved, 'hello');
+});
+
 function matchProps(obj: any, properties: Record<string, any>) {
   for (const [key, value] of Object.entries(properties)) {
     equal(obj[key], value, `${obj[key]} !== ${value}`);

packages/qwik/src/core/readme.md

@@ -246,6 +246,10 @@ At times it may be necessary to resolve a `QRL` reference to the actual value. T
 
 NOTE: `element` is needed because `QRL`s are relative and need a base location to resolve against. The base location is encoded in the HTML in the form of `<div q:base="/url">`.
 
+## `QRL.resolved`
+
+Once `QRL.resolve()` returns, the value is stored under `QRL.resolved`. This allows the value to be used without having to await `QRL.resolve()` again.
+
 ## Question: Why not just use `import()`?
 
 At first glance, `QRL` serves the same purpose as `import()`. However, there are three subtle differences that need to be taken into account.