@flexireact/core 2.2.0 → 2.4.0

package/README.md

@@ -20,8 +20,21 @@
   <a href="#"><img src="https://img.shields.io/badge/Tailwind-v4-38B2AC.svg" alt="Tailwind CSS v4" /></a>
 </p>
 
-## 🆕 What's New in v2
+## 🆕 What's New in v2.2
 
+### v2.2.0 (Latest)
+- **🌊 Streaming SSR** — Progressive HTML rendering with React 18 `renderToPipeableStream`
+- **⚡ Server Actions** — Call server functions directly from client components
+- **🔗 Link Prefetching** — Automatic prefetch on hover/viewport visibility
+
+### v2.1.0
+- **🛠️ Server Helpers** — `redirect()`, `notFound()`, `json()`, `cookies`, `headers`
+- **🚧 Error/Loading Boundaries** — Per-segment `error.tsx` and `loading.tsx`
+- **🔐 Route Middleware** — `_middleware.ts` for per-route logic
+- **📊 Bundle Analyzer** — `flexi build --analyze`
+- **🔄 CI/CD** — GitHub Actions workflow
+
+### v2.0.0
 - **TypeScript Native** — Core rewritten in TypeScript for better DX
 - **Tailwind CSS v4** — New `@import "tailwindcss"` and `@theme` syntax
 - **Routes Directory** — New `routes/` directory with route groups, dynamic segments
@@ -401,21 +414,117 @@ export function post(req, res) {
 }
 ```
 
+## ⚡ Server Actions (v2.2+)
+
+Call server functions directly from client components:
+
+```tsx
+// actions.ts
+'use server';
+import { serverAction, redirect, cookies } from '@flexireact/core';
+
+export const createUser = serverAction(async (formData: FormData) => {
+  const name = formData.get('name') as string;
+  const user = await db.users.create({ name });
+  
+  // Set a cookie
+  cookies.set('userId', user.id);
+  
+  // Redirect after action
+  redirect('/users');
+});
+
+// Form.tsx
+'use client';
+import { createUser } from './actions';
+
+export function CreateUserForm() {
+  return (
+    <form action={createUser}>
+      <input name="name" placeholder="Name" required />
+      <button type="submit">Create User</button>
+    </form>
+  );
+}
+```
+
+## 🔗 Link with Prefetching (v2.1+)
+
+Enhanced Link component with automatic prefetching:
+
+```tsx
+import { Link } from '@flexireact/core/client';
+
+// Prefetch on hover (default)
+<Link href="/about">About</Link>
+
+// Prefetch when visible in viewport
+<Link href="/products" prefetch="viewport">Products</Link>
+
+// Replace history instead of push
+<Link href="/login" replace>Login</Link>
+
+// Programmatic navigation
+import { useRouter } from '@flexireact/core/client';
+
+function MyComponent() {
+  const router = useRouter();
+  
+  return (
+    <button onClick={() => router.push('/dashboard')}>
+      Go to Dashboard
+    </button>
+  );
+}
+```
+
+## 🛠️ Server Helpers (v2.1+)
+
+Utility functions for server-side operations:
+
+```tsx
+import { redirect, notFound, json, cookies, headers } from '@flexireact/core';
+
+// Redirect
+redirect('/dashboard');
+redirect('/login', 'permanent'); // 308 redirect
+
+// Not Found
+notFound(); // Throws 404
+
+// JSON Response (in API routes)
+return json({ data: 'hello' }, { status: 200 });
+
+// Cookies
+const token = cookies.get(request, 'token');
+const setCookie = cookies.set('session', 'abc123', { 
+  httpOnly: true, 
+  maxAge: 86400 
+});
+
+// Headers
+const auth = headers.bearerToken(request);
+const corsHeaders = headers.cors({ origin: '*' });
+const securityHeaders = headers.security();
+```
+
 ## 🛡️ Middleware
 
-Create `middleware.js` in your project root:
+### Global Middleware
+
+Create `middleware.ts` in your project root:
+
+```ts
+import { redirect, cookies } from '@flexireact/core';
 
