@flexireact/core 2.1.0 → 2.2.0

package/core/actions/index.ts

@@ -0,0 +1,364 @@
+/**
+ * FlexiReact Server Actions
+ * 
+ * Server Actions allow you to define server-side functions that can be called
+ * directly from client components. They are automatically serialized and executed
+ * on the server.
+ * 
+ * Usage:
+ * ```tsx
+ * // In a server file (actions.ts)
+ * 'use server';
+ * 
+ * export async function createUser(formData: FormData) {
+ *   const name = formData.get('name');
+ *   // Save to database...
+ *   return { success: true, id: 123 };
+ * }
+ * 
+ * // In a client component
+ * 'use client';
+ * import { createUser } from './actions';
+ * 
+ * function Form() {
+ *   return (
+ *     <form action={createUser}>
+ *       <input name="name" />
+ *       <button type="submit">Create</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+
+import { cookies, headers, redirect, notFound, RedirectError, NotFoundError } from '../helpers.js';
+
+// Global action registry
+declare global {
+  var __FLEXI_ACTIONS__: Record<string, ServerActionFunction>;
+  var __FLEXI_ACTION_CONTEXT__: ActionContext | null;
+}
+
+globalThis.__FLEXI_ACTIONS__ = globalThis.__FLEXI_ACTIONS__ || {};
+globalThis.__FLEXI_ACTION_CONTEXT__ = null;
+
+export interface ActionContext {
+  request: Request;
+  cookies: typeof cookies;
+  headers: typeof headers;
+  redirect: typeof redirect;
+  notFound: typeof notFound;
+}
+
+export type ServerActionFunction = (...args: any[]) => Promise<any>;
+
+export interface ActionResult<T = any> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  redirect?: string;
+}
+
+/**
+ * Decorator to mark a function as a server action
+ */
+export function serverAction<T extends ServerActionFunction>(
+  fn: T,
+  actionId?: string
+): T {
+  const id = actionId || `action_${fn.name}_${generateActionId()}`;
+  
+  // Register the action
+  globalThis.__FLEXI_ACTIONS__[id] = fn;
+  
+  // Create a proxy that will be serialized for the client
+  const proxy = (async (...args: any[]) => {
+    // If we're on the server, execute directly
+    if (typeof window === 'undefined') {
+      return await executeAction(id, args);
+    }
+    
+    // If we're on the client, make a fetch request
+    return await callServerAction(id, args);
+  }) as T;
+  
+  // Mark as server action
+  (proxy as any).$$typeof = Symbol.for('react.server.action');
+  (proxy as any).$$id = id;
+  (proxy as any).$$bound = null;
+  
+  return proxy;
+}
+
+/**
+ * Register a server action
+ */
+export function registerAction(id: string, fn: ServerActionFunction): void {
+  globalThis.__FLEXI_ACTIONS__[id] = fn;
+}
+
+/**
+ * Get a registered action
+ */
+export function getAction(id: string): ServerActionFunction | undefined {
+  return globalThis.__FLEXI_ACTIONS__[id];
+}
+
+/**
+ * Execute a server action on the server
+ */
+export async function executeAction(
+  actionId: string,
+  args: any[],
+  context?: Partial<ActionContext>
+): Promise<ActionResult> {
+  const action = globalThis.__FLEXI_ACTIONS__[actionId];
+  
+  if (!action) {
+    return {
+      success: false,
+      error: `Server action not found: ${actionId}`
+    };
+  }
+  
+  // Set up action context
+  const actionContext: ActionContext = {
+    request: context?.request || new Request('http://localhost'),
+    cookies,
+    headers,
+    redirect,
+    notFound
+  };
+  
+  globalThis.__FLEXI_ACTION_CONTEXT__ = actionContext;
+  
+  try {
+    const result = await action(...args);
+    
+    return {
+      success: true,
+      data: result
+    };
+  } catch (error: any) {
+    // Handle redirect
+    if (error instanceof RedirectError) {
+      return {
+        success: true,
+        redirect: error.url
+      };
+    }
+    
+    // Handle not found
+    if (error instanceof NotFoundError) {
+      return {
+        success: false,
+        error: 'Not found'
+      };
+    }
+    
+    return {
+      success: false,
+      error: error.message || 'Action failed'
+    };
+  } finally {
+    globalThis.__FLEXI_ACTION_CONTEXT__ = null;
+  }
+}
+
+/**
+ * Call a server action from the client
+ */
+export async function callServerAction(
+  actionId: string,
+  args: any[]
+): Promise<ActionResult> {
+  try {
+    const response = await fetch('/_flexi/action', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Flexi-Action': actionId
+      },
+      body: JSON.stringify({
+        actionId,
+        args: serializeArgs(args)
+      }),
+      credentials: 'same-origin'
+    });
+    
+    if (!response.ok) {
+      throw new Error(`Action failed: ${response.statusText}`);
+    }
+    
+    const result = await response.json();
+    
+    // Handle redirect
+    if (result.redirect) {
+      window.location.href = result.redirect;
+      return result;
+    }
+    
+    return result;
+  } catch (error: any) {
+    return {
+      success: false,
+      error: error.message || 'Network error'
+    };
+  }
+}
+
+/**
+ * Serialize action arguments for transmission
+ */
+function serializeArgs(args: any[]): any[] {
+  return args.map(arg => {
+    // Handle FormData
+    if (arg instanceof FormData) {
+      const obj: Record<string, any> = {};
+      arg.forEach((value, key) => {
+        if (obj[key]) {
+          // Handle multiple values
+          if (Array.isArray(obj[key])) {
+            obj[key].push(value);
+          } else {
+            obj[key] = [obj[key], value];
+          }
+        } else {
+          obj[key] = value;
+        }
+      });
+      return { $$type: 'FormData', data: obj };
+    }
+    
+    // Handle File
+    if (typeof File !== 'undefined' && arg instanceof File) {
+      return { $$type: 'File', name: arg.name, type: arg.type, size: arg.size };
+    }
+    
+    // Handle Date
+    if (arg instanceof Date) {
+      return { $$type: 'Date', value: arg.toISOString() };
+    }
+    
+    // Handle regular objects
+    if (typeof arg === 'object' && arg !== null) {
+      return JSON.parse(JSON.stringify(arg));
+    }
+    
+    return arg;
+  });
+}
+
+/**
+ * Deserialize action arguments on the server
+ */
+export function deserializeArgs(args: any[]): any[] {
+  return args.map(arg => {
+    if (arg && typeof arg === 'object') {
+      // Handle FormData
+      if (arg.$$type === 'FormData') {
+        const formData = new FormData();
+        for (const [key, value] of Object.entries(arg.data)) {
+          if (Array.isArray(value)) {
+            value.forEach(v => formData.append(key, v as string));
+          } else {
+            formData.append(key, value as string);
+          }
+        }
+        return formData;
+      }
+      
+      // Handle Date
+      if (arg.$$type === 'Date') {
+        return new Date(arg.value);
+      }
+    }
+    
+    return arg;
+  });
+}
+
+/**
+ * Generate a unique action ID
+ */
+function generateActionId(): string {
+  return Math.random().toString(36).substring(2, 10);
+}
+
+/**
+ * Hook to get the current action context
+ */
+export function useActionContext(): ActionContext | null {
+  return globalThis.__FLEXI_ACTION_CONTEXT__;
+}
+
+/**
+ * Create a form action handler
+ * Wraps a server action for use with HTML forms
+ */
+export function formAction<T>(
+  action: (formData: FormData) => Promise<T>
+): (formData: FormData) => Promise<ActionResult<T>> {
+  return async (formData: FormData) => {
+    try {
+      const result = await action(formData);
+      return { success: true, data: result };
+    } catch (error: any) {
+      if (error instanceof RedirectError) {
+        return { success: true, redirect: error.url };
+      }
+      return { success: false, error: error.message };
+    }
+  };
+}
+
+/**
+ * useFormState hook for progressive enhancement
+ * Works with server actions and provides loading/error states
+ */
+export function createFormState<T>(
+  action: (formData: FormData) => Promise<ActionResult<T>>,
+  initialState: T | null = null
+) {
+  return {
+    action,
+    initialState,
+    // This will be enhanced on the client
+    pending: false,
+    error: null as string | null,
+    data: initialState
+  };
+}
+
+/**
+ * Bind arguments to a server action
+ * Creates a new action with pre-filled arguments
+ */
+export function bindArgs<T extends ServerActionFunction>(
+  action: T,
+  ...boundArgs: any[]
+): T {
+  const boundAction = (async (...args: any[]) => {
+    return await (action as any)(...boundArgs, ...args);
+  }) as T;
+  
+  // Copy action metadata
+  (boundAction as any).$$typeof = (action as any).$$typeof;
+  (boundAction as any).$$id = (action as any).$$id;
+  (boundAction as any).$$bound = boundArgs;
+  
+  return boundAction;
+}
+
+export default {
+  serverAction,
+  registerAction,
+  getAction,
+  executeAction,
+  callServerAction,
+  deserializeArgs,
+  useActionContext,
+  formAction,
+  createFormState,
+  bindArgs
+};

