@iterant/site-runtime 3.5.0 → 3.6.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.5.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.6.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/src/lib/database.ts

@@ -1,5 +1,4 @@
-// Reading the brand's Database from a page, at request time (epic DBX, decision
-// DBX-D11).
+// Reading the brand's Database from a page (epic DBX, decision DBX-D11).
 //
 // A published site holds no database binding and composes no SQL. It asks the
 // platform's public read route for rows of ONE table, and the platform decides
@@ -12,10 +11,21 @@
 // platform generates on every publish and puts in front of Astro's entry. It
 // assigns them to `globalThis.__ITERANT_SITE_DB__` at module scope. In `astro
 // dev` there is no gate, so the pair arrives as environment variables instead.
+// A prerendered route reads while the site BUILDS, before that gate is even
+// generated, so the publish pipeline puts the pair in `.dev.vars` beside the
+// wrangler config and it reaches the render as environment variables too.
 //
 // Every failure answers with no rows and a console warning, never a throw: a
-// listing that renders empty is a page the customer can still see, and a build
-// that fails on a database blip is not.
+// listing that renders empty is a page the customer can still see, and a
+// request that fails on a database blip is not.
+//
+// That contract inverts at BAKE time. A prerendered route reads once, during
+// the publish build, and whatever it read is served until the next publish, so
+// an empty answer there is not a transient blank list but a blog that stays
+// empty for days. The publish build therefore sets `ITERANT_SITE_DB_STRICT=1`
+// and every failure below throws instead, killing the build at its cause. The
+// deployed runtime and the dev server never set it, so their behavior is
+// unchanged.
 
 const GLOBAL_KEY = "__ITERANT_SITE_DB__";
 
@@ -23,9 +33,18 @@ const URL_ENV = "ITERANT_SITE_DB_URL";
 
 const TOKEN_ENV = "ITERANT_SITE_DB_TOKEN";
 
+const STRICT_ENV = "ITERANT_SITE_DB_STRICT";
+
 /** How long one read may take before the page renders without it. */
 const TIMEOUT_MS = 10_000;
 
+/** The platform's own ceiling on `limit`, and so the pager's page size. */
+const MAX_LIMIT = 200;
+
+/** The platform refuses an `offset` past this, so `MAX_LIMIT` rows after it is
+ *  the last row {@link readDatabaseAll} can reach. */
+const MAX_OFFSET = 100_000;
+
 export type DatabaseFilterOp =
   | "eq"
   | "ne"
