@xtia/timeline 1.1.3 → 1.1.5

package/README.md

@@ -6,6 +6,7 @@ Timeline is a type-safe, seekable, deterministic choreography system that can co
 
 * [API Reference](#reference)
 * [Playground](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
+* [Intro by HL](https://codepen.io/H-L-the-lessful/full/vELdyvB)
 
 ## Basic Use:
 
@@ -113,13 +114,11 @@ const urlEmitter = filenameEmitter
 
 ```
 
-Range objects also provide a `play()` method that instructs the Timeline to play through that particular range:
+Range objects also be passed to `Timeline`'s `play()` method to play through that particular range:
 
 ```ts
-// play through the first two seconds of the Timeline
-await timeline
-    .range(0, 2000)
-    .play();
+// play through the first 5 seconds of the Timeline at 1000 units/s
+await timeline.play(firstFiveSeconds);
 ```
 
 Custom easers can be passed to `ease()` as `(progress: number) => number`:
@@ -356,6 +355,27 @@ Despite the massive overhaul, the previous API is present and expanded and upgra
 
 ## Reference
 
+### Contents
+
+#### Functions
+
+* [`animate`](#animateduration-function)
+
+#### Classes
+
+* [`Timeline`](#timeline-class)
+* [`TimelinePoint`](#timelinepoint-class)
+* [`TimelineRange`](#timelinerange-class)
+* [`RangeProgression`](#rangeprogression-class)
+* [`Emitter<T>`](#emittert-class)
+
+#### Interfaces
+
+* [`PointEvent`](#pointevent-interface)
+* [`ChainingInterface`](#chaininginterface-interface)
+
+
+
 ### `Timeline` class
 
 A self-contained collection of points and ranges that trigger events as the Timeline seeks to and through them.
@@ -374,17 +394,17 @@ Controls the speed at which a Timeline will progress when driven by the `play()`
 
 Returns true if the Timeline is actively being driven by the `play()` method (including by autoplay).
 
-##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+##### `end: `[`TimelinePoint`](#timelinepoint-class)
 
 Returns the **current** final point in the Timeline.
 
-##### `start: `[`TimelinePoint`](#timelinepoint-interface)
+##### `start: `[`TimelinePoint`](#timelinepoint-class)
 
 Returns a point representing position 0.
 
 #### Methods
 
-##### `point(position): `[`TimelinePoint`](#timelinepoint-interface)
+##### `point(position): `[`TimelinePoint`](#timelinepoint-class)
 
 Returns a point that represents a specific position on the Timeline.
 
@@ -392,7 +412,7 @@ If `position` is greater than that Timeline's end-position, the end-position wil
 
 *Note*, for deterministic consistency, points will be triggered if a forward-moving seek lands exactly on the point's position (or passes it entirely), while a backward-moving seek will trigger points that are passed or moved from.
 
-##### `range(start, duration): `[`TimelineRange`](#timelinerange-interface)
+##### `range(start, duration): `[`TimelineRange`](#timelinerange-class)
 
 Returns a range that represents a section of the Timeline.
 
@@ -404,7 +424,9 @@ If `start` is omitted, the range will start at 0 and represent the full **curren
 
 ##### `seek(toPosition): void`
 
-Sets the Timeline's internal position (`currentTime`), triggering in chronological order listeners attached to any [`TimelinePoint`](#timelinepoint-interface) or [`TimelineRange`](#timelinerange-interface) that are passed or landed on.
+Sets the Timeline's internal position (`currentTime`), triggering in chronological order listeners attached to any [`TimelinePoint`](#timelinepoint-class) or [`TimelineRange`](#timelinerange-class) that are passed or landed on.
+
+`toPosition` may be a number or a [`TimelinePoint`](#timelinepoint-class).
 
 ##### `seek(toPosition, duration, easer?): Promise<void>`
 
@@ -422,9 +444,13 @@ Begins playing through the Timeline, from its current position, at (1000 × `tim
 
 Begins playing through the Timeline, from its current position, at (1000 × `timeScale`) units per second, updating `fps` times per second.
 
+##### `play(range, easer?): Promise<void>`
+
+If a [`TimelineRange`](#timelinerange-class) is passed, the Timeline will play through that range at 1000 units per second, following the rules of a [smooth seek](#seektoposition-duration-easer-promisevoid).
+
 ##### `tween<T>(start, duration, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
 
-Creates a [`TimelineRange`](#timelinerange-interface) and attaches a tweening listener.
+Creates a [`TimelineRange`](#timelinerange-class) and attaches a tweening listener.
 
 Equivalent to
 
@@ -438,24 +464,46 @@ timeline
 
 Returns a [`ChainingInterface`](#chaininginterface-interface) representing the point at which the tween ends.
 
+##### `apply(handler)`
+
+Registers a handler to be invoked on every seek, after points and ranges are applied.
+
+This is useful for systems that use Timeline's point and range emissions to manipulate state that is to be applied *at once* to another system.
+
+```ts
+// don't wastefully render the scene for every entity update
+timeline
+    .range(0, 1000)
+    .tween(10, 30)
+    .apply(v => scene.hero.x = v);
+timeline
+    .range(500, 1000)
+    .tween(15, 50)
+    .apply(v => scene.monster.x = v);
+// render when all updates for a frame are done:
+timeline.apply(() => renderScene(scene));
+```
+
 ##### `tween<T>(start, end, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
 
-As above, but if the second argument is a [`TimelinePoint`](#timelinepoint-interface), it will specify when on the Timeline the tween will *end*.
+As above, but if the second argument is a [`TimelinePoint`](#timelinepoint-class), it will specify when on the Timeline the tween will *end*.
 
 ##### `at(position, apply, reverse?): `[`ChainingInterface`](#chaininginterface-interface)
 
-Creates a [`TimelinePoint`](#timelinepoint-interface) and attaches a listener that will trigger when the Timeline seeks past or to that point.
+Creates a [`TimelinePoint`](#timelinepoint-class) and attaches a listener that will trigger when the Timeline seeks past or to that point.
 
 If `reverse` is a function, that will be called instead of `apply` when the seek that triggered the event was moving backwards. If `reverse` is `true`, `apply` will be called regardless of which direction the seek moved. If `reverse` is false or omitted, this listener will ignore backward-moving seeks.
 
 
 
 
-### `TimelinePoint` interface
+### `TimelinePoint` class
 
 Represents a single point on a [`Timeline`](#timeline-class).
 
-##### Inherits [`Emitter<PointEvent>`](#emittert-interface)
+This class is not meant to be constructed directly; instances are created with [`Timeline.point()`](#pointposition-timelinepoint).
+
+##### Inherits [`Emitter<PointEvent>`](#emittert-class)
 
 Listeners will be invoked with a [`PointEvent`](#pointevent-interface) when a seek passes or lands on the point.
 
@@ -471,11 +519,11 @@ This point's position on the Timeline.
 
 ##### `range(duration): TimelineRange`
 
-Creates a [`TimelineRange`](#timelinerange-interface) on the Timeline to which the point belongs, of the specified duration.
+Creates a [`TimelineRange`](#timelinerange-class) on the Timeline to which the point belongs, of the specified duration.
 
 ##### `to(endPoint): TimelineRange`
 
-Creates a [`TimelineRange`](#timelinerange-interface) on the Timeline to which the point belongs, ending at the specified point.
+Creates a [`TimelineRange`](#timelinerange-class) on the Timeline to which the point belongs, ending at the specified point.
 
 ##### `delta(timeOffset): TimelinePoint`
 
@@ -520,7 +568,7 @@ point
 
 ### `PointEvent` interface
 
-Provides information relevant to [`TimelinePoint`](#timelinepoint-interface) events.
+Provides information relevant to [`TimelinePoint`](#timelinepoint-class) events.
 
 #### Properties
 
@@ -544,21 +592,23 @@ timeline
 
 
 
-### `TimelineRange` interface
+### `TimelineRange` class
 
 Represents a fixed-length, fixed position section of a [`Timeline`](#timeline-class).
 
-##### Inherits [`RangeProgression`](#rangeprogression-interface)
+This class is not meant to be constructed directly; instances are created with [`Timeline.range()`](#rangestart-duration-timelinerange).
+
+##### Inherits [`RangeProgression`](#rangeprogression-class)
 
 Emits a normalised progression (0..1) of the range when the parent Timeline seeks over or into it.
 
 #### Properties
 
-##### `start: `[`TimelinePoint`](#timelinepoint-interface)
+##### `start: `[`TimelinePoint`](#timelinepoint-class)
 
 The point on the Timeline at which this range starts.
 
-##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+##### `end: `[`TimelinePoint`](#timelinepoint-class)
 
 The point on the Timeline at which this range ends.
 
@@ -572,7 +622,7 @@ The length of the range.
 
 Creates two ranges representing two distinct sections of the parent. `position` is relative to the parent's start.
 
-##### `spread(count): `[`TimelinePoint`](#timelinepoint-interface)[]
+##### `spread(count): `[`TimelinePoint`](#timelinepoint-class)[]
 
 Creates and returns `count` points spread evenly over the range.
 
@@ -600,7 +650,7 @@ Creates a new range by offsetting the parent by a given time delta.
 
 ##### `contains(point): boolean`
 
-Returns true if the given [`TimelinePoint`](#timelinepoint-interface) sits within this range.
+Returns true if the given [`TimelinePoint`](#timelinepoint-class) sits within this range.
 
 ##### `overlaps(range): boolean`
 
@@ -609,11 +659,13 @@ Returns true if the given range overlaps with this range.
 
 
 
-### `RangeProgression` interface
+### `RangeProgression` class
+
+Represents a step in an immutable [`TimelineRange`](#timelinerange-class) event transformation pipeline.
 
-Represents a step in an immutable [`TimelineRange`](#timelinerange-interface) event transformation pipeline.
+This class is not meant to be constructed directly; instances are created by various transformation methods of [`TimelineRange`](#timelinerange-class).
 
-##### Inherits [`Emitter<number>`](#emittert-interface)
+##### Inherits [`Emitter<number>`](#emittert-class)
 
 Listeners will be invoked when a seek passes or lands within a range.
 
@@ -623,7 +675,7 @@ Listeners will be invoked when a seek passes or lands within a range.
 
 Creates an emitter that applies an easing function to parent emissions.
 
-##### `tween<T>(from, to): `[`Emitter<T>`](#emittert-interface)
+##### `tween<T>(from, to): `[`Emitter<T>`](#emittert-class)
 
 Creates an emitter blends two values, biased by progression emitted by the parent.
 
@@ -637,7 +689,7 @@ blend(from: this, to: this, progress: number): this
 
 Creates an emitter that quantises progression emitted by the parent to the nearest of `steps` discrete values.
 
-##### `sample<T>(values: ArrayLike<T>): `[`Emitter<T>`](#emittert-interface)
+##### `sample<T>(values: ArrayLike<T>): `[`Emitter<T>`](#emittert-class)
 
 Creates an emitter that emits values from an array according to progression.
 
@@ -705,7 +757,7 @@ range
 
 
 
-### `Emitter<T>` interface
+### `Emitter<T>` class
 
 #### Methods
 
@@ -713,6 +765,8 @@ range
 
 Attaches a handler to the emitter and returns a function that will unsubscribe the handler.
 
+This class is not meant to be constructed directly; instances are created by transformation methods.
+
 ##### `map<R>(mapFunc: (value: T) => R): Emitter<R>`
 
 Creates an emitter that performs an arbitrary transformation.
@@ -753,7 +807,7 @@ range
 
 ### `animate(duration)` function
 
-Creates and returns a [`TimelineRange`](#timelinerange-interface) that will automatically play over `duration` milliseconds.
+Creates and returns a [`TimelineRange`](#timelinerange-class) that will automatically play over `duration` milliseconds.
 
 ### `ChainingInterface` interface
 
@@ -770,7 +824,7 @@ timeline
 
 #### Properties
 
-##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+##### `end: `[`TimelinePoint`](#timelinepoint-class)
 
 The point on the Timeline at which the effect of the previous chained call ends.
 

package/internal/emitters.d.ts

@@ -14,7 +14,7 @@ export declare class Emitter<T> {
      * @param listen
      * @returns {this}
      */
-    protected redirect: (listen: ListenFunc<T>) => Emitter<T>;
+    protected redirect(listen: ListenFunc<T>): Emitter<T>;
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
      * @param handler
@@ -68,11 +68,10 @@ export declare class Emitter<T> {
      * ```ts
      * range
      *   .tween("0%", "100%")
-     *   .fork(branch => {
-     *     branch
+     *   .fork(branch => branch
      *       .map(s => `Loading: ${s}`)
      *       .apply(s => document.title = s)
-     *   })
+     *   )
      *   .apply(v => progressBar.style.width = v);
      * ```
      * @param cb
@@ -80,7 +79,7 @@ export declare class Emitter<T> {
     fork(cb: (branch: this) => void): this;
 }
 export declare class RangeProgression extends Emitter<number> {
-    protected redirect: (listen: ListenFunc<number>) => RangeProgression;
+    protected redirect(listen: ListenFunc<number>): RangeProgression;
     /**
      * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
      *
@@ -216,4 +215,8 @@ export declare class RangeProgression extends Emitter<number> {
      */
     offset(delta: number): RangeProgression;
 }
+export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLast?: () => void): {
+    listen: (fn: (v: T) => void) => UnsubscribeFunc;
+    emit: (value: T) => void;
+};
 export {};

package/internal/emitters.js

@@ -4,15 +4,17 @@ import { clamp } from "./utils";
 export class Emitter {
     constructor(onListen) {
         this.onListen = onListen;
-        /**
-         * Used by tap() to create a clone of an Emitter with a redirected onListen
-         *
-         * Should be overridden in all Emitter subclasses
-         * @see {@link TimelineRange.redirect}
-         * @param listen
-         * @returns {this}
-         */
-        this.redirect = (listen) => new Emitter(listen);
+    }
+    /**
+     * Used by tap() to create a clone of an Emitter with a redirected onListen
+     *
+     * Should be overridden in all Emitter subclasses
+     * @see {@link TimelineRange.redirect}
+     * @param listen
+     * @returns {this}
+     */
+    redirect(listen) {
+        return new Emitter(listen);
     }
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
@@ -88,26 +90,15 @@ export class Emitter {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb) {
-        const listeners = [];
         let parentUnsubscribe = null;
-        const tappedListen = (handler) => {
-            listeners.push(handler);
-            if (listeners.length === 1) {
-                parentUnsubscribe = this.onListen(value => {
-                    cb(value);
-                    listeners.slice().forEach(fn => fn(value));
-                });
-            }
-            return () => {
-                const idx = listeners.indexOf(handler);
-                listeners.splice(idx, 1);
-                if (listeners.length === 0 && parentUnsubscribe) {
-                    parentUnsubscribe();
-                    parentUnsubscribe = null;
-                }
-            };
-        };
-        return this.redirect(tappedListen);
+        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+            cb(value);
+            emit(value);
+        }), () => {
+            parentUnsubscribe();
+            parentUnsubscribe = null;
+        });
+        return this.redirect(listen);
     }
     /**
      * Immediately passes this emitter to a callback and returns this emitter
@@ -118,11 +109,10 @@ export class Emitter {
      * ```ts
      * range
      *   .tween("0%", "100%")
-     *   .fork(branch => {
-     *     branch
+     *   .fork(branch => branch
      *       .map(s => `Loading: ${s}`)
      *       .apply(s => document.title = s)
-     *   })
+     *   )
      *   .apply(v => progressBar.style.width = v);
      * ```
      * @param cb
@@ -133,9 +123,8 @@ export class Emitter {
     }
 }
 export class RangeProgression extends Emitter {
-    constructor() {
-        super(...arguments);
-        this.redirect = (listen) => new RangeProgression(listen);
+    redirect(listen) {
+        return new RangeProgression(listen);
     }
     ease(easer) {
         if (!easer)
@@ -279,3 +268,24 @@ export class RangeProgression extends Emitter {
         return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
     }
 }
+export function createListenable(onAddFirst, onRemoveLast) {
+    const handlers = [];
+    const addListener = (fn) => {
+        const unique = (v) => fn(v);
+        handlers.push(unique);
+        if (onAddFirst && handlers.length == 1)
+            onAddFirst();
+        return () => {
+            const idx = handlers.indexOf(unique);
+            if (idx === -1)
+                throw new Error("Handler already unsubscribed");
+            handlers.splice(idx, 1);
+            if (onRemoveLast && handlers.length == 0)
+                onRemoveLast();
+        };
+    };
+    return {
+        listen: addListener,
+        emit: (value) => handlers.forEach(h => h(value)),
+    };
+}

package/internal/point.d.ts

@@ -17,7 +17,7 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * The point's absolute position on the Timeline
      */
     position: number);
-    protected redirect: (listen: ListenFunc<PointEvent>) => TimelinePoint;
+    protected redirect(listen: ListenFunc<PointEvent>): TimelinePoint;
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
      * @param duration

package/internal/point.js

@@ -9,7 +9,9 @@ export class TimelinePoint extends Emitter {
         super(onListen);
         this.timeline = timeline;
         this.position = position;
-        this.redirect = (listen) => new TimelinePoint(listen, this.timeline, this.position);
+    }
+    redirect(listen) {
+        return new TimelinePoint(listen, this.timeline, this.position);
     }
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
@@ -56,20 +58,15 @@ export class TimelinePoint extends Emitter {
         return this.filter(-1);
     }
     filter(arg) {
-        if (typeof arg == "number") {
-            return new Emitter(handler => {
-                return this.onListen((ev) => {
-                    if (ev.direction === arg)
-                        handler(ev);
-                });
-            });
-        }
-        return new Emitter(handler => {
-            return this.onListen((ev) => {
+        return new Emitter(typeof arg == "number"
+            ? handler => this.onListen(ev => {
+                if (ev.direction === arg)
+                    handler(ev);
+            })
+            : handler => this.onListen((ev) => {
                 if (arg(ev))
                     handler(ev);
-            });
-        });
+            }));
     }
     /**
      * Creates a Promise that will be resolved when the Timeline first seeks to/past this point

package/internal/range.d.ts

@@ -4,19 +4,21 @@ import { TimelinePoint } from "./point";
 import { Timeline } from "./timeline";
 export declare class TimelineRange extends RangeProgression {
     private timeline;
-    private startPosition;
-    /** The duration of this range */
-    readonly duration: number;
-    private endPosition;
     /** The point on the Timeline at which this range begins */
     readonly start: TimelinePoint;
     /** The point on the Timeline at which this range ends */
     readonly end: TimelinePoint;
-    /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
-    constructor(onListen: ListenFunc<number>, timeline: Timeline, startPosition: number, 
+    private startPosition;
+    private endPosition;
     /** The duration of this range */
-    duration: number);
-    protected redirect: (listen: ListenFunc<number>) => TimelineRange;
+    readonly duration: number;
+    /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
+    constructor(onListen: ListenFunc<number>, timeline: Timeline, 
+    /** The point on the Timeline at which this range begins */
+    start: TimelinePoint, 
+    /** The point on the Timeline at which this range ends */
+    end: TimelinePoint);
+    protected redirect(listen: ListenFunc<number>): TimelineRange;
     /**
      * Creates two ranges by seperating one at a given point
      * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
@@ -70,7 +72,7 @@ export declare class TimelineRange extends RangeProgression {
      * @param point The point to check
      * @returns true if the provided point is within the range
      */
-    contains(point: TimelinePoint): boolean;
+    contains(point: TimelinePoint | number): boolean;
     /**
      * Checks if a range is fully within this range
      * @param range The range to check

package/internal/range.js

@@ -2,21 +2,21 @@ import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
 export class TimelineRange extends RangeProgression {
     /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
-    constructor(onListen, timeline, startPosition, 
-    /** The duration of this range */
-    duration) {
-        super(duration == 0
-            ? () => {
-                throw new Error("Zero-duration ranges may not be listened");
-            }
-            : onListen);
+    constructor(onListen, timeline, 
+    /** The point on the Timeline at which this range begins */
+    start, 
+    /** The point on the Timeline at which this range ends */
+    end) {
+        super(onListen);
         this.timeline = timeline;
-        this.startPosition = startPosition;
-        this.duration = duration;
-        this.redirect = (listen) => new TimelineRange(listen, this.timeline, this.startPosition, this.duration);
-        this.endPosition = startPosition + duration;
-        this.end = timeline.point(this.endPosition);
-        this.start = timeline.point(startPosition);
+        this.start = start;
+        this.end = end;
+        this.startPosition = start.position;
+        this.endPosition = end.position;
+        this.duration = this.endPosition - this.startPosition;
+    }
+    redirect(listen) {
+        return new TimelineRange(listen, this.timeline, this.start, this.end);
     }
     /**
      * Creates two ranges by seperating one at a given point
@@ -26,6 +26,9 @@ export class TimelineRange extends RangeProgression {
      * @returns Tuple of two ranges
      */
     bisect(position = this.duration / 2) {
+        if (position >= this.endPosition) {
+            throw new RangeError("Bisection position is beyond end of range");
+        }
         return [
             this.timeline.range(this.startPosition, position),
             this.timeline.range(position + this.startPosition, this.duration - position),
@@ -93,6 +96,9 @@ export class TimelineRange extends RangeProgression {
         return this.grow((factor - 1) * this.duration, anchor);
     }
     contains(target) {
+        if (typeof target == "number") {
+            return target >= this.startPosition && target < this.endPosition;
+        }
         const [targetStart, targetEnd] = target instanceof TimelinePoint
             ? [target.position, target.position]
             : [target.startPosition, target.startPosition + target.duration];

package/internal/timeline.d.ts

@@ -1,5 +1,5 @@
 import { Easer, easers } from "./easing";
-import { RangeProgression } from "./emitters";
+import { RangeProgression, UnsubscribeFunc } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { Tweenable } from "./tween";
@@ -10,12 +10,16 @@ declare const EndAction: {
     readonly wrap: 2;
     readonly restart: 3;
 };
+type Period = {
+    asMilliseconds: number;
+};
 /**
  * Creates an autoplaying Timeline and returns a range from it
- * @param duration Animation duration, in milliseconds
+ * @param durationMs Animation duration, in milliseconds
  * @returns Object representing a range on a single-use, autoplaying Timeline
  */
-export declare function animate(duration: number): TimelineRange;
+export declare function animate(durationMs: number): TimelineRange;
+export declare function animate(period: Period): TimelineRange;
 export declare class Timeline {
     /**
      * Multiplies the speed at which `play()` progresses through the Timeline
@@ -37,13 +41,15 @@ export declare class Timeline {
     private smoothSeeker;
     private seeking;
     readonly start: TimelinePoint;
-    private progressionHandlers;
+    private _frameEvents;
+    /**
+     * Registers a handler to be invoked on every seek, after points and ranges are applied
+     */
+    apply(handler: () => void): UnsubscribeFunc;
     private _progression;
     /**
      * Listenable: emits a progression value (0..1) when the Timeline's internal
      * position changes, and when the Timeline's total duration is extended
-     *
-     * **Experimental**
      */
     get progression(): RangeProgression;
     constructor();
@@ -114,7 +120,8 @@ export declare class Timeline {
      * @param easer Optional easing function for the smooth-seek process
      * @returns A promise, resolved when the smooth-seek process finishes
      */
-    seek(toPosition: number | TimelinePoint, duration: number, easer?: Easer | keyof typeof easers): Promise<void>;
+    seek(toPosition: number | TimelinePoint, durationMs: number, easer?: Easer | keyof typeof easers): Promise<void>;
+    seek(toPosition: number | TimelinePoint, duration: Period, easer?: Easer | keyof typeof easers): Promise<void>;
     private seekDirect;
     private seekPoints;
     private seekRanges;

package/internal/timeline.js

@@ -1,4 +1,4 @@
-import { RangeProgression } from "./emitters";
+import { createListenable, RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { clamp } from "./utils";
@@ -9,13 +9,11 @@ const EndAction = {
     wrap: 2,
     restart: 3,
 };
-/**
- * Creates an autoplaying Timeline and returns a range from it
- * @param duration Animation duration, in milliseconds
- * @returns Object representing a range on a single-use, autoplaying Timeline
- */
-export function animate(duration) {
-    return new Timeline(true).range(0, duration);
+export function animate(durationMs) {
+    return new Timeline(true)
+        .range(0, typeof durationMs == "number"
+        ? durationMs
+        : durationMs.asMilliseconds);
 }
 export class Timeline {
     get currentTime() { return this._currentTime; }
@@ -28,16 +26,32 @@ export class Timeline {
     get end() {
         return this.point(this._endPosition);
     }
+    /**
+     * Registers a handler to be invoked on every seek, after points and ranges are applied
+     */
+    apply(handler) {
+        if (this._frameEvents === null) {
+            const { emit, listen } = createListenable();
+            this._frameEvents = {
+                listen,
+                emit,
+            };
+        }
+        return this._frameEvents.listen(handler);
+    }
     /**
      * Listenable: emits a progression value (0..1) when the Timeline's internal
      * position changes, and when the Timeline's total duration is extended
-     *
-     * **Experimental**
      */
     get progression() {
-        if (this._progression === null)
-            this._progression = new TimelineProgressionEmitter(this.progressionHandlers);
-        return this._progression;
+        if (this._progression === null) {
+            const { emit, listen } = createListenable();
+            this._progression = {
+                emitter: new TimelineProgressionEmitter(listen),
+                emit,
+            };
+        }
+        return this._progression.emitter;
     }
     constructor(autoplay = false, endAction = "pause") {
         /**
@@ -55,7 +69,7 @@ export class Timeline {
         this.smoothSeeker = null;
         this.seeking = false;
         this.start = this.point(0);
-        this.progressionHandlers = [];
+        this._frameEvents = null;
         this._progression = null;
         if (endAction == "loop")
             endAction = "restart";
@@ -93,32 +107,25 @@ export class Timeline {
     point(position) {
         if (position > this._endPosition) {
             this._endPosition = position;
-            this.progressionHandlers.slice().forEach(h => h(this._currentTime / position));
+            this._progression?.emit(this._currentTime / position);
         }
-        const handlers = [];
-        const data = {
-            handlers,
-            position,
-        };
+        const { emit, listen } = createListenable(() => this.points.push(data), () => {
+            const idx = this.points.indexOf(data);
+            this.points.splice(idx, 1);
+        });
         const addHandler = (handler) => {
             if (this.seeking)
                 throw new Error("Can't add a listener while seeking");
-            // we're adding and removing points and ranges to the internal registry according to whether any subscriptions are active, to allow obsolete points and ranges to be garbage-collected
-            if (handlers.length == 0) {
-                this.points.push(data);
-                this.currentSortDirection = 0;
+            if (position == this._currentTime) {
+                emit({
+                    direction: 1
+                });
             }
-            handlers.push(handler);
-            return () => {
-                const idx = handlers.indexOf(handler);
-                if (idx === -1)
-                    throw new Error("Internal error: attempting to remove a non-present handler");
-                handlers.splice(idx, 1);
-                if (handlers.length == 0) {
-                    const idx = this.points.indexOf(data);
-                    this.points.splice(idx, 1);
-                }
-            };
+            return listen(handler);
+        };
+        const data = {
+            emit,
+            position,
         };
         return new TimelinePoint(addHandler, this, position);
     }
@@ -128,35 +135,31 @@ export class Timeline {
             : start;
         const startPosition = startPoint.position;
         const duration = optionalDuration ?? this._endPosition - startPosition;
-        // const endPosition = startPosition + duration;
-        //if (endPosition > this._endPosition) this._endPosition = endPosition;
-        // ^ leave this to range's point() calls
-        const handlers = [];
-        const range = {
+        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 rangeData = {
             position: startPosition,
             duration,
-            handlers,
+            emit,
         };
-        const addHandler = (handler) => {
-            if (this.seeking)
-                throw new Error("Can't add a listener while seeking");
-            if (handlers.length == 0) {
-                this.ranges.push(range);
-                this.currentSortDirection = 0;
+        const addHandler = duration == 0
+            ? () => {
+                throw new Error("Zero-duration ranges may not be listened");
             }
-            handlers.push(handler);
-            return () => {
-                const idx = handlers.indexOf(handler);
-                if (idx === -1)
-                    throw new Error("Internal error: attempting to remove a non-present handler");
-                handlers.splice(idx, 1);
-                if (handlers.length == 0) {
-                    const idx = this.ranges.indexOf(range);
-                    this.ranges.splice(idx, 1);
+            : (handler) => {
+                if (this.seeking)
+                    throw new Error("Can't add a listener while seeking");
+                if (range.contains(this._currentTime)) {
+                    let progress = clamp((this._currentTime - startPosition) / duration, 0, 1);
+                    handler(progress);
                 }
+                return listen(handler);
             };
-        };
-        return new TimelineRange(addHandler, this, startPosition, duration);
+        const range = new TimelineRange(addHandler, this, startPoint, endPoint);
+        return range;
     }
     getWrappedPosition(n) {
         if (this.endAction.type !== EndAction.wrap)
@@ -174,7 +177,10 @@ export class Timeline {
         const remainder = overflow % segment;
         return loopStart + remainder;
     }
-    seek(to, duration = 0, easer) {
+    seek(to, duration, easer) {
+        const durationMs = typeof duration == "object"
+            ? duration.asMilliseconds
+            : duration;
         const toPosition = typeof to == "number"
             ? to
             : to.position;
@@ -183,20 +189,26 @@ export class Timeline {
         }
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
-            // ensure any awaits are resolved for the previous seek
-            this.smoothSeeker.seek(this.smoothSeeker.end);
+            // ensure any awaits are resolved for the interrupted seek
+            const interruptPosition = this._currentTime;
+            this.smoothSeeker.seekDirect(this.smoothSeeker.end.position);
             this.smoothSeeker = null;
+            // and jump back to where we were interrupted
+            this.seekDirect(interruptPosition);
         }
-        if (duration === 0) {
+        if (!durationMs) {
+            const fromTime = this._currentTime;
             this.seekDirect(toPosition);
-            return Promise.resolve();
+            this._frameEvents?.emit();
+            // only add Promise overhead if duration is explicitly 0
+            return durationMs === 0 ? Promise.resolve() : undefined;
         }
         const seeker = new Timeline(true);
         this.smoothSeeker = seeker;
         seeker
-            .range(0, duration)
+            .range(0, durationMs)
             .ease(easer)
-            .tween(this.currentTime, toPosition)
+            .tween(this._currentTime, toPosition)
             .apply(v => this.seekDirect(v));
         return seeker.end.promise();
     }
@@ -242,10 +254,12 @@ export class Timeline {
         pointsBetween.slice().forEach(p => {
             this.seekRanges(p.position);
             this._currentTime = p.position;
-            p.handlers.slice().forEach(h => h(eventData));
+            p.emit(eventData);
         });
     }
     seekRanges(to) {
+        if (this._currentTime === to)
+            return;
         const fromTime = Math.min(this._currentTime, to);
         const toTime = Math.max(this._currentTime, to);
         this.ranges.slice().forEach((range) => {
@@ -253,10 +267,10 @@ export class Timeline {
             const overlaps = fromTime <= rangeEnd && toTime >= range.position;
             if (overlaps) {
                 let progress = clamp((to - range.position) / range.duration, 0, 1);
-                range.handlers.slice().forEach(h => h(progress));
+                range.emit(progress);
             }
         });
-        this.progressionHandlers.slice().forEach(h => h(toTime / this._endPosition));
+        this._progression?.emit(toTime / this._endPosition);
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -289,7 +303,7 @@ export class Timeline {
                 this.currentTime += delta;
                 return;
             }
-            // overshot; perform endAction			
+            // overshot; perform restart/pause endAction			
             if (this.endAction.type == EndAction.restart) {
                 const loopRange = this.endAction.at.to(this._endPosition);
                 const loopLen = loopRange.duration;
@@ -379,15 +393,8 @@ export class Timeline {
     }
 }
 class TimelineProgressionEmitter extends RangeProgression {
-    constructor(handlers) {
-        super((handler) => {
-            const unique = (n) => handler(n);
-            handlers.push(unique);
-            return () => {
-                const idx = handlers.indexOf(unique);
-                handlers.splice(idx, 1);
-            };
-        });
+    constructor(listen) {
+        super(listen);
     }
 }
 const sortEvents = (a, b) => {

package/internal/tween.d.ts

@@ -1,5 +1,5 @@
 /** @internal */
-export type Tweenable = number | number[] | string | string[] | Blendable | Blendable[];
+export type Tweenable = number | number[] | string | string[] | Blendable | Date | Blendable[];
 /** @internal */
 export interface Blendable {
     blend(target: this, progress: number): this;

package/internal/tween.js

@@ -18,7 +18,14 @@ export function createTween(from, to) {
     }
     switch (typeof from) {
         case "number": return progress => blendNumbers(from, to, progress);
-        case "object": return progress => from.blend(to, progress);
+        case "object": {
+            if (from instanceof Date) {
+                const fromStamp = from.getTime();
+                const toStamp = to.getTime();
+                return progress => new Date(blendNumbers(fromStamp, toStamp, progress));
+            }
+            return progress => from.blend(to, progress);
+        }
         case "string": return createStringTween(from, to);
         default: throw new Error("Invalid tweening type");
     }
@@ -26,9 +33,9 @@ export function createTween(from, to) {
 function createStringTween(from, to) {
     const fromChunks = tokenise(from);
     const toChunks = tokenise(to);
-    const tokenCount = fromChunks.filter(c => c.token).length;
-    // where length mismatch, use merging
-    if (tokenCount !== toChunks.filter(c => c.token).length) {
+    const tokenCount = fromChunks.length;
+    // where token count mismatch, use merging
+    if (tokenCount !== toChunks.length) {
         return createStringMerge(from, to);
     }
     // where token prefix/type mismatch, use merging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"
@@ -22,7 +22,8 @@
   },
   "keywords": [
     "animation",
-    "timeline"
+    "timeline",
+    "choreography"
   ],
   "author": "Aleta Lovelace",
   "license": "MIT"