@buenojs/bueno 0.8.4 → 0.8.6

package/src/events/__tests__/event-system.test.ts

@@ -0,0 +1,235 @@
+import {
+	createEvent,
+	createEventCategory,
+	createEventListener,
+	createEventManager,
+	createEventRegistry,
+	deserializeEvent,
+	serializeEvent,
+	validateEvent,
+} from "../index";
+
+describe("Event System", () => {
+	let manager: any;
+	let registry: any;
+
+	beforeEach(() => {
+		manager = createEventManager();
+		registry = createEventRegistry();
+	});
+
+	describe("Event Manager", () => {
+		it("should emit and handle events", async () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+
+			const handler = jest.fn();
+			manager.on("test.event", handler);
+
+			await manager.emit(event);
+
+			expect(handler).toHaveBeenCalledWith(event);
+			expect(handler).toHaveBeenCalledTimes(1);
+		});
+
+		it("should support one-time listeners", async () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+
+			const handler = jest.fn();
+			manager.once("test.event", handler);
+
+			await manager.emit(event);
+			await manager.emit(event);
+
+			expect(handler).toHaveBeenCalledWith(event);
+			expect(handler).toHaveBeenCalledTimes(1);
+		});
+
+		it("should support event filtering", async () => {
+			const eventData1 = { type: "important" };
+			const eventData2 = { type: "normal" };
+			const event1 = createEvent("test.event", eventData1);
+			const event2 = createEvent("test.event", eventData2);
+
+			const handler = jest.fn();
+			const filter = (e: any) => e.data.type === "important";
+			manager.on("test.event", handler, { filter });
+
+			await manager.emit(event1);
+			await manager.emit(event2);
+
+			expect(handler).toHaveBeenCalledWith(event1);
+			expect(handler).toHaveBeenCalledTimes(1);
+		});
+
+		it("should support event middleware", async () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+
+			const middleware = jest.fn(async (e, next) => {
+				e.data.middleware = true;
+				await next();
+			});
+
+			manager.addMiddleware(middleware);
+			const handler = jest.fn();
+			manager.on("test.event", handler);
+
+			await manager.emit(event);
+
+			expect(middleware).toHaveBeenCalled();
+			expect(handler).toHaveBeenCalledWith(event);
+			expect(event.data.middleware).toBe(true);
+		});
+
+		it("should handle errors gracefully", async () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+
+			const failingHandler = jest.fn(() => {
+				throw new Error("Test error");
+			});
+			const successHandler = jest.fn();
+
+			manager.on("test.event", failingHandler);
+			manager.on("test.event", successHandler);
+
+			await manager.emit(event);
+
+			expect(failingHandler).toHaveBeenCalled();
+			expect(successHandler).toHaveBeenCalled();
+		});
+
+		it("should support event categories", () => {
+			const category = createEventCategory("database", "Database operations");
+			manager.registerEventCategory(category);
+
+			expect(manager.getEventCategories()).toContainEqual(category);
+		});
+	});
+
+	describe("Event Registry", () => {
+		it("should register and retrieve events", () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+
+			registry.registerEvent(event);
+
+			expect(registry.getEvent(event.id)).toEqual(event);
+		});
+
+		it("should support event cleanup", () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData, {
+				timestamp: new Date(Date.now() - 25 * 60 * 60 * 1000), // 25 hours ago
+			});
+
+			registry.registerEvent(event);
+			registry.cleanupOldEvents();
+
+			expect(registry.getEvent(event.id)).toBeUndefined();
+		});
+
+		it("should support event search", () => {
+			const event1 = createEvent("user.created", { name: "John" });
+			const event2 = createEvent("user.deleted", { name: "Jane" });
+
+			registry.registerEvent(event1);
+			registry.registerEvent(event2);
+
+			const results = registry.searchEvents("user");
+
+			expect(results).toHaveLength(2);
+			expect(results).toContainEqual(event1);
+			expect(results).toContainEqual(event2);
+		});
+
+		it("should support event history", () => {
+			const events = [
+				createEvent(
+					"test.event",
+					{ count: 1 },
+					{ timestamp: new Date(Date.now() - 3000) },
+				),
+				createEvent(
+					"test.event",
+					{ count: 2 },
+					{ timestamp: new Date(Date.now() - 2000) },
+				),
+				createEvent(
+					"test.event",
+					{ count: 3 },
+					{ timestamp: new Date(Date.now() - 1000) },
+				),
+			];
+
+			events.forEach((event) => registry.registerEvent(event));
+
+			const history = registry.getEventHistory({
+				category: undefined,
+				startTime: new Date(Date.now() - 60 * 60 * 1000),
+				endTime: new Date(),
+				limit: 2,
+			});
+
+			expect(history).toHaveLength(2);
+			expect(history[0].data.count).toBe(3);
+			expect(history[1].data.count).toBe(2);
+		});
+	});
+
+	describe("Event Utilities", () => {
+		it("should create valid events", () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+
+			expect(event).toHaveProperty("id");
+			expect(event).toHaveProperty("name", "test.event");
+			expect(event).toHaveProperty("timestamp");
+			expect(event).toHaveProperty("data", eventData);
+		});
+
+		it("should validate events", () => {
+			const validEvent = createEvent("test.event", { message: "test" });
+			const invalidEvent = { name: "test", data: {} };
+
+			expect(validateEvent(validEvent)).toBe(true);
+			expect(validateEvent(invalidEvent)).toBe(false);
+		});
+
+		it("should serialize and deserialize events", () => {
+			const eventData = { message: "test" };
+			const event = createEvent("test.event", eventData);
+			const serialized = serializeEvent(event);
+			const deserialized = deserializeEvent(serialized);
+
+			expect(deserialized).toEqual(event);
+		});
+
+		it("should create event listeners", () => {
+			const handler = () => {};
+			const listener = createEventListener("test.listener", handler, {
+				priority: 10,
+				once: true,
+			});
+
+			expect(listener).toHaveProperty("id");
+			expect(listener).toHaveProperty("name", "test.listener");
+			expect(listener).toHaveProperty("handler", handler);
+			expect(listener).toHaveProperty("priority", 10);
+			expect(listener).toHaveProperty("once", true);
+		});
+
+		it("should create event categories", () => {
+			const category = createEventCategory("database", "Database operations", [
+				"query",
+				"mutation",
+			]);
+
+			expect(category).toHaveProperty("name", "database");
+			expect(category).toHaveProperty("description", "Database operations");
+			expect(category).toHaveProperty("events", ["query", "mutation"]);
+		});
+	});
+});

