@ecopages/core 0.2.0-alpha.1

package/src/errors/http-error.js

@@ -0,0 +1,50 @@
+class HttpError extends Error {
+  status;
+  details;
+  constructor(status, message, details) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.details = details;
+  }
+  /**
+   * Serialize error to JSON for API responses.
+   */
+  toJSON() {
+    const json = {
+      error: this.message,
+      status: this.status
+    };
+    if (this.details) {
+      json.details = this.details;
+    }
+    return json;
+  }
+  /**
+   * Create a Response object from this error.
+   */
+  toResponse() {
+    return Response.json(this.toJSON(), { status: this.status });
+  }
+  static BadRequest(message = "Bad Request", details) {
+    return new HttpError(400, message, details);
+  }
+  static Unauthorized(message = "Unauthorized") {
+    return new HttpError(401, message);
+  }
+  static Forbidden(message = "Forbidden") {
+    return new HttpError(403, message);
+  }
+  static NotFound(message = "Not Found") {
+    return new HttpError(404, message);
+  }
+  static Conflict(message = "Conflict", details) {
+    return new HttpError(409, message, details);
+  }
+  static InternalServerError(message = "Internal Server Error") {
+    return new HttpError(500, message);
+  }
+}
+export {
+  HttpError
+};

package/src/errors/http-error.ts

@@ -0,0 +1,72 @@
+export interface HttpErrorDetails {
+	[key: string]: unknown;
+}
+
+export interface HttpErrorJson {
+	error: string;
+	status: number;
+	details?: HttpErrorDetails;
+}
+
+/**
+ * HTTP error class for structured error handling in route handlers.
+ * Provides static factory methods for common HTTP error responses.
+ */
+export class HttpError extends Error {
+	readonly status: number;
+	readonly details?: HttpErrorDetails;
+
+	constructor(status: number, message: string, details?: HttpErrorDetails) {
+		super(message);
+		this.name = 'HttpError';
+		this.status = status;
+		this.details = details;
+	}
+
+	/**
+	 * Serialize error to JSON for API responses.
+	 */
+	toJSON(): HttpErrorJson {
+		const json: HttpErrorJson = {
+			error: this.message,
+			status: this.status,
+		};
+
+		if (this.details) {
+			json.details = this.details;
+		}
+
+		return json;
+	}
+
+	/**
+	 * Create a Response object from this error.
+	 */
+	toResponse(): Response {
+		return Response.json(this.toJSON(), { status: this.status });
+	}
+
+	static BadRequest(message = 'Bad Request', details?: HttpErrorDetails): HttpError {
+		return new HttpError(400, message, details);
+	}
+
+	static Unauthorized(message = 'Unauthorized'): HttpError {
+		return new HttpError(401, message);
+	}
+
+	static Forbidden(message = 'Forbidden'): HttpError {
+		return new HttpError(403, message);
+	}
+
+	static NotFound(message = 'Not Found'): HttpError {
+		return new HttpError(404, message);
+	}
+
+	static Conflict(message = 'Conflict', details?: HttpErrorDetails): HttpError {
+		return new HttpError(409, message, details);
+	}
+
+	static InternalServerError(message = 'Internal Server Error'): HttpError {
+		return new HttpError(500, message);
+	}
+}

package/src/errors/index.d.ts

@@ -0,0 +1,2 @@
+export { HttpError } from './http-error.js';
+export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';

package/src/errors/index.js

@@ -0,0 +1,4 @@
+import { HttpError } from "./http-error.js";
+export {
+  HttpError
+};

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export { HttpError } from './http-error.ts';
+export type { HttpErrorDetails, HttpErrorJson } from './http-error.ts';

package/src/errors/locals-access-error.d.ts

@@ -0,0 +1,4 @@
+export declare class LocalsAccessError extends Error {
+    name: string;
+    constructor(message: string);
+}

package/src/errors/locals-access-error.js

@@ -0,0 +1,9 @@
+class LocalsAccessError extends Error {
+  name = "LocalsAccessError";
+  constructor(message) {
+    super(message);
+  }
+}
+export {
+  LocalsAccessError
+};

package/src/errors/locals-access-error.ts

@@ -0,0 +1,7 @@
+export class LocalsAccessError extends Error {
+	override name = 'LocalsAccessError';
+
+	constructor(message: string) {
+		super(message);
+	}
+}

package/src/global/app-logger.d.ts

@@ -0,0 +1,2 @@
+import { Logger } from '@ecopages/logger';
+export declare const appLogger: Logger;

