flowfn 0.0.1

package/src/patterns/priority.ts

@@ -0,0 +1,146 @@
+/**
+ * Priority queue pattern for FlowFn
+ */
+
+export interface PriorityItem<T> {
+  value: T;
+  priority: number;
+}
+
+/**
+ * Priority queue implementation using binary heap
+ */
+export class PriorityQueue<T> {
+  private heap: PriorityItem<T>[] = [];
+  private compareFn: (a: number, b: number) => number;
+
+  constructor(mode: "min" | "max" = "max") {
+    // Max heap by default (higher priority first)
+    this.compareFn =
+      mode === "max"
+        ? (a, b) => a - b // Max heap: parent >= children
+        : (a, b) => b - a; // Min heap: parent <= children
+  }
+
+  /**
+   * Add item with priority
+   */
+  enqueue(value: T, priority: number): void {
+    this.heap.push({ value, priority });
+    this.bubbleUp(this.heap.length - 1);
+  }
+
+  /**
+   * Remove and return highest priority item
+   */
+  dequeue(): T | undefined {
+    if (this.heap.length === 0) return undefined;
+    if (this.heap.length === 1) return this.heap.pop()!.value;
+
+    const result = this.heap[0];
+    this.heap[0] = this.heap.pop()!;
+    this.bubbleDown(0);
+
+    return result.value;
+  }
+
+  /**
+   * Peek at highest priority item without removing
+   */
+  peek(): T | undefined {
+    return this.heap[0]?.value;
+  }
+
+  /**
+   * Get queue size
+   */
+  size(): number {
+    return this.heap.length;
+  }
+
+  /**
+   * Check if queue is empty
+   */
+  isEmpty(): boolean {
+    return this.heap.length === 0;
+  }
+
+  /**
+   * Clear the queue
+   */
+  clear(): void {
+    this.heap = [];
+  }
+
+  /**
+   * Convert to array (sorted by priority)
+   */
+  toArray(): T[] {
+    const copy = [...this.heap];
+    const result: T[] = [];
+
+    while (this.heap.length > 0) {
+      result.push(this.dequeue()!);
+    }
+
+    this.heap = copy;
+    return result;
+  }
+
+  private bubbleUp(index: number): void {
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+
+      if (
+        this.compareFn(
+          this.heap[index].priority,
+          this.heap[parentIndex].priority
+        ) <= 0
+      ) {
+        break;
+      }
+
+      [this.heap[index], this.heap[parentIndex]] = [
+        this.heap[parentIndex],
+        this.heap[index],
+      ];
+      index = parentIndex;
+    }
+  }
+
+  private bubbleDown(index: number): void {
+    while (true) {
+      const leftChild = 2 * index + 1;
+      const rightChild = 2 * index + 2;
+      let largest = index;
+
+      if (
+        leftChild < this.heap.length &&
+        this.compareFn(
+          this.heap[leftChild].priority,
+          this.heap[largest].priority
+        ) > 0
+      ) {
+        largest = leftChild;
+      }
+
+      if (
+        rightChild < this.heap.length &&
+        this.compareFn(
+          this.heap[rightChild].priority,
+          this.heap[largest].priority
+        ) > 0
+      ) {
+        largest = rightChild;
+      }
+
+      if (largest === index) break;
+
+      [this.heap[index], this.heap[largest]] = [
+        this.heap[largest],
+        this.heap[index],
+      ];
+      index = largest;
+    }
+  }
+}

package/src/patterns/rate-limit.ts

