feat: implement serializationStrategy for route loaders

Author: Varixo

packages/qwik-router/src/middleware/request-handler/middleware.request-handler.api.md

@@ -17,6 +17,7 @@ import type { RenderOptions } from '@qwik.dev/core/server';
 import { RequestEvent as RequestEvent_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { RequestHandler as RequestHandler_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { ResolveSyncValue as ResolveSyncValue_2 } from '@qwik.dev/router/middleware/request-handler';
+import type { SerializationStrategy } from '@qwik.dev/core/internal';
 import type { _serialize } from '@qwik.dev/core/internal';
 import type { ValueOrPromise } from '@qwik.dev/core';
 import type { _verifySerializable } from '@qwik.dev/core/internal';

packages/qwik-router/src/middleware/request-handler/request-event.ts

@@ -1,4 +1,5 @@
 import type { ValueOrPromise } from '@qwik.dev/core';
+import type { SerializationStrategy } from '@qwik.dev/core/internal';
 import { QDATA_KEY } from '../../runtime/src/constants';
 import {
   LoadedRouteProp,
@@ -33,6 +34,9 @@ const RequestEvLoaders = Symbol('RequestEvLoaders');
 const RequestEvMode = Symbol('RequestEvMode');
 const RequestEvRoute = Symbol('RequestEvRoute');
 export const RequestEvQwikSerializer = Symbol('RequestEvQwikSerializer');
+export const RequestEvLoadersSerializationStrategy = Symbol(
+  'RequestEvLoadersSerializationStrategy'
+);
 export const RequestEvTrailingSlash = Symbol('RequestEvTrailingSlash');
 export const RequestRouteName = '@routeName';
 export const RequestEvSharedActionId = '@actionId';
@@ -149,6 +153,7 @@ export function createRequestEvent(
   const loaders: Record<string, Promise<any>> = {};
   const requestEv: RequestEventInternal = {
     [RequestEvLoaders]: loaders,
+    [RequestEvLoadersSerializationStrategy]: new Map(),
     [RequestEvMode]: serverRequestEv.mode,
     [RequestEvTrailingSlash]: trailingSlash,
     get [RequestEvRoute]() {
@@ -328,6 +333,7 @@ export function createRequestEvent(
 
 export interface RequestEventInternal extends RequestEvent, RequestEventLoader {
   [RequestEvLoaders]: Record<string, ValueOrPromise<unknown> | undefined>;
+  [RequestEvLoadersSerializationStrategy]: Map<string, SerializationStrategy>;
   [RequestEvMode]: ServerRequestMode;
   [RequestEvTrailingSlash]: boolean;
   [RequestEvRoute]: LoadedRoute | null;
@@ -358,6 +364,10 @@ export function getRequestLoaders(requestEv: RequestEventCommon) {
   return (requestEv as RequestEventInternal)[RequestEvLoaders];
 }
 
+export function getRequestLoadersSerializationStrategy(requestEv: RequestEventCommon) {
+  return (requestEv as RequestEventInternal)[RequestEvLoadersSerializationStrategy];
+}
+
 export function getRequestTrailingSlash(requestEv: RequestEventCommon) {
   return (requestEv as RequestEventInternal)[RequestEvTrailingSlash];
 }

packages/qwik-router/src/middleware/request-handler/resolve-request-handlers.ts

@@ -1,6 +1,6 @@
 import { type QRL } from '@qwik.dev/core';
 import type { Render, RenderToStringResult } from '@qwik.dev/core/server';
-import { QACTION_KEY, QFN_KEY, QLOADER_EAGER, QLOADER_KEY } from '../../runtime/src/constants';
+import { QACTION_KEY, QFN_KEY, QLOADER_KEY } from '../../runtime/src/constants';
 import {
   type ActionInternal,
   type ClientPageData,
@@ -26,6 +26,7 @@ import {
   type RequestEventInternal,
   RequestEvShareServerTiming,
   RequestEvShareQData,
+  getRequestLoadersSerializationStrategy,
 } from './request-event';
 import { getQwikRouterServerData } from './response-page';
 import type {
@@ -307,7 +308,8 @@ async function getRouteLoaderPromise(
       }
       return resolvedLoader;
     });
-  (loaders[loaderId] as any)[QLOADER_EAGER] = loader.__eager;
+  const loadersSerializationStrategy = getRequestLoadersSerializationStrategy(requestEv);
+  loadersSerializationStrategy.set(loaderId, loader.__serializationStrategy);
   return loaders[loaderId];
 }
 

packages/qwik-router/src/middleware/request-handler/response-page.ts

@@ -1,6 +1,7 @@
 import type { QwikRouterEnvData } from '../../runtime/src/types';
 import {
   getRequestLoaders,
+  getRequestLoadersSerializationStrategy,
   getRequestRoute,
   RequestEvSharedActionFormData,
   RequestEvSharedActionId,
@@ -32,6 +33,7 @@ export function getQwikRouterServerData(requestEv: RequestEvent) {
   }
 
   const loaders = getRequestLoaders(requestEv);
+  const loadersSerializationStrategy = getRequestLoadersSerializationStrategy(requestEv);
 
   return {
     url: reconstructedUrl.href,
@@ -49,6 +51,7 @@ export function getQwikRouterServerData(requestEv: RequestEvent) {
       response: {
         status: status(),
         loaders,
+        loadersSerializationStrategy,
         action,
         formData,
       },

packages/qwik-router/src/runtime/src/constants.ts

@@ -13,5 +13,3 @@ export const QFN_KEY = 'qfunc';
 export const QDATA_KEY = 'qdata';
 
 export const Q_ROUTE = 'q:route';
-
-export const QLOADER_EAGER = Symbol('qloader_eager');

packages/qwik-router/src/runtime/src/qwik-router-component.tsx

@@ -106,7 +106,7 @@ export interface QwikRouterProps {
    *
    * @see https://github.com/WICG/view-transitions/blob/main/explainer.md
    * @see https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
-   * @see https://caniuse.com/mdn-api_viewtransition
+   * @see https://caniuse.com/mdn_api_viewtransition
    */
   viewTransition?: boolean;
 }
@@ -176,26 +176,29 @@ export const QwikRouterProvider = component$<QwikRouterProps>((props) => {
   );
   const navResolver: { r?: () => void } = {};
   const container = _getContextContainer();
-  const spaLoaderState: Record<string, unknown> = Object.fromEntries(
-    Object.entries(env.response.loaders).map(([k, v]) => {
-      return [k, v];
-    })
-  );
-  (spaLoaderState as any)[SerializerSymbol] = (obj: Record<string, unknown>) => {
-    return Object.fromEntries(
-      Object.entries(obj).map(([k, v]) => {
-        return [k, _UNINITIALIZED];
-      })
+  const getSerializationStrategy = (loaderId: string) => {
+    return env.response.loadersSerializationStrategy.get(loaderId) || 'never';
+  };
+
+  const loadersObject: Record<string, unknown> = {};
+  const loaderState: Record<string, Signal<unknown>> = {};
+  for (const [key, value] of Object.entries(env.response.loaders)) {
+    loadersObject[key] = value;
+    loaderState[key] = createLoaderSignal(
+      loadersObject,
+      key,
+      url,
+      getSerializationStrategy(key),
+      container
     );
+  }
+  (loadersObject as any)[SerializerSymbol] = (obj: Record<string, unknown>) => {
+    const loadersSerializationObject: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) {
+      loadersSerializationObject[k] = getSerializationStrategy(k) === 'always' ? v : _UNINITIALIZED;
+    }
+    return loadersSerializationObject;
   };
-  const loaderState = Object.fromEntries(
-    Object.entries(env.response.loaders).map(([k, v]) => {
-      // const isEager = (v as any)[QLOADER_EAGER];
-      // const value = isEager ? createSignal(v) : createLoaderSignal(spaLoaderState, k, v, url);
-      const value = createLoaderSignal(spaLoaderState, k, url, container);
-      return [k, value];
-    })
-  );
 
   const routeInternal = useSignal<RouteStateInternal>({
     type: 'initial',
@@ -515,9 +518,15 @@ export const QwikRouterProvider = component$<QwikRouterProps>((props) => {
             for (const [key, value] of Object.entries(loaders)) {
               const signal = loaderState[key] as Signal<unknown>;
               const awaitedValue = await value;
-              spaLoaderState[key] = awaitedValue;
+              loadersObject[key] = awaitedValue;
               if (!signal) {
-                loaderState[key] = createLoaderSignal(spaLoaderState, key, trackUrl, container);
+                loaderState[key] = createLoaderSignal(
+                  loadersObject,
+                  key,
+                  trackUrl,
+                  'never',
+                  container
+                );
               } else {
                 (signal as any).force();
               }

packages/qwik-router/src/runtime/src/qwik-router.runtime.api.md

@@ -23,6 +23,7 @@ import { RequestEventCommon } from '@qwik.dev/router/middleware/request-handler'
 import { RequestEventLoader } from '@qwik.dev/router/middleware/request-handler';
 import { RequestHandler } from '@qwik.dev/router/middleware/request-handler';
 import type { ResolveSyncValue } from '@qwik.dev/router/middleware/request-handler';
+import type { SerializationStrategy } from '@qwik.dev/core/internal';
 import type * as v from 'valibot';
 import type { ValueOrPromise } from '@qwik.dev/core';
 import { z } from 'zod';

packages/qwik-router/src/runtime/src/server-functions.ts

@@ -17,6 +17,7 @@ import {
   _serialize,
   _useInvokeContext,
   _UNINITIALIZED,
+  type SerializationStrategy,
 } from '@qwik.dev/core/internal';
 
 import * as v from 'valibot';
@@ -29,9 +30,8 @@ import type {
   ActionConstructorQRL,
   ActionInternal,
   ActionStore,
-  CommonLoaderActionOptions,
+  ActionOptions,
   DataValidator,
-  EagerLoaderOptions,
   Editable,
   JSONObject,
   LoaderConstructor,
@@ -54,6 +54,7 @@ import type {
   ZodConstructor,
   ZodConstructorQRL,
   ZodDataValidator,
+  LoaderOptions,
 } from './types';
 import { useAction, useLocation, useQwikRouterEnv } from './use-functions';
 
@@ -64,7 +65,7 @@ import { loadClientData } from './use-endpoint';
 /** @internal */
 export const routeActionQrl = ((
   actionQrl: QRL<(form: JSONObject, event: RequestEventAction) => unknown>,
-  ...rest: (CommonLoaderActionOptions | DataValidator)[]
+  ...rest: (ActionOptions | DataValidator)[]
 ) => {
   const { id, validators } = getValidators(rest, actionQrl);
   function action() {
@@ -168,7 +169,7 @@ Action.run() can only be called on the browser, for example when a user clicks a
 /** @internal */
 export const globalActionQrl = ((
   actionQrl: QRL<(form: JSONObject, event: RequestEventAction) => unknown>,
-  ...rest: (CommonLoaderActionOptions | DataValidator)[]
+  ...rest: (ActionOptions | DataValidator)[]
 ) => {
   const action = routeActionQrl(actionQrl, ...(rest as any));
   if (isServer) {
@@ -193,9 +194,9 @@ export const globalAction$: ActionConstructor = /*#__PURE__*/ implicit$FirstArg(
 /** @internal */
 export const routeLoaderQrl = ((
   loaderQrl: QRL<(event: RequestEventLoader) => unknown>,
-  ...rest: (EagerLoaderOptions | DataValidator)[]
+  ...rest: (LoaderOptions | DataValidator)[]
 ): LoaderInternal => {
-  const { id, validators, eager } = getValidators(rest, loaderQrl);
+  const { id, validators, serializationStrategy } = getValidators(rest, loaderQrl);
   function loader() {
     const iCtx = _useInvokeContext();
     const state = iCtx.$container$.resolveContext(iCtx.$hostElement$, RouteStateContext)!;
@@ -210,7 +211,7 @@ export const routeLoaderQrl = ((
     For more information check: https://qwik.dev/docs/re-exporting-loaders/`);
     }
     const loaderData = untrack(() => state[id].value);
-    if (loaderData === _UNINITIALIZED && isBrowser) {
+    if (isBrowser && loaderData === _UNINITIALIZED) {
       // Request the loader data from the server and throw the Promise
       // so the client can load it synchronously.
       throw loadClientData(location.url, iCtx.$hostElement$, {
@@ -225,7 +226,7 @@ export const routeLoaderQrl = ((
   loader.__qrl = loaderQrl;
   loader.__validators = validators;
   loader.__id = id;
-  loader.__eager = eager;
+  loader.__serializationStrategy = serializationStrategy;
   Object.freeze(loader);
 
   return loader;
@@ -515,9 +516,9 @@ export const serverQrl = <T extends ServerFunction>(
 /** @public */
 export const server$ = /*#__PURE__*/ implicit$FirstArg(serverQrl);
 
-const getValidators = (rest: (EagerLoaderOptions | DataValidator)[], qrl: QRL) => {
+const getValidators = (rest: (LoaderOptions | DataValidator)[], qrl: QRL) => {
   let id: string | undefined;
-  let eager = false;
+  let serializationStrategy: SerializationStrategy = 'never';
   const validators: DataValidator[] = [];
   if (rest.length === 1) {
     const options = rest[0];
@@ -526,7 +527,7 @@ const getValidators = (rest: (EagerLoaderOptions | DataValidator)[], qrl: QRL) =
         validators.push(options);
       } else {
         id = options.id;
-        eager = options.eager || false;
+        serializationStrategy = options.serializationStrategy || 'never';
         if (options.validation) {
           validators.push(...options.validation);
         }
@@ -549,7 +550,7 @@ const getValidators = (rest: (EagerLoaderOptions | DataValidator)[], qrl: QRL) =
   return {
     validators: validators.reverse(),
     id,
-    eager,
+    serializationStrategy,
   };
 };
 

packages/qwik-router/src/runtime/src/types.ts

@@ -6,6 +6,7 @@ import type {
   Signal,
   ValueOrPromise,
 } from '@qwik.dev/core';
+import type { SerializationStrategy } from '@qwik.dev/core/internal';
 import type {
   EnvGetter,
   RequestEvent,
@@ -319,11 +320,13 @@ export const enum LoadedRouteProp {
 export interface EndpointResponse {
   status: number;
   loaders: Record<string, unknown>;
+  loadersSerializationStrategy: Map<string, SerializationStrategy>;
   formData?: FormData;
   action?: string;
 }
 
-export interface ClientPageData extends Omit<EndpointResponse, 'status'> {
+export interface ClientPageData
+  extends Omit<EndpointResponse, 'status' | 'loadersSerializationStrategy'> {
   status: number;
   href: string;
   redirect?: string;
@@ -403,15 +406,11 @@ export type GetValidatorType<VALIDATOR extends TypedDataValidator> =
   GetValidatorOutputType<VALIDATOR>;
 
 /** @public */
-export type CommonLoaderActionOptions = {
+export type ActionOptions = {
   readonly id?: string;
   readonly validation?: DataValidator[];
 };
 
-export interface EagerLoaderOptions extends CommonLoaderActionOptions {
-  readonly eager?: boolean;
-}
-
 /** @public */
 export type FailOfRest<REST extends readonly DataValidator[]> = REST extends readonly DataValidator<
   infer ERROR
@@ -651,8 +650,9 @@ export type ActionConstructorQRL = {
 
 /** @public */
 export type LoaderOptions = {
-  id?: string;
-  eager?: boolean;
+  readonly id?: string;
+  readonly validation?: DataValidator[];
+  readonly serializationStrategy?: SerializationStrategy;
 };
 
 /** @public */
@@ -796,7 +796,7 @@ export interface LoaderInternal extends Loader<any> {
   __qrl: QRL<(event: RequestEventLoader) => ValueOrPromise<unknown>>;
   __id: string;
   __validators: DataValidator[] | undefined;
-  __eager: boolean;
+  __serializationStrategy: SerializationStrategy;
   (): LoaderSignal<unknown>;
 }
 

packages/qwik-router/src/runtime/src/utils.ts

@@ -7,6 +7,7 @@ import {
   _getDomContainer,
   _useInvokeContext,
   type ClientContainer,
+  type SerializationStrategy,
 } from '@qwik.dev/core/internal';
 import { createAsyncComputed$, isBrowser } from '@qwik.dev/core';
 import { loadClientData } from './use-endpoint';
@@ -105,25 +106,25 @@ export const deepFreeze = (obj: any) => {
 };
 
 export const createLoaderSignal = (
-  spaLoaderState: Record<string, unknown>,
+  loadersObject: Record<string, unknown>,
   loaderId: string,
   url: URL,
+  serializationStrategy: SerializationStrategy,
   container?: ClientContainer
 ) => {
-  // container?.$ignoredComputedValues$.add(value);
   return createAsyncComputed$(
     async () => {
-      if (isBrowser && spaLoaderState[loaderId] === _UNINITIALIZED) {
+      if (isBrowser && loadersObject[loaderId] === _UNINITIALIZED) {
         const data = await loadClientData(url, undefined, {
           loaderIds: [loaderId],
         });
-        spaLoaderState[loaderId] = data?.loaders[loaderId] ?? _UNINITIALIZED;
+        loadersObject[loaderId] = data?.loaders[loaderId] ?? _UNINITIALIZED;
       }
-      return spaLoaderState[loaderId];
+      return loadersObject[loaderId];
     },
     {
       container: container as ClientContainer,
-      serializationStrategy: 'never',
+      serializationStrategy,
     }
   );
 };