@xtia/timeline 1.0.6 → 1.0.7

package/README.md

@@ -4,6 +4,7 @@
 
 **Timeline** is a general‑purpose, environment-agnostic choreography engine that lets you orchestrate any sequence of value changes; numbers, vectors, colour tokens, custom blendable objects, or arbitrary data structures.
 
+* [API Reference](#reference)
 
 ## Basic Use:
 
@@ -33,8 +34,9 @@ timeline
     );
 
 // use an easing function
-typingRange
+timeline
     .end
+    .delta(500)
     .range(3000)
     .ease("bounce")
     .tween("50%", "0%")
@@ -174,6 +176,7 @@ timeline
 timeline
     .range(0, 2000)
     .tween("--------", "########")
+    .dedupe()
     .listen(v => document.title = v);
 ```
 
@@ -260,10 +263,12 @@ loadingTimeline
     .tween("0%", "100%");
     .listen(v => progressBar.style.width = v);
 
+// and do something when they're loaded
 loadingTimeline
     .end
     .listen(startGame);
 
+// to drive it, just seek forward by 1 for each loaded resource
 resourceUrls.forEach(url => {
     preload(url).then(
         () => loadingTimeline.currentTime++
@@ -279,7 +284,7 @@ timeline.seek(timeline.end, 400, "overshootIn");
 
 ## Backward-compatibility
 
-Despite the massive overhaul, the previous API is present and expanded  and upgrading to 1.0.0 should be frictionless in the vast majority of cases.
+Despite the massive overhaul, the previous API is present and expanded and upgrading to 1.0.0 should be frictionless in the vast majority of cases.
 
 #### Breaking changes
 
@@ -288,7 +293,7 @@ Despite the massive overhaul, the previous API is present and expanded  and upgr
 #### Mitigation
 
 * `timeline.tween()` now accepts TimelinePoint as a starting position, and provides an overload that replaces the `duration: number` parameter with `end: TimelinePoint`.
-* Should you encounter a case where this change still causes issue, eg `tl.tween(0, tl.end / 2, ...)`, `tl.end.position` is equivalent to the old API's `tl.end`.
+* Should you encounter a case where this change still causes issue, eg `timeline.tween(0, timeline.end / 2, ...)`, `timeline.end.position` is equivalent to the old API's `timeline.end`.
 
 #### Enhancements (non-breaking)
 
@@ -299,4 +304,402 @@ Despite the massive overhaul, the previous API is present and expanded  and upgr
 
 * `timeline.position` will be replaced with `timeline.currentTime` to be consistent with other seekable concepts.
 * `"loop"` endAction is now `"restart"` to disambiguate from new looping strategies.
-* `timeline.step()` is redundant now that `currentTime` is writable; use `timeline.currentTime += delta` instead.
+* `timeline.step()` is redundant now that `currentTime` is writable; use `timeline.currentTime += delta` instead.
+
+
+
+## Reference
+
+### `Timeline` class
+
+A self-contained collection of points and ranges that trigger events as the Timeline seeks to and through them.
+
+#### Properties
+
+##### `currentTime: number`
+
+Reads or sets the Timeline's current time position. Setting this property will perform a `seek()`, triggering any listener that is passed or landed on.
+
+##### `timeScale: number`
+
+Controls the speed at which a Timeline will progress when driven by the `play()` method (including by autoplay).
+
+##### `isPlaying: boolean`
+
+Returns true if the Timeline is actively being driven by the `play()` method (including by autoplay).
+
+##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+
+Returns the **current** final point in the Timeline.
+
+##### `start: `[`TimelinePoint`](#timelinepoint-interface)
+
+Returns a point representing position 0.
+
+#### Methods
+
+##### `point(position): `[`TimelinePoint`](#timelinepoint-interface)
+
+Returns a point that represents a specific position on the Timeline.
+
+If `position` is greater than that Timeline's end-position, the end-position will be extended to `position`.
+
+*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)
+
+Returns a range that represents a section of the Timeline.
+
+If the end of the range is beyond the Timeline's end-position, the end-position will be extended to the end of the range.
+
+If `duration` is omitted, the range will extend from `start` to the **current** end-position of the Timeline.
+
+If `start` is omitted, the range will start at 0 and represent the full **current** range of the Timeline.
+
+##### `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.
+
+##### `seek(toPosition, duration, easer?): Promise<void>`
+
+Performs an interruptable 'smooth seek' to a specified position, lasting `duration` milliseconds, with optional easing.
+
+Returns a Promise that will be resolved when the smooth seek is completed (or is interrupted by another seek\*).
+
+\* Resolution on interruption is not finalised in the library's design and the effect should be considered exceptional; relying on it is not recommended. Future versions might reject the promise when its seek is interrupted.
+
+##### `play(): void`
+
+Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating 60 times per second.
+
+##### `play(fps): void`
+
+Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating `fps` times per second.
+
+##### `tween<T>(start, duration, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
+
+Creates a [`TimelineRange`](#timelinerange-interface) and attaches a tweening listener.
+
+Equivalent to
+
+```ts
+timeline
+    .range(start, duration)
+    .ease(easer)
+    .tween(from, to)
+    .listen(apply);
+```
+
+Returns a [`ChainingInterface`](#chaininginterface-interface) representing the point at which the tween ends.
+
+##### `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*.
+
+##### `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.
+
+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
+
+Represents a single point on a [`Timeline`](#timeline-class).
+
+##### Inherits [`Emitter<PointEvent>`](#emittert-interface)
+
+Listeners will be invoked with a [`PointEvent`](#pointevent-interface) when a seek passes or lands on the point.
+
+*Note*, during a point event, the parent Timeline's `currentTime` property will return that point's position, even if the Timeline is configured with a [*wrap* end action](#autoplay-and-looping-strategies) and its true position is beyond its end. For deterministic consistency, ranges will emit values for the point's position before the point emits.
+
+#### Properties
+
+##### `position: number`
+
+This point's position on the Timeline.
+
+#### Methods
+
+##### `range(duration): TimelineRange`
+
+Creates a [`TimelineRange`](#timelinerange-interface) 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.
+
+##### `delta(timeOffset): TimelinePoint`
+
+Creates a `TimelinePoint` at an offset from the this point.
+
+
+
+
+### `PointEvent` interface
+
+Provides information relevant to [`TimelinePoint`](#timelinepoint-interface) events.
+
+#### Properties
+
+##### `direction: -1 | 1`
+
+Provides the direction of the seek that triggered a point event. `direction === 1` indicates that the seek moved forward and `direction === -1` indicates that the seek was moving backwards.
+
+Allows point listeners to undo effects when the Timeline is reversed.
+
+```ts
+timeline
+    .point(4000)
+    .listen(
+        event => element.classList.toggle(
+            "visible",
+            event.direction > 0
+        )
+    );
+```
+
+
+
+
+### `TimelineRange` interface
+
+Represents a fixed-length, fixed position section of a [`Timeline`](#timeline-class).
+
+##### Inherits [`RangeProgression`](#rangeprogression-interface)
+
+Emits a normalised progression (0..1) of the range when the parent Timeline seeks over or into it.
+
+#### Properties
+
+##### `start: `[`TimelinePoint`](#timelinepoint-interface)
+
+The point on the Timeline at which this range starts.
+
+##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+
+The point on the Timeline at which this range ends.
+
+##### `duration: number`
+
+The length of the range.
+
+#### Methods
+
+##### `bisect(position?): [TimelineRange, TimelineRange]`
+
+Creates two ranges representing two distinct sections of the parent. `position` is relative to the parent's start.
+
+##### `spread(count): `[`TimelinePoint`](#timelinepoint-interface)[]
+
+Creates and returns `count` points spread evenly over the range.
+
+##### `play(easer?): Promise<void>`
+
+Instructs the Timeline to which this range belongs to play through the represented range. This playthrough counts as a smooth seek for seek interruption purposes.
+
+Returns a Promise that will be resolved when the range playthrough completes.
+
+##### `grow(delta, anchor?): TimelineRange`
+
+Creates a new range on the parent Timeline. The location and duration of the new range are copied from this range and grown from an anchor point, specified as a normalised (0..1) progression of the parent range.
+
+##### `grow(delta, anchor?): TimelineRange`
+
+Creates a new range on the parent Timeline. The location and duration of the new range are copied from this range and scaled multiplicatively from an anchor point, specified as a normalised (0..1) progression of the parent range.
+
+##### `contains(point)`
+
+Returns true if the given [`TimelinePoint`](#timelinepoint-interface) sits within this range.
+
+
+
+
+### `RangeProgression` interface
+
+Represents a step in an immutable [`TimelineRange`](#timelinerange-interface) event transformation pipeline.
+
+##### Inherits [`Emitter<number>`](#emittert-interface)
+
+Listeners will be invoked when a seek passes or lands within a range.
+
+#### Methods
+
+##### `ease(easer?): RangeProgression`
+
+Creates an emitter that applies an easing function to parent emissions.
+
+##### `tween<T>(from, to): `[`Emitter<T>`](#emittert-interface)
+
+Creates an emitter blends two values, biased by progression emitted by the parent.
+
+`T` may be `string`, `number`, `number[]` or an object type that includes
+
+```ts
+blend(from: this, to: this, progress: number): this
+```
+
+##### `snap(steps): RangeProgression`
+
+Creates an emitter that quantises progression emitted by the parent to the nearest of `steps` discrete values.
+
+##### `threshold(threshold): RangeProgression`
+
+Creates an emitter that emits 0 when the parent emits a value below `threshold` and 1 when a parent emission is equal to or greater than `threshold`.
+
+```ts
+emittedValue = parentEmission < threshold ? 0 : 1
+```
+
+##### `clamp(min?, max?): RangeProgression`
+
+Creates an emitter that clamps progression between `min` and `max`.
+
+##### `repeat(count): RangeProgression`
+
+Creates an emitter that multiplies progression and wraps at 1, thereby mapping to a repeating scale.
+
+##### `tap(cb): RangeProgression`
+
+Creates an emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+
+##### `filter(check: (value) => boolean): RangeProgression`
+
+Creates an emitter that selectively discards parent emissions.
+
+If `check(value)` returns true, the value will be emitted.
+
+##### `dedupe(): RangeProgression`
+
+Creates an emitter that discards emitted values that are the same as the last value emitted by the new emitter
+
+##### `offset(delta): RangeProgression`
+
+Creates an emitter that offsets its parent's values by the given delta, wrapping at 1
+
+##### `fork(cb: (branch) => void): RangeProgression`
+
+Immediately invokes `cb` with this emitter and returns this emitter for further chaining.
+
+Allows branching without breaking a composition chain, eg:
+
+```ts
+range
+  .tween("0%", "100%")
+  .fork(branch => {
+    branch
+      .map(s => `Loading: ${s}`)
+      .listen(s => document.title = s)
+  })
+  .listen(v => progressBar.style.width = v);
+```
+
+
+
+
+### `Emitter<T>` interface
+
+#### Methods
+
+##### `listen(handler: Handler<T>): UnsubscribeFunc`
+
+Attaches a handler to the emitter and returns a function that will unsubscribe the handler.
+
+##### `map<R>(mapFunc: (value: T) => R): Emitter<R>`
+
+Creates an emitter that performs an arbitrary transformation.
+
+##### `filter(check: (value: T) => boolean): Emitter<T>`
+
+Creates an emitter that selectively discards parent emissions.
+
+If `check(value)` returns true, the value will be emitted.
+
+##### `dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>`
+
+Creates an emitter that discards emitted values that are the same as the last value emitted by the new emitter
+
+##### `tap(cb: Handler<T>): Emitter<T>`
+
+Creates an emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+
+##### `fork(cb: (branch: Emitter<T>) => void): Emitter<T>`
+
+Immediately invokes `cb` with this emitter and returns this emitter for further chaining.
+
+Allows branching without breaking a composition chain, eg:
+
+```ts
+range
+  .tween("0%", "100%")
+  .fork(branch => {
+    branch
+      .map(s => `Loading: ${s}`)
+      .listen(s => document.title = s)
+  })
+  .listen(v => progressBar.style.width = v);
+```
+
+
+
+
+### `animate(duration)` function
+
+Creates and returns a [`TimelineRange`](#timelinerange-interface) that will automatically play over `duration` milliseconds.
+
+### `ChainingInterface` interface
+
+Conveys composable sequential tweens and events with the simplified API. Each instance represents a specific point on the parent Timeline.
+
+```ts
+timeline
+    .tween(0, 1000, doThing, 0, 100)
+    .thenWait(500)
+    .then(doOtherThing)
+    .thenWait(250)
+    .thenTween(2000, dothing, 100, 0);
+```
+
+#### Properties
+
+##### `end: `[`TimelinePoint`](#timelinepoint-interface)
+
+The point on the Timeline at which the effect of the previous chained call ends.
+
+#### Methods
+
+##### `thenTween(duration, apply, from, to, easer): ChainingInterface`
+
+Adds a tween, beginning at the point the interface represents. Returns a new `ChainingInterface` representing the end of the new tween.
+
+##### `then(action: () => void): ChainingInterface`
+
+Adds a point event at the point the interface represents.
+
+##### `thenWait(duration): ChainingInterface`
+
+Creates a new `ChainingInterface` by offsetting the parent by `duration`.
+
+
+
+### `easers` const
+
+The following easers are provided:
+
+`linear`, `easeIn`, `easeIn4`, `easeOut`, `easeOut4`, `circleIn`, `circleIn4`, `circleOut`, `circleOut4`, `easeInOut`, `elastic`, `overshootIn`, `sine`, `invert`, `bounce`, `noise`, `pingpong`
+
+Methods that accept an easing function accept both `(progress: number) => number` and any of the names above.
+
+```ts
+timeline
+    .tween(s, e, a, f, t, v => Math.sqrt(v))
+    .thenTween(s, e, a, f, t, c, "elastic");
+
+timeline
+    .range(0, 1000)
+    .ease("circleOut")
+    .ease(easers.easeIn)
+    // ...
+```

package/index.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.easers = exports.animate = exports.Timeline = void 0;
+exports.easers = exports.RangeProgression = exports.Emitter = exports.TimelineRange = exports.TimelinePoint = exports.animate = exports.Timeline = void 0;
 var timeline_1 = require("./internal/timeline");
 Object.defineProperty(exports, "Timeline", { enumerable: true, get: function () { return timeline_1.Timeline; } });
 Object.defineProperty(exports, "animate", { enumerable: true, get: function () { return timeline_1.animate; } });
+var point_1 = require("./internal/point");
+Object.defineProperty(exports, "TimelinePoint", { enumerable: true, get: function () { return point_1.TimelinePoint; } });
+var range_1 = require("./internal/range");
+Object.defineProperty(exports, "TimelineRange", { enumerable: true, get: function () { return range_1.TimelineRange; } });
+var emitters_1 = require("./internal/emitters");
+Object.defineProperty(exports, "Emitter", { enumerable: true, get: function () { return emitters_1.Emitter; } });
+Object.defineProperty(exports, "RangeProgression", { enumerable: true, get: function () { return emitters_1.RangeProgression; } });
 var easing_1 = require("./internal/easing");
 Object.defineProperty(exports, "easers", { enumerable: true, get: function () { return easing_1.easers; } });

package/internal/emitters.d.ts

@@ -1,18 +1,19 @@
 import { Easer, easers } from "./easing";
-import { Blendable } from "./tween";
-import { OptionalIfKeyIn } from "./utils";
-/** @internal */
-export declare function createEmitter<T>(listen: ListenFunc<T>): Emitter<T>;
-/** @internal */
-export declare function createEmitter<T, API extends object>(onListen: ListenFunc<T>, api: OptionalIfKeyIn<API, Emitter<T>>): Emitter<T> & API;
-/** @internal */
-export declare function createProgressEmitter<API extends object>(listen: ListenFunc<number>, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
-/** @internal */
-export declare function createProgressEmitter(listen: ListenFunc<number>): RangeProgression;
+import { Tweenable } from "./tween";
 type Handler<T> = (value: T) => void;
-type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
+export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
-export interface Emitter<T> {
+export declare class Emitter<T> {
+    protected onListen: ListenFunc<T>;
+    protected constructor(onListen: ListenFunc<T>);
+    /**
+     * 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}
+     */
+    protected redirect: (listen: ListenFunc<T>) => Emitter<T>;
     /**
      * Registers a function to receive emitted values
      * @param handler
@@ -50,7 +51,7 @@ export interface Emitter<T> {
      * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
-    tap(cb: Handler<T>): Emitter<T>;
+    tap(cb: Handler<T>): this;
     /**
      * Immediately passes this emitter to a callback and returns this emitter
      *
@@ -69,9 +70,10 @@ export interface Emitter<T> {
      * ```
      * @param cb
      */
-    fork(cb: (branch: Emitter<T>) => void): Emitter<T>;
+    fork(cb: (branch: this) => void): this;
 }
-export interface RangeProgression extends Emitter<number> {
+export declare class RangeProgression extends Emitter<number> {
+    protected redirect: (listen: ListenFunc<number>) => RangeProgression;
     /**
      * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
      *
@@ -79,6 +81,7 @@ export interface RangeProgression extends Emitter<number> {
      * @returns Listenable: emits eased progression values
      */
     ease(easer?: Easer | keyof typeof easers): RangeProgression;
+    ease(easer?: undefined): RangeProgression;
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
@@ -119,7 +122,7 @@ export interface RangeProgression extends Emitter<number> {
      * @param to Value to interpolate to
      * @returns Listenable: emits interpolated values
      */
-    tween<T extends Blendable | number[]>(from: T, to: T): Emitter<T>;
+    tween<T extends Tweenable>(from: T, to: T): Emitter<T>;
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
      *
@@ -161,18 +164,6 @@ export interface RangeProgression extends Emitter<number> {
      * @returns Listenable: emits scaled and repeating values
      */
     repeat(count: number): RangeProgression;
-    /**
-     * Creates a chainable progress emitter that mirrors 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.
-     *
-     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
-     *
-     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
-     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
-     */
-    tap(cb: (value: number) => void): RangeProgression;
     /**
      * Creates a chainable progress emitter that selectively forwards emissions along the chain
      * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
@@ -202,6 +193,5 @@ export interface RangeProgression extends Emitter<number> {
      * @returns Listenable: emits offset values
      */
     offset(delta: number): RangeProgression;
-    fork(cb: (branch: RangeProgression) => void): RangeProgression;
 }
 export {};

package/internal/emitters.js

@@ -1,108 +1,254 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createEmitter = createEmitter;
-exports.createProgressEmitter = createProgressEmitter;
+exports.RangeProgression = exports.Emitter = void 0;
 const easing_1 = require("./easing");
 const tween_1 = require("./tween");
 const utils_1 = require("./utils");
-/** @internal */
-function createEmitter(listen, api) {
-    const methods = {
-        listen: (handler) => listen((value) => {
+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);
+    }
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    listen(handler) {
+        return this.onListen((value) => {
             handler(value);
-        }),
-        map: (mapFunc) => createEmitter(handler => listen((value) => {
+        });
+    }
+    /**
+     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
+     * @param mapFunc
+     * @returns Listenable: emits transformed values
+     */
+    map(mapFunc) {
+        return new Emitter(handler => this.onListen((value) => {
             handler(mapFunc(value));
-        })),
-        filter: (filterFunc) => createEmitter(handler => listen((value) => {
-            if (filterFunc(value))
+        }));
+    }
+    /**
+     * Creates a chainable emitter that selectively forwards emissions along the chain
+     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check) {
+        return new Emitter(handler => this.onListen((value) => {
+            if (check(value))
                 handler(value);
-        })),
-        dedupe: (compare) => {
-            let previous = null;
-            return createEmitter(handler => {
-                const filteredHandler = (value) => {
-                    if (!previous || (compare
-                        ? !compare(previous.value, value)
-                        : (previous.value !== value))) {
-                        handler(value);
-                        previous = { value };
-                    }
-                };
-                return listen(filteredHandler);
-            }, api ?? {});
-        },
-        tap: (cb) => createTap((createEmitter), listen, cb),
-        fork: (cb) => {
-            cb(emitter);
-            return emitter;
-        }
-    };
-    const emitter = (0, utils_1.prototypify)(methods, api ?? {});
-    return emitter;
-}
-/** @internal */
-function createProgressEmitter(listen, api) {
-    const methods = {
-        ease: (easer) => {
-            const easerFunc = typeof easer == "string"
-                ? easing_1.easers[easer]
-                : easer;
-            return createProgressEmitter(easer ? (handler => listen((progress) => {
-                handler(easerFunc(progress));
-            })) : listen);
-        },
-        tween: (from, to) => createEmitter(handler => listen(progress => handler((0, tween_1.tweenValue)(from, to, progress)))),
-        snap: (steps) => {
-            if (!Number.isInteger(steps) || steps <= 0) {
-                throw new RangeError('snap(steps) requires a positive integer');
+        }));
+    }
+    /**
+     * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
+     * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
+     *
+     * If no `compare` function is provided, values will be compared via `===`
+     * @returns Listenable: emits non-repeating values
+     */
+    dedupe(compare) {
+        let previous = null;
+        return new Emitter(handler => {
+            const filteredHandler = (value) => {
+                if (!previous || (compare
+                    ? !compare(previous.value, value)
+                    : (previous.value !== value))) {
+                    handler(value);
+                    previous = { value };
+                }
+            };
+            return this.onListen(filteredHandler);
+        });
+    }
+    /**
+     * Creates a chainable emitter that mirrors 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.
+     *
+     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     *
+     * @param cb A function to be called as a side effect for each value emitted by the parent 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 createProgressEmitter(handler => listen(progress => {
-                const snapped = Math.round(progress * steps) / steps;
-                handler((0, utils_1.clamp)(snapped, 0, 1));
-            }));
-        },
-        threshold: (threshold) => createProgressEmitter(handler => listen(progress => {
+            return () => {
+                const idx = listeners.indexOf(handler);
+                listeners.splice(idx, 1);
+                if (listeners.length === 0 && parentUnsubscribe) {
+                    parentUnsubscribe();
+                    parentUnsubscribe = null;
+                }
+            };
+        };
+        return this.redirect(tappedListen);
+    }
+    /**
+     * Immediately passes this emitter to a callback and returns this emitter
+     *
+     * Allows branching without breaking a composition chain
+     *
+     * @example
+     * ```ts
+     * range
+     *   .tween("0%", "100%")
+     *   .fork(branch => {
+     *     branch
+     *       .map(s => `Loading: ${s}`)
+     *       .listen(s => document.title = s)
+     *   })
+     *   .listen(v => progressBar.style.width = v);
+     * ```
+     * @param cb
+     */
+    fork(cb) {
+        cb(this);
+        return this;
+    }
+}
+exports.Emitter = Emitter;
+class RangeProgression extends Emitter {
+    constructor() {
+        super(...arguments);
+        this.redirect = (listen) => new RangeProgression(listen);
+    }
+    ease(easer) {
+        if (!easer)
+            return this;
+        const easerFunc = typeof easer == "string"
+            ? easing_1.easers[easer]
+            : easer;
+        return new RangeProgression(easer ? (handler => this.onListen((progress) => {
+            handler(easerFunc(progress));
+        })) : h => this.onListen(h));
+    }
+    tween(from, to) {
+        return new Emitter(handler => this.onListen(progress => handler((0, tween_1.tweenValue)(from, to, progress))));
+    }
+    /**
+     * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
+     *
+     * @param steps – positive integer (e.g. 10 → 0, .1, .2 … 1)
+     * @throws RangeError if steps is not a positive integer
+     * @returns Listenable: emits quantised progression values
+     */
+    snap(steps) {
+        if (!Number.isInteger(steps) || steps <= 0) {
+            throw new RangeError('snap(steps) requires a positive integer');
+        }
+        return new RangeProgression(handler => this.onListen(progress => {
+            const snapped = Math.round(progress * steps) / steps;
+            handler((0, utils_1.clamp)(snapped, 0, 1));
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that emits `1` when the incoming progress value is greater‑than‑or‑equal to the supplied `threshold`, otherwise emits `0`
+     *
+     * @param threshold the cut‑off value
+     * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
+     */
+    threshold(threshold) {
+        return new RangeProgression(handler => this.onListen(progress => {
             handler(progress >= threshold ? 1 : 0);
-        })),
-        clamp: (min = 0, max = 1) => createProgressEmitter(handler => listen(progress => handler((0, utils_1.clamp)(progress, min, max)))),
-        repeat: (repetitions) => {
-            repetitions = Math.max(0, repetitions);
-            return createProgressEmitter(handler => listen(progress => {
-                const out = (progress * repetitions) % 1;
-                handler(out);
-            }));
-        },
-        tap: (cb) => createTap(createProgressEmitter, listen, cb),
-        filter: (filterFunc) => createProgressEmitter(handler => listen((value) => {
-            if (filterFunc(value))
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that clamps incoming values
+     * @param min default 0
+     * @param max default 1
+     * @returns Listenable: emits clamped progression values
+     */
+    clamp(min = 0, max = 1) {
+        return new RangeProgression(handler => this.onListen(progress => handler((0, utils_1.clamp)(progress, min, max))));
+    }
+    /**
+     * Creates a chainable progress emitter that maps incoming values to a repeating linear scale
+     *
+     * ```plain
+     * 	count=2
+     *‎	1
+     *‎	 |     /     /
+     *‎	o|    /     /
+     *‎	u|   /     /
+     *‎	t|  /     /
+     *‎	 | /     /
+     *‎	 |/_____/_____
+     *‎	0     in      1
+     * ```
+     *
+     * @param count Number of repetitions
+     * @returns Listenable: emits scaled and repeating values
+     */
+    repeat(count) {
+        count = Math.max(0, count);
+        return new RangeProgression(handler => this.onListen(progress => {
+            const out = (progress * count) % 1;
+            handler(out);
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that selectively forwards emissions along the chain
+     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check) {
+        return new RangeProgression(handler => this.onListen((value) => {
+            if (check(value))
                 handler(value);
-        })),
-        offset: (delta) => createProgressEmitter(handler => listen(value => handler((value + delta) % 1))),
-    };
-    const baseEmitter = createEmitter(listen, methods);
-    const emitter = (0, utils_1.prototypify)(baseEmitter, api ?? {});
-    return emitter;
-}
-function createTap(create, parentListen, cb) {
-    const listeners = [];
-    let parentUnsubscribe = null;
-    const tappedListen = (handler) => {
-        listeners.push(handler);
-        if (listeners.length === 1) {
-            parentUnsubscribe = parentListen(value => {
-                cb(value);
-                listeners.slice().forEach(fn => fn(value));
+        }));
+    }
+    /**
+     * Creates a chainable progress emitter that discards emitted values that are the same as the last value emitted by the new emitter
+     * @returns Listenable: emits non-repeating values
+     */
+    dedupe() {
+        let previous = null;
+        return new RangeProgression(handler => {
+            return this.onListen((value) => {
+                if (!previous === null || previous !== value) {
+                    handler(value);
+                    previous = value;
+                }
             });
-        }
-        return () => {
-            const idx = listeners.indexOf(handler);
-            listeners.splice(idx, 1);
-            if (listeners.length === 0 && parentUnsubscribe) {
-                parentUnsubscribe();
-                parentUnsubscribe = null;
-            }
-        };
-    };
-    return create(tappedListen);
+        });
+    }
+    /**
+     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
+     *
+     * ```plain
+     *‎	1
+     *‎	 |  /
+     *‎	o| /
+     *‎	u|/      __ delta=.5
+     *‎	t|     /
+     *‎	 |    /
+     *‎	 |___/__
+     *‎	0  in   1
+     * ```
+     *
+     * @param delta
+     * @returns Listenable: emits offset values
+     */
+    offset(delta) {
+        return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
+    }
 }
+exports.RangeProgression = RangeProgression;

package/internal/point.d.ts

@@ -1,9 +1,22 @@
-import { Emitter } from "./emitters";
+import { Emitter, ListenFunc } from "./emitters";
 import { TimelineRange } from "./range";
+import { Timeline } from "./timeline";
 export type PointEvent = {
     direction: -1 | 1;
 };
-export interface TimelinePoint extends Emitter<PointEvent> {
+export declare class TimelinePoint extends Emitter<PointEvent> {
+    private timeline;
+    /**
+     * The point's absolute position on the Timeline
+     */
+    readonly position: number;
+    /** @internal Manual construction of TimelinePoint is outside of the API contract and subject to undocumented change */
+    constructor(onListen: ListenFunc<PointEvent>, timeline: Timeline, 
+    /**
+     * The point's absolute position on the Timeline
+     */
+    position: number);
+    protected redirect: (listen: ListenFunc<PointEvent>) => TimelinePoint;
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
      * @param duration
@@ -22,8 +35,4 @@ export interface TimelinePoint extends Emitter<PointEvent> {
      * @returns Listenable: emits a PointEvent when the point is reached or passed by a Timeline seek
      */
     delta(timeOffset: number): TimelinePoint;
-    /**
-     * The point's absolute position on the Timeline
-     */
-    readonly position: number;
 }

package/internal/point.js

@@ -1,2 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimelinePoint = void 0;
+const emitters_1 = require("./emitters");
+class TimelinePoint extends emitters_1.Emitter {
+    /** @internal Manual construction of TimelinePoint is outside of the API contract and subject to undocumented change */
+    constructor(onListen, timeline, 
+    /**
+     * The point's absolute position on the Timeline
+     */
+    position) {
+        super(onListen);
+        this.timeline = timeline;
+        this.position = position;
+        this.redirect = (listen) => new TimelinePoint(listen, this.timeline, this.position);
+    }
+    /**
+     * Creates a range on the Timeline, with a given duration, starting at this point
+     * @param duration
+     * @returns Listenable: emits normalised (0..1) range progression
+     */
+    range(duration) {
+        return this.timeline.range(this.position, duration);
+    }
+    /**
+     * Creates a range on the Timeline, with a given end point, starting at this point
+     * @param endPoint
+     * @returns Listenable: emits normalised (0..1) range progression
+     */
+    to(endPoint) {
+        const endPosition = typeof endPoint == "number"
+            ? endPoint
+            : endPoint.position;
+        return this.timeline.range(this.position, endPosition - this.position);
+    }
+    /**
+     * Creates a point on the Timeline at an offset position from this one
+     * @param timeOffset
+     * @returns Listenable: emits a PointEvent when the point is reached or passed by a Timeline seek
+     */
+    delta(timeOffset) {
+        return this.timeline.point(this.position + timeOffset);
+    }
+}
+exports.TimelinePoint = TimelinePoint;

package/internal/range.d.ts

@@ -1,7 +1,18 @@
 import { Easer, easers } from "./easing";
-import { RangeProgression } from "./emitters";
+import { ListenFunc, RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
-export interface TimelineRange extends RangeProgression {
+import { Timeline } from "./timeline";
+export declare class TimelineRange extends RangeProgression {
+    private timeline;
+    private startPosition;
+    /** The duration of this range */
+    readonly duration: number;
+    private endPosition;
+    /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
+    constructor(onListen: ListenFunc<number>, timeline: Timeline, startPosition: number, 
+    /** The duration of this range */
+    duration: number);
+    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
@@ -41,10 +52,9 @@ export interface TimelineRange extends RangeProgression {
      * @returns true if the provided point is within the range
      */
     contains(point: TimelinePoint): boolean;
+    contains(range: TimelineRange): boolean;
     /** 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;
-    /** The duration of this range */
-    readonly duration: number;
 }

package/internal/range.js

@@ -1,2 +1,100 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimelineRange = void 0;
+const emitters_1 = require("./emitters");
+const point_1 = require("./point");
+const utils_1 = require("./utils");
+class TimelineRange extends emitters_1.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(onListen);
+        this.timeline = timeline;
+        this.startPosition = startPosition;
+        this.duration = duration;
+        this.redirect = (listen) => new TimelineRange(listen, this.timeline, this.startPosition, this.duration);
+        this.start = timeline.point(startPosition);
+        this.end = timeline.point(startPosition + duration);
+        this.endPosition = startPosition + 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
+     *
+     * Must be greater than 0 and less than the range's duration
+     * @returns Tuple of two ranges
+     */
+    bisect(position = this.duration / 2) {
+        return [
+            this.timeline.range(position, this.startPosition),
+            this.timeline.range(position + this.startPosition, this.duration - this.startPosition),
+        ];
+    }
+    /**
+     * Creates a series of evenly-spread points across the range, excluding the range's start and end
+     * @param count Number of Points to return
+     * @returns Array(count) of points
+     */
+    spread(count) {
+        const delta = this.duration / (count + 1);
+        return [
+            ...Array(count).fill(0).map((_, idx) => this.timeline.point(idx * delta + this.startPosition + delta))
+        ];
+    }
+    /**
+     * Progresses the Timeline across the range
+     * @param easer
+     */
+    play(easer) {
+        this.timeline.pause();
+        this.timeline.currentTime = this.startPosition;
+        return this.timeline.seek(this.startPosition + this.duration, this.duration, easer);
+    }
+    /**
+     * Creates a new range representing a direct expansion of this one
+     * @param delta Amount to grow by (in time units)
+     * @param anchor Normalised position at which to expand (0 being the start, expanding right, 1 being the end, expanding left, 0.5 expanding evenly)
+     * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
+     */
+    grow(delta, anchor = 0) {
+        const clampedAnchor = (0, utils_1.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);
+    }
+    /**
+     * Creates a new range representing a multiplicative expansion of this one
+     * @param factor Size multiplier
+     * @param anchor Normalised position at which to expand (0 being the start, expanding right, 1 being the end, expanding left, 0.5 expanding evenly)
+     * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
+     */
+    scale(factor, anchor = 0) {
+        if (factor <= 0) {
+            throw new RangeError('scale factor must be > 0');
+        }
+        const clampedAnchor = (0, utils_1.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);
+    }
+    contains(target) {
+        const [targetStart, targetEnd] = target instanceof point_1.TimelinePoint
+            ? [target.position, target.position]
+            : [target.startPosition, target.startPosition + target.duration];
+        return targetStart >= this.startPosition && targetEnd < this.endPosition;
+    }
+}
+exports.TimelineRange = TimelineRange;

package/internal/timeline.d.ts

@@ -128,9 +128,9 @@ export declare class Timeline {
      * @deprecated Use timeline.position += n
      */
     step(delta: number): void;
-    tween<T extends Tweenable>(start: number | TimelinePoint, duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    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, ...)
-    apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer): ChainingInterface;
+    apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer | keyof typeof easers): ChainingInterface;
     at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
     private createChainingInterface;
     /**
@@ -139,7 +139,7 @@ export declare class Timeline {
     get position(): number;
 }
 export interface ChainingInterface {
-    thenTween(duration: number, apply: (v: number) => void, from?: number, to?: number, 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;
     readonly end: TimelinePoint;

package/internal/timeline.js

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Timeline = void 0;
 exports.animate = animate;
-const emitters_1 = require("./emitters");
+const point_1 = require("./point");
+const range_1 = require("./range");
 const utils_1 = require("./utils");
 const default_fps = 60;
 const EndAction = {
@@ -88,7 +89,7 @@ class Timeline {
             handlers,
             position,
         };
-        return (0, emitters_1.createEmitter)(handler => {
+        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
@@ -107,17 +108,8 @@ class Timeline {
                     this.points.splice(idx, 1);
                 }
             };
-        }, {
-            delta: t => this.point(position + t),
-            range: duration => this.range(position, duration),
-            to: target => {
-                const targetPosition = typeof target == "number"
-                    ? target
-                    : target.position;
-                return this.range(position, targetPosition - position);
-            },
-            position,
-        });
+        };
+        return new point_1.TimelinePoint(addHandler, this, position);
     }
     range(start = 0, optionalDuration) {
         const startPoint = typeof start == "number"
@@ -153,58 +145,7 @@ class Timeline {
                 }
             };
         };
-        return (0, emitters_1.createProgressEmitter)(addHandler, {
-            duration,
-            start: this.point(startPosition),
-            end: this.point(startPosition + duration),
-            bisect: (position = duration / 2) => {
-                return [
-                    this.range(startPosition, position),
-                    this.range(startPosition + position, duration - position),
-                ];
-            },
-            spread: (count) => {
-                const delta = duration / (count + 1);
-                return [
-                    ...Array(count).fill(0).map((_, idx) => this.point(idx * delta + startPosition + delta))
-                ];
-            },
-            play: (easer) => {
-                this.pause();
-                this.currentTime = startPosition;
-                return this.seek(startPosition + duration, duration, easer);
-            },
-            grow: (delta, anchor = 0) => {
-                const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
-                const leftDelta = -delta * (1 - clampedAnchor);
-                const rightDelta = delta * clampedAnchor;
-                const newStart = startPosition + leftDelta;
-                const newEnd = endPosition + rightDelta;
-                if (newEnd < newStart) {
-                    const mid = (newStart + newEnd) / 2;
-                    return this.range(mid, 0);
-                }
-                return this.range(newStart, newEnd - newStart);
-            },
-            scale: (factor, anchor = 0.5) => {
-                if (factor <= 0) {
-                    throw new RangeError('scale factor must be > 0');
-                }
-                const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
-                const oldLen = endPosition - startPosition;
-                const pivot = startPosition + oldLen * clampedAnchor;
-                const newStart = pivot - (pivot - startPosition) * factor;
-                const newEnd = pivot + (endPosition - pivot) * factor;
-                if (newEnd < newStart) {
-                    const mid = (newStart + newEnd) / 2;
-                    return this.range(mid, 0);
-                }
-                return this.range(newStart, newEnd - newStart);
-            },
-            contains: point => {
-                return point.position >= startPosition && point.position < endPosition;
-            }
-        });
+        return new range_1.TimelineRange(addHandler, this, startPosition, duration);
     }
     getWrappedPosition(n) {
         if (this.endAction.type !== EndAction.wrap)
@@ -385,7 +326,7 @@ class Timeline {
     }
     createChainingInterface(position) {
         return {
-            thenTween: (duration, apply, from = 0, to = 1, easer) => {
+            thenTween: (duration, apply, from, to, easer) => {
                 return this.tween(position, duration, apply, from, to, easer);
             },
             then: (action) => this.at(position, action),

package/internal/utils.d.ts

@@ -2,5 +2,3 @@
 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 OptionalIfKeyIn<T, U> = Omit<T, keyof U> & Partial<Pick<T, Extract<keyof T, keyof U>>>;
-export declare function prototypify<Prototype extends object, Members extends object>(proto: Prototype, members: Members): Prototype & Members;

package/internal/utils.js

@@ -1,14 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clamp = void 0;
-exports.prototypify = prototypify;
 /** @internal */
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
 exports.clamp = clamp;
-function prototypify(proto, members) {
-    const propertyDescriptor = Object.fromEntries(Object.entries(members).map(([key, value]) => [
-        key,
-        { value }
-    ]));
-    return Object.create(proto, propertyDescriptor);
-}

package/package.json

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