@usequark/quark-core 2.5.4

package/src/error-reporter.js

@@ -0,0 +1,266 @@
+/**
+ * @techstream/quark-core - Error Reporter Module
+ * Adapter/hook system for pluggable error reporting
+ */
+
+import { normalizeError } from "./errors.js";
+import { logger } from "./logger.js";
+
+const MAX_BREADCRUMBS = 50;
+
+/**
+ * @typedef {Object} ErrorAdapter
+ * @property {string} name - Unique adapter identifier
+ * @property {(error: Error, context: Object) => void} report - Called when an error is reported
+ * @property {(message: string, level: string, context: Object) => void} [captureMessage] - For non-error events
+ * @property {(user: Object) => void} [setUser] - Sets user context
+ * @property {(message: string, category: string, data: Object) => void} [addBreadcrumb] - Adds a breadcrumb
+ */
+
+/**
+ * @typedef {Object} Breadcrumb
+ * @property {string} message - Breadcrumb message
+ * @property {string} category - Breadcrumb category
+ * @property {Object} data - Associated data
+ * @property {string} timestamp - ISO timestamp
+ */
+
+/**
+ * Built-in adapter that logs errors via the Quark logger.
+ * @type {ErrorAdapter}
+ */
+export const consoleAdapter = {
+	name: "console",
+
+	report(error, context) {
+		const appError = normalizeError(error);
+		logger.error(appError.message, {
+			error: appError.toJSON(),
+			context,
+			stack: error.stack,
+		});
+	},
+
+	captureMessage(message, level = "info", context = {}) {
+		const logFn = logger[level] || logger.info;
+		logFn.call(logger, message, context);
+	},
+
+	setUser(_user) {
+		// Console adapter does not persist user context
+	},
+
+	addBreadcrumb(_message, _category, _data) {
+		// Console adapter does not store breadcrumbs
+	},
+};
+
+/**
+ * Error reporter with adapter registration.
+ * Distributes error reports to all registered adapters.
+ */
+export class ErrorReporter {
+	/** @type {ErrorAdapter[]} */
+	#adapters = [];
+
+	/** @type {Breadcrumb[]} */
+	#breadcrumbs = [];
+
+	/** @type {Object|null} */
+	#user = null;
+
+	constructor() {
+		this.#adapters = [consoleAdapter];
+		this.#breadcrumbs = [];
+		this.#user = null;
+	}
+
+	/**
+	 * Register an adapter
+	 * @param {ErrorAdapter} adapter - The adapter to register
+	 * @returns {void}
+	 */
+	use(adapter) {
+		if (
+			!adapter ||
+			typeof adapter.name !== "string" ||
+			typeof adapter.report !== "function"
+		) {
+			throw new Error(
+				"Adapter must have a name (string) and a report (function)",
+			);
+		}
+		this.#adapters.push(adapter);
+	}
+
+	/**
+	 * Report an error to all registered adapters
+	 * @param {Error} error - The error to report
+	 * @param {Object} [context={}] - Additional context
+	 * @returns {void}
+	 */
+	report(error, context = {}) {
+		const enrichedContext = {
+			...context,
+			...(this.#user ? { user: this.#user } : {}),
+			breadcrumbs: [...this.#breadcrumbs],
+		};
+
+		for (const adapter of this.#adapters) {
+			try {
+				adapter.report(error, enrichedContext);
+			} catch (_adapterError) {
+				// Swallow adapter errors to avoid cascading failures
+			}
+		}
+	}
+
+	/**
+	 * Capture a non-error message event
+	 * @param {string} message - The message to capture
+	 * @param {string} [level="info"] - Log level
+	 * @param {Object} [context={}] - Additional context
+	 * @returns {void}
+	 */
+	captureMessage(message, level = "info", context = {}) {
+		const enrichedContext = {
+			...context,
+			...(this.#user ? { user: this.#user } : {}),
+		};
+
+		for (const adapter of this.#adapters) {
+			try {
+				if (typeof adapter.captureMessage === "function") {
+					adapter.captureMessage(message, level, enrichedContext);
+				}
+			} catch (_adapterError) {
+				// Swallow adapter errors
+			}
+		}
+	}
+
+	/**
+	 * Set user context for subsequent reports
+	 * @param {Object} user - User information
+	 * @returns {void}
+	 */
+	setUser(user) {
+		this.#user = user;
+
+		for (const adapter of this.#adapters) {
+			try {
+				if (typeof adapter.setUser === "function") {
+					adapter.setUser(user);
+				}
+			} catch (_adapterError) {
+				// Swallow adapter errors
+			}
+		}
+	}
+
+	/**
+	 * Add a breadcrumb to the trail (circular buffer, max 50)
+	 * @param {string} message - Breadcrumb message
+	 * @param {string} [category="default"] - Breadcrumb category
+	 * @param {Object} [data={}] - Associated data
+	 * @returns {void}
+	 */
+	addBreadcrumb(message, category = "default", data = {}) {
+		/** @type {Breadcrumb} */
+		const breadcrumb = {
+			message,
+			category,
+			data,
+			timestamp: new Date().toISOString(),
+		};
+
+		if (this.#breadcrumbs.length >= MAX_BREADCRUMBS) {
+			this.#breadcrumbs.shift();
+		}
+		this.#breadcrumbs.push(breadcrumb);
+
+		for (const adapter of this.#adapters) {
+			try {
+				if (typeof adapter.addBreadcrumb === "function") {
+					adapter.addBreadcrumb(message, category, data);
+				}
+			} catch (_adapterError) {
+				// Swallow adapter errors
+			}
+		}
+	}
+
+	/**
+	 * Returns the list of registered adapters (for inspection/testing)
+	 * @returns {ErrorAdapter[]}
+	 */
+	get adapters() {
+		return [...this.#adapters];
+	}
+
+	/**
+	 * Returns the current breadcrumbs (for inspection/testing)
+	 * @returns {Breadcrumb[]}
+	 */
+	get breadcrumbs() {
+		return [...this.#breadcrumbs];
+	}
+}
+
+/**
+ * Creates a Sentry adapter factory (stub/example).
+ * Downstream projects can use this as a template to integrate Sentry.
+ *
+ * @param {Object} _options - Sentry configuration options
+ * @returns {ErrorAdapter} A Sentry adapter (stubbed)
+ *
+ * @example
+ * ```js
+ * import * as Sentry from "@sentry/node";
+ * import { errorReporter, createSentryAdapter } from "@techstream/quark-core";
+ *
+ * Sentry.init({ dsn: "https://example@sentry.io/123" });
+ * errorReporter.use(createSentryAdapter({ Sentry }));
+ * ```
+ */
+export const createSentryAdapter = (_options = {}) => {
+	return {
+		name: "sentry",
+
+		report(_error, _context) {
+			// Example Sentry integration:
+			// const { Sentry } = options;
+			// Sentry.withScope((scope) => {
+			//   if (context.user) scope.setUser(context.user);
+			//   if (context.breadcrumbs) {
+			//     for (const b of context.breadcrumbs) {
+			//       Sentry.addBreadcrumb({ message: b.message, category: b.category, data: b.data });
+			//     }
+			//   }
+			//   scope.setExtras(context);
+			//   Sentry.captureException(error);
+			// });
+		},
+
+		captureMessage(_message, _level, _context) {
+			// Example:
+			// const { Sentry } = options;
+			// Sentry.captureMessage(message, level);
+		},
+
+		setUser(_user) {
+			// Example:
+			// const { Sentry } = options;
+			// Sentry.setUser(user);
+		},
+
+		addBreadcrumb(_message, _category, _data) {
+			// Example:
+			// const { Sentry } = options;
+			// Sentry.addBreadcrumb({ message, category, data });
+		},
+	};
+};
+
+/** Global singleton error reporter instance */
+export const errorReporter = new ErrorReporter();

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);
+		}
+	};
+};