utneque 1.0.0

package/packages/core/src/priority-queue/__tests__/index.test.ts

@@ -0,0 +1,158 @@
+import { PriorityQueue } from '..'
+
+type Item = {
+  id: string
+}
+
+describe('RetryQueue', () => {
+  it('accepts new work', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' }, { id: 'cde' })
+    expect(queue.length).toBe(2)
+  })
+
+  it('pops items off the queue', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' }, { id: 'cde' })
+
+    expect(queue.pop()).toEqual({ id: 'abc' })
+    expect(queue.length).toBe(1)
+
+    expect(queue.pop()).toEqual({ id: 'cde' })
+    expect(queue.length).toBe(0)
+  })
+
+  it('deprioritizes repeated items', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' })
+    queue.push({ id: 'abc' })
+
+    queue.push({ id: 'cde' })
+
+    // deprioritizes 'abc' because it was seen twice
+    expect(queue.pop()).toEqual({ id: 'cde' })
+  })
+
+  it('deprioritizes repeated items even though they have been popped before', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+    queue.push({ id: 'abc' })
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    queue.push({ id: 'cde' })
+
+    // a queue does not forget
+    expect(queue.pop()).toEqual({ id: 'cde' })
+  })
+
+  it('stops accepting an item after attempts have been exausted', () => {
+    const queue = new PriorityQueue<Item>(3, [])
+    queue.push({ id: 'abc' })
+    expect(queue.length).toBe(1)
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    expect(queue.length).toBe(1)
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    expect(queue.length).toBe(1)
+    queue.pop()
+
+    queue.push({ id: 'abc' })
+    // does not accept it anymore
+    expect(queue.length).toBe(0)
+  })
+})
+
+describe('backoffs', () => {
+  afterEach(() => {
+    jest.clearAllTimers()
+  })
+
+  it('accepts new work', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    queue.pushWithBackoff({ id: 'cde' })
+
+    expect(queue.length).toBe(2)
+    expect(queue.todo).toBe(2)
+  })
+
+  it('ignores when item has not been worked on', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+
+    expect(queue.pushWithBackoff({ id: 'abc' })).toBe(true)
+    expect(queue.pushWithBackoff({ id: 'abc' })).toBe(false)
+    expect(queue.length).toBe(1)
+    expect(queue.todo).toBe(1)
+  })
+
+  it('schedules as future work when item returns to the queue', () => {
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    queue.pop()
+
+    // accepted work
+    expect(queue.pushWithBackoff({ id: 'abc' })).toBe(true)
+
+    // not in the main queue yet
+    expect(queue.length).toBe(0)
+
+    // present in future work
+    expect(queue.todo).toBe(1)
+    expect(queue.includes({ id: 'abc' })).toBe(true)
+  })
+
+  it('schedules as future work for later', () => {
+    jest.useFakeTimers()
+    const spy = jest.spyOn(global, 'setTimeout')
+
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    expect(spy).not.toHaveBeenCalled()
+
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    expect(spy).toHaveBeenCalled()
+
+    const delay = spy.mock.calls[0][1]
+    expect(delay).toBeGreaterThan(1000)
+  })
+
+  it('increases the delay as work gets requeued', () => {
+    jest.useFakeTimers()
+    const spy = jest.spyOn(global, 'setTimeout')
+
+    const queue = new PriorityQueue<Item>(10, [])
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    queue.pushWithBackoff({ id: 'abc' })
+    jest.advanceTimersToNextTimer()
+    queue.pop()
+
+    const firstDelay = spy.mock.calls[0][1]
+    expect(firstDelay).toBeGreaterThan(1000)
+
+    const secondDelay = spy.mock.calls[1][1]
+    expect(secondDelay).toBeGreaterThan(2000)
+
+    const thirdDelay = spy.mock.calls[2][1]
+    expect(thirdDelay).toBeGreaterThan(3000)
+  })
+})

package/packages/core/src/priority-queue/backoff.ts

@@ -0,0 +1,24 @@
+type BackoffParams = {
+  /** The number of milliseconds before starting the first retry. Default is 500 */
+  minTimeout?: number
+
+  /** The maximum number of milliseconds between two retries. Default is Infinity */
+  maxTimeout?: number
+
+  /** The exponential factor to use. Default is 2. */
+  factor?: number
+
+  /** The current attempt */
+  attempt: number
+}
+
+export function backoff(params: BackoffParams): number {
+  const random = Math.random() + 1
+  const {
+    minTimeout = 500,
+    factor = 2,
+    attempt,
+    maxTimeout = Infinity,
+  } = params
+  return Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)
+}

package/packages/core/src/priority-queue/index.ts

@@ -0,0 +1,103 @@
+import { Emitter } from '../emitter'
+import { backoff } from './backoff'
+
+/**
+ * @internal
+ */
+export const ON_REMOVE_FROM_FUTURE = 'onRemoveFromFuture'
+
+interface QueueItem {
+  id: string
+}
+
+export class PriorityQueue<Item extends QueueItem = QueueItem> extends Emitter {
+  protected future: Item[] = []
+  protected queue: Item[]
+  protected seen: Record<string, number>
+
+  public maxAttempts: number
+
+  constructor(
+    maxAttempts: number,
+    queue: Item[],
+    seen?: Record<string, number>
+  ) {
+    super()
+    this.maxAttempts = maxAttempts
+    this.queue = queue
+    this.seen = seen ?? {}
+  }
+
+  push(...items: Item[]): boolean[] {
+    const accepted = items.map((operation) => {
+      const attempts = this.updateAttempts(operation)
+
+      if (attempts > this.maxAttempts || this.includes(operation)) {
+        return false
+      }
+
+      this.queue.push(operation)
+      return true
+    })
+
+    this.queue = this.queue.sort(
+      (a, b) => this.getAttempts(a) - this.getAttempts(b)
+    )
+    return accepted
+  }
+
+  pushWithBackoff(item: Item): boolean {
+    if (this.getAttempts(item) === 0) {
+      return this.push(item)[0]
+    }
+
+    const attempt = this.updateAttempts(item)
+
+    if (attempt > this.maxAttempts || this.includes(item)) {
+      return false
+    }
+
+    const timeout = backoff({ attempt: attempt - 1 })
+
+    setTimeout(() => {
+      this.queue.push(item)
+      // remove from future list
+      this.future = this.future.filter((f) => f.id !== item.id)
+      // Lets listeners know that a 'future' message is now available in the queue
+      this.emit(ON_REMOVE_FROM_FUTURE)
+    }, timeout)
+
+    this.future.push(item)
+    return true
+  }
+
+  public getAttempts(item: Item): number {
+    return this.seen[item.id] ?? 0
+  }
+
+  public updateAttempts(item: Item): number {
+    this.seen[item.id] = this.getAttempts(item) + 1
+    return this.getAttempts(item)
+  }
+
+  includes(item: Item): boolean {
+    return (
+      this.queue.includes(item) ||
+      this.future.includes(item) ||
+      Boolean(this.queue.find((i) => i.id === item.id)) ||
+      Boolean(this.future.find((i) => i.id === item.id))
+    )
+  }
+
+  pop(): Item | undefined {
+    return this.queue.shift()
+  }
+
+  public get length(): number {
+    return this.queue.length
+  }
+
+  public get todo(): number {
+    return this.queue.length + this.future.length
+  }
+}