@typed/template 0.14.0 → 1.0.0-beta.0

package/src/RenderQueue.ts

@@ -1,447 +1,352 @@
-/**
- * The context in which templates are rendered within
- * @since 1.0.0
- */
+import { constVoid } from "effect/Function";
 
-import * as Context from "@typed/context"
-import * as Idle from "@typed/fx/Idle"
-import * as Effect from "effect/Effect"
-import * as FiberRef from "effect/FiberRef"
-import { dual } from "effect/Function"
-import type * as Layer from "effect/Layer"
-import * as Scope from "effect/Scope"
+export const RenderQueueTypeId = "@typed/template/RenderQueue";
+export type RenderQueueTypeId = typeof RenderQueueTypeId;
 
-/**
- * @since 1.0.0
- */
-export const DEFAULT_PRIORITY = 10
+type Entry = { task: () => void; dispose: () => void };
 
 /**
- * The context in which templates are rendered within
+ * An abstract base class for managing the execution of rendering tasks.
+ * It allows prioritizing updates and scheduling them using different strategies
+ * (e.g., `requestAnimationFrame`, `requestIdleCallback`, `setTimeout`, or synchronous execution).
+ *
+ * @example
+ * ```ts
+ * import { MixedRenderQueue, RenderPriority } from "@typed/template/RenderQueue"
+ *
+ * const queue = new MixedRenderQueue()
+ *
+ * // Add a high-priority synchronous task
+ * queue.add("task1", () => console.log("High priority"), () => {}, RenderPriority.Sync)
+ *
+ * // Add a medium-priority RAF task
+ * queue.add("task2", () => console.log("Medium priority"), () => {}, RenderPriority.Raf(5))
+ *
+ * // Add a low-priority idle task
+ * queue.add("task3", () => console.log("Low priority"), () => {}, RenderPriority.Idle(1))
+ * ```
+ *
  * @since 1.0.0
+ * @category models
  */
