@buenojs/bueno 0.8.3 → 0.8.5

package/src/index.ts

@@ -53,42 +53,16 @@ export {
 	createApp,
 } from "./modules";
 
-// Database
+// Database (connection layer)
 export {
 	Database,
 	createConnection,
 	detectDriver,
-	QueryBuilder,
-	table,
 	ReservedConnection,
 	type DatabaseConfig as DatabaseConfigType,
 	type DatabaseDriver,
 	type QueryResult,
 	type Transaction,
-	// Schema
-	SchemaBuilder,
-	createSchema,
-	defineTable,
-	generateCreateTable,
-	generateDropTable,
-	generateCreateIndex,
-	type ColumnType,
-	type ColumnOptions,
-	type TableSchema,
-	type IndexDefinition,
-	type ConstraintDefinition,
-	type TypeScriptType,
-	type InferType,
-	type InferInsertType,
-	// Migrations
-	MigrationRunner,
-	MigrationBuilder,
-	createMigration,
-	createMigrationRunner,
-	generateMigrationId,
-	type Migration,
-	type MigrationRecord,
-	type MigrationOptions,
 } from "./database";
 
 // Validation
@@ -156,6 +130,159 @@ export {
 	type LockHandle,
 } from "./lock";
 
+// Background Jobs
+export {
+	JobQueue,
+	JobWorker,
+	createJobQueue,
+	startWorker,
+	MemoryJobQueueDriver,
+	RedisJobQueueDriver,
+	type Job,
+	type JobStatus,
+	type JobQueueConfig,
+	type QueueOptions,
+	type JobHandler,
+	type QueueMetrics,
+	type JobEvent,
+	type JobEventType,
+	type JobClaimHandle,
+	type JobQueueDriver,
+	type HandlerRegistryEntry,
+	type JobConfigValidationResult,
+} from "./jobs";
+
+// Templates
+export {
+	TemplateEngine,
+	TemplateLoader,
+	SimpleRenderer,
+	MarkdownRenderer,
+	type Template,
+	type TemplateMetadata,
+	type TemplateData,
+	type RenderOptions,
+	type TemplateEngineConfig,
+	type TemplateEngineMetrics,
+	type IRenderer,
+	type FilterRegistry,
+	type TemplateLoaderOptions,
+	type TemplateLoadedEvent,
+} from "./templates";
+
+// Notification
+export {
+	NotificationService,
+	createNotificationService,
+	BaseChannelService,
+	EmailChannelService,
+	SMSChannelService,
+	WhatsAppChannelService,
+	PushNotificationChannelService,
+	type NotificationChannel,
+	type NotificationMessage,
+	type EmailRecipient,
+	type EmailRecipients,
+	type EmailAttachment,
+	type EmailMessage,
+	type SMSMessage,
+	type WhatsAppMessage,
+	type PushNotificationMessage,
+	type BuiltInNotification,
+	type Notifiable,
+	type ChannelHealth,
+	type ChannelService,
+	type BaseChannelConfig,
+	type EmailChannelConfig,
+	type SMSChannelConfig,
+	type WhatsAppChannelConfig,
+	type PushChannelConfig,
+	type ChannelConfig,
+	type NotificationServiceConfig,
+	type ChannelMetrics,
+	type NotificationEvent,
+	type NotificationEventType,
+	type NotificationValidationResult,
+} from "./notification";
+
+// OpenAPI
+export {
+	DocumentBuilder,
+	SchemaGenerator,
+	RouteScanner,
+	SwaggerModule,
+	ApiTags,
+	ApiBearerAuth,
+	ApiBasicAuth,
+	ApiApiKey,
+	ApiExcludeController,
+	ApiOperation,
+	ApiResponse,
+	ApiParam,
+	ApiQuery,
+	ApiHeader,
+	ApiBody,
+	ApiExcludeEndpoint,
+	ApiProperty,
+	ApiPropertyOptional,
+	type OpenAPIDocument,
+	type OpenAPIInfo,
+	type OpenAPIContact,
+	type OpenAPILicense,
+	type OpenAPIServer,
+	type OpenAPIPaths,
+	type OpenAPIPath,
+	type OpenAPIOperation,
+	type OpenAPIExternalDocs,
+	type OpenAPIParameter,
+	type OpenAPIRequestBody,
+	type OpenAPIMediaType,
+	type OpenAPIExample,
+	type OpenAPIResponse,
+	type OpenAPIHeader,
+	type OpenAPIResponses,
+	type OpenAPISchema,
+	type OpenAPIDiscriminator,
+	type OpenAPIXML,
+	type OpenAPIComponents,
+	type OpenAPISecurityScheme,
+	type OpenAPIOAuthFlows,
+	type OpenAPIOAuthFlow,
+	type OpenAPISecurity,
+	type OpenAPITag,
+	type SwaggerOptions,
+	type ApiOperationOptions,
+	type ApiResponseOptions,
+	type ApiParamOptions,
+	type ApiQueryOptions,
+	type ApiHeaderOptions,
+	type ApiBodyOptions,
+	type ApiPropertyOptions,
+	type SecuritySchemeOptions,
+	type ApiKeySecurityOptions,
+} from "./openapi";
+
+// i18n
+export {
+	I18n,
+	createI18n,
+	TranslationLoader,
+	LocaleNegotiator,
+	parseAcceptLanguage,
+	normaliseLocale,
+	i18nMiddleware,
+	getLocale,
+	getT,
+	type PluralKey,
+	type TranslationParams,
+	type TranslationFunction,
+	type LocaleMatch,
+	type I18nContext,
+	type LocaleBundle,
+	type I18nMetrics,
+	type I18nMiddlewareOptions,
+} from "./i18n";
+
 // SSG
 export {
 	SSG,
@@ -269,6 +396,28 @@ export {
 	type CacheLike,
 } from "./health";
 
+// Observability
+export {
+	ObservabilityModule,
+	ObservabilityService,
+	ObservabilityInterceptor,
+	BreadcrumbCollector,
+	httpBreadcrumb,
+	logBreadcrumb,
+	extractTraceContext,
+	generateTraceId,
+	generateSpanId,
+	buildTraceparent,
+	type BreadcrumbEntry,
+	type ErrorEvent,
+	type ErrorRequestContext,
+	type ErrorUserContext,
+	type MessageEvent,
+	type ErrorReporter,
+	type ObservabilityOptions,
+	type ObservabilityConfig,
+} from "./observability";
+
 // Types
 export type {
 	HTTPMethod,
@@ -355,6 +504,9 @@ export type {
 	MetricsConfig,
 	TelemetryConfig,
 	FrontendConfig,
+	JobsConfig,
+	NotificationConfig,
+	I18nConfig,
 	DeepPartial,
 	UserConfig,
 	UserConfigFn,

package/src/jobs/drivers/memory.ts

@@ -0,0 +1,315 @@
+/**
+ * In-Memory Job Queue Driver
+ *
+ * Used for development and testing. No external dependencies.
+ * Jobs are stored in memory and lost on process restart.
+ */
+
+import type {
+	Job,
+	JobQueueConfig,
+	JobQueueDriver,
+	QueueMetrics,
+	QueueOptions,
+} from "../types";
+
+// ============= In-Memory Store =============
+
+interface StoredJob {
+	job: Job;
+	expiresAt: number; // Timestamp when job expires (for cleanup)
+}
+
+// ============= Memory Job Queue Driver =============
+
+export class MemoryJobQueueDriver implements JobQueueDriver {
+	private jobStore = new Map<string, StoredJob>();
+	private pendingQueue: string[] = []; // Job IDs in FIFO order
+	private processingSet = new Set<string>(); // Currently claimed jobs
+	private failedQueue: string[] = [];
+	private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+	private jobCounter = 0; // For generating sequential IDs
+	private metrics: QueueMetrics = {
+		enqueued: 0,
+		processed: 0,
+		failed: 0,
+		pending: 0,
+		processing: 0,
+		avgLatency: 0,
+		totalLatency: 0,
+		retried: 0,
+		successRate: 0,
+		avgAttempts: 0,
+	};
+
+	constructor(private config: JobQueueConfig = {}) {
+		this._startCleanup();
+	}
+
+	/**
+	 * Generate a unique job ID
+	 */
+	private generateJobId(): string {
+		this.jobCounter++;
+		return `job:memory:${Date.now()}:${this.jobCounter}`;
+	}
+
+	/**
+	 * Start periodic cleanup of expired jobs
+	 */
+	private _startCleanup(): void {
+		this.cleanupInterval = setInterval(() => {
+			const now = Date.now();
+			for (const [jobId, stored] of this.jobStore.entries()) {
+				if (now > stored.expiresAt) {
+					this.jobStore.delete(jobId);
+				}
+			}
+		}, 30000); // Run every 30 seconds
+	}
+
+	async connect(): Promise<void> {
+		// No-op for in-memory driver
+	}
+
+	async disconnect(): Promise<void> {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = null;
+		}
+		this.jobStore.clear();
+		this.pendingQueue = [];
+		this.processingSet.clear();
+		this.failedQueue = [];
+	}
+
+	async isConnected(): Promise<boolean> {
+		return true; // Always connected for in-memory
+	}
+
+	async enqueue<T = unknown>(
+		name: string,
+		data: T,
+		options?: QueueOptions,
+	): Promise<string> {
+		const jobId = this.generateJobId();
+		const now = new Date();
+
+		const job: Job<T> = {
+			id: jobId,
+			name,
+			data,
+			status: "pending",
+			attempts: 0,
+			maxRetries: options?.maxRetries ?? this.config.maxRetries ?? 3,
+			createdAt: now.toISOString(),
+			updatedAt: now.toISOString(),
+			priority: options?.priority ?? 0,
+			metadata: options?.metadata,
+		};
+
+		// Handle delayed jobs
+		if (options?.delay) {
+			const delayMs =
+				options.delay instanceof Date
+					? options.delay.getTime() - Date.now()
+					: options.delay;
+
+			if (delayMs > 0) {
+				job.status = "delayed";
+				job.scheduledFor = new Date(Date.now() + delayMs).toISOString();
+			}
+		}
+
+		// Store job with expiry (7 days by default)
+		const expiryMs = 7 * 24 * 60 * 60 * 1000;
+		this.jobStore.set(jobId, {
+			job,
+			expiresAt: Date.now() + expiryMs,
+		});
+
+		// Add to pending queue if not delayed
+		if (job.status === "pending") {
+			this.pendingQueue.push(jobId);
+		}
+
+		this.metrics.enqueued++;
+		this.metrics.pending = this.pendingQueue.length;
+
+		return jobId;
+	}
+
+	async claim(count: number, timeout: number): Promise<Job[]> {
+		const now = Date.now();
+		const claimed: Job[] = [];
+
+		// Move delayed jobs to pending if their time has come
+		const toRemove: number[] = [];
+		this.jobStore.forEach((stored, jobId) => {
+			if (
+				stored.job.status === "delayed" &&
+				stored.job.scheduledFor &&
+				new Date(stored.job.scheduledFor).getTime() <= now
+			) {
+				stored.job.status = "pending";
+				if (!this.pendingQueue.includes(jobId)) {
+					this.pendingQueue.push(jobId);
+				}
+			}
+		});
+
+		// Claim up to 'count' pending jobs
+		while (claimed.length < count && this.pendingQueue.length > 0) {
+			const jobId = this.pendingQueue.shift();
+			if (!jobId) break;
+
+			const stored = this.jobStore.get(jobId);
+			if (!stored) continue;
+
+			const job = stored.job;
+			job.status = "processing";
+			job.attempts++;
+			job.startedAt = new Date().toISOString();
+			job.claimExpiresAt = new Date(now + timeout).toISOString();
+			job.updatedAt = new Date().toISOString();
+
+			this.processingSet.add(jobId);
+			claimed.push(job);
+		}
+
+		this.metrics.processing = this.processingSet.size;
+		this.metrics.pending = this.pendingQueue.length;
+
+		return claimed;
+	}
+
+	async complete(jobId: string): Promise<void> {
+		const stored = this.jobStore.get(jobId);
+		if (!stored) return;
+
+		const job = stored.job;
+		const now = new Date();
+
+		job.status = "completed";
+		job.completedAt = now.toISOString();
+		job.updatedAt = now.toISOString();
+
+		// Calculate duration
+		if (job.startedAt) {
+			job.duration =
+				new Date(job.completedAt).getTime() - new Date(job.startedAt).getTime();
+			this.metrics.totalLatency += job.duration;
+		}
+
+		this.processingSet.delete(jobId);
+		this.metrics.processed++;
+		this.metrics.processing = this.processingSet.size;
+
+		// Update average latency
+		if (this.metrics.processed > 0) {
+			this.metrics.avgLatency =
+				this.metrics.totalLatency / this.metrics.processed;
+		}
+
+		// Update success rate
+		const total =
+			this.metrics.processed + this.metrics.failed + this.metrics.pending;
+		if (total > 0) {
+			this.metrics.successRate = this.metrics.processed / total;
+		}
+
+		// Calculate average attempts
+		const allJobs = Array.from(this.jobStore.values())
+			.map((s) => s.job)
+			.filter((j) => j.status === "completed" || j.status === "failed");
+		if (allJobs.length > 0) {
+			const totalAttempts = allJobs.reduce(
+				(sum, j) => sum + (j.attempts || 1),
+				0,
+			);
+			this.metrics.avgAttempts = totalAttempts / allJobs.length;
+		}
+	}
+
+	async fail(jobId: string, error: string, stackTrace?: string): Promise<void> {
+		const stored = this.jobStore.get(jobId);
+		if (!stored) return;
+
+		const job = stored.job;
+		const now = new Date();
+
+		job.error = error;
+		job.stackTrace = stackTrace;
+		job.status = "failed";
+		job.updatedAt = now.toISOString();
+
+		this.processingSet.delete(jobId);
+		this.failedQueue.push(jobId);
+
+		this.metrics.failed++;
+		this.metrics.processing = this.processingSet.size;
+
+		// Update success rate
+		const total =
+			this.metrics.processed + this.metrics.failed + this.metrics.pending;
+		if (total > 0) {
+			this.metrics.successRate = this.metrics.processed / total;
+		}
+	}
+
+	async scheduleRetry(
+		jobId: string,
+		delayMs: number,
+		error: string,
+	): Promise<void> {
+		const stored = this.jobStore.get(jobId);
+		if (!stored) return;
+
+		const job = stored.job;
+		const now = new Date();
+
+		job.error = error;
+		job.status = "delayed";
+		job.scheduledFor = new Date(now.getTime() + delayMs).toISOString();
+		job.updatedAt = now.toISOString();
+
+		// Remove from processing and failed queues
+		this.processingSet.delete(jobId);
+		const failedIndex = this.failedQueue.indexOf(jobId);
+		if (failedIndex >= 0) {
+			this.failedQueue.splice(failedIndex, 1);
+		}
+
+		// Don't add back to pending yet - it will be added when delay expires
+		this.metrics.retried++;
+		this.metrics.processing = this.processingSet.size;
+	}
+
+	async getJob(jobId: string): Promise<Job | null> {
+		const stored = this.jobStore.get(jobId);
+		return stored ? stored.job : null;
+	}
+
+	async getMetrics(): Promise<QueueMetrics> {
+		return { ...this.metrics };
+	}
+
+	async clear(): Promise<void> {
+		this.jobStore.clear();
+		this.pendingQueue = [];
+		this.processingSet.clear();
+		this.failedQueue = [];
+		this.metrics = {
+			enqueued: 0,
+			processed: 0,
+			failed: 0,
+			pending: 0,
+			processing: 0,
+			avgLatency: 0,
+			totalLatency: 0,
+			retried: 0,
+			successRate: 0,
+			avgAttempts: 0,
+		};
+	}
+}