package/src/global/app-logger.js

@@ -0,0 +1,6 @@
+import { Logger } from "@ecopages/logger";
+const debug = process.env.ECOPAGES_LOGGER_DEBUG === "true";
+const appLogger = new Logger("[@ecopages/core]", { debug });
+export {
+  appLogger
+};

package/src/global/app-logger.ts

@@ -0,0 +1,4 @@
+import { Logger } from '@ecopages/logger';
+
+const debug = process.env.ECOPAGES_LOGGER_DEBUG === 'true';
+export const appLogger = new Logger('[@ecopages/core]', { debug });

package/src/hmr/client/hmr-runtime.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Ecopages HMR Runtime
+ * Injected into the browser to handle Hot Module Replacement updates.
+ */
+interface HMRPayload {
+    type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
+    path?: string;
+    message?: string;
+    timestamp?: number;
+}

package/src/hmr/client/hmr-runtime.js

@@ -0,0 +1,86 @@
+(function() {
+  const WS_URL = "ws://" + location.host + "/_hmr";
+  let socket;
+  let reconnectAttempts = 0;
+  function connect() {
+    socket = new WebSocket(WS_URL);
+    socket.addEventListener("open", () => {
+      console.log("[ecopages] HMR Connected");
+      reconnectAttempts = 0;
+    });
+    socket.addEventListener("message", async (event) => {
+      try {
+        const payload = JSON.parse(event.data);
+        handleMessage(payload);
+      } catch (e) {
+        console.error("[ecopages] Invalid HMR message:", e);
+      }
+    });
+    socket.addEventListener("close", () => {
+      if (reconnectAttempts < 10) {
+        setTimeout(connect, 1e3 * 2 ** reconnectAttempts);
+        reconnectAttempts++;
+      }
+    });
+  }
+  async function handleMessage(payload) {
+    switch (payload.type) {
+      case "reload":
+        location.reload();
+        break;
+      case "layout-update": {
+        const reloadFn = window.__ecopages_reload_current_page__;
+        if (typeof reloadFn === "function") {
+          await reloadFn({ clearCache: true });
+        } else {
+          location.reload();
+        }
+        break;
+      }
+      case "error":
+        console.error("[ecopages] HMR Error:", payload.message);
+        break;
+      case "update":
+        if (payload.path) {
+          await applyUpdate(payload.path, payload.timestamp);
+        }
+        break;
+      case "css-update":
+        if (payload.path) {
+          refreshStylesheet(payload.path);
+        }
+        break;
+    }
+  }
+  async function applyUpdate(path, timestamp) {
+    try {
+      const url = path + "?t=" + (timestamp || Date.now());
+      const handlers = window.__ecopages_hmr_handlers__;
+      if (handlers?.[path]) {
+        await handlers[path](url);
+        return;
+      }
+      await import(url);
+      const reloadFn = window.__ecopages_reload_current_page__;
+      if (typeof reloadFn === "function") {
+        await reloadFn({ clearCache: false });
+      }
+    } catch (e) {
+      console.error("[ecopages] Failed to apply HMR update:", e);
+    }
+  }
+  function refreshStylesheet(path) {
+    const filename = path.split("/").pop() || "";
+    const links = document.querySelectorAll('link[rel="stylesheet"]');
+    links.forEach((link) => {
+      const href = link.href;
+      if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, "/assets/"))) {
+        const url = new URL(href, location.origin);
+        url.searchParams.set("t", Date.now().toString());
+        link.href = url.toString();
+        console.log("[ecopages] CSS updated:", filename);
+      }
+    });
+  }
+  connect();
+})();

package/src/hmr/client/hmr-runtime.ts

