@onebun/core 0.1.2 → 0.1.4

package/src/queue/index.ts

@@ -0,0 +1,118 @@
+/**
+ * Queue Module
+ *
+ * Unified queue system for OneBun.
+ * Supports multiple backends: memory, redis, nats, jetstream.
+ */
+
+// Types
+export type {
+  AckMode,
+  MessageMetadata,
+  Message,
+  PublishOptions,
+  RetryOptions,
+  DeadLetterOptions,
+  SubscribeOptions,
+  QueueEvents,
+  Subscription,
+  OverlapStrategy,
+  ScheduledJobOptions,
+  ScheduledJobInfo,
+  QueueFeature,
+  QueueAdapterType,
+  MessageHandler,
+  QueueAdapter,
+  BuiltInAdapterType,
+  QueueAdapterConstructor,
+  QueueConfig,
+  SubscribeDecoratorOptions,
+  CronDecoratorOptions,
+  IntervalDecoratorOptions,
+  TimeoutDecoratorOptions,
+  MessageExecutionContext,
+  MessageGuard,
+  MessageGuardConstructor,
+} from './types';
+
+// Cron Parser
+export {
+  parseCronExpression,
+  getNextRun,
+  getNextRuns,
+  getMillisecondsUntilNextRun,
+  isValidCronExpression,
+  type CronSchedule,
+} from './cron-parser';
+
+// Cron Expression
+export { CronExpression, type CronExpressionValue } from './cron-expression';
+
+// Pattern Matcher
+export {
+  parseQueuePattern,
+  matchQueuePattern,
+  isQueuePatternMatch,
+  createQueuePatternMatcher,
+  isQueuePattern,
+  getQueuePatternParams,
+  buildFromQueuePattern,
+  findMatchingTopics,
+  type QueuePatternMatch,
+} from './pattern-matcher';
+
+// Guards
+export {
+  MessageExecutionContextImpl,
+  MessageAuthGuard,
+  MessageServiceGuard,
+  MessageHeaderGuard,
+  MessageTraceGuard,
+  MessageAllGuards,
+  MessageAnyGuard,
+  executeMessageGuards,
+  createMessageGuard,
+} from './guards';
+
+// Decorators
+export {
+  Subscribe,
+  Cron,
+  Interval,
+  Timeout,
+  UseMessageGuards,
+  OnQueueReady,
+  OnQueueError,
+  OnMessageFailed,
+  OnMessageReceived,
+  OnMessageProcessed,
+  // Metadata helpers
+  getSubscribeMetadata,
+  getCronMetadata,
+  getIntervalMetadata,
+  getTimeoutMetadata,
+  getMessageGuards,
+  getLifecycleHandlers,
+  hasQueueDecorators,
+  QUEUE_METADATA,
+  type SubscribeMetadata,
+  type CronMetadata,
+  type IntervalMetadata,
+  type TimeoutMetadata,
+  type LifecycleMetadata,
+} from './decorators';
+
+// Scheduler
+export { QueueScheduler, createQueueScheduler } from './scheduler';
+
+// Queue Service
+export {
+  QueueService,
+  QueueServiceTag,
+  makeQueueLayer,
+  createQueueService,
+  resolveAdapterType,
+} from './queue.service';
+
+// Adapters (re-export from adapters folder)
+export * from './adapters';

