@techstream/quark-core 1.1.0

package/src/error-reporter.test.js

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import {
+	createSentryAdapter,
+	ErrorReporter,
+	errorReporter,
+} from "./error-reporter.js";
+
+describe("ErrorReporter", () => {
+	/** @type {ErrorReporter} */
+	let reporter;
+
+	beforeEach(() => {
+		reporter = new ErrorReporter();
+	});
+
+	describe("default instance", () => {
+		it("has console adapter registered by default", () => {
+			assert.equal(reporter.adapters.length, 1);
+			assert.equal(reporter.adapters[0].name, "console");
+		});
+
+		it("global singleton has console adapter", () => {
+			const names = errorReporter.adapters.map((a) => a.name);
+			assert.ok(names.includes("console"));
+		});
+	});
+
+	describe("use()", () => {
+		it("adds an adapter", () => {
+			const adapter = { name: "test", report: () => {} };
+			reporter.use(adapter);
+			assert.equal(reporter.adapters.length, 2);
+			assert.equal(reporter.adapters[1].name, "test");
+		});
+
+		it("throws if adapter has no name", () => {
+			assert.throws(() => reporter.use({ report: () => {} }), /name/);
+		});
+
+		it("throws if adapter has no report function", () => {
+			assert.throws(() => reporter.use({ name: "bad" }), /report/);
+		});
+	});
+
+	describe("report()", () => {
+		it("calls all registered adapters", () => {
+			const calls = [];
+			const adapter1 = {
+				name: "a1",
+				report: (err, ctx) => calls.push({ adapter: "a1", err, ctx }),
+			};
+			const adapter2 = {
+				name: "a2",
+				report: (err, ctx) => calls.push({ adapter: "a2", err, ctx }),
+			};
+
+			reporter.use(adapter1);
+			reporter.use(adapter2);
+
+			const error = new Error("test error");
+			reporter.report(error, { requestId: "123" });
+
+			// console adapter + 2 custom = 3 calls
+			assert.equal(calls.length, 2);
+			assert.equal(calls[0].adapter, "a1");
+			assert.equal(calls[1].adapter, "a2");
+			assert.equal(calls[0].err, error);
+			assert.equal(calls[0].ctx.requestId, "123");
+		});
+
+		it("swallows adapter errors without throwing", () => {
+			const failAdapter = {
+				name: "fail",
+				report: () => {
+					throw new Error("adapter crash");
+				},
+			};
+			reporter.use(failAdapter);
+
+			assert.doesNotThrow(() => reporter.report(new Error("test")));
+		});
+	});
+
+	describe("captureMessage()", () => {
+		it("calls adapters that support captureMessage", () => {
+			const messages = [];
+			const adapter = {
+				name: "msg",
+				report: () => {},
+				captureMessage: (msg, level, ctx) => messages.push({ msg, level, ctx }),
+			};
+			reporter.use(adapter);
+
+			reporter.captureMessage("hello", "warn", { extra: true });
+
+			assert.equal(messages.length, 1);
+			assert.equal(messages[0].msg, "hello");
+			assert.equal(messages[0].level, "warn");
+			assert.equal(messages[0].ctx.extra, true);
+		});
+
+		it("skips adapters without captureMessage", () => {
+			const adapter = { name: "no-msg", report: () => {} };
+			reporter.use(adapter);
+
+			assert.doesNotThrow(() => reporter.captureMessage("hello"));
+		});
+	});
+
+	describe("setUser()", () => {
+		it("includes user in subsequent reports", () => {
+			const reported = [];
+			const adapter = {
+				name: "user-test",
+				report: (_err, ctx) => reported.push(ctx),
+			};
+			reporter.use(adapter);
+
+			reporter.setUser({ id: "u1", email: "a@b.com" });
+			reporter.report(new Error("test"));
+
+			assert.equal(reported.length, 1);
+			assert.deepEqual(reported[0].user, { id: "u1", email: "a@b.com" });
+		});
+
+		it("forwards user to adapters with setUser", () => {
+			let receivedUser = null;
+			const adapter = {
+				name: "user-fwd",
+				report: () => {},
+				setUser: (u) => {
+					receivedUser = u;
+				},
+			};
+			reporter.use(adapter);
+
+			reporter.setUser({ id: "u2" });
+			assert.deepEqual(receivedUser, { id: "u2" });
+		});
+	});
+
+	describe("addBreadcrumb()", () => {
+		it("stores breadcrumbs and attaches them to report context", () => {
+			const reported = [];
+			const adapter = {
+				name: "bc-test",
+				report: (_err, ctx) => reported.push(ctx),
+			};
+			reporter.use(adapter);
+
+			reporter.addBreadcrumb("clicked button", "ui", { buttonId: "submit" });
+			reporter.addBreadcrumb("navigated", "navigation");
+			reporter.report(new Error("test"));
+
+			assert.equal(reported.length, 1);
+			assert.equal(reported[0].breadcrumbs.length, 2);
+			assert.equal(reported[0].breadcrumbs[0].message, "clicked button");
+			assert.equal(reported[0].breadcrumbs[0].category, "ui");
+			assert.deepEqual(reported[0].breadcrumbs[0].data, { buttonId: "submit" });
+			assert.equal(reported[0].breadcrumbs[1].message, "navigated");
+			assert.equal(reported[0].breadcrumbs[1].category, "navigation");
+			assert.ok(reported[0].breadcrumbs[0].timestamp);
+		});
+
+		it("circular buffer keeps max 50 breadcrumbs", () => {
+			for (let i = 0; i < 60; i++) {
+				reporter.addBreadcrumb(`crumb-${i}`, "test");
+			}
+
+			const crumbs = reporter.breadcrumbs;
+			assert.equal(crumbs.length, 50);
+			// First 10 should have been evicted, first remaining is crumb-10
+			assert.equal(crumbs[0].message, "crumb-10");
+			assert.equal(crumbs[49].message, "crumb-59");
+		});
+
+		it("forwards breadcrumbs to adapters that support it", () => {
+			const received = [];
+			const adapter = {
+				name: "bc-fwd",
+				report: () => {},
+				addBreadcrumb: (msg, cat, data) => received.push({ msg, cat, data }),
+			};
+			reporter.use(adapter);
+
+			reporter.addBreadcrumb("test", "cat", { key: "val" });
+
+			assert.equal(received.length, 1);
+			assert.equal(received[0].msg, "test");
+			assert.equal(received[0].cat, "cat");
+			assert.deepEqual(received[0].data, { key: "val" });
+		});
+	});
+
+	describe("custom adapter receives correct data", () => {
+		it("passes error and enriched context", () => {
+			const reported = [];
+			const adapter = {
+				name: "custom",
+				report: (err, ctx) => reported.push({ err, ctx }),
+			};
+			reporter.use(adapter);
+
+			reporter.setUser({ id: "u1" });
+			reporter.addBreadcrumb("init", "app");
+
+			const error = new Error("custom test");
+			reporter.report(error, { route: "/api/test" });
+
+			assert.equal(reported.length, 1);
+			assert.equal(reported[0].err, error);
+			assert.equal(reported[0].ctx.route, "/api/test");
+			assert.deepEqual(reported[0].ctx.user, { id: "u1" });
+			assert.equal(reported[0].ctx.breadcrumbs.length, 1);
+			assert.equal(reported[0].ctx.breadcrumbs[0].message, "init");
+		});
+	});
+
+	describe("createSentryAdapter()", () => {
+		it("returns a valid adapter shape", () => {
+			const adapter = createSentryAdapter();
+			assert.equal(adapter.name, "sentry");
+			assert.equal(typeof adapter.report, "function");
+			assert.equal(typeof adapter.captureMessage, "function");
+			assert.equal(typeof adapter.setUser, "function");
+			assert.equal(typeof adapter.addBreadcrumb, "function");
+		});
+
+		it("can be registered without errors", () => {
+			const adapter = createSentryAdapter();
+			assert.doesNotThrow(() => reporter.use(adapter));
+			assert.doesNotThrow(() => reporter.report(new Error("test")));
+		});
+	});
+});

