@tramvai/module-page-render-mode 7.5.3 → 7.7.0

package/lib/staticPages.js

@@ -6,7 +6,6 @@ var core = require('@tramvai/core');
 var tokensCommon = require('@tramvai/tokens-common');
 var tokensServerPrivate = require('@tramvai/tokens-server-private');
 var tokensRouter = require('@tramvai/tokens-router');
-var moduleClientHints = require('@tramvai/module-client-hints');
 var tokensServer = require('@tramvai/tokens-server');
 var tokensMetrics = require('@tramvai/tokens-metrics');
 var papi = require('@tramvai/papi');
@@ -16,21 +15,21 @@ var getPageRenderMode = require('./utils/getPageRenderMode.js');
 var cacheKey = require('./utils/cacheKey.js');
 var backgroundFetchService = require('./staticPages/backgroundFetchService.js');
 var staticPagesService = require('./staticPages/staticPagesService.js');
+var fileSystemCache = require('./staticPages/fileSystemCache.js');
+var privateTokens = require('./private-tokens.js');
 
-const STATIC_PAGES_BACKGROUND_FETCH_SERVICE = core.createToken();
-const STATIC_PAGES_GET_CACHE_KEY_TOKEN = core.createToken();
-const STATIC_PAGES_CACHE_HIT_METRIC_TOKEN = core.createToken();
-const STATIC_PAGES_SERVICE = core.createToken();
 const staticPagesProviders = [
     core.provide({
-        provide: STATIC_PAGES_CACHE_HIT_METRIC_TOKEN,
+        provide: privateTokens.STATIC_PAGES_CACHE_METRICS_TOKEN,
         scope: core.Scope.SINGLETON,
         useFactory: ({ metrics }) => {
-            return metrics.counter({
-                name: 'static_pages_cache_hit',
-                help: 'Total static pages returned from cache',
-                labelNames: [],
-            });
+            return {
+                hit: metrics.counter({
+                    name: 'static_pages_cache_hit',
+                    help: 'Total static pages returned from cache',
+                    labelNames: [],
+                }),
+            };
         },
         deps: {
             metrics: tokensMetrics.METRICS_MODULE_TOKEN,
@@ -54,40 +53,143 @@ const staticPagesProviders = [
         provide: tokens.STATIC_PAGES_OPTIONS_TOKEN,
         useValue: {
             // @TODO: unique ttl per pages
-            ttl: 60 * 1000,
-            // @TODO: too much, better save to file-system
-            maxSize: 1000,
+            ttl: 5 * 60 * 1000,
+            maxSize: 100,
+            allowStale: true,
+            allowedHeaders: [],
         },
     }),
     core.provide({
-        provide: STATIC_PAGES_GET_CACHE_KEY_TOKEN,
-        useFactory: ({ requestManager, userAgent }) => {
+        provide: tokens.STATIC_PAGES_KEY_TOKEN,
+        useFactory: () => {
             return () => {
-                const deviceType = userAgent.mobileOS ? 'mobile' : 'desktop';
-                return cacheKey.getCacheKey({
-                    method: requestManager.getMethod(),
-                    host: requestManager.getHost(),
-                    path: requestManager.getParsedUrl().pathname,
-                    deviceType,
-                });
+                return '';
+            };
+        },
+    }),
+    core.provide({
+        provide: tokens.STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN,
+        useValue: ({ ttl }) => {
+            // prevent browser caching for pages in development mode
+            if (process.env.NODE_ENV === 'development') {
+                return 'private, no-cache, no-store, max-age=0, must-revalidate';
+            }
+            return `public, max-age=${ttl / 1000}`;
+        },
+    }),
+    core.provide({
+        provide: tokens.STATIC_PAGES_FS_CACHE_ENABLED,
+        useValue: () => false,
+    }),
+    core.provide({
+        provide: tokens.STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN,
+        useFactory: () => {
+            return {
+                directory: process.env.__TRAMVAI_OUTPUT_STATIC ?? 'dist/static',
+                maxSize: 1000,
+                ttl: 5 * 60 * 1000,
+                allowStale: true,
+            };
+        },
+    }),
+    core.provide({
+        provide: privateTokens.STATIC_PAGES_FS_CACHE_METRICS_TOKEN,
+        scope: core.Scope.SINGLETON,
+        useFactory: ({ metrics }) => {
+            return {
+                hit: metrics.counter({
+                    name: 'static_pages_fs_cache_hit',
+                    help: 'Total static pages returned from file system cache',
+                    labelNames: [],
+                }),
+                miss: metrics.counter({
+                    name: 'static_pages_fs_cache_miss',
+                    help: 'Total static pages not found in file system cache',
+                    labelNames: [],
+                }),
+                size: metrics.gauge({
+                    name: 'static_pages_fs_cache_size',
+                    help: 'Number of files in file system cache',
+                    labelNames: [],
+                }),
+                bytes: metrics.gauge({
+                    name: 'static_pages_fs_cache_bytes',
+                    help: 'Total size of files in file system cache in bytes',
+                    labelNames: [],
+                }),
             };
         },
         deps: {
-            requestManager: tokensCommon.REQUEST_MANAGER_TOKEN,
-            userAgent: moduleClientHints.USER_AGENT_TOKEN,
+            metrics: tokensMetrics.METRICS_MODULE_TOKEN,
+        },
+    }),
+    core.provide({
+        provide: privateTokens.STATIC_PAGES_FS_CACHE_TOKEN,
+        scope: core.Scope.SINGLETON,
+        useFactory: ({ fsCacheEnabled, fsCacheOptions, logger, metrics }) => {
+            if (!fsCacheEnabled()) {
+                return null;
+            }
+            return new fileSystemCache.FileSystemCache({
+                ...fsCacheOptions,
+                logger,
+                metrics,
+            });
+        },
+        deps: {
+            fsCacheEnabled: tokens.STATIC_PAGES_FS_CACHE_ENABLED,
+            fsCacheOptions: tokens.STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN,
+            logger: tokensCommon.LOGGER_TOKEN,
+            metrics: privateTokens.STATIC_PAGES_FS_CACHE_METRICS_TOKEN,
+        },
+    }),
+    core.provide({
+        provide: core.commandLineListTokens.init,
+        multi: true,
+        scope: core.Scope.SINGLETON,
+        useFactory: ({ fsCache, fsCacheEnabled }) => {
+            return async function initFileSystemCache() {
+                if (fsCacheEnabled() && fsCache) {
+                    await fsCache.init();
+                }
+            };
+        },
+        deps: {
+            fsCache: privateTokens.STATIC_PAGES_FS_CACHE_TOKEN,
+            fsCacheEnabled: tokens.STATIC_PAGES_FS_CACHE_ENABLED,
         },
     }),
     core.provide({
         provide: tokens.STATIC_PAGES_SHOULD_USE_CACHE,
         useFactory: ({ requestManager }) => {
             return () => {
-                return !requestManager.getHeader('x-tramvai-static-page-revalidate');
+                return (!requestManager.getHeader('x-tramvai-static-page-revalidate') &&
+                    !requestManager.getHeader('x-tramvai-prerender'));
             };
         },
         deps: {
             requestManager: tokensCommon.REQUEST_MANAGER_TOKEN,
         },
     }),
+    core.provide({
+        provide: privateTokens.STATIC_PAGES_RESOLVE_PAGE_RENDER_MODE,
+        useFactory: ({ requestManager, pageService, router, defaultRenderMode, fileSystemCache }) => {
+            return () => getPageRenderMode.getPageRenderMode({
+                pageService,
+                router,
+                requestManager,
+                defaultRenderMode,
+                fileSystemCache,
+            });
+        },
+        deps: {
+            requestManager: tokensCommon.REQUEST_MANAGER_TOKEN,
+            router: core.optional(tokensRouter.ROUTER_TOKEN),
+            pageService: core.optional(tokensRouter.PAGE_SERVICE_TOKEN),
+            defaultRenderMode: tokens.PAGE_RENDER_DEFAULT_MODE,
+            fileSystemCache: core.optional(privateTokens.STATIC_PAGES_FS_CACHE_TOKEN),
+        },
+    }),
     core.provide({
         provide: tokens.STATIC_PAGES_BACKGROUND_FETCH_ENABLED,
         useValue: () => {
@@ -101,32 +203,35 @@ const staticPagesProviders = [
         },
     }),
     core.provide({
-        provide: STATIC_PAGES_BACKGROUND_FETCH_SERVICE,
+        provide: privateTokens.STATIC_PAGES_BACKGROUND_FETCH_SERVICE,
         scope: core.Scope.SINGLETON,
         useClass: backgroundFetchService.BackgroundFetchService,
         deps: {
             logger: tokensCommon.LOGGER_TOKEN,
+            envManager: tokensCommon.ENV_MANAGER_TOKEN,
             backgroundFetchEnabled: tokens.STATIC_PAGES_BACKGROUND_FETCH_ENABLED,
         },
     }),
     core.provide({
-        provide: STATIC_PAGES_SERVICE,
+        provide: tokens.STATIC_PAGES_SERVICE,
         scope: core.Scope.REQUEST,
         useClass: staticPagesService.StaticPagesService,
         deps: {
-            getCacheKey: STATIC_PAGES_GET_CACHE_KEY_TOKEN,
+            staticPagesKey: tokens.STATIC_PAGES_KEY_TOKEN,
             requestManager: tokensCommon.REQUEST_MANAGER_TOKEN,
             responseManager: tokensCommon.RESPONSE_MANAGER_TOKEN,
             response: tokensServerPrivate.FASTIFY_RESPONSE,
             environmentManager: tokensCommon.ENV_MANAGER_TOKEN,
-            userAgent: moduleClientHints.USER_AGENT_TOKEN,
             logger: tokensCommon.LOGGER_TOKEN,
             cache: tokens.STATIC_PAGES_CACHE_TOKEN,
+            fsCache: privateTokens.STATIC_PAGES_FS_CACHE_TOKEN,
+            fsCacheEnabled: tokens.STATIC_PAGES_FS_CACHE_ENABLED,
             modifyCache: { token: tokens.STATIC_PAGES_MODIFY_CACHE, optional: true },
             shouldUseCache: tokens.STATIC_PAGES_SHOULD_USE_CACHE,
-            backgroundFetchService: STATIC_PAGES_BACKGROUND_FETCH_SERVICE,
+            backgroundFetchService: privateTokens.STATIC_PAGES_BACKGROUND_FETCH_SERVICE,
             options: tokens.STATIC_PAGES_OPTIONS_TOKEN,
             cache5xxResponse: tokens.STATIC_PAGES_CACHE_5xx_RESPONSE,
+            cacheControlFactory: tokens.STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN,
         },
     }),
     core.provide({
@@ -139,22 +244,61 @@ const staticPagesProviders = [
                     provide: staticPagesCommandLine
                         ? core.commandLineListTokens[staticPagesCommandLine]
                         : core.commandLineListTokens.customerStart,
-                    useFactory: ({ staticPagesService, staticPagesCacheHitMetric, logger }) => {
-                        logger('static-pages');
-                        return function staticPagesFromCache() {
-                            if (staticPagesService.shouldUseCache()) {
-                                staticPagesService.respond(() => {
-                                    // @TODO: маска урла на этом этапе?
-                                    staticPagesCacheHitMetric.inc();
-                                    throw new error.StopCommandLineRunnerError();
+                    useFactory: ({ staticPagesService, staticPagesCacheMetrics, logger, requestManager, responseManager, staticPagesKey, linkPrefetchManager, resolvePageRenderMode, router, pageRegistry, }) => {
+                        const log = logger('static-pages');
+                        return async function staticPagesFromCache() {
+                            const isPrerenderRequest = !!requestManager.getHeader('x-tramvai-prerender');
+                            const { pathname } = requestManager.getParsedUrl();
+                            const route = router?.getCurrentRoute() ?? router?.resolve(pathname);
+                            // prefetch route only for `tramvai static` because it can be async and slow in runtime
+                            if (isPrerenderRequest) {
+                                log.debug(`Should prefetch route and component to determine if page is static: ${pathname}`);
+                                await linkPrefetchManager.prefetch(pathname);
+                                // for already resolved routes we can prefetch page component in runtime without significant performance impact
+                            }
+                            else if (route) {
+                                log.debug(`Should prefetch page component to determine if page is static: ${pathname}`);
+                                await pageRegistry?.resolve(route).catch((error) => {
+                                    if (!route.redirect) {
+                                        log.info(`${pathname} page component for prefetch failed: ${error.message}`);
+                                    }
                                 });
                             }
+                            const isStatic = resolvePageRenderMode() === 'static';
+                            const shouldUseCache = staticPagesService.shouldUseCache();
+                            if (isStatic) {
+                                responseManager.setHeader('X-Tramvai-Static-Page-Key', staticPagesKey());
+                                // we need to tell for `tramvai static` prerendering command that this page has `static` render mode,
+                                // and also provide route info to generate list of static routes in `dist/client/meta.json`.
+                                // this list will be used in `STATIC_PAGES_RESOLVE_PAGE_RENDER_MODE` to determine render mode of the page in runtime before route resolving.
+                                if (isPrerenderRequest && route) {
+                                    responseManager.setHeader('X-Tramvai-Static-Page-Route', JSON.stringify(route));
+                                }
+                                if (shouldUseCache) {
+                                    log.debug(`Should use static pages cache: ${pathname}`);
+                                    await staticPagesService.respond(() => {
+                                        log.debug(`Successful static page response from cache: ${pathname}`);
+                                        staticPagesCacheMetrics.hit.inc();
+                                        throw new error.StopCommandLineRunnerError();
+                                    });
+                                }
+                                else {
+                                    log.debug(`Static pages cache is not used for this request: ${pathname}`);
+                                }
+                            }
                         };
                     },
                     deps: {
-                        staticPagesService: STATIC_PAGES_SERVICE,
-                        staticPagesCacheHitMetric: STATIC_PAGES_CACHE_HIT_METRIC_TOKEN,
+                        staticPagesService: tokens.STATIC_PAGES_SERVICE,
+                        staticPagesCacheMetrics: privateTokens.STATIC_PAGES_CACHE_METRICS_TOKEN,
                         logger: tokensCommon.LOGGER_TOKEN,
+                        requestManager: tokensCommon.REQUEST_MANAGER_TOKEN,
+                        responseManager: tokensCommon.RESPONSE_MANAGER_TOKEN,
+                        staticPagesKey: tokens.STATIC_PAGES_KEY_TOKEN,
+                        linkPrefetchManager: tokensRouter.LINK_PREFETCH_MANAGER_TOKEN,
+                        resolvePageRenderMode: privateTokens.STATIC_PAGES_RESOLVE_PAGE_RENDER_MODE,
+                        router: core.optional(tokensRouter.ROUTER_TOKEN),
+                        pageRegistry: core.optional(tokensRouter.PAGE_REGISTRY_TOKEN),
                     },
                 });
             };
@@ -164,38 +308,57 @@ const staticPagesProviders = [
             staticPagesCommandLine: { token: tokens.STATIC_PAGES_COMMAND_LINE, optional: true },
         },
     }),
-    core.provide({
-        provide: core.commandLineListTokens.clear,
-        useFactory: ({ staticPagesService, pageService, defaultRenderMode }) => {
-            return function cacheStaticPages() {
-                const isStaticPage = getPageRenderMode.getPageRenderMode({ pageService, defaultRenderMode }) === 'static';
-                if (!isStaticPage) {
-                    return;
-                }
-                staticPagesService.revalidate();
-            };
-        },
-        deps: {
-            staticPagesService: STATIC_PAGES_SERVICE,
-            pageService: tokensRouter.PAGE_SERVICE_TOKEN,
-            defaultRenderMode: tokens.PAGE_RENDER_DEFAULT_MODE,
-        },
-    }),
     core.provide({
         provide: tokensServer.SERVER_MODULE_PAPI_PRIVATE_ROUTE,
-        useFactory: ({ staticPagesCache }) => {
+        useFactory: ({ staticPagesCache, fsCache, fsCacheEnabled, logger }) => {
             return papi.createPapiMethod({
                 path: '/revalidate/',
                 method: 'post',
-                async handler({ body = {} }) {
-                    const { path } = body;
-                    const pathKey = `/${path}/`;
-                    if (!path) {
+                async handler({ body = {}, headers }) {
+                    const log = logger('static-pages:revalidate');
+                    const { pathname, key = '' } = body;
+                    if (!pathname) {
+                        log.info({
+                            event: 'revalidate-all',
+                            request: body,
+                            headers,
+                        });
                         staticPagesCache.clear();
+                        if (fsCacheEnabled() && fsCache) {
+                            await fsCache.clear();
+                        }
                     }
-                    else if (staticPagesCache.has(pathKey)) {
-                        staticPagesCache.set(pathKey, new Map());
-                        // @TODO: revalidate request with background fetch?
+                    else {
+                        const cacheKey$1 = cacheKey.getCacheKey({ pathname, key });
+                        log.info({
+                            event: 'revalidate-path',
+                            request: body,
+                            cacheKey: cacheKey$1,
+                        });
+                        if (key) {
+                            if (staticPagesCache.has(cacheKey$1)) {
+                                staticPagesCache.delete(cacheKey$1);
+                            }
+                            if (fsCacheEnabled() && fsCache && fsCache.has(cacheKey$1)) {
+                                await fsCache.delete(cacheKey$1);
+                            }
+                        }
+                        else {
+                            const memoryCaches = staticPagesCache.dump();
+                            for (const entry of memoryCaches) {
+                                if (entry[0].startsWith(`${pathname}^`)) {
+                                    staticPagesCache.delete(entry[0]);
+                                }
+                            }
+                            if (fsCacheEnabled() && fsCache) {
+                                const fsCaches = fsCache.dump();
+                                for (const entry of fsCaches) {
+                                    if (entry[0].startsWith(`${pathname}^`)) {
+                                        fsCache.delete(entry[0]);
+                                    }
+                                }
+                            }
+                        }
                     }
                     return 'Success';
                 },
@@ -203,12 +366,11 @@ const staticPagesProviders = [
         },
         deps: {
             staticPagesCache: tokens.STATIC_PAGES_CACHE_TOKEN,
+            fsCache: privateTokens.STATIC_PAGES_FS_CACHE_TOKEN,
+            fsCacheEnabled: tokens.STATIC_PAGES_FS_CACHE_ENABLED,
+            logger: tokensCommon.LOGGER_TOKEN,
         },
     }),
 ];
 
-exports.STATIC_PAGES_BACKGROUND_FETCH_SERVICE = STATIC_PAGES_BACKGROUND_FETCH_SERVICE;
-exports.STATIC_PAGES_CACHE_HIT_METRIC_TOKEN = STATIC_PAGES_CACHE_HIT_METRIC_TOKEN;
-exports.STATIC_PAGES_GET_CACHE_KEY_TOKEN = STATIC_PAGES_GET_CACHE_KEY_TOKEN;
-exports.STATIC_PAGES_SERVICE = STATIC_PAGES_SERVICE;
 exports.staticPagesProviders = staticPagesProviders;

package/lib/tokens.browser.js

@@ -14,5 +14,19 @@ const STATIC_PAGES_OPTIONS_TOKEN = createToken('static pages options');
 const STATIC_PAGES_COMMAND_LINE = createToken('static pages command line');
 const STATIC_PAGES_MODIFY_CACHE = createToken('static pages modify cache', { multi: true });
 const STATIC_PAGES_CACHE_5xx_RESPONSE = createToken('static pages cache 5xx response');
+/**
+ * Token that computes the current cache key for a page variation
+ * For example: 'mobile', 'desktop', or empty string for default variation
+ * Used in combination with pathname to create the full cache key
+ */
+const STATIC_PAGES_KEY_TOKEN = createToken('static pages key', {
+    scope: Scope.REQUEST,
+});
+const STATIC_PAGES_FS_CACHE_ENABLED = createToken('static pages file system cache enabled', { scope: Scope.SINGLETON });
+const STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN = createToken('static pages file system cache options', { scope: Scope.SINGLETON });
+const STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN = createToken('static pages cache-control header', {
+    scope: Scope.REQUEST,
+});
+const STATIC_PAGES_SERVICE = createToken('static pages service');
 
-export { PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT, PAGE_RENDER_DEFAULT_MODE, PAGE_RENDER_FALLBACK_COMPONENT_PREFIX, PAGE_RENDER_WRAPPER_TYPE, STATIC_PAGES_BACKGROUND_FETCH_ENABLED, STATIC_PAGES_CACHE_5xx_RESPONSE, STATIC_PAGES_CACHE_TOKEN, STATIC_PAGES_COMMAND_LINE, STATIC_PAGES_MODIFY_CACHE, STATIC_PAGES_OPTIONS_TOKEN, STATIC_PAGES_SHOULD_USE_CACHE };
+export { PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT, PAGE_RENDER_DEFAULT_MODE, PAGE_RENDER_FALLBACK_COMPONENT_PREFIX, PAGE_RENDER_WRAPPER_TYPE, STATIC_PAGES_BACKGROUND_FETCH_ENABLED, STATIC_PAGES_CACHE_5xx_RESPONSE, STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN, STATIC_PAGES_CACHE_TOKEN, STATIC_PAGES_COMMAND_LINE, STATIC_PAGES_FS_CACHE_ENABLED, STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN, STATIC_PAGES_KEY_TOKEN, STATIC_PAGES_MODIFY_CACHE, STATIC_PAGES_OPTIONS_TOKEN, STATIC_PAGES_SERVICE, STATIC_PAGES_SHOULD_USE_CACHE };

package/lib/tokens.d.ts

@@ -1,87 +1,145 @@
 import type { TramvaiRenderMode } from '@tramvai/tokens-render';
 import type { Cache, ResponseManager } from '@tramvai/tokens-common';
+import { StaticPagesService } from './staticPages/staticPagesService';
 export declare const PAGE_RENDER_FALLBACK_COMPONENT_PREFIX: string & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 };
 /**
  * @deprecated Use token `TRAMVAI_RENDER_MODE` from `@tramvai/tokens-render`
  */
 export declare const PAGE_RENDER_DEFAULT_MODE: ("ssr" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("client" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("static" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ((() => TramvaiRenderMode) & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 });
 export declare const PAGE_RENDER_WRAPPER_TYPE: ("layout" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("content" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("page" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 });
 export declare const PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT: (import("react").ComponentClass<any, any> & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | (import("react").FunctionComponent<any> & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 });
 export interface StaticPagesCacheEntry {
     updatedAt: number;
     headers: ReturnType<ResponseManager['getHeaders']>;
     status: ReturnType<ResponseManager['getStatus']>;
     body: string;
+    source: 'memory' | 'fs';
 }
 export interface StaticPagesOptions {
     /**
      * Static page cache live time in milliseconds
-     * @default 60000
+     * @default 300000
      */
     ttl: number;
     /**
-     * Cached static page maximum size
-     * @default 1000
+     * Cached static page maximum size in memory
+     * @default 100
      */
     maxSize: number;
+    /**
+     * Whether to allow stale entries to be returned
+     * @default true
+     */
+    allowStale: boolean;
+    /**
+     * Whitelist of headers, that are allowed to be passed from client request to backround cache revalidation request,
+     * and allowed to be cached and returned with the cached response
+     * @default []
+     */
+    allowedHeaders: string[];
 }
-export declare const STATIC_PAGES_CACHE_TOKEN: Cache<Map<string, StaticPagesCacheEntry>> & {
-    __type?: "base token";
+export declare const STATIC_PAGES_CACHE_TOKEN: Cache<StaticPagesCacheEntry> & {
+    __type?: "base token" | undefined;
 };
 export declare const STATIC_PAGES_SHOULD_USE_CACHE: (() => boolean) & {
-    __type?: "multi token";
+    __type?: "multi token" | undefined;
 };
 export declare const STATIC_PAGES_BACKGROUND_FETCH_ENABLED: (() => boolean) & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 };
 export declare const STATIC_PAGES_OPTIONS_TOKEN: StaticPagesOptions & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 };
-export declare const STATIC_PAGES_COMMAND_LINE: ("init" & {
-    __type?: "base token";
+export declare const STATIC_PAGES_COMMAND_LINE: ("clear" & {
+    __type?: "base token" | undefined;
+}) | ("init" & {
+    __type?: "base token" | undefined;
 }) | ("listen" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("customerStart" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("resolveUserDeps" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("resolvePageDeps" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("generatePage" & {
-    __type?: "base token";
-}) | ("clear" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("spaTransition" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("afterSpaTransition" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 }) | ("close" & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
 });
 export declare const STATIC_PAGES_MODIFY_CACHE: ((entry: StaticPagesCacheEntry) => StaticPagesCacheEntry) & {
-    __type?: "multi token";
+    __type?: "multi token" | undefined;
 };
 export declare const STATIC_PAGES_CACHE_5xx_RESPONSE: (() => boolean) & {
-    __type?: "base token";
+    __type?: "base token" | undefined;
+};
+/**
+ * Token that computes the current cache key for a page variation
+ * For example: 'mobile', 'desktop', or empty string for default variation
+ * Used in combination with pathname to create the full cache key
+ */
+export declare const STATIC_PAGES_KEY_TOKEN: (() => string) & {
+    __type?: "base token" | undefined;
+};
+export interface FileSystemCacheOptions {
+    /**
+     * Directory where static HTML files are stored
+     * @default 'dist/static'
+     */
+    directory: string;
+    /**
+     * Maximum number of files to keep in cache
+     * @default 1000
+     */
+    maxSize: number;
+    /**
+     * TTL for cache entries in milliseconds
+     * @default 300000
+     */
+    ttl: number;
+    /**
+     * Whether to allow stale entries to be returned
+     * @default true
+     */
+    allowStale: boolean;
+}
+export declare const STATIC_PAGES_FS_CACHE_ENABLED: (() => boolean) & {
+    __type?: "base token" | undefined;
+};
+export declare const STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN: FileSystemCacheOptions & {
+    __type?: "base token" | undefined;
+};
+export declare const STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN: ((entry: {
+    ttl: number;
+    updatedAt: number;
+}) => string) & {
+    __type?: "base token" | undefined;
+};
+export declare const STATIC_PAGES_SERVICE: StaticPagesService & {
+    __type?: "base token" | undefined;
 };
 //# sourceMappingURL=tokens.d.ts.map

package/lib/tokens.es.js

@@ -14,5 +14,19 @@ const STATIC_PAGES_OPTIONS_TOKEN = createToken('static pages options');
 const STATIC_PAGES_COMMAND_LINE = createToken('static pages command line');
 const STATIC_PAGES_MODIFY_CACHE = createToken('static pages modify cache', { multi: true });
 const STATIC_PAGES_CACHE_5xx_RESPONSE = createToken('static pages cache 5xx response');
+/**
+ * Token that computes the current cache key for a page variation
+ * For example: 'mobile', 'desktop', or empty string for default variation
+ * Used in combination with pathname to create the full cache key
+ */
+const STATIC_PAGES_KEY_TOKEN = createToken('static pages key', {
+    scope: Scope.REQUEST,
+});
+const STATIC_PAGES_FS_CACHE_ENABLED = createToken('static pages file system cache enabled', { scope: Scope.SINGLETON });
+const STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN = createToken('static pages file system cache options', { scope: Scope.SINGLETON });
+const STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN = createToken('static pages cache-control header', {
+    scope: Scope.REQUEST,
+});
+const STATIC_PAGES_SERVICE = createToken('static pages service');
 
-export { PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT, PAGE_RENDER_DEFAULT_MODE, PAGE_RENDER_FALLBACK_COMPONENT_PREFIX, PAGE_RENDER_WRAPPER_TYPE, STATIC_PAGES_BACKGROUND_FETCH_ENABLED, STATIC_PAGES_CACHE_5xx_RESPONSE, STATIC_PAGES_CACHE_TOKEN, STATIC_PAGES_COMMAND_LINE, STATIC_PAGES_MODIFY_CACHE, STATIC_PAGES_OPTIONS_TOKEN, STATIC_PAGES_SHOULD_USE_CACHE };
+export { PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT, PAGE_RENDER_DEFAULT_MODE, PAGE_RENDER_FALLBACK_COMPONENT_PREFIX, PAGE_RENDER_WRAPPER_TYPE, STATIC_PAGES_BACKGROUND_FETCH_ENABLED, STATIC_PAGES_CACHE_5xx_RESPONSE, STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN, STATIC_PAGES_CACHE_TOKEN, STATIC_PAGES_COMMAND_LINE, STATIC_PAGES_FS_CACHE_ENABLED, STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN, STATIC_PAGES_KEY_TOKEN, STATIC_PAGES_MODIFY_CACHE, STATIC_PAGES_OPTIONS_TOKEN, STATIC_PAGES_SERVICE, STATIC_PAGES_SHOULD_USE_CACHE };

package/lib/tokens.js

@@ -18,6 +18,20 @@ const STATIC_PAGES_OPTIONS_TOKEN = dippy.createToken('static pages options');
 const STATIC_PAGES_COMMAND_LINE = dippy.createToken('static pages command line');
 const STATIC_PAGES_MODIFY_CACHE = dippy.createToken('static pages modify cache', { multi: true });
 const STATIC_PAGES_CACHE_5xx_RESPONSE = dippy.createToken('static pages cache 5xx response');
+/**
+ * Token that computes the current cache key for a page variation
+ * For example: 'mobile', 'desktop', or empty string for default variation
+ * Used in combination with pathname to create the full cache key
+ */
+const STATIC_PAGES_KEY_TOKEN = dippy.createToken('static pages key', {
+    scope: dippy.Scope.REQUEST,
+});
+const STATIC_PAGES_FS_CACHE_ENABLED = dippy.createToken('static pages file system cache enabled', { scope: dippy.Scope.SINGLETON });
+const STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN = dippy.createToken('static pages file system cache options', { scope: dippy.Scope.SINGLETON });
+const STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN = dippy.createToken('static pages cache-control header', {
+    scope: dippy.Scope.REQUEST,
+});
+const STATIC_PAGES_SERVICE = dippy.createToken('static pages service');
 
 exports.PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT = PAGE_RENDER_DEFAULT_FALLBACK_COMPONENT;
 exports.PAGE_RENDER_DEFAULT_MODE = PAGE_RENDER_DEFAULT_MODE;
@@ -25,8 +39,13 @@ exports.PAGE_RENDER_FALLBACK_COMPONENT_PREFIX = PAGE_RENDER_FALLBACK_COMPONENT_P
 exports.PAGE_RENDER_WRAPPER_TYPE = PAGE_RENDER_WRAPPER_TYPE;
 exports.STATIC_PAGES_BACKGROUND_FETCH_ENABLED = STATIC_PAGES_BACKGROUND_FETCH_ENABLED;
 exports.STATIC_PAGES_CACHE_5xx_RESPONSE = STATIC_PAGES_CACHE_5xx_RESPONSE;
+exports.STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN = STATIC_PAGES_CACHE_CONTROL_HEADER_TOKEN;
 exports.STATIC_PAGES_CACHE_TOKEN = STATIC_PAGES_CACHE_TOKEN;
 exports.STATIC_PAGES_COMMAND_LINE = STATIC_PAGES_COMMAND_LINE;
+exports.STATIC_PAGES_FS_CACHE_ENABLED = STATIC_PAGES_FS_CACHE_ENABLED;
+exports.STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN = STATIC_PAGES_FS_CACHE_OPTIONS_TOKEN;
+exports.STATIC_PAGES_KEY_TOKEN = STATIC_PAGES_KEY_TOKEN;
 exports.STATIC_PAGES_MODIFY_CACHE = STATIC_PAGES_MODIFY_CACHE;
 exports.STATIC_PAGES_OPTIONS_TOKEN = STATIC_PAGES_OPTIONS_TOKEN;
+exports.STATIC_PAGES_SERVICE = STATIC_PAGES_SERVICE;
 exports.STATIC_PAGES_SHOULD_USE_CACHE = STATIC_PAGES_SHOULD_USE_CACHE;