@xtia/timeline 1.1.19 → 1.2.0

package/README.md

@@ -12,7 +12,9 @@ Timeline is a type-safe, seekable, deterministic choreography system that can co
 
 ## Basic Use:
 
-`npm i @xtia/timeline`
+Install with `npm i @xtia/timeline`
+
+Timeline's primary building block is a *range* that emits a normalised progression (0 -> 1) as time flows through it. It can be expressively chained to ease progression, interpolate values and apply effects.
 
 ```ts
 import { Timeline } from "@xtia/timeline";
@@ -57,12 +59,12 @@ timeline.play();
 const firstFiveSeconds = timeline.range(0, 5000);
 ```
 
-The range object is *applyable* and emits a progression value (between 0 and 1) when the Timeline's internal position passes through or over that period.
+The range object is *applyable* and emits a progression value when the Timeline seeks through or over that period.
 
 ```ts
 firstFiveSeconds
     .apply(
-        value => console.log(`${value} is between 0 and 1`)
+        value => console.log(value) // logs 0 -> 1 over 5 seconds
     );
 ```
 
@@ -104,7 +106,7 @@ range
 // each step in a chain is a 'pure', independent emitter that emits a
 // transformation of its parent's emissions
 const filenameEmitter = range
-    .tween(0, 3)
+    .tween(0, 30)
     .map(Math.floor)
     .dedupe()
     .map(n => `animation-frame-${n}.png`);

package/internal/emitters.d.ts

@@ -221,7 +221,7 @@ export declare class RangeProgression extends Emitter<number> {
      */
     tap(cb: Handler<number>): RangeProgression;
 }