package/src/errors.js

@@ -0,0 +1,192 @@
+/**
+ * @techstream/quark-core - Error Handling Module
+ * Standardized error types and utilities for consistent error handling
+ */
+
+import { errorReporter } from "./error-reporter.js";
+
+/**
+ * Base application error class
+ */
+export class AppError extends Error {
+	constructor(message, statusCode = 500, code = "INTERNAL_ERROR") {
+		super(message);
+		this.name = this.constructor.name;
+		this.statusCode = statusCode;
+		this.code = code;
+		this.timestamp = new Date().toISOString();
+		Error.captureStackTrace(this, this.constructor);
+	}
+
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			statusCode: this.statusCode,
+			timestamp: this.timestamp,
+		};
+	}
+}
+
+/**
+ * 400 Bad Request Error
+ */
+export class ValidationError extends AppError {
+	constructor(message, details = null) {
+		super(message, 400, "VALIDATION_ERROR");
+		this.details = details;
+	}
+
+	toJSON() {
+		return {
+			...super.toJSON(),
+			details: this.details,
+		};
+	}
+}
+
+/**
+ * 401 Unauthorized Error
+ */
+export class UnauthorizedError extends AppError {
+	constructor(message = "Authentication required") {
+		super(message, 401, "UNAUTHORIZED");
+	}
+}
+
+/**
+ * 403 Forbidden Error
+ */
+export class ForbiddenError extends AppError {
+	constructor(message = "Access denied") {
+		super(message, 403, "FORBIDDEN");
+	}
+}
+
+/**
+ * 404 Not Found Error
+ */
+export class NotFoundError extends AppError {
+	constructor(message = "Resource not found") {
+		super(message, 404, "NOT_FOUND");
+	}
+}
+
+/**
+ * 409 Conflict Error
+ */
+export class ConflictError extends AppError {
+	constructor(message = "Resource conflict") {
+		super(message, 409, "CONFLICT");
+	}
+}
+
+/**
+ * 429 Rate Limit Error
+ */
+export class RateLimitError extends AppError {
+	constructor(message = "Too many requests", retryAfter = 60) {
+		super(message, 429, "RATE_LIMIT");
+		this.retryAfter = retryAfter;
+	}
+
+	toJSON() {
+		return {
+			...super.toJSON(),
+			retryAfter: this.retryAfter,
+		};
+	}
+}
+
+/**
+ * Database Error
+ */
+export class DatabaseError extends AppError {
+	constructor(message = "Database error", originalError = null) {
+		super(message, 500, "DATABASE_ERROR");
+		this.originalError = originalError;
+	}
+}
+
+/**
+ * External Service Error
+ */
+export class ServiceError extends AppError {
+	constructor(serviceName, message = "Service error", statusCode = 502) {
+		super(message, statusCode, "SERVICE_ERROR");
+		this.serviceName = serviceName;
+	}
+
+	toJSON() {
+		return {
+			...super.toJSON(),
+			serviceName: this.serviceName,
+		};
+	}
+}
+
+/**
+ * Safely extracts error message from various error types
+ * @param {Error|string|Object} error - The error to extract from
+ * @returns {string} Extracted error message
+ */
+export const getErrorMessage = (error) => {
+	if (typeof error === "string") return error;
+	if (error instanceof Error) return error.message;
+	if (error && typeof error === "object" && error.message) return error.message;
+	return "An unknown error occurred";
+};
+
+/**
+ * Safely extracts status code from error
+ * @param {Error|AppError} error - The error to extract from
+ * @returns {number} HTTP status code
+ */
+export const getStatusCode = (error) => {
+	if (error instanceof AppError) return error.statusCode;
+	if (error.statusCode) return error.statusCode;
+	return 500;
+};
+
+/**
+ * Converts any error to an AppError instance
+ * @param {Error|AppError|any} error - The error to normalize
+ * @returns {AppError} Normalized error
+ */
+export const normalizeError = (error) => {
+	if (error instanceof AppError) return error;
+	if (error instanceof Error) {
+		return new AppError(error.message, 500, "INTERNAL_ERROR");
+	}
+	return new AppError(
+		typeof error === "string" ? error : "An unknown error occurred",
+		500,
+		"INTERNAL_ERROR",
+	);
+};
+
+/**
+ * Logs error with context
+ * @param {Error} error - The error to log
+ * @param {Object} context - Additional context
+ */
+export const logError = (error, context = {}) => {
+	errorReporter.report(error, context);
+};
+
+/**
+ * Wraps async function and handles errors consistently
+ * @param {Function} fn - Async function to wrap
+ * @returns {Function} Wrapped function
+ */
+export const withErrorHandling = (fn) => {
+	return async (...args) => {
+		try {
+			return await fn(...args);
+		} catch (error) {
+			errorReporter.report(error);
+			throw normalizeError(error);
+		}
+	};
+};