@@ -0,0 +1,121 @@
+/**
+ * Ecopages HMR Runtime
+ * Injected into the browser to handle Hot Module Replacement updates.
+ */
+
+interface HMRPayload {
+	type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
+	path?: string;
+	message?: string;
+	timestamp?: number;
+}
+
+(function () {
+	const WS_URL = 'ws://' + location.host + '/_hmr';
+	let socket: WebSocket;
+	let reconnectAttempts = 0;
+
+	function connect() {
+		socket = new WebSocket(WS_URL);
+
+		socket.addEventListener('open', () => {
+			console.log('[ecopages] HMR Connected');
+			reconnectAttempts = 0;
+		});
+
+		socket.addEventListener('message', async (event) => {
+			try {
+				const payload: HMRPayload = JSON.parse(event.data);
+				handleMessage(payload);
+			} catch (e) {
+				console.error('[ecopages] Invalid HMR message:', e);
+			}
+		});
+
+		socket.addEventListener('close', () => {
+			if (reconnectAttempts < 10) {
+				setTimeout(connect, 1000 * 2 ** reconnectAttempts);
+				reconnectAttempts++;
+			}
+		});
+	}
+
+	async function handleMessage(payload: HMRPayload) {
+		switch (payload.type) {
+			case 'reload':
+				location.reload();
+				break;
+			case 'layout-update': {
+				const reloadFn = window.__ecopages_reload_current_page__;
+				if (typeof reloadFn === 'function') {
+					await reloadFn({ clearCache: true });
+				} else {
+					location.reload();
+				}
+				break;
+			}
+			case 'error':
+				console.error('[ecopages] HMR Error:', payload.message);
+				break;
+			case 'update':
+				if (payload.path) {
+					await applyUpdate(payload.path, payload.timestamp);
+				}
+				break;
+			case 'css-update':
+				if (payload.path) {
+					refreshStylesheet(payload.path);
+				}
+				break;
+		}
+	}
+
+	/**
+	 * Applies a module update by calling registered HMR handlers or re-importing the module.
+	 * @param path - The module path to update
+	 * @param timestamp - Optional timestamp for cache busting
+	 */
+	async function applyUpdate(path: string, timestamp?: number) {
+		try {
+			const url = path + '?t=' + (timestamp || Date.now());
+			const handlers = window.__ecopages_hmr_handlers__;
+
+			if (handlers?.[path]) {
+				await handlers[path](url);
+				return;
+			}
+
+			await import(url);
+
+			// If we're inside the EcoRouter, we need to trigger a router navigation to render the new component.
+			// Passing clearCache: false preserves the persisted layout cache.
+			const reloadFn = window.__ecopages_reload_current_page__;
+			if (typeof reloadFn === 'function') {
+				await reloadFn({ clearCache: false });
+			}
+		} catch (e) {
+			console.error('[ecopages] Failed to apply HMR update:', e);
+		}
+	}
+
+	/**
+	 * Hot-reload CSS by updating stylesheet link href with cache-busting query param.
+	 * This causes the browser to re-fetch the stylesheet without a full page reload.
+	 */
+	function refreshStylesheet(path: string) {
+		const filename = path.split('/').pop() || '';
+		const links = document.querySelectorAll('link[rel="stylesheet"]');
+
+		links.forEach((link) => {
+			const href = (link as HTMLLinkElement).href;
+			if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, '/assets/'))) {
+				const url = new URL(href, location.origin);
+				url.searchParams.set('t', Date.now().toString());
+				(link as HTMLLinkElement).href = url.toString();
+				console.log('[ecopages] CSS updated:', filename);
+			}
+		});
+	}
+
+	connect();
+})();

package/src/hmr/hmr-strategy.d.ts

