@techstream/quark-core 1.1.0

package/src/utils.js

@@ -0,0 +1,219 @@
+import crypto from "node:crypto";
+
+/**
+ * @techstream/quark-core - Utility Functions
+ * Common utility functions used across the platform
+ */
+
+/**
+ * Retries an async function with exponential backoff
+ * @param {Function} fn - Async function to retry
+ * @param {Object} options - Retry options
+ * @param {number} options.maxAttempts - Maximum number of attempts (default: 3)
+ * @param {number} options.initialDelay - Initial delay in ms (default: 1000)
+ * @param {number} options.maxDelay - Maximum delay in ms (default: 10000)
+ * @param {Function} options.onRetry - Callback on each retry
+ * @returns {Promise<any>} Result of the function
+ */
+export const retryAsync = async (fn, options = {}) => {
+	const {
+		maxAttempts = 3,
+		initialDelay = 1000,
+		maxDelay = 10000,
+		onRetry = null,
+	} = options;
+
+	let lastError;
+
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		try {
+			return await fn();
+		} catch (error) {
+			lastError = error;
+
+			if (attempt < maxAttempts) {
+				const delay = Math.min(initialDelay * 2 ** (attempt - 1), maxDelay);
+				if (onRetry) {
+					onRetry({ attempt, delay, error });
+				}
+				await sleep(delay);
+			}
+		}
+	}
+
+	throw lastError;
+};
+
+/**
+ * Sleeps for a specified number of milliseconds
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+export const sleep = (ms) => {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+};
+
+/**
+ * Validates required environment variables
+ * @param {Array<string>} vars - Variable names to validate
+ * @throws {Error} If any variables are missing
+ * @returns {boolean} True if all variables exist
+ */
+export const validateEnv = (vars) => {
+	const missing = vars.filter((v) => !process.env[v]);
+
+	if (missing.length > 0) {
+		throw new Error(
+			`Missing required environment variables: ${missing.join(", ")}`,
+		);
+	}
+
+	return true;
+};
+
+/**
+ * Deep merges two objects
+ * @param {Object} target - Target object
+ * @param {Object} source - Source object to merge
+ * @returns {Object} Merged object
+ */
+export const deepMerge = (target, source) => {
+	const output = Object.assign({}, target);
+
+	if (isObject(target) && isObject(source)) {
+		Object.keys(source).forEach((key) => {
+			// Guard against prototype pollution
+			if (key === "__proto__" || key === "constructor" || key === "prototype") {
+				return;
+			}
+			if (isObject(source[key])) {
+				if (!(key in target)) {
+					Object.assign(output, { [key]: source[key] });
+				} else {
+					output[key] = deepMerge(target[key], source[key]);
+				}
+			} else {
+				Object.assign(output, { [key]: source[key] });
+			}
+		});
+	}
+
+	return output;
+};
+
+/**
+ * Checks if value is a plain object
+ * @param {any} item - Item to check
+ * @returns {boolean}
+ */
+export const isObject = (item) => {
+	return item && typeof item === "object" && !Array.isArray(item);
+};
+
+/**
+ * @deprecated Use `getErrorMessage` from `@techstream/quark-core/errors` instead.
+ * Normalizes error messages for consistency
+ * @param {Error|string} error - Error to normalize
+ * @returns {string} Normalized error message
+ */
+export { getErrorMessage as normalizeErrorMessage } from "./errors.js";
+
+/**
+ * Generates a cryptographically secure random string of specified length.
+ * Uses crypto.randomBytes for secure randomness — safe for tokens and IDs.
+ * @param {number} length - String length
+ * @param {string} chars - Characters to use (default: alphanumeric)
+ * @returns {string} Random string
+ */
+export const randomString = (
+	length = 16,
+	chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
+) => {
+	const bytes = crypto.randomBytes(length);
+	let result = "";
+	for (let i = 0; i < length; i++) {
+		result += chars.charAt(bytes[i] % chars.length);
+	}
+	return result;
+};
+
+/**
+ * Sanitizes a string for use in URLs or IDs
+ * @param {string} str - String to sanitize
+ * @returns {string} Sanitized string
+ */
+export const sanitizeId = (str) => {
+	return str
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+};
+
+/**
+ * Formats bytes to human-readable size
+ * @param {number} bytes - Number of bytes
+ * @returns {string} Formatted size
+ */
+export const formatBytes = (bytes) => {
+	if (bytes === 0) return "0 Bytes";
+
+	const k = 1024;
+	const sizes = ["Bytes", "KB", "MB", "GB"];
+	const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+	return `${Math.round((bytes / k ** i) * 100) / 100} ${sizes[i]}`;
+};
+
+/**
+ * Measures execution time of async function
+ * @param {Function} fn - Async function to measure
+ * @returns {Promise<Object>} { result, duration: ms }
+ */
+export const measureTime = async (fn) => {
+	const start = performance.now();
+	const result = await fn();
+	const duration = performance.now() - start;
+
+	return { result, duration: Math.round(duration * 100) / 100 };
+};
+
+/**
+ * Creates a debounced function
+ * @param {Function} fn - Function to debounce
+ * @param {number} delay - Delay in milliseconds
+ * @returns {Function} Debounced function
+ */
+export const debounce = (fn, delay = 300) => {
+	let timeoutId;
+
+	return (...args) => {
+		clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => fn(...args), delay);
+	};
+};
+
+/**
+ * Creates a memoized function (caches results)
+ * @param {Function} fn - Function to memoize
+ * @param {number} ttl - Time to live in milliseconds (0 = no expiry)
+ * @returns {Function} Memoized function
+ */
+export const memoize = (fn, ttl = 0) => {
+	const cache = new Map();
+
+	return (...args) => {
+		const key = JSON.stringify(args);
+
+		if (cache.has(key)) {
+			const cached = cache.get(key);
+			if (ttl === 0 || Date.now() - cached.timestamp < ttl) {
+				return cached.value;
+			}
+			cache.delete(key);
+		}
+
+		const value = fn(...args);
+		cache.set(key, { value, timestamp: Date.now() });
+		return value;
+	};
+};