-export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLast?: () => void): {
+export declare function createListenable<T>(sourceListen?: () => UnsubscribeFunc | undefined): {
     listen: (fn: (v: T) => void) => UnsubscribeFunc;
     emit: (value: T) => void;
 };

package/internal/emitters.js

@@ -7,14 +7,9 @@ export class Emitter {
         this.onListen = onListen;
     }
     transform(handler) {
-        let parentUnsubscribe = null;
-        const parentListen = this.onListen;
-        const { emit, listen } = createListenable(() => parentUnsubscribe = parentListen(value => {
+        const { emit, listen } = createListenable(() => this.onListen(value => {
             handler(value, emit);
-        }), () => {
-            parentUnsubscribe();
-            parentUnsubscribe = null;
-        });
+        }));
         return listen;
     }
     /**
@@ -246,21 +241,14 @@ export class RangeProgression extends Emitter {
         let parentUnsubscribe = null;
         let pathUnsubscribe = null;
         const { listen, emit } = createListenable(() => {
-            // onAddFirst - when first listener subscribes
             pathUnsubscribe = pathEvaluator.listen(emit);
             parentUnsubscribe = this.listen((timeValue) => {
                 pathEvaluator.seek(timeValue);
             });
-        }, () => {
-            // onRemoveLast - when last listener unsubscribes  
-            if (pathUnsubscribe) {
+            return () => {
                 pathUnsubscribe();
-                pathUnsubscribe = null;
-            }
-            if (parentUnsubscribe) {
                 parentUnsubscribe();
-                parentUnsubscribe = null;
-            }
+            };
         });
         return new Emitter(listen);
     }
@@ -303,13 +291,14 @@ export class RangeProgression extends Emitter {
         return new RangeProgression(listen);
     }
 }
-export function createListenable(onAddFirst, onRemoveLast) {
+export function createListenable(sourceListen) {
     const handlers = [];
+    let onRemoveLast;
     const addListener = (fn) => {
         const unique = { fn };
         handlers.push(unique);
-        if (onAddFirst && handlers.length == 1)
-            onAddFirst();
+        if (sourceListen && handlers.length == 1)
+            onRemoveLast = sourceListen();
         return () => {
             const idx = handlers.indexOf(unique);
             if (idx === -1)

package/internal/timeline.d.ts

@@ -20,6 +20,14 @@ type Period = {
  */
 export declare function animate(durationMs: number): TimelineRange;
 export declare function animate(period: Period): TimelineRange;
+/**
+ * Creates a looping Timeline and returns a range from it
+ *
+ * This timeline will play while it has active listeners
+ * @param duration Animation duration, in milliseconds, or a Period
+ * @returns Object representing a range on a single-use, autoplaying Timeline
+ */
+export declare function animate(duration: number | Period, looping: true): TimelineRange;
 type TimelineOptions = {
     atEnd?: {
         wrapAt: number;
@@ -27,13 +35,8 @@ type TimelineOptions = {
         restartAt: number;
     } | keyof typeof EndAction;
     timeScale?: number;
-} & ({
-    autoplay: true;
-    fps?: number;
-} | ({
-    autoplay?: false;
-    fps?: never;
-}));
+    autoplay?: boolean;
+};
 export declare class Timeline {
     /**
      * Multiplies the speed at which `play()` progresses through the Timeline
@@ -83,11 +86,6 @@ export declare class Timeline {
      * @param autoplay Pass `true` to begin playing at (1000 × this.timeScale) units per second immediately on creation
      */
     constructor(autoplay: boolean);
-    /**
-     * Creates a Timeline that begins playing immediately at (1000 × this.timeScale) units per second
-     * @param autoplayFps Specifies frames per second
-     */
-    constructor(autoplayFps: number);
     /**
      * @param autoplay If this argument is `true`, the Timeline will begin playing immediately on creation. If the argument is a number, the Timeline will begin playing at the specified frames per second
      * @param endAction Specifies what should happen when the final position is passed by `play()`/`autoplay`
@@ -99,7 +97,7 @@ export declare class Timeline {
      * * `{restartAt: number}`: Like `"restart"` but seeking back to `restartAt` instead of 0
      * * `{wrapAt: number}`: Like `"wrap"` but as if restarting at `wrapAt` instead of 0
      */
-    constructor(autoplay: boolean | number, endAction: {
+    constructor(autoplay: boolean, endAction: {
         wrapAt: number;
     } | {
         restartAt: number;
@@ -166,13 +164,10 @@ export declare class Timeline {
      * Starts progression of the Timeline from its current position at (1000 × this.timeScale) units per second
      */
     play(): void;
-    play(fps: number): void;
     /**
      * Performs a smooth-seek through a range at (1000 × this.timeScale) units per second
      */
     play(range: TimelineRange, easer?: Easer): Promise<void>;
-    private playWithInterval;
-    private playWithRAF;
     private next;
     /**
      * Stops normal progression instigated by play()

package/internal/timeline.js

@@ -3,38 +3,52 @@ import { TimelinePoint } from "./point.js";
 import { TimelineRange } from "./range.js";
 import { clamp } from "./utils.js";
 const default_interval_fps = 60;
-const requestAnimFrame = globalThis?.requestAnimationFrame;
-const cancelAnimFrame = globalThis?.cancelAnimationFrame;
-const rafController = (() => {
-    const timelines = new Map();
+const createRafDriver = (tick) => {
     let rafId = null;
-    const start = () => {
-        let previousTime = null;
-        const frame = (currentTime) => {
-            if (previousTime === null) {
-                previousTime = currentTime;
-            }
-            const elapsed = currentTime - previousTime;
-            previousTime = currentTime;
-            timelines.forEach((step, tl) => {
-                const delta = elapsed * tl.timeScale;
-                step(delta);
-            });
-            rafId = requestAnimFrame(frame);
+    return () => {
+        const frame = (ts) => {
+            tick(ts);
+            rafId = requestAnimationFrame(frame);
         };
-        rafId = requestAnimFrame(frame);
+        rafId = requestAnimationFrame(frame);
+        return () => cancelAnimationFrame(rafId);
+    };
+};
+const createIntervalDriver = (tick) => {
+    return () => {
+        const intervalId = setInterval(() => tick(performance.now()), 1000 / default_interval_fps);
+        return () => clearInterval(intervalId);
+    };
+};
+const masterDriver = (() => {
+    const timelines = new Map();
+    let previousTime = null;
+    let pause = null;
+    const step = (currentTime) => {
+        if (previousTime === null) {
+            previousTime = currentTime;
+        }
+        const delta = currentTime - previousTime;
+        previousTime = currentTime;
+        timelines.forEach((step, tl) => {
+            step(delta * tl.timeScale);
+        });
     };
+    const start = "requestAnimationFrame" in globalThis
+        ? createRafDriver(step)
+        : createIntervalDriver(step);
     return {
         add: (timeline, stepFn) => {
             timelines.set(timeline, stepFn);
-            if (rafId === null)
-                start();
+            if (timelines.size === 1) {
+                previousTime = null;
+                pause = start();
+            }
         },
         remove: (timeline) => {
             timelines.delete(timeline);
             if (timelines.size === 0) {
-                cancelAnimFrame(rafId);
-                rafId = null;
+                pause();
             }
         }
     };
@@ -45,11 +59,31 @@ const EndAction = {
     wrap: 2,
     restart: 3,
 };
-export function animate(durationMs) {
-    return new Timeline(true)
-        .range(0, typeof durationMs == "number"
-        ? durationMs
-        : durationMs.asMilliseconds);
+export function animate(duration, looping = false) {
+    const tl = new Timeline(false, "wrap");
+    const durationMs = typeof duration == "number"
+        ? duration
+        : duration.asMilliseconds;
+    const parentRange = tl.range(0, durationMs).ease();
+    if (looping) {
+        let listeners = 0;
+        const range = new TimelineRange(h => {
+            if (++listeners == 1) {
+                tl.play();
+            }
+            let unsub = parentRange.apply(h);
+            return () => {
+                if (--listeners == 0)
+                    tl.pause();
+                unsub();
+            };
+        }, tl, tl.start, tl.point(durationMs));
+        return range;
+    }
+    else {
+        tl.play();
+        return parentRange;
+    }
 }
 export class Timeline {
     /**
@@ -125,21 +159,12 @@ export class Timeline {
         if (typeof optionsOrAutoplay == "object") {
             endAction = optionsOrAutoplay.atEnd ?? "pause";
             this.timeScale = optionsOrAutoplay.timeScale ?? 1;
-            if ("autoplay" in optionsOrAutoplay && optionsOrAutoplay.autoplay) {
-                if ("fps" in optionsOrAutoplay && optionsOrAutoplay.fps) {
-                    this.play(optionsOrAutoplay.fps);
-                }
-                else {
-                    this.play();
-                }
-            }
+            if (optionsOrAutoplay.autoplay)
+                this.play();
         }
         else if (optionsOrAutoplay === true) {
             this.play();
         }
-        else if (typeof optionsOrAutoplay == "number") {
-            this.play(optionsOrAutoplay);
-        }
         if (typeof endAction == "object"
             && "restartAt" in endAction) {
             this.endAction = {
@@ -173,9 +198,12 @@ export class Timeline {
             this._endPosition = position;
             this._progression?.emit(this._currentTime / position);
         }
-        const { emit, listen } = createListenable(() => this.points.push(data), () => {
-            const idx = this.points.indexOf(data);
-            this.points.splice(idx, 1);
+        const { emit, listen } = createListenable(() => {
+            this.points.push(data);
+            return () => {
+                const idx = this.points.indexOf(data);
+                this.points.splice(idx, 1);
+            };
         });
         const addHandler = (handler) => {
             if (this.seeking)
@@ -200,9 +228,12 @@ export class Timeline {
         const startPosition = startPoint.position;
         const duration = optionalDuration ?? this._endPosition - startPosition;
         const endPoint = this.point(startPosition + duration);
-        const { emit, listen } = createListenable(() => this.ranges.push(rangeData), () => {
-            const idx = this.ranges.indexOf(rangeData);
-            this.ranges.splice(idx, 1);
+        const { emit, listen } = createListenable(() => {
+            this.ranges.push(rangeData);
+            return () => {
+                const idx = this.ranges.indexOf(rangeData);
+                this.ranges.splice(idx, 1);
+            };
         });
         const rangeData = {
             position: startPosition,
@@ -380,26 +411,8 @@ export class Timeline {
             this.seek(arg.start);
             return this.seek(arg.end, arg.duration / this.timeScale, easer);
         }
-        if (arg === undefined && requestAnimFrame) {
-            this.playWithRAF();
-            return;
-        }
-        this.playWithInterval(arg ?? default_interval_fps);
-    }
-    playWithInterval(fps) {
-        let previousTime = performance.now();
-        const interval = setInterval(() => {
-            const newTime = performance.now();
-            const elapsed = newTime - previousTime;
-            previousTime = newTime;
-            let delta = elapsed * this.timeScale;
-            this.next(delta);
-        }, 1000 / fps);
-        this._pause = () => clearInterval(interval);
-    }
-    playWithRAF() {
-        rafController.add(this, n => this.next(n));
-        this._pause = () => rafController.remove(this);
+        masterDriver.add(this, n => this.next(n));
+        this._pause = () => masterDriver.remove(this);
     }
     next(delta) {
         if (this._currentTime + delta <= this._endPosition) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.1.19",
+  "version": "1.2.0",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"