@lolyjs/core 0.2.0-alpha.15 → 0.2.0-alpha.17

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import http from 'http';
-import { Request, Response } from 'express';
-import { Socket, Server } from 'socket.io';
-export { c as bootstrapClient } from './bootstrap-DgvWWDim.js';
+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-DMOO-uvF.js';
+import { Server, Socket } from 'socket.io';
+export { c as bootstrapClient } from './bootstrap-BfGTMUkj.js';
 import { ZodSchema, z } from 'zod';
 import * as express_rate_limit from 'express-rate-limit';
 import pino, { Logger as Logger$1 } from 'pino';
+import { Request, Response } from 'express';
 
 /**
  * Framework configuration interface.
@@ -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,81 +121,271 @@ 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"];
+    socket: Socket;
+    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
+     */
+    broadcast(event: string, payload?: any, opts?: {
+        excludeSelf?: boolean;
+    }): void;
+    /**
+     * Join a room
+     */
+    join(room: string): Promise<void>;
+    /**
+     * Leave a room
      */
-    emit: (event: string, ...args: any[]) => void;
+    leave(room: string): Promise<void>;
     /**
-     * Emit an event to a specific socket by Socket.IO socket ID
+     * Emit to a specific room
      */
-    emitTo: (socketId: string, event: string, ...args: any[]) => void;
+    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 error event (reserved event: __loly:error)
+     */
+    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;
+/**
+ * Extended WssContext with full RFC support.
+ */
+interface WssContext<TData = any, TUser = any> {
+    /** Socket.IO server instance */
     io: Server;
+    /** Socket.IO socket instance */
+    socket: Socket;
+    /** 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;
-}
-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;
+    /** State store for shared state */
+    state: RealtimeStateStore;
+    /** Logger with WSS context */
+    log: RealtimeLogger;
+    /** Metrics (optional) */
+    metrics?: RealtimeMetrics;
 }
 /**
- * Server loader function type (getServerSideProps).
- * This function is exported from server.hook.ts files.
- */
-type ServerLoader = (ctx: ServerContext) => Promise<LoaderResult>;
-interface PageMetadata {
-    title?: string;
-    description?: string;
-    metaTags?: {
-        name?: string;
-        property?: string;
-        content: 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>;
+ * 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 ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
 
+/**
+ * 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);
@@ -211,6 +403,8 @@ interface ServerConfig {
             includeSubDomains?: boolean;
         };
     };
+    /** Realtime/WebSocket configuration */
+    realtime?: RealtimeConfig;
 }
 
 interface BuildAppOptions {
@@ -220,6 +414,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;
 
 /**
@@ -336,12 +567,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;
 /**
@@ -446,4 +680,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 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 };