dinou 5.0.3 → 5.1.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [5.1.0] - 2026-07-11
+
+### Added
+- **On-Demand Revalidation API**: Added `revalidatePath` and `revalidateTag` exports to the new `"dinou/server"` server-only entry point.
+  - **`revalidatePath(path)`**: Triggers the purge and background regeneration of static files for the targeted route. Fully supports relative path navigation inputs (e.g. `./` or `detalles`), resolved dynamically at runtime using the active request context and the `referer` header.
+  - **`revalidateTag(tag)`**: Scans statically generated outputs to locate and regenerate all routes associated with the matching cache tag.
+- **Route Caching Tags (`getCacheTags`)**: Integrated support for defining a custom `getCacheTags(params)` function inside route-level `page_functions` files. Registered tags are saved into the route's `metadata.json` during compile time and subsequent on-demand builds for tag-based invalidation queries.
+- **Lazy Load Module Boundaries**: Implemented dynamic CJS `require` and ESM `import()` layers inside the `"dinou/server"` entry point. This safely halts recursive import chains, preventing client-side bundlers and SSR rendering subprocesses from evaluating server-exclusive Node.js runtime code.
+
+### Fixed
+- **Slot Error Boundary Recovery during Static Site Generation (SSG)**: Implemented isolated try-catch evaluation blocks and local `error.jsx` fallback resolutions for layout slots inside `build-static-pages.js`. This matches the runtime router's slot containment behavior, preventing slot-level crashes from bubbling up and aborting compile-time builds or revalidation processes.
+- **HTTP Status Retrieval Bug in Static Serving (`getStatus`)**: Corrected the invocation of the status manifest retrieval logic in `server.js` (replacing the faulty `getStatus[reqPath]` property lookup with the correct `getStatus(reqPath)` function call). This ensures the server serves pre-rendered static pages with their recorded status codes (e.g. `500` for slot/page errors) instead of falling back to a `200 OK` default.
+
 ## [5.0.3] - 2026-07-09
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # **Dinou**
 
