@livetemplate/client 0.1.0 โ†’ 0.3.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 (23) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +171 -115
  3. package/dist/livetemplate-client.browser.js +5 -5
  4. package/dist/livetemplate-client.browser.js.map +4 -4
  5. package/dist/livetemplate-client.d.ts +5 -0
  6. package/dist/livetemplate-client.d.ts.map +1 -1
  7. package/dist/livetemplate-client.js +66 -0
  8. package/dist/livetemplate-client.js.map +1 -1
  9. package/dist/tests/test-reconstruction.test.js +1 -1
  10. package/dist/tests/test-reconstruction.test.js.map +1 -1
  11. package/dist/upload/s3-uploader.d.ts +11 -0
  12. package/dist/upload/s3-uploader.d.ts.map +1 -0
  13. package/dist/upload/s3-uploader.js +71 -0
  14. package/dist/upload/s3-uploader.js.map +1 -0
  15. package/dist/upload/types.d.ts +96 -0
  16. package/dist/upload/types.d.ts.map +1 -0
  17. package/dist/upload/types.js +6 -0
  18. package/dist/upload/types.js.map +1 -0
  19. package/dist/upload/upload-handler.d.ts +71 -0
  20. package/dist/upload/upload-handler.d.ts.map +1 -0
  21. package/dist/upload/upload-handler.js +315 -0
  22. package/dist/upload/upload-handler.js.map +1 -0
  23. package/package.json +5 -6
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Adnaan Badr
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,179 +1,235 @@
1
- # LiveTemplate TypeScript Client
1
+ # @livetemplate/client
2
2
 
3
- A TypeScript client for consuming LiveTemplate tree-based updates, implementing Phoenix LiveView-style optimization.
3
+ TypeScript/JavaScript client library for LiveTemplate - reactive HTML over the wire.
4
4
 
5
- ## ๐Ÿš€ Features
5
+ ## Overview
6
6
 
7
- - **Tree-based Updates**: Consume optimized JSON updates from LiveTemplate server
8
- - **Static Structure Caching**: Cache static HTML structure client-side for maximum efficiency
9
- - **Phoenix LiveView Compatible**: Only dynamic values transmitted after initial render
10
- - **Bandwidth Optimization**: 75%+ reduction in update payload sizes
11
- - **Type Safety**: Full TypeScript support with type definitions
7
+ The LiveTemplate client enables reactive web applications by efficiently applying tree-based HTML updates from the server. It uses DOM morphing, intelligent static content caching, and WebSocket transport for real-time interactivity.
12
8
 
13
- ## ๐Ÿ“ฆ Installation
9
+ ## Features
14
10
 
15
- ```bash
16
- npm install
17
- npm run build
18
- ```
11
+ - **Tree-based Updates**: Efficiently applies minimal JSON updates to the DOM
12
+ - **Static Structure Caching**: Client caches static HTML, receives only dynamic changes
13
+ - **DOM Morphing**: Uses morphdom for efficient, minimal DOM updates
14
+ - **WebSocket Transport**: Real-time bidirectional communication
15
+ - **Focus Management**: Preserves focus during updates
16
+ - **Form Lifecycle**: Automatic form state management
17
+ - **Event Delegation**: Efficient event handling
18
+ - **Modal Management**: Built-in modal support
19
+ - **TypeScript**: Full type safety and IDE support
19
20
 
20
- ## ๐Ÿงช Testing
21
+ ## Installation
21
22
 
22
- The client includes comprehensive tests to validate the optimization effectiveness:
23
+ ### npm
23
24
 
24
25
  ```bash
25
- # Run optimization validation tests
26
- npm run test:optimization
27
-
28
- # Run HTML reconstruction tests
29
- npm run test:reconstruction
30
-
31
- # Run all tests
32
- npm run test:all
26
+ npm install @livetemplate/client
33
27
  ```
34
28
 
35
- ## ๐Ÿ“Š Test Results
36
-
37
- Current optimization performance:
29
+ ### CDN
38
30
 
