proteum 2.5.25 → 2.6.0

package/client/services/router/request/api.ts

@@ -2,6 +2,9 @@
 - DEPENDANCES
 ----------------------------------*/
 
+// Npm
+import safeStringify from 'fast-safe-stringify';
+
 // Core
 import type ClientApplication from '@client/app';
 import { buildConnectedProjectProxyPath } from '@common/connectedProjects';
@@ -44,6 +47,19 @@ const isFileValue = (value: unknown): value is Blob =>
 const isFileListValue = (value: unknown): value is FileList =>
     typeof FileList !== 'undefined' && typeof value === 'object' && value instanceof FileList;
 
+// Same rule as the server: an api fetcher names the endpoint it calls
+const isApiFetcher = (value: unknown): value is TFetcher =>
+    typeof value === 'object' && value !== null && 'method' in value && 'path' in value;
+
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+    typeof value === 'object' && value !== null && typeof (value as PromiseLike<unknown>).then === 'function';
+
+// Locally resolved data goes through JSON like SSR data and /api responses (Date to string, no undefined keys)
+const toPageData = (value: unknown): { value: unknown } | undefined => {
+    const json = safeStringify(value);
+    return json === undefined ? undefined : { value: JSON.parse(json) };
+};
+
 const containsFileValue = (value: unknown): boolean => {
     if (isFileValue(value) || isFileListValue(value)) return true;
     if (value instanceof Date) return false;
@@ -105,6 +121,9 @@ export default class ApiClient implements ApiClientService {
 
         debug && console.log('[api] Reload data', ids, params, page.fetchers);
 
+        // A deferred page reloads through its navigation: pending state, then the data step again
+        if (page.isDeferred()) return page.navigationRetry();
+
         page.fetchData()
             .then((data: TObjetDonnees) => {
                 this.set(data);
@@ -199,86 +218,115 @@ export default class ApiClient implements ApiClientService {
     }
 
     public async fetchSync(fetchers: TFetcherList, alreadyLoadedData: {}): Promise<TObjetDonnees> {
-        // Pick the fetchers where the data is needed
-        const fetchersToRun: TFetcherList = {};
-        let fetchersCount: number = 0;
+        // Only api fetchers go to the server, in one POST /api batch. Other promises resolve here,
+        // and plain values are page data as they are: sending them would only echo them back.
+        const batch: TFetcherList = {};
+        const local: TObjetDonnees = {};
+        const localPromises: Promise<void>[] = [];
+        const setLocal = (fetcherId: string, value: unknown) => {
+            const data = toPageData(value);
+            if (data) local[fetcherId] = data.value;
+        };
         // The fetcher can be undefined
-        for (const fetcherId in fetchers)
-            if (!(fetcherId in alreadyLoadedData) && fetchers[fetcherId]) {
-                fetchersToRun[fetcherId] = fetchers[fetcherId];
-                fetchersCount++;
+        for (const fetcherId in fetchers) {
+            const entry = fetchers[fetcherId];
+            if (fetcherId in alreadyLoadedData || !entry) continue;
+
+            if (isApiFetcher(entry)) batch[fetcherId] = entry;
+            else if (isThenable(entry))
+                localPromises.push(
+                    Promise.resolve(entry).then(
+                        (value) => setLocal(fetcherId, value),
+                        (error: unknown) => {
+                            // Surfaced like an /api failure
+                            this.app.handleError(error);
+                            throw error;
+                        },
+                    ),
+                );
+            else setLocal(fetcherId, entry);
+        }
+
+        // Errors will be catched in the caller
+        const [fetchedData] = await Promise.all([
+            Object.keys(batch).length === 0 ? ({} as TObjetDonnees) : this.fetchBatch(batch),
+            ...localPromises,
+        ]);
+
+        // Keep the order of the data provider keys
+        const data: TObjetDonnees = { ...alreadyLoadedData };
+        for (const fetcherId in fetchers) {
+            if (fetcherId in local) data[fetcherId] = local[fetcherId];
+            else if (fetcherId in fetchedData) data[fetcherId] = fetchedData[fetcherId];
+        }
+
+        return data;
+    }
+
+    // Fetch all the api data thanks to one http request
+    private async fetchBatch(fetchersToRun: TFetcherList): Promise<TObjetDonnees> {
+        const pendingTrace = withProfiler((runtime) =>
+            runtime.startTrace('navigation-data', {
+                fetcherIds: Object.keys(fetchersToRun),
+                label: 'Navigation data',
+                method: 'POST',
+                path: '/api',
+            }),
+        );
+
+        try {
+            const result = await this.executeDetailed<TObjetDonnees>(
+                'client-navigation',
+                'POST',
+                '/api',
+                ({ fetchers: fetchersToRun } as unknown) as TPostData,
+            );
+            const profilerModule = getProfilerModule();
+            const traceRequestId = profilerModule?.readProfilerTraceRequestId(result.response);
+
+            if (pendingTrace && traceRequestId) {
+                await profilerModule?.profilerRuntime.attachTraceByRequestId(
+                    pendingTrace.sessionId,
+                    pendingTrace.traceId,
+                    traceRequestId,
+                );
+            } else if (pendingTrace) {
+                withProfiler((runtime) =>
+                    runtime.completeTrace(pendingTrace.traceId, {
+                        durationMs: result.durationMs,
+                        status: 'completed',
+                    }),
+                );
             }
 
-        // Fetch all the api data thanks to one http request
-        const fetchedData =
-            fetchersCount === 0
-                ? {}
-                : await (async () => {
-                      const pendingTrace = withProfiler((runtime) =>
-                          runtime.startTrace('navigation-data', {
-                              fetcherIds: Object.keys(fetchersToRun),
-                              label: 'Navigation data',
-                              method: 'POST',
-                              path: '/api',
-                          }),
-                      );
-
-                      try {
-                          const result = await this.executeDetailed<TObjetDonnees>(
-                              'client-navigation',
-                              'POST',
-                              '/api',
-                              ({ fetchers: fetchersToRun } as unknown) as TPostData,
-                          );
-                          const profilerModule = getProfilerModule();
-                          const traceRequestId = profilerModule?.readProfilerTraceRequestId(result.response);
-
-                          if (pendingTrace && traceRequestId) {
-                              await profilerModule?.profilerRuntime.attachTraceByRequestId(
-                                  pendingTrace.sessionId,
-                                  pendingTrace.traceId,
-                                  traceRequestId,
-                              );
-                          } else if (pendingTrace) {
-                              withProfiler((runtime) =>
-                                  runtime.completeTrace(pendingTrace.traceId, {
-                                      durationMs: result.durationMs,
-                                      status: 'completed',
-                                  }),
-                              );
-                          }
-
-                          const responseData: TObjetDonnees = {};
-                          for (const id in result.data) responseData[id] = result.data[id];
-                          return responseData;
-                      } catch (e) {
-                          const profilerModule = getProfilerModule();
-                          const errorResponse = (e as Error & { response?: Response }).response;
-                          const traceRequestId = errorResponse ? profilerModule?.readProfilerTraceRequestId(errorResponse) : undefined;
-                          if (pendingTrace && traceRequestId) {
-                              await profilerModule?.profilerRuntime.attachTraceByRequestId(
-                                  pendingTrace.sessionId,
-                                  pendingTrace.traceId,
-                                  traceRequestId,
-                              );
-                          }
-                          withProfiler((runtime) =>
-                              runtime.completeTrace(pendingTrace?.traceId, {
-                                  errorMessage: e instanceof Error ? e.message : String(e),
-                                  status: 'error',
-                              }),
-                          );
-
-                          // API Error hook
-                          this.app.handleError(e);
-
-                          throw e;
-                      }
-                  })();
+            const responseData: TObjetDonnees = {};
+            for (const id in result.data) responseData[id] = result.data[id];
+            return responseData;
+        } catch (e) {
+            const profilerModule = getProfilerModule();
+            const errorResponse = (e as Error & { response?: Response }).response;
+            const traceRequestId = errorResponse
+                ? profilerModule?.readProfilerTraceRequestId(errorResponse)
+                : undefined;
+            if (pendingTrace && traceRequestId) {
+                await profilerModule?.profilerRuntime.attachTraceByRequestId(
+                    pendingTrace.sessionId,
+                    pendingTrace.traceId,
+                    traceRequestId,
+                );
+            }
+            withProfiler((runtime) =>
+                runtime.completeTrace(pendingTrace?.traceId, {
+                    errorMessage: e instanceof Error ? e.message : String(e),
+                    status: 'error',
+                }),
+            );
 
-        // Errors will be catched in the caller
+            // API Error hook
+            this.app.handleError(e);
 
-        return { ...alreadyLoadedData, ...fetchedData };
+            throw e;
+        }
     }
 
     public configure = (...[method, path, data, options = {}]: TFetcherArgs) => {

package/client/services/router/response/index.tsx

@@ -112,7 +112,12 @@ export default class ClientPageResponse<
         if (existingContext === undefined) {
             this.request.router.context = newContext;
         } else {
+            // The page on screen stays the context's page until a navigation commits (the router's commit port
+            //  sets it): this response may belong to a navigation that never does (superseded, failed), and
+            //  api.set and api.reload read the page from the context.
+            const pageOnScreen = existingContext.page;
             Object.assign(existingContext, newContext);
+            existingContext.page = pageOnScreen;
         }
 
         return newContext;

package/client/services/router/response/page.ts

@@ -7,8 +7,10 @@ import type { ComponentChild } from 'preact';
 
 // Core
 import type { Layout, TErrorRoute, TRoute } from '@common/router';
-import PageResponse, { TFrontRenderer } from '@common/router/response/page';
+import type { TFetcherList } from '@common/router/request/api';
+import PageResponse, { type TPageNavigation, type TPageRenderer } from '@common/router/response/page';
 import { isClientRequest } from '../request';
+import { shouldDeferNavigation } from '../navigation';
 
 // Specific
 import type ClientRouter from '..';
@@ -35,7 +37,7 @@ export default class ClientPage<TRouter extends ClientRouter<any, any> = ClientR
 
     public constructor(
         public route: TClientPageRouteLike<TRouter>,
-        public component: TFrontRenderer,
+        public component: TPageRenderer,
         public context: TRouterContext<TRouter, TRouter['app']>,
         public layout?: Layout,
     ) {
@@ -45,16 +47,22 @@ export default class ClientPage<TRouter extends ClientRouter<any, any> = ClientR
         this.scrollToId = isClientRequest(context.request) ? context.request.hash : undefined;
     }
 
-    public async preRender(data?: TObjetDonnees) {
+    // `fetchers`: the result of an earlier prepareFetchers() call, so the data providers do not run twice
+    public async preRender(data?: TObjetDonnees, fetchers?: TFetcherList) {
         // Add the page to the context
         this.context.page = this;
 
         // Data succesfully loaded
-        this.context.data = this.data = data || (await this.fetchData());
+        this.context.data = this.data = data || (await this.fetchData(fetchers));
 
         return this;
     }
 
+    // The page swaps in before its data: deferred router mode, deferred page option and a data loader
+    public isDeferred() {
+        return shouldDeferNavigation(this.context.Router.config.navigation?.mode, this.route);
+    }
+
     /*----------------------------------
     - ACTIONS
     ----------------------------------*/
@@ -68,6 +76,14 @@ export default class ClientPage<TRouter extends ClientRouter<any, any> = ClientR
     public setAllData(callback: (data: { [k: string]: any }) => void) {
         console.warn(`page.setAllData not yet attached to the page Reatc component.`);
     }
+    // Re-renders the page with this.navigation. Bound by the Page component, like setAllData
+    public setNavigation(navigation: TPageNavigation) {}
+
+    // Re-runs the data step of a deferred page (see createNavigationSequencer)
+    public navigationRetry() {
+        this.navigation.retry();
+    }
+
     public setData(key: string, value: ((value: any) => void) | any) {
         this.setAllData((old) => ({ ...old, [key]: typeof value === 'function' ? value(old[key]) : value }));
     }

package/common/router/contracts.ts

@@ -3,7 +3,7 @@
 ----------------------------------*/
 
 // Core
-import type { TFrontRenderer, TPageDataProvider } from './response/page';
+import type { TPageDataProvider, TPageRenderer } from './response/page';
 import type { TRouteOptions } from '.';
 
 /*----------------------------------
@@ -16,7 +16,7 @@ export type TRegisterPageArgs<TProvidedData extends {} = {}, TPageOptions extend
         path: string,
         options: Partial<TPageOptions>,
         data: TPageDataProvider<TProvidedData> | null,
-        renderer: TFrontRenderer<TProvidedData>,
+        renderer: TPageRenderer<TProvidedData>,
     ];
 
 // Serialized SSR route description exchanged between build output and runtime.

package/common/router/definitions.ts

@@ -7,7 +7,7 @@ import type { Request, Response, NextFunction } from 'express';
 
 // Core
 import type { TAnyRouter, TRouterContext, TRouteHttpMethod } from '@server/services/router';
-import type { TFrontRenderer, TPageDataProvider } from './response/page';
+import type { TDeferredFrontRenderer, TFrontRenderer, TPageDataProvider, TPageRenderer } from './response/page';
 import type { TRouteOptions } from '.';
 
 /*----------------------------------
@@ -27,7 +27,7 @@ export type TPageRouteDefinition<TProvidedData extends {} = {}> = {
     path: string;
     options: Partial<TRouteOptions>;
     data: TPageDataProvider<TProvidedData> | null;
-    render: TFrontRenderer<TProvidedData>;
+    render: TPageRenderer<TProvidedData>;
 };
 
 export type TErrorRouteDefinition = {
@@ -75,18 +75,36 @@ export type TRouteDefinitionRegistrar = {
 - HELPERS
 ----------------------------------*/
 
-export const definePageRoute = <TProvidedData extends {} = {}>({
-    path,
-    options,
-    data,
-    render,
-}: Omit<TPageRouteDefinition<TProvidedData>, 'kind'>): TPageRouteDefinition<TProvidedData> => ({
-    kind: 'page',
+// A page declaring `options.navigation: 'deferred'` renders with TDeferredFrontRenderer:
+//  every data key may be undefined, plus the `navigation` prop
+export function definePageRoute<TProvidedData extends {} = {}>(definition: {
+    path: string;
+    options: Partial<TRouteOptions> & { navigation: 'deferred' };
+    data: TPageDataProvider<TProvidedData> | null;
+    render: TDeferredFrontRenderer<TProvidedData>;
+}): TPageRouteDefinition<TProvidedData>;
+// The blocking overload refuses `navigation: 'deferred'`: a deferred page whose render does not fit the deferred
+//  renderer (an annotated props type) would otherwise fall through to it and type its data as always defined
+export function definePageRoute<TProvidedData extends {} = {}>(definition: {
+    path: string;
+    options: Omit<Partial<TRouteOptions>, 'navigation'> & { navigation?: 'blocking' };
+    data: TPageDataProvider<TProvidedData> | null;
+    render: TFrontRenderer<TProvidedData>;
+}): TPageRouteDefinition<TProvidedData>;
+export function definePageRoute<TProvidedData extends {} = {}>({
     path,
     options,
     data,
     render,
-});
+}: Omit<TPageRouteDefinition<TProvidedData>, 'kind'>): TPageRouteDefinition<TProvidedData> {
+    return {
+        kind: 'page',
+        path,
+        options,
+        data,
+        render,
+    };
+}
 
 export const defineErrorRoute = ({
     code,

package/common/router/index.ts

@@ -115,6 +115,8 @@ export type TRouteOptions = {
     whenStatic?: boolean; // If true, the route is only executed even if the page is cached
     canonicalParams?: string[]; // For SEO + unique ID for static cache
     layout?: false | string; // The nale of the layout
+    // Client navigation: 'deferred' swaps the page in before its data when the router runs in deferred mode
+    navigation?: 'deferred' | 'blocking';
 
     // To cleanup
     TESTING?: boolean;

package/common/router/pageData.ts

@@ -18,18 +18,23 @@ export const routeOptionKeys = [
     'whenStatic',
     'canonicalParams',
     'layout',
+    'navigation',
     'TESTING',
     'logging',
 ] as const satisfies (keyof TRouteOptions)[];
 
 export const reservedRouteOptionKeys = ['id', 'filepath', 'sourceLocation', 'data'] as const;
 
+// `navigation` stays a legal data key on blocking pages, where apps already return one.
+// A deferred page reserves it for its navigation render prop (see validateDeferredDataKeys).
+const dataReservedRouteOptionKeys = routeOptionKeys.filter((key) => key !== 'navigation');
+
 const routeOptionKeysSet = new Set<string>(routeOptionKeys);
 const reservedRouteOptionKeysSet = new Set<string>(reservedRouteOptionKeys);
 const reservedPageDataKeys = new Set<string>([
-    ...routeOptionKeys,
+    ...dataReservedRouteOptionKeys,
     ...reservedRouteOptionKeys,
-    ...routeOptionKeys.map((key) => `_${key}`),
+    ...dataReservedRouteOptionKeys.map((key) => `_${key}`),
     ...reservedRouteOptionKeys.map((key) => `_${key}`),
 ]);
 
@@ -51,6 +56,17 @@ export const getRouteOptionKey = (key: string) => {
     return routeOptionKeysSet.has(key) ? (key as keyof TRouteOptions) : null;
 };
 
+// Page and layout data both reach the render props, where a deferred page reads `navigation`
+export const validateDeferredDataKeys = (route: TAnyRoute, result: object, source: string) => {
+    if (route.options.navigation !== 'deferred' || !result || !('navigation' in result)) return;
+
+    throw new Error(
+        `${source} for ${formatRouteTarget(route)} in ${formatRouteSource(route)} ` +
+            `cannot return key "navigation": a page declaring navigation: 'deferred' receives its ` +
+            `navigation state under that render prop. Rename the data key.`,
+    );
+};
+
 export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
     if (!result || typeof result !== 'object' || Array.isArray(result)) {
         throw new Error(
@@ -59,6 +75,8 @@ export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
         );
     }
 
+    validateDeferredDataKeys(route, result, 'definePageRoute data');
+
     for (const key of Object.keys(result)) {
         if (!reservedPageDataKeys.has(key)) continue;
 

package/common/router/response/page.ts

@@ -10,7 +10,7 @@ import type { Thing } from 'schema-dts';
 import type { ClientContext } from '@/client/context';
 import { ClientOrServerRouter, TErrorRoute, TPageErrorRoute, TPageRoute, TRoute, TRouteOptions } from '@common/router';
 import type { TFetcher, TFetcherList } from '@common/router/request/api';
-import { validatePageDataResult } from '@common/router/pageData';
+import { validateDeferredDataKeys, validatePageDataResult } from '@common/router/pageData';
 
 /*----------------------------------
 - TYPES
@@ -61,6 +61,65 @@ export type TFrontRenderer<
         TAdditionnalData & { context: TPageRenderContext; data: { [key: string]: PrimitiveValue } },
 ) => VNode<any> | null;
 
+// Navigation state of a page that declares navigation: 'deferred'.
+// `since` is the Date.now() timestamp of the last status change; `stale` means the previous data is still on screen.
+// `reloading` means the data step runs again for a navigation whose data already reached the screen (api.reload,
+//  or retry() after ready): the stale data is this page's own, never a previous page's under the new URL.
+type TPageNavigationBase = { since: number; retry: () => void };
+
+export type TPageNavigation =
+    | (TPageNavigationBase & { status: 'ready'; pending: false; stale: false; reloading: false; error: null })
+    | (TPageNavigationBase & { status: 'pending'; pending: true; stale: boolean; reloading: boolean; error: null })
+    | (TPageNavigationBase & { status: 'error'; pending: false; stale: boolean; reloading: boolean; error: Error });
+
+export type TPageNavigationState =
+    | { status: 'ready' }
+    | { status: 'pending'; stale: boolean; reloading?: boolean }
+    | { status: 'error'; stale: boolean; reloading?: boolean; error: Error };
+
+export const createPageNavigation = (state: TPageNavigationState, retry: () => void = () => {}): TPageNavigation => {
+    const base = { since: Date.now(), retry };
+
+    if (state.status === 'ready')
+        return { ...base, status: 'ready', pending: false, stale: false, reloading: false, error: null };
+    if (state.status === 'pending')
+        return {
+            ...base,
+            status: 'pending',
+            pending: true,
+            stale: state.stale,
+            reloading: state.reloading === true,
+            error: null,
+        };
+    return {
+        ...base,
+        status: 'error',
+        pending: false,
+        stale: state.stale,
+        reloading: state.reloading === true,
+        error: state.error,
+    };
+};
+
+// Page data as a deferred page sees it: every key is undefined until the navigation is ready
+export type TDeferredPageData<TProvidedData extends {} = {}> = {
+    [Property in keyof TResolvedPageData<TProvidedData>]: TResolvedPageData<TProvidedData>[Property] | undefined;
+};
+
+// The renderer of a page that declares navigation: 'deferred'
+export type TDeferredFrontRenderer<TProvidedData extends {} = {}> = (
+    context: TPageRenderContext &
+        TDeferredPageData<TProvidedData> & {
+            context: TPageRenderContext;
+            data: { [key: string]: PrimitiveValue };
+            navigation: TPageNavigation;
+        },
+) => VNode<any> | null;
+
+export type TPageRenderer<TProvidedData extends {} = {}> =
+    | TFrontRenderer<TProvidedData>
+    | TDeferredFrontRenderer<TProvidedData>;
+
 // Script or CSS resource
 export type TPageResource = { id: string; attrs?: TObjetDonnees } & (
     | { inline: string }
@@ -100,10 +159,11 @@ export default abstract class PageResponse<
     // Data
     public fetchers: TFetcherList = {};
     public data: TObjetDonnees = {};
+    public navigation: TPageNavigation = createPageNavigation({ status: 'ready' });
 
     public constructor(
         public route: TRouteLike,
-        public renderer: TFrontRenderer,
+        public renderer: TPageRenderer,
         public context: TContext,
     ) {
         this.chunkId = context.route.options.id;
@@ -129,23 +189,29 @@ export default abstract class PageResponse<
         return data as TFetcherList;
     }
 
-    public async fetchData() {
+    // Runs the page and layout data providers without fetching anything
+    public prepareFetchers() {
         this.fetchers = this.createFetchers();
         this.bodyId = this.route.options.bodyId;
 
-        // Fetch layout data
+        // Layout data
         if (this.layout?.data) {
             const layoutContext = {
                 ...this.context,
                 data: this.context.request.data,
             } as unknown as Parameters<typeof this.layout.data>[0];
             const fetchers = this.layout.data(layoutContext);
+            validateDeferredDataKeys(this.route, fetchers, 'Layout data');
             this.fetchers = { ...this.fetchers, ...fetchers };
         }
 
-        // Fetch page data
-        debug && console.log(`[router][page] Fetching api data:` + Object.keys(this.fetchers));
-        this.data = await this.context.request.api.fetchSync(this.fetchers, this.data);
+        return this.fetchers;
+    }
+
+    // Pass the fetchers of an earlier prepareFetchers() call to skip running the providers again
+    public async fetchData(fetchers: TFetcherList = this.prepareFetchers()) {
+        debug && console.log(`[router][page] Fetching api data:` + Object.keys(fetchers));
+        this.data = await this.context.request.api.fetchSync(fetchers, this.data);
 
         return this.data;
     }