@@ -98,15 +117,29 @@ type SiteDatabaseHandoff = {
 
 const EMPTY: DatabaseResult = { rows: [], total: 0 };
 
-function fromEnvironment(): SiteDatabaseHandoff | null {
-  const environment = (
+function environment(): Record<string, string | undefined> | undefined {
+  return (
     globalThis as { process?: { env?: Record<string, string | undefined> } }
   ).process?.env;
-  const url = environment?.[URL_ENV];
-  const token = environment?.[TOKEN_ENV];
+}
+
+function fromEnvironment(): SiteDatabaseHandoff | null {
+  const url = environment()?.[URL_ENV];
+  const token = environment()?.[TOKEN_ENV];
   return url && token ? { url, token } : null;
 }
 
+/**
+ * Whether a failed read must kill the process instead of rendering empty.
+ *
+ * Read from the environment only, never from the global handoff: the handoff is
+ * what a DEPLOYED site carries, and a deployed site is exactly where the
+ * never-throw contract still holds.
+ */
+function strict(): boolean {
+  return environment()?.[STRICT_ENV] === "1";
+}
+
 function handoff(): SiteDatabaseHandoff | null {
   const baked = (globalThis as Record<string, unknown>)[GLOBAL_KEY];
   if (baked && typeof baked === "object") {
@@ -118,8 +151,25 @@ function handoff(): SiteDatabaseHandoff | null {
   return fromEnvironment();
 }
 
+function detailOf(detail: unknown): string {
+  if (detail instanceof Error) return detail.message;
+  if (typeof detail === "string") return detail;
+  return JSON.stringify(detail) ?? String(detail);
+}
+
+/** Say a read did not work, the way this environment wants it said. */
+function report(message: string, detail?: unknown): void {
+  const line = `[site-runtime] ${message}`;
+  if (strict()) {
+    throw new Error(
+      detail === undefined ? line : `${line} ${detailOf(detail)}`,
+    );
+  }
+  console.warn(line, detail ?? "");
+}
+
 function warn(message: string, detail?: unknown): DatabaseResult {
-  console.warn(`[site-runtime] readDatabase: ${message}`, detail ?? "");
+  report(`readDatabase: ${message}`, detail);
   return EMPTY;
 }
 
@@ -133,8 +183,9 @@ function warn(message: string, detail?: unknown): DatabaseResult {
  * });
  * ```
  *
- * Call it in a page's frontmatter (server side). The rows are read on every
- * request, so publishing a row shows it on the next page load with no rebuild.
+ * Call it in a page's frontmatter (server side). On a prerendered route the read
+ * happens once, at publish time, and the site shows those rows until the next
+ * publish; on an SSR route it happens per request.
  */
 export async function readDatabase(
   table: string,
@@ -182,6 +233,63 @@ export async function readDatabase(
   };
 }
 
+/**
+ * Every row a query matches, not just the first page of it.
+ *
+ * ```ts
+ * export async function getStaticPaths() {
+ *   const { rows } = await readDatabaseAll("articles", { select: ["slug"] });
+ *   return rows.map((row) => ({ params: { slug: String(row.slug) } }));
+ * }
+ * ```
+ *
+ * This is the enumeration a `getStaticPaths` needs, and the reason it exists is
+ * that a plain {@link readDatabase} answers at most {@link MAX_LIMIT} rows and
+ * says so only in `total`. A blog of 300 articles would bake its first 200 and
+ * look complete. Paging here is not an optimization; it is the difference
+ * between a whole blog and a silently truncated one.
+ *
+ * Any `limit` or `offset` on the query is ignored; `filter`, `sort` and `select`
+ * are carried on every page.
+ */
+export async function readDatabaseAll(
+  table: string,
+  query: DatabaseQuery = {},
+): Promise<DatabaseResult> {
+  const { limit: _limit, offset: _offset, ...shared } = query;
+  const rows: DatabaseRow[] = [];
+  let total = 0;
+  for (let offset = 0; ; offset += MAX_LIMIT) {
+    const page = await readDatabase(table, {
+      ...shared,
+      limit: MAX_LIMIT,
+      offset,
+    });
+    // No rows means the end of the table, or a page that failed and rendered
+    // empty under the never-throw contract. Its `total` is not the table's, and
+    // adopting it would answer with rows already read alongside a total of
+    // none, which is a shape no caller can act on.
+    if (page.rows.length === 0) break;
+    rows.push(...page.rows);
+    // The first page's count is the snapshot the rest of the walk is measured
+    // against. A total that is not a real number (a route answering `"many"`)
+    // would compare false forever and walk to the offset ceiling, so an
+    // unusable one falls back to what actually arrived.
+    if (offset === 0) {
+      total = Number.isFinite(page.total) ? page.total : rows.length;
+    }
+    if (rows.length >= total) break;
+    if (offset + MAX_LIMIT > MAX_OFFSET) {
+      report(
+        `readDatabaseAll: "${table}" holds ${total} rows, past the ${MAX_OFFSET + MAX_LIMIT} ` +
+          `that offset paging reaches, so ${rows.length} of them were read.`,
+      );
+      break;
+    }
+  }
+  return { rows, total };
+}
+
 /**
  * Attach {@link DbProvenance} to a row that carries a system `_id`.
  *