@velumo/runtime 0.1.0-beta.0

package/src/timeline.ts

@@ -0,0 +1,323 @@
+import type { Cue } from "@velumo/core";
+
+const ERROR_PREFIX = "TimelineScheduler: ";
+
+function validateNonNegativeFinite(value: number, field: string): void {
+  if (!Number.isFinite(value)) {
+    throw new Error(
+      `${ERROR_PREFIX}${field} must be a finite number; got ${String(value)}`,
+    );
+  }
+  if (value < 0) {
+    throw new Error(
+      `${ERROR_PREFIX}${field} must be non-negative; got ${value}`,
+    );
+  }
+}
+
+function validateDuration(value: number | undefined): void {
+  if (value === undefined) {
+    return;
+  }
+  validateNonNegativeFinite(value, "duration");
+  if (value === 0) {
+    throw new Error(`${ERROR_PREFIX}duration must be greater than 0; got 0`);
+  }
+}
+
+function validateInitialTimeMs(
+  value: number | undefined,
+  duration: number | undefined,
+): void {
+  if (value === undefined) {
+    return;
+  }
+  validateNonNegativeFinite(value, "initialTimeMs");
+  if (duration !== undefined && value > duration) {
+    throw new Error(
+      `${ERROR_PREFIX}initialTimeMs (${value}) exceeds duration (${duration})`,
+    );
+  }
+}
+
+function validateCues(
+  cues: readonly Cue[] | undefined,
+  duration: number | undefined,
+): void {
+  if (cues === undefined) {
+    return;
+  }
+  for (const cue of cues) {
+    validateNonNegativeFinite(cue.time, "cue.time");
+    if (duration !== undefined && cue.time > duration) {
+      throw new Error(
+        `${ERROR_PREFIX}cue.time (${cue.time}) exceeds duration (${duration}); the cue could never fire`,
+      );
+    }
+  }
+}
+
+export type TimelineEventName = "cue:fired" | "scene:end" | "state:change";
+
+export interface TimelineCueFiredEvent {
+  readonly type: "cue:fired";
+  readonly timeMs: number;
+  readonly cueIndex: number;
+  readonly cue: Cue;
+}
+
+export interface TimelineSceneEndEvent {
+  readonly type: "scene:end";
+  readonly timeMs: number;
+}
+
+export interface TimelineStateChangeEvent {
+  readonly type: "state:change";
+  readonly state: TimelineState;
+}
+
+export type TimelineEvent =
+  | TimelineCueFiredEvent
+  | TimelineSceneEndEvent
+  | TimelineStateChangeEvent;
+
+export type TimelineEventHandler<E extends TimelineEvent = TimelineEvent> = (
+  event: E,
+) => void;
+
+export interface TimelineState {
+  readonly timeMs: number;
+  readonly isPlaying: boolean;
+  readonly firedCueIndices: readonly number[];
+  readonly sceneEnded: boolean;
+}
+
+export interface TimelineSchedulerOptions {
+  readonly cues?: readonly Cue[];
+  readonly duration?: number;
+  readonly initialTimeMs?: number;
+  readonly initialPlaying?: boolean;
+}
+
+export class TimelineScheduler {
+  readonly #cues: Cue[];
+  readonly #duration: number | undefined;
+  readonly #handlers = new Map<TimelineEventName, Set<TimelineEventHandler>>();
+  #timeMs: number;
+  #isPlaying: boolean;
+  readonly #firedCueIndices: Set<number>;
+  #sceneEnded: boolean;
+
+  constructor(options: TimelineSchedulerOptions = {}) {
+    validateDuration(options.duration);
+    validateCues(options.cues, options.duration);
+    validateInitialTimeMs(options.initialTimeMs, options.duration);
+
+    this.#duration = options.duration;
+    this.#cues = options.cues === undefined ? [] : [...options.cues];
+    this.#cues.sort((a, b) => a.time - b.time);
+
+    this.#timeMs = options.initialTimeMs ?? 0;
+    this.#isPlaying = options.initialPlaying ?? false;
+    this.#firedCueIndices = new Set<number>();
+    this.#sceneEnded =
+      this.#duration !== undefined && this.#timeMs === this.#duration;
+
+    if (this.#timeMs > 0) {
+      for (let i = 0; i < this.#cues.length; i += 1) {
+        if (this.#cues[i].time <= this.#timeMs) {
+          this.#firedCueIndices.add(i);
+        }
+      }
+    }
+  }
+
+  getCues(): readonly Cue[] {
+    return [...this.#cues];
+  }
+
+  getState(): TimelineState {
+    return {
+      timeMs: this.#timeMs,
+      isPlaying: this.#isPlaying,
+      firedCueIndices: [...this.#firedCueIndices].sort((a, b) => a - b),
+      sceneEnded: this.#sceneEnded,
+    };
+  }
+
+  play(): void {
+    if (this.#isPlaying) {
+      return;
+    }
+    this.#isPlaying = true;
+    this.#emitStateChange();
+  }
+
+  pause(): void {
+    if (!this.#isPlaying) {
+      return;
+    }
+    this.#isPlaying = false;
+    this.#emitStateChange();
+  }
+
+  seek(timeMs: number): void {
+    if (!Number.isFinite(timeMs)) {
+      throw new Error(
+        `${ERROR_PREFIX}seek(timeMs): timeMs must be a finite number; got ${String(timeMs)}`,
+      );
+    }
+    if (timeMs < 0) {
+      throw new Error(
+        `${ERROR_PREFIX}seek(timeMs): timeMs must be non-negative; got ${timeMs}`,
+      );
+    }
+
+    const clamped =
+      this.#duration !== undefined ? Math.min(timeMs, this.#duration) : timeMs;
+    this.#timeMs = clamped;
+    this.#firedCueIndices.clear();
+
+    // clamped > 0 leaves cue-at-time-0 unfired so the "cue at time === 0
+    // fires on first forward advance from 0" boundary rule still applies after seek(0).
+    if (clamped > 0) {
+      for (let i = 0; i < this.#cues.length; i += 1) {
+        if (this.#cues[i].time <= clamped) {
+          this.#firedCueIndices.add(i);
+        }
+      }
+    }
+
+    this.#sceneEnded =
+      this.#duration !== undefined && clamped === this.#duration;
+
+    this.#emitStateChange();
+  }
+
+  advance(deltaMs: number): void {
+    if (!Number.isFinite(deltaMs)) {
+      throw new Error(
+        `${ERROR_PREFIX}advance(deltaMs): deltaMs must be a finite number; got ${String(deltaMs)}`,
+      );
+    }
+    if (deltaMs < 0) {
+      throw new Error(
+        `${ERROR_PREFIX}advance(deltaMs): deltaMs must be non-negative; got ${deltaMs}`,
+      );
+    }
+
+    if (deltaMs === 0) {
+      return;
+    }
+    if (!this.#isPlaying) {
+      return;
+    }
+    if (this.#sceneEnded) {
+      return;
+    }
+
+    const prevTime = this.#timeMs;
+    let newTime = prevTime + deltaMs;
+    let willEnd = false;
+
+    if (this.#duration !== undefined && newTime >= this.#duration) {
+      newTime = this.#duration;
+      willEnd = true;
+    }
+
+    const cuesToFire: number[] = [];
+    for (let i = 0; i < this.#cues.length; i += 1) {
+      const cue = this.#cues[i];
+      if (this.#firedCueIndices.has(i)) {
+        continue;
+      }
+      const inRange =
+        cue.time <= newTime &&
+        (cue.time > prevTime || (prevTime === 0 && cue.time === 0));
+      if (inRange) {
+        cuesToFire.push(i);
+      }
+    }
+
+    this.#timeMs = newTime;
+    if (willEnd) {
+      this.#sceneEnded = true;
+    }
+
+    for (const cueIndex of cuesToFire) {
+      this.#firedCueIndices.add(cueIndex);
+      this.#emit("cue:fired", {
+        type: "cue:fired",
+        timeMs: newTime,
+        cueIndex,
+        cue: this.#cues[cueIndex],
+      });
+    }
+
+    if (willEnd) {
+      this.#emit("scene:end", {
+        type: "scene:end",
+        timeMs: newTime,
+      });
+    }
+
+    this.#emitStateChange();
+  }
+
+  on(eventName: TimelineEventName, handler: TimelineEventHandler): () => void {
+    let handlers = this.#handlers.get(eventName);
+    if (handlers === undefined) {
+      handlers = new Set();
+      this.#handlers.set(eventName, handlers);
+    }
+    handlers.add(handler);
+
+    let disposed = false;
+    return () => {
+      if (disposed) {
+        return;
+      }
+      disposed = true;
+      handlers.delete(handler);
+    };
+  }
+
+  #emit(eventName: TimelineEventName, event: TimelineEvent): void {
+    const handlers = this.#handlers.get(eventName);
+    if (handlers === undefined) {
+      return;
+    }
+    for (const handler of [...handlers]) {
+      handler(event);
+    }
+  }
+
+  #emitStateChange(): void {
+    this.#emit("state:change", {
+      type: "state:change",
+      state: this.getState(),
+    });
+  }
+}
+
+export function createTimelineScheduler(
+  options?: TimelineSchedulerOptions,
+): TimelineScheduler {
+  return new TimelineScheduler(options);
+}
+
+export type EasingFunction = (t: number) => number;
+
+const _timelineEasingTypeCheck: EasingFunction = (t) => t;
+void _timelineEasingTypeCheck;
+
+export function lerp(start: number, end: number, t: number): number {
+  return start + (end - start) * t;
+}
+
+export function easeInOutCubic(t: number): number {
+  if (t < 0.5) {
+    return 4 * t ** 3;
+  }
+  return 1 - Math.pow(-2 * t + 2, 3) / 2;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "references": [{ "path": "../core" }]
+}