@lolyjs/core 0.2.0-alpha.3 → 0.2.0-alpha.30

package/dist/index.d.mts

@@ -1,7 +1,8 @@
 import http from 'http';
+export { a as ApiContext, A as ApiMiddleware, G as GenerateStaticParams, L as LoaderResult, M as MetadataLoader, R as RouteMiddleware, S as ServerContext, b as ServerLoader, W as WssActions } from './index.types-B9j4OQft.mjs';
+import { Socket } from 'socket.io';
 import { Request, Response } from 'express';
-import { Socket, Server } from 'socket.io';
-export { c as bootstrapClient } from './bootstrap-BiCQmSkx.mjs';
+export { c as bootstrapClient } from './bootstrap-BfGTMUkj.mjs';
 import { ZodSchema, z } from 'zod';
 import * as express_rate_limit from 'express-rate-limit';
 import pino, { Logger as Logger$1 } from 'pino';
@@ -63,6 +64,7 @@ declare const DEFAULT_CONFIG: FrameworkConfig;
  *
  * @param projectRoot - Root directory of the project
  * @returns Framework configuration
+ * @throws ConfigValidationError if configuration is invalid
  */
 declare function loadConfig(projectRoot: string): FrameworkConfig;
 /**
@@ -119,77 +121,301 @@ interface InitServerData {
     server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 }
 
-type GenerateStaticParams = () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;
-interface ServerContext {
-    req: Request;
-    res: Response;
-    params: Record<string, string>;
-    pathname: string;
-    locals: Record<string, any>;
+/**
+ * Authentication context provided to the auth hook.
+ * Contains request metadata needed for authentication.
+ */
+interface AuthContext {
+    /** Request headers */
+    req: {
+        headers: Record<string, string | string[] | undefined>;
+        ip?: string;
+        url?: string;
+        cookies?: Record<string, string>;
+    };
+    /** Socket.IO socket instance */
+    socket: Socket;
+    /** Namespace path (e.g., "/chat") */
+    namespace: string;
 }
