@zap-js/client 0.0.2 → 0.0.5

package/dist/runtime/logger.js

@@ -0,0 +1,164 @@
+/**
+ * Structured JSON Logger for ZapJS
+ *
+ * Provides consistent JSON logging with request context.
+ * Used across the TypeScript runtime for observability.
+ */
+const LEVEL_PRIORITY = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+};
+class Logger {
+    constructor() {
+        this.jsonFormat = process.env.ZAP_JSON_LOGS === 'true';
+        this.minLevel = process.env.ZAP_LOG_LEVEL || 'info';
+    }
+    shouldLog(level) {
+        return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[this.minLevel];
+    }
+    formatEntry(entry) {
+        if (this.jsonFormat) {
+            return JSON.stringify(entry);
+        }
+        // Human-readable format for development
+        const ctx = entry.context;
+        const timestamp = entry.timestamp.split('T')[1].split('.')[0]; // HH:MM:SS
+        const level = entry.level.toUpperCase().padEnd(5);
+        const requestIdStr = ctx?.request_id ? `[${ctx.request_id.slice(0, 8)}]` : '';
+        const contextParts = [];
+        if (ctx) {
+            if (ctx.method)
+                contextParts.push(`${ctx.method}`);
+            if (ctx.path)
+                contextParts.push(`${ctx.path}`);
+            if (ctx.handler_id)
+                contextParts.push(`handler=${ctx.handler_id}`);
+            if (ctx.duration_ms !== undefined)
+                contextParts.push(`${ctx.duration_ms.toFixed(2)}ms`);
+            if (ctx.status)
+                contextParts.push(`status=${ctx.status}`);
+        }
+        const contextStr = contextParts.length > 0 ? ` ${contextParts.join(' ')}` : '';
+        let result = `${timestamp} ${level} ${requestIdStr} ${entry.message}${contextStr}`;
+        if (entry.error) {
+            result += `\n  Error: ${entry.error.name}: ${entry.error.message}`;
+            if (entry.error.stack && process.env.NODE_ENV !== 'production') {
+                result += `\n${entry.error.stack}`;
+            }
+        }
+        return result.trim();
+    }
+    log(level, message, context, error) {
+        if (!this.shouldLog(level))
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            context,
+        };
+        if (error) {
+            entry.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        const output = this.formatEntry(entry);
+        if (level === 'error') {
+            console.error(output);
+        }
+        else if (level === 'warn') {
+            console.warn(output);
+        }
+        else {
+            console.log(output);
+        }
+    }
+    trace(message, context) {
+        this.log('trace', message, context);
+    }
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    error(message, context, error) {
+        this.log('error', message, context, error);
+    }
+    /**
+     * Create a child logger with pre-set context
+     */
+    child(baseContext) {
+        return new ChildLogger(this, baseContext);
+    }
+    /**
+     * Set JSON format mode
+     */
+    setJsonFormat(enabled) {
+        this.jsonFormat = enabled;
+    }
+    /**
+     * Set minimum log level
+     */
+    setMinLevel(level) {
+        this.minLevel = level;
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return {
+            jsonFormat: this.jsonFormat,
+            minLevel: this.minLevel,
+        };
+    }
+}
+/**
+ * Child logger with inherited base context
+ */
+class ChildLogger {
+    constructor(parent, baseContext) {
+        this.parent = parent;
+        this.baseContext = baseContext;
+    }
+    mergeContext(context) {
+        return { ...this.baseContext, ...context };
+    }
+    trace(message, context) {
+        this.parent.trace(message, this.mergeContext(context));
+    }
+    debug(message, context) {
+        this.parent.debug(message, this.mergeContext(context));
+    }
+    info(message, context) {
+        this.parent.info(message, this.mergeContext(context));
+    }
+    warn(message, context) {
+        this.parent.warn(message, this.mergeContext(context));
+    }
+    error(message, context, error) {
+        this.parent.error(message, this.mergeContext(context), error);
+    }
+    /**
+     * Create a further nested child logger
+     */
+    child(additionalContext) {
+        return new ChildLogger(this.parent, {
+            ...this.baseContext,
+            ...additionalContext,
+        });
+    }
+}
+/**
+ * Global logger instance
+ */
+export const logger = new Logger();
+export { Logger, ChildLogger };

