@zap-js/client 0.0.2 → 0.0.5

package/dist/runtime/streaming-utils.js

@@ -0,0 +1,150 @@
+/**
+ * Streaming utilities for ZapJS
+ * Helper functions for working with streaming responses
+ */
+import { isAsyncIterable } from './types.js';
+// Re-export type guard
+export { isAsyncIterable };
+export function createChunk(input) {
+    if (typeof input === 'string') {
+        return { data: input };
+    }
+    return { bytes: input };
+}
+/**
+ * Create a streaming response from an array of strings
+ * @param items - Array of strings to stream
+ * @param delimiter - Optional delimiter to add after each item (default: newline)
+ * @returns Async iterable of stream chunks
+ */
+export async function* createStream(items, delimiter = '\n') {
+    for (const item of items) {
+        yield createChunk(item + delimiter);
+    }
+}
+/**
+ * Create a streaming JSON response (NDJSON format)
+ * Each object is sent as a separate JSON line
+ * @param objects - Array of objects to stream
+ * @returns Async iterable of stream chunks
+ */
+export async function* streamJson(objects) {
+    for (const obj of objects) {
+        yield createChunk(JSON.stringify(obj) + '\n');
+    }
+}
+/**
+ * Stream Server-Sent Events (SSE) format
+ * @param events - Array of SSE events
+ * @returns Async iterable of stream chunks
+ */
+export async function* streamSSE(events) {
+    for (const evt of events) {
+        let message = '';
+        if (evt.event) {
+            message += `event: ${evt.event}\n`;
+        }
+        if (evt.id !== undefined) {
+            message += `id: ${evt.id}\n`;
+        }
+        if (evt.retry !== undefined) {
+            message += `retry: ${evt.retry}\n`;
+        }
+        const data = typeof evt.data === 'string' ? evt.data : JSON.stringify(evt.data);
+        message += `data: ${data}\n\n`;
+        yield createChunk(message);
+    }
+}
+/**
+ * Transform an async iterable with a mapper function
+ * @param source - Source async iterable
+ * @param mapper - Function to transform each item
+ * @returns Async iterable of transformed items
+ */
+export async function* mapStream(source, mapper) {
+    for await (const item of source) {
+        yield await mapper(item);
+    }
+}
+/**
+ * Filter an async iterable with a predicate function
+ * @param source - Source async iterable
+ * @param predicate - Function to test each item
+ * @returns Async iterable of filtered items
+ */
+export async function* filterStream(source, predicate) {
+    for await (const item of source) {
+        if (await predicate(item)) {
+            yield item;
+        }
+    }
+}
+/**
+ * Batch stream chunks together
+ * @param source - Source async iterable
+ * @param batchSize - Number of items per batch
+ * @returns Async iterable of batched items
+ */
+export async function* batchStream(source, batchSize) {
+    let batch = [];
+    for await (const item of source) {
+        batch.push(item);
+        if (batch.length >= batchSize) {
+            yield batch;
+            batch = [];
+        }
+    }
+    if (batch.length > 0) {
+        yield batch;
+    }
+}
+/**
+ * Add delay between stream chunks
+ * @param source - Source async iterable
+ * @param delayMs - Delay in milliseconds between chunks
+ * @returns Async iterable with delays
+ */
+export async function* delayStream(source, delayMs) {
+    for await (const item of source) {
+        yield item;
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+}
+/**
+ * Convert a ReadableStream to an async iterable
+ * @param stream - ReadableStream to convert
+ * @returns Async iterable
+ */
+export async function* fromReadableStream(stream) {
+    const reader = stream.getReader();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            yield value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Create a streaming response that emits at regular intervals
+ * @param interval - Interval in milliseconds
+ * @param maxCount - Maximum number of emissions (optional)
+ * @param generator - Function to generate data for each emission
+ * @returns Async iterable of stream chunks
+ */
+export async function* intervalStream(interval, generator, maxCount) {
+    let count = 0;
+    while (maxCount === undefined || count < maxCount) {
+        const data = generator(count);
+        const chunk = typeof data === 'string' ? data : JSON.stringify(data);
+        yield createChunk(chunk);
+        count++;
+        if (maxCount !== undefined && count >= maxCount)
+            break;
+        await new Promise(resolve => setTimeout(resolve, interval));
+    }
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,465 @@
+/**
+ * ZapJS Runtime Types
+ *
+ * Shared type definitions for the ZapJS runtime.
+ * These types ensure type safety across IPC communication,
+ * handlers, and request/response handling.
+ */
+/**
+ * HTTP method types supported by ZapJS
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/**
+ * Base request interface from IPC
+ */
+export interface ZapRequest<TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>> {
+    /** Unique request ID for correlation across Rust/TypeScript boundary */
+    request_id: string;
+    /** HTTP method */
+    method: string;
+    /** Full path including query string */
+    path: string;
+    /** Path without query string */
+    path_only: string;
+    /** Parsed query parameters */
+    query: TQuery;
+    /** Route parameters extracted from path */
+    params: TParams;
+    /** HTTP headers */
+    headers: Record<string, string>;
+    /** Request body as string */
+    body: string;
+    /** Parsed cookies */
+    cookies: Record<string, string>;
+}
+/**
+ * Handler response format for IPC
+ */
+export interface ZapHandlerResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Type-safe handler function
+ *
+ * @template TParams - Route parameter types
+ * @template TQuery - Query parameter types
+ * @template TResponse - Response body type
+ */
+export type Handler<TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>, TResponse = unknown> = (request: ZapRequest<TParams, TQuery>) => TResponse | Promise<TResponse>;
+/**
+ * Internal handler function type (used by IPC server)
+ */
+export type InternalHandlerFunction = (req: ZapRequest) => Promise<ZapHandlerResponse>;
+/**
+ * Message to invoke a TypeScript handler
+ */
+export interface InvokeHandlerMessage {
+    type: 'invoke_handler';
+    handler_id: string;
+    request: ZapRequest;
+}
+/**
+ * Response from a handler invocation
+ */
+export interface HandlerResponseMessage {
+    type: 'handler_response';
+    handler_id: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Structured error response message with full context
+ */
+export interface ErrorMessage {
+    type: 'error';
+    /** Machine-readable error code (e.g., "HANDLER_ERROR", "VALIDATION_ERROR") */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code */
+    status: number;
+    /** Unique error identifier for log correlation */
+    digest: string;
+    /** Additional error-specific details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Health check request message
+ */
+export interface HealthCheckMessage {
+    type: 'health_check';
+}
+/**
+ * Health check response message
+ */
+export interface HealthCheckResponseMessage {
+    type: 'health_check_response';
+}
+/**
+ * Start a streaming response
+ */
+export interface StreamStartMessage {
+    type: 'stream_start';
+    stream_id: string;
+    status: number;
+    headers: Record<string, string>;
+}
+/**
+ * A chunk of streaming data
+ */
+export interface StreamChunkMessage {
+    type: 'stream_chunk';
+    stream_id: string;
+    /** Base64-encoded binary data */
+    data: string;
+}
+/**
+ * End of streaming response
+ */
+export interface StreamEndMessage {
+    type: 'stream_end';
+    stream_id: string;
+}
+/**
+ * All streaming message types
+ */
+export type StreamMessage = StreamStartMessage | StreamChunkMessage | StreamEndMessage;
+/**
+ * WebSocket connection opened
+ */
+export interface WsConnectMessage {
+    type: 'ws_connect';
+    connection_id: string;
+    handler_id: string;
+    path: string;
+    headers: Record<string, string>;
+}
+/**
+ * WebSocket message from client
+ */
+export interface WsMessageMessage {
+    type: 'ws_message';
+    connection_id: string;
+    handler_id: string;
+    /** Message data (text or base64-encoded binary) */
+    data: string;
+    /** true if binary data */
+    binary: boolean;
+}
+/**
+ * WebSocket connection closed
+ */
+export interface WsCloseMessage {
+    type: 'ws_close';
+    connection_id: string;
+    handler_id: string;
+    code?: number;
+    reason?: string;
+}
+/**
+ * WebSocket message to send to client (TypeScript -> Rust)
+ */
+export interface WsSendMessage {
+    type: 'ws_send';
+    connection_id: string;
+    data: string;
+    binary: boolean;
+}
+/**
+ * All WebSocket message types
+ */
+export type WsMessage = WsConnectMessage | WsMessageMessage | WsCloseMessage | WsSendMessage;
+/**
+ * All possible IPC message types (discriminated union)
+ */
+export type IpcMessage = InvokeHandlerMessage | HandlerResponseMessage | ErrorMessage | HealthCheckMessage | HealthCheckResponseMessage | RpcCallMessage | RpcResponseMessage | RpcErrorMessage | StreamStartMessage | StreamChunkMessage | StreamEndMessage | WsConnectMessage | WsMessageMessage | WsCloseMessage | WsSendMessage;
+/**
+ * IPC message types as string literals
+ */
+export type IpcMessageType = IpcMessage['type'];
+/**
+ * RPC call request
+ */
+export interface RpcCallMessage {
+    type: 'rpc_call';
+    function_name: string;
+    params: Record<string, unknown>;
+    request_id: string;
+}
+/**
+ * RPC successful response
+ */
+export interface RpcResponseMessage {
+    type: 'rpc_response';
+    request_id: string;
+    result: unknown;
+}
+/**
+ * RPC error response
+ */
+export interface RpcErrorMessage {
+    type: 'rpc_error';
+    request_id: string;
+    error: string;
+    error_type: string;
+}
+/**
+ * All RPC message types
+ */
+export type RpcMessage = RpcCallMessage | RpcResponseMessage | RpcErrorMessage;
+/**
+ * Route configuration for Rust server
+ */
+export interface RouteConfig {
+    method: string;
+    path: string;
+    handler_id: string;
+    is_typescript: boolean;
+}
+/**
+ * Static file serving options
+ */
+export interface StaticFileOptions {
+    /** Cache-Control max-age in seconds */
+    maxAge?: number;
+    /** Enable directory listing */
+    directoryListing?: boolean;
+    /** Default file to serve for directories */
+    index?: string;
+    /** Enable ETag generation */
+    etag?: boolean;
+}
+/**
+ * Static file configuration
+ */
+export interface StaticFileConfig {
+    prefix: string;
+    directory: string;
+    options?: StaticFileOptions;
+}
+/**
+ * Middleware configuration
+ */
+export interface MiddlewareConfig {
+    enable_cors?: boolean;
+    enable_logging?: boolean;
+    enable_compression?: boolean;
+    /** Security configuration */
+    security?: SecurityConfig;
+    /** CORS configuration (replaces enable_cors when present) */
+    cors?: CorsConfig;
+}
+/**
+ * Security headers configuration
+ */
+export interface SecurityHeadersConfig {
+    /** Enable security headers middleware (default: true) */
+    enabled?: boolean;
+    /** X-Frame-Options header (default: "DENY") */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    /** X-Content-Type-Options (default: "nosniff") */
+    contentTypeOptions?: 'nosniff' | false;
+    /** X-XSS-Protection (default: "1; mode=block") */
+    xssProtection?: string | false;
+    /** HSTS configuration */
+    hsts?: HstsConfig | false;
+    /** Content-Security-Policy (must be explicitly configured) */
+    contentSecurityPolicy?: string;
+    /** Referrer-Policy (default: "strict-origin-when-cross-origin") */
+    referrerPolicy?: string;
+}
+/**
+ * HTTP Strict Transport Security configuration
+ */
+export interface HstsConfig {
+    /** max-age in seconds (default: 31536000 = 1 year) */
+    maxAge?: number;
+    /** Include subdomains (default: true) */
+    includeSubDomains?: boolean;
+    /** Preload flag (default: false) */
+    preload?: boolean;
+}
+/**
+ * Rate limiting configuration
+ */
+export interface RateLimitConfig {
+    /** Enable rate limiting (default: false) */
+    enabled?: boolean;
+    /** Maximum requests per window (default: 100) */
+    max?: number;
+    /** Time window in seconds (default: 60) */
+    windowSecs?: number;
+    /** Storage backend: "memory" | "redis" (default: "memory") */
+    storage?: 'memory' | 'redis';
+    /** Redis connection URL (required if storage is "redis") */
+    redisUrl?: string;
+    /** Paths to skip rate limiting */
+    skipPaths?: string[];
+    /** Custom error message */
+    message?: string;
+}
+/**
+ * CORS configuration (strict - no wildcard allowed)
+ */
+export interface CorsConfig {
+    /** Allowed origins (REQUIRED - no more "*" wildcard) */
+    origins: string[];
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    headers?: string[];
+    /** Expose headers */
+    exposeHeaders?: string[];
+    /** Allow credentials */
+    credentials?: boolean;
+    /** Max age for preflight cache in seconds */
+    maxAge?: number;
+}
+/**
+ * Full security configuration
+ */
+export interface SecurityConfig {
+    /** Security headers configuration */
+    headers?: SecurityHeadersConfig;
+    /** Rate limiting configuration */
+    rateLimit?: RateLimitConfig;
+    /** CORS configuration */
+    cors?: CorsConfig;
+}
+/**
+ * Observability configuration
+ */
+export interface ObservabilityConfig {
+    /** Enable JSON logging format (default: false in dev, true in prod) */
+    jsonLogs?: boolean;
+    /** Metrics endpoint path (default: "/metrics", null to disable) */
+    metricsPath?: string | null;
+    /** Enable request ID generation/propagation (default: true) */
+    enableRequestId?: boolean;
+    /** Log level */
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Full Zap server configuration
+ */
+export interface ZapConfig {
+    port: number;
+    hostname: string;
+    ipc_socket_path: string;
+    max_request_body_size?: number;
+    request_timeout_secs?: number;
+    routes: RouteConfig[];
+    static_files: StaticFileConfig[];
+    middleware: MiddlewareConfig;
+    health_check_path?: string;
+    metrics_path?: string;
+    /** Security configuration */
+    security?: SecurityConfig;
+    /** Observability configuration */
+    observability?: ObservabilityConfig;
+}
+/**
+ * Type guard for InvokeHandlerMessage
+ */
+export declare function isInvokeHandlerMessage(msg: IpcMessage): msg is InvokeHandlerMessage;
+/**
+ * Type guard for HandlerResponseMessage
+ */
+export declare function isHandlerResponseMessage(msg: IpcMessage): msg is HandlerResponseMessage;
+/**
+ * Type guard for ErrorMessage
+ */
+export declare function isErrorMessage(msg: IpcMessage): msg is ErrorMessage;
+/**
+ * Type guard for HealthCheckMessage
+ */
+export declare function isHealthCheckMessage(msg: IpcMessage): msg is HealthCheckMessage;
+/**
+ * Type guard for HealthCheckResponseMessage
+ */
+export declare function isHealthCheckResponseMessage(msg: IpcMessage): msg is HealthCheckResponseMessage;
+/**
+ * Type guard for RpcResponseMessage
+ */
+export declare function isRpcResponseMessage(msg: RpcMessage): msg is RpcResponseMessage;
+/**
+ * Type guard for RpcErrorMessage
+ */
+export declare function isRpcErrorMessage(msg: RpcMessage): msg is RpcErrorMessage;
+/**
+ * Pending RPC request tracker
+ */
+export interface PendingRequest<T = unknown> {
+    resolve: (value: T) => void;
+    reject: (reason: Error) => void;
+    timeout: NodeJS.Timeout;
+}
+/**
+ * File-based routing configuration
+ */
+export interface FileRouteConfig {
+    routesDir?: string;
+    generatedDir?: string;
+}
+/**
+ * Zap server options
+ */
+export interface ZapOptions {
+    port?: number;
+    hostname?: string;
+    logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * A chunk of streaming data
+ */
+export interface StreamChunk {
+    /** String data to send */
+    data?: string;
+    /** Binary data to send (base64 encoded in IPC) */
+    bytes?: Uint8Array;
+}
+/**
+ * Streaming handler response - yields chunks over time
+ */
+export type StreamingHandler<TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>> = (request: ZapRequest<TParams, TQuery>) => AsyncIterable<StreamChunk>;
+/**
+ * Combined handler type that can be regular or streaming
+ */
+export type AnyHandler<TParams extends Record<string, string> = Record<string, string>, TQuery extends Record<string, string> = Record<string, string>, TResponse = unknown> = Handler<TParams, TQuery, TResponse> | StreamingHandler<TParams, TQuery>;
+/**
+ * Check if a value is an async iterable (streaming handler result)
+ */
+export declare function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T>;
+/**
+ * WebSocket connection context
+ */
+export interface WsConnection {
+    /** Unique connection ID */
+    id: string;
+    /** Path the WebSocket connected to */
+    path: string;
+    /** Headers from the initial connection */
+    headers: Record<string, string>;
+    /** Send a text message to the client */
+    send(data: string): void;
+    /** Send binary data to the client */
+    sendBinary(data: Uint8Array): void;
+    /** Close the connection */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * WebSocket handler definition
+ */
+export interface WsHandler {
+    /** Called when a client connects */
+    onConnect?: (connection: WsConnection) => void | Promise<void>;
+    /** Called when a message is received */
+    onMessage?: (connection: WsConnection, message: string | Uint8Array) => void | Promise<void>;
+    /** Called when the connection closes */
+    onClose?: (connection: WsConnection, code?: number, reason?: string) => void | Promise<void>;
+    /** Called when an error occurs */
+    onError?: (connection: WsConnection, error: Error) => void | Promise<void>;
+}

package/dist/runtime/types.js

@@ -0,0 +1,60 @@
+/**
+ * ZapJS Runtime Types
+ *
+ * Shared type definitions for the ZapJS runtime.
+ * These types ensure type safety across IPC communication,
+ * handlers, and request/response handling.
+ */
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Type guard for InvokeHandlerMessage
+ */
+export function isInvokeHandlerMessage(msg) {
+    return msg.type === 'invoke_handler';
+}
+/**
+ * Type guard for HandlerResponseMessage
+ */
+export function isHandlerResponseMessage(msg) {
+    return msg.type === 'handler_response';
+}
+/**
+ * Type guard for ErrorMessage
+ */
+export function isErrorMessage(msg) {
+    return msg.type === 'error';
+}
+/**
+ * Type guard for HealthCheckMessage
+ */
+export function isHealthCheckMessage(msg) {
+    return msg.type === 'health_check';
+}
+/**
+ * Type guard for HealthCheckResponseMessage
+ */
+export function isHealthCheckResponseMessage(msg) {
+    return msg.type === 'health_check_response';
+}
+/**
+ * Type guard for RpcResponseMessage
+ */
+export function isRpcResponseMessage(msg) {
+    return msg.type === 'rpc_response';
+}
+/**
+ * Type guard for RpcErrorMessage
+ */
+export function isRpcErrorMessage(msg) {
+    return msg.type === 'rpc_error';
+}
+/**
+ * Check if a value is an async iterable (streaming handler result)
+ */
+export function isAsyncIterable(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        Symbol.asyncIterator in value);
+}