package/src/utils.test.js

@@ -0,0 +1,193 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	debounce,
+	deepMerge,
+	formatBytes,
+	isObject,
+	memoize,
+	normalizeErrorMessage,
+	randomString,
+	retryAsync,
+	sanitizeId,
+	sleep,
+	validateEnv,
+} from "../src/utils.js";
+
+test("Utils Module", async (t) => {
+	await t.test("retryAsync succeeds on first attempt", async () => {
+		let attempts = 0;
+		const result = await retryAsync(async () => {
+			attempts++;
+			return "success";
+		});
+
+		assert(result === "success");
+		assert(attempts === 1);
+	});
+
+	await t.test("retryAsync retries on failure", async () => {
+		let attempts = 0;
+		const result = await retryAsync(
+			async () => {
+				attempts++;
+				if (attempts < 3) throw new Error("Fail");
+				return "success";
+			},
+			{ maxAttempts: 5, initialDelay: 10 },
+		);
+
+		assert(result === "success");
+		assert(attempts === 3);
+	});
+
+	await t.test("retryAsync throws after max attempts", async () => {
+		let attempts = 0;
+		await assert.rejects(async () => {
+			await retryAsync(
+				async () => {
+					attempts++;
+					throw new Error("Always fails");
+				},
+				{ maxAttempts: 3, initialDelay: 10 },
+			);
+		});
+
+		assert(attempts === 3);
+	});
+
+	await t.test("sleep delays execution", async () => {
+		const start = Date.now();
+		await sleep(50);
+		const elapsed = Date.now() - start;
+		assert(elapsed >= 40); // Allow some variance
+	});
+
+	await t.test("validateEnv checks required variables", () => {
+		process.env.TEST_VAR = "test";
+		assert(validateEnv(["TEST_VAR"]) === true);
+	});
+
+	await t.test("validateEnv throws on missing variables", () => {
+		assert.throws(() => {
+			validateEnv(["NONEXISTENT_VAR_12345"]);
+		});
+	});
+
+	await t.test("deepMerge merges objects", () => {
+		const result = deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 });
+
+		assert.deepStrictEqual(result, {
+			a: 1,
+			b: { c: 2, d: 3 },
+			e: 4,
+		});
+	});
+
+	await t.test("deepMerge handles nested objects", () => {
+		const result = deepMerge({ a: { b: { c: 1 } } }, { a: { b: { d: 2 } } });
+
+		assert.deepStrictEqual(result, {
+			a: { b: { c: 1, d: 2 } },
+		});
+	});
+
+	await t.test("isObject identifies objects", () => {
+		assert(isObject({}));
+		assert(isObject({ a: 1 }));
+		assert(!isObject([]));
+		assert(!isObject(null));
+		assert(!isObject("string"));
+		assert(!isObject(123));
+	});
+
+	await t.test("normalizeErrorMessage handles various types", () => {
+		assert(normalizeErrorMessage("string") === "string");
+		assert(normalizeErrorMessage(new Error("error")) === "error");
+		assert(normalizeErrorMessage({ message: "msg" }) === "msg");
+		assert(normalizeErrorMessage(null).includes("unknown"));
+	});
+
+	await t.test("randomString generates random strings", () => {
+		const str1 = randomString(16);
+		const str2 = randomString(16);
+
+		assert(str1.length === 16);
+		assert(str2.length === 16);
+		// Very unlikely to be equal
+		assert(str1 !== str2);
+	});
+
+	await t.test("randomString respects length parameter", () => {
+		assert(randomString(10).length === 10);
+		assert(randomString(50).length === 50);
+	});
+
+	await t.test("sanitizeId converts to valid IDs", () => {
+		assert(sanitizeId("Hello World") === "hello-world");
+		assert(sanitizeId("Test_123") === "test-123");
+		assert(sanitizeId("---hello---") === "hello");
+		assert(sanitizeId("UPPERCASE") === "uppercase");
+	});
+
+	await t.test("formatBytes formats file sizes", () => {
+		assert(formatBytes(0) === "0 Bytes");
+		assert(formatBytes(1024) === "1 KB");
+		assert(formatBytes(1024 * 1024) === "1 MB");
+		assert(formatBytes(1024 * 1024 * 1024) === "1 GB");
+	});
+
+	await t.test("debounce delays function execution", (_t, done) => {
+		let callCount = 0;
+		const debounced = debounce(() => {
+			callCount++;
+		}, 30);
+
+		debounced();
+		debounced();
+		debounced();
+
+		assert(callCount === 0); // Not called yet
+
+		setTimeout(() => {
+			assert(callCount === 1); // Called once after delay
+			done();
+		}, 50);
+	});
+
+	await t.test("memoize caches function results", () => {
+		let callCount = 0;
+		const memoized = memoize((x) => {
+			callCount++;
+			return x * 2;
+		});
+
+		assert(memoized(5) === 10);
+		assert(callCount === 1);
+		assert(memoized(5) === 10);
+		assert(callCount === 1); // Same result from cache
+
+		assert(memoized(10) === 20);
+		assert(callCount === 2); // Different input, new call
+	});
+
+	await t.test("memoize respects TTL", (_t, done) => {
+		let callCount = 0;
+		const memoized = memoize(
+			(x) => {
+				callCount++;
+				return x * 2;
+			},
+			30, // 30ms TTL
+		);
+
+		assert(memoized(5) === 10);
+		assert(callCount === 1);
+
+		setTimeout(() => {
+			assert(memoized(5) === 10);
+			assert(callCount === 2); // Cache expired, new call
+			done();
+		}, 50);
+	});
+});