package/dist/runtime/middleware.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Route-level middleware for ZapJS
+ *
+ * Middleware can:
+ * - Protect routes (authentication/authorization)
+ * - Transform data before rendering
+ * - Handle redirects
+ * - Log/monitor route access
+ */
+import type { RouteMatch } from './router.js';
+export interface MiddlewareContext {
+    /** Current route match */
+    match: RouteMatch;
+    /** URL pathname */
+    pathname: string;
+    /** Search params */
+    search: string;
+    /** Hash */
+    hash: string;
+    /** Navigation state */
+    state?: unknown;
+}
+export interface MiddlewareResult {
+    /** Continue to route */
+    type: 'continue' | 'redirect' | 'block';
+    /** Redirect path if type is 'redirect' */
+    redirectTo?: string;
+    /** Error to throw if type is 'block' */
+    error?: Error;
+    /** Data to pass to route */
+    data?: Record<string, any>;
+}
+export type MiddlewareFunction = (context: MiddlewareContext) => Promise<MiddlewareResult> | MiddlewareResult;
+export interface RouteMiddleware {
+    /** Middleware name for debugging */
+    name?: string;
+    /** Middleware function */
+    handler: MiddlewareFunction;
+}
+/**
+ * Compose multiple middleware functions into one
+ */
+export declare function composeMiddleware(middlewares: RouteMiddleware[]): MiddlewareFunction;
+/**
+ * Common middleware factories
+ */
+/**
+ * Authentication middleware
+ */
+export declare function requireAuth(checkAuth: () => boolean | Promise<boolean>, loginPath?: string): RouteMiddleware;
+/**
+ * Role-based access control
+ */
+export declare function requireRole(roles: string[], getUserRoles: () => string[] | Promise<string[]>, forbiddenPath?: string): RouteMiddleware;
+/**
+ * Logging middleware
+ */
+export declare function routeLogger(log: (info: {
+    pathname: string;
+    params: Record<string, string>;
+    timestamp: number;
+}) => void): RouteMiddleware;
+/**
+ * Data preloading middleware
+ */
+export declare function preloadData<T>(loader: (params: Record<string, string>) => Promise<T>, key?: string): RouteMiddleware;

package/dist/runtime/middleware.js

@@ -0,0 +1,114 @@
+/**
+ * Route-level middleware for ZapJS
+ *
+ * Middleware can:
+ * - Protect routes (authentication/authorization)
+ * - Transform data before rendering
+ * - Handle redirects
+ * - Log/monitor route access
+ */
+/**
+ * Compose multiple middleware functions into one
+ */
+export function composeMiddleware(middlewares) {
+    return async (context) => {
+        for (const middleware of middlewares) {
+            try {
+                const result = await middleware.handler(context);
+                if (result.type !== 'continue') {
+                    return result;
+                }
+                // Pass data to next middleware
+                if (result.data) {
+                    const existingState = typeof context.state === 'object' && context.state !== null ? context.state : {};
+                    context = { ...context, state: { ...existingState, ...result.data } };
+                }
+            }
+            catch (error) {
+                console.error(`Middleware ${middleware.name || 'unknown'} error:`, error);
+                return {
+                    type: 'block',
+                    error: error instanceof Error ? error : new Error('Middleware error'),
+                };
+            }
+        }
+        return { type: 'continue' };
+    };
+}
+/**
+ * Common middleware factories
+ */
+/**
+ * Authentication middleware
+ */
+export function requireAuth(checkAuth, loginPath = '/login') {
+    return {
+        name: 'requireAuth',
+        handler: async (context) => {
+            const isAuthenticated = await checkAuth();
+            if (!isAuthenticated) {
+                return {
+                    type: 'redirect',
+                    redirectTo: `${loginPath}?redirect=${encodeURIComponent(context.pathname)}`,
+                };
+            }
+            return { type: 'continue' };
+        },
+    };
+}
+/**
+ * Role-based access control
+ */
+export function requireRole(roles, getUserRoles, forbiddenPath = '/403') {
+    return {
+        name: 'requireRole',
+        handler: async (context) => {
+            const userRoles = await getUserRoles();
+            const hasRole = roles.some(role => userRoles.includes(role));
+            if (!hasRole) {
+                return {
+                    type: 'redirect',
+                    redirectTo: forbiddenPath,
+                };
+            }
+            return { type: 'continue' };
+        },
+    };
+}
+/**
+ * Logging middleware
+ */
+export function routeLogger(log) {
+    return {
+        name: 'routeLogger',
+        handler: (context) => {
+            log({
+                pathname: context.pathname,
+                params: context.match.params,
+                timestamp: Date.now(),
+            });
+            return { type: 'continue' };
+        },
+    };
+}
+/**
+ * Data preloading middleware
+ */
+export function preloadData(loader, key = 'preloadedData') {
+    return {
+        name: 'preloadData',
+        handler: async (context) => {
+            try {
+                const data = await loader(context.match.params);
+                return {
+                    type: 'continue',
+                    data: { [key]: data },
+                };
+            }
+            catch (error) {
+                console.error('Data preload failed:', error);
+                return { type: 'continue' };
+            }
+        },
+    };
+}