39
- - **Update 1**: 168 bytes (first update after initial render)
40
- - **Update 2**: 128 bytes (subsequent optimized update)
41
- - **Bandwidth Savings**: ~75.3% vs full HTML updates
42
- - **Static Structure**: Successfully excluded from updates โœ…
31
+ ```html
32
+ <script src="https://cdn.jsdelivr.net/npm/@livetemplate/client@0.1.0/dist/livetemplate-client.browser.js"></script>
33
+ ```
43
34
 
44
- ## ๐Ÿ› ๏ธ Usage
35
+ ## Quick Start
36
+
37
+ ### Browser (via CDN)
38
+
39
+ ```html
40
+ <!DOCTYPE html>
41
+ <html>
42
+ <head>
43
+ <script src="https://cdn.jsdelivr.net/npm/@livetemplate/client@0.1.0/dist/livetemplate-client.browser.js"></script>
44
+ </head>
45
+ <body>
46
+ <div id="app"></div>
47
+ <script>
48
+ const client = new LiveTemplateClient.LiveTemplateClient({
49
+ targetSelector: "#app",
50
+ wsUrl: "ws://localhost:8080/ws",
51
+ httpUrl: "http://localhost:8080"
52
+ });
53
+
54
+ client.connect();
55
+ </script>
56
+ </body>
57
+ </html>
58
+ ```
45
59
 
46
- ### Basic Client Usage
60
+ ### TypeScript/ES Modules
47
61
 
48
62
  ```typescript
49
- import { LiveTemplateClient } from "./livetemplate-client";
63
+ import { LiveTemplateClient } from "@livetemplate/client";
50
64
 
51
- const client = new LiveTemplateClient();
52
-
53
- // Apply initial update (includes static structure)
54
- const initialResult = client.applyUpdate({
55
- s: ["<h1>", "</h1><p>Count: ", "</p>"], // Static HTML segments
56
- "0": "Hello World", // Dynamic content
57
- "1": "42", // Dynamic content
65
+ const client = new LiveTemplateClient({
66
+ targetSelector: "#app",
67
+ wsUrl: "ws://localhost:8080/ws",
68
+ httpUrl: "http://localhost:8080"
58
69
  });
59
70
 
60
- console.log(initialResult.html); // "<h1>Hello World</h1><p>Count: 42</p>"
71
+ client.connect();
72
+ ```
61
73
 
62
- // Apply subsequent update (only changed dynamic values)
63
- const updateResult = client.applyUpdate({
64
- "1": "43", // Only the changed value
65
- });
74
+ ## Configuration Options
66
75
 
67
- console.log(updateResult.html); // "<h1>Hello World</h1><p>Count: 43</p>"
68
- console.log(updateResult.changed); // true
76
+ ```typescript
77
+ interface LiveTemplateClientOptions {
78
+ // Required
79
+ targetSelector: string; // CSS selector for target element
80
+ wsUrl: string; // WebSocket URL
81
+ httpUrl: string; // HTTP URL for initial render
82
+
83
+ // Optional
84
+ debug?: boolean; // Enable debug logging (default: false)
85
+ reconnectInterval?: number; // Reconnect interval in ms (default: 3000)
86
+ maxReconnectAttempts?: number;// Max reconnect attempts (default: 10)
87
+ }
69
88
  ```
70
89
 
71
- ### Loading Updates from Files
90
+ ## API
91
+
92
+ ### Client Methods
72
93
 
73
94
  ```typescript
74
- import { loadAndApplyUpdate } from "./livetemplate-client";
95
+ // Connect to server
96
+ client.connect(): void
97
+
98
+ // Disconnect from server
99
+ client.disconnect(): void
75
100
 
76
- const client = new LiveTemplateClient();
101
+ // Send event to server
102
+ client.sendEvent(event: string, data: any): void
77
103
 
78
- // Load update from JSON file
79
- const result = await loadAndApplyUpdate(client, "update_01.json");
80
- console.log(result.html);
104
+ // Set debug mode
105
+ client.setDebug(enabled: boolean): void
81
106
  ```
82
107
 
83
- ### HTML Comparison
108
+ ### Events
109
+
110
+ The client emits events you can listen to:
84
111
 
