@lolyjs/core 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,445 @@
+import http from 'http';
+import { Request, Response } from 'express';
+import { Socket, Server } from 'socket.io';
+export { c as bootstrapClient } from './bootstrap-BiCQmSkx.mjs';
+import { ZodSchema, z } from 'zod';
+import * as express_rate_limit from 'express-rate-limit';
+import pino, { Logger as Logger$1 } from 'pino';
+
+/**
+ * Framework configuration interface.
+ *
+ * Allows customization of framework behavior without code changes.
+ */
+interface FrameworkConfig {
+    directories: {
+        app: string;
+        build: string;
+        static: string;
+    };
+    conventions: {
+        page: string;
+        layout: string;
+        notFound: string;
+        error: string;
+        api: string;
+    };
+    routing: {
+        trailingSlash: 'always' | 'never' | 'ignore';
+        caseSensitive: boolean;
+        basePath: string;
+    };
+    build: {
+        clientBundler: 'rspack' | 'webpack' | 'vite';
+        serverBundler: 'esbuild' | 'tsup' | 'swc';
+        outputFormat: 'cjs' | 'esm';
+    };
+    server: {
+        adapter: 'express' | 'fastify' | 'koa';
+        port: number;
+        host: string;
+    };
+    rendering: {
+        framework: 'react' | 'preact' | 'vue' | 'svelte';
+        streaming: boolean;
+        ssr: boolean;
+        ssg: boolean;
+    };
+    plugins?: any[];
+}
+/**
+ * Default framework configuration.
+ */
+declare const DEFAULT_CONFIG: FrameworkConfig;
+/**
+ * Loads framework configuration from project root.
+ *
+ * Looks for configuration in the following order:
+ * 1. loly.config.ts (TypeScript)
+ * 2. loly.config.js (JavaScript)
+ * 3. loly.config.json (JSON)
+ *
+ * Merges user config with defaults and validates.
+ *
+ * @param projectRoot - Root directory of the project
+ * @returns Framework configuration
+ */
+declare function loadConfig(projectRoot: string): FrameworkConfig;
+/**
+ * Gets the resolved app directory path.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param config - Framework configuration
+ * @returns Resolved app directory path
+ */
+declare function getAppDir(projectRoot: string, config: FrameworkConfig): string;
+/**
+ * Gets the resolved build directory path.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param config - Framework configuration
+ * @returns Resolved build directory path
+ */
+declare function getBuildDir(projectRoot: string, config: FrameworkConfig): string;
+/**
+ * Gets the resolved static directory path.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param config - Framework configuration
+ * @returns Resolved static directory path
+ */
+declare function getStaticDir(projectRoot: string, config: FrameworkConfig): string;
+
+interface StartDevServerOptions {
+    port?: number;
+    rootDir?: string;
+    appDir?: string;
+}
+/**
+ * Development server startup.
+ * Wrapper around startServer for backward compatibility.
+ *
+ * @param options - Server options
+ */
+declare function startDevServer(options?: StartDevServerOptions): Promise<void>;
+interface StartProdServerOptions {
+    port?: number;
+    rootDir?: string;
+    appDir?: string;
+}
+/**
+ * Production server startup.
+ * Wrapper around startServer for backward compatibility.
+ *
+ * @param options - Server options
+ */
+declare function startProdServer(options?: StartProdServerOptions): Promise<void>;
+
+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>;
+}
+interface WssActions {
+    /**
+     * Emit an event to all clients in the namespace
+     */
+    emit: (event: string, ...args: any[]) => void;
+    /**
+     * Emit an event to a specific socket by Socket.IO socket ID
+     */
+    emitTo: (socketId: string, event: string, ...args: any[]) => void;
+    /**
+     * Emit an event to a specific client by custom clientId
+     * Requires clientId to be stored in socket.data.clientId during connection
+     */
+    emitToClient: (clientId: string, event: string, ...args: any[]) => void;
+    /**
+     * Broadcast an event to all clients in the namespace except the sender
+     */
+    broadcast: (event: string, ...args: any[]) => void;
+}
+interface WssContext {
+    socket: Socket;
+    io: Server;
+    params: Record<string, string>;
+    pathname: string;
+    data?: any;
+    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;
+}
+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>;
+}
+type ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
+
+interface ServerConfig {
+    bodyLimit?: string;
+    corsOrigin?: string | string[] | boolean | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
+    rateLimit?: {
+        windowMs?: number;
+        max?: number;
+        apiMax?: number;
+        strictMax?: number;
+        strictPatterns?: string[];
+    };
+    security?: {
+        contentSecurityPolicy?: boolean | Record<string, any>;
+        hsts?: boolean | {
+            maxAge?: number;
+            includeSubDomains?: boolean;
+        };
+    };
+}
+
+interface BuildAppOptions {
+    rootDir?: string;
+    appDir?: string;
+    config?: FrameworkConfig;
+}
+declare function buildApp(options?: BuildAppOptions): Promise<void>;
+
+declare function withCache(fn: any, options: any): any;
+
+/**
+ * Validation error with detailed information.
+ */
+declare class ValidationError extends Error {
+    errors: z.ZodIssue[];
+    constructor(errors: z.ZodIssue[], message?: string);
+    /**
+     * Formats validation errors into a user-friendly format.
+     */
+    format(): Record<string, string[]>;
+}
+/**
+ * Validates data against a Zod schema.
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @returns Validated data
+ * @throws ValidationError if validation fails
+ */
+declare function validate<T>(schema: ZodSchema<T>, data: unknown): T;
+/**
+ * Safely validates data and returns a result object.
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @returns Result object with success flag and data/error
+ */
+declare function safeValidate<T>(schema: ZodSchema<T>, data: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ValidationError;
+};
+/**
+ * Common validation schemas for reuse.
+ */
+declare const commonSchemas: {
+    /**
+     * Validates a string parameter (e.g., route params).
+     */
+    stringParam: z.ZodString;
+    /**
+     * Validates an optional string parameter.
+     */
+    optionalStringParam: z.ZodOptional<z.ZodString>;
+    /**
+     * Validates a numeric ID parameter.
+     */
+    idParam: z.ZodEffects<z.ZodString, number, string>;
+    /**
+     * Validates a UUID parameter.
+     */
+    uuidParam: z.ZodString;
+    /**
+     * Validates pagination parameters.
+     */
+    pagination: z.ZodObject<{
+        page: z.ZodDefault<z.ZodEffects<z.ZodString, number, string>>;
+        limit: z.ZodDefault<z.ZodEffects<z.ZodString, number, string>>;
+    }, "strip", z.ZodTypeAny, {
+        page: number;
+        limit: number;
+    }, {
+        page?: string | undefined;
+        limit?: string | undefined;
+    }>;
+    /**
+     * Validates a search query parameter.
+     */
+    searchQuery: z.ZodOptional<z.ZodString>;
+};
+
+/**
+ * Security utilities for input sanitization.
+ */
+/**
+ * Sanitizes a string by removing potentially dangerous characters.
+ * Basic sanitization - for production, consider using a library like DOMPurify.
+ *
+ * @param input - String to sanitize
+ * @returns Sanitized string
+ */
+declare function sanitizeString(input: string): string;
+/**
+ * Sanitizes an object by recursively sanitizing all string values.
+ *
+ * @param obj - Object to sanitize
+ * @returns Sanitized object
+ */
+declare function sanitizeObject<T extends Record<string, any>>(obj: T): T;
+/**
+ * Sanitizes route parameters.
+ *
+ * @param params - Route parameters object
+ * @returns Sanitized parameters
+ */
+declare function sanitizeParams<T extends Record<string, string | string[]>>(params: T): T;
+/**
+ * Sanitizes query parameters.
+ *
+ * @param query - Query parameters object
+ * @returns Sanitized query parameters
+ */
+declare function sanitizeQuery<T extends Record<string, any>>(query: T): T;
+
+interface RateLimitConfig {
+    windowMs?: number;
+    max?: number;
+    message?: string;
+    standardHeaders?: boolean;
+    legacyHeaders?: boolean;
+    skipSuccessfulRequests?: boolean;
+    skipFailedRequests?: boolean;
+}
+/**
+ * Creates a rate limiter middleware with configurable options.
+ *
+ * @param config - Rate limiting configuration
+ * @returns Express rate limit middleware
+ */
+declare function createRateLimiter(config?: RateLimitConfig): express_rate_limit.RateLimitRequestHandler;
+/**
+ * Default rate limiter for general API routes.
+ * Limits: 100 requests per 15 minutes per IP
+ */
+declare const defaultRateLimiter: express_rate_limit.RateLimitRequestHandler;
+/**
+ * Strict rate limiter for authentication and sensitive endpoints.
+ * Limits: 5 requests per 15 minutes per IP
+ */
+declare const strictRateLimiter: express_rate_limit.RateLimitRequestHandler;
+/**
+ * Lenient rate limiter for public pages.
+ * Limits: 200 requests per 15 minutes per IP
+ */
+declare const lenientRateLimiter: express_rate_limit.RateLimitRequestHandler;
+
+type LogLevel = "fatal" | "error" | "warn" | "info" | "debug" | "trace";
+interface LoggerContext {
+    [key: string]: unknown;
+}
+interface LoggerOptions {
+    level?: LogLevel;
+    enabled?: boolean;
+    pretty?: boolean;
+    destination?: pino.DestinationStream;
+}
+/**
+ * Gets or creates the singleton logger instance.
+ */
+declare function getLogger(options?: LoggerOptions): Logger$1;
+/**
+ * Sets a custom logger instance (useful for testing or custom configuration).
+ */
+declare function setLogger(customLogger: Logger$1): void;
+/**
+ * Resets the logger instance (useful for testing).
+ */
+declare function resetLogger(): void;
+/**
+ * Logger class wrapper for easier usage with context.
+ */
+declare class Logger {
+    private pino;
+    private context;
+    constructor(logger?: Logger$1, context?: LoggerContext);
+    /**
+     * Creates a child logger with additional context.
+     */
+    child(context: LoggerContext): Logger;
+    /**
+     * Logs a fatal error (application should terminate).
+     */
+    fatal(message: string, context?: LoggerContext): void;
+    /**
+     * Logs an error.
+     */
+    error(message: string, error?: Error | unknown, context?: LoggerContext): void;
+    /**
+     * Logs a warning.
+     */
+    warn(message: string, context?: LoggerContext): void;
+    /**
+     * Logs informational message.
+     */
+    info(message: string, context?: LoggerContext): void;
+    /**
+     * Logs a debug message (only in development or when level is debug).
+     */
+    debug(message: string, context?: LoggerContext): void;
+    /**
+     * Logs a trace message (most verbose).
+     */
+    trace(message: string, context?: LoggerContext): void;
+}
+/**
+ * Default logger instance.
+ */
+declare const logger: Logger;
+/**
+ * Creates a logger for a specific module/component.
+ */
+declare function createModuleLogger(module: string, context?: LoggerContext): Logger;
+/**
+ * Generates a unique request ID for request tracking.
+ */
+declare function generateRequestId(): string;
+/**
+ * Express middleware for request logging.
+ * Adds request ID to res.locals and logs incoming requests.
+ */
+declare function requestLoggerMiddleware(options?: {
+    logger?: Logger;
+    logRequests?: boolean;
+    logResponses?: boolean;
+    ignorePaths?: (string | RegExp)[];
+    logStaticAssets?: boolean;
+}): (req: Request, res: Response, next: () => void) => void;
+/**
+ * Gets the logger from the request object (set by requestLoggerMiddleware).
+ */
+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 };