@@ -0,0 +1,290 @@
+/**
+ * Rate limiting pattern for FlowFn
+ */
+
+export interface RateLimitOptions {
+  /**
+   * Maximum number of requests allowed
+   */
+  limit: number;
+
+  /**
+   * Time window in milliseconds
+   */
+  window: number;
+
+  /**
+   * Strategy for handling rate limit exceeded
+   */
+  strategy?: "throw" | "delay" | "drop";
+
+  /**
+   * Custom key generator for partitioning rate limits
+   */
+  keyGenerator?: (...args: any[]) => string;
+}
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  resetAt: number;
+  retryAfter?: number;
+}
+
+export class RateLimiter {
+  private counters: Map<string, { count: number; resetAt: number }> = new Map();
+  private options: RateLimitOptions;
+
+  constructor(options: RateLimitOptions) {
+    this.options = {
+      strategy: "throw",
+      ...options,
+    };
+  }
+
+  /**
+   * Check if request is allowed
+   */
+  async check(key: string = "default"): Promise<RateLimitResult> {
+    const now = Date.now();
+    let counter = this.counters.get(key);
+
+    // Reset counter if window has passed
+    if (!counter || now >= counter.resetAt) {
+      counter = {
+        count: 0,
+        resetAt: now + this.options.window,
+      };
+      this.counters.set(key, counter);
+    }
+
+    const allowed = counter.count < this.options.limit;
+    const remaining = Math.max(0, this.options.limit - counter.count);
+    const retryAfter = allowed ? undefined : counter.resetAt - now;
+
+    if (allowed) {
+      counter.count++;
+    }
+
+    return {
+      allowed,
+      remaining,
+      resetAt: counter.resetAt,
+      retryAfter,
+    };
+  }
+
+  /**
+   * Execute a function with rate limiting
+   */
+  async execute<T>(fn: () => Promise<T>, key: string = "default"): Promise<T> {
+    const result = await this.check(key);
+
+    if (!result.allowed) {
+      switch (this.options.strategy) {
+        case "throw":
+          throw new Error(
+            `Rate limit exceeded. Retry after ${result.retryAfter}ms`
+          );
+
+        case "delay":
+          await new Promise((resolve) =>
+            setTimeout(resolve, result.retryAfter)
+          );
+          return this.execute(fn, key);
+
+        case "drop":
+          throw new Error("Request dropped due to rate limit");
+
+        default:
+          throw new Error("Unknown rate limit strategy");
+      }
+    }
+
+    return fn();
+  }
+
+  /**
+   * Clear all rate limit counters
+   */
+  reset(): void {
+    this.counters.clear();
+  }
+
+  /**
+   * Clear rate limit counter for specific key
+   */
+  resetKey(key: string): void {
+    this.counters.delete(key);
+  }
+
+  /**
+   * Get current limit info for a key
+   */
+  getInfo(key: string = "default"): RateLimitResult {
+    const now = Date.now();
+    const counter = this.counters.get(key);
+
+    if (!counter || now >= counter.resetAt) {
+      return {
+        allowed: true,
+        remaining: this.options.limit,
+        resetAt: now + this.options.window,
+      };
+    }
+
+    const allowed = counter.count < this.options.limit;
+    const remaining = Math.max(0, this.options.limit - counter.count);
+
+    return {
+      allowed,
+      remaining,
+      resetAt: counter.resetAt,
+      retryAfter: allowed ? undefined : counter.resetAt - now,
+    };
+  }
+}
+
+/**
+ * Create a rate limiter
+ */
+export function createRateLimiter(options: RateLimitOptions): RateLimiter {
+  return new RateLimiter(options);
+}
+
+/**
+ * Sliding window rate limiter (more accurate)
+ */
+export class SlidingWindowRateLimiter {
+  private requests: Map<string, number[]> = new Map();
+  private options: RateLimitOptions;
+
+  constructor(options: RateLimitOptions) {
+    this.options = options;
+  }
+
+  async check(key: string = "default"): Promise<RateLimitResult> {
+    const now = Date.now();
+    const windowStart = now - this.options.window;
+
+    let requests = this.requests.get(key) || [];
+
+    // Remove old requests outside the window
+    requests = requests.filter((timestamp) => timestamp > windowStart);
+    this.requests.set(key, requests);
+
+    const allowed = requests.length < this.options.limit;
+    const remaining = Math.max(0, this.options.limit - requests.length);
+
+    if (allowed) {
+      requests.push(now);
+    }
+
+    const oldestRequest = requests[0];
+    const resetAt = oldestRequest
+      ? oldestRequest + this.options.window
+      : now + this.options.window;
+    const retryAfter = allowed ? undefined : resetAt - now;
+
+    return {
+      allowed,
+      remaining,
+      resetAt,
+      retryAfter,
+    };
+  }
+
+  async execute<T>(fn: () => Promise<T>, key: string = "default"): Promise<T> {
+    const result = await this.check(key);
+
+    if (!result.allowed) {
+      switch (this.options.strategy || "throw") {
+        case "throw":
+          throw new Error(
+            `Rate limit exceeded. Retry after ${result.retryAfter}ms`
+          );
+        case "delay":
+          await new Promise((resolve) =>
+            setTimeout(resolve, result.retryAfter)
+          );
+          return this.execute(fn, key);
+        case "drop":
+          throw new Error("Request dropped due to rate limit");
+      }
+    }
+
+    return fn();
+  }
+
+  reset(): void {
+    this.requests.clear();
+  }
+}
+
+/**
+ * Token bucket rate limiter
+ */
+export class TokenBucketRateLimiter {
+  private buckets: Map<string, { tokens: number; lastRefill: number }> =
+    new Map();
+  private capacity: number;
+  private refillRate: number; // tokens per second
+  private refillInterval: number;
+
+  constructor(options: {
+    capacity: number;
+    refillRate: number;
+    refillInterval?: number;
+  }) {
+    this.capacity = options.capacity;
+    this.refillRate = options.refillRate;
+    this.refillInterval = options.refillInterval || 1000; // default 1 second
+  }
+
+  private refill(key: string): void {
+    const now = Date.now();
+    let bucket = this.buckets.get(key);
+
+    if (!bucket) {
+      bucket = { tokens: this.capacity, lastRefill: now };
+      this.buckets.set(key, bucket);
+      return;
+    }
+
+    const timePassed = now - bucket.lastRefill;
+    const intervals = timePassed / this.refillInterval;
+    const tokensToAdd = intervals * this.refillRate;
+
+    bucket.tokens = Math.min(this.capacity, bucket.tokens + tokensToAdd);
+    bucket.lastRefill = now;
+  }
+
+  async check(
+    key: string = "default",
+    cost: number = 1
+  ): Promise<RateLimitResult> {
+    this.refill(key);
+    const bucket = this.buckets.get(key)!;
+
+    const allowed = bucket.tokens >= cost;
+
+    if (allowed) {
+      bucket.tokens -= cost;
+    }
+
+    return {
+      allowed,
+      remaining: Math.floor(bucket.tokens),
+      resetAt: bucket.lastRefill + this.refillInterval,
+      retryAfter: allowed
+        ? undefined
+        : Math.ceil(
+            ((cost - bucket.tokens) / this.refillRate) * this.refillInterval
+          ),
+    };
+  }
+
+  reset(): void {
+    this.buckets.clear();
+  }
+}

