odac 0.9.0 → 1.0.0

package/docs/backend/12-streaming/01-streaming-overview.md

@@ -1,6 +1,6 @@
 # Streaming API
 
-CandyPack provides a unified streaming API that automatically handles Server-Sent Events (SSE), with future support for WebSocket and HTTP/3.
+Odac provides a unified streaming API that automatically handles Server-Sent Events (SSE), with future support for WebSocket and HTTP/3.
 
 ## Quick Start
 
@@ -8,8 +8,8 @@ CandyPack provides a unified streaming API that automatically handles Server-Sen
 
 ```javascript
 // route/www.js
-Candy.Route.get('/hello', async (Candy) => {
-  Candy.stream('Hello World')
+Odac.Route.get('/hello', async (Odac) => {
+  Odac.stream('Hello World')
 })
 ```
 
@@ -17,11 +17,11 @@ Candy.Route.get('/hello', async (Candy) => {
 
 ```javascript
 // route/www.js
-Candy.Route.get('/hello', 'hello')
+Odac.Route.get('/hello', 'hello')
 
 // controller/hello/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream('Hello World')
+module.exports = async (Odac) => {
+  Odac.stream('Hello World')
 }
 ```
 
@@ -29,34 +29,37 @@ module.exports = async (Candy) => {
 
 ```javascript
 // controller/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream({ message: 'Hello', time: Date.now() })
+module.exports = async (Odac) => {
+  Odac.stream({ message: 'Hello', time: Date.now() })
 }
 ```
 
 ## Multiple Messages
 
-### Callback Pattern
+### Callback Pattern with Auto-Cleanup
 
 ```javascript
 // controller/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream((send) => {
+module.exports = async (Odac) => {
+  Odac.stream((send) => {
     send({ type: 'connected' })
     
-    setInterval(() => {
+    // Use Odac.setInterval for automatic cleanup
+    Odac.setInterval(() => {
       send({ time: Date.now() })
     }, 1000)
   })
 }
 ```
 
-### With Cleanup
+**Important:** Always use `Odac.setInterval()` and `Odac.setTimeout()` instead of global functions. They are automatically cleaned up when the connection closes.
+
+### Manual Cleanup (Alternative)
 
 ```javascript
 // controller/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream((send, close) => {
+module.exports = async (Odac) => {
+  Odac.stream((send, close) => {
     send({ type: 'connected' })
     
     const interval = setInterval(() => {
@@ -77,8 +80,8 @@ module.exports = async (Candy) => {
 
 ```javascript
 // controller/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream([1, 2, 3, 4, 5])
+module.exports = async (Odac) => {
+  Odac.stream([1, 2, 3, 4, 5])
 }
 ```
 
@@ -86,9 +89,9 @@ module.exports = async (Candy) => {
 
 ```javascript
 // controller/users/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream(async function* () {
-    const users = await Candy.Mysql.table('users').get()
+module.exports = async (Odac) => {
+  Odac.stream(async function* () {
+    const users = await Odac.Mysql.table('users').get()
     
     for (const user of users) {
       yield user
@@ -101,8 +104,8 @@ module.exports = async (Candy) => {
 
 ```javascript
 // controller/app/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream(
+module.exports = async (Odac) => {
+  Odac.stream(
     fetch('https://api.example.com/data')
       .then(r => r.json())
   )
@@ -113,9 +116,9 @@ module.exports = async (Candy) => {
 
 ```javascript
 // controller/file/get/index.js
-module.exports = async (Candy) => {
+module.exports = async (Odac) => {
   const fs = require('fs')
-  Candy.stream(fs.createReadStream('large-file.txt'))
+  Odac.stream(fs.createReadStream('large-file.txt'))
 }
 ```
 
@@ -125,27 +128,26 @@ module.exports = async (Candy) => {
 
 ```javascript
 // controller/monitor/get/index.js
-module.exports = async (Candy) => {
-  const stream = Candy.stream()
-  
-  stream.send({ type: 'connected' })
-  
-  const interval = setInterval(() => {
-    stream.send({ time: Date.now() })
-  }, 1000)
-  
-  stream.on('close', () => {
-    clearInterval(interval)
+module.exports = async (Odac) => {
+  return Odac.stream((send) => {
+    send({ type: 'connected' })
+    
+    // Use Odac.setInterval for automatic cleanup
+    Odac.setInterval(() => {
+      send({ time: Date.now() })
+    }, 1000)
   })
 }
 ```
 
+**Note:** When using `Odac.setInterval()` or `Odac.setTimeout()`, cleanup is automatic. No need for manual `clearInterval()` or `clearTimeout()`.
+
 ### Error Handling
 
 ```javascript
 // controller/data/get/fetch.js
-module.exports = async (Candy) => {
-  const stream = Candy.stream()
+module.exports = async (Odac) => {
+  const stream = Odac.stream()
   
   try {
     const data = await fetchData()
@@ -162,11 +164,11 @@ module.exports = async (Candy) => {
 
 ```javascript
 // route/www.js
-Candy.Route.get('/logs', 'logs')
+Odac.Route.get('/logs', 'logs')
 
 // controller/logs/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream(async function* () {
+module.exports = async (Odac) => {
+  return Odac.stream(async function* () {
     const logStream = await getDeploymentLogs()
     
     for await (const log of logStream) {
@@ -183,16 +185,16 @@ module.exports = async (Candy) => {
 
 ```javascript
 // route/www.js
-Candy.Route.get('/posts', 'posts')
+Odac.Route.get('/posts', 'posts')
 
 // controller/posts/get/index.js
-module.exports = async (Candy) => {
-  Candy.stream(async function* () {
+module.exports = async (Odac) => {
+  return Odac.stream(async function* () {
     let page = 1
     let hasMore = true
     
     while (hasMore) {
-      const posts = await Candy.Mysql.table('posts')
+      const posts = await Odac.Mysql.table('posts')
         .limit(10)
         .offset((page - 1) * 10)
         .get()
@@ -261,7 +263,7 @@ function Dashboard() {
 
 ## Protocol
 
-CandyPack uses **Server-Sent Events (SSE)** for streaming:
+Odac uses **Server-Sent Events (SSE)** for streaming:
 - ✅ One-way communication (server → client)
 - ✅ Automatic reconnection
 - ✅ Works over HTTP/2
@@ -275,26 +277,66 @@ CandyPack uses **Server-Sent Events (SSE)** for streaming:
 - **Reconnection:** Automatic (browser handles)
 - **Compression:** Supported via HTTP/2
 
+## Memory Management
+
+Odac automatically manages timers and intervals in streaming contexts:
+
+```javascript
+module.exports = async (Odac) => {
+  return Odac.stream((send) => {
+    // ✅ Automatically cleaned up when connection closes
+    Odac.setInterval(() => {
+      send({ time: Date.now() })
+    }, 1000)
+    
+    Odac.setTimeout(() => {
+      send({ type: 'delayed' })
+    }, 5000)
+  })
+}
+```
+
+**Why this matters:**
+- Prevents memory leaks
+- No orphaned intervals after disconnect
+- Automatic cleanup on connection close
+
+**Manual cleanup (if needed):**
+```javascript
+const intervalId = Odac.setInterval(() => { ... }, 1000)
+Odac.clearInterval(intervalId)
+
+const timeoutId = Odac.setTimeout(() => { ... }, 5000)
+Odac.clearTimeout(timeoutId)
+```
+
 ## Best Practices
 
-1. **Always handle cleanup:** Use the cleanup function or `stream.on('close')`
-2. **Throttle messages:** Don't send too frequently (use intervals)
-3. **Handle errors:** Use try-catch and `stream.error()`
-4. **Close when done:** Call `stream.close()` when finished
+1. **Use Odac timers:** Always use `Odac.setInterval()` and `Odac.setTimeout()` instead of global functions
+2. **Return the stream:** Always `return Odac.stream(...)` from your controller
+3. **Throttle messages:** Don't send too frequently (use intervals)
+4. **Handle errors:** Use try-catch for async operations
 5. **Test reconnection:** Ensure your app handles connection drops
 
 ## Troubleshooting
 
 **Connection drops immediately:**
-- Check if you're calling `Candy.return()` or `res.end()`
+- Check if you're calling `Odac.return()` or `res.end()`
 - Don't use both streaming and regular responses
+- Make sure to `return Odac.stream(...)`
 
 **Messages not received:**
 - Verify JSON format
 - Check browser console for errors
 - Ensure CORS headers if cross-origin
 
-**High memory usage:**
-- Limit number of concurrent connections
-- Implement cleanup properly
-- Use throttling for frequent updates
+**High memory usage / Memory leaks:**
+- Use `Odac.setInterval()` instead of global `setInterval()`
+- Use `Odac.setTimeout()` instead of global `setTimeout()`
+- Avoid creating intervals outside the stream callback
+- Check for other resource leaks (database connections, file handles)
+
+**Intervals keep running after disconnect:**
+- Replace `setInterval()` with `Odac.setInterval()`
+- Replace `setTimeout()` with `Odac.setTimeout()`
+- These are automatically cleaned up when the connection closes