@xtia/timeline 1.2.1 → 1.2.3

package/index.d.ts

@@ -1,5 +1,6 @@
-export { Timeline, animate, ChainingInterface } from "./internal/timeline.js";
+export { Timeline, ChainingInterface } from "./internal/timeline.js";
+export { animate } from "./internal/animate.js";
 export { TimelinePoint, PointEvent } from "./internal/point.js";
 export { TimelineRange } from "./internal/range.js";
-export { Emitter, RangeProgression, UnsubscribeFunc } from "./internal/emitters.js";
+export { type Emitter, type RangeProgression, UnsubscribeFunc } from "./internal/emitters.js";
 export { easers } from "./internal/easing.js";

package/index.js

@@ -1,5 +1,5 @@
-export { Timeline, animate } from "./internal/timeline.js";
+export { Timeline } from "./internal/timeline.js";
+export { animate } from "./internal/animate.js";
 export { TimelinePoint } from "./internal/point.js";
 export { TimelineRange } from "./internal/range.js";
-export { Emitter, RangeProgression } from "./internal/emitters.js";
 export { easers } from "./internal/easing.js";

package/internal/animate.d.ts

@@ -0,0 +1,15 @@
+import { RangeProgression } from "./emitters.js";
+import { Period } from "./utils.js";
+/**
+ * Creates an autoplaying one-shot progression emitter
+ * @param durationMs Animation duration, in milliseconds
+ * @returns Object representing a range on a single-use, autoplaying Timeline
+ */
+export declare function animate(durationMs: number): RangeProgression;
+export declare function animate(period: Period): RangeProgression;
+/**
+ * Creates a looping progression emitter that will play while it has active listeners
+ * @param duration Animation duration, in milliseconds, or a Period
+ * @returns Object representing a range on a looping Timeline
+ */
+export declare function animate(duration: number | Period, looping: true): RangeProgression;

package/internal/animate.js

@@ -0,0 +1,32 @@
+import { masterDriver } from "./driver.js";
+import { createListenable, RangeProgression } from "./emitters.js";
+export function animate(duration, looping = false) {
+    const durationMs = typeof duration == "number"
+        ? duration
+        : duration.asMilliseconds;
+    if (durationMs === Infinity || durationMs < 0)
+        throw new RangeError("animate() duration must be positive and finite");
+    let t = 0;
+    if (looping) {
+        const { emit, listen } = createListenable(() => masterDriver(delta => {
+            t += delta;
+            emit((t / durationMs) % 1);
+        }));
+        return new RangeProgression(h => {
+            h(t);
+            return listen(h);
+        });
+    }
+    const { emit, listen } = createListenable();
+    const masterUnsub = masterDriver(delta => {
+        t = Math.min(durationMs, t + delta);
+        emit(t / durationMs);
+        if (t === duration) {
+            masterUnsub();
+        }
+    });
+    return new RangeProgression(h => {
+        h(t);
+        return listen(h);
+    });
+}

package/internal/driver.d.ts

@@ -0,0 +1 @@
+export declare const masterDriver: (stepFn: (n: number) => void) => () => void;

package/internal/driver.js

@@ -0,0 +1,53 @@
+const default_interval_fps = 60;
+const createRafDriver = (tick) => {
+    let rafId = null;
+    return () => {
+        const frame = (ts) => {
+            tick(ts);
+            rafId = requestAnimationFrame(frame);
+        };
+        rafId = requestAnimationFrame(frame);
+        return () => cancelAnimationFrame(rafId);
+    };
+};
+const createIntervalDriver = (tick) => {
+    const timeSource = globalThis.performance || globalThis.Date;
+    const tickTime = () => tick(timeSource.now());
+    return () => {
+        const intervalId = setInterval(tickTime, 1000 / default_interval_fps);
+        return () => clearInterval(intervalId);
+    };
+};
+export const masterDriver = (() => {
+    const timelines = new Map();
+    let previousTime = null;
+    let pause = null;
+    const stepAll = (currentTime) => {
+        if (previousTime === null) {
+            previousTime = currentTime;
+            return;
+        }
+        const delta = currentTime - previousTime;
+        previousTime = currentTime;
+        timelines.forEach((step, tl) => {
+            step(delta);
+        });
+    };
+    const start = "requestAnimationFrame" in globalThis
+        ? createRafDriver(stepAll)
+        : createIntervalDriver(stepAll);
+    return (stepFn) => {
+        const key = Symbol();
+        timelines.set(key, stepFn);
+        if (timelines.size === 1) {
+            previousTime = null;
+            pause = start();
+        }
+        return () => {
+            timelines.delete(key);
+            if (timelines.size === 0) {
+                pause();
+            }
+        };
+    };
+})();

package/internal/emitters.d.ts