-```js
 export default function middleware(request) {
   // Protect routes
   if (request.pathname.startsWith('/admin')) {
-    if (!request.cookie('token')) {
-      return MiddlewareResponse.redirect('/login');
+    const token = cookies.get(request, 'token');
+    if (!token) {
+      redirect('/login');
     }
   }
-  
-  // Continue
-  return MiddlewareResponse.next();
 }
 
 export const config = {
@@ -423,6 +532,32 @@ export const config = {
 };
 ```
 
+### Route Middleware (v2.1+)
+
+Create `_middleware.ts` in any route directory:
+
+```
+routes/
+  admin/
+    _middleware.ts   # Runs for all /admin/* routes
+    dashboard.tsx
+    settings.tsx
+```
+
+```ts
+// routes/admin/_middleware.ts
+export default async function middleware(req, res, { route, params }) {
+  const user = await getUser(req);
+  
+  if (!user?.isAdmin) {
+    return { redirect: '/login' };
+  }
+  
+  // Continue to route
+  return { user };
+}
+```
+
 ## 🔧 Configuration
 
 Create `flexireact.config.js`:
@@ -496,15 +631,68 @@ export default {
 ## 🖥️ CLI Commands
 
 ```bash
-flexi create <name>   # Create new project
-flexi dev             # Start dev server
-flexi build           # Build for production
-flexi start           # Start production server
-flexi doctor          # Check project health
-flexi --version       # Show version
-flexi help            # Show help
+flexi create <name>      # Create new project
+flexi dev                # Start dev server
+flexi build              # Build for production
+flexi build --analyze    # Build with bundle analysis
+flexi start              # Start production server
+flexi doctor             # Check project health
+flexi --version          # Show version
+flexi help               # Show help
 ```
 
+### Bundle Analysis (v2.1+)
+
+```bash
+flexi build --analyze
+```
+
+Output:
+```
+📊 Bundle Analysis:
+
+  ─────────────────────────────────────────────────
+  File                                   Size
+  ─────────────────────────────────────────────────
+  client/main.js                         45.2 KB (13.56 KB gzip)
+  client/vendor.js                       120.5 KB (38.2 KB gzip)
+  server/pages.js                        12.3 KB
+  ─────────────────────────────────────────────────
+  Total:                                 178 KB
+  Gzipped:                               51.76 KB
+```
+
+## 🌊 Streaming SSR (v2.2+)
+
+Progressive HTML rendering with React 18:
+
+```tsx
+import { renderPageStream, streamToResponse } from '@flexireact/core';
+
+// In your server handler
+const { stream, shellReady } = await renderPageStream({
+  Component: MyPage,
+  props: { data },
+  loading: LoadingSpinner,
+  error: ErrorBoundary,
+  title: 'My Page',
+  styles: ['/styles.css']
+});
+
+// Wait for shell (initial HTML) to be ready
+await shellReady;
+
+// Stream to response
+res.setHeader('Content-Type', 'text/html');
+streamToResponse(res, stream);
+```
+
+Benefits:
+- **Faster Time to First Byte (TTFB)** — Send HTML as it's ready
+- **Progressive Loading** — Users see content immediately
+- **Suspense Support** — Loading states stream in as data resolves
+- **Better UX** — No blank screen while waiting for data
+
 ## 📚 Concepts Explained
 
 ### React Server Components (RSC)

package/core/edge/cache.ts

@@ -0,0 +1,344 @@
+/**
+ * FlexiReact Universal Cache System
+ * 
+ * Smart caching that works on:
+ * - Cloudflare Workers (Cache API + KV)
+ * - Vercel Edge (Edge Config + KV)
+ * - Deno (Deno KV)
+ * - Node.js/Bun (In-memory + File cache)
+ */
+
+import { detectRuntime } from './runtime.js';
+
+// Cache entry
+export interface CacheEntry<T = any> {
+  value: T;
+  expires: number; // timestamp
+  stale?: number; // stale-while-revalidate timestamp
+  tags?: string[];
+  etag?: string;
+}
+
+// Cache options
+export interface CacheOptions {
+  ttl?: number; // seconds
+  staleWhileRevalidate?: number; // seconds
+  tags?: string[];
+  key?: string;
+  revalidate?: number | false; // ISR-style revalidation
+}
+
+// Cache storage interface
+export interface CacheStorage {
+  get<T>(key: string): Promise<CacheEntry<T> | null>;
+  set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+  delete(key: string): Promise<void>;
+  deleteByTag(tag: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+// In-memory cache (fallback)
+class MemoryCache implements CacheStorage {
+  private store = new Map<string, CacheEntry>();
+  private tagIndex = new Map<string, Set<string>>();
+  
+  async get<T>(key: string): Promise<CacheEntry<T> | null> {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    
+    // Check expiration
+    if (entry.expires && entry.expires < Date.now()) {
+      // Check stale-while-revalidate
+      if (entry.stale && entry.stale > Date.now()) {
+        return { ...entry, value: entry.value as T };
+      }
+      this.store.delete(key);
+      return null;
+    }
+    
+    return { ...entry, value: entry.value as T };
+  }
+  
+  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
+    this.store.set(key, entry);
+    
+    // Index by tags
+    if (entry.tags) {
+      entry.tags.forEach(tag => {
+        if (!this.tagIndex.has(tag)) {
+          this.tagIndex.set(tag, new Set());
+        }
+        this.tagIndex.get(tag)!.add(key);
+      });
+    }
+  }
+  
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+  
+  async deleteByTag(tag: string): Promise<void> {
+    const keys = this.tagIndex.get(tag);
+    if (keys) {
+      keys.forEach(key => this.store.delete(key));
+      this.tagIndex.delete(tag);
+    }
+  }
+  
+  async clear(): Promise<void> {
+    this.store.clear();
+    this.tagIndex.clear();
+  }
+}
+
+// Cloudflare KV cache
+class CloudflareCache implements CacheStorage {
+  private kv: any;
+  
+  constructor(kv: any) {
+    this.kv = kv;
+  }
+  
+  async get<T>(key: string): Promise<CacheEntry<T> | null> {
+    try {
+      const data = await this.kv.get(key, 'json');
+      if (!data) return null;
+      
+      const entry = data as CacheEntry<T>;
+      if (entry.expires && entry.expires < Date.now()) {
+        if (entry.stale && entry.stale > Date.now()) {
+          return entry;
+        }
+        await this.kv.delete(key);
+        return null;
+      }
+      
+      return entry;
+    } catch {
+      return null;
+    }
+  }
+  
+  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
+    const ttl = entry.expires ? Math.ceil((entry.expires - Date.now()) / 1000) : undefined;
+    await this.kv.put(key, JSON.stringify(entry), { expirationTtl: ttl });
+  }
+  
+  async delete(key: string): Promise<void> {
+    await this.kv.delete(key);
+  }
+  
+  async deleteByTag(tag: string): Promise<void> {
+    // KV doesn't support tag-based deletion natively
+    // Would need to maintain a tag index
+    console.warn('Tag-based deletion not fully supported in Cloudflare KV');
+  }
+  
+  async clear(): Promise<void> {
+    // KV doesn't support clear
+    console.warn('Clear not supported in Cloudflare KV');
+  }
+}
+
+// Deno KV cache
+class DenoKVCache implements CacheStorage {
+  private kv: any;
+  
+  constructor() {
+    // @ts-ignore - Deno global
+    this.kv = Deno.openKv();
+  }
+  
+  async get<T>(key: string): Promise<CacheEntry<T> | null> {
+    try {
+      const kv = await this.kv;
+      const result = await kv.get(['cache', key]);
+      if (!result.value) return null;
+      
+      const entry = result.value as CacheEntry<T>;
+      if (entry.expires && entry.expires < Date.now()) {
+        if (entry.stale && entry.stale > Date.now()) {
+          return entry;
+        }
+        await kv.delete(['cache', key]);
+        return null;
+      }
+      
+      return entry;
+    } catch {
+      return null;
+    }
+  }
+  
+  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
+    const kv = await this.kv;
+    await kv.set(['cache', key], entry);
+  }
+  
+  async delete(key: string): Promise<void> {
+    const kv = await this.kv;
+    await kv.delete(['cache', key]);
+  }
+  
+  async deleteByTag(tag: string): Promise<void> {
+    // Would need tag index
+    console.warn('Tag-based deletion requires tag index in Deno KV');
+  }
+  
+  async clear(): Promise<void> {
+    // Would need to iterate all keys
+    console.warn('Clear requires iteration in Deno KV');
+  }
+}
+
+// Create cache based on runtime
+function createCacheStorage(options?: { kv?: any }): CacheStorage {
+  const runtime = detectRuntime();
+  
+  switch (runtime) {
+    case 'cloudflare':
+      if (options?.kv) {
+        return new CloudflareCache(options.kv);
+      }
+      return new MemoryCache();
+    
+    case 'deno':
+      return new DenoKVCache();
+    
+    case 'node':
+    case 'bun':
+    default:
+      return new MemoryCache();
+  }
+}
+
+// Main cache instance
+let cacheStorage: CacheStorage = new MemoryCache();
+
+// Initialize cache with platform-specific storage
+export function initCache(options?: { kv?: any }): void {
+  cacheStorage = createCacheStorage(options);
+}
+
+// Cache function wrapper (like React cache)
+export function cacheFunction<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  options: CacheOptions = {}
+): T {
+  const { ttl = 60, staleWhileRevalidate = 0, tags = [] } = options;
+  
+  return (async (...args: any[]) => {
+    const key = options.key || `fn:${fn.name}:${JSON.stringify(args)}`;
+    
+    // Try cache first
+    const cached = await cacheStorage.get(key);
+    if (cached) {
+      // Check if stale and needs revalidation
+      if (cached.expires < Date.now() && cached.stale && cached.stale > Date.now()) {
+        // Return stale data, revalidate in background
+        queueMicrotask(async () => {
+          try {
+            const fresh = await fn(...args);
+            await cacheStorage.set(key, {
+              value: fresh,
+              expires: Date.now() + ttl * 1000,
+              stale: Date.now() + (ttl + staleWhileRevalidate) * 1000,
+              tags
+            });
+          } catch (e) {
+            console.error('Background revalidation failed:', e);
+          }
+        });
+      }
+      return cached.value;
+    }
+    
+    // Execute function
+    const result = await fn(...args);
+    
+    // Cache result
+    await cacheStorage.set(key, {
+      value: result,
+      expires: Date.now() + ttl * 1000,
+      stale: staleWhileRevalidate ? Date.now() + (ttl + staleWhileRevalidate) * 1000 : undefined,
+      tags
+    });
+    
+    return result;
+  }) as T;
+}
+
+// Unstable cache (Next.js compatible API)
+export function unstable_cache<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  keyParts?: string[],
+  options?: { revalidate?: number | false; tags?: string[] }
+): T {
+  return cacheFunction(fn, {
+    key: keyParts?.join(':'),
+    ttl: typeof options?.revalidate === 'number' ? options.revalidate : 3600,
+    tags: options?.tags
+  });
+}
+
+// Revalidate by tag
+export async function revalidateTag(tag: string): Promise<void> {
+  await cacheStorage.deleteByTag(tag);
+}
+
+// Revalidate by path
+export async function revalidatePath(path: string): Promise<void> {
+  await cacheStorage.delete(`page:${path}`);
+}
+
+// Cache object for direct access
+export const cache = {
+  get: <T>(key: string) => cacheStorage.get<T>(key),
+  set: <T>(key: string, value: T, options: CacheOptions = {}) => {
+    const { ttl = 60, staleWhileRevalidate = 0, tags = [] } = options;
+    return cacheStorage.set(key, {
+      value,
+      expires: Date.now() + ttl * 1000,
+      stale: staleWhileRevalidate ? Date.now() + (ttl + staleWhileRevalidate) * 1000 : undefined,
+      tags
+    });
+  },
+  delete: (key: string) => cacheStorage.delete(key),
+  deleteByTag: (tag: string) => cacheStorage.deleteByTag(tag),
+  clear: () => cacheStorage.clear(),
+  
+  // Wrap function with caching
+  wrap: cacheFunction,
+  
+  // Next.js compatible
+  unstable_cache,
+  revalidateTag,
+  revalidatePath
+};
+
+// Request-level cache (per-request deduplication)
+const requestCache = new WeakMap<Request, Map<string, any>>();
+
+export function getRequestCache(request: Request): Map<string, any> {
+  if (!requestCache.has(request)) {
+    requestCache.set(request, new Map());
+  }
+  return requestCache.get(request)!;
+}
+
+// React-style cache for request deduplication
+export function reactCache<T extends (...args: any[]) => any>(fn: T): T {
+  const cache = new Map<string, any>();
+  
+  return ((...args: any[]) => {
+    const key = JSON.stringify(args);
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  }) as T;
+}
+
+export default cache;