package/src/queue/pattern-matcher.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Queue Pattern Matcher Tests
+ */
+
+import {
+  describe,
+  it,
+  expect,
+} from 'bun:test';
+
+import {
+  matchQueuePattern,
+  isQueuePatternMatch,
+  createQueuePatternMatcher,
+  isQueuePattern,
+  getQueuePatternParams,
+  buildFromQueuePattern,
+  findMatchingTopics,
+} from './pattern-matcher';
+
+describe('queue-pattern-matcher', () => {
+  describe('matchQueuePattern', () => {
+    it('should match exact strings', () => {
+      const result = matchQueuePattern('orders.created', 'orders.created');
+      expect(result.matched).toBe(true);
+      expect(result.params).toEqual({});
+    });
+
+    it('should not match different strings', () => {
+      const result = matchQueuePattern('orders.created', 'orders.updated');
+      expect(result.matched).toBe(false);
+    });
+
+    it('should match single-level wildcard (*)', () => {
+      const result = matchQueuePattern('orders.*', 'orders.created');
+      expect(result.matched).toBe(true);
+      expect(result.params).toEqual({});
+    });
+
+    it('should match single-level wildcard in the middle', () => {
+      const result = matchQueuePattern('orders.*.status', 'orders.123.status');
+      expect(result.matched).toBe(true);
+    });
+
+    it('should not match single-level wildcard with extra segments', () => {
+      const result = matchQueuePattern('orders.*', 'orders.123.status');
+      expect(result.matched).toBe(false);
+    });
+
+    it('should match multi-level wildcard (#)', () => {
+      const result = matchQueuePattern('events.#', 'events.user.created');
+      expect(result.matched).toBe(true);
+    });
+
+    it('should match multi-level wildcard with many segments', () => {
+      const result = matchQueuePattern('events.#', 'events.user.order.payment.completed');
+      expect(result.matched).toBe(true);
+    });
+
+    it('should match multi-level wildcard at end (empty)', () => {
+      // events.# should match events.anything, not just 'events'
+      const result = matchQueuePattern('events.#', 'events.');
+      expect(result.matched).toBe(true);
+    });
+
+    it('should extract named parameters', () => {
+      const result = matchQueuePattern('orders.{orderId}', 'orders.123');
+      expect(result.matched).toBe(true);
+      expect(result.params).toEqual({ orderId: '123' });
+    });
+
+    it('should extract multiple parameters', () => {
+      const result = matchQueuePattern('users.{userId}.orders.{orderId}', 'users.456.orders.123');
+      expect(result.matched).toBe(true);
+      expect(result.params).toEqual({ userId: '456', orderId: '123' });
+    });
+
+    it('should handle combined wildcard and parameters', () => {
+      const result = matchQueuePattern('service.{name}.*', 'service.auth.login');
+      expect(result.matched).toBe(true);
+      expect(result.params).toEqual({ name: 'auth' });
+    });
+
+    it('should not match when parameter value contains separator', () => {
+      const result = matchQueuePattern('orders.{id}', 'orders.123.extra');
+      expect(result.matched).toBe(false);
+    });
+  });
+
+  describe('isQueuePatternMatch', () => {
+    it('should return true for matching patterns', () => {
+      expect(isQueuePatternMatch('orders.*', 'orders.created')).toBe(true);
+      expect(isQueuePatternMatch('events.#', 'events.user.created')).toBe(true);
+    });
+
+    it('should return false for non-matching patterns', () => {
+      expect(isQueuePatternMatch('orders.*', 'users.created')).toBe(false);
+    });
+  });
+
+  describe('createQueuePatternMatcher', () => {
+    it('should create reusable matcher function', () => {
+      const matcher = createQueuePatternMatcher('orders.{orderId}.status');
+
+      const result1 = matcher('orders.123.status');
+      expect(result1.matched).toBe(true);
+      expect(result1.params).toEqual({ orderId: '123' });
+
+      const result2 = matcher('orders.456.status');
+      expect(result2.matched).toBe(true);
+      expect(result2.params).toEqual({ orderId: '456' });
+
+      const result3 = matcher('orders.123.other');
+      expect(result3.matched).toBe(false);
+    });
+
+    it('should optimize exact match patterns', () => {
+      const matcher = createQueuePatternMatcher('orders.created');
+
+      expect(matcher('orders.created').matched).toBe(true);
+      expect(matcher('orders.updated').matched).toBe(false);
+    });
+  });
+
+  describe('isQueuePattern', () => {
+    it('should return true for single-level wildcard patterns', () => {
+      expect(isQueuePattern('orders.*')).toBe(true);
+    });
+
+    it('should return true for multi-level wildcard patterns', () => {
+      expect(isQueuePattern('events.#')).toBe(true);
+    });
+
+    it('should return true for parameter patterns', () => {
+      expect(isQueuePattern('orders.{id}')).toBe(true);
+    });
+
+    it('should return false for literal strings', () => {
+      expect(isQueuePattern('orders.created')).toBe(false);
+    });
+  });
+
+  describe('getQueuePatternParams', () => {
+    it('should extract parameter names', () => {
+      const params = getQueuePatternParams('users.{userId}.orders.{orderId}');
+      expect(params).toEqual(['userId', 'orderId']);
+    });
+
+    it('should return empty array for patterns without parameters', () => {
+      const params = getQueuePatternParams('orders.*');
+      expect(params).toEqual([]);
+    });
+  });
+
+  describe('buildFromQueuePattern', () => {
+    it('should build topic from pattern and params', () => {
+      const result = buildFromQueuePattern('orders.{id}.status', { id: '123' });
+      expect(result).toBe('orders.123.status');
+    });
+
+    it('should handle multiple parameters', () => {
+      const result = buildFromQueuePattern('users.{uid}.orders.{oid}', { uid: '456', oid: '123' });
+      expect(result).toBe('users.456.orders.123');
+    });
+
+    it('should remove wildcards', () => {
+      const result = buildFromQueuePattern('orders.*.status', {});
+      expect(result).toBe('orders..status');
+    });
+  });
+
+  describe('findMatchingTopics', () => {
+    it('should find all matching topics', () => {
+      const topics = ['orders.created', 'orders.updated', 'users.created', 'orders.deleted'];
+      const matching = findMatchingTopics('orders.*', topics);
+      expect(matching).toEqual(['orders.created', 'orders.updated', 'orders.deleted']);
+    });
+
+    it('should find topics with multi-level wildcard', () => {
+      const topics = ['events.user.created', 'events.order.created', 'logs.info', 'events.deep.nested.event'];
+      const matching = findMatchingTopics('events.#', topics);
+      expect(matching).toEqual(['events.user.created', 'events.order.created', 'events.deep.nested.event']);
+    });
+
+    it('should return empty array when nothing matches', () => {
+      const topics = ['users.created', 'users.updated'];
+      const matching = findMatchingTopics('orders.*', topics);
+      expect(matching).toEqual([]);
+    });
+  });
+});

