@ultimat3/render 27.8.1 → 27.9.0

package/README.md

@@ -26,6 +26,14 @@ export const config = defineRoute({
 export function Page(props: { data: Post }) { /* the SAME object meta was given */ }
 ```
 
+`prerender()` answers the pages to build: a bare string (a one-param route), a params object, or an
+entry — `{ params, lastmod?, locales? }` (`PrerenderEntry`) — mixed freely. The build reads `params`
+alone and renders every routed locale; `lastmod` (a `Date` or ISO 8601 with a zone) and `locales`
+are what the page says of itself for the sitemap: its `<lastmod>`, and the locales it is listed and
+cross-linked in. `enumeratePrerender()` answers params, `enumeratePrerenderEntries()` the entries.
+A key outside the three, a `lastmod` that is neither a string nor a `Date`, or `locales` that is
+not a list of names is `X_PRERENDER_FAILED`, naming the route file.
+
 ## `load` is the one server-side data seam
 
 Optional, and the only way a page gets data. It runs **once per render** and the result is handed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "27.8.1",
+  "version": "27.9.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "27.8.1",
-    "@ultimat3/core": "27.8.1",
-    "@ultimat3/http": "27.8.1",
-    "@ultimat3/i18n": "27.8.1",
-    "@ultimat3/seo": "27.8.1",
+    "@ultimat3/cache": "27.9.0",
+    "@ultimat3/core": "27.9.0",
+    "@ultimat3/http": "27.9.0",
+    "@ultimat3/i18n": "27.9.0",
+    "@ultimat3/seo": "27.9.0",
     "sass": "1.105.1"
   }
 }

package/src/index.ts

@@ -182,7 +182,9 @@ export {
 export type {
   InvalidateMode,
   LoadRequirement,
+  PrerenderEntry,
   PrerenderFn,
+  PrerenderItem,
   RenderResult,
   RevalidateConfig,
   RouteAlternate,

package/src/prerender-enumerate.ts

@@ -0,0 +1,108 @@
+// Single responsibility: what a route's `prerender()` answered, normalised — every page as its
+// params, plus what the page said about itself for a sitemap (`lastmod`, `locales`).
+
+import { renderCauseValue, renderThrowable } from '@ultimat3/core';
+import { PrerenderFailedError } from './errors';
+import type { RouteEntry } from './registry';
+import type { PrerenderEntry, RouteParams } from './route';
+
+const ENTRY_KEYS: readonly string[] = ['params', 'lastmod', 'locales'];
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Is `item` the ENTRY form — `{ params: { … }, lastmod?, locales? }` — rather than a params object?
+ * Decided by `params` holding an object: a param VALUE is always a string, so `{ params: 'a' }` on a
+ * route whose own dynamic segment is `[params]` stays the plain params it has always been.
+ */
+const isEntry = (item: Readonly<Record<string, unknown>>): boolean => isRecord(item['params']);
+
+function entryOf(entry: RouteEntry, item: Readonly<Record<string, unknown>>): PrerenderEntry {
+  const refuse = (problem: string): never => {
+    throw new PrerenderFailedError(
+      `prerender() for ${entry.path} returned an entry ${problem}`,
+      `x build --target static --json   # after prerender in ${entry.file} returns { params, lastmod?: Date | ISO 8601 string, locales?: string[] }`,
+    );
+  };
+  const extra = Object.keys(item).find((key) => !ENTRY_KEYS.includes(key));
+  if (extra !== undefined) {
+    refuse(`with the key ${JSON.stringify(extra)}, which is not one of ${ENTRY_KEYS.join(', ')}`);
+  }
+  const { lastmod, locales } = item;
+  if (lastmod !== undefined && typeof lastmod !== 'string' && !(lastmod instanceof Date)) {
+    refuse(`whose lastmod is ${renderCauseValue(lastmod)}, neither a Date nor an ISO 8601 string`);
+  }
+  if (
+    locales !== undefined &&
+    !(Array.isArray(locales) && locales.every((locale) => typeof locale === 'string'))
+  ) {
+    refuse(`whose locales is ${renderCauseValue(locales)}, not a list of locale names`);
+  }
+  return {
+    params: item['params'] as RouteParams,
+    ...(lastmod === undefined ? {} : { lastmod: lastmod as string | Date }),
+    ...(locales === undefined ? {} : { locales: locales as readonly string[] }),
+  };
+}
+
+/**
+ * Every page `prerender()` enumerates, as an entry. A bare string fills the route's one dynamic
+ * param; a params object is an entry with nothing to add. `lastmod` is carried AS WRITTEN — whether
+ * it names an instant is the sitemap's question (`@ultimat3/seo`, `X_SITEMAP_ENTRY_INVALID`).
+ */
+export async function enumeratePrerenderEntries(
+  entry: RouteEntry,
+): Promise<readonly PrerenderEntry[]> {
+  const prerender = entry.config.prerender;
+  if (prerender === undefined) {
+    return entry.pattern.keys.length === 0 ? [{ params: {} }] : [];
+  }
+
+  let produced: unknown;
+  try {
+    produced = await prerender();
+  } catch (error) {
+    throw new PrerenderFailedError(
+      // `renderThrowable`, never `.message`/`String()`: `prerender` is app code and may throw a
+      // value whose read raises in turn — this frame is what makes the build failure a coded one.
+      `prerender() for ${entry.path} threw: ${renderThrowable(error)}`,
+      `fix prerender in ${entry.file} — it runs at build time with no request context`,
+    );
+  }
+
+  if (!Array.isArray(produced)) {
+    throw new PrerenderFailedError(
+      `prerender() for ${entry.path} returned ${typeof produced}, expected an array`,
+      `return an array of params from prerender in ${entry.file}`,
+    );
+  }
+
+  const keys = entry.pattern.keys;
+  return produced.map((item: unknown): PrerenderEntry => {
+    if (typeof item === 'string') {
+      const only = keys[0];
+      if (keys.length !== 1 || only === undefined) {
+        throw new PrerenderFailedError(
+          `prerender() for ${entry.path} returned the bare string ${renderCauseValue(item)} ` +
+            `but the route has ${keys.length} dynamic params (${keys.join(', ')})`,
+          `return objects from prerender in ${entry.file}, e.g. { ${keys.join(': …, ')}: … }`,
+        );
+      }
+      return { params: { [only]: item } };
+    }
+    // A `null` reached `Object.hasOwn` in `static-path.ts` and left the build as a bare `TypeError`.
+    if (!isRecord(item)) {
+      throw new PrerenderFailedError(
+        `prerender() for ${entry.path} returned ${renderCauseValue(item)} as one of its items, which is neither a params object nor a string`,
+        `return an array of params objects (or strings, for a one-param route) from prerender in ${entry.file}`,
+      );
+    }
+    return isEntry(item) ? entryOf(entry, item) : { params: item as RouteParams };
+  });
+}
+
+/** The params of every page `prerender()` enumerates — what a build renders, one document each. */
+export async function enumeratePrerender(entry: RouteEntry): Promise<readonly RouteParams[]> {
+  return (await enumeratePrerenderEntries(entry)).map((page) => page.params);
+}