-export const RenderQueue: Context.Tagged<RenderQueue, RenderQueue> = Context.Tagged<RenderQueue>(
-  "@typed/template/RenderQueue"
-)
+export abstract class RenderQueue implements Disposable {
+  protected readonly buckets: Array<KeyedPriorityBucket<Entry>> = [];
+  protected scheduled: Disposable | undefined = undefined;
 
-/**
- * @since 1.0.0
- */
-export const currentPriority: FiberRef.FiberRef<number> = FiberRef.unsafeMake(DEFAULT_PRIORITY)
+  readonly [RenderQueueTypeId]: RenderQueueTypeId = RenderQueueTypeId;
 
-/**
- * @since 1.0.0
- */
-export interface RenderQueue {
-  readonly add: (part: unknown, task: () => void, priority: number) => Effect.Effect<void, never, Scope.Scope>
+  /**
+   * Adds a task to the render queue.
+   *
+   * @param key - A unique key to identify the task (used for deduplication/cancellation).
+   * @param task - The function to execute.
+   * @param dispose - A cleanup function to run after the task is executed.
+   * @param priority - The priority of the task. Higher priority tasks may run sooner depending on the implementation.
+   * @returns A Disposable that can be used to cancel the task.
+   */
+  readonly add: (
+    key: unknown,
+    task: () => void,
+    dispose: () => void,
+    priority: number,
+  ) => Disposable = (key, task, dispose, priority) => {
+    insert(this.buckets, priority, key, { task, dispose }, (entry) => entry.dispose());
+    this.scheduleNext();
+    return disposable(() => remove(this.buckets, priority, key));
+  };
+
+  readonly [Symbol.dispose]: () => void = () => {
+    if (this.scheduled) {
+      dispose(this.scheduled);
+      this.scheduled = undefined;
+    }
+    this.buckets.length = 0;
+  };
+
+  protected abstract schedule(task: (deadline: IdleDeadline) => void): Disposable;
+
+  protected runTasks(deadline: IdleDeadline): void {
+    this.scheduled = undefined;
+
+    while (shouldContinue(deadline) && this.buckets.length > 0) {
+      const [_priority, map] = this.buckets.shift()!;
+      for (const { dispose, task } of map.values()) {
+        task();
+        dispose();
+      }
+    }
+
+    this.scheduleNext();
+  }
+
+  private scheduleNext(): void {
+    if (this.buckets.length === 0) {
+      dispose(this);
+      return;
+    }
+
+    if (!this.scheduled) {
+      this.scheduled = this.schedule((deadline) => this.runTasks(deadline));
+    }
+  }
 }
 
+// 16ms to match 60fps
+const DEFAULT_DURATION_ALLOWED = 16;
+const SYNC_DEADLINE: IdleDeadline = { timeRemaining: () => Infinity, didTimeout: false };
+
 /**
+ * A RenderQueue that executes tasks synchronously and immediately.
+ *
+ * @example
+ * ```ts
+ * import { SyncRenderQueue, RenderPriority } from "@typed/template/RenderQueue"
+ *
+ * const queue = new SyncRenderQueue()
+ * queue.add("task", () => console.log("Immediate"), () => {}, RenderPriority.Sync)
+ * ```
+ *
  * @since 1.0.0
+ * @category models
  */
-export interface IdleRenderQueueOptions extends IdleRequestOptions {
-  readonly scope: Scope.Scope
+export class SyncRenderQueue extends RenderQueue {
+  protected schedule(task: (deadline: IdleDeadline) => void): Disposable {
+    task(SYNC_DEADLINE);
+    return disposable(constVoid);
+  }
 }
 
 /**
- * @since 1.0.0
+ * A RenderQueue that schedules tasks using `setTimeout(..., 0)`.
  */
-export const unsafeMakeIdleRenderQueue = ({ scope, ...options }: IdleRenderQueueOptions): RenderQueue =>
-  new IdleImpl(scope, options)
+export class SetTimeoutRenderQueue extends RenderQueue {
+  protected schedule(task: (deadline: IdleDeadline) => void): Disposable {
+    const id = setTimeout(
+      () => task(idleDealineFromTime(performance.now(), DEFAULT_DURATION_ALLOWED)),
+      0,
+    );
+    return disposable(() => clearTimeout(id));
+  }
+}
 
 /**
+ * A RenderQueue that schedules tasks using `requestAnimationFrame`.
+ * Good for visual updates that should happen before the next repaint.
+ *
+ * @example
+ * ```ts
+ * import { RequestAnimationFrameRenderQueue, RenderPriority } from "@typed/template/RenderQueue"
+ *
+ * const queue = new RequestAnimationFrameRenderQueue(16) // 16ms budget
+ * queue.add("update", () => updateDOM(), () => {}, RenderPriority.Raf(5))
+ * ```
+ *
  * @since 1.0.0
+ * @category models
  */
-export const unsafeMakeRafRenderQueue = (scope: Scope.Scope): RenderQueue => new RafImpl(scope)
+export class RequestAnimationFrameRenderQueue extends RenderQueue {
+  readonly durationAllowed: number;
+  constructor(durationAllowed: number = DEFAULT_DURATION_ALLOWED) {
+    super();
+    this.durationAllowed = durationAllowed;
+  }
 
-/**
- * @since 1.0.0
- */
-export const unsafeMakeMicrotaskRenderQueue = (scope: Scope.Scope): RenderQueue => new MicroTaskImpl(scope)
+  protected schedule(task: (deadline: IdleDeadline) => void): Disposable {
+    const id = requestAnimationFrame((time) =>
+      task(idleDealineFromTime(time, this.durationAllowed)),
+    );
+    return disposable(() => cancelAnimationFrame(id));
+  }
+}
 
 /**
- * @since 1.0.0
+ * A RenderQueue that schedules tasks using `requestIdleCallback`.
+ * Good for low-priority background work.
  */
-export const unsafeMakeSyncRenderQueue = (): RenderQueue => new SyncImpl()
+export class RequestIdleCallbackRenderQueue extends RenderQueue {
+  protected schedule(task: (deadline: IdleDeadline) => void): Disposable {
+    const id = requestIdleCallback(task);
+    return disposable(() => cancelIdleCallback(id));
+  }
+}
 
-/**
- * @since 1.0.0
- */
-export const idle = (options?: IdleRequestOptions): Layer.Layer<RenderQueue> =>
-  RenderQueue.scoped(
-    Effect.scopeWith((scope) => Effect.succeed(unsafeMakeIdleRenderQueue({ scope, ...options })))
-  )
+const NONE = disposable(constVoid);
 
 /**
+ * A composite RenderQueue that directs tasks to different queues based on their priority.
+ * - High priority: Sync
+ * - Medium priority: RAF (or setTimeout fallback)
+ * - Low priority: IdleCallback (or setTimeout fallback)
+ *
+ * @example
+ * ```ts
+ * import { MixedRenderQueue, RenderPriority } from "@typed/template/RenderQueue"
+ *
+ * const queue = new MixedRenderQueue()
+ *
+ * // Tasks are automatically routed to the appropriate queue
+ * queue.add("sync", () => {}, () => {}, RenderPriority.Sync)
+ * queue.add("raf", () => {}, () => {}, RenderPriority.Raf(5))
+ * queue.add("idle", () => {}, () => {}, RenderPriority.Idle(1))
+ * ```
+ *
  * @since 1.0.0
+ * @category models
  */
-export const raf: Layer.Layer<RenderQueue> = RenderQueue.scoped(
-  Effect.scopeWith((scope) => Effect.succeed(unsafeMakeRafRenderQueue(scope)))
-)
+export class MixedRenderQueue extends RenderQueue {
+  private readonly high: RenderQueue;
+  private readonly mid: RenderQueue;
+  private readonly low: RenderQueue;
+
+  constructor(durationAllowed: number = DEFAULT_DURATION_ALLOWED) {
+    super();
+    this.high = new SyncRenderQueue();
+    this.mid =
+      typeof requestAnimationFrame === "function"
+        ? new RequestAnimationFrameRenderQueue(durationAllowed)
+        : new SetTimeoutRenderQueue();
+    this.low =
+      typeof requestIdleCallback === "function"
+        ? new RequestIdleCallbackRenderQueue()
+        : new SetTimeoutRenderQueue();
+  }
 
-/**
- * @since 1.0.0
- */
-export const microtask: Layer.Layer<RenderQueue> = RenderQueue.scoped(
-  Effect.scopeWith((scope) => Effect.succeed(unsafeMakeMicrotaskRenderQueue(scope)))
-)
+  override readonly add = (
+    key: unknown,
+    task: () => void,
+    dispose: () => void,
+    priority: number,
+  ): Disposable => {
+    if (priority === RenderPriority.Sync) {
+      return this.high.add(key, task, dispose, priority);
+    } else if (
+      priority > RenderPriority.Sync &&
+      priority <= RenderPriority.Raf(RAF_PRIORITY_RANGE)
+    ) {
+      return this.mid.add(key, task, dispose, priority);
+    } else {
+      return this.low.add(key, task, dispose, priority);
+    }
+  };
 
-/**
- * @since 1.0.0
- */
-export const sync: Layer.Layer<RenderQueue> = RenderQueue.layer(Effect.sync(unsafeMakeSyncRenderQueue))
+  // We let the other queues handle the actual scheduling
+  protected schedule(): Disposable {
+    return NONE;
+  }
 
-const MICRO_TASK_END = DEFAULT_PRIORITY - 1
-const RAF_END = DEFAULT_PRIORITY + 9
-const IDLE_START = RAF_END + 1
+  override [Symbol.dispose]: () => void = () => {
+    dispose(this.high);
+    dispose(this.mid);
+    dispose(this.low);
+  };
+}
 
-/**
- * @since 1.0.0
- */
-export const mixed = (options?: IdleRequestOptions): Layer.Layer<RenderQueue> =>
-  RenderQueue.scoped(Effect.gen(function*() {
-    const scope = yield* Effect.scope
-    const queues: Array<readonly [priorityRange: readonly [number, number], RenderQueue]> = [
-      [[-1, -1], new SyncImpl()],
-      [[0, MICRO_TASK_END], new MicroTaskImpl(scope)],
-      [[DEFAULT_PRIORITY, RAF_END], new RafImpl(scope)],
-      [[IDLE_START, Number.MAX_SAFE_INTEGER], new IdleImpl(scope, options)]
-    ]
-
-    return new MixedImpl(queues)
-  }))
+const RAF_PRIORITY_RANGE = 10;
 
 /**
+ * Defines priority levels for rendering tasks.
+ *
+ * @example
+ * ```ts
+ * import { RenderPriority } from "@typed/template/RenderQueue"
+ *
+ * // Synchronous execution (highest priority)
+ * const syncPriority = RenderPriority.Sync
+ *
+ * // RequestAnimationFrame priority (0-10)
+ * const rafPriority = RenderPriority.Raf(5)
+ *
+ * // Idle callback priority (lowest priority)
+ * const idlePriority = RenderPriority.Idle(1)
+ * ```
+ *
  * @since 1.0.0
+ * @category utilities
  */
-export const Priority = {
-  Sync: -1,
+export const RenderPriority = {
   /**
-   * @example
-   * RenderPriority.MicroTask(0-9)
+   * Immediate, synchronous execution.
    */
-  MicroTask: (priority: number) => Math.min(Math.max(0, priority), MICRO_TASK_END),
+  Sync: -1,
   /**
-   * @example
-   * RenderPriority.Raf(0-9)
+   * Scheduled via requestAnimationFrame.
+   * @param priority - A value between 0 and 10.
    */
-  Raf: (priority: number) => Math.min(Math.max(DEFAULT_PRIORITY, DEFAULT_PRIORITY + priority), RAF_END),
+  Raf: (priority: number) => Math.max(0, Math.min(priority, RAF_PRIORITY_RANGE)),
   /**
-   * @example
-   * RenderPriority.Idle(0-9)
+   * Scheduled via requestIdleCallback.
    */
-  Idle: (priority: number) => Math.max(IDLE_START, IDLE_START + priority)
-} as const
-
-class PriorityQueue {
-  tasks: Map<unknown, () => void> = new Map()
-  priority: Map<unknown, number> = new Map<unknown, number>()
-  priorities: Map<number, Set<unknown>> = new Map()
-
-  add(part: unknown, task: () => void, priority: number) {
-    this.tasks.set(part, task)
-    this.setPriority(part, priority)
-  }
-
-  get(part: unknown) {
-    return this.tasks.get(part)
-  }
-
-  delete(part: unknown) {
-    this.tasks.delete(part)
-    const priority = this.priority.get(part)
-    if (priority === undefined) {
-      return false
-    } else {
-      this.priorities.get(priority)?.delete(part)
-      this.priority.delete(part)
-      return true
-    }
-  }
-
-  get isEmpty() {
-    return this.priorities.size === 0
-  }
-
-  *entries() {
-    for (const priority of Array.from(this.priorities.keys()).sort((a, b) => a - b)) {
-      const parts = this.priorities.get(priority)!
-      this.priorities.delete(priority)
-      yield this.getTasks(parts)
-    }
-  }
-
-  private getTasks(parts: Set<unknown>) {
-    return Array.from(parts.values()).flatMap((part) => {
-      const task = this.tasks.get(part)
-      if (task === undefined) return []
-      this.tasks.delete(part)
-      this.priority.delete(part)
-      return [task]
-    })
-  }
-
-  private setPriority(task: unknown, priority: number) {
-    const current = this.priority.get(task)
-    if (current === undefined) {
-      this.priority.set(task, priority)
-      this.addTaskToPriority(task, priority)
-      return priority
-    } else if (priority < current) {
-      this.priorities.get(current)?.delete(task)
-      this.priority.set(task, priority)
-      this.addTaskToPriority(task, priority)
-      return priority
-    } else {
-      return current
-    }
-  }
-
-  private addTaskToPriority(task: unknown, priority: number) {
-    let set = this.priorities.get(priority)
-    if (set === undefined) {
-      set = new Set()
-      this.priorities.set(priority, set)
-    }
-    set.add(task)
-  }
+  Idle: (priority: number) => RAF_PRIORITY_RANGE + priority,
+} as const;
+
+function idleDealineFromTime(startTime: number, durationAllowed: number): IdleDeadline {
+  return {
+    timeRemaining: () => {
+      const elapsed = performance.now() - startTime;
+      return Math.max(0, durationAllowed - elapsed);
+    },
+    didTimeout: false,
+  };
 }
 
-abstract class BaseImpl implements RenderQueue {
-  queue = new PriorityQueue()
-  scheduled = false
-
-  constructor(readonly scope: Scope.Scope) {
-    this.add.bind(this)
-  }
-
-  add(part: unknown, task: () => void, priority: number) {
-    return Effect.suspend(() => {
-      this.queue.add(part, task, priority)
-
-      return Effect.zipRight(
-        Effect.addFinalizer(() =>
-          Effect.sync(() => {
-            const currentTask = this.queue.get(part)
-            // If the current task is still the same we'll delete it from the queue
-            if (currentTask === task) {
-              this.queue.delete(part)
-            }
-          })
-        ),
-        this.scheduleNextRun
-      )
-    })
-  }
-
-  scheduleNextRun = Effect.suspend(() => {
-    if (this.queue.isEmpty || this.scheduled) return Effect.void
-
-    this.scheduled = true
-
-    return this.run.pipe(
-      Scope.extend(this.scope),
-      Effect.forkIn(this.scope)
-    )
-  })
-
-  abstract run: Effect.Effect<void, never, Scope.Scope>
-
-  protected runTasks = (iterator: Iterator<Array<() => void>>) => {
-    const result = iterator.next()
-
-    if (result.done) return false
-    else {
-      for (const task of result.value) {
-        this.tryRunTask(task)
-      }
-
-      return true
-    }
-  }
-
-  protected tryRunTask = (task: () => void) => {
-    try {
-      task()
-    } catch (error) {
-      // TODO: We should probably be able to report this back to a template
-      console.error(error)
-    }
-  }
+function disposable(f: () => void): Disposable {
+  return {
+    [Symbol.dispose]: f,
+  };
 }
 
-class IdleImpl extends BaseImpl implements RenderQueue {
-  constructor(
-    scope: Scope.Scope,
-    readonly options?: IdleRequestOptions
-  ) {
-    super(scope)
-  }
-
-  run: Effect.Effect<void, never, Scope.Scope> = Effect.suspend(() => {
-    return Effect.flatMap(
-      Idle.whenIdle(this.options),
-      (deadline) =>
-        Effect.suspend(() => {
-          const iterator = this.queue.entries()
-
-          while (Idle.shouldContinue(deadline) && this.runTasks(iterator)) {
-            // Continue
-          }
-
-          // If we have more work to do, schedule another run
-          if (!this.queue.isEmpty) {
-            return this.run
-          }
-
-          this.scheduled = false
-
-          return Effect.void
-        })
-    )
-  })
+function dispose(self: Disposable): void {
+  if (self === NONE) return;
+  self[Symbol.dispose]();
 }
 
-class RafImpl extends BaseImpl implements RenderQueue {
-  private _set: ((callback: FrameRequestCallback) => number) | typeof setTimeout
-  private _clear: (handle: number) => void
-
-  constructor(
-    readonly scope: Scope.Scope
-  ) {
-    super(scope)
-
-    const [set, clear] = typeof globalThis.requestAnimationFrame === "function"
-      ? [requestAnimationFrame.bind(globalThis), cancelAnimationFrame.bind(globalThis)]
-      : [setTimeout, clearTimeout]
-    this._set = set
-    this._clear = clear
-  }
-
-  run: Effect.Effect<void> = Effect.async((cb) => {
-    const id = this._set(() => {
-      this.runAllTasks()
-      return cb(Effect.void)
-    })
-    return Effect.sync(() => {
-      this.scheduled = false
-      this._clear(id)
-    })
-  })
-
-  private runAllTasks = () => {
-    const iterator = this.queue.entries()
-    while (this.runTasks(iterator)) {
-      // Continue
-    }
-
-    this.scheduled = false
-  }
+function shouldContinue(deadline: IdleDeadline): boolean {
+  return deadline.timeRemaining() > 0;
 }
 
-const noOp = () => void 0
-
-class MicroTaskImpl extends BaseImpl implements RenderQueue {
-  private _set: { (callback: VoidFunction): void; (callback: () => void): void } | typeof setTimeout
-  private _clear:
-    | { (id: number | undefined): void; (timeoutId: string | number | NodeJS.Timeout | undefined): void }
-    | (() => undefined)
-
-  constructor(
-    readonly scope: Scope.Scope
-  ) {
-    super(scope)
-
-    const [set, clear] = typeof globalThis.queueMicrotask === "function"
-      ? [globalThis.queueMicrotask.bind(globalThis), noOp]
-      : [setTimeout, clearTimeout]
-    this._set = set
-    this._clear = clear
-  }
-
-  run: Effect.Effect<void> = Effect.async((cb) => {
-    const id = this._set(() => {
-      this.runAllTasks()
-      return cb(Effect.void)
-    })
-    return Effect.sync(() => {
-      this.scheduled = false
-      if (id) {
-        this._clear(id)
-      }
-    })
-  })
-
-  private runAllTasks = () => {
-    const iterator = this.queue.entries()
-    while (this.runTasks(iterator)) {
-      // Continue
+type KeyedPriorityBucket<A> = [priority: number, Map<unknown, A>];
+
+function insert<A>(
+  buckets: Array<KeyedPriorityBucket<A>>,
+  priority: number,
+  key: unknown,
+  task: A,
+  onRemoved: (task: A) => void,
+): void {
+  const index = binarySearch(buckets, priority);
+  if (index === buckets.length) {
+    buckets.push([priority, new Map([[key, task]])]);
+  } else {
+    const map = buckets[index][1];
+    const existing = map.get(key);
+    if (existing !== undefined) {
+      onRemoved(existing);
     }
-
-    this.scheduled = false
+    map.set(key, task);
   }
 }
 
-class SyncImpl implements RenderQueue {
-  constructor() {
-    this.add.bind(this)
-  }
-
-  add(_: unknown, task: () => void) {
-    return Effect.sync(task)
+function remove<A>(buckets: Array<KeyedPriorityBucket<A>>, priority: number, key: unknown): void {
+  const index = binarySearch(buckets, priority);
+  if (index === buckets.length) {
+    return;
   }
+  buckets[index][1].delete(key);
 }
 
-class MixedImpl implements RenderQueue {
-  private _priorityCache = new Map<number, RenderQueue>()
-
-  constructor(
-    readonly queues: Array<readonly [priorityRange: readonly [number, number], RenderQueue]>
-  ) {
-    this.queues.sort(([a], [b]) => a[0] - b[0])
-
-    this.add.bind(this)
-  }
-
-  add(part: unknown, task: () => void, priority: number) {
-    let queue = this.getQueueForPriority(priority)
-
-    if (queue === undefined) {
-      queue = this.queues[this.queues.length - 1][1]
-    }
-
-    return queue.add(part, task, priority)
-  }
-
-  private getQueueForPriority(priority: number) {
-    if (this._priorityCache.has(priority)) {
-      return this._priorityCache.get(priority)!
-    }
-
-    const q = this.queues.find(([range]) => priority >= range[0] && priority <= range[1])
-
-    if (q) {
-      this._priorityCache.set(priority, q[1])
-      return q[1]
+function binarySearch<A>(buckets: Array<KeyedPriorityBucket<A>>, priority: number): number {
+  let low = 0;
+  let high = buckets.length - 1;
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const [bucketPriority] = buckets[mid];
+    if (bucketPriority === priority) {
+      return mid;
+    } else if (bucketPriority < priority) {
+      low = mid + 1;
+    } else {
+      high = mid - 1;
     }
-
-    return q
   }
+  return low;
 }
-
-/**
- * @since 1.0.0
- */
-export const withCurrentPriority = <A, E, R>(f: (priority: number) => Effect.Effect<A, E, R>) =>
-  Effect.flatMap(FiberRef.get(currentPriority), f)
-
-/**
- * @since 1.0.0
- */
-export const usingCurrentPriority: {
-  (priority: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
-  <A, E, R>(effect: Effect.Effect<A, E, R>, priority: number): Effect.Effect<A, E, R>
-} = dual(
-  2,
-  <A, E, R>(effect: Effect.Effect<A, E, R>, priority: number) => Effect.locally(effect, currentPriority, priority)
-)