package/src/queue/pattern-matcher.ts

@@ -0,0 +1,252 @@
+/**
+ * Queue Pattern Matcher
+ *
+ * Pattern matching for queue subscriptions.
+ * Supports both AMQP-style and MQTT-style wildcards.
+ *
+ * Supported patterns:
+ * - Exact match: 'orders.created' matches only 'orders.created'
+ * - Single-level wildcard (*): 'orders.*' matches 'orders.created', 'orders.updated'
+ * - Multi-level wildcard (#): 'events.#' matches 'events.user.created', 'events.order.shipped'
+ * - Named parameters: 'orders.{orderId}' extracts orderId from matching messages
+ *
+ * Separator: '.' (dot) is used as the separator (like AMQP/MQTT)
+ *
+ * @example
+ * ```typescript
+ * // Single-level wildcard
+ * matchQueuePattern('orders.*', 'orders.created')    // true
+ * matchQueuePattern('orders.*', 'orders.created.new') // false
+ *
+ * // Multi-level wildcard
+ * matchQueuePattern('events.#', 'events.user.created') // true
+ * matchQueuePattern('events.#', 'events')              // true
+ *
+ * // Named parameters
+ * matchQueuePattern('orders.{id}.status', 'orders.123.status')
+ * // { matched: true, params: { id: '123' } }
+ * ```
+ */
+
+/**
+ * Pattern match result
+ */
+export interface QueuePatternMatch {
+  matched: boolean;
+  params: Record<string, string>;
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Parse a queue pattern into a regex and extract parameter names
+ *
+ * @param pattern - Pattern string with wildcards and/or parameters
+ * @returns Object with regex and parameter names
+ */
+export function parseQueuePattern(pattern: string): {
+  regex: RegExp;
+  paramNames: string[];
+} {
+  const paramNames: string[] = [];
+  let regexStr = '^';
+  let i = 0;
+
+  while (i < pattern.length) {
+    const char = pattern[i];
+
+    if (char === '#') {
+      // Multi-level wildcard: matches any number of segments (including zero)
+      // # must be at the end or followed by separator
+      if (i === pattern.length - 1) {
+        regexStr += '.*';
+      } else if (pattern[i + 1] === '.') {
+        regexStr += '(?:[^.]+\\.)*';
+        i++; // Skip the dot
+      } else {
+        // Invalid # position, treat as literal
+        regexStr += escapeRegex(char);
+      }
+      i++;
+    } else if (char === '*') {
+      // Single-level wildcard: matches exactly one segment
+      regexStr += '[^.]+';
+      i++;
+    } else if (char === '{') {
+      // Named parameter: {paramName}
+      const endIndex = pattern.indexOf('}', i);
+      if (endIndex === -1) {
+        // Invalid pattern, treat as literal
+        regexStr += escapeRegex(char);
+        i++;
+      } else {
+        const paramName = pattern.substring(i + 1, endIndex);
+        paramNames.push(paramName);
+        // Match one segment
+        regexStr += '([^.]+)';
+        i = endIndex + 1;
+      }
+    } else if (char === '.') {
+      // Separator
+      regexStr += '\\.';
+      i++;
+    } else {
+      // Literal character
+      regexStr += escapeRegex(char);
+      i++;
+    }
+  }
+
+  regexStr += '$';
+
+  return {
+    regex: new RegExp(regexStr),
+    paramNames,
+  };
+}
+
+/**
+ * Match a topic against a pattern
+ *
+ * @param pattern - Pattern string with wildcards and/or parameters
+ * @param topic - Topic to match
+ * @returns Match result with extracted parameters
+ *
+ * @example
+ * ```typescript
+ * matchQueuePattern('orders.*', 'orders.created')
+ * // { matched: true, params: {} }
+ *
+ * matchQueuePattern('orders.{orderId}', 'orders.123')
+ * // { matched: true, params: { orderId: '123' } }
+ *
+ * matchQueuePattern('events.#', 'events.user.created')
+ * // { matched: true, params: {} }
+ * ```
+ */
+export function matchQueuePattern(pattern: string, topic: string): QueuePatternMatch {
+  // Exact match fast path
+  if (pattern === topic) {
+    return { matched: true, params: {} };
+  }
+
+  // Check if pattern has any special characters
+  if (!pattern.includes('*') && !pattern.includes('#') && !pattern.includes('{')) {
+    // No wildcards or parameters, must be exact match
+    return { matched: false, params: {} };
+  }
+
+  const { regex, paramNames } = parseQueuePattern(pattern);
+  const match = topic.match(regex);
+
+  if (!match) {
+    return { matched: false, params: {} };
+  }
+
+  // Extract parameters
+  const params: Record<string, string> = {};
+  for (let i = 0; i < paramNames.length; i++) {
+    params[paramNames[i]] = match[i + 1];
+  }
+
+  return { matched: true, params };
+}
+
+/**
+ * Check if a pattern matches a topic (without extracting parameters)
+ */
+export function isQueuePatternMatch(pattern: string, topic: string): boolean {
+  return matchQueuePattern(pattern, topic).matched;
+}
+
+/**
+ * Create a pattern matcher function for a specific pattern
+ * (pre-compiles the regex for better performance)
+ *
+ * @param pattern - Pattern string
+ * @returns Function that matches topics against the pattern
+ */
+export function createQueuePatternMatcher(pattern: string): (topic: string) => QueuePatternMatch {
+  // Exact match fast path
+  if (!pattern.includes('*') && !pattern.includes('#') && !pattern.includes('{')) {
+    return (topic: string) => ({
+      matched: pattern === topic,
+      params: {},
+    });
+  }
+
+  const { regex, paramNames } = parseQueuePattern(pattern);
+
+  return (topic: string): QueuePatternMatch => {
+    // Exact match fast path
+    if (pattern === topic) {
+      return { matched: true, params: {} };
+    }
+
+    const match = topic.match(regex);
+
+    if (!match) {
+      return { matched: false, params: {} };
+    }
+
+    const params: Record<string, string> = {};
+    for (let i = 0; i < paramNames.length; i++) {
+      params[paramNames[i]] = match[i + 1];
+    }
+
+    return { matched: true, params };
+  };
+}
+
+/**
+ * Check if a string is a pattern (contains wildcards or parameters)
+ */
+export function isQueuePattern(value: string): boolean {
+  return value.includes('*') || value.includes('#') || value.includes('{');
+}
+
+/**
+ * Extract parameter names from a pattern
+ */
+export function getQueuePatternParams(pattern: string): string[] {
+  const params: string[] = [];
+  const regex = /\{([^}]+)\}/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(pattern)) !== null) {
+    params.push(match[1]);
+  }
+
+  return params;
+}
+
+/**
+ * Build a topic from a pattern and parameters
+ */
+export function buildFromQueuePattern(pattern: string, params: Record<string, string>): string {
+  let result = pattern;
+
+  // Replace parameters with values
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(`{${key}}`, value);
+  }
+
+  // Remove wildcards (they shouldn't be in built topics)
+  result = result.replace(/[*#]/g, '');
+
+  return result;
+}
+
+/**
+ * Find all topics that match a pattern
+ */
+export function findMatchingTopics(pattern: string, topics: string[]): string[] {
+  const matcher = createQueuePatternMatcher(pattern);
+
+  return topics.filter((topic) => matcher(topic).matched);
+}