package/src/errors.test.js

@@ -0,0 +1,128 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	AppError,
+	ConflictError,
+	DatabaseError,
+	ForbiddenError,
+	getErrorMessage,
+	getStatusCode,
+	logError,
+	NotFoundError,
+	normalizeError,
+	RateLimitError,
+	ServiceError,
+	UnauthorizedError,
+	ValidationError,
+} from "../src/errors.js";
+
+test("Error Module", async (t) => {
+	await t.test("AppError has correct properties", () => {
+		const error = new AppError("Test error", 500, "TEST_ERROR");
+		assert(error.message === "Test error");
+		assert(error.statusCode === 500);
+		assert(error.code === "TEST_ERROR");
+		assert(error.name === "AppError");
+	});
+
+	await t.test("AppError.toJSON() serializes correctly", () => {
+		const error = new AppError("Test", 500, "TEST");
+		const json = error.toJSON();
+		assert(json.message === "Test");
+		assert(json.statusCode === 500);
+		assert(json.code === "TEST");
+		assert(json.timestamp);
+	});
+
+	await t.test("ValidationError has status 400", () => {
+		const error = new ValidationError("Invalid input");
+		assert(error.statusCode === 400);
+		assert(error.code === "VALIDATION_ERROR");
+	});
+
+	await t.test("UnauthorizedError has status 401", () => {
+		const error = new UnauthorizedError();
+		assert(error.statusCode === 401);
+		assert(error.code === "UNAUTHORIZED");
+	});
+
+	await t.test("ForbiddenError has status 403", () => {
+		const error = new ForbiddenError();
+		assert(error.statusCode === 403);
+		assert(error.code === "FORBIDDEN");
+	});
+
+	await t.test("NotFoundError has status 404", () => {
+		const error = new NotFoundError();
+		assert(error.statusCode === 404);
+		assert(error.code === "NOT_FOUND");
+	});
+
+	await t.test("ConflictError has status 409", () => {
+		const error = new ConflictError();
+		assert(error.statusCode === 409);
+		assert(error.code === "CONFLICT");
+	});
+
+	await t.test("RateLimitError has status 429", () => {
+		const error = new RateLimitError("Too many requests", 60);
+		assert(error.statusCode === 429);
+		assert(error.code === "RATE_LIMIT");
+		assert(error.retryAfter === 60);
+	});
+
+	await t.test("DatabaseError wraps database errors", () => {
+		const originalError = new Error("Connection failed");
+		const error = new DatabaseError("DB error", originalError);
+		assert(error.statusCode === 500);
+		assert(error.originalError === originalError);
+	});
+
+	await t.test("ServiceError includes service name", () => {
+		const error = new ServiceError("PaymentAPI", "Payment failed");
+		assert(error.serviceName === "PaymentAPI");
+		assert(error.statusCode === 502);
+		const json = error.toJSON();
+		assert(json.serviceName === "PaymentAPI");
+	});
+
+	await t.test("getErrorMessage extracts from various types", () => {
+		assert(getErrorMessage("string error") === "string error");
+		assert(getErrorMessage(new Error("error message")) === "error message");
+		assert(getErrorMessage({ message: "obj error" }) === "obj error");
+		assert(getErrorMessage({}).includes("unknown")); // Changed from null to empty object
+	});
+
+	await t.test("getStatusCode returns correct code", () => {
+		assert(getStatusCode(new ValidationError("")) === 400);
+		assert(getStatusCode(new UnauthorizedError()) === 401);
+		assert(getStatusCode(new NotFoundError()) === 404);
+		assert(getStatusCode(new Error()) === 500);
+	});
+
+	await t.test("normalizeError converts to AppError", () => {
+		const error = normalizeError(new Error("test"));
+		assert(error instanceof AppError);
+		assert(error.message === "test");
+		assert(error.statusCode === 500);
+	});
+
+	await t.test("normalizeError handles string errors", () => {
+		const error = normalizeError("string error");
+		assert(error instanceof AppError);
+		assert(error.message === "string error");
+	});
+
+	await t.test("normalizeError handles non-Error objects", () => {
+		const error = normalizeError({ some: "object" });
+		assert(error instanceof AppError);
+		assert(error.message.includes("unknown"));
+	});
+
+	await t.test("logError handles errors with context", () => {
+		// This should not throw
+		const error = new ValidationError("test");
+		logError(error, { userId: "123", action: "test" });
+		assert(true);
+	});
+});

package/src/index.js

@@ -0,0 +1,32 @@
+// Authorization exports
+
+// Auth exports
+export * from "./auth/index.js";
+export * from "./authorization.js";
+// Cache exports
+export * from "./cache.js";
+// CSRF protection exports
+export * from "./csrf.js";
+// Error Reporter exports
+export * from "./error-reporter.js";
+// Error exports
+export * from "./errors.js";
+// Logger exports
+export * from "./logger.js";
+// Mailhog exports
+export * from "./mailhog.js";
+// Email service exports
+export * from "./email.js";
+// Queue exports
+export * from "./queue/index.js";
+// Rate limiting exports
+export * from "./rate-limiter.js";
+// Redis exports
+export * from "./redis.js";
+
+// Utility exports
+export * from "./utils.js";
+export * from "./validation.js";
+
+// Testing utilities (import from "@techstream/quark-core/testing" in test files)
+// Not re-exported from main to avoid polluting production imports