85
112
  ```typescript
86
- import { compareHTML } from "./livetemplate-client";
113
+ // Connection established
114
+ window.addEventListener("livetemplate:connected", (e) => {
115
+ console.log("Connected to server");
116
+ });
87
117
 
88
- const comparison = compareHTML(expectedHTML, actualHTML);
89
- if (comparison.match) {
90
- console.log("โœ… HTML matches!");
91
- } else {
92
- console.log("โŒ Differences found:", comparison.differences);
93
- }
118
+ // Connection closed
119
+ window.addEventListener("livetemplate:disconnected", (e) => {
120
+ console.log("Disconnected from server");
121
+ });
122
+
123
+ // Update received
124
+ window.addEventListener("livetemplate:update", (e) => {
125
+ console.log("Received update:", e.detail);
126
+ });
94
127
  ```
95
128
 
96
- ## ๐Ÿ—๏ธ Architecture
129
+ ## How It Works
97
130
 
98
- ### Tree-Based Updates
131
+ 1. **Initial Render**: Client fetches full HTML from server, caches static structure
132
+ 2. **Updates**: Server sends only changed dynamic values as tree updates
133
+ 3. **DOM Morphing**: Client applies updates using morphdom for minimal DOM changes
134
+ 4. **Caching**: Static HTML structure is cached, never re-transmitted
99
135
 
100
- LiveTemplate uses a tree-based approach where:
136
+ This results in **~75% reduction** in update payload sizes compared to full HTML updates.
101
137
 
102
- 1. **Static Structure** (`"s"` key): HTML segments sent once and cached client-side
103
- 2. **Dynamic Values** (numbered keys): Only the values that change between updates
104
- 3. **Segment Interleaving**: Client reconstructs HTML by interleaving static + dynamic
138
+ ## Development
105
139
 
106
- Example update structure:
140
+ ### Setup
107
141
 
108
- ```json
109
- {
110
- "s": ["<h1>", "</h1><div>Count: ", "</div>"], // Static HTML (sent once)
111
- "0": "Task Manager", // Dynamic: page title
112
- "1": "42" // Dynamic: counter value
113
- }
114
- ```
142
+ ```bash
143
+ # Clone repository
144
+ git clone https://github.com/livetemplate/client.git
145
+ cd client
115
146
 
116
- ### Optimization Strategy
147
+ # Install dependencies
148
+ npm install
117
149
 
118
- Following Phoenix LiveView's approach:
150
+ # Run tests
151
+ npm test
119
152
 
120
- - **Initial Render**: Full HTML + cached static structure
121
- - **Subsequent Updates**: Only changed dynamic values (75%+ bandwidth savings)
122
- - **Client Reconstruction**: Merge updates with cached structure
123
- - **DOM Morphing**: Let morphdom handle efficient DOM updates
153
+ # Build
154
+ npm run build
155
+ ```
124
156
 
125
- ## ๐Ÿงช Test Data
157
+ ### Project Structure
126
158
 
127
- The test suite validates optimization using real E2E test data:
159
+ ```
160
+ client/
161
+ โ”œโ”€โ”€ livetemplate-client.ts # Main client
162
+ โ”œโ”€โ”€ dom/ # DOM utilities
163
+ โ”‚ โ”œโ”€โ”€ directives.ts
164
+ โ”‚ โ”œโ”€โ”€ event-delegation.ts
165
+ โ”‚ โ”œโ”€โ”€ focus-manager.ts
166
+ โ”‚ โ”œโ”€โ”€ form-disabler.ts
167
+ โ”‚ โ”œโ”€โ”€ loading-indicator.ts
168
+ โ”‚ โ”œโ”€โ”€ modal-manager.ts
169
+ โ”‚ โ””โ”€โ”€ observer-manager.ts
170
+ โ”œโ”€โ”€ state/ # State management
171
+ โ”‚ โ”œโ”€โ”€ form-lifecycle-manager.ts
172
+ โ”‚ โ””โ”€โ”€ tree-renderer.ts
173
+ โ”œโ”€โ”€ transport/ # Network layer
174
+ โ”‚ โ””โ”€โ”€ websocket.ts
175
+ โ”œโ”€โ”€ utils/ # Utilities
176
+ โ”‚ โ”œโ”€โ”€ logger.ts
177
+ โ”‚ โ”œโ”€โ”€ rate-limit.ts
178
+ โ”‚ โ””โ”€โ”€ testing.ts
179
+ โ””โ”€โ”€ tests/ # Test suite
180
+ ```
128
181
 