@@ -6,7 +6,7 @@ export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
 export declare class Emitter<T> {
     protected onListen: ListenFunc<T>;
-    protected constructor(onListen: ListenFunc<T>);
+    constructor(onListen: ListenFunc<T>);
     protected transform<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
@@ -41,7 +41,7 @@ export declare class Emitter<T> {
      */
     dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>;
     /**
-     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     * Creates a chainable emitter that forwards emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
      *
      * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
      * All listeners attached to the returned emitter receive the same values as the parent emitter.
@@ -70,6 +70,12 @@ export declare class Emitter<T> {
      * @param cb
      */
     fork(...cb: ((branch: this) => void)[]): this;
+    /**
+     * Creates a chainable emitter that forwards emissions from the parent and any of the provided emitters
+     * @param emitters
+     */
+    or(...emitters: Emitter<T>[]): Emitter<T>;
+    or<U>(...emitters: Emitter<U>[]): Emitter<T | U>;
 }
 export declare class RangeProgression extends Emitter<number> {
     /**

package/internal/emitters.js

@@ -66,7 +66,7 @@ export class Emitter {
         return new Emitter(listen);
     }
     /**
-     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     * Creates a chainable emitter that forwards emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
      *
      * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
      * All listeners attached to the returned emitter receive the same values as the parent emitter.
@@ -104,6 +104,12 @@ export class Emitter {
         cb.forEach(cb => cb(this));
         return this;
     }
+    or(...emitters) {
+        return new Emitter(handler => {
+            const unsubs = [this, ...emitters].map(e => e.listen(handler));
+            return () => unsubs.forEach(unsub => unsub());
+        });
+    }
 }
 export class RangeProgression extends Emitter {
     ease(easer) {

package/internal/timeline.d.ts

@@ -3,31 +3,13 @@ import { RangeProgression, UnsubscribeFunc } from "./emitters.js";
 import { TimelinePoint } from "./point.js";
 import { TimelineRange } from "./range.js";
 import { Tweenable } from "./tween.js";
-import { Widen } from "./utils.js";
+import { Period, Widen } from "./utils.js";
 declare const EndAction: {
     readonly pause: 0;
     readonly continue: 1;
     readonly wrap: 2;
     readonly restart: 3;
 };
-type Period = {
-    asMilliseconds: number;
-};
-/**
- * Creates an autoplaying Timeline and returns a range from it
- * @param durationMs Animation duration, in milliseconds
- * @returns Object representing a range on a single-use, autoplaying Timeline
- */
-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;
@@ -198,6 +180,7 @@ export declare class Timeline {
      * @param from Value at start of range
      * @param to Value at end of range
      * @param easer Optional easing function
+     * @deprecated Legacy API may be absent in a future major version
      */
     tween<T extends Tweenable>(start: number | TimelinePoint, duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer | keyof typeof easers): ChainingInterface;
     tween<T extends Tweenable>(start: number | TimelinePoint, end: TimelinePoint, // ease migration for tl.tween(0, tl.end, ...)
@@ -210,6 +193,7 @@ export declare class Timeline {
      * @param action Handler for forward seeking
      * @param reverse Handler for backward seeking
      * @returns A tween/event chaining interface
+     * @deprecated Legacy API may be absent in a future major version
      */
     at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
     private createChainingInterface;
@@ -218,6 +202,9 @@ export declare class Timeline {
      */
     get position(): number;
 }
+/**
+ * @deprecated Legacy API may be absent in a future major version
+*/
 export interface ChainingInterface {
     thenTween<T extends Tweenable>(duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
     then(action: () => void): ChainingInterface;

package/internal/timeline.js

@@ -2,89 +2,13 @@ import { createListenable, RangeProgression } from "./emitters.js";
 import { TimelinePoint } from "./point.js";
 import { TimelineRange } from "./range.js";
 import { clamp } from "./utils.js";
-const default_interval_fps = 60;
-const createRafDriver = (tick) => {
-    let rafId = null;
-    return () => {
-        const frame = (ts) => {
-            tick(ts);
-            rafId = requestAnimationFrame(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 (timelines.size === 1) {
-                previousTime = null;
-                pause = start();
-            }
-        },
-        remove: (timeline) => {
-            timelines.delete(timeline);
-            if (timelines.size === 0) {
-                pause();
-            }
-        }
-    };
-})();
+import { masterDriver } from "./driver.js";
 const EndAction = {
     pause: 0,
     continue: 1,
     wrap: 2,
     restart: 3,
 };
-export function animate(duration, looping = false) {
-    const tl = new Timeline(false, looping ? "wrap" : "pause");
-    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 {
     /**
      * The current position of this Timeline's 'play head'
@@ -411,8 +335,7 @@ export class Timeline {
             this.seek(arg.start);
             return this.seek(arg.end, arg.duration / this.timeScale, easer);
         }
-        masterDriver.add(this, n => this.next(n));
-        this._pause = () => masterDriver.remove(this);
+        this._pause = masterDriver(n => this.next(n * this.timeScale));
     }
     next(delta) {
         if (this._currentTime + delta <= this._endPosition) {
@@ -481,6 +404,7 @@ export class Timeline {
      * @param action Handler for forward seeking
      * @param reverse Handler for backward seeking
      * @returns A tween/event chaining interface
+     * @deprecated Legacy API may be absent in a future major version
      */
     at(position, action, reverse) {
         const point = typeof position == "number" ? this.point(position) : position;

package/internal/utils.d.ts

@@ -2,3 +2,6 @@
 export declare const clamp: (value: number, min?: number, max?: number) => number;
 /** @internal */
 export type Widen<T> = T extends number ? number : T extends string ? string : T;
+export type Period = {
+    asMilliseconds: number;
+};

package/package.json

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