package/src/validation.js

@@ -0,0 +1,26 @@
+import { ZodError } from "zod";
+import { ValidationError } from "./errors.js";
+
+/**
+ * Validates request body against a Zod schema
+ * @param {Request} request - Next.js Request object
+ * @param {import("zod").ZodSchema} schema - Zod schema to validate against
+ * @returns {Promise<any>} - Validated data
+ */
+export async function validateBody(request, schema) {
+	let body;
+	try {
+		body = await request.json();
+	} catch (_err) {
+		throw new ValidationError("Invalid JSON body");
+	}
+
+	try {
+		return schema.parse(body);
+	} catch (error) {
+		if (error instanceof ZodError) {
+			throw new ValidationError("Validation failed", error.errors);
+		}
+		throw error;
+	}
+}

package/test-imports.mjs

@@ -0,0 +1,21 @@
+// Test script - verify all core modules load
+import("./src/auth/index.js").then(() => {
+	console.log("✅ Auth module loaded");
+});
+
+import("./src/errors.js").then(() => {
+	console.log("✅ Errors module loaded");
+});
+
+import("./src/utils.js").then(() => {
+	console.log("✅ Utils module loaded");
+});
+
+import("./src/queue/index.js").then(() => {
+	console.log("✅ Queue module loaded");
+});
+
+setTimeout(() => {
+	console.log("\n✨ All core modules are properly configured!");
+	process.exit(0);
+}, 500);