129
- - `testdata/e2e/update_01_add_todos.json` - First optimized update (168 bytes)
130
- - `testdata/e2e/update_02_remove_todo.json` - Subsequent update (128 bytes)
131
- - `testdata/e2e/rendered_*.html` - Expected HTML output for comparison
182
+ ### Running Tests
132
183
 
133
- ## ๐Ÿ”ง API Reference
184
+ ```bash
185
+ # Run all tests
186
+ npm test
134
187
 
135
- ### LiveTemplateClient
188
+ # Run specific test
189
+ npm test -- focus-manager
136
190
 
137
- #### `applyUpdate(update: TreeNode): UpdateResult`
191
+ # Run with coverage
192
+ npm test -- --coverage
193
+ ```
138
194
 
139
- Apply a tree-based update to the client state.
195
+ ### Building
140
196
 
141
- - **Parameters**: `update` - Tree update object from LiveTemplate server
142
- - **Returns**: `{ html: string, changed: boolean }`
197
+ ```bash
198
+ # Build TypeScript and browser bundle
199
+ npm run build
143
200
 
144
- #### `reset(): void`
201
+ # Build browser bundle only
202
+ npm run build:browser
145
203
 
146
- Reset client state (useful for testing).
204
+ # Clean build artifacts
205
+ npm run clean
206
+ ```
147
207
 
148
- #### `getState(): { static: string[] | null, dynamic: object }`
208
+ ## Related Projects
149
209
 
150
- Get current cached state for debugging.
210
+ - **[LiveTemplate Core](https://github.com/livetemplate/livetemplate)** - Go library for server-side rendering
211
+ - **[LVT CLI](https://github.com/livetemplate/lvt)** - Code generator and development server
212
+ - **[Examples](https://github.com/livetemplate/examples)** - Example applications
151
213
 
152
- ### Utility Functions
214
+ ## Version Synchronization
153
215
 
154
- #### `loadAndApplyUpdate(client, path): Promise<UpdateResult>`
216
+ This client library follows the LiveTemplate core library's major.minor version. For example:
155
217
 
156
- Load update from JSON file and apply to client.
218
+ - Core: `v0.1.5` โ†’ Client: `v0.1.x` (any patch version)
219
+ - Core: `v0.2.0` โ†’ Client: `v0.2.0` (must match major.minor)
157
220
 
158
- #### `compareHTML(expected, actual): { match: boolean, differences: string[] }`
221
+ Patch versions are independent and can be incremented for client-specific fixes.
159
222
 
160
- Compare two HTML strings, ignoring whitespace differences.
223
+ ## Contributing
161
224
 
162
- ## ๐Ÿš€ Performance
225
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
163
226
 
164
- Optimization results with real E2E test data:
227
+ ## License
165
228
 
166
- | Update Type | Size (bytes) | Bandwidth Savings |
167
- | ------------ | ------------ | ----------------- |
168
- | Full HTML | ~600 | 0% (baseline) |
169
- | Optimized #1 | 168 | 72% |
170
- | Optimized #2 | 128 | 79% |
171
- | **Average** | **148** | **~75.3%** |
229
+ MIT License - see [LICENSE](LICENSE) for details.
172
230
 
173
- ## ๐Ÿ“ˆ Future Enhancements
231
+ ## Support
174
232
 
175
- - Browser-based DOM morphing integration
176
- - WebSocket client for real-time updates
177
- - React/Vue.js integration hooks
178
- - Advanced diff algorithms for complex nested structures
179
- - Performance monitoring and metrics
233
+ - **Issues**: [GitHub Issues](https://github.com/livetemplate/client/issues)
234
+ - **Discussions**: [GitHub Discussions](https://github.com/livetemplate/client/discussions)
235
+ - **Documentation**: [LiveTemplate Docs](https://github.com/livetemplate/livetemplate)