package/core/index.ts

@@ -15,7 +15,7 @@ export * from './utils.js';
 export { buildRouteTree, matchRoute, findRouteLayouts, RouteType } from './router/index.js';
 
 // Render
-export { renderPage, renderError, renderLoading } from './render/index.js';
+export { renderPage, renderPageStream, streamToResponse, renderError, renderLoading } from './render/index.js';
 
 // Server
 import { createServer } from './server/index.js';
@@ -70,6 +70,20 @@ export {
   builtinPlugins 
 } from './plugins/index.js';
 
+// Server Actions
+export {
+  serverAction,
+  registerAction,
+  getAction,
+  executeAction,
+  callServerAction,
+  formAction,
+  createFormState,
+  bindArgs,
+  useActionContext
+} from './actions/index.js';
+export type { ActionContext, ActionResult, ServerActionFunction } from './actions/index.js';
+
 // Server Helpers
 export {
   // Response helpers
@@ -96,7 +110,7 @@ export {
 export type { CookieOptions } from './helpers.js';
 
 // Version
-export const VERSION = '2.1.0';
+export const VERSION = '2.2.0';
 
 // Default export
 export default {

package/core/render/index.ts

@@ -91,6 +91,164 @@ export async function renderPage(options) {
   }
 }
 
+/**
+ * Streaming SSR with React 18
+ * Renders the page progressively, sending HTML chunks as they become ready
+ */
+export async function renderPageStream(options: {
+  Component: React.ComponentType<any>;
+  props?: Record<string, any>;
+  layouts?: Array<{ Component: React.ComponentType<any>; props?: Record<string, any> }>;
+  loading?: React.ComponentType | null;
+  error?: React.ComponentType<{ error: Error }> | null;
+  title?: string;
+  meta?: Record<string, string>;
+  scripts?: Array<string | { src?: string; content?: string; type?: string }>;
+  styles?: Array<string | { content: string }>;
+  favicon?: string | null;
+  route?: string;
+  onShellReady?: () => void;
+  onAllReady?: () => void;
+  onError?: (error: Error) => void;
+}): Promise<{ stream: NodeJS.ReadableStream; shellReady: Promise<void> }> {
+  const {
+    Component,
+    props = {},
+    layouts = [],
+    loading = null,
+    error = null,
+    title = 'FlexiReact App',
+    meta = {},
+    scripts = [],
+    styles = [],
+    favicon = null,
+    route = '/',
+    onShellReady,
+    onAllReady,
+    onError
+  } = options;
+
+  const renderStart = Date.now();
+
+  // Build the component tree
+  let element: any = React.createElement(Component, props);
+
+  // Wrap with error boundary if error component exists
+  if (error) {
+    element = React.createElement(ErrorBoundaryWrapper as any, {
+      fallback: error,
+      children: element
+    });
+  }
+
+  // Wrap with Suspense if loading component exists
+  if (loading) {
+    element = React.createElement(React.Suspense as any, {
+      fallback: React.createElement(loading),
+      children: element
+    });
+  }
+
+  // Wrap with layouts
+  for (const layout of [...layouts].reverse()) {
+    if (layout.Component) {
+      element = React.createElement(layout.Component, layout.props, element);
+    }
+  }
+
+  // Create the full document wrapper
+  const DocumentWrapper = ({ children }: { children: React.ReactNode }) => {
+    return React.createElement('html', { lang: 'en', className: 'dark' },
+      React.createElement('head', null,
+        React.createElement('meta', { charSet: 'UTF-8' }),
+        React.createElement('meta', { name: 'viewport', content: 'width=device-width, initial-scale=1.0' }),
+        React.createElement('title', null, title),
+        favicon && React.createElement('link', { rel: 'icon', href: favicon }),
+        ...Object.entries(meta).map(([name, content]) => 
+          React.createElement('meta', { key: name, name, content })
+        ),
+        ...styles.map((style, i) => 
+          typeof style === 'string'
+            ? React.createElement('link', { key: i, rel: 'stylesheet', href: style })
+            : React.createElement('style', { key: i, dangerouslySetInnerHTML: { __html: style.content } })
+        )
+      ),
+      React.createElement('body', null,
+        React.createElement('div', { id: 'root' }, children),
+        ...scripts.map((script, i) => 
+          typeof script === 'string'
+            ? React.createElement('script', { key: i, src: script })
+            : script.src
+              ? React.createElement('script', { key: i, src: script.src, type: script.type })
+              : React.createElement('script', { key: i, type: script.type, dangerouslySetInnerHTML: { __html: script.content } })
+        )
+      )
+    );
+  };
+
+  const fullElement = React.createElement(DocumentWrapper, null, element);
+
+  // Create streaming render
+  let shellReadyResolve: () => void;
+  const shellReady = new Promise<void>((resolve) => {
+    shellReadyResolve = resolve;
+  });
+
+  const { pipe, abort } = renderToPipeableStream(fullElement, {
+    onShellReady() {
+      const renderTime = Date.now() - renderStart;
+      console.log(`⚡ Shell ready in ${renderTime}ms`);
+      shellReadyResolve();
+      onShellReady?.();
+    },
+    onAllReady() {
+      const renderTime = Date.now() - renderStart;
+      console.log(`✨ All content ready in ${renderTime}ms`);
+      onAllReady?.();
+    },
+    onError(err: Error) {
+      console.error('Streaming SSR Error:', err);
+      onError?.(err);
+    }
+  });
+
+  // Create a passthrough stream
+  const { PassThrough } = await import('stream');
+  const passThrough = new PassThrough();
+  
+  // Pipe the render stream to our passthrough
+  pipe(passThrough);
+
+  return {
+    stream: passThrough,
+    shellReady
+  };
+}
+
+/**
+ * Render to stream for HTTP response
+ * Use this in the server to stream HTML to the client
+ */
+export function streamToResponse(
+  res: { write: (chunk: string) => void; end: () => void },
+  stream: NodeJS.ReadableStream,
+  options: { onFinish?: () => void } = {}
+): void {
+  stream.on('data', (chunk) => {
+    res.write(chunk.toString());
+  });
+
+  stream.on('end', () => {
+    res.end();
+    options.onFinish?.();
+  });
+
+  stream.on('error', (err) => {
+    console.error('Stream error:', err);
+    res.end();
+  });
+}
+
 /**
  * Error Boundary Wrapper for SSR
  */

package/core/server/index.ts

@@ -16,6 +16,7 @@ import { getRegisteredIslands, generateAdvancedHydrationScript } from '../island
 import { createRequestContext, RequestContext, RouteContext } from '../context.js';
 import { logger } from '../logger.js';
 import { RedirectError, NotFoundError } from '../helpers.js';
+import { executeAction, deserializeArgs } from '../actions/index.js';
 import React from 'react';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -125,6 +126,11 @@ export async function createServer(options: CreateServerOptions = {}) {
         return await serveClientComponent(res, config.pagesDir, componentName);
       }
 
+      // Handle server actions
+      if (effectivePath === '/_flexi/action' && req.method === 'POST') {
+        return await handleServerAction(req, res);
+      }
+
       // Rebuild routes in dev mode for hot reload
       if (isDev) {
         routes = buildRouteTree(config.pagesDir, config.layoutsDir);
@@ -317,6 +323,49 @@ async function handleApiRoute(req, res, route, loadModule) {
   }
 }
 
+/**
+ * Handles server action requests
+ */
+async function handleServerAction(req, res) {
+  try {
+    // Parse request body
+    const body: any = await parseBody(req);
+    const { actionId, args } = body;
+
+    if (!actionId) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ success: false, error: 'Missing actionId' }));
+      return;
+    }
+
+    // Deserialize arguments
+    const deserializedArgs = deserializeArgs(args || []);
+
+    // Execute the action
+    const result = await executeAction(actionId, deserializedArgs, {
+      request: new Request(`http://${req.headers.host}${req.url}`, {
+        method: req.method,
+        headers: req.headers as any
+      })
+    });
+
+    // Send response
+    res.writeHead(200, { 
+      'Content-Type': 'application/json',
+      'X-Flexi-Action': actionId
+    });
+    res.end(JSON.stringify(result));
+
+  } catch (error: any) {
+    console.error('Server Action Error:', error);
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      success: false, 
+      error: error.message || 'Action execution failed' 
+    }));
+  }
+}
+
 /**
  * Creates an enhanced API response object
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flexireact/core",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The Modern React Framework v2 - SSR, SSG, Islands, App Router, TypeScript, Tailwind",
   "main": "core/index.ts",
   "types": "core/types.ts",