@zap-js/client 0.0.2 → 0.0.4

package/dist/runtime/index.js

@@ -0,0 +1,449 @@
+import { join } from "path";
+import { tmpdir } from "os";
+import { existsSync, readFileSync } from "fs";
+import { ProcessManager } from "./process-manager.js";
+import { IpcServer } from "./ipc-client.js";
+// Re-export type guards
+export { isInvokeHandlerMessage, isHandlerResponseMessage, isErrorMessage, isHealthCheckMessage, isHealthCheckResponseMessage, isRpcResponseMessage, isRpcErrorMessage, isAsyncIterable, } from "./types.js";
+// Re-export internal modules for dev-server usage
+export { ProcessManager } from "./process-manager.js";
+export { IpcServer, IpcClient } from "./ipc-client.js";
+// Re-export error boundary components and hooks (Phase 10.3)
+export { ErrorBoundary, DefaultErrorComponent, RouteErrorContext, createRouteError, ZapError, } from "./error-boundary.js";
+export { useRouteError, useIsErrorState, useErrorState, } from "./hooks.js";
+// Re-export logger (Phase 10.2)
+export { Logger, logger } from "./logger.js";
+// Re-export client router
+export { 
+// Provider
+RouterProvider, 
+// Hooks
+useRouter, useParams, usePathname, useSearchParams, useRouteMatch, useIsPending, 
+// Components
+Link, NavLink, Outlet, Redirect, } from "./router.js";
+// Re-export CSRF protection utilities
+export { getCsrfToken, useCsrfToken, createCsrfFetch, CsrfTokenInput, CsrfForm, addCsrfToFormData, getCsrfHeaders, } from "./csrf.js";
+// Re-export RPC client utilities
+export { rpcCall, } from "./rpc-client.js";
+/**
+ * Zap - Ultra-fast HTTP server for Node.js and Bun
+ *
+ * This is the main API entry point. It manages:
+ * 1. Route registration from TypeScript
+ * 2. Spawning and managing the Rust binary process
+ * 3. IPC communication between TypeScript handlers and Rust server
+ *
+ * Usage:
+ * ```
+ * const app = new Zap({ port: 3000 });
+ * app.get('/', () => ({ message: 'Hello!' }));
+ * app.post('/api/data', (req) => ({ received: req.body }));
+ * await app.listen();
+ * ```
+ */
+export class Zap {
+    constructor(options) {
+        this.handlers = new Map();
+        this.routes = [];
+        this.staticFiles = [];
+        this.port = 3000;
+        this.hostname = "127.0.0.1";
+        this.logLevel = "info";
+        this.healthCheckPath = "/health";
+        this.metricsPath = null;
+        this.enableCors = false;
+        this.enableLogging = false;
+        this.enableCompression = false;
+        this.fileRoutingEnabled = false;
+        this.fileRoutingConfig = {};
+        // Parse options
+        if (options?.port)
+            this.port = options.port;
+        if (options?.hostname)
+            this.hostname = options.hostname;
+        if (options?.logLevel)
+            this.logLevel = options.logLevel;
+        // Create IPC socket path (unique per instance)
+        const socketPath = join(tmpdir(), `zap-${Date.now()}-${Math.random().toString(36).substring(7)}.sock`);
+        // Initialize managers
+        this.processManager = new ProcessManager(undefined, socketPath);
+        this.ipcServer = new IpcServer(socketPath);
+    }
+    // ============================================================================
+    // Fluent Configuration API
+    // ============================================================================
+    /**
+     * Set the server port
+     */
+    setPort(port) {
+        this.port = port;
+        return this;
+    }
+    /**
+     * Set the server hostname
+     */
+    setHostname(hostname) {
+        this.hostname = hostname;
+        return this;
+    }
+    /**
+     * Enable CORS middleware
+     */
+    cors() {
+        this.enableCors = true;
+        return this;
+    }
+    /**
+     * Enable request logging middleware
+     */
+    logging() {
+        this.enableLogging = true;
+        return this;
+    }
+    /**
+     * Enable response compression middleware
+     */
+    compression() {
+        this.enableCompression = true;
+        return this;
+    }
+    /**
+     * Set custom health check path
+     */
+    healthCheck(path) {
+        this.healthCheckPath = path;
+        return this;
+    }
+    /**
+     * Set metrics endpoint path
+     */
+    metrics(path) {
+        this.metricsPath = path;
+        return this;
+    }
+    /**
+     * Enable file-based routing (TanStack style)
+     *
+     * Automatically registers routes from the routes/ directory
+     * using the generated route manifest from @zapjs/router
+     */
+    useFileRouting(config) {
+        this.fileRoutingEnabled = true;
+        this.fileRoutingConfig = config || {};
+        return this;
+    }
+    // ============================================================================
+    // Route Registration API
+    // ============================================================================
+    /**
+     * Register a GET route
+     */
+    get(path, handler) {
+        return this.registerRoute("GET", path, handler);
+    }
+    /**
+     * Register a POST route
+     */
+    post(path, handler) {
+        return this.registerRoute("POST", path, handler);
+    }
+    /**
+     * Register a PUT route
+     */
+    put(path, handler) {
+        return this.registerRoute("PUT", path, handler);
+    }
+    /**
+     * Register a DELETE route
+     */
+    delete(path, handler) {
+        return this.registerRoute("DELETE", path, handler);
+    }
+    /**
+     * Register a PATCH route
+     */
+    patch(path, handler) {
+        return this.registerRoute("PATCH", path, handler);
+    }
+    /**
+     * Register a HEAD route
+     */
+    head(path, handler) {
+        return this.registerRoute("HEAD", path, handler);
+    }
+    /**
+     * Convenience method for GET routes that return JSON
+     */
+    getJson(path, handler) {
+        return this.get(path, handler);
+    }
+    /**
+     * Convenience method for POST routes that return JSON
+     */
+    postJson(path, handler) {
+        return this.post(path, handler);
+    }
+    /**
+     * Register static file serving
+     */
+    static(prefix, directory) {
+        this.staticFiles.push({ prefix, directory });
+        return this;
+    }
+    /**
+     * Register a route with a handler (internal)
+     */
+    registerRoute(method, path, handler) {
+        const handlerId = `handler_${this.handlers.size}`;
+        this.handlers.set(handlerId, handler);
+        this.routes.push({
+            method,
+            path,
+            handler_id: handlerId,
+            is_typescript: true,
+        });
+        return this;
+    }
+    // ============================================================================
+    // Server Lifecycle
+    // ============================================================================
+    /**
+     * Start the server
+     */
+    async listen(port) {
+        // Allow overriding port in listen()
+        if (port !== undefined) {
+            this.port = port;
+        }
+        try {
+            // Load file-based routes if enabled
+            if (this.fileRoutingEnabled) {
+                await this.loadFileRoutes();
+            }
+            // Start IPC server first
+            console.log("[Zap] Starting IPC server...");
+            await this.ipcServer.start();
+            // Register all handlers with IPC server
+            console.log(`[Zap] Registering ${this.handlers.size} handlers...`);
+            for (const [handlerId, handler] of this.handlers) {
+                this.ipcServer.registerHandler(handlerId, async (req) => {
+                    const result = await handler(req);
+                    // Handle different response types
+                    if (result instanceof Response) {
+                        // Convert Headers to Record<string, string>
+                        const headersObj = {};
+                        result.headers.forEach((value, key) => {
+                            headersObj[key] = value;
+                        });
+                        return {
+                            status: result.status,
+                            headers: headersObj,
+                            body: await result.text(),
+                        };
+                    }
+                    if (typeof result === "string") {
+                        return {
+                            status: 200,
+                            headers: { "content-type": "text/plain" },
+                            body: result,
+                        };
+                    }
+                    // Default to JSON
+                    return {
+                        status: 200,
+                        headers: { "content-type": "application/json" },
+                        body: JSON.stringify(result),
+                    };
+                });
+            }
+            // Build Rust configuration
+            const config = {
+                port: this.port,
+                hostname: this.hostname,
+                ipc_socket_path: this.processManager.getSocketPath(),
+                routes: this.routes,
+                static_files: this.staticFiles,
+                middleware: {
+                    enable_cors: this.enableCors,
+                    enable_logging: this.enableLogging,
+                    enable_compression: this.enableCompression,
+                },
+                health_check_path: this.healthCheckPath,
+                metrics_path: this.metricsPath ?? undefined,
+            };
+            // Start Rust server process
+            console.log("[Zap] Starting Rust server process...");
+            await this.processManager.start(config, this.logLevel);
+            console.log(`[Zap] Server listening on http://${this.hostname}:${this.port}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error("[Zap] Failed to start server:", message);
+            await this.close();
+            throw error;
+        }
+    }
+    /**
+     * Close the server gracefully
+     */
+    async close() {
+        console.log("[Zap] Closing server...");
+        try {
+            await this.processManager.stop();
+            await this.ipcServer.stop();
+            console.log("[Zap] Server closed");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error("[Zap] Error closing server:", message);
+            throw error;
+        }
+    }
+    /**
+     * Check if server is running
+     */
+    isRunning() {
+        return this.processManager.isRunning();
+    }
+    /**
+     * Load routes from generated route manifest
+     */
+    async loadFileRoutes() {
+        const generatedDir = this.fileRoutingConfig.generatedDir || join(process.cwd(), 'src', 'generated');
+        const manifestPath = join(generatedDir, 'routeManifest.json');
+        if (!existsSync(manifestPath)) {
+            console.log("[Zap] No route manifest found. Run route scanner first.");
+            return;
+        }
+        try {
+            const manifestContent = readFileSync(manifestPath, 'utf-8');
+            const manifest = JSON.parse(manifestContent);
+            console.log(`[Zap] Loading ${manifest.apiRoutes?.length ?? 0} API routes from manifest...`);
+            // Register API routes
+            for (const route of manifest.apiRoutes ?? []) {
+                // Convert :param to Rust radix router format
+                const rustPath = route.urlPath;
+                // Import the route handler module
+                const routeFile = join(process.cwd(), 'routes', route.filePath);
+                if (existsSync(routeFile.replace(/\.ts$/, '.js')) || existsSync(routeFile)) {
+                    try {
+                        const routeModule = await import(routeFile);
+                        // Register each HTTP method handler
+                        const methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
+                        for (const method of methods) {
+                            const methodHandler = routeModule[method];
+                            if (methodHandler) {
+                                this.registerRoute(method, rustPath, methodHandler);
+                                console.log(`[Zap]   ${method} ${rustPath}`);
+                            }
+                        }
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.log(`[Zap] Failed to import ${routeFile}: ${message}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error("[Zap] Failed to load route manifest:", message);
+        }
+    }
+}
+// ============================================================================
+// Namespace Exports (Clean API)
+// ============================================================================
+/**
+ * Router namespace - all routing functionality
+ * Usage: import { router } from '@zap-js/client'
+ */
+import { RouterProvider, useRouter as useRouterFn, useParams as useParamsFn, usePathname as usePathnameFn, useSearchParams as useSearchParamsFn, useRouteMatch as useRouteMatchFn, useIsPending as useIsPendingFn, Link, NavLink, Outlet, Redirect, } from "./router.js";
+export const router = {
+    RouterProvider,
+    useRouter: useRouterFn,
+    useParams: useParamsFn,
+    usePathname: usePathnameFn,
+    useSearchParams: useSearchParamsFn,
+    useRouteMatch: useRouteMatchFn,
+    useIsPending: useIsPendingFn,
+    Link,
+    NavLink,
+    Outlet,
+    Redirect,
+};
+/**
+ * Errors namespace - error handling and boundaries
+ * Usage: import { errors } from '@zap-js/client'
+ */
+import { ErrorBoundary, DefaultErrorComponent, createRouteError, ZapError, } from "./error-boundary.js";
+import { useRouteError, useIsErrorState, useErrorState, } from "./hooks.js";
+export const errors = {
+    ErrorBoundary,
+    DefaultErrorComponent,
+    createRouteError,
+    ZapError,
+    useRouteError,
+    useIsErrorState,
+    useErrorState,
+};
+/**
+ * Middleware namespace - route middleware utilities
+ * Usage: import { middleware } from '@zap-js/client'
+ */
+import { composeMiddleware, requireAuth, requireRole, routeLogger, preloadData, } from "./middleware.js";
+export const middleware = {
+    compose: composeMiddleware,
+    requireAuth,
+    requireRole,
+    logger: routeLogger,
+    preloadData,
+};
+/**
+ * Types namespace - type definitions and guards
+ * Usage: import { types } from '@zap-js/client'
+ */
+import * as TypeGuards from "./types.js";
+export const types = {
+    isInvokeHandlerMessage: TypeGuards.isInvokeHandlerMessage,
+    isHandlerResponseMessage: TypeGuards.isHandlerResponseMessage,
+    isErrorMessage: TypeGuards.isErrorMessage,
+    isHealthCheckMessage: TypeGuards.isHealthCheckMessage,
+    isHealthCheckResponseMessage: TypeGuards.isHealthCheckResponseMessage,
+    isRpcResponseMessage: TypeGuards.isRpcResponseMessage,
+    isRpcErrorMessage: TypeGuards.isRpcErrorMessage,
+    isAsyncIterable: TypeGuards.isAsyncIterable,
+};
+/**
+ * WebSockets namespace - WebSocket utilities and helpers
+ * Usage: import { websockets } from '@zap-js/client'
+ */
+import * as WebSocketUtils from "./websockets-utils.js";
+export const websockets = {
+    isWsMessage: WebSocketUtils.isWsMessage,
+    broadcast: WebSocketUtils.broadcast,
+    broadcastExcept: WebSocketUtils.broadcastExcept,
+    sendJson: WebSocketUtils.sendJson,
+    parseMessage: WebSocketUtils.parseMessage,
+    createErrorMessage: WebSocketUtils.createErrorMessage,
+    createSuccessMessage: WebSocketUtils.createSuccessMessage,
+};
+/**
+ * Streaming namespace - Streaming response utilities
+ * Usage: import { streaming } from '@zap-js/client'
+ */
+import * as StreamingUtils from "./streaming-utils.js";
+export const streaming = {
+    isAsyncIterable: StreamingUtils.isAsyncIterable,
+    createChunk: StreamingUtils.createChunk,
+    createStream: StreamingUtils.createStream,
+    streamJson: StreamingUtils.streamJson,
+    streamSSE: StreamingUtils.streamSSE,
+    mapStream: StreamingUtils.mapStream,
+    filterStream: StreamingUtils.filterStream,
+    batchStream: StreamingUtils.batchStream,
+    delayStream: StreamingUtils.delayStream,
+    fromReadableStream: StreamingUtils.fromReadableStream,
+    intervalStream: StreamingUtils.intervalStream,
+};
+export default Zap;

package/dist/runtime/ipc-client.d.ts

@@ -0,0 +1,144 @@
+import { EventEmitter } from "events";
+import type { ZapRequest, ZapHandlerResponse, IpcMessage, StreamChunk, WsHandler } from "./types.js";
+export type { ZapRequest as IpcRequest } from "./types.js";
+/**
+ * IPC encoding format
+ */
+export type IpcEncoding = "msgpack" | "json";
+/**
+ * Handler function type for IPC server (supports regular and streaming responses)
+ */
+export type HandlerFunction = (req: ZapRequest) => Promise<ZapHandlerResponse> | AsyncIterable<StreamChunk>;
+/**
+ * Streaming handler function type
+ */
+export type StreamingHandlerFunction = (req: ZapRequest) => AsyncIterable<StreamChunk>;
+/**
+ * WebSocket handler function type
+ */
+export type WsHandlerFunction = WsHandler;
+/**
+ * Serialize an IPC message to bytes
+ */
+declare function serializeMessage(msg: IpcMessage, encoding: IpcEncoding): Buffer;
+/**
+ * Deserialize an IPC message from bytes (auto-detects encoding)
+ */
+declare function deserializeMessage(data: Buffer): IpcMessage;
+/**
+ * FrameReader - reads length-prefixed frames from a socket
+ */
+declare class FrameReader {
+    private buffer;
+    private onFrame;
+    constructor(onFrame: (frame: Buffer) => void);
+    /**
+     * Process incoming data chunks
+     */
+    push(chunk: Buffer): void;
+    /**
+     * Reset the buffer
+     */
+    reset(): void;
+}
+/**
+ * IpcServer
+ *
+ * Listens on a Unix socket for IPC messages from the Rust backend.
+ * The Rust server sends handler invocation requests, which we dispatch
+ * to the registered TypeScript handlers and send responses back.
+ *
+ * Protocol: Length-prefixed MessagePack (default) with JSON fallback
+ * Frame format: [4-byte big-endian length][payload]
+ */
+export declare class IpcServer {
+    private server;
+    private socketPath;
+    private handlers;
+    private wsHandlers;
+    private wsConnections;
+    private encoding;
+    private currentSocket;
+    constructor(socketPath: string, encoding?: IpcEncoding);
+    /**
+     * Register a handler function for a specific handler ID
+     */
+    registerHandler(handlerId: string, handler: HandlerFunction): void;
+    /**
+     * Register a WebSocket handler for a specific handler ID
+     */
+    registerWsHandler(handlerId: string, handler: WsHandlerFunction): void;
+    /**
+     * Start the IPC server listening on the Unix socket
+     */
+    start(): Promise<void>;
+    /**
+     * Handle a new IPC connection from the Rust server
+     */
+    private handleConnection;
+    /**
+     * Handle a complete frame
+     */
+    private handleFrame;
+    /**
+     * Process an incoming IPC message
+     */
+    private processMessage;
+    /**
+     * Handle a streaming response from a handler
+     */
+    private handleStreamingResponse;
+    /**
+     * Send a message to a WebSocket client via the Rust server
+     */
+    sendWsMessage(connectionId: string, data: string, binary: boolean): void;
+    /**
+     * Close a WebSocket connection via the Rust server
+     */
+    closeWsConnection(connectionId: string, code?: number, reason?: string): void;
+    /**
+     * Stop the IPC server
+     */
+    stop(): Promise<void>;
+}
+/**
+ * IpcClient
+ *
+ * Connects to a Unix socket to communicate with the Rust server.
+ * Used for RPC calls from TypeScript to Rust.
+ *
+ * Protocol: Length-prefixed MessagePack (default) with JSON fallback
+ */
+export declare class IpcClient extends EventEmitter {
+    private socket;
+    private socketPath;
+    private connected;
+    private frameReader;
+    private encoding;
+    constructor(socketPath: string, encoding?: IpcEncoding);
+    /**
+     * Connect to the Unix socket
+     */
+    private connect;
+    /**
+     * Send a message to the server
+     */
+    send(message: IpcMessage): void;
+    /**
+     * Send a message and wait for response
+     */
+    sendRecv(message: IpcMessage): Promise<IpcMessage>;
+    /**
+     * Close the connection
+     */
+    close(): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Get the encoding being used
+     */
+    getEncoding(): IpcEncoding;
+}
+export { serializeMessage, deserializeMessage, FrameReader };