@onebun/core 0.1.2 → 0.1.4

package/src/queue/types.ts

@@ -0,0 +1,502 @@
+/**
+ * Unified Queue System Types
+ *
+ * Common types and interfaces for all queue adapters (memory, redis, nats, jetstream).
+ */
+
+// ============================================================================
+// Ack Modes
+// ============================================================================
+
+/**
+ * Message acknowledgment mode
+ * - 'auto': Message is automatically acknowledged after successful handler execution
+ * - 'manual': Handler must call message.ack() or message.nack() explicitly
+ */
+export type AckMode = 'auto' | 'manual';
+
+// ============================================================================
+// Message Types
+// ============================================================================
+
+/**
+ * Message metadata for inter-service communication, guards, and authorization
+ */
+export interface MessageMetadata {
+  /** Custom headers */
+  headers?: Record<string, string>;
+
+  /** Authorization token (e.g., "Bearer xxx") */
+  authorization?: string;
+
+  /** ID of the calling service */
+  serviceId?: string;
+
+  /** Trace ID for distributed tracing (integration with @onebun/trace) */
+  traceId?: string;
+
+  /** Span ID for distributed tracing */
+  spanId?: string;
+
+  /** Parent span ID for distributed tracing */
+  parentSpanId?: string;
+
+  /** Additional data (for guards and custom logic) */
+  [key: string]: unknown;
+}
+
+/**
+ * Queue message interface
+ */
+export interface Message<T = unknown> {
+  /** Unique message ID */
+  id: string;
+
+  /** Message pattern/topic */
+  pattern: string;
+
+  /** Message payload */
+  data: T;
+
+  /** Message timestamp (ms since epoch) */
+  timestamp: number;
+
+  /** Whether this message was redelivered */
+  redelivered?: boolean;
+
+  /** Message metadata for inter-service communication */
+  metadata: MessageMetadata;
+
+  /** Current attempt number (for retries) */
+  attempt?: number;
+
+  /** Maximum attempts allowed */
+  maxAttempts?: number;
+
+  /**
+   * Acknowledge the message (for manual ack mode)
+   */
+  ack(): Promise<void>;
+
+  /**
+   * Negative acknowledge the message (for manual ack mode)
+   * @param requeue - Whether to requeue the message for reprocessing
+   */
+  nack(requeue?: boolean): Promise<void>;
+}
+
+// ============================================================================
+// Publish Options
+// ============================================================================
+
+/**
+ * Options for publishing messages
+ */
+export interface PublishOptions {
+  /** Delay before the message is delivered (ms) */
+  delay?: number;
+
+  /** Message priority (higher = more important) */
+  priority?: number;
+
+  /** Custom message ID */
+  messageId?: string;
+
+  /** Metadata for inter-service communication */
+  metadata?: Partial<MessageMetadata>;
+
+  /** Repeat options for scheduled jobs */
+  repeat?: {
+    /** Cron expression */
+    pattern?: string;
+    /** Interval in milliseconds */
+    every?: number;
+    /** Maximum number of repetitions */
+    limit?: number;
+    /** End date for repetitions */
+    endDate?: Date;
+  };
+}
+
+// ============================================================================
+// Subscribe Options
+// ============================================================================
+
+/**
+ * Retry configuration
+ */
+export interface RetryOptions {
+  /** Maximum number of attempts */
+  attempts?: number;
+  /** Backoff strategy */
+  backoff?: 'fixed' | 'linear' | 'exponential';
+  /** Base delay in milliseconds */
+  delay?: number;
+}
+
+/**
+ * Dead Letter Queue configuration
+ */
+export interface DeadLetterOptions {
+  /** Queue name for dead letters */
+  queue: string;
+  /** Maximum retries before sending to DLQ */
+  maxRetries?: number;
+}
+
+/**
+ * Options for subscribing to messages
+ */
+export interface SubscribeOptions {
+  /** Acknowledgment mode ('auto' by default) */
+  ackMode?: AckMode;
+
+  /** Number of messages to process in parallel */
+  prefetch?: number;
+
+  /** Consumer group (for load balancing between instances) */
+  group?: string;
+
+  /** Retry settings (optional extension) */
+  retry?: RetryOptions;
+
+  /** Dead Letter Queue settings (optional extension) */
+  deadLetter?: DeadLetterOptions;
+}
+
+// ============================================================================
+// Lifecycle Events
+// ============================================================================
+
+/**
+ * Queue lifecycle events
+ */
+export interface QueueEvents {
+  /** Called when the queue adapter is ready */
+  onReady?: () => void;
+
+  /** Called when an error occurs */
+  onError?: (error: Error) => void;
+
+  /** Called when a message is received */
+  onMessageReceived?: (message: Message) => void;
+
+  /** Called when a message is processed successfully */
+  onMessageProcessed?: (message: Message) => void;
+
+  /** Called when message processing fails */
+  onMessageFailed?: (message: Message, error: Error) => void;
+}
+
+// ============================================================================
+// Subscription
+// ============================================================================
+
+/**
+ * Subscription handle returned by subscribe()
+ */
+export interface Subscription {
+  /** Unsubscribe from the pattern */
+  unsubscribe(): Promise<void>;
+
+  /** Pause receiving messages */
+  pause(): void;
+
+  /** Resume receiving messages */
+  resume(): void;
+
+  /** The pattern this subscription is for */
+  readonly pattern: string;
+
+  /** Whether the subscription is active */
+  readonly isActive: boolean;
+}
+
+// ============================================================================
+// Scheduled Jobs
+// ============================================================================
+
+/**
+ * Overlap strategy for scheduled jobs
+ * - 'skip': Skip execution if previous job is still running
+ * - 'queue': Queue as a regular message even if previous is running
+ */
+export type OverlapStrategy = 'skip' | 'queue';
+
+/**
+ * Options for scheduled jobs
+ */
+export interface ScheduledJobOptions {
+  /** Pattern to publish to */
+  pattern: string;
+
+  /** Data to include in the message */
+  data?: unknown;
+
+  /** Schedule configuration */
+  schedule: {
+    /** Cron expression */
+    cron?: string;
+    /** Interval in milliseconds */
+    every?: number;
+  };
+
+  /** Metadata to include in messages */
+  metadata?: Partial<MessageMetadata>;
+
+  /** What to do if previous job is still running */
+  overlapStrategy?: OverlapStrategy;
+}
+
+/**
+ * Information about a scheduled job
+ */
+export interface ScheduledJobInfo {
+  /** Job name */
+  name: string;
+
+  /** Pattern to publish to */
+  pattern: string;
+
+  /** Schedule configuration */
+  schedule: {
+    cron?: string;
+    every?: number;
+  };
+
+  /** Next scheduled run time */
+  nextRun?: Date;
+
+  /** Last run time */
+  lastRun?: Date;
+
+  /** Whether the job is currently running */
+  isRunning?: boolean;
+}
+
+// ============================================================================
+// Queue Features
+// ============================================================================
+
+/**
+ * Features that queue adapters may support
+ */
+export type QueueFeature =
+  | 'delayed-messages'
+  | 'priority'
+  | 'dead-letter-queue'
+  | 'retry'
+  | 'scheduled-jobs'
+  | 'consumer-groups'
+  | 'pattern-subscriptions';
+
+// ============================================================================
+// Queue Adapter Interface
+// ============================================================================
+
+/**
+ * Queue adapter type
+ */
+export type QueueAdapterType = 'memory' | 'redis' | 'nats' | 'jetstream';
+
+/**
+ * Message handler function
+ */
+export type MessageHandler<T = unknown> = (message: Message<T>) => Promise<void>;
+
+/**
+ * Unified Queue Adapter interface
+ *
+ * All queue backends (memory, redis, nats, jetstream) implement this interface.
+ * Configuration differs, but the API remains the same.
+ */
+export interface QueueAdapter {
+  /** Adapter name */
+  readonly name: string;
+
+  /** Adapter type */
+  readonly type: QueueAdapterType;
+
+  // Lifecycle
+  /** Connect to the queue backend */
+  connect(): Promise<void>;
+
+  /** Disconnect from the queue backend */
+  disconnect(): Promise<void>;
+
+  /** Check if connected */
+  isConnected(): boolean;
+
+  // Publishing
+  /**
+   * Publish a message to a pattern
+   * @returns Message ID
+   */
+  publish<T>(pattern: string, data: T, options?: PublishOptions): Promise<string>;
+
+  /**
+   * Publish multiple messages in a batch
+   * @returns Array of message IDs
+   */
+  publishBatch<T>(
+    messages: Array<{ pattern: string; data: T; options?: PublishOptions }>
+  ): Promise<string[]>;
+
+  // Subscribing
+  /**
+   * Subscribe to messages matching a pattern
+   * Supports wildcards: 'orders.*', 'events.user.#'
+   */
+  subscribe<T>(
+    pattern: string,
+    handler: MessageHandler<T>,
+    options?: SubscribeOptions
+  ): Promise<Subscription>;
+
+  // Scheduled Jobs
+  /** Add a scheduled job */
+  addScheduledJob(name: string, options: ScheduledJobOptions): Promise<void>;
+
+  /** Remove a scheduled job */
+  removeScheduledJob(name: string): Promise<boolean>;
+
+  /** Get all scheduled jobs */
+  getScheduledJobs(): Promise<ScheduledJobInfo[]>;
+
+  // Feature Support
+  /** Check if a feature is supported by this adapter */
+  supports(feature: QueueFeature): boolean;
+
+  // Events
+  /** Register an event handler */
+  on<E extends keyof QueueEvents>(event: E, handler: NonNullable<QueueEvents[E]>): void;
+
+  /** Unregister an event handler */
+  off<E extends keyof QueueEvents>(event: E, handler: NonNullable<QueueEvents[E]>): void;
+}
+
+// ============================================================================
+// Queue Configuration
+// ============================================================================
+
+/**
+ * Built-in adapter types
+ */
+export type BuiltInAdapterType = 'memory' | 'redis';
+
+/**
+ * Queue adapter constructor
+ */
+export interface QueueAdapterConstructor {
+  new (options?: unknown): QueueAdapter;
+}
+
+/**
+ * Queue configuration options
+ */
+export interface QueueConfig {
+  /** Adapter type or custom adapter class */
+  adapter: BuiltInAdapterType | QueueAdapterConstructor;
+
+  /** Adapter-specific options */
+  options?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Decorator Metadata Types
+// ============================================================================
+
+/**
+ * Subscribe decorator options
+ */
+export interface SubscribeDecoratorOptions extends SubscribeOptions {
+  /** Pattern is required and comes from decorator argument */
+}
+
+/**
+ * Cron decorator options
+ */
+export interface CronDecoratorOptions {
+  /** Pattern to publish to when cron triggers */
+  pattern: string;
+
+  /** Metadata to include in messages */
+  metadata?: Partial<MessageMetadata>;
+
+  /** Job name (defaults to method name) */
+  name?: string;
+
+  /** Overlap strategy */
+  overlapStrategy?: OverlapStrategy;
+}
+
+/**
+ * Interval decorator options
+ */
+export interface IntervalDecoratorOptions {
+  /** Pattern to publish to when interval triggers */
+  pattern: string;
+
+  /** Metadata to include in messages */
+  metadata?: Partial<MessageMetadata>;
+
+  /** Job name (defaults to method name) */
+  name?: string;
+}
+
+/**
+ * Timeout decorator options
+ */
+export interface TimeoutDecoratorOptions {
+  /** Pattern to publish to when timeout fires */
+  pattern: string;
+
+  /** Metadata to include in messages */
+  metadata?: Partial<MessageMetadata>;
+
+  /** Job name (defaults to method name) */
+  name?: string;
+}
+
+// ============================================================================
+// Guard Types
+// ============================================================================
+
+/**
+ * Message execution context for guards
+ */
+export interface MessageExecutionContext {
+  /** Get the message */
+  getMessage<T>(): Message<T>;
+
+  /** Get message metadata */
+  getMetadata(): MessageMetadata;
+
+  /** Get the pattern */
+  getPattern(): string;
+
+  /** Get the handler function */
+  getHandler(): (...args: unknown[]) => unknown;
+
+  /** Get the class containing the handler */
+  getClass(): new (...args: unknown[]) => unknown;
+}
+
+/** Handler function type alias */
+export type HandlerFunction = (...args: unknown[]) => unknown;
+
+/**
+ * Message guard interface
+ */
+export interface MessageGuard {
+  /**
+   * Determine if the message should be processed
+   * @returns true to allow processing, false to reject
+   */
+  canActivate(context: MessageExecutionContext): boolean | Promise<boolean>;
+}
+
+/**
+ * Guard constructor type
+ */
+export type MessageGuardConstructor = new (...args: unknown[]) => MessageGuard;

package/src/redis/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Redis Module
+ *
+ * Redis client and shared provider for OneBun.
+ */
+
+export * from './redis-client';
+export * from './shared-redis';

package/src/{env-resolver.ts → service-client/env-resolver.ts}

@@ -1,4 +1,4 @@
-import type { EnvOverrides, EnvOverrideValue } from './multi-service.types';
+import type { EnvOverrides, EnvOverrideValue } from '../application/multi-service.types';
 
 import {
   type EnvLoadOptions,

package/src/service-client/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Service Client Module
+ *
+ * Type-safe service definitions and clients for inter-service communication.
+ */
+
+export * from './service-client.types';
+export * from './service-definition';
+export * from './service-client';
+export * from './env-resolver';

package/src/{service-client.test.ts → service-client/service-client.test.ts}

@@ -15,10 +15,11 @@ import {
   Post,
   Body,
   Query,
-} from './decorators';
+} from '../decorators/decorators';
+import { HttpMethod } from '../types';
+
 import { createServiceClient, getServiceUrl } from './service-client';
 import { createServiceDefinition } from './service-definition';
-import { HttpMethod } from './types';
 
 // Test controller with various parameter types
 @Controller('/users')

package/src/{service-client.ts → service-client/service-client.ts}

@@ -7,7 +7,7 @@ import type {
 
 import { HttpClient, type HttpMethod as RequestsHttpMethod } from '@onebun/requests';
 
-import { ParamType } from './types';
+import { ParamType } from '../types';
 
 /**
  * Build request parameters from endpoint metadata and arguments

package/src/{service-definition.test.ts → service-client/service-definition.test.ts}

@@ -11,9 +11,10 @@ import {
   Param,
   Post,
   Body,
-} from './decorators';
+} from '../decorators/decorators';
+import { HttpMethod } from '../types';
+
 import { createServiceDefinition } from './service-definition';
-import { HttpMethod } from './types';
 
 // Test controller
 @Controller('/users')

package/src/{service-definition.ts → service-client/service-definition.ts}

@@ -1,5 +1,5 @@
-import { getControllerMetadata, getModuleMetadata } from './decorators';
-import { type HttpMethod, type ParamMetadata } from './types';
+import { getControllerMetadata, getModuleMetadata } from '../decorators/decorators';
+import { type HttpMethod, type ParamMetadata } from '../types';
 
 /**
  * Metadata for a single endpoint

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Testing Utilities
+ *
+ * Helpers for testing OneBun applications.
+ */
+
+export * from './test-utils';

package/src/types.ts

@@ -6,7 +6,7 @@ import type { Logger } from '@onebun/logger';
 /**
  * Base interface for all OneBun services
  */
-export interface Service {
+export interface ServiceInterface {
   readonly [key: string]: unknown;
 }
 
@@ -17,7 +17,7 @@ export interface ModuleProviders {
   /**
    * Services to provide
    */
-  providers?: Service[];
+  providers?: ServiceInterface[];
 
   /**
    * Controllers to include
@@ -27,7 +27,7 @@ export interface ModuleProviders {
   /**
    * Modules to import
    */
-  imports?: Module[];
+  imports?: ModuleInstance[];
 
   /**
    * Services to export to parent modules
@@ -36,9 +36,9 @@ export interface ModuleProviders {
 }
 
 /**
- * Module interface
+ * Module instance interface
  */
-export interface Module {
+export interface ModuleInstance {
   /**
    * Setup the module
    */
@@ -272,6 +272,11 @@ export interface ApplicationOptions {
    */
   websocket?: WebSocketApplicationOptions;
 
+  /**
+   * Queue configuration
+   */
+  queue?: QueueApplicationOptions;
+
   /**
    * Enable graceful shutdown on SIGTERM/SIGINT
    * When enabled, the application will cleanly shutdown on process signals,
@@ -282,6 +287,30 @@ export interface ApplicationOptions {
   gracefulShutdown?: boolean;
 }
 
+/**
+ * Queue adapter type for application configuration
+ */
+export type QueueAdapterType = 'memory' | 'redis';
+
+/**
+ * Queue configuration for OneBunApplication
+ */
+export interface QueueApplicationOptions {
+  /** Enable/disable queue (default: auto - enabled if handlers exist) */
+  enabled?: boolean;
+  /** Adapter type or custom adapter instance */
+  adapter?: QueueAdapterType;
+  /** Redis-specific options (only used when adapter is 'redis') */
+  redis?: {
+    /** Use shared Redis provider instead of dedicated connection */
+    useSharedProvider?: boolean;
+    /** Redis connection URL (required if not using shared provider) */
+    url?: string;
+    /** Key prefix for Redis keys */
+    prefix?: string;
+  };
+}
+
 /**
  * WebSocket storage type
  */