package/src/events/config.ts

@@ -0,0 +1,238 @@
+import {
+	EventManagerConfig,
+	type EventManagerOptions,
+	type EventRegistryOptions,
+} from "./types";
+
+export interface EventSystemConfig {
+	manager: EventManagerOptions;
+	registry: EventRegistryOptions;
+	defaultContext?: EventContext;
+	errorHandling?: "throw" | "log" | "ignore";
+	maxEventSize?: number;
+	eventCategories?: EventCategory[];
+}
+
+export const defaultEventSystemConfig: EventSystemConfig = {
+	manager: {
+		maxListeners: 100,
+		errorHandling: "log",
+	},
+	registry: {
+		maxEvents: 1000,
+		retentionPeriod: 24 * 60 * 60 * 1000, // 24 hours
+		cleanupInterval: 60 * 60 * 1000, // 1 hour
+	},
+	defaultContext: {
+		userId: undefined,
+		sessionId: undefined,
+		requestId: undefined,
+		ipAddress: undefined,
+		userAgent: undefined,
+	},
+	errorHandling: "log",
+	maxEventSize: 1024 * 1024, // 1MB
+	eventCategories: [
+		{
+			name: "database",
+			description: "Database operations and query lifecycle",
+			events: ["query", "mutation", "connection", "transaction"],
+		},
+		{
+			name: "job-queue",
+			description: "Background job processing and queue management",
+			events: ["job.created", "job.started", "job.completed", "job.failed"],
+		},
+		{
+			name: "notification",
+			description: "Multi-channel notification system",
+			events: [
+				"notification.sent",
+				"notification.delivered",
+				"notification.failed",
+			],
+		},
+		{
+			name: "websocket",
+			description: "Real-time WebSocket communication",
+			events: ["connection", "message", "disconnection", "error"],
+		},
+		{
+			name: "http-rpc",
+			description: "HTTP and RPC request/response handling",
+			events: ["request.received", "response.sent", "error"],
+		},
+		{
+			name: "system",
+			description: "System-level events and health checks",
+			events: ["startup", "shutdown", "health.check"],
+		},
+		{
+			name: "cache",
+			description: "Caching operations and invalidation",
+			events: ["cache.set", "cache.get", "cache.delete", "cache.miss"],
+		},
+		{
+			name: "validation",
+			description: "Data validation and sanitization",
+			events: ["validation.passed", "validation.failed"],
+		},
+		{
+			name: "security",
+			description: "Security and authentication events",
+			events: ["login", "logout", "permission.granted", "permission.denied"],
+		},
+		{
+			name: "logging",
+			description: "Application logging and monitoring",
+			events: ["log.info", "log.warn", "log.error", "log.debug"],
+		},
+	],
+};
+
+export function createEventSystemConfig(
+	customConfig: Partial<EventSystemConfig> = {},
+): EventSystemConfig {
+	return {
+		...defaultEventSystemConfig,
+		...customConfig,
+		manager: {
+			...defaultEventSystemConfig.manager,
+			...customConfig.manager,
+		},
+		registry: {
+			...defaultEventSystemConfig.registry,
+			...customConfig.registry,
+		},
+		defaultContext: {
+			...defaultEventSystemConfig.defaultContext,
+			...customConfig.defaultContext,
+		},
+	};
+}
+
+export function validateEventSystemConfig(config: EventSystemConfig): boolean {
+	if (!config || typeof config !== "object") return false;
+
+	// Validate manager config
+	if (!config.manager || typeof config.manager !== "object") return false;
+	if (
+		config.manager.maxListeners !== undefined &&
+		(typeof config.manager.maxListeners !== "number" ||
+			config.manager.maxListeners < 0)
+	) {
+		return false;
+	}
+
+	// Validate registry config
+	if (!config.registry || typeof config.registry !== "object") return false;
+	if (
+		config.registry.maxEvents !== undefined &&
+		(typeof config.registry.maxEvents !== "number" ||
+			config.registry.maxEvents < 0)
+	) {
+		return false;
+	}
+	if (
+		config.registry.retentionPeriod !== undefined &&
+		(typeof config.registry.retentionPeriod !== "number" ||
+			config.registry.retentionPeriod < 0)
+	) {
+		return false;
+	}
+	if (
+		config.registry.cleanupInterval !== undefined &&
+		(typeof config.registry.cleanupInterval !== "number" ||
+			config.registry.cleanupInterval < 0)
+	) {
+		return false;
+	}
+
+	// Validate error handling
+	if (
+		config.errorHandling &&
+		!["throw", "log", "ignore"].includes(config.errorHandling)
+	) {
+		return false;
+	}
+
+	// Validate max event size
+	if (
+		config.maxEventSize !== undefined &&
+		(typeof config.maxEventSize !== "number" || config.maxEventSize < 0)
+	) {
+		return false;
+	}
+
+	// Validate event categories
+	if (config.eventCategories) {
+		for (const category of config.eventCategories) {
+			if (!category.name || typeof category.name !== "string") return false;
+			if (!category.description || typeof category.description !== "string")
+				return false;
+			if (category.events && !Array.isArray(category.events)) return false;
+		}
+	}
+
+	return true;
+}
+
+export function loadEventSystemConfig(
+	configPath = "./config/event-system.json",
+): EventSystemConfig {
+	try {
+		const config = require(configPath);
+		if (validateEventSystemConfig(config)) {
+			return config;
+		}
+		console.warn("Invalid event system config, using defaults");
+	} catch (error) {
+		console.warn("Could not load event system config, using defaults");
+	}
+
+	return defaultEventSystemConfig;
+}
+
+export function saveEventSystemConfig(
+	config: EventSystemConfig,
+	configPath = "./config/event-system.json",
+): boolean {
+	try {
+		const fs = require("fs");
+		const path = require("path");
+
+		const dir = path.dirname(configPath);
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+
+		fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+		return true;
+	} catch (error) {
+		console.error("Failed to save event system config:", error);
+		return false;
+	}
+}
+
+export function mergeEventSystemConfigs(
+	...configs: Partial<EventSystemConfig>[]
+): EventSystemConfig {
+	return configs.reduce((merged, config) => {
+		return {
+			...merged,
+			...config,
+			manager: {
+				...merged.manager,
+				...config.manager,
+			},
+			registry: {
+				...merged.registry,
+				...config.registry,
+			},
+			defaultContext: {
+				...merged.defaultContext,
+				...config.defaultContext,
+			},
+		};
+	}, defaultEventSystemConfig);
+}

