@gravito/ion 3.1.0 → 4.0.0

package/README.md

@@ -1,18 +1,19 @@
 # 🛰️ Orbit Inertia (Ion)
 
-> Inertia.js adapter for Gravito. Build modern monoliths with React/Vue/Svelte.
+> Inertia.js v2 adapter for Gravito. Build modern monoliths with React/Vue/Svelte.
 
-**Orbit Inertia** (@gravito/ion) is a high-performance adapter that allows you to build single-page apps using classic server-side routing and controllers. It acts as the "glue" between Gravito (Photon) and your frontend framework, eliminating the need for a separate REST/GraphQL API.
+**Orbit Inertia** (@gravito/ion) is a high-performance adapter implementing the **Inertia.js v2 protocol** for Gravito. It allows you to build single-page apps using classic server-side routing and controllers, acting as the "glue" between Gravito (Photon) and your frontend framework, eliminating the need for a separate REST/GraphQL API.
 
 ## ✨ Key Features
 
 - **🚀 Modern Monolith Architecture**: Combine the productivity of server-side routing with the interactivity of SPA frameworks.
 - **🛠️ Zero API Development**: Pass data directly from controllers to components as typed props—no more managing endpoints or manual serialization.
-- **⚡ High-Performance Rendering**: Built-in multi-layer caching for components and metadata, ensuring sub-millisecond overhead.
+- **⚡ High-Performance Rendering**: Built-in multi-layer caching, version caching (60s TTL), and component metadata optimization.
 - **🛡️ Native Type Safety**: Full TypeScript support with generics for props, ensuring end-to-end type safety from server to client.
 - **🔗 Ecosystem Integration**: Seamlessly works with `OrbitPrism` for root templates and Gravito's session/auth modules.
 - **🔍 SEO & SSR Friendly**: Designed for modern web requirements, supporting Server-Side Rendering patterns for optimal visibility.
 - **🎨 Multi-Framework Support**: Official support for **React**, **Vue**, and **Svelte**.
+- **✨ Inertia v2 Protocol**: Full support for deferred props, merge strategies, error bags, and CSRF protection.
 
 ## 📦 Installation
 
@@ -74,6 +75,71 @@ export class DashboardController {
 }
 ```
 
+## 🔧 Inertia v2 Protocol Features
+
+### Deferred Props (Lazy Loading)
+Skip initial render, load props separately post-render:
+
+```typescript
+inertia.render('Dashboard', {
+  user: { id: 1, name: 'Carl' }, // Initial
+  stats: InertiaService.defer(() => fetchStats(), 'heavy'), // Deferred
+  notifications: InertiaService.defer(() => fetchNotifications(), 'notifications')
+});
+```
+
+### Merge Strategies (Partial Reloads)
+Control how props merge during partial reloads:
+
+```typescript
+inertia.render('Products/List', {
+  items: InertiaService.prepend([newProduct]), // Add to start
+  filters: InertiaService.deepMerge({ status: 'active' }), // Recursive merge
+  config: InertiaService.merge({ sortBy: 'name' }) // Shallow merge
+});
+```
+
+### Error Bags (Form Validation)
+Organize validation errors by category:
+
+```typescript
+inertia.withErrors({
+  email: 'Email is required',
+  password: 'Must be 8+ characters'
+}, 'login'); // Named bag
+
+inertia.withErrors({
+  line_1: 'Invalid CSV format'
+}, 'import');
+```
+
+### Smart Redirects
+Automatic 409 response for Inertia requests, 302 for regular requests:
+
+```typescript
+if (!user) {
+  return inertia.location('/login'); // Smart redirect
+}
+```
+
+### History Control
+```typescript
+inertia.encryptHistory(true);   // Disable back button
+inertia.clearHistory();         // Clear history after load
+```
+
+### CSRF Protection
+Automatic XSRF-TOKEN cookie generation (Axios-compatible):
+
+```typescript
+const ion = new OrbitIon({
+  csrf: {
+    enabled: true,
+    cookieName: 'XSRF-TOKEN' // Axios reads this automatically
+  }
+});
+```
+
 ## 🔧 Advanced Features
 
 ### Shared Props
@@ -84,7 +150,18 @@ inertia.share('auth', { user: 'Carl' });
 ```
 
 ### Partial Reloads
-Ion supports Inertia's partial reloads, allowing the client to request only specific data to save bandwidth.
+Ion supports Inertia's partial reloads with smart merge strategies, allowing the client to request only specific data to save bandwidth.
+
+### Method Chaining
+All methods support fluent interface:
+
+```typescript
+return await inertia
+  .encryptHistory()
+  .clearHistory()
+  .withErrors({ email: 'Invalid' })
+  .render('SecurePage', props);
+```
 
 ### Manual Serialization Control
 Customize how your data is converted to JSON for the client:

package/README.zh-TW.md

@@ -1,18 +1,19 @@
 # 🛰️ Orbit Inertia (Ion)
 
-> Gravito 的 Inertia.js 轉接器，用於建立現代化單體應用 (Modern Monolith)。支援 React、Vue 與 Svelte。
+> Gravito 的 Inertia.js v2 轉接器，用於建立現代化單體應用 (Modern Monolith)。支援 React、Vue 與 Svelte。
 
-**Orbit Inertia** (@gravito/ion) 是一個高效能的轉接器，讓您能夠使用傳統的伺服器端路由與控制器來建立單頁應用程式 (SPA)。它扮演了 Gravito (Photon) 與前端框架之間的「膠水」，消除了開發獨立 REST 或 GraphQL API 的需求。
+**Orbit Inertia** (@gravito/ion) 是一個高效能的轉接器，實現 **Inertia.js v2 協議**，讓您能夠使用傳統的伺服器端路由與控制器來建立單頁應用程式 (SPA)。它扮演了 Gravito (Photon) 與前端框架之間的「膠水」，消除了開發獨立 REST 或 GraphQL API 的需求。
 
 ## ✨ 核心特性
 
 - **🚀 現代化單體架構**：結合伺服器端開發的高效率與 SPA 框架的高互動性。
 - **🛠️ 零 API 開發**：直接將資料從控制器傳遞到組件作為具備型別的 Props，不再需要管理 API 端點或手動處理序列化。
-- **⚡ 高效能渲染**：內建針對組件與元資料 (Metadata) 的多層快取機制，確保毫秒級的極低開銷。
+- **⚡ 高效能渲染**：內建多層快取、版本快取 (60 秒 TTL) 與組件元資料最佳化，確保毫秒級的極低開銷。
 - **🛡️ 原生型別安全**：完整的 TypeScript 支援，透過 Generics 確保從伺服器到前端的端到端型別安全。
 - **🔗 生態系整合**：與 `OrbitPrism` (模板引擎) 及 Gravito 的 Session/Auth 模組完美協作。
 - **🔍 SEO 與 SSR 友善**：專為現代 Web 需求設計，支援伺服器端渲染 (SSR) 模式以優化搜尋引擎可見度。
 - **🎨 多框架支援**：官方支援 **React**、**Vue** 與 **Svelte**。
+- **✨ Inertia v2 協議**：完整支援延遲 Props、合併策略、錯誤包與 CSRF 防護。
 
 ## 📦 安裝
 
@@ -74,6 +75,71 @@ export class DashboardController {
 }
 ```
 
+## 🔧 Inertia v2 協議功能
+
+### 延遲 Props (Deferred Props)
+跳過初始渲染，在後續操作中單獨載入 Props：
+
+```typescript
+inertia.render('Dashboard', {
+  user: { id: 1, name: 'Carl' }, // 初始載入
+  stats: InertiaService.defer(() => fetchStats(), 'heavy'), // 延遲載入
+  notifications: InertiaService.defer(() => fetchNotifications(), 'notifications')
+});
+```
+
+### 合併策略 (Merge Strategies)
+控制局部重新載入時 Props 如何合併：
+
+```typescript
+inertia.render('Products/List', {
+  items: InertiaService.prepend([newProduct]), // 加到開頭
+  filters: InertiaService.deepMerge({ status: 'active' }), // 遞迴合併
+  config: InertiaService.merge({ sortBy: 'name' }) // 淺合併
+});
+```
+
+### 錯誤包 (Error Bags)
+按類別組織表單驗證錯誤：
+
+```typescript
+inertia.withErrors({
+  email: '電郵為必填',
+  password: '必須為 8 個字元以上'
+}, 'login'); // 命名包
+
+inertia.withErrors({
+  line_1: '無效的 CSV 格式'
+}, 'import');
+```
+
+### 智慧重定向 (Smart Redirects)
+自動為 Inertia 請求回傳 409，普通請求回傳 302：
+
+```typescript
+if (!user) {
+  return inertia.location('/login'); // 智慧重定向
+}
+```
+
+### 瀏覽歷史控制 (History Control)
+```typescript
+inertia.encryptHistory(true);   // 停用返回按鈕
+inertia.clearHistory();         // 載入後清除歷史
+```
+
+### CSRF 防護
+自動產生 XSRF-TOKEN Cookie (與 Axios 相容)：
+
+```typescript
+const ion = new OrbitIon({
+  csrf: {
+    enabled: true,
+    cookieName: 'XSRF-TOKEN' // Axios 會自動讀取
+  }
+});
+```
+
 ## 🔧 進階功能
 
 ### 共享 Props (Shared Props)
@@ -84,7 +150,18 @@ inertia.share('auth', { user: 'Carl' });
 ```
 
 ### 局部重新載入 (Partial Reloads)