+/**
+ * Rate limit configuration for events.
+ */
+interface RateLimitCfg {
+    /** Maximum events per second */
+    eventsPerSecond: number;
+    /** Burst capacity (optional, defaults to eventsPerSecond * 2) */
+    burst?: number;
+}
+/**
+ * Guard function type. Returns true to allow, false to block.
+ */
+type GuardFn<TUser = any> = (ctx: {
+    user: TUser | null;
+    req: AuthContext["req"];
+    namespace: string;
+}) => boolean | Promise<boolean>;
+/**
+ * Authentication function type.
+ * Returns the authenticated user or null.
+ */
+type AuthFn<TUser = any> = (ctx: AuthContext) => TUser | null | Promise<TUser | null>;
+/**
+ * Schema validation adapter.
+ * Must support Zod-like interface: schema.parse(data) or schema.safeParse(data)
+ */
+type Schema = {
+    parse?: (data: any) => any;
+    safeParse?: (data: any) => {
+        success: boolean;
+        error?: any;
+        data?: any;
+    };
+} & Record<string, any>;
+/**
+ * Realtime state store interface.
+ * Provides key-value storage, lists, sets, and atomic operations.
+ */
+interface RealtimeStateStore {
+    /** Get a value by key */
+    get<T = any>(key: string): Promise<T | null>;
+    /** Set a value with optional TTL */
+    set<T = any>(key: string, value: T, opts?: {
+        ttlMs?: number;
+    }): Promise<void>;
+    /** Delete a key */
+    del(key: string): Promise<void>;
+    /** Increment a numeric value */
+    incr(key: string, by?: number): Promise<number>;
+    /** Decrement a numeric value */
+    decr(key: string, by?: number): Promise<number>;
+    /** Push to a list (left push) */
+    listPush(key: string, value: any, opts?: {
+        maxLen?: number;
+    }): Promise<void>;
+    /** Get range from a list */
+    listRange<T = any>(key: string, start: number, end: number): Promise<T[]>;
+    /** Add member to a set */
+    setAdd(key: string, member: string): Promise<void>;
+    /** Remove member from a set */
+    setRem(key: string, member: string): Promise<void>;
+    /** Get all members of a set */
+    setMembers(key: string): Promise<string[]>;
+    /** Optional: Acquire a distributed lock (returns unlock function) */
+    lock?(key: string, ttlMs: number): Promise<() => Promise<void>>;
+}
+/**
+ * Logger interface for realtime events.
+ */
+interface RealtimeLogger {
+    debug(message: string, meta?: Record<string, any>): void;
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, meta?: Record<string, any>): void;
+}
+/**
+ * Metrics interface (optional for v1).
+ */
+interface RealtimeMetrics {
+    incrementCounter(name: string, labels?: Record<string, string>): void;
+    recordLatency(name: string, ms: number, labels?: Record<string, string>): void;
+}
+/**
+ * Extended WssActions with full RFC support.
+ */
 interface WssActions {
     /**
-     * Emit an event to all clients in the namespace
+     * Emit to current socket only (reply)
+     */
+    reply(event: string, payload?: any): void;
+    /**
+     * Emit to all sockets in current namespace
+     */
+    emit(event: string, payload?: any): void;
+    /**
+     * Emit to everyone except current socket
      */
-    emit: (event: string, ...args: any[]) => void;
+    broadcast(event: string, payload?: any, opts?: {
+        excludeSelf?: boolean;
+    }): void;
+    /**
+     * Join a room
+     */
+    join(room: string): Promise<void>;
+    /**
+     * Leave a room
+     */
+    leave(room: string): Promise<void>;
+    /**
+     * Emit to a specific room
+     */
+    toRoom(room: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit to a specific user (by userId)
+     * Uses presence mapping to find user's sockets
+     */
+    toUser(userId: string): {
+        emit(event: string, payload?: any): void;
+    };
     /**
-     * Emit an event to a specific socket by Socket.IO socket ID
+     * Emit error event (reserved event: __loly:error)
      */
-    emitTo: (socketId: string, event: string, ...args: any[]) => void;
+    error(code: string, message: string, details?: any): void;
     /**
-     * Emit an event to a specific client by custom clientId
-     * Requires clientId to be stored in socket.data.clientId during connection
+     * Legacy: Emit to a specific socket by Socket.IO socket ID
+     * @deprecated Use toUser() for user targeting
      */
-    emitToClient: (clientId: string, event: string, ...args: any[]) => void;
+    emitTo?: (socketId: string, event: string, ...args: any[]) => void;
     /**
-     * Broadcast an event to all clients in the namespace except the sender
+     * Legacy: Emit to a specific client by custom clientId
+     * @deprecated Use toUser() for user targeting
      */
-    broadcast: (event: string, ...args: any[]) => void;
+    emitToClient?: (clientId: string, event: string, ...args: any[]) => void;
 }
-interface WssContext {
-    socket: Socket;
-    io: Server;
+/**
+ * Extended WssContext with full RFC support.
+ */
+interface WssContext<TData = any, TUser = any> {
+    /** Request metadata */
+    req: {
+        headers: Record<string, string | string[] | undefined>;
+        ip?: string;
+        url?: string;
+        cookies?: Record<string, string>;
+    };
+    /** Authenticated user (set by auth hook) */
+    user: TUser | null;
+    /** Incoming payload for current event */
+    data: TData;
+    /** Route params (from dynamic routes) */
     params: Record<string, string>;
+    /** Route pathname */
     pathname: string;
-    data?: any;
+    /** Framework utilities */
     actions: WssActions;
+    /** State store for shared state */
+    state: RealtimeStateStore;
+    /** Logger with WSS context */
+    log: RealtimeLogger;
+    /** Metrics (optional) */
+    metrics?: RealtimeMetrics;
 }
-type RouteMiddleware = (ctx: ServerContext & {
-    theme?: string;
-}, next: () => Promise<void>) => Promise<void> | void;
-interface LoaderResult {
-    props?: Record<string, any>;
-    redirect?: {
-        destination: string;
-        permanent?: boolean;
-    };
-    notFound?: boolean;
-    metadata?: PageMetadata | null;
-    className?: string;
-    theme?: string;
+/**
+ * WSS event handler type.
+ */
+type WssHandler<TData = any, TUser = any> = (ctx: WssContext<TData, TUser>) => void | Promise<void>;
+/**
+ * WSS event definition.
+ * Can be a simple handler or an object with validation, guards, and rate limiting.
+ */
+type WssEventDefinition<TData = any, TUser = any> = WssHandler<TData, TUser> | {
+    /** Schema for validation (Zod/Valibot compatible) */
+    schema?: Schema;
+    /** Per-event rate limit config */
+    rateLimit?: RateLimitCfg;
+    /** Guard function (auth/roles/permissions) */
+    guard?: GuardFn<TUser>;
+    /** Event handler */
+    handler: WssHandler<TData, TUser>;
+};
+/**
+ * WSS route definition (result of defineWssRoute).
+ */
+interface WssRouteDefinition<TUser = any> {
+    /** Namespace (optional, inferred from folder name) */
+    namespace?: string;
+    /** Authentication hook */
+    auth?: AuthFn<TUser>;
+    /** Connection hook */
+    onConnect?: WssHandler<any, TUser>;
+    /** Disconnection hook */
+    onDisconnect?: (ctx: WssContext<any, TUser>, reason?: string) => void | Promise<void>;
+    /** Event handlers */
+    events: Record<string, WssEventDefinition<any, TUser>>;
 }
-type ServerLoader = (ctx: ServerContext) => Promise<LoaderResult>;
-interface PageMetadata {
-    title?: string;
-    description?: string;
-    metaTags?: {
-        name?: string;
-        property?: string;
-        content: string;
-    }[];
+
+/**
+ * Rewrite condition types.
+ * Used in the `has` array to conditionally apply rewrites.
+ */
+type RewriteConditionType = "host" | "header" | "cookie" | "query";
+/**
+ * Rewrite condition.
+ * Defines when a rewrite should be applied.
+ */
+interface RewriteCondition {
+    type: RewriteConditionType;
+    key?: string;
+    value: string;
 }
-type MetadataLoader = (ctx: ServerContext) => PageMetadata | Promise<PageMetadata>;
-interface ApiContext {
-    req: Request;
-    res: Response;
-    Response: (body?: any, status?: number) => Response<any, Record<string, any>>;
-    NotFound: (body?: any) => Response<any, Record<string, any>>;
-    params: Record<string, string>;
-    pathname: string;
-    locals: Record<string, any>;
+/**
+ * Rewrite destination can be:
+ * - A string (static or with :param placeholders)
+ * - An async function that returns a string (for dynamic rewrites)
+ */
+type RewriteDestination = string | ((params: Record<string, string>, req: Request) => Promise<string> | string);
+/**
+ * Rewrite rule configuration.
+ * Defines how to rewrite a URL pattern.
+ */
+interface RewriteRule {
+    source: string;
+    destination: RewriteDestination;
+    has?: RewriteCondition[];
 }
-type ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
+/**
+ * Rewrite configuration.
+ * Array of rewrite rules to apply in order.
+ */
+type RewriteConfig = RewriteRule[];
 
+/**
+ * Realtime/WebSocket configuration
+ */
+interface RealtimeConfig {
+    /** Enable realtime features */
+    enabled?: boolean;
+    /** Socket.IO server settings */
+    path?: string;
+    transports?: ("websocket" | "polling")[];
+    pingIntervalMs?: number;
+    pingTimeoutMs?: number;
+    maxPayloadBytes?: number;
+    /** Security */
+    allowedOrigins?: string | string[];
+    cors?: {
+        credentials?: boolean;
+        allowedHeaders?: string[];
+    };
+    /** Scaling configuration */
+    scale?: {
+        mode?: "single" | "cluster";
+        adapter?: {
+            name: "redis";
+            url: string;
+            pubClientName?: string;
+            subClientName?: string;
+        };
+        stateStore?: {
+            name: "memory" | "redis";
+            url?: string;
+            prefix?: string;
+        };
+    };
+    /** Rate limiting */
+    limits?: {
+        connectionsPerIp?: number;
+        eventsPerSecond?: number;
+        burst?: number;
+    };
+    /** Logging */
+    logging?: {
+        level?: "debug" | "info" | "warn" | "error";
+        pretty?: boolean;
+    };
+}
 interface ServerConfig {
     bodyLimit?: string;
     corsOrigin?: string | string[] | boolean | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
@@ -207,6 +433,8 @@ interface ServerConfig {
             includeSubDomains?: boolean;
         };
     };
+    /** Realtime/WebSocket configuration */
+    realtime?: RealtimeConfig;
 }
 
 interface BuildAppOptions {
@@ -216,6 +444,43 @@ interface BuildAppOptions {
 }
 declare function buildApp(options?: BuildAppOptions): Promise<void>;
 
+/**
+ * Defines a WebSocket route with authentication, hooks, and event handlers.
+ *
+ * This is the new, recommended way to define WSS routes. It provides:
+ * - Type safety
+ * - Built-in validation
+ * - Auth hooks
+ * - Connection/disconnection hooks
+ * - Per-event validation, guards, and rate limiting
+ *
+ * @example
+ * ```ts
+ * import { defineWssRoute } from "@lolyjs/core";
+ * import { z } from "zod";
+ *
+ * export default defineWssRoute({
+ *   auth: async (ctx) => {
+ *     const token = ctx.req.headers.authorization;
+ *     return await verifyToken(token);
+ *   },
+ *   onConnect: (ctx) => {
+ *     console.log("User connected:", ctx.user?.id);
+ *   },
+ *   events: {
+ *     message: {
+ *       schema: z.object({ text: z.string() }),
+ *       guard: ({ user }) => !!user,
+ *       handler: (ctx) => {
+ *         ctx.actions.broadcast("message", ctx.data);
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineWssRoute<TUser = any>(definition: WssRouteDefinition<TUser>): WssRouteDefinition<TUser>;
+
 declare function withCache(fn: any, options: any): any;
 
 /**
@@ -332,12 +597,15 @@ interface RateLimitConfig {
     legacyHeaders?: boolean;
     skipSuccessfulRequests?: boolean;
     skipFailedRequests?: boolean;
+    keyGenerator?: (req: any) => string;
+    skip?: (req: any) => boolean;
 }
 /**
  * Creates a rate limiter middleware with configurable options.
  *
  * @param config - Rate limiting configuration
  * @returns Express rate limit middleware
+ * @throws Error if configuration is invalid
  */
 declare function createRateLimiter(config?: RateLimitConfig): express_rate_limit.RateLimitRequestHandler;
 /**
@@ -442,4 +710,4 @@ declare function requestLoggerMiddleware(options?: {
  */
 declare function getRequestLogger(req: Request): Logger;
 
-export { type ApiContext, type ApiMiddleware, DEFAULT_CONFIG, type FrameworkConfig, type GenerateStaticParams, type InitServerData, type LoaderResult, type LogLevel, Logger, type LoggerContext, type LoggerOptions, type MetadataLoader, type RouteMiddleware, type ServerConfig, type ServerContext, type ServerLoader, ValidationError, type WssContext, buildApp, commonSchemas, createModuleLogger, createRateLimiter, defaultRateLimiter, generateRequestId, getAppDir, getBuildDir, getLogger, getRequestLogger, getStaticDir, lenientRateLimiter, loadConfig, logger, requestLoggerMiddleware, resetLogger, safeValidate, sanitizeObject, sanitizeParams, sanitizeQuery, sanitizeString, setLogger, startDevServer, startProdServer, strictRateLimiter, validate, withCache };
+export { type AuthContext, type AuthFn, DEFAULT_CONFIG, type FrameworkConfig, type GuardFn, type InitServerData, type LogLevel, Logger, type LoggerContext, type LoggerOptions, type RateLimitCfg, type RealtimeConfig, type RealtimeLogger, type RealtimeMetrics, type RealtimeStateStore, type RewriteCondition, type RewriteConfig, type RewriteDestination, type RewriteRule, type Schema, type ServerConfig, ValidationError, type WssContext, type WssEventDefinition, type WssHandler, type WssRouteDefinition, buildApp, commonSchemas, createModuleLogger, createRateLimiter, defaultRateLimiter, defineWssRoute, generateRequestId, getAppDir, getBuildDir, getLogger, getRequestLogger, getStaticDir, lenientRateLimiter, loadConfig, logger, requestLoggerMiddleware, resetLogger, safeValidate, sanitizeObject, sanitizeParams, sanitizeQuery, sanitizeString, setLogger, startDevServer, startProdServer, strictRateLimiter, validate, withCache };