package/src/events/example-usage.ts

@@ -0,0 +1,185 @@
+import {
+	createEvent,
+	createEventCategory,
+	createEventContext,
+	createEventFilter,
+	createEventListener,
+	createEventManager,
+	createEventMiddleware,
+	createEventRegistry,
+} from "./index";
+
+// Create event manager and registry
+const manager = createEventManager({
+	maxListeners: 200,
+	errorHandling: "log",
+});
+
+const registry = createEventRegistry({
+	maxEvents: 5000,
+	retentionPeriod: 7 * 24 * 60 * 60 * 1000, // 7 days
+});
+
+// Register event categories
+const databaseCategory = createEventCategory(
+	"database",
+	"Database operations and query lifecycle",
+	["query", "mutation", "connection", "transaction"],
+);
+
+const jobQueueCategory = createEventCategory(
+	"job-queue",
+	"Background job processing and queue management",
+	["job.created", "job.started", "job.completed", "job.failed"],
+);
+
+manager.registerEventCategory(databaseCategory);
+manager.registerEventCategory(jobQueueCategory);
+
+// Create event context
+const defaultContext = createEventContext({
+	userId: "user123",
+	sessionId: "session456",
+	ipAddress: "192.168.1.1",
+});
+
+// Create event middleware
+const loggingMiddleware = createEventMiddleware(async (event, next) => {
+	console.log(`Event received: ${event.name}`);
+	await next();
+});
+
+const validationMiddleware = createEventMiddleware(async (event, next) => {
+	if (event.data && typeof event.data === "object") {
+		// Validate event data
+		if (Object.keys(event.data).length === 0) {
+			throw new Error("Event data cannot be empty");
+		}
+	}
+	await next();
+});
+
+manager.addMiddleware(loggingMiddleware);
+manager.addMiddleware(validationMiddleware);
+
+// Create event listeners
+const queryListener = createEventListener(
+	"database.query",
+	async (event) => {
+		console.log("Query executed:", event.data.query);
+		// Log query to database
+		registry.registerEvent(event);
+	},
+	{ priority: 10 },
+);
+
+const jobStartedListener = createEventListener("job.started", async (event) => {
+	console.log(`Job started: ${event.data.jobId}`);
+	// Update job status
+});
+
+const errorListener = createEventListener(
+	"error",
+	async (event) => {
+		console.error("Error occurred:", event.data.error);
+	},
+	{ priority: 100 },
+);
+
+// Add listeners to manager
+manager.addListener(queryListener);
+manager.addListener(jobStartedListener);
+manager.addListener(errorListener);
+
+// Create event filters
+const importantFilter = createEventFilter((event) => {
+	return event.data && event.data.importance === "high";
+});
+
+// Create filtered listener
+const importantEventListener = createEventListener(
+	"important.event",
+	async (event) => {
+		console.log("Important event detected:", event.data);
+		// Send alert or notification
+	},
+	{ filter: importantFilter },
+);
+
+manager.addListener(importantEventListener);
+
+// Example event emission
+async function exampleUsage() {
+	try {
+		// Database query event
+		const queryEvent = createEvent(
+			"database.query",
+			{
+				query: "SELECT * FROM users WHERE id = 1",
+				executionTime: 120,
+			},
+			{ context: defaultContext },
+		);
+
+		await manager.emit(queryEvent);
+
+		// Job started event
+		const jobEvent = createEvent(
+			"job.started",
+			{
+				jobId: "job789",
+				type: "email-sender",
+				data: { userId: "user123" },
+			},
+			{ context: defaultContext },
+		);
+
+		await manager.emit(jobEvent);
+
+		// Important event
+		const importantEvent = createEvent(
+			"important.event",
+			{
+				message: "System alert",
+				importance: "high",
+				details: "High memory usage detected",
+			},
+			{ context: defaultContext },
+		);
+
+		await manager.emit(importantEvent);
+
+		// Error event
+		const errorEvent = createEvent(
+			"error",
+			{
+				error: new Error("Test error"),
+				source: "example-usage",
+			},
+			{ context: defaultContext },
+		);
+
+		await manager.emit(errorEvent);
+
+		console.log("All events processed successfully!");
+	} catch (error) {
+		console.error("Error in example usage:", error);
+	}
+}
+
+// Run example
+exampleUsage();
+
+// Export for use in other modules
+export {
+	manager,
+	registry,
+	defaultContext,
+	loggingMiddleware,
+	validationMiddleware,
+	queryListener,
+	jobStartedListener,
+	errorListener,
+	importantFilter,
+	importantEventListener,
+};