-[![Documentation](https://img.shields.io/badge/docs-dinou.dev-blue?style=flat-square)](https://dinou.dev)
+[![Documentation](https://img.shields.io/badge/docs-dinou.dev-blue?style=flat-square)](https://dinou.dev) [![Version](https://img.shields.io/badge/version-5.1.0-orange?style=flat-square)](https://www.npmjs.com/package/dinou)
 
 ### **Lightweight-Ejectable Full-Stack React 19 Framework**
 
@@ -53,6 +53,7 @@ Support for React Server Components (RSC), Server Functions, Server-Side Renderi
   - [4. `dynamic` (Force SSR)](#4-dynamic-force-ssr)
   - [5. `validateParams` (Route Parameter Validation)](#5-validateparams-route-parameter-validation)
   - [6. `allowISG` (Control On-Demand Generation)](#6-allowisg-control-on-demand-generation)
+  - [7. `getCacheTags` (Route Caching Tags)](#7-getcachetags-route-caching-tags)
 - [⚡ React Compiler & Automatic Optimizations](#-react-compiler--automatic-optimizations)
   - [Integration Strategy](#integration-strategy)
   - [Code Example](#code-example)
@@ -60,7 +61,7 @@ Support for React Server Components (RSC), Server Functions, Server-Side Renderi
   - [1. Components (`dinou`)](#1-components-dinou)
   - [2. Utilities (`dinou`)](#2-utilities-dinou)
   - [3. Client Hooks (`dinou` - Client Components Only)](#3-client-hooks-dinou---client-components-only)
-  - [4. Server-Only Utilities (`dinou`)](#4-server-only-utilities-dinou)
+  - [4. Server-Only Utilities (`dinou` & `dinou/server`)](#4-server-only-utilities)
   - [5. Page Configuration (`page_functions.ts`)](#5-page-configuration-page_functionsts)
   - [6. File Conventions Cheatsheet](#6-file-conventions-cheatsheet)
 - [🎨 Favicons](#-favicons)
@@ -912,6 +913,21 @@ export function allowISG() {
 }
 ```
 
+### 7. `getCacheTags` (Route Caching Tags)
+
+Associates invalidation tags with the pre-rendered or dynamic route for tag-based on-demand revalidation.
+
+- **Arguments:** `params` (The dynamic route parameters).
+- **Returns:** `string[]` or `Promise<string[]>` (an array of cache tags).
+
+```typescript
+// src/posts/[id]/page_functions.ts
+export async function getCacheTags(params) {
+  // Tag this page with a generic collection tag and a specific resource tag
+  return ["posts", `post-${params.id}`];
+}
+```
+
 ## ⚡ React Compiler & Automatic Optimizations
 
 Dinou integrates the **React Compiler** (React 19+) out of the box. It analyzes your code and automatically applies fine-grained memoization to values and functions.
@@ -1105,9 +1121,9 @@ export default function LoadingBar() {
 
 ---
 
-### 4. Server-Only Utilities (`dinou`)
+### 4. Server-Only Utilities
 
-#### `getContext()`
+#### `getContext()` (from `"dinou"`)
 
 Retrieves the request/response context. Available **only** inside server-side execution threads (Server Components, `page_functions` like `getProps`, and Server Functions).
 
@@ -1115,6 +1131,40 @@ Retrieves the request/response context. Available **only** inside server-side ex
 - **req:** `headers`, `cookies`, `query`, `path`, `method`.
 - **res:** `status()`, `setHeader()`, `redirect()`, `cookie()`, `clearCookie()`.
 
+#### On-Demand Revalidation (from `"dinou/server"`)
+
+These server-only utilities must be imported from the `"dinou/server"` entry point.
+
+##### `revalidatePath(path)`
+
+Triggers background regeneration of static files for the targeted route path. Supports relative paths (e.g. `./` or `detalles`), resolved relative to the request referer context at runtime.
+
+- **Arguments:** `path` (a string representing the route to revalidate).
+- **Returns:** `void`.
+
+```javascript
+import { revalidatePath } from "dinou/server";
+
+export async function action() {
+  revalidatePath("/blog/posts");
+}
+```
+
+##### `revalidateTag(tag)`
+
+Triggers background regeneration of all routes registered with the matching cache tag.
+
+- **Arguments:** `tag` (a string representing the tag to invalidate).
+- **Returns:** `void`.
+
+```javascript
+import { revalidateTag } from "dinou/server";
+
+export async function action() {
+  revalidateTag("posts");
+}
+```
+
 #### ⚠️ Security Warning: `getContext` in Client Components
 
 While `getContext()` technically works during the Server-Side Rendering (SSR) phase of Client Components, **using it directly inside a Client Component is strongly discouraged**.
@@ -1234,6 +1284,19 @@ export function allowISG() {
 }
 ```
 
+#### `getCacheTags(params)`
+
+Defines cache tags associated with the pre-rendered page for tag-based invalidation.
+
+- **Receives:** Resolved `params` object.
+- **Returns:** `string[]` or `Promise<string[]>` (an array of cache tag strings).
+
+```typescript
+export function getCacheTags(params) {
+  return ["posts", `post-${params.id}`];
+}
+```
+
 ---
 
 ### 6. File Conventions Cheatsheet

package/dinou/core/build-static-pages.js

@@ -824,6 +824,7 @@ async function buildStaticPages() {
       };
 
       let revalidate;
+      let cacheTags = [];
       const jsx = await requestStorage.run(mockContext, async () => {
         const [pagePath] = getFilePathAndDynamicParams(
           segments,
@@ -857,6 +858,13 @@ async function buildStaticPages() {
           const pageFunctionsModule = await importModule(pageFunctionsPath);
           const getProps = pageFunctionsModule.getProps;
           revalidate = pageFunctionsModule.revalidate;
+          if (pageFunctionsModule.getCacheTags) {
+            try {
+              cacheTags = await pageFunctionsModule.getCacheTags(params);
+            } catch (e) {
+              console.error("Error running getCacheTags in buildStaticPages:", e);
+            }
+          }
           pageFunctionsProps = await getProps?.(params);
           props = { ...props, ...(pageFunctionsProps?.page ?? {}) };
         }
@@ -896,11 +904,60 @@ async function buildStaticPages() {
               const updatedSlots = {};
               for (const [slotName, slotElement] of Object.entries(slots)) {
                 const alreadyFoundPath = slotElement.props?.__modulePath;
-
-                updatedSlots[slotName] = {
+                const slotElementWithModule = {
                   ...slotElement,
                   __modulePath: alreadyFoundPath ?? null,
                 };
+
+                let updatedSlotElement;
+                try {
+                  await asyncRenderJSXToClientJSX(slotElementWithModule);
+                  updatedSlotElement = slotElementWithModule;
+                } catch (e) {
+                  const slotFilePath = alreadyFoundPath;
+                  if (slotFilePath) {
+                    const realSlotFolder = path.dirname(slotFilePath);
+                    const [slotErrorPath, slotErrorParams] =
+                      getFilePathAndDynamicParams(
+                        segments,
+                        {},
+                        realSlotFolder,
+                        "error",
+                        true,
+                        true,
+                        undefined,
+                        segments.length,
+                      );
+
+                    if (slotErrorPath) {
+                      const slotErrorModule = await importModule(slotErrorPath);
+                      const SlotError = slotErrorModule.default ?? slotErrorModule;
+
+                      const serializedError = {
+                        message: e.message || "Unknown Error",
+                        name: e.name,
+                        stack: process.env.NODE_ENV !== "production" ? e.stack : undefined,
+                      };
+
+                      updatedSlotElement = React.createElement(SlotError, {
+                        params: slotErrorParams,
+                        key: slotName,
+                        error: serializedError,
+                      });
+                    } else {
+                      console.warn(
+                        `[Dinou Build] Slot @${slotName} failed and does not have error.tsx`,
+                      );
+                      updatedSlotElement = null;
+                    }
+                  } else {
+                    console.error(
+                      `[Dinou Build] Slot @${slotName} failed and has no module path`,
+                    );
+                    updatedSlotElement = null;
+                  }
+                }
+                updatedSlots[slotName] = updatedSlotElement;
               }
               let props = {
                 params: dParams,
@@ -943,6 +1000,7 @@ async function buildStaticPages() {
       staticMetadata.set(reqPath, {
         revalidate: revalidate?.(),
         effects: sideEffects,
+        tags: cacheTags,
       });
       console.log(`Registered static page at ${reqPath}`);
     } catch (err) {
@@ -1096,6 +1154,7 @@ async function buildStaticPage(reqPath, isDynamic = null) {
     };
 
     let revalidate;
+    let cacheTags = [];
     const jsx = await requestStorage.run(mockContext, async () => {
       const [pagePath, dParams] = getFilePathAndDynamicParams(
         segments,
@@ -1132,6 +1191,13 @@ async function buildStaticPage(reqPath, isDynamic = null) {
         if (isDynamic && (isDynamic.value = pageFunctionsModule.dynamic?.()))
           return;
         revalidate = pageFunctionsModule.revalidate;
+        if (pageFunctionsModule.getCacheTags) {
+          try {
+            cacheTags = await pageFunctionsModule.getCacheTags(dParams);
+          } catch (e) {
+            console.error("Error running getCacheTags:", e);
+          }
+        }
         pageFunctionsProps = await getProps?.(dParams);
         props = { ...props, ...(pageFunctionsProps?.page ?? {}) };
       }
@@ -1169,11 +1235,60 @@ async function buildStaticPage(reqPath, isDynamic = null) {
             const updatedSlots = {};
             for (const [slotName, slotElement] of Object.entries(slots)) {
               const alreadyFoundPath = slotElement.props?.__modulePath;
-
-              updatedSlots[slotName] = {
+              const slotElementWithModule = {
                 ...slotElement,
                 __modulePath: alreadyFoundPath ?? null,
               };
+
+              let updatedSlotElement;
+              try {
+                await asyncRenderJSXToClientJSX(slotElementWithModule);
+                updatedSlotElement = slotElementWithModule;
+              } catch (e) {
+                const slotFilePath = alreadyFoundPath;
+                if (slotFilePath) {
+                  const realSlotFolder = path.dirname(slotFilePath);
+                  const [slotErrorPath, slotErrorParams] =
+                    getFilePathAndDynamicParams(
+                      segments,
+                      {},
+                      realSlotFolder,
+                      "error",
+                      true, // withExtension
+                      true, // finalDestination
+                      undefined, // lastFound
+                      segments.length,
+                    );
+
+                  if (slotErrorPath) {
+                    const slotErrorModule = await importModule(slotErrorPath);
+                    const SlotError = slotErrorModule.default ?? slotErrorModule;
+
+                    const serializedError = {
+                      message: e.message || "Unknown Error",
+                      name: e.name,
+                      stack: process.env.NODE_ENV !== "production" ? e.stack : undefined,
+                    };
+
+                    updatedSlotElement = React.createElement(SlotError, {
+                      params: slotErrorParams,
+                      key: slotName,
+                      error: serializedError,
+                    });
+                  } else {
+                    console.warn(
+                      `[Dinou Build] Slot @${slotName} failed and does not have error.tsx`,
+                    );
+                    updatedSlotElement = null;
+                  }
+                } else {
+                  console.error(
+                    `[Dinou Build] Slot @${slotName} failed and has no module path`,
+                  );
+                  updatedSlotElement = null;
+                }
+              }
+              updatedSlots[slotName] = updatedSlotElement;
             }
             let layoutProps = {
               params: dParams,
@@ -1221,6 +1336,7 @@ async function buildStaticPage(reqPath, isDynamic = null) {
     staticMetadata.set(reqPath, {
       revalidate: revalidate?.(),
       effects: sideEffects,
+      tags: cacheTags,
     });
     console.warn(`Registered rebuilt static page at ${reqPath}`);
   } catch (error) {

package/dinou/core/cache-revalidate.js

@@ -0,0 +1,145 @@
+const path = require("path");
+const fs = require("fs").promises;
+const { existsSync, copyFileSync } = require("fs");
+const generateStaticPage = require("./generate-static-page");
+const { buildStaticPage } = require("./build-static-pages");
+const generateStaticRSC = require("./generate-static-rsc");
+const { safeRename } = require("./safe-rename");
+const { updateStatus } = require("./status-manifest");
+
+const { getContext } = require("./request-context");
+const { resolveRelativeUrl } = require("./url-resolver");
+
+async function walkMetadataFiles(dir, fileList = []) {
+  try {
+    const files = await fs.readdir(dir);
+    for (const file of files) {
+      const filePath = path.join(dir, file);
+      const stat = await fs.stat(filePath);
+      if (stat.isDirectory()) {
+        await walkMetadataFiles(filePath, fileList);
+      } else if (file === "metadata.json") {
+        fileList.push(filePath);
+      }
+    }
+  } catch (err) {
+    // Ignore read errors for individual folders/files
+  }
+  return fileList;
+}
+
+async function revalidatePath(reqPath) {
+  let targetPath = reqPath;
+
+  if (targetPath && !targetPath.startsWith("/") && !targetPath.includes("://")) {
+    const ctx = getContext();
+    let currentPathname = "/";
+    if (ctx && ctx.req) {
+      const referer = ctx.req.headers?.referer;
+      if (referer) {
+        try {
+          currentPathname = new URL(referer).pathname;
+        } catch (e) {}
+      } else {
+        currentPathname = ctx.req.path || "/";
+      }
+    }
+    targetPath = resolveRelativeUrl(targetPath, currentPathname);
+  }
+
+  let cleanPath = targetPath;
+  if (!cleanPath.startsWith("/")) {
+    cleanPath = "/" + cleanPath;
+  }
+  if (cleanPath !== "/" && cleanPath.endsWith("/")) {
+    cleanPath = cleanPath.slice(0, -1);
+  }
+
+  const dist2Folder = path.resolve(process.cwd(), "dist2");
+  const reqPathWithSlash = cleanPath.endsWith("/") ? cleanPath : cleanPath + "/";
+
+  // Check if there is an existing page to copy to _old
+  try {
+    if (existsSync(path.join(dist2Folder, reqPathWithSlash, "index.html"))) {
+      copyFileSync(
+        path.join(dist2Folder, reqPathWithSlash, "index.html"),
+        path.join(dist2Folder, reqPathWithSlash, "index._old.html")
+      );
+    }
+    if (existsSync(path.join(dist2Folder, reqPathWithSlash, "rsc.rsc"))) {
+      copyFileSync(
+        path.join(dist2Folder, reqPathWithSlash, "rsc.rsc"),
+        path.join(dist2Folder, reqPathWithSlash, "rsc._old.rsc")
+      );
+    }
+  } catch (e) {
+    // Ignore copy errors
+  }
+
+  console.log(`[Revalidate] Starting on-demand revalidation for ${cleanPath}...`);
+  try {
+    const isDynamic = {};
+    await buildStaticPage(cleanPath, isDynamic);
+    if (isDynamic.value) {
+      console.log(`[Revalidate] Bailout detected for ${cleanPath}. Switching to dynamic (skipping static write).`);
+      return;
+    }
+
+    const rscResult = await generateStaticRSC(cleanPath);
+    if (!rscResult.success) {
+      console.warn(`⚠️ [Revalidate] RSC generation failed for ${cleanPath}.`);
+      if (rscResult.tempPath && existsSync(rscResult.tempPath)) {
+        await fs.unlink(rscResult.tempPath).catch(() => {});
+      }
+      return;
+    }
+
+    await safeRename(rscResult.tempPath, rscResult.finalPath);
+
+    const pageResult = await generateStaticPage(cleanPath);
+    if (pageResult.success) {
+      await safeRename(pageResult.tempPath, pageResult.finalPath);
+      updateStatus(cleanPath, pageResult.status);
+      console.log(`✅ [Revalidate] Successfully revalidated ${cleanPath} (Status: ${pageResult.status})`);
+    } else {
+      console.warn(`⚠️ [Revalidate] HTML generation failed for ${cleanPath}.`);
+      if (pageResult.tempPath && existsSync(pageResult.tempPath)) {
+        await fs.unlink(pageResult.tempPath).catch(() => {});
+      }
+    }
+  } catch (e) {
+    console.error(`[Revalidate] Critical error revalidating ${cleanPath}:`, e);
+    throw e;
+  }
+}
+
+async function revalidateTag(tag) {
+  console.log(`[Revalidate] Starting on-demand revalidation for tag: "${tag}"...`);
+  const dist2Folder = path.resolve(process.cwd(), "dist2");
+  if (!existsSync(dist2Folder)) return;
+
+  const metadataFiles = await walkMetadataFiles(dist2Folder);
+  const revalidatePromises = [];
+
+  for (const fileOfMeta of metadataFiles) {
+    try {
+      const content = await fs.readFile(fileOfMeta, "utf8");
+      const metadata = JSON.parse(content);
+      if (metadata && Array.isArray(metadata.tags) && metadata.tags.includes(tag)) {
+        // Calculate the request path
+        const relative = path.relative(dist2Folder, path.dirname(fileOfMeta));
+        const reqPath = "/" + relative.replace(/\\/g, "/");
+        revalidatePromises.push(revalidatePath(reqPath));
+      }
+    } catch (err) {
+      console.error(`[Revalidate] Error reading tags from ${fileOfMeta}:`, err);
+    }
+  }
+
+  await Promise.all(revalidatePromises);
+}
+
+module.exports = {
+  revalidatePath,
+  revalidateTag,
+};

package/dinou/core/generate-static-page.js

@@ -10,7 +10,7 @@ const OUT_DIR = path.resolve("dist2");
 async function generateStaticPage(reqPath) {
   const finalReqPath = reqPath.endsWith("/") ? reqPath : reqPath + "/";
   const htmlPath = path.join(OUT_DIR, finalReqPath, "index.html");
-  const tempHtmlPath = path.join(OUT_DIR, finalReqPath, "index.html.tmp");
+  const tempHtmlPath = path.join(OUT_DIR, finalReqPath, `index.html.${Date.now()}-${Math.random()}.tmp`);
 
   const query = {};
   const paramsString = JSON.stringify(query);
@@ -94,6 +94,7 @@ async function generateStaticPage(reqPath) {
           revalidate: metadata.revalidate,
           generatedAt: Date.now(),
           effects: metadata.effects,
+          tags: metadata.tags || [],
         }, null, 2),
         "utf8"
       );

package/dinou/core/generate-static-pages.js

@@ -107,6 +107,7 @@ async function generateStaticPages(routes) {
             revalidate: metadata.revalidate,
             generatedAt: Date.now(),
             effects: metadata.effects,
+            tags: metadata.tags || [],
           }, null, 2),
           "utf8"
         );

package/dinou/core/generate-static-rsc.js

@@ -15,9 +15,8 @@ const OUT_DIR = path.resolve("dist2");
 async function generateStaticRSC(reqPath) {
   const finalReqPath = reqPath.endsWith("/") ? reqPath : reqPath + "/";
 
-  // 1. PATHS: Final and Temporary
   const payloadPath = path.join(OUT_DIR, finalReqPath, "rsc.rsc");
-  const tempPayloadPath = payloadPath + ".tmp"; // 👈 We write here
+  const tempPayloadPath = path.join(OUT_DIR, finalReqPath, `rsc.rsc.${Date.now()}-${Math.random()}.tmp`);
 
   // 👇 2. MOCK RES (Complete and Robust Version)
   const mockRes = {

package/dinou/core/server.js

@@ -1026,10 +1026,10 @@ app.get(/^\/.*\/?$/, async (req, res) => {
       if (existsSync(fileToRead) && !dynamicState.value) {
         res.setHeader("Content-Type", "text/html");
         res.setHeader("Cache-Control", "no-store, no-cache, must-revalidate");
-        const meta = getStatus[reqPath];
+        const status = getStatus(reqPath);
 
-        if (meta && meta.status) {
-          res.statusCode = meta.status;
+        if (status) {
+          res.statusCode = status;
         } else {
           res.statusCode = 200; // Default
         }

package/dinou/package.json

@@ -1,12 +1,17 @@
 {
   "name": "dinou-ejected",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "main": "index.js",
   "private": true,
   "exports": {
     ".": {
       "import": "./index.mjs",
       "require": "./index.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./server.mjs",
+      "require": "./server.js"
     }
   },
   "types": "./index.d.ts",

package/dinou/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Revalidates the cache for a specific route path.
+ * * It deletes the old cached HTML and RSC files and rebuilds them synchronously.
+ * @param path The path of the route to revalidate (e.g. "/blog" or "/blog/12").
+ */
+export declare function revalidatePath(path: string): Promise<void>;
+
+/**
+ * Revalidates all routes that are associated with the specified cache tag.
+ * @param tag The tag string to revalidate (e.g. "blog-posts").
+ */
+export declare function revalidateTag(tag: string): Promise<void>;

package/dinou/server.js

@@ -0,0 +1,10 @@
+module.exports = {
+  revalidatePath: async function (path) {
+    const { revalidatePath: fn } = require("./core/cache-revalidate.js");
+    return fn(path);
+  },
+  revalidateTag: async function (tag) {
+    const { revalidateTag: fn } = require("./core/cache-revalidate.js");
+    return fn(tag);
+  },
+};

package/dinou/server.mjs

@@ -0,0 +1,9 @@
+export async function revalidatePath(path) {
+  const { revalidatePath: fn } = await import("./core/cache-revalidate.js");
+  return fn(path);
+}
+
+export async function revalidateTag(tag) {
+  const { revalidateTag: fn } = await import("./core/cache-revalidate.js");
+  return fn(tag);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dinou",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "description": "Lightweight-Ejectable Full-Stack React 19 Framework with support for React Server Components (RSC), Server Functions, Server-Side Rendering (SSR), Static Generation (SSG), Incremental Static Generation (ISG), and Incremental Static Regeneration (ISR)",
   "main": "index.js",
   "bin": {