package/src/patterns/retry.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createFlow } from '../core/flow-fn.js';
+
+describe('Retry & Backoff', () => {
+    let flow;
+
+    beforeEach(() => {
+        flow = createFlow({ adapter: 'memory' });
+    });
+
+    afterEach(async () => {
+        await flow.close();
+    });
+
+    it('should retry a failed job with backoff', async () => {
+        const queue = flow.queue('retry-test');
+        let attempts = 0;
+
+        await queue.add('test-job', { foo: 'bar' }, {
+            attempts: 3,
+            backoff: { type: 'fixed', delay: 10 }
+        });
+
+        await new Promise<void>((resolve) => {
+            queue.process(async (job) => {
+                attempts++;
+                if (attempts < 3) {
+                    throw new Error('Transient failure');
+                }
+                resolve();
+            });
+        });
+
+        expect(attempts).toBe(3);
+    });
+
+    it('should move to failed after max attempts', async () => {
+        const queue = flow.queue('fail-test');
+        let attempts = 0;
+
+        await queue.add('test-job', { foo: 'bar' }, {
+            attempts: 2,
+            backoff: { type: 'fixed', delay: 10 }
+        });
+
+        const failedPromise = new Promise<void>((resolve) => {
+            queue.on('failed', (job) => {
+                if (job.attemptsMade === 2) {
+                    resolve();
+                }
+            });
+        });
+
+        queue.process(async (job) => {
+            attempts++;
+            throw new Error('Permanent failure');
+        });
+
+        await failedPromise;
+        expect(attempts).toBe(2);
+    });
+});

package/src/queue/batch.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createFlow } from '../core/flow-fn.js';
+
+describe('Batch Processing', () => {
+    let flow;
+
+    beforeEach(() => {
+        flow = createFlow({ adapter: 'memory' });
+    });
+
+    afterEach(async () => {
+        await flow.close();
+    });
+
+    it('should process jobs in batches', async () => {
+        const queue = flow.queue('batch-test');
+        let processedBatches = 0;
+
+        await queue.addBulk([
+            { name: 'j1', data: 1 },
+            { name: 'j2', data: 2 },
+            { name: 'j3', data: 3 }
+        ]);
+
+        await new Promise<void>((resolve) => {
+            queue.processBatch('test', 2, async (jobs) => {
+                processedBatches++;
+                if (processedBatches === 2) resolve();
+                return jobs.map(j => j.data * 2);
+            });
+        });
+
+        expect(processedBatches).toBe(2); // One batch of 2, one batch of 1
+    });
+});

package/src/queue/dependencies.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createFlow } from '../core/flow-fn.js';
+
+describe('Job Dependencies', () => {
+    let flow;
+
+    beforeEach(() => {
+        flow = createFlow({ adapter: 'memory' });
+    });
+
+    afterEach(async () => {
+        await flow.close();
+    });
+
+    it('should wait for dependencies to complete', async () => {
+        const queue = flow.queue('dep-test');
+        let order: string[] = [];
+
+        const job1 = await queue.add('job1', { id: 1 });
+        const job2 = await queue.add('job2', { id: 2 }, { waitFor: [job1.id] });
+
+        // Start processing
+        queue.process(async (job) => {
+            order.push(job.name);
+            return { done: true };
+        });
+
+        // Wait for both to complete
+        await new Promise(r => setTimeout(r, 500));
+        
+        expect(order).toEqual(['job1', 'job2']);
+    });
+});