package/dist/runtime/process-manager.d.ts

@@ -0,0 +1,51 @@
+import type { ZapConfig } from "./types.js";
+export type { ZapConfig, RouteConfig, MiddlewareConfig, StaticFileConfig, StaticFileOptions, } from "./types.js";
+/**
+ * ProcessManager
+ *
+ * Manages the lifecycle of the Rust binary process:
+ * - Spawning the process with proper configuration
+ * - Forwarding logs to console
+ * - Monitoring for crashes
+ * - Graceful shutdown with timeout
+ * - Health check polling
+ */
+export declare class ProcessManager {
+    private process;
+    private configPath;
+    private binaryPath;
+    private socketPath;
+    constructor(binaryPath?: string, socketPath?: string);
+    /**
+     * Find the Zap binary in common locations
+     */
+    private getDefaultBinaryPath;
+    /**
+     * Check if a binary file exists and is executable
+     */
+    private binaryExists;
+    /**
+     * Start the Rust server process
+     */
+    start(config: ZapConfig, logLevel?: string): Promise<void>;
+    /**
+     * Poll the health check endpoint until the server is ready
+     */
+    private waitForHealthy;
+    /**
+     * Stop the server process immediately
+     */
+    stop(): Promise<void>;
+    /**
+     * Restart the server
+     */
+    restart(config: ZapConfig, logLevel?: string): Promise<void>;
+    /**
+     * Get the IPC socket path
+     */
+    getSocketPath(): string;
+    /**
+     * Check if the process is still running
+     */
+    isRunning(): boolean;
+}

package/dist/runtime/process-manager.js

