@363045841yyt/klinechart-core 0.8.14 → 0.9.0-alpha.0

package/src/scheduler/__tests__/createFrameBudget.test.ts

@@ -1,319 +0,0 @@
-/**
- * Tests for `createFrameBudget`.
- *
- * The clock is injected via `opts.now`, so timing assertions are exact:
- * we advance a counter manually and the scheduler reads from it.
- *
- * Coverage:
- *   1. Construction validates targetMs / historySize / maxQueueSize.
- *   2. submit:
- *      - rejects empty id with KLineChartError(INVALID_PARAM)
- *      - queues into correct priority tier (queueDepth updates)
- *      - coalesces same-id submission (the later wins)
- *      - re-buckets when coalesce changes priority
- *      - drops oldest low/medium under maxQueueSize pressure
- *      - never drops high under pressure
- *   3. flush:
- *      - runs all queued tasks if deadline is generous
- *      - stops at deadline (remaining stay queued)
- *      - runs high before medium before low (priority ordering)
- *      - within a tier, FIFO
- *      - returns the number of tasks run
- *      - throw in task is caught + dropped, others continue
- *   4. beginFrame / endFrame:
- *      - validate finite timestamps
- *      - recentFrameMs is the rolling average over historySize frames
- *      - overruns increments only when dur > targetMs
- *   5. clear / dispose.
- */
-
-import { describe, it, expect } from 'vitest'
-
-import { createFrameBudget, type FrameTask } from '..'
-import { isKLineChartError } from '../../errors'
-
-function fakeClock(): {
-  now: () => number
-  advance: (ms: number) => void
-  set: (t: number) => void
-} {
-  let t = 0
-  return {
-    now: () => t,
-    advance: (ms: number) => {
-      t += ms
-    },
-    set: (next: number) => {
-      t = next
-    },
-  }
-}
-
-function record(
-  id: string,
-  store: string[],
-  priority: FrameTask['priority'] = 'medium',
-): FrameTask {
-  return { id, priority, work: () => store.push(id) }
-}
-
-// ---------------------------------------------------------------------------
-// Construction
-// ---------------------------------------------------------------------------
-
-describe('createFrameBudget — validation', () => {
-  it('rejects non-positive targetMs', () => {
-    for (const v of [0, -1, Number.NaN]) {
-      try {
-        createFrameBudget({ targetMs: v })
-        expect.fail(`expected throw for ${v}`)
-      } catch (e) {
-        expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
-      }
-    }
-  })
-
-  it('rejects non-positive-integer historySize', () => {
-    for (const v of [0, -1, 1.5]) {
-      try {
-        createFrameBudget({ historySize: v })
-        expect.fail(`expected throw for ${v}`)
-      } catch (e) {
-        expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
-      }
-    }
-  })
-
-  it('rejects non-positive-integer maxQueueSize', () => {
-    try {
-      createFrameBudget({ maxQueueSize: 0 })
-      expect.fail('expected throw')
-    } catch (e) {
-      expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
-    }
-  })
-
-  it('exposes targetMs verbatim', () => {
-    expect(createFrameBudget({ targetMs: 8 }).targetMs).toBe(8)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// submit
-// ---------------------------------------------------------------------------
-
-describe('submit', () => {
-  it('rejects empty id', () => {
-    const fb = createFrameBudget()
-    try {
-      fb.submit({ id: '', priority: 'low', work: () => {} })
-      expect.fail('expected throw')
-    } catch (e) {
-      expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
-    }
-  })
-
-  it('queueDepth tracks submissions across tiers', () => {
-    const fb = createFrameBudget()
-    const seen: string[] = []
-    fb.submit(record('a', seen, 'high'))
-    fb.submit(record('b', seen, 'medium'))
-    fb.submit(record('c', seen, 'low'))
-    expect(fb.queueDepth.peek()).toBe(3)
-  })
-
-  it('coalesces same-id submission (later wins)', () => {
-    const fb = createFrameBudget()
-    const seen: string[] = []
-    fb.submit({ id: 'x', priority: 'low', work: () => seen.push('first') })
-    fb.submit({ id: 'x', priority: 'low', work: () => seen.push('second') })
-    const clk = fakeClock()
-    // Cheap test: a fresh budget with default now — flush with a far deadline.
-    fb.flush(Number.POSITIVE_INFINITY)
-    expect(seen).toEqual(['second'])
-  })
-
-  it('re-buckets when coalesce changes priority', () => {
-    const seen: string[] = []
-    const fb = createFrameBudget({ now: fakeClock().now })
-    fb.submit({ id: 'x', priority: 'low', work: () => seen.push('low') })
-    fb.submit({ id: 'x', priority: 'high', work: () => seen.push('high') })
-    fb.submit(record('y', seen, 'medium'))
-    fb.flush(Number.POSITIVE_INFINITY)
-    // x runs first (it's now high), then y.
-    expect(seen).toEqual(['high', 'y'])
-  })
-
-  it('drops oldest low under maxQueueSize pressure', () => {
-    const seen: string[] = []
-    const fb = createFrameBudget({ maxQueueSize: 2 })
-    fb.submit(record('a', seen, 'low'))
-    fb.submit(record('b', seen, 'low'))
-    fb.submit(record('c', seen, 'high'))
-    fb.flush(Number.POSITIVE_INFINITY)
-    // 'a' was the oldest low; it got dropped to make room for 'c'.
-    expect(seen).toEqual(['c', 'b'])
-  })
-
-  it('never drops high under pressure', () => {
-    const seen: string[] = []
-    const fb = createFrameBudget({ maxQueueSize: 2 })
-    fb.submit(record('a', seen, 'high'))
-    fb.submit(record('b', seen, 'high'))
-    fb.submit(record('c', seen, 'high'))
-    fb.flush(Number.POSITIVE_INFINITY)
-    // All 3 high tasks present; the cap was exceeded but high
-    // is never dropped (producer-is-misbehaving signal).
-    expect(seen).toEqual(['a', 'b', 'c'])
-  })
-})
-
-// ---------------------------------------------------------------------------
-// flush
-// ---------------------------------------------------------------------------
-
-describe('flush', () => {
-  it('runs high before medium before low (priority)', () => {
-    const seen: string[] = []
-    const fb = createFrameBudget()
-    fb.submit(record('low1', seen, 'low'))
-    fb.submit(record('med1', seen, 'medium'))
-    fb.submit(record('hi1', seen, 'high'))
-    fb.submit(record('hi2', seen, 'high'))
-    fb.submit(record('med2', seen, 'medium'))
-    fb.flush(Number.POSITIVE_INFINITY)
-    expect(seen).toEqual(['hi1', 'hi2', 'med1', 'med2', 'low1'])
-  })
-
-  it('within a tier, runs FIFO', () => {
-    const seen: string[] = []
-    const fb = createFrameBudget()
-    for (const id of ['a', 'b', 'c', 'd']) {
-      fb.submit(record(id, seen, 'medium'))
-    }
-    fb.flush(Number.POSITIVE_INFINITY)
-    expect(seen).toEqual(['a', 'b', 'c', 'd'])
-  })
-
-  it('stops at deadline; remaining tasks stay queued', () => {
-    const seen: string[] = []
-    const clk = fakeClock()
-    const fb = createFrameBudget({ now: clk.now })
-    for (let i = 0; i < 5; i++) {
-      fb.submit({
-        id: `t${i}`,
-        priority: 'medium',
-        work: () => {
-          seen.push(`t${i}`)
-          clk.advance(2) // each task costs 2ms
-        },
-      })
-    }
-    // Deadline at 5ms — 2 tasks complete (4ms), the 3rd would push us
-    // to 6ms but clock check happens BEFORE running each task. After
-    // 2 tasks, the next iteration sees now() = 4 < 5 — runs the 3rd
-    // (push to 6). After that, now() = 6 >= 5 — stop.
-    const done = fb.flush(5)
-    expect(done).toBe(3)
-    expect(seen).toEqual(['t0', 't1', 't2'])
-    expect(fb.queueDepth.peek()).toBe(2)
-  })
-
-  it('returns 0 if deadline already passed', () => {
-    const clk = fakeClock()
-    clk.set(100)
-    const fb = createFrameBudget({ now: clk.now })
-    fb.submit(record('a', [], 'high'))
-    expect(fb.flush(50)).toBe(0)
-  })
-
-  it('a throwing task is dropped; others continue', () => {
-    const seen: string[] = []
-    const fb = createFrameBudget()
-    fb.submit({ id: 'a', priority: 'high', work: () => seen.push('a') })
-    fb.submit({
-      id: 'bad',
-      priority: 'high',
-      work: () => {
-        throw new Error('boom')
-      },
-    })
-    fb.submit({ id: 'c', priority: 'high', work: () => seen.push('c') })
-    const done = fb.flush(Number.POSITIVE_INFINITY)
-    expect(done).toBe(2) // a + c, not bad
-    expect(seen).toEqual(['a', 'c'])
-  })
-})
-
-// ---------------------------------------------------------------------------
-// beginFrame / endFrame
-// ---------------------------------------------------------------------------
-
-describe('beginFrame / endFrame', () => {
-  it('validates finite timestamps', () => {
-    const fb = createFrameBudget()
-    for (const m of ['beginFrame', 'endFrame'] as const) {
-      try {
-        fb[m](Number.NaN)
-        expect.fail('expected throw')
-      } catch (e) {
-        expect(isKLineChartError(e, 'INVALID_PARAM')).toBe(true)
-      }
-    }
-  })
-
-  it('recentFrameMs is the rolling average over historySize frames', () => {
-    const fb = createFrameBudget({ historySize: 3 })
-    // 3 frames at 10ms each → avg 10
-    for (let i = 0; i < 3; i++) {
-      fb.beginFrame(i * 16)
-      fb.endFrame(i * 16 + 10)
-    }
-    expect(fb.recentFrameMs.peek()).toBe(10)
-    // Push one 20ms frame; rolling window drops the oldest.
-    fb.beginFrame(48)
-    fb.endFrame(68)
-    // window: [10, 10, 20] → avg ≈ 13.33
-    expect(fb.recentFrameMs.peek()).toBeCloseTo((10 + 10 + 20) / 3, 5)
-  })
-
-  it('overruns increments only when frame > targetMs', () => {
-    const fb = createFrameBudget({ targetMs: 16 })
-    // 10ms frame — not an overrun
-    fb.beginFrame(0)
-    fb.endFrame(10)
-    expect(fb.overruns.peek()).toBe(0)
-    // 18ms frame — overrun
-    fb.beginFrame(16)
-    fb.endFrame(34)
-    expect(fb.overruns.peek()).toBe(1)
-    // Exactly at targetMs — not an overrun (> strict)
-    fb.beginFrame(32)
-    fb.endFrame(48)
-    expect(fb.overruns.peek()).toBe(1)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// clear / dispose
-// ---------------------------------------------------------------------------
-
-describe('clear', () => {
-  it('drops all queued tasks', () => {
-    const fb = createFrameBudget()
-    fb.submit(record('a', [], 'high'))
-    fb.submit(record('b', [], 'low'))
-    fb.clear()
-    expect(fb.queueDepth.peek()).toBe(0)
-  })
-})
-
-describe('dispose', () => {
-  it('makes submit / flush / frame markers no-ops', () => {
-    const fb = createFrameBudget()
-    fb.dispose()
-    expect(() => fb.submit(record('a', [], 'high'))).not.toThrow()
-    expect(fb.queueDepth.peek()).toBe(0)
-    expect(fb.flush(Number.POSITIVE_INFINITY)).toBe(0)
-  })
-})

package/src/scheduler/createFrameBudget.ts

@@ -1,316 +0,0 @@
-/**
- * Frame budget scheduler — adaptive workload manager.
- *
- * Real-time finance charts share a constraint with games and trading
- * terminals: the renderer has a wall-clock budget per frame (16.67 ms
- * at 60 fps, 6.94 ms at 144 fps), and exceeding it means dropped frames.
- * Work that doesn't fit gets deferred to the next frame, but the work
- * *queue* must not grow without bound — a stale indicator update is
- * worse than a missed update.
- *
- * This module owns the policy. Consumers submit prioritised tasks;
- * `flush(deadline)` drains as many as fit; the rest stay queued until
- * the next call. A rolling-average frame-time signal lets components
- * back off proactively rather than waiting for budget exhaustion.
- *
- * Pure data: no requestAnimationFrame, no performance.now() side effects.
- * The host (browser / Node test / Deno) supplies the clock via a `now`
- * function. Default: `performance.now()` if available, else `Date.now()`.
- *
- *   const budget = createFrameBudget({ targetMs: 16 })
- *
- *   // Host's rAF loop:
- *   function tick(t) {
- *     budget.beginFrame(t)
- *     budget.submit({ id: 'indicators', priority: 'high', work: recompute })
- *     budget.submit({ id: 'labels',     priority: 'low',  work: drawLabels })
- *     budget.flush(t + budget.targetMs)
- *     budget.endFrame(performance.now())
- *     requestAnimationFrame(tick)
- *   }
- *
- *   // Consumers can read the load signal to back off:
- *   if (budget.recentFrameMs() > 18) skipLowPriorityWork()
- */
-
-import { KLineChartError } from '../errors'
-import { createSignal, type Signal } from '../reactivity'
-
-// ---------------------------------------------------------------------------
-// Public shape
-// ---------------------------------------------------------------------------
-
-export type TaskPriority = 'high' | 'medium' | 'low'
-
-export interface FrameTask {
-  /** Stable id. Duplicate submissions with the same id are coalesced — the
-   *  later submission's `work` and `priority` win. */
-  readonly id: string
-  readonly priority: TaskPriority
-  /** Synchronous unit of work. Throws are caught and logged but do NOT
-   *  abort the frame; the task is dropped. */
-  readonly work: () => void
-}
-
-export interface FrameBudgetOptions {
-  /** Target frame budget in milliseconds. Default 16 (≈60 fps). */
-  readonly targetMs?: number
-  /** Rolling window for `recentFrameMs`. Default 60 frames (1 s at 60 fps). */
-  readonly historySize?: number
-  /**
-   * Clock function. Default: `performance.now()` if available, else
-   * `Date.now()`. Injected for tests so timing is deterministic.
-   */
-  readonly now?: () => number
-  /**
-   * Maximum queued tasks. Older low/medium tasks are dropped when the
-   * queue exceeds this. Default 256 — high enough that legitimate
-   * workloads never hit it, low enough that runaway producers fail loud.
-   */
-  readonly maxQueueSize?: number
-}
-
-export interface FrameBudget {
-  readonly targetMs: number
-  /** Current rolling-average frame time in ms. */
-  readonly recentFrameMs: Signal<number>
-  /** Number of tasks currently queued (not yet flushed). */
-  readonly queueDepth: Signal<number>
-  /** Frames whose work exceeded targetMs (cumulative). */
-  readonly overruns: Signal<number>
-
-  /** Mark the start of a frame. Pass `performance.now()` (or test clock). */
-  beginFrame(t: number): void
-  /** Queue a task. Coalesces on id (later submission wins). */
-  submit(task: FrameTask): void
-  /**
-   * Drain queued tasks until the deadline (absolute timestamp in the
-   * `now`-clock's scale). Returns the number of tasks completed.
-   *
-   * Tasks run in priority order: all `high` first, then `medium`, then
-   * `low`. Within a priority, FIFO. A task that throws is caught and
-   * dropped; remaining tasks continue.
-   */
-  flush(deadlineAbs: number): number
-  /** Mark the end of a frame. Updates `recentFrameMs` + overrun count. */
-  endFrame(t: number): void
-  /** Drop all queued tasks. */
-  clear(): void
-  dispose(): void
-}
-
-const PRIORITY_ORDER: ReadonlyArray<TaskPriority> = ['high', 'medium', 'low']
-
-// ---------------------------------------------------------------------------
-// Internals
-// ---------------------------------------------------------------------------
-
-function defaultNow(): number {
-  const perf = (globalThis as { performance?: { now?: () => number } }).performance
-  if (typeof perf?.now === 'function') return perf.now()
-  return Date.now()
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-export function createFrameBudget(opts: FrameBudgetOptions = {}): FrameBudget {
-  const targetMs = opts.targetMs ?? 16
-  const historySize = opts.historySize ?? 60
-  const maxQueueSize = opts.maxQueueSize ?? 256
-  const now = opts.now ?? defaultNow
-
-  if (!(targetMs > 0) || !Number.isFinite(targetMs)) {
-    throw new KLineChartError(
-      'INVALID_PARAM',
-      `createFrameBudget: targetMs must be > 0, got ${targetMs}`,
-    )
-  }
-  if (!(historySize > 0) || !Number.isInteger(historySize)) {
-    throw new KLineChartError(
-      'INVALID_PARAM',
-      `createFrameBudget: historySize must be a positive integer, got ${historySize}`,
-    )
-  }
-  if (!(maxQueueSize > 0) || !Number.isInteger(maxQueueSize)) {
-    throw new KLineChartError(
-      'INVALID_PARAM',
-      `createFrameBudget: maxQueueSize must be a positive integer, got ${maxQueueSize}`,
-    )
-  }
-
-  const recentFrameMs = createSignal(0)
-  const queueDepth = createSignal(0)
-  const overruns = createSignal(0)
-
-  // One queue per priority; preserves FIFO inside a tier.
-  const queues: Record<TaskPriority, FrameTask[]> = {
-    high: [],
-    medium: [],
-    low: [],
-  }
-  // Reverse lookup so coalesce-by-id is O(1).
-  const byId = new Map<string, { tier: TaskPriority; index: number }>()
-
-  const frameTimes: number[] = []
-  let frameStart = 0
-  let disposed = false
-
-  function publishDepth(): void {
-    queueDepth.set(queues.high.length + queues.medium.length + queues.low.length)
-  }
-
-  function totalQueued(): number {
-    return queues.high.length + queues.medium.length + queues.low.length
-  }
-
-  function dropOldestLowOrMedium(): void {
-    // Prefer dropping low first, then medium. We never drop high.
-    if (queues.low.length > 0) {
-      const dropped = queues.low.shift()!
-      byId.delete(dropped.id)
-      return
-    }
-    if (queues.medium.length > 0) {
-      const dropped = queues.medium.shift()!
-      byId.delete(dropped.id)
-      return
-    }
-    // Only high tasks remain. We don't drop high tasks for queue
-    // pressure; the producer is misbehaving. Surface via overruns
-    // signal so the host can decide.
-  }
-
-  function submit(task: FrameTask): void {
-    if (disposed) return
-    if (task.id === '' || typeof task.id !== 'string') {
-      throw new KLineChartError(
-        'INVALID_PARAM',
-        `FrameBudget.submit: task.id must be a non-empty string`,
-      )
-    }
-    // Coalesce by id — replace existing entry.
-    const existing = byId.get(task.id)
-    if (existing !== undefined) {
-      queues[existing.tier][existing.index] = task
-      // The tier might be changing; if it is, we need to re-bucket.
-      if (existing.tier !== task.priority) {
-        // Mark old slot as a tombstone (we can't splice cheaply mid-iteration
-        // in some paths). The flush loop tolerates undefined entries.
-        ;(queues[existing.tier] as Array<FrameTask | undefined>)[existing.index] = undefined
-        queues[task.priority].push(task)
-        byId.set(task.id, {
-          tier: task.priority,
-          index: queues[task.priority].length - 1,
-        })
-      }
-      publishDepth()
-      return
-    }
-    // Enforce maxQueueSize by dropping older low/medium first.
-    while (totalQueued() >= maxQueueSize) {
-      dropOldestLowOrMedium()
-      // If only high tasks left and we're still at the cap, bail.
-      if (totalQueued() >= maxQueueSize && queues.low.length === 0 && queues.medium.length === 0) {
-        break
-      }
-    }
-    queues[task.priority].push(task)
-    byId.set(task.id, {
-      tier: task.priority,
-      index: queues[task.priority].length - 1,
-    })
-    publishDepth()
-  }
-
-  function flush(deadlineAbs: number): number {
-    if (disposed) return 0
-    let completed = 0
-    for (const tier of PRIORITY_ORDER) {
-      const q = queues[tier] as Array<FrameTask | undefined>
-      while (q.length > 0) {
-        if (now() >= deadlineAbs) {
-          // Compact the tier so later flushes skip tombstones.
-          queues[tier] = q.filter((t): t is FrameTask => t !== undefined)
-          // Rebuild byId indices for this tier.
-          for (let i = 0; i < queues[tier].length; i++) {
-            const t = queues[tier][i]!
-            byId.set(t.id, { tier, index: i })
-          }
-          publishDepth()
-          return completed
-        }
-        const task = q.shift()
-        if (task === undefined) continue // tombstone
-        byId.delete(task.id)
-        try {
-          task.work()
-          completed++
-        } catch {
-          // Task threw; drop it. We don't propagate — one
-          // bad task must not poison the frame.
-        }
-      }
-    }
-    publishDepth()
-    return completed
-  }
-
-  function beginFrame(t: number): void {
-    if (disposed) return
-    if (!Number.isFinite(t)) {
-      throw new KLineChartError(
-        'INVALID_PARAM',
-        `FrameBudget.beginFrame: t must be finite, got ${t}`,
-      )
-    }
-    frameStart = t
-  }
-
-  function endFrame(t: number): void {
-    if (disposed) return
-    if (!Number.isFinite(t)) {
-      throw new KLineChartError('INVALID_PARAM', `FrameBudget.endFrame: t must be finite, got ${t}`)
-    }
-    const dur = Math.max(0, t - frameStart)
-    frameTimes.push(dur)
-    while (frameTimes.length > historySize) frameTimes.shift()
-    let sum = 0
-    for (const v of frameTimes) sum += v
-    recentFrameMs.set(sum / frameTimes.length)
-    if (dur > targetMs) overruns.set(overruns.peek() + 1)
-  }
-
-  function clear(): void {
-    if (disposed) return
-    queues.high = []
-    queues.medium = []
-    queues.low = []
-    byId.clear()
-    publishDepth()
-  }
-
-  function dispose(): void {
-    if (disposed) return
-    disposed = true
-    queues.high = []
-    queues.medium = []
-    queues.low = []
-    byId.clear()
-    frameTimes.length = 0
-  }
-
-  return {
-    targetMs,
-    recentFrameMs,
-    queueDepth,
-    overruns,
-    beginFrame,
-    submit,
-    flush,
-    endFrame,
-    clear,
-    dispose,
-  }
-}