httpath 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,382 @@
+import * as http0 from "http";
+import { IncomingMessage, ServerResponse } from "node:http";
+import "fs";
+import { EventEmitter } from "node:events";
+
+//#region src/types/index.d.mts
+interface ServerConfig {
+  port: number;
+  rootPath: string;
+  reload: boolean;
+  ignorePatterns?: string[];
+  enableDirectoryListing?: boolean;
+  restartOnChange?: boolean;
+  logLevel?: LogLevel;
+  debounceMs?: number;
+}
+interface HttpRequest extends IncomingMessage {
+  url: string;
+  method: string;
+}
+interface HttpResponse extends ServerResponse {
+  writeHead(statusCode: number, headers?: Record<string, string>): void;
+  end(chunk?: string): void;
+  write(chunk: string): void;
+}
+interface HotReloadOptions {
+  watchPath: string;
+  ignored?: string[];
+  debounceMs?: number;
+  restartOnChange?: boolean;
+}
+interface ReloadEvent {
+  type: "file-changed" | "directory-changed" | "file-added" | "file-removed";
+  path: string;
+  timestamp: Date;
+}
+interface ServerInstance {
+  port: number;
+  server: http0.Server;
+  config: ServerConfig;
+  stop: () => Promise<void>;
+}
+interface PortFinderOptions {
+  startPort: number;
+  endPort?: number;
+  timeout?: number;
+}
+type LogLevel = "debug" | "info" | "warn" | "error";
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: Date;
+  method?: string;
+  url?: string;
+  statusCode?: number;
+  responseTime?: number;
+}
+interface LoggerOptions {
+  level: LogLevel;
+  format?: "simple" | "json" | "detailed";
+  includeTimestamp?: boolean;
+  colorize?: boolean;
+}
+interface Success<T> {
+  readonly success: true;
+  readonly data: T;
+  readonly error?: never;
+}
+interface Failure<E = Error> {
+  readonly success: false;
+  readonly data?: never;
+  readonly error: E;
+}
+type Result<T, E = Error> = Success<T> | Failure<E>;
+//#endregion
+//#region src/config/cli.d.mts
+/**
+ * Version information
+ */
+declare const VERSION_INFO: {
+  readonly name: "HTTPath";
+  readonly version: "0.1.0";
+  readonly description: "A minimalist Node.js file server with hot-reload capabilities";
+  readonly author: "José Martínez Santana";
+  readonly license: "MIT";
+};
+/**
+ * Parse CLI arguments into ServerConfig
+ * @param argv - Array of command-line arguments
+ * @returns Result containing ServerConfig or error
+ * @description
+ * This function uses Node.js's built-in parseArgs utility to parse command-line arguments based on predefined options.
+ */
+declare const parseCliArgs: (argv?: string[]) => Result<ServerConfig>;
+/**
+ * Validate server configuration
+ * @param config - Server configuration to validate
+ * @returns boolean indicating if the configuration is valid
+ * @description
+ * This function checks the validity of the server configuration. It ensures that the port number is within the valid range (1-65535),
+ * the root path is a non-empty string, and the reload flag is a boolean. If any of these checks fail, it logs an error message and returns false. Otherwise, it returns true.
+ */
+declare const validateConfig: (config: ServerConfig) => boolean;
+//#endregion
+//#region src/services/server.d.mts
+/**
+ * HTTP Server service class
+ */
+declare class HTTPServer {
+  private server;
+  private config;
+  private hotReload;
+  private logger;
+  private isRunning;
+  constructor(config: ServerConfig);
+  /**
+   * Start the HTTP server
+   * @returns ServerInstance object with server details
+   */
+  start(): Promise<ServerInstance>;
+  /**
+   * Stop the HTTP server
+   * @returns Promise that resolves when the server is stopped
+   */
+  stop(): Promise<void>;
+  /**
+   * Handle incoming HTTP requests
+   * @param req - Incoming HTTP request
+   * @param res - HTTP response to send data
+   * @returns Promise that resolves when the request is handled
+   */
+  private handleRequest;
+  /**
+   * Handle directory requests
+   * @param dirPath - Filesystem path of the directory
+   * @param urlPath - URL path requested
+   * @param res - HTTP response to send data
+   * @returns Promise that resolves when the directory request is handled
+   */
+  private handleDirectoryRequest;
+  /**
+   * Handle file requests
+   * @param filePath - Filesystem path of the file
+   * @param res - HTTP response to send data
+   * @returns Promise that resolves when the file request is handled
+   */
+  private handleFileRequest;
+  /**
+   * Send error response
+   * @param res - HTTP response
+   * @param statusCode - HTTP status code
+   * @param statusText - HTTP status text
+   * @returns {void}
+   */
+  private sendError;
+  /**
+   * Generate error page HTML
+   * @param statusCode - HTTP status code
+   * @param statusText - HTTP status text
+   * @returns HTML string for the error page
+   */
+  private generateErrorPage;
+}
+/**
+ * Create HTTP server instance
+ * @param config - Server configuration
+ * @returns HTTPServer instance
+ */
+declare const createHTTPServer: (config: ServerConfig) => HTTPServer;
+//#endregion
+//#region src/utils/logger.d.mts
+/**
+ * Logger class for handling application logging
+ */
+declare class Logger {
+  private options;
+  private startTime;
+  constructor(options?: LoggerOptions);
+  /**
+   * Log debug message
+   */
+  debug(message: string, ...args: any[]): void;
+  /**
+   * Log info message
+   */
+  info(message: string, ...args: any[]): void;
+  /**
+   * Log warning message
+   */
+  warn(message: string, ...args: any[]): void;
+  /**
+   * Log error message
+   */
+  error(message: string, ...args: any[]): void;
+  /**
+   * Log HTTP request
+   */
+  logRequest(method: string, url: string, userAgent?: string): void;
+  /**
+   * Log HTTP response
+   */
+  logResponse(statusCode: number, responseTime?: number): void;
+  /**
+   * Create a log entry object
+   */
+  createLogEntry(level: LogLevel, message: string, meta?: Record<string, any>): LogEntry;
+  /**
+   * Set log level
+   */
+  setLevel(level: LogLevel): void;
+  /**
+   * Get current log level
+   */
+  getLevel(): LogLevel;
+  /**
+   * Check if a log level should be output
+   */
+  shouldLog(level: LogLevel): boolean;
+  /**
+   * Get server uptime
+   */
+  getUptime(): number;
+  /**
+   * Format uptime as human readable string
+   */
+  formatUptime(): string;
+  /**
+   * Core logging method
+   */
+  private log;
+  /**
+   * Write log to console
+   */
+  private writeLog;
+  /**
+   * Format message with arguments
+   */
+  private formatMessage;
+  /**
+   * Format timestamp
+   */
+  private formatTimestamp;
+  /**
+   * Apply color to text if colorization is enabled
+   */
+  private colorize;
+  /**
+   * Get color for HTTP status code
+   */
+  private getStatusColor;
+}
+/**
+ * Create a new logger instance
+ */
+declare const createLogger: (options?: LoggerOptions) => Logger;
+//#endregion
+//#region src/utils/port-finder.d.mts
+/**
+ * Find a single available port within a specified range
+ * @param options - PortFinderOptions to specify range and timeout
+ * @returns Promise resolving to Result<number> with the available port number or error
+ * @description
+ * This function iterates through the specified port range, checking each port's availability.
+ * It returns the first available port found. If no ports are available in the range,
+ * it returns an error indicating the failure.
+ */
+declare const findAvailablePort: (options?: Partial<PortFinderOptions>) => Promise<Result<number>>;
+//#endregion
+//#region src/services/hot-reload.d.mts
+/**
+ * HotReloadService class
+ * Manages hot-reload functionality for development environments
+ */
+declare class HotReloadService extends EventEmitter {
+  private watcher;
+  private clients;
+  private options;
+  private debounceTimer;
+  constructor(options?: HotReloadOptions);
+  /**
+   * Start watching for file changes
+   * @returns Result indicating success or failure of starting the watcher
+   */
+  start(): Result<void>;
+  /**
+   * Stop watching for file changes
+   * @description Stops the file system watcher and cleans up resources
+   */
+  stop(): void;
+  /**
+   * Handle new SSE connection from client
+   * @param req - HTTP request
+   * @param res - HTTP response
+   */
+  handleSSEConnection(req: HttpRequest, res: HttpResponse): void;
+  /**
+   * Broadcast reload signal to all connected clients
+   * @param event - Optional reload event details
+   * @returns {void}
+   */
+  broadcastReload(event?: ReloadEvent): void;
+  /**
+   * Inject hot-reload script into HTML content
+   * @param htmlContent - HTML content to inject script into
+   * @returns HTML content with injected hot-reload script
+   */
+  injectScript(htmlContent: string): string;
+  /**
+   * Get number of connected clients
+   * @returns {number} Number of connected clients
+   */
+  getClientCount(): number;
+  /**
+   * Get information about connected clients
+   * @returns Array of client info objects
+   */
+  getClientInfo(): Array<{
+    id: string;
+    connectedAt: Date;
+  }>;
+  /**
+   * Handle file change events
+   * @param eventType - Type of file system event
+   * @param filename - Name of the changed file
+   * @returns {void}
+   */
+  private handleFileChange;
+  /**
+   * Check if a file should be ignored based on configured ignored patterns
+   * @param filename - Name of the file to check
+   * @returns boolean indicating if file should be ignored
+   */
+  private shouldIgnoreFile;
+  /**
+   * Map fs.watch event type to ReloadEvent type
+   * @param eventType - Event type from fs.watch
+   * @returns Corresponding ReloadEvent type
+   */
+  private getEventType;
+  /**
+   * Decide if any of the given paths should trigger a server restart
+   * @param paths - Array of changed file paths
+   * @returns {boolean} indicating if server should restart
+   */
+  private shouldRestartServer;
+  /**
+   * Decide if any of the given paths should trigger a browser reload
+   * @param paths - Array of changed file paths
+   * @returns {boolean} indicating if browser should reload
+   */
+  private shouldTriggerBrowserReload;
+  /**
+   * Restart the current Node.js process
+   * @returns {void}
+   */
+  private restartProcess;
+  /**
+   * Generate a unique client ID
+   * @returns string representing the unique client ID
+   */
+  private generateClientId;
+  /**
+   * Remove a client by ID
+   * @param clientId - ID of the client to remove
+   * @returns {void}
+   */
+  private removeClient;
+}
+/**
+ * Create and return a HotReloadService instance
+ * @param options - Hot-reload options
+ * @returns HotReloadService instance
+ */
+declare const createHotReloadService: (options?: HotReloadOptions) => HotReloadService;
+//#endregion
+//#region src/index.d.mts
+/**
+ * Main application function
+ */
+declare const main: () => Promise<void>;
+//#endregion
+export { type HotReloadOptions, type LoggerOptions, type ServerConfig, type ServerInstance, VERSION_INFO, createHTTPServer, createHotReloadService, createLogger, findAvailablePort, main, parseCliArgs, validateConfig };