@gravito/ion 3.0.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +54 -40
  2. package/README.zh-TW.md +96 -17
  3. package/dist/index.cjs +343 -82
  4. package/dist/index.d.cts +359 -71
  5. package/dist/index.d.ts +359 -71
  6. package/dist/index.js +339 -82
  7. package/package.json +7 -5
package/README.md CHANGED
@@ -1,15 +1,18 @@
1
- # 🛰️ Orbit Inertia
1
+ # 🛰️ Orbit Inertia (Ion)
2
2
 
3
- > Inertia.js adapter for Gravito. Build modern monoliths with React/Vue.
3
+ > Inertia.js adapter for Gravito. Build modern monoliths with React/Vue/Svelte.
4
4
 
5
- **Orbit Inertia** 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.
5
+ **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.
6
6
 
7
- ## ✨ Features
7
+ ## ✨ Key Features
8
8
 
9
- - **Server-Side Routing**: Use Gravito's elegant routing and controllers.
10
- - **Client-Side Rendering**: Build your UI with React, Vue, or Svelte.
11
- - **No API required**: Pass data directly from controllers to components as props.
12
- - **SEO Ready**: Compatible with SSR (Server-Side Rendering) patterns since we control the initial page load.
9
+ - **🚀 Modern Monolith Architecture**: Combine the productivity of server-side routing with the interactivity of SPA frameworks.
10
+ - **🛠️ Zero API Development**: Pass data directly from controllers to components as typed props—no more managing endpoints or manual serialization.
11
+ - **⚡ High-Performance Rendering**: Built-in multi-layer caching for components and metadata, ensuring sub-millisecond overhead.
12
+ - **🛡️ Native Type Safety**: Full TypeScript support with generics for props, ensuring end-to-end type safety from server to client.
13
+ - **🔗 Ecosystem Integration**: Seamlessly works with `OrbitPrism` for root templates and Gravito's session/auth modules.
14
+ - **🔍 SEO & SSR Friendly**: Designed for modern web requirements, supporting Server-Side Rendering patterns for optimal visibility.
15
+ - **🎨 Multi-Framework Support**: Official support for **React**, **Vue**, and **Svelte**.
13
16
 
14
17
  ## 📦 Installation
15
18
 
@@ -17,85 +20,96 @@
17
20
  bun add @gravito/ion
18
21
  ```
19
22
 
20
- ## 🚀 Usage
23
+ ## 🚀 Quick Start
21
24
 
22
25
  ### 1. Register the Orbit
23
26
 
24
- In your `bootstrap.ts`:
27
+ In your application bootstrap:
25
28
 
26
29
  ```typescript
27
30
  import { OrbitIon } from '@gravito/ion';
28
- import { OrbitPrism } from '@gravito/prism'; // Required for root template
31
+ import { OrbitPrism } from '@gravito/prism'; // Required for the base HTML template
29
32
 
30
33
  const config = defineConfig({
31
34
  orbits: [OrbitPrism, OrbitIon],
32
35
  });
33
36
  ```
34
37
 
35
- ### 2. Create the Root Template
38
+ ### 2. Configure the Root Template
36
39
 
37
- By default, Inertia looks for `src/views/app.html`. This is the "shell" of your application.
40
+ By default, Ion looks for `src/views/app.html`. Use the `{{{ page }}}` placeholder to inject the Inertia data:
38
41
 
39
42
  ```html
40
43
  <!DOCTYPE html>
41
44
  <html>
42
45
  <head>
43
46
  <meta charset="utf-8" />
44
- <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
45
- <!-- Include your compiled assets -->
46
- <script type="module" src="/static/build/assets/index.js"></script>
47
- <link rel="stylesheet" href="/static/build/assets/index.css">
47
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
48
+ <script type="module" src="/static/assets/app.js"></script>
49
+ <link rel="stylesheet" href="/static/assets/app.css">
48
50
  </head>
49
51
  <body>
50
- <!-- The data-page attribute is crucial for Inertia -->
51
52
  <div id="app" data-page='{{{ page }}}'></div>
52
53
  </body>
53
54
  </html>
54
55
  ```
55
56
 
56
- ### 3. Return Responses
57
+ ### 3. Return Responses from Controllers
57
58
 
58
- In your controllers, simply use `inertia.render()`:
59
+ Use the `InertiaService` provided in the context:
59
60
 
60
61
  ```typescript
61
62
  import { Context } from '@gravito/photon';
62
63
  import { InertiaService } from '@gravito/ion';
63
64
 