package/src/render-static.ts

@@ -4,12 +4,16 @@
  * the precache revision in `sw.js`, and the asset filename suffix.
  */
 
-import { BUILD_ID_HEADER, renderCauseValue, renderThrowable, useContext } from '@ultimat3/core';
+import { BUILD_ID_HEADER, renderThrowable, useContext } from '@ultimat3/core';
 import { PrerenderFailedError, RouteModeInvalidError } from './errors';
+import { enumeratePrerender } from './prerender-enumerate';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
 import { filePathOf, filledSegments, urlPathOf } from './static-path';
 
+// Re-exported where it has always been imported from; the enumeration is `prerender-enumerate.ts`'s.
+export { enumeratePrerender } from './prerender-enumerate';
+
 export interface StaticArtifact {
   readonly path: string;
   readonly params: RouteParams;
@@ -61,59 +65,6 @@ export function assertNoPerRequestState(file: string): void {
   }
 }
 
-/** Normalize `prerender()` output. A bare string fills the route's one dynamic param. */
-export async function enumeratePrerender(entry: RouteEntry): Promise<readonly RouteParams[]> {
-  const prerender = entry.config.prerender;
-  if (prerender === undefined) {
-    return entry.pattern.keys.length === 0 ? [{}] : [];
-  }
-
-  let produced: readonly (string | RouteParams)[];
-  try {
-    produced = await prerender();
-  } catch (error) {
-    throw new PrerenderFailedError(
-      // `renderThrowable`, never `.message`/`String()`: `prerender` is app code and may throw a
-      // value whose read raises in turn — this frame is what makes the build failure a coded one.
-      `prerender() for ${entry.path} threw: ${renderThrowable(error)}`,
-      `fix prerender in ${entry.file} — it runs at build time with no request context`,
-    );
-  }
-
-  if (!Array.isArray(produced)) {
-    throw new PrerenderFailedError(
-      `prerender() for ${entry.path} returned ${typeof produced}, expected an array`,
-      `return an array of params from prerender in ${entry.file}`,
-    );
-  }
-
-  const keys = entry.pattern.keys;
-  return produced.map((item: unknown) => {
-    if (typeof item !== 'string') return paramsOf(entry, item);
-    const only = keys[0];
-    if (keys.length !== 1 || only === undefined) {
-      throw new PrerenderFailedError(
-        `prerender() for ${entry.path} returned the bare string ${renderCauseValue(item)} ` +
-          `but the route has ${keys.length} dynamic params (${keys.join(', ')})`,
-        `return objects from prerender in ${entry.file}, e.g. { ${keys.join(': …, ')}: … }`,
-      );
-    }
-    return { [only]: item };
-  });
-}
-
-/**
- * One `prerender()` item that is not a bare string: a params object, or a coded refusal. A `null`
- * reached `Object.hasOwn` in `static-path.ts` and left the build as a bare `TypeError`.
- */
-function paramsOf(entry: RouteEntry, item: unknown): RouteParams {
-  if (typeof item === 'object' && item !== null && !Array.isArray(item)) return item as RouteParams;
-  throw new PrerenderFailedError(
-    `prerender() for ${entry.path} returned ${renderCauseValue(item)} as one of its items, which is neither a params object nor a string`,
-    `return an array of params objects (or strings, for a one-param route) from prerender in ${entry.file}`,
-  );
-}
-
 export interface StaticBuildOptions {
   readonly buildId: string;
   /** Extension-less output files get `/index.html` appended. */

package/src/route.ts

@@ -186,10 +186,29 @@ export type RouteMetaAsyncFn<TData = RouteData> = (
   ctx: RouteMetaContext<TData>,
 ) => Promise<RouteMeta>;
 
-/** Returns the params to build at deploy time. Bare strings fill a single dynamic param. */
-export type PrerenderFn = () =>
-  | readonly (string | RouteParams)[]
-  | Promise<readonly (string | RouteParams)[]>;
+/**
+ * One page `prerender()` answers, with what the page says about itself for the SITEMAP. The build
+ * reads `params` alone: every routed locale's document is still rendered.
+ */
+export interface PrerenderEntry {
+  readonly params: RouteParams;
+  /**
+   * When this page last changed — the sitemap's `<lastmod>` for it. A `Date`, or ISO 8601 with an
+   * explicit zone (`row.updatedAt`); a moment in the future is written as now.
+   */
+  readonly lastmod?: string | Date;
+  /**
+   * The locales this page is LISTED in: one sitemap `<url>` each, cross-linked with hreflang among
+   * themselves only. Omitted: every routed locale. Empty: built, and listed nowhere.
+   */
+  readonly locales?: readonly string[];
+}
+
+/** One item of a `prerender()` answer: a bare string, a params object, or an entry. */
+export type PrerenderItem = string | RouteParams | PrerenderEntry;
+
+/** Returns the pages to build at deploy time. Bare strings fill a single dynamic param. */
+export type PrerenderFn = () => readonly PrerenderItem[] | Promise<readonly PrerenderItem[]>;
 
 /**
  * The rule that makes the no-`load` fallback true: a route that loads nothing renders

package/src/server.ts

@@ -36,10 +36,10 @@ export {
   stylesheetsRevision,
   transformTsx,
 } from './module-loader';
+export { enumeratePrerenderEntries } from './prerender-enumerate';
 // ---- the render pipeline: one entry point per mode ----------------------------------------------
 export type { RenderHtmlOptions } from './render-html';
 export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
-
 export {
   DEFAULT_ISR_REGENERATE_DEADLINE_MS,
   invalidateAndRevalidate,