-Ion 支援 Inertia 的局部重載機制，允許客戶端僅請求特定資料以節省頻寬。
+Ion 支援 Inertia 的局部重載機制，搭配智慧合併策略，允許客戶端僅請求特定資料以節省頻寬。
+
+### 方法鏈式調用 (Method Chaining)
+所有方法都支援流暢介面：
+
+```typescript
+return await inertia
+  .encryptHistory()
+  .clearHistory()
+  .withErrors({ email: '無效' })
+  .render('SecurePage', props);
+```
 
 ### 手動序列化控制
 自定義資料如何轉換為 JSON 傳遞給客戶端：

package/dist/index.cjs

@@ -97,8 +97,71 @@ var InertiaService = class {
     this.onRenderCallback = config.onRender;
   }
   sharedProps = {};
+  errorBags = {};
+  encryptHistoryFlag = false;
+  clearHistoryFlag = false;
   logLevel;
   onRenderCallback;
+  /**
+   * Creates a deferred prop that will be loaded after the initial render.
+   *
+   * @param factory - Function that resolves to the prop value.
+   * @param group - Optional group name for organizing deferred props.
+   * @returns A deferred prop definition.
+   *
+   * @example
+   * ```typescript
+   * props: {
+   *   user: { id: 1 },
+   *   stats: InertiaService.defer(() => fetchStats())
+   * }
+   * ```
+   */
+  static defer(factory, group = "default") {
+    return {
+      _type: "deferred",
+      factory,
+      group
+    };
+  }
+  /**
+   * Marks a prop to be merged (shallow) with existing data during partial reloads.
+   *
+   * @param value - The prop value to merge.
+   * @param matchOn - Optional key(s) to match on when merging arrays.
+   * @returns A merge prop definition.
+   */
+  static merge(value, matchOn) {
+    return {
+      _type: "merge",
+      value,
+      matchOn
+    };
+  }
+  /**
+   * Marks a prop to prepend to an array during partial reloads.
+   *
+   * @param value - The prop value to prepend.
+   * @returns A prepend prop definition.
+   */
+  static prepend(value) {
+    return {
+      _type: "prepend",
+      value
+    };
+  }
+  /**
+   * Marks a prop to be deep-merged with existing data during partial reloads.
+   *
+   * @param value - The prop value to deep merge.
+   * @returns A deep merge prop definition.
+   */
+  static deepMerge(value) {
+    return {
+      _type: "deepMerge",
+      value
+    };
+  }
   /**
    * Internal logging helper that respects the configured log level.
    *
@@ -186,10 +249,14 @@ var InertiaService = class {
         const partialData = this.context.req.header("X-Inertia-Partial-Data");
         const partialExcept = this.context.req.header("X-Inertia-Partial-Except");
         const partialComponent = this.context.req.header("X-Inertia-Partial-Component");
+        const resetKeys = this.context.req.header("X-Inertia-Reset");
         const isPartial = partialComponent === component;
         const only = partialData && isPartial ? partialData.split(",") : [];
         const except = partialExcept && isPartial ? partialExcept.split(",") : [];
+        const resetKeyList = resetKeys ? resetKeys.split(",") : [];
         const resolved = {};
+        const deferredGroups2 = {};
+        const mergedKeys2 = [];
         for (const [key, value] of Object.entries(p)) {
           if (only.length > 0 && !only.includes(key)) {
             continue;
@@ -197,6 +264,33 @@ var InertiaService = class {
           if (except.length > 0 && except.includes(key)) {
             continue;
           }
+          if (value && typeof value === "object" && "_type" in value && value._type === "deferred") {
+            const deferred = value;
+            const group = deferred.group ?? "default";
+            if (!deferredGroups2[group]) {
+              deferredGroups2[group] = [];
+            }
+            deferredGroups2[group].push(key);
+            continue;
+          }
+          if (value && typeof value === "object" && "_type" in value && ["merge", "prepend", "deepMerge"].includes(value._type)) {
+            const merged = value;
+            const existing = mergedKeys2.find((m) => m.mode === merged._type);
+            if (existing) {
+              existing.keys.push(key);
+            } else {
+              mergedKeys2.push({
+                keys: [key],
+                mode: merged._type
+              });
+            }
+            resolved[key] = merged.value;
+            continue;
+          }
+          if (resetKeyList.includes(key)) {
+            resolved[key] = void 0;
+            continue;
+          }
           if (typeof value === "function") {
             const propStart = performance.now();
             try {
@@ -212,7 +306,7 @@ var InertiaService = class {
             resolved[key] = value;
           }
         }
-        return resolved;
+        return { resolved, deferredGroups: deferredGroups2, mergedKeys: mergedKeys2 };
       };
       const resolveVersion = async () => {
         if (typeof this.config.version === "function") {
@@ -228,12 +322,32 @@ var InertiaService = class {
         }
         return { ...this.sharedProps, ...propsToMerge };
       };
+      const {
+        resolved: resolvedPropsData,
+        deferredGroups,
+        mergedKeys
+      } = await resolveProps(getMergedProps());
       const page = {
         component,
-        props: await resolveProps(getMergedProps()),
+        props: resolvedPropsData,
         url: pageUrl,
         version
       };
+      if (Object.keys(deferredGroups).length > 0) {
+        page.deferredProps = deferredGroups;
+      }
+      if (mergedKeys.length > 0) {
+        page.mergeProps = mergedKeys;
+      }
+      if (this.encryptHistoryFlag) {
+        page.encryptHistory = true;
+      }
+      if (this.clearHistoryFlag) {
+        page.clearHistory = true;
+      }
+      if (Object.keys(this.errorBags).length > 0) {
+        page.errorBags = this.errorBags;
+      }
       let pageJson;
       try {
         pageJson = JSON.stringify(page);
@@ -322,6 +436,42 @@ var InertiaService = class {
         duration: `${duration.toFixed(2)}ms`,
         error
       });
+      const isDev = process.env.NODE_ENV !== "production";
+      if (isDev && error instanceof Error) {
+        const errorHtml = `
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta charset="utf-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1">
+              <title>Inertia Render Error</title>
+              <style>
+                * { margin: 0; padding: 0; box-sizing: border-box; }
+                body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto; background: #f5f5f5; padding: 20px; }
+                .container { max-width: 800px; margin: 40px auto; background: white; border-radius: 8px; padding: 30px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
+                h1 { color: #d32f2f; margin-bottom: 10px; font-size: 24px; }
+                .meta { color: #666; margin-bottom: 20px; font-size: 14px; }
+                .component { background: #f5f5f5; padding: 10px 15px; border-left: 3px solid #1976d2; margin-bottom: 20px; font-family: monospace; }
+                .error-message { background: #ffebee; border: 1px solid #ef5350; border-radius: 4px; padding: 15px; margin-bottom: 20px; color: #c62828; }
+                .stack { background: #f5f5f5; border: 1px solid #ddd; border-radius: 4px; padding: 15px; overflow-x: auto; font-family: monospace; font-size: 12px; color: #333; line-height: 1.5; }
+                .hint { background: #e8f5e9; border-left: 3px solid #4caf50; padding: 15px; margin-top: 20px; color: #2e7d32; }
+              </style>
+            </head>
+            <body>
+              <div class="container">
+                <h1>\u{1F6A8} Inertia Render Error</h1>
+                <div class="meta">Component: <span class="component">${component}</span></div>
+                <div class="error-message">${error.message || "Unknown error"}</div>
+                ${error.stack ? `<div><strong>Stack Trace:</strong><div class="stack">${error.stack.split("\n").map((line) => line.replace(/</g, "&lt;").replace(/>/g, "&gt;")).join("\n")}</div></div>` : ""}
+                <div class="hint">
+                  <strong>\u{1F4A1} Dev Mode Tip:</strong> This enhanced error page is only visible in development mode. In production, a generic error message is shown.
+                </div>
+              </div>
+            </body>
+          </html>
+        `;
+        return this.context.html(errorHtml, 500);
+      }
       return new Response("Inertia Render Error", { status: 500 });
     }
   }
@@ -362,7 +512,7 @@ var InertiaService = class {
    * ```
    */
   shareAll(props) {
-    Object.assign(this.sharedProps, props);
+    this.sharedProps = { ...this.sharedProps, ...props };
   }
   /**
    * Returns a shallow copy of the current shared props.
@@ -382,6 +532,94 @@ var InertiaService = class {
   getSharedProps() {
     return { ...this.sharedProps };
   }
+  /**
+   * Instructs the Inertia client to navigate to a different URL.
+   *
+   * For Inertia AJAX requests, this returns a 409 Conflict with the `X-Inertia-Location` header.
+   * For regular page loads, this returns a 302 Found redirect.
+   *
+   * This is useful for server-side redirects triggered by authentication or authorization checks.
+   *
+   * @param url - The URL to redirect to.
+   * @returns A redirect response.
+   *
+   * @example
+   * ```typescript
+   * if (!ctx.get('user')) {
+   *   return inertia.location('/login');
+   * }
+   * ```
+   */
+  location(url) {
+    const isInertiaRequest = Boolean(this.context.req.header("X-Inertia"));
+    if (isInertiaRequest) {
+      this.context.header("X-Inertia-Location", url);
+      return new Response("", { status: 409 });
+    }
+    this.context.header("Location", url);
+    return new Response("", { status: 302 });
+  }
+  /**
+   * Controls whether the Inertia client should encrypt browser history.
+   *
+   * When enabled, history is not written to the browser's History API,
+   * preventing users from using the browser back button to return to previous pages.
+   *
+   * @param encrypt - Whether to encrypt history (defaults to true).
+   * @returns The service instance for method chaining.
+   *
+   * @example
+   * ```typescript
+   * return await inertia.encryptHistory(true).render('SecurePage');
+   * ```
+   */
+  encryptHistory(encrypt = true) {
+    this.encryptHistoryFlag = encrypt;
+    return this;
+  }
+  /**
+   * Clears the browser history after the page load.
+   *
+   * Useful for sensitive operations or multi-step wizards where you don't want
+   * users navigating back to previous states.
+   *
+   * @returns The service instance for method chaining.
+   *
+   * @example
+   * ```typescript
+   * return await inertia.clearHistory().render('SuccessPage');
+   * ```
+   */
+  clearHistory() {
+    this.clearHistoryFlag = true;
+    return this;
+  }
+  /**
+   * Registers form validation errors organized into named bags.
+   *
+   * Error bags allow multiple validation failure scenarios to coexist.
+   * For example, you might have 'default' errors and 'import' errors from different forms.
+   *
+   * @param errors - Validation errors, with field names as keys and error messages as values.
+   * @param bag - The error bag name (defaults to 'default').
+   * @returns The service instance for method chaining.
+   *
+   * @example
+   * ```typescript
+   * inertia.withErrors({
+   *   email: 'Email is required',
+   *   password: 'Must be 8+ characters'
+   * }, 'login');
+   *
+   * inertia.withErrors({
+   *   line_1: 'Invalid CSV format'
+   * }, 'import');
+   * ```
+   */
+  withErrors(errors, bag = "default") {
+    this.errorBags[bag] = errors;
+    return this;
+  }
 };
 
 // src/index.ts
@@ -413,9 +651,35 @@ var OrbitIon = class {
     core.logger.info("\u{1F6F0}\uFE0F Orbit Inertia installed (Callable Interface)");
     const appVersion = this.options.version ?? core.config.get("APP_VERSION", "1.0.0");
     const rootView = this.options.rootView ?? "app";
+    const csrfEnabled = this.options.csrf?.enabled !== false;
+    const csrfCookieName = this.options.csrf?.cookieName ?? "XSRF-TOKEN";
+    const VERSION_CACHE_TTL = 6e4;
+    let cachedVersion;
+    let versionCacheTime = 0;
+    const resolveAppVersion = async () => {
+      if (typeof appVersion !== "function") {
+        return appVersion;
+      }
+      const now = Date.now();
+      if (cachedVersion && now - versionCacheTime < VERSION_CACHE_TTL) {
+        return cachedVersion;
+      }
+      cachedVersion = await appVersion();
+      versionCacheTime = now;
+      return cachedVersion;
+    };
+    if (csrfEnabled) {
+      core.adapter.use("*", async (c, next) => {
+        const token = crypto.randomUUID();
+        const secure = process.env.NODE_ENV === "production";
+        const cookieValue = `${csrfCookieName}=${token}; Path=/; ${secure ? "Secure; " : ""}SameSite=Lax`;
+        c.header("Set-Cookie", cookieValue);
+        return await next();
+      });
+    }
     core.adapter.use("*", async (c, next) => {
       const service = new InertiaService(c, {
-        version: appVersion,
+        version: resolveAppVersion,
         rootView,
         ssr: this.options.ssr
       });
@@ -427,6 +691,10 @@ var OrbitIon = class {
         shareAll: service.shareAll.bind(service),
         getSharedProps: service.getSharedProps.bind(service),
         render: service.render.bind(service),
+        location: service.location.bind(service),
+        encryptHistory: service.encryptHistory.bind(service),
+        clearHistory: service.clearHistory.bind(service),
+        withErrors: service.withErrors.bind(service),
         service
       });
       c.set("inertia", inertiaProxy);