64
- export class HomeController {
65
+ export class DashboardController {
65
66
  index = async (c: Context) => {
66
67
  const inertia = c.get('inertia') as InertiaService;
67
68
 
68
- return inertia.render('Home', {
69
- user: 'Carl',
70
- stats: { visits: 100 }
69
+ return inertia.render('Dashboard/Index', {
70
+ user: c.get('user'),
71
+ stats: { activeOrders: 5 }
71
72
  });
72
73
  };
73
74
  }
74
75
  ```
75
76
 
76
- The `'Home'` string corresponds to your frontend component path (e.g., `src/client/pages/Home.tsx`).
77
+ ## 🔧 Advanced Features
77
78
 
78
- ## 🔧 Client-Side Setup (React Example)
79
+ ### Shared Props
80
+ Automatically share data with every Inertia response (e.g., auth user, flash messages):
79
81
 
80
- You need to set up your client entry point (e.g., `src/client/app.tsx`):
82
+ ```typescript
83
+ inertia.share('auth', { user: 'Carl' });
84
+ ```
85
+
86
+ ### Partial Reloads
87
+ Ion supports Inertia's partial reloads, allowing the client to request only specific data to save bandwidth.
81
88
 
82
- ```tsx
83
- import { createInertiaApp } from '@inertiajs/react';
84
- import { createRoot } from 'react-dom/client';
89
+ ### Manual Serialization Control
90
+ Customize how your data is converted to JSON for the client:
85
91
 
86
- createInertiaApp({
87
- resolve: name => {
88
- const pages = import.meta.glob('./pages/**/*.tsx', { eager: true });
89
- return pages[`./pages/${name}.tsx`];
90
- },
91
- setup({ el, App, props }) {
92
- createRoot(el).render(<App {...props} />);
93
- },
92
+ ```typescript
93
+ inertia.render('ProductDetail', {
94
+ product: product.toShortArray() // Explicit control
94
95
  });
95
96
  ```
96
97
 
97
- See `templates/inertia-react` for a complete working example with Vite.
98
+ ## 🛡️ Performance & Reliability
99
+
100
+ ### Benchmarks (Internal)
101
+ | Operation | Latency |
102
+ |-----------|---------|
103
+ | Response Generation | < 0.2ms |
104
+ | Template Injection | < 0.1ms |
105
+ | Props Serialization | Optimized LRU Caching |
106
+
107
+ ### Error Codes
108
+ Ion provides detailed error types via `InertiaErrorCodes`:
109
+ - `CONFIG_VIEW_SERVICE_MISSING`: Ensure `OrbitPrism` is loaded.
110
+ - `SERIALIZATION_FAILED`: Circular dependencies detected in props.
111
+ - `TEMPLATE_RENDER_FAILED`: The base HTML template could not be found or parsed.
98
112
 
99
113
  ## 📝 License
100
114
 
101
- MIT
115
+ MIT © Carl Lee
package/README.zh-TW.md CHANGED
@@ -1,36 +1,115 @@
1
- # Orbit Inertia
1
+ # 🛰️ Orbit Inertia (Ion)
2
2
 
3
- > Gravito 的 Inertia.js 轉接器，可用 React/Vue 建立現代化單體應用。
3
+ > Gravito 的 Inertia.js 轉接器，用於建立現代化單體應用 (Modern Monolith)。支援 React、Vue 與 Svelte。
4
4
 
5
- ## 安裝
5
+ **Orbit Inertia** (@gravito/ion) 是一個高效能的轉接器，讓您能夠使用傳統的伺服器端路由與控制器來建立單頁應用程式 (SPA)。它扮演了 Gravito (Photon) 與前端框架之間的「膠水」，消除了開發獨立 REST 或 GraphQL API 的需求。
6
+
7
+ ## ✨ 核心特性
8
+
9
+ - **🚀 現代化單體架構**：結合伺服器端開發的高效率與 SPA 框架的高互動性。
10
+ - **🛠️ 零 API 開發**：直接將資料從控制器傳遞到組件作為具備型別的 Props，不再需要管理 API 端點或手動處理序列化。
11
+ - **⚡ 高效能渲染**：內建針對組件與元資料 (Metadata) 的多層快取機制，確保毫秒級的極低開銷。
12
+ - **🛡️ 原生型別安全**：完整的 TypeScript 支援，透過 Generics 確保從伺服器到前端的端到端型別安全。
13
+ - **🔗 生態系整合**：與 `OrbitPrism` (模板引擎) 及 Gravito 的 Session/Auth 模組完美協作。
14
+ - **🔍 SEO 與 SSR 友善**：專為現代 Web 需求設計，支援伺服器端渲染 (SSR) 模式以優化搜尋引擎可見度。
15
+ - **🎨 多框架支援**：官方支援 **React**、**Vue** 與 **Svelte**。
16
+
17
+ ## 📦 安裝
6
18
 
7
19
  ```bash
8
20
  bun add @gravito/ion
9
21
  ```
10
22
 
11
- ## 快速開始
23
+ ## 🚀 快速上手
24
+
25
+ ### 1. 註冊 Orbit
26
+
27
+ 在應用程式啟動程式碼中：
12
28
 
13
29
  ```typescript
14
- import { OrbitIon } from '@gravito/ion'
15
- import { OrbitPrism } from '@gravito/prism'
30
+ import { OrbitIon } from '@gravito/ion';
31
+ import { OrbitPrism } from '@gravito/prism'; // 渲染基礎 HTML 模板所需
16
32
 
17
33
  const config = defineConfig({
18
34
  orbits: [OrbitPrism, OrbitIon],
19
- })
35
+ });
36
+ ```
37
+
38
+ ### 2. 設定基礎模板
39
+
40
+ 預設情況下，Ion 會尋找 `src/views/app.html`。使用 `{{{ page }}}` 佔位符來注入 Inertia 的資料：
41
+
42
+ ```html
43
+ <!DOCTYPE html>
44
+ <html>
45
+ <head>
46
+ <meta charset="utf-8" />
47
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
48
+ <script type="module" src="/static/assets/app.js"></script>
49
+ <link rel="stylesheet" href="/static/assets/app.css">
50
+ </head>
51
+ <body>
52
+ <div id="app" data-page='{{{ page }}}'></div>
53
+ </body>
54
+ </html>
20
55
  ```
21
56
 
57
+ ### 3. 從控制器回傳回應
58
+
59
+ 使用 Context 中提供的 `InertiaService`：
60
+
22
61
  ```typescript
23
- import { Context } from '@gravito/photon'
24
- import { InertiaService } from '@gravito/ion'
62
+ import { Context } from '@gravito/photon';
63
+ import { InertiaService } from '@gravito/ion';
25
64
 
26
- export class HomeController {
65
+ export class DashboardController {
27
66
  index = async (c: Context) => {
28
- const inertia = c.get('inertia') as InertiaService
29
-
30
- return inertia.render('Home', {
31
- user: 'Carl',
32
- stats: { visits: 100 }
33
- })
34
- }
67
+ const inertia = c.get('inertia') as InertiaService;
68
+
69
+ return inertia.render('Dashboard/Index', {
70
+ user: c.get('user'),
71
+ stats: { activeOrders: 5 }
72
+ });
73
+ };
35
74
  }
36
75
  ```
76
+
77
+ ## 🔧 進階功能
78
+
79
+ ### 共享 Props (Shared Props)
80
+ 自動在每個 Inertia 回應中共享資料 (例如：當前用戶、快閃訊息)：
81
+
82
+ ```typescript
83
+ inertia.share('auth', { user: 'Carl' });
84
+ ```
85
+
86
+ ### 局部重新載入 (Partial Reloads)
87
+ Ion 支援 Inertia 的局部重載機制，允許客戶端僅請求特定資料以節省頻寬。
88
+
89
+ ### 手動序列化控制
90
+ 自定義資料如何轉換為 JSON 傳遞給客戶端：
91
+
92
+ ```typescript
93
+ inertia.render('ProductDetail', {
94
+ product: product.toShortArray() // 顯式控制
95
+ });
96
+ ```
97
+
98
+ ## 🛡️ 效能與可靠性
99
+
100
+ ### 基準測試 (內部測試)
101
+ | 操作 | 延遲 (Latency) |
102
+ |-----------|---------|
103
+ | 回應生成 | < 0.2ms |
104
+ | 模板注入 | < 0.1ms |
105
+ | Props 序列化 | 優化後的 LRU 快取 |
106
+
107
+ ### 錯誤代碼
108
+ Ion 透過 `InertiaErrorCodes` 提供詳細的錯誤類型：
109
+ - `CONFIG_VIEW_SERVICE_MISSING`：請確保已載入 `OrbitPrism`。
110
+ - `SERIALIZATION_FAILED`：在 Props 中偵測到循環依賴。
111
+ - `TEMPLATE_RENDER_FAILED`：找不到或無法解析基礎 HTML 模板。
112
+
113
+ ## 📝 授權
114
+
115
+ MIT © Carl Lee