@@ -0,0 +1,207 @@
+import { spawn, execSync } from "child_process";
+import { writeFileSync, unlinkSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+/**
+ * ProcessManager
+ *
+ * Manages the lifecycle of the Rust binary process:
+ * - Spawning the process with proper configuration
+ * - Forwarding logs to console
+ * - Monitoring for crashes
+ * - Graceful shutdown with timeout
+ * - Health check polling
+ */
+export class ProcessManager {
+    constructor(binaryPath, socketPath) {
+        this.process = null;
+        this.configPath = null;
+        this.binaryPath = binaryPath || this.getDefaultBinaryPath();
+        this.socketPath = socketPath || join(tmpdir(), `zap-${Date.now()}.sock`);
+    }
+    /**
+     * Find the Zap binary in common locations
+     */
+    getDefaultBinaryPath() {
+        // Try multiple locations
+        const arch = process.arch === "arm64" ? "aarch64-apple-darwin" : `${process.arch}-${process.platform}`;
+        const candidates = [
+            // Project local bin directory
+            join(process.cwd(), "bin/zap"),
+            // Installed package location (when @zap-js/client is a dependency)
+            join(__dirname, "../../bin/zap"),
+            // node_modules location
+            join(process.cwd(), "node_modules/@zap-js/client/bin/zap"),
+            // Legacy locations
+            join(__dirname, `../target/${arch}/release/zap`),
+            join(__dirname, "../target/release/zap"),
+            join(__dirname, "../server/target/release/zap"),
+            join(process.cwd(), "target/release/zap"),
+            join(process.cwd(), `target/${arch}/release/zap`),
+            "zap", // System PATH
+        ];
+        for (const candidate of candidates) {
+            if (this.binaryExists(candidate)) {
+                return candidate;
+            }
+        }
+        throw new Error("Zap binary not found. Build with: npm run build:rust or cargo build --release --bin zap");
+    }
+    /**
+     * Check if a binary file exists and is executable
+     */
+    binaryExists(path) {
+        if (!existsSync(path)) {
+            return false;
+        }
+        // For system PATH, just check existence
+        if (!path.includes("/")) {
+            return true;
+        }
+        // For local paths, more thorough check
+        try {
+            execSync(`test -x "${path}"`, { stdio: "ignore" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Start the Rust server process
+     */
+    async start(config, logLevel = "info") {
+        try {
+            // Write configuration to temporary JSON file
+            this.configPath = join(tmpdir(), `zap-config-${Date.now()}.json`);
+            writeFileSync(this.configPath, JSON.stringify(config, null, 2));
+            console.log(`[Zap] Starting server on ${config.hostname}:${config.port}`);
+            console.log(`[Zap] IPC socket: ${this.socketPath}`);
+            // Spawn the Rust binary
+            this.process = spawn(this.binaryPath, [
+                "--config",
+                this.configPath,
+                "--socket",
+                this.socketPath,
+                "--log-level",
+                logLevel,
+            ], {
+                stdio: ["ignore", "pipe", "pipe"],
+                env: {
+                    ...process.env,
+                    RUST_LOG: logLevel,
+                },
+            });
+            if (!this.process.stdout || !this.process.stderr) {
+                throw new Error("Failed to create process streams");
+            }
+            // Forward stdout
+            this.process.stdout.on("data", (data) => {
+                const output = data.toString().trim();
+                if (output) {
+                    console.log(`[Zap] ${output}`);
+                }
+            });
+            // Forward stderr
+            this.process.stderr.on("data", (data) => {
+                const output = data.toString().trim();
+                if (output) {
+                    console.error(`[Zap] ${output}`);
+                }
+            });
+            // Handle process exit
+            this.process.on("exit", (code, signal) => {
+                if (code !== 0 || signal) {
+                    console.error(`[Zap] Process exited: code=${code ?? 'null'}, signal=${signal ?? 'null'}`);
+                }
+            });
+            // Handle process errors
+            this.process.on("error", (err) => {
+                console.error(`[Zap] Process error:`, err);
+            });
+            console.log(`[Zap] Server started on http://${config.hostname}:${config.port}`);
+        }
+        catch (error) {
+            // Clean up on error
+            await this.stop();
+            throw error;
+        }
+    }
+    /**
+     * Poll the health check endpoint until the server is ready
+     */
+    async waitForHealthy(hostname, port, healthPath, maxAttempts = 50, delayMs = 100) {
+        for (let i = 0; i < maxAttempts; i++) {
+            try {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 1000);
+                const response = await fetch(`http://${hostname}:${port}${healthPath}`, {
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                if (response.ok) {
+                    return;
+                }
+            }
+            catch {
+                // Server not ready yet, continue polling
+            }
+            // Wait before retrying
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+        throw new Error(`Server failed to start within ${maxAttempts * delayMs}ms`);
+    }
+    /**
+     * Stop the server process immediately
+     */
+    async stop() {
+        if (!this.process) {
+            // Clean up config file if it exists
+            if (this.configPath && existsSync(this.configPath)) {
+                try {
+                    unlinkSync(this.configPath);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+            return;
+        }
+        // Kill immediately
+        if (!this.process.killed) {
+            this.process.kill("SIGKILL");
+        }
+        this.process = null;
+        // Clean up config file
+        if (this.configPath && existsSync(this.configPath)) {
+            try {
+                unlinkSync(this.configPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+    /**
+     * Restart the server
+     */
+    async restart(config, logLevel = "info") {
+        console.log("[Zap] Restarting server...");
+        await this.stop();
+        // Small delay to ensure clean shutdown
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        await this.start(config, logLevel);
+    }
+    /**
+     * Get the IPC socket path
+     */
+    getSocketPath() {
+        return this.socketPath;
+    }
+    /**
+     * Check if the process is still running
+     */
+    isRunning() {
+        return this.process !== null && !this.process.killed;
+    }
+}

package/dist/runtime/router-simple.d.ts

@@ -0,0 +1,98 @@
+/**
+ * ZapJS Production Router with Nested Layouts
+ *
+ * Features:
+ * - Nested layout support
+ * - Route-level code splitting
+ * - Error boundaries per route
+ * - Suspense boundaries
+ * - Type-safe navigation
+ */
+import React, { type ReactNode, type ComponentType } from 'react';
+export interface LayoutDefinition {
+    path: string;
+    component: React.LazyExoticComponent<ComponentType<any>>;
+    parentLayout?: string;
+}
+export interface RouteDefinition {
+    path: string;
+    pattern: RegExp;
+    paramNames: string[];
+    component: React.LazyExoticComponent<ComponentType<any>>;
+    layoutPath?: string;
+    errorComponent?: React.LazyExoticComponent<ComponentType<any>>;
+    pendingComponent?: React.LazyExoticComponent<ComponentType<any>>;
+    meta?: () => Promise<RouteMeta>;
+}
+export interface RouteMeta {
+    title?: string;
+    description?: string;
+    keywords?: string[];
+    [key: string]: any;
+}
+export interface RouteMatch {
+    route: RouteDefinition;
+    params: Record<string, string>;
+    pathname: string;
+}
+export interface RouterState {
+    pathname: string;
+    search: string;
+    hash: string;
+    match: RouteMatch | null;
+}
+export interface NavigateOptions {
+    replace?: boolean;
+    scroll?: boolean;
+    state?: unknown;
+}
+export interface Router {
+    push(path: string, options?: NavigateOptions): void;
+    replace(path: string, options?: NavigateOptions): void;
+    back(): void;
+    forward(): void;
+    refresh(): void;
+    prefetch(path: string): void;
+}
+interface RouterProviderProps {
+    routes: RouteDefinition[];
+    layouts?: LayoutDefinition[];
+    children: ReactNode;
+    notFound?: ComponentType;
+    fallback?: ReactNode;
+}
+export declare function RouterProvider({ routes, layouts, children, notFound: NotFound, fallback, }: RouterProviderProps): JSX.Element;
+export declare function useRouter(): Router;
+export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+export declare function usePathname(): string;
+export declare function useSearchParams(): [URLSearchParams, (params: Record<string, string>) => void];
+export declare function useRouteMatch(): RouteMatch | null;
+export declare function useIsPending(): boolean;
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+    to: string;
+    replace?: boolean;
+    prefetch?: boolean;
+    scroll?: boolean;
+    children: ReactNode;
+}
+export declare function Link({ to, replace, prefetch, scroll, children, onClick, onMouseEnter, ...props }: LinkProps): JSX.Element;
+interface OutletProps {
+    notFound?: ComponentType;
+    fallback?: ReactNode;
+}
+export declare function Outlet({ notFound: NotFound, fallback }: OutletProps): JSX.Element | null;
+interface NavLinkProps extends LinkProps {
+    activeClassName?: string;
+    activeStyle?: React.CSSProperties;
+    exact?: boolean;
+    pending?: boolean;
+    pendingClassName?: string;
+    pendingStyle?: React.CSSProperties;
+}
+export declare function NavLink({ to, activeClassName, activeStyle, exact, pending, pendingClassName, pendingStyle, className, style, ...props }: NavLinkProps): JSX.Element;
+interface RedirectProps {
+    to: string;
+    replace?: boolean;
+}
+export declare function Redirect({ to, replace }: RedirectProps): null;
+export {};