@xtia/timeline 1.1.2 → 1.1.4

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:
 
@@ -40,7 +41,7 @@ timeline
 timeline
     .range(1000, 2000)
     .tween(0, 255)
-    .listen(value => microcontroller.setPWM(value))
+    .apply(value => microcontroller.setPWM(value))
 
 // make it go
 timeline.play();
@@ -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
 
@@ -440,22 +466,24 @@ Returns a [`ChainingInterface`](#chaininginterface-interface) representing the p
 
 ##### `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 +499,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 +548,7 @@ point
 
 ### `PointEvent` interface
 
-Provides information relevant to [`TimelinePoint`](#timelinepoint-interface) events.
+Provides information relevant to [`TimelinePoint`](#timelinepoint-class) events.
 
 #### Properties
 
@@ -544,21 +572,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 +602,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 +630,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 +639,13 @@ Returns true if the given range overlaps with this range.
 
 
 
-### `RangeProgression` interface
+### `RangeProgression` class
 
-Represents a step in an immutable [`TimelineRange`](#timelinerange-interface) event transformation pipeline.
+Represents a step in an immutable [`TimelineRange`](#timelinerange-class) event transformation pipeline.
 
-##### Inherits [`Emitter<number>`](#emittert-interface)
+This class is not meant to be constructed directly; instances are created by various transformation methods of [`TimelineRange`](#timelinerange-class).
+
+##### Inherits [`Emitter<number>`](#emittert-class)
 
 Listeners will be invoked when a seek passes or lands within a range.
 
@@ -623,7 +655,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 +669,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 +737,7 @@ range
 
 
 
-### `Emitter<T>` interface
+### `Emitter<T>` class
 
 #### Methods
 
@@ -713,6 +745,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 +787,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 +804,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
@@ -80,7 +80,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
      *

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
@@ -133,9 +135,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)

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
@@ -38,19 +38,31 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
     delta(timeOffset: number): TimelinePoint;
     /**
      * Seeks the parent Timeline to this point
+     * @deprecated Use timeline.seek(point)
      */
     seek(): void;
+    /**
+     * Smooth-seeks the parent Timeline to this point
+     * @deprecated Use timeline.seek(point)
+     */
     seek(duration: number, easer?: Easer): Promise<void>;
     /**
      * Creates an emitter that only emits on forward-moving seeks
-     * @returns
+     * @returns Listenable: emits forward-seeking point events
      */
     forwardOnly(): Emitter<PointEvent>;
     /**
      * Creates an emitter that only emits on backward-moving seeks
-     * @returns
+     * @returns Listenable: emits backward-seeking point events
      */
     reverseOnly(): Emitter<PointEvent>;
+    filter(check: (event: PointEvent) => boolean): Emitter<PointEvent>;
+    /**
+     * Creates an emitter that forwards events emitted by seeks of a specific direction
+     * @param allow Direction to allow
+     * @returns Listenable: emits point events that match the given direction
+     */
+    filter(allow: -1 | 1): Emitter<PointEvent>;
     /**
      * Creates a Promise that will be resolved when the Timeline first seeks to/past this point
      *
@@ -79,4 +91,9 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * @returns A function to deregister both handlers
      */
     applyDirectional(apply: () => void, revert: () => void): UnsubscribeFunc;
+    /**
+     * Creates an emitter that forwards point events whose direction differs from the previous emission
+     * @returns Listenable: emits non-repeating point events
+     */
+    dedupe(): Emitter<PointEvent>;
 }

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
@@ -43,27 +45,28 @@ export class TimelinePoint extends Emitter {
     }
     /**
      * Creates an emitter that only emits on forward-moving seeks
-     * @returns
+     * @returns Listenable: emits forward-seeking point events
      */
     forwardOnly() {
-        return new Emitter(handler => {
-            return this.onListen((ev) => {
-                if (ev.direction > 0)
-                    handler(ev);
-            });
-        });
+        return this.filter(1);
     }
     /**
      * Creates an emitter that only emits on backward-moving seeks
-     * @returns
+     * @returns Listenable: emits backward-seeking point events
      */
     reverseOnly() {
-        return new Emitter(handler => {
-            return this.onListen((ev) => {
-                if (ev.direction < 0)
+        return this.filter(-1);
+    }
+    filter(arg) {
+        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
@@ -104,4 +107,17 @@ export class TimelinePoint extends Emitter {
             ? apply()
             : revert());
     }
+    /**
+     * Creates an emitter that forwards point events whose direction differs from the previous emission
+     * @returns Listenable: emits non-repeating point events
+     */
+    dedupe() {
+        let previous = 0;
+        return new Emitter(handler => this.onListen(event => {
+            if (event.direction !== previous) {
+                handler(event);
+                previous = event.direction;
+            }
+        }));
+    }
 }

package/internal/range.d.ts

@@ -16,7 +16,7 @@ export declare class TimelineRange extends RangeProgression {
     constructor(onListen: ListenFunc<number>, timeline: Timeline, startPosition: number, 
     /** The duration of this range */
     duration: number);
-    protected redirect: (listen: ListenFunc<number>) => TimelineRange;
+    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
@@ -48,6 +48,7 @@ export declare class TimelineRange extends RangeProgression {
      * Progresses the Timeline across the range at 1000 units per second
      * @param easer Optional easing function
      * @returns Promise, resolved when the end is reached
+     * @deprecated Use timeline.play(range, easer?)
      */
     play(easer?: Easer | keyof typeof easers): Promise<void>;
     /**
@@ -69,7 +70,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

@@ -1,6 +1,5 @@
 import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
-import { clamp } from "./utils";
 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, 
@@ -14,11 +13,13 @@ export class TimelineRange extends RangeProgression {
         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);
     }
+    redirect(listen) {
+        return new TimelineRange(listen, this.timeline, this.startPosition, this.duration);
+    }
     /**
      * 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
@@ -28,8 +29,8 @@ export class TimelineRange extends RangeProgression {
      */
     bisect(position = this.duration / 2) {
         return [
-            this.timeline.range(position, this.startPosition),
-            this.timeline.range(position + this.startPosition, this.duration - this.startPosition),
+            this.timeline.range(this.startPosition, position),
+            this.timeline.range(position + this.startPosition, this.duration - position),
         ];
     }
     /**
@@ -65,11 +66,12 @@ export class TimelineRange extends RangeProgression {
      * Progresses the Timeline across the range at 1000 units per second
      * @param easer Optional easing function
      * @returns Promise, resolved when the end is reached
+     * @deprecated Use timeline.play(range, easer?)
      */
     play(easer) {
         this.timeline.pause();
         this.timeline.currentTime = this.startPosition;
-        return this.timeline.seek(this.startPosition + this.duration, this.duration, easer);
+        return this.timeline.seek(this.end, this.duration, easer);
     }
     /**
      * Creates a new range representing a direct expansion of this one
@@ -78,16 +80,7 @@ export class TimelineRange extends RangeProgression {
      * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
     grow(delta, anchor = 0) {
-        const clampedAnchor = clamp(anchor, 0, 1);
-        const leftDelta = -delta * (1 - clampedAnchor);
-        const rightDelta = delta * clampedAnchor;
-        const newStart = this.startPosition + leftDelta;
-        const newEnd = this.startPosition + this.duration + rightDelta;
-        if (newEnd < newStart) {
-            const mid = (newStart + newEnd) / 2;
-            return this.timeline.range(mid, 0);
-        }
-        return this.timeline.range(newStart, newEnd - newStart);
+        return this.timeline.range(this.startPosition - (delta * anchor), this.duration + delta);
     }
     /**
      * Creates a new range representing a multiplicative expansion of this one
@@ -99,18 +92,12 @@ export class TimelineRange extends RangeProgression {
         if (factor <= 0) {
             throw new RangeError('Scale factor must be > 0');
         }
-        const clampedAnchor = clamp(anchor, 0, 1);
-        const oldLen = this.endPosition - this.startPosition;
-        const pivot = this.startPosition + oldLen * clampedAnchor;
-        const newStart = pivot - (pivot - this.startPosition) * factor;
-        const newEnd = pivot + (this.endPosition - pivot) * factor;
-        if (newEnd < newStart) {
-            const mid = (newStart + newEnd) / 2;
-            return this.timeline.range(mid, 0);
-        }
-        return this.timeline.range(newStart, newEnd - newStart);
+        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

@@ -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
@@ -89,12 +93,12 @@ export declare class Timeline {
      * Defines a range on this Timeline
      *
      * @param start The position on this Timeline at which the range starts
-     * @param duration Length of the resulting range - if omitted, the range will end at the Timeline's **current** final position
+     * @param duration Length of the resulting range
      * @returns A range on the Timeline
      *
      * Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
-    range(start: number | TimelinePoint, duration?: number): TimelineRange;
+    range(start: number | TimelinePoint, duration: number): TimelineRange;
     /**
      * Creates an observable range from position 0 to the Timeline's **current** final position
      */
@@ -114,7 +118,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;
@@ -124,6 +129,16 @@ export declare class Timeline {
      */
     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>;
+    /**
+     * Stops normal progression instigated by play()
+     *
+     * Does not affect ongoing smooth-seek operations or play(range)
+     *
+     */
     pause(): void;
     /**
      * Progresses the Timeline by 1 unit
@@ -148,7 +163,7 @@ export declare class Timeline {
     get position(): number;
 }
 export interface ChainingInterface {
-    thenTween<T extends Tweenable>(duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer: Easer): ChainingInterface;
+    thenTween<T extends Tweenable>(duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
     then(action: () => void): ChainingInterface;
     thenWait(duration: number): ChainingInterface;
     fork(fn: (chain: ChainingInterface) => void): ChainingInterface;

package/internal/timeline.js

@@ -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; }
@@ -132,7 +130,7 @@ export class Timeline {
         //if (endPosition > this._endPosition) this._endPosition = endPosition;
         // ^ leave this to range's point() calls
         const handlers = [];
-        const range = {
+        const rangeData = {
             position: startPosition,
             duration,
             handlers,
@@ -141,22 +139,28 @@ export class Timeline {
             if (this.seeking)
                 throw new Error("Can't add a listener while seeking");
             if (handlers.length == 0) {
-                this.ranges.push(range);
+                this.ranges.push(rangeData);
                 this.currentSortDirection = 0;
             }
             handlers.push(handler);
+            // if currentTime is in this range, apply immediately
+            if (range.contains(this._currentTime)) {
+                let progress = clamp((this._currentTime - startPosition) / duration, 0, 1);
+                handler(progress);
+            }
             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);
+                    const idx = this.ranges.indexOf(rangeData);
                     this.ranges.splice(idx, 1);
                 }
             };
         };
-        return new TimelineRange(addHandler, this, startPosition, duration);
+        const range = new TimelineRange(addHandler, this, startPosition, duration);
+        return range;
     }
     getWrappedPosition(n) {
         if (this.endAction.type !== EndAction.wrap)
@@ -175,26 +179,36 @@ export class Timeline {
         return loopStart + remainder;
     }
     seek(to, duration = 0, easer) {
+        const durationMs = typeof duration == "number"
+            ? duration
+            : duration.asMilliseconds;
         const toPosition = typeof to == "number"
             ? to
             : to.position;
         if (this.seeking) {
-            throw new Error("Can't seek while seeking");
+            throw new Error("Can't seek while a seek event is processed");
         }
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
-            // ensure any awaits are resolved for the previous seek
-            this.smoothSeeker.end.seek();
+            // ensure any awaits are resolved for the interrupted seek
+            const interruptPosition = this._currentTime;
+            this.smoothSeeker.seek(this.smoothSeeker.end);
             this.smoothSeeker = null;
+            // and jump back to where we were interrupted
+            this.seek(interruptPosition);
         }
-        if (duration === 0) {
+        if (durationMs === 0) {
             this.seekDirect(toPosition);
             return Promise.resolve();
         }
         const seeker = new Timeline(true);
         this.smoothSeeker = seeker;
-        seeker.range(0, duration).ease(easer).tween(this.currentTime, toPosition).apply(v => this.seekDirect(v));
-        return new Promise(r => seeker.end.apply(() => r()));
+        seeker
+            .range(0, durationMs)
+            .ease(easer)
+            .tween(this.currentTime, toPosition)
+            .apply(v => this.seekDirect(v));
+        return seeker.end.promise();
     }
     seekDirect(toPosition) {
         const fromPosition = this._currentTime;
@@ -242,6 +256,8 @@ export class Timeline {
         });
     }
     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) => {
@@ -252,7 +268,7 @@ export class Timeline {
                 range.handlers.slice().forEach(h => h(progress));
             }
         });
-        this.progressionHandlers.slice().forEach(h => h(fromTime / this._endPosition));
+        this.progressionHandlers.slice().forEach(h => h(toTime / this._endPosition));
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -263,9 +279,18 @@ export class Timeline {
             ? sortTweens
             : sortReverse);
     }
-    play(fps = default_fps) {
+    play(arg = default_fps, easer) {
         if (this.interval !== null)
             this.pause();
+        if (this.smoothSeeker) {
+            this.smoothSeeker.pause();
+            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker = null;
+        }
+        if (arg instanceof TimelineRange) {
+            this.seek(arg.start);
+            return this.seek(arg.end, arg.duration / this.timeScale, easer);
+        }
         let previousTime = Date.now();
         this.interval = setInterval(() => {
             const newTime = Date.now();
@@ -276,7 +301,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;
@@ -303,8 +328,14 @@ export class Timeline {
                 return;
             }
             this.currentTime += delta;
-        }, 1000 / fps);
+        }, 1000 / arg);
     }
+    /**
+     * Stops normal progression instigated by play()
+     *
+     * Does not affect ongoing smooth-seek operations or play(range)
+     *
+     */
     pause() {
         if (this.interval === null)
             return;

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,11 @@ 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)
+                return progress => new Date(blendNumbers(from.getTime(), to.getTime(), progress));
+            return progress => from.blend(to, progress);
+        }
         case "string": return createStringTween(from, to);
         default: throw new Error("Invalid tweening type");
     }

package/package.json

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