@@ -0,0 +1,159 @@
+import type { ClientBridgeEvent } from '../public-types';
+/**
+ * HMR Strategy Pattern
+ *
+ * This module defines the base classes and types for Hot Module Replacement strategies.
+ * Each strategy handles a specific type of file change and determines how to process it.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * class CustomHmrStrategy extends HmrStrategy {
+ *   readonly type = HmrStrategyType.INTEGRATION;
+ *
+ *   matches(filePath: string): boolean {
+ *     return filePath.endsWith('.custom');
+ *   }
+ *
+ *   async process(filePath: string): Promise<HmrAction> {
+ *     return {
+ *       type: 'broadcast',
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
+ *     };
+ *   }
+ * }
+
+ * Defines the category of an HMR strategy, which determines its execution priority.
+ * Strategies are evaluated in descending order: INTEGRATION → ASSET → SCRIPT → FALLBACK.
+ *
+ * @remarks
+ * The numeric values represent base priorities. Strategies can fine-tune their priority
+ * using the `priorityOffset` property.
+ */
+export declare enum HmrStrategyType {
+    /**
+     * Integration-specific strategies (React, Lit, etc.)
+     * Highest priority to allow framework-specific HMR handling.
+     */
+    INTEGRATION = 100,
+    /**
+     * Asset processing strategies (CSS, images, etc.)
+     * High priority for specialized asset handling.
+     */
+    ASSET = 50,
+    /**
+     * Generic script bundling strategies (JS/TS)
+     * Medium priority for standard script processing.
+     */
+    SCRIPT = 25,
+    /**
+     * Fallback strategy for unhandled file types.
+     * Lowest priority, triggers full page reload.
+     */
+    FALLBACK = 0
+}
+/**
+ * Represents an action to be taken after processing a file change.
+ */
+export interface HmrAction {
+    /**
+     * Whether to broadcast an HMR event to connected clients.
+     */
+    type: 'broadcast' | 'none';
+    /**
+     * The HMR events to broadcast, if type is 'broadcast'.
+     * capable of broadcasting multiple events at once.
+     */
+    events?: ClientBridgeEvent[];
+}
+/**
+ * Base class for HMR strategies.
+ *
+ * Each strategy handles a specific type of file change and determines how to process it.
+ * Strategies are selected based on their priority (higher values are evaluated first) and
+ * whether they match the changed file path.
+ *
+ * @remarks
+ * Strategies should be stateless and idempotent. The same file change should always
+ * produce the same result when processed by the same strategy.
+ *
+ * @example
+ * ```typescript
+ * class MyAssetStrategy extends HmrStrategy {
+ *   readonly type = HmrStrategyType.ASSET;
+ *   readonly priorityOffset = 5;
+ *
+ *   matches(filePath: string): boolean {
+ *     return /\.(png|jpg|svg)$/.test(filePath);
+ *   }
+ *
+ *   async process(filePath: string): Promise<HmrAction> {
+ *     await this.optimizeImage(filePath);
+ *     return {
+ *       type: 'broadcast',
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class HmrStrategy {
+    /**
+     * The category of this strategy, determining its base priority.
+     */
+    abstract readonly type: HmrStrategyType;
+    /**
+     * Optional offset to fine-tune priority within the same category.
+     * Useful when multiple strategies share the same type.
+     *
+     * @defaultValue 0
+     */
+    readonly priorityOffset: number;
+    /**
+     * Computed priority for strategy selection.
+     * Higher values are evaluated first.
+     *
+     * @returns The sum of the strategy type and priority offset
+     */
+    get priority(): number;
+    /**
+     * Determines if this strategy can handle the given file path.
+     *
+     * @param filePath - Absolute path to the changed file
+     * @returns True if this strategy should process the file
+     *
+     * @example
+     * ```typescript
+     * matches(filePath: string): boolean {
+     *   return filePath.endsWith('.css');
+     * }
+     * ```
+     */
+    abstract matches(filePath: string): boolean;
+    /**
+     * Processes a file change and returns the action to take.
+     *
+     * This method may perform side effects such as:
+     * - Rebuilding files
+     * - Writing to disk
+     * - Transforming code
+     * - Updating caches
+     *
+     * @param filePath - Absolute path to the changed file
+     * @returns Action to take (broadcast event or none)
+     *
+     * @example
+     * ```typescript
+     * async process(filePath: string): Promise<HmrAction> {
+     *   const processed = await this.transform(filePath);
+     *   await Bun.write(outputPath, processed);
+     *
+     *   return {
+     *     type: 'broadcast',
+     *     events: [{ type: 'update', path: outputPath, timestamp: Date.now() }]
+     *   };
+     * }
+     * ```
+     */
+    abstract process(filePath: string): Promise<HmrAction>;
+}

package/src/hmr/hmr-strategy.js

@@ -0,0 +1,29 @@
+var HmrStrategyType = /* @__PURE__ */ ((HmrStrategyType2) => {
+  HmrStrategyType2[HmrStrategyType2["INTEGRATION"] = 100] = "INTEGRATION";
+  HmrStrategyType2[HmrStrategyType2["ASSET"] = 50] = "ASSET";
+  HmrStrategyType2[HmrStrategyType2["SCRIPT"] = 25] = "SCRIPT";
+  HmrStrategyType2[HmrStrategyType2["FALLBACK"] = 0] = "FALLBACK";
+  return HmrStrategyType2;
+})(HmrStrategyType || {});
+class HmrStrategy {
+  /**
+   * Optional offset to fine-tune priority within the same category.
+   * Useful when multiple strategies share the same type.
+   *
+   * @defaultValue 0
+   */
+  priorityOffset = 0;
+  /**
+   * Computed priority for strategy selection.
+   * Higher values are evaluated first.
+   *
+   * @returns The sum of the strategy type and priority offset
+   */
+  get priority() {
+    return this.type + this.priorityOffset;
+  }
+}
+export {
+  HmrStrategy,
+  HmrStrategyType
+};