@xtia/timeline 1.1.5 → 1.1.7

package/internal/emitters.d.ts

@@ -6,15 +6,7 @@ export type UnsubscribeFunc = () => void;
 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>;
+    protected createTransformListen<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
      * @param handler
@@ -58,7 +50,7 @@ export declare class 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>): this;
+    tap(cb: Handler<T>): Emitter<T>;
     /**
      * Immediately passes this emitter to a callback and returns this emitter
      *
@@ -79,7 +71,6 @@ export declare class Emitter<T> {
     fork(cb: (branch: this) => void): this;
 }
 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
      *
@@ -91,7 +82,7 @@ export declare class RangeProgression extends Emitter<number> {
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, progression: number): this` method
      *
      * @param from Value to interpolate from
      * @param to Value to interpolate to
@@ -101,7 +92,7 @@ export declare class RangeProgression extends Emitter<number> {
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, progression: number): this` method
      *
      * #### String interpolation
      * * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
@@ -122,7 +113,7 @@ export declare class RangeProgression extends Emitter<number> {
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, progression: number): this` method
      *
      * @param from Value to interpolate from
      * @param to Value to interpolate to
@@ -190,12 +181,13 @@ export declare class RangeProgression extends Emitter<number> {
      * @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: (value: number) => boolean): RangeProgression;
+    filter(check: (progress: number) => boolean): RangeProgression;
     /**
      * 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(): RangeProgression;
+    private _dedupe?;
     /**
      * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
      *
@@ -214,6 +206,18 @@ export declare class RangeProgression extends Emitter<number> {
      * @returns Listenable: emits offset values
      */
     offset(delta: number): RangeProgression;
+    /**
+     * 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: Handler<number>): RangeProgression;
 }
 export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLast?: () => void): {
     listen: (fn: (v: T) => void) => UnsubscribeFunc;

package/internal/emitters.js

@@ -5,16 +5,15 @@ 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}
-     */
-    redirect(listen) {
-        return new Emitter(listen);
+    createTransformListen(handler) {
+        let parentUnsubscribe = null;
+        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+            handler(value, emit);
+        }), () => {
+            parentUnsubscribe();
+            parentUnsubscribe = null;
+        });
+        return listen;
     }
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
@@ -22,9 +21,7 @@ export class Emitter {
      * @returns A function to deregister the handler
      */
     listen(handler) {
-        return this.onListen((value) => {
-            handler(value);
-        });
+        return this.onListen(handler);
     }
     /**
      * Registers a function to receive emitted values
@@ -32,9 +29,7 @@ export class Emitter {
      * @returns A function to deregister the handler
      */
     apply(handler) {
-        return this.onListen((value) => {
-            handler(value);
-        });
+        return this.onListen(handler);
     }
     /**
      * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
@@ -42,9 +37,8 @@ export class Emitter {
      * @returns Listenable: emits transformed values
      */
     map(mapFunc) {
-        return new Emitter(handler => this.onListen((value) => {
-            handler(mapFunc(value));
-        }));
+        const listen = this.createTransformListen((value, emit) => emit(mapFunc(value)));
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that selectively forwards emissions along the chain
@@ -52,10 +46,8 @@ export class Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        return new Emitter(handler => this.onListen((value) => {
-            if (check(value))
-                handler(value);
-        }));
+        const listen = this.createTransformListen((value, emit) => check(value) && emit(value));
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
@@ -66,17 +58,15 @@ export class Emitter {
      */
     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);
+        const listen = this.createTransformListen((value, emit) => {
+            if (!previous || (compare
+                ? !compare(previous.value, value)
+                : (previous.value !== value))) {
+                emit(value);
+                previous = { value };
+            }
         });
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
@@ -90,15 +80,11 @@ export class Emitter {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb) {
-        let parentUnsubscribe = null;
-        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+        const listen = this.createTransformListen((value, emit) => {
             cb(value);
             emit(value);
-        }), () => {
-            parentUnsubscribe();
-            parentUnsubscribe = null;
         });
-        return this.redirect(listen);
+        return new Emitter(listen);
     }
     /**
      * Immediately passes this emitter to a callback and returns this emitter
@@ -123,22 +109,19 @@ export class Emitter {
     }
 }
 export class RangeProgression extends Emitter {
-    redirect(listen) {
-        return new RangeProgression(listen);
-    }
     ease(easer) {
-        if (!easer)
-            return this;
         const easerFunc = typeof easer == "string"
             ? easers[easer]
             : easer;
-        return new RangeProgression(easer ? (handler => this.onListen((progress) => {
-            handler(easerFunc(progress));
-        })) : h => this.onListen(h));
+        const listen = easerFunc
+            ? this.createTransformListen((value, emit) => emit(easerFunc(value)))
+            : this.onListen;
+        return new RangeProgression(listen);
     }
     tween(from, to) {
         const tween = createTween(from, to);
-        return new Emitter(handler => this.onListen(progress => handler(tween(progress))));
+        const listen = this.createTransformListen((progress, emit) => emit(tween(progress)));
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that takes a value from an array according to progression
@@ -154,11 +137,12 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits the sampled values
      */
     sample(source) {
-        return new Emitter(handler => this.onListen(progress => {
-            const clampedProgress = clamp(progress);
+        const listen = this.createTransformListen((value, emit) => {
+            const clampedProgress = clamp(value);
             const index = Math.floor(clampedProgress * (source.length - 1));
-            handler(source[index]);
-        }));
+            emit(source[index]);
+        });
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
@@ -183,9 +167,8 @@ export class RangeProgression extends Emitter {
      * @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);
-        }));
+        const listen = this.createTransformListen((value, emit) => emit(value >= threshold ? 1 : 0));
+        return new RangeProgression(listen);
     }
     /**
      * Creates a chainable progress emitter that clamps incoming values
@@ -215,11 +198,13 @@ export class RangeProgression extends Emitter {
      * @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);
-        }));
+        if (count <= 0)
+            throw new RangeError("Repeat count must be greater than 0");
+        const listen = this.createTransformListen((value, emit) => {
+            const out = (value * count) % 1;
+            emit(out);
+        });
+        return new RangeProgression(listen);
     }
     /**
      * Creates a chainable progress emitter that selectively forwards emissions along the chain
@@ -227,25 +212,28 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        return new RangeProgression(handler => this.onListen((value) => {
+        const listen = this.createTransformListen((value, emit) => {
             if (check(value))
-                handler(value);
-        }));
+                emit(value);
+        });
+        return new RangeProgression(listen);
     }
     /**
      * 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);
+        if (!this._dedupe) {
+            let previous = null;
+            const listen = this.createTransformListen((value, emit) => {
+                if (previous !== value) {
+                    emit(value);
                     previous = value;
                 }
             });
-        });
+            this._dedupe = new RangeProgression(listen);
+        }
+        return this._dedupe;
     }
     /**
      * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
@@ -267,11 +255,29 @@ export class RangeProgression extends Emitter {
     offset(delta) {
         return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
     }
+    /**
+     * 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 listen = this.createTransformListen((value, emit) => {
+            cb(value);
+            emit(value);
+        });
+        return new RangeProgression(listen);
+    }
 }
 export function createListenable(onAddFirst, onRemoveLast) {
     const handlers = [];
     const addListener = (fn) => {
-        const unique = (v) => fn(v);
+        const unique = { fn };
         handlers.push(unique);
         if (onAddFirst && handlers.length == 1)
             onAddFirst();
@@ -286,6 +292,6 @@ export function createListenable(onAddFirst, onRemoveLast) {
     };
     return {
         listen: addListener,
-        emit: (value) => handlers.forEach(h => h(value)),
+        emit: (value) => handlers.forEach(h => h.fn(value)),
     };
 }

package/internal/point.d.ts

@@ -17,7 +17,6 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * 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
@@ -51,11 +50,13 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * @returns Listenable: emits forward-seeking point events
      */
     forwardOnly(): Emitter<PointEvent>;
+    private _forwardOnly?;
     /**
      * Creates an emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
     reverseOnly(): Emitter<PointEvent>;
+    private _reverseOnly?;
     filter(check: (event: PointEvent) => boolean): Emitter<PointEvent>;
     /**
      * Creates an emitter that forwards events emitted by seeks of a specific direction
@@ -96,4 +97,5 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * @returns Listenable: emits non-repeating point events
      */
     dedupe(): Emitter<PointEvent>;
+    private _dedupe?;
 }

package/internal/point.js

@@ -10,9 +10,6 @@ export class TimelinePoint extends Emitter {
         this.timeline = timeline;
         this.position = 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
      * @param duration
@@ -48,25 +45,30 @@ export class TimelinePoint extends Emitter {
      * @returns Listenable: emits forward-seeking point events
      */
     forwardOnly() {
-        return this.filter(1);
+        if (!this._forwardOnly)
+            this._forwardOnly = this.filter(1);
+        return this._forwardOnly;
     }
     /**
      * Creates an emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
     reverseOnly() {
-        return this.filter(-1);
+        if (!this._reverseOnly)
+            this._reverseOnly = this.filter(-1);
+        return this._reverseOnly;
     }
     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);
-            }));
+        const listen = this.createTransformListen(typeof arg == "number"
+            ? (value, emit) => {
+                if (value.direction === arg)
+                    emit(value);
+            }
+            : (value, emit) => {
+                if (arg(value))
+                    emit(value);
+            });
+        return new Emitter(listen);
     }
     /**
      * Creates a Promise that will be resolved when the Timeline first seeks to/past this point
@@ -112,12 +114,16 @@ export class TimelinePoint extends Emitter {
      * @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;
-            }
-        }));
+        if (!this._dedupe) {
+            let previous = 0;
+            const listen = this.createTransformListen((value, emit) => {
+                if (value.direction !== previous) {
+                    previous = value.direction;
+                    emit(value);
+                }
+            });
+            this._dedupe = new Emitter(listen);
+        }
+        return this._dedupe;
     }
 }

package/internal/range.d.ts

@@ -18,7 +18,6 @@ export declare class TimelineRange extends RangeProgression {
     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
@@ -33,6 +32,18 @@ export declare class TimelineRange extends RangeProgression {
      * @returns Array(count) of points
      */
     spread(count: number): TimelinePoint[];
+    /**
+     * Creates a series of evenly-spread points across the range, optionally including the range's start and end
+     * @param count Number of Points to return, including head and tail
+     * @param includeEnds
+     */
+    spread(count: number, includeEnds: boolean): TimelinePoint[];
+    /**
+     * Creates a series of evenly-spread points across the range, optionally including the range's start and end
+     * @param count Number of Points to return, including head and tail
+     * @param includeEnds
+     */
+    spread(count: number, includeStart: boolean, includeEnd: boolean): TimelinePoint[];
     /**
      * Creates the specified number of ranges, each of `(parent.duration / count)` duration, spread
      * evenly over this range

package/internal/range.js

@@ -15,9 +15,6 @@ export class TimelineRange extends RangeProgression {
         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
      * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
@@ -34,15 +31,26 @@ export class TimelineRange extends RangeProgression {
             this.timeline.range(position + this.startPosition, this.duration - position),
         ];
     }
-    /**
-     * 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) {
+    spread(count, includeStart = false, includeEnd = includeStart) {
+        let start = [];
+        let end = [];
+        if (includeStart) {
+            start = [this.start];
+            count--;
+        }
+        if (includeEnd) {
+            end = [this.end];
+            count--;
+        }
+        if (count == 0)
+            return [...start, ...end];
+        if (count < 0)
+            throw new Error("Invalid spread count");
         const delta = this.duration / (count + 1);
         return [
-            ...Array(count).fill(0).map((_, idx) => this.timeline.point(idx * delta + this.startPosition + delta))
+            ...start,
+            ...Array(count).fill(0).map((_, idx) => this.timeline.point(idx * delta + this.startPosition + delta)),
+            ...end
         ];
     }
     /**

package/internal/timeline.d.ts

@@ -27,9 +27,18 @@ export declare class Timeline {
      * A value of 2 would double progression speed while .25 would slow it to a quarter
      */
     timeScale: number;
+    /**
+     * The current position of this Timeline's 'play head'
+     */
     get currentTime(): number;
     set currentTime(v: number);
+    /**
+     * Returns true if this Timeline is currently progressing via `play()`, otherwise false
+     */
     get isPlaying(): boolean;
+    /**
+     * Returns a fixed point at the current end of the Timeline
+     */
     get end(): TimelinePoint;
     private _currentTime;
     private _endPosition;
@@ -40,6 +49,9 @@ export declare class Timeline {
     private currentSortDirection;
     private smoothSeeker;
     private seeking;
+    /**
+     * A fixed point representing the start of this Timeline (position 0)
+     */
     readonly start: TimelinePoint;
     private _frameEvents;
     /**
@@ -48,8 +60,8 @@ export declare class Timeline {
     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
+     * Listenable: emits a progression value (0..1), representing progression through the entire Timeline,
+     * when the Timeline's internal position changes, and when the Timeline's total duration is extended
      */
     get progression(): RangeProgression;
     constructor();
@@ -102,10 +114,9 @@ export declare class Timeline {
      */
     range(start: number | TimelinePoint, duration: number): TimelineRange;
     /**
-     * Creates an observable range from position 0 to the Timeline's **current** final position
+     * Defines a range from position 0 to the Timeline's **current** final position
      */
     range(): TimelineRange;
-    private getWrappedPosition;
     /**
      * Seeks the Timeline to a specified position, triggering in order any point and range subscriptions between its current and new positions
      * @param toPosition
@@ -123,6 +134,7 @@ export declare class Timeline {
     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 seekWrapped;
     private seekPoints;
     private seekRanges;
     private sortEntries;
@@ -154,9 +166,29 @@ export declare class Timeline {
      * @deprecated Use timeline.position += n
      */
     step(delta: number): void;
+    /**
+     * Adds a tweening range to the Timeline
+     *
+     * **Legacy API**
+     * @param start Range's start position
+     * @param duration Tween's duration
+     * @param apply Function to apply interpolated values
+     * @param from Value at start of range
+     * @param to Value at end of range
+     * @param easer Optional easing function
+     */
     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 | keyof typeof easers): ChainingInterface;
+    /**
+     * Adds an event at a specific position
+     *
+     * **Legacy API**
+     * @param position Position of the event
+     * @param action Handler for forward seeking
+     * @param reverse Handler for backward seeking
+     * @returns A tween/event chaining interface
+     */
     at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
     private createChainingInterface;
     /**

package/internal/timeline.js

@@ -16,13 +16,22 @@ export function animate(durationMs) {
         : durationMs.asMilliseconds);
 }
 export class Timeline {
+    /**
+     * The current position of this Timeline's 'play head'
+     */
     get currentTime() { return this._currentTime; }
     set currentTime(v) {
         this.seek(v);
     }
+    /**
+     * Returns true if this Timeline is currently progressing via `play()`, otherwise false
+     */
     get isPlaying() {
         return this.interval !== null;
     }
+    /**
+     * Returns a fixed point at the current end of the Timeline
+     */
     get end() {
         return this.point(this._endPosition);
     }
@@ -40,8 +49,8 @@ export class Timeline {
         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
+     * Listenable: emits a progression value (0..1), representing progression through the entire Timeline,
+     * when the Timeline's internal position changes, and when the Timeline's total duration is extended
      */
     get progression() {
         if (this._progression === null) {
@@ -68,6 +77,9 @@ export class Timeline {
         this.currentSortDirection = 0;
         this.smoothSeeker = null;
         this.seeking = false;
+        /**
+         * A fixed point representing the start of this Timeline (position 0)
+         */
         this.start = this.point(0);
         this._frameEvents = null;
         this._progression = null;
@@ -161,22 +173,6 @@ export class Timeline {
         const range = new TimelineRange(addHandler, this, startPoint, endPoint);
         return range;
     }
-    getWrappedPosition(n) {
-        if (this.endAction.type !== EndAction.wrap)
-            return n;
-        const wrapAt = this.endAction.at?.position ?? 0;
-        if (wrapAt == 0)
-            return n % this._endPosition;
-        if (n <= this._endPosition)
-            return n;
-        const loopStart = wrapAt;
-        const segment = this._endPosition - loopStart;
-        if (segment <= 0)
-            return Math.min(n, this._endPosition);
-        const overflow = n - this._endPosition;
-        const remainder = overflow % segment;
-        return loopStart + remainder;
-    }
     seek(to, duration, easer) {
         const durationMs = typeof duration == "object"
             ? duration.asMilliseconds
@@ -216,31 +212,65 @@ export class Timeline {
         const fromPosition = this._currentTime;
         if (toPosition === fromPosition)
             return;
-        const loopingTo = this.getWrappedPosition(toPosition);
-        const loopingFrom = this.getWrappedPosition(fromPosition);
-        let virtualFrom = loopingFrom;
-        let virtualTo = loopingTo;
         const direction = toPosition > fromPosition ? 1 : -1;
         if (direction !== this.currentSortDirection)
             this.sortEntries(direction);
-        if (direction === 1 && loopingTo < loopingFrom) {
-            virtualFrom = loopingFrom - this._endPosition;
-        }
-        else if (direction === -1 && loopingTo > loopingFrom) {
-            virtualFrom = loopingFrom + this._endPosition;
-        }
         this.seeking = true;
-        this._currentTime = virtualFrom;
         try {
-            this.seekPoints(virtualTo);
-            this.seekRanges(virtualTo);
+            // use wrapping logic?
+            if (this.endAction.type === EndAction.wrap && (fromPosition > this._endPosition || toPosition > this._endPosition)) {
+                this.seekWrapped(toPosition);
+            }
+            else {
+                this.seekPoints(toPosition);
+                this.seekRanges(toPosition);
+            }
         }
         catch (e) {
             this.pause();
             throw e;
         }
+        finally {
+            this.seeking = false;
+        }
+        this._currentTime = toPosition;
+    }
+    seekWrapped(toPosition) {
+        const fromPosition = this._currentTime;
+        const timelineEnd = this._endPosition;
+        const wrapAt = "at" in this.endAction ? this.endAction.at.position : 0;
+        const loopLen = timelineEnd - wrapAt;
+        const getWrappedPosition = (pos) => ((pos - wrapAt) % loopLen + loopLen) % loopLen + wrapAt;
+        const realDelta = toPosition - fromPosition;
+        const direction = realDelta >= 0 ? 1 : -1;
+        let remaining = Math.abs(realDelta);
+        let virtualFrom = getWrappedPosition(fromPosition);
+        while (remaining > 0) {
+            let virtualTo;
+            if (direction > 0) {
+                const wrapSize = timelineEnd - virtualFrom;
+                virtualTo = remaining <= wrapSize
+                    ? virtualFrom + remaining
+                    : timelineEnd;
+            }
+            else {
+                const wrapSize = virtualFrom - wrapAt;
+                virtualTo = remaining <= wrapSize
+                    ? virtualFrom - remaining
+                    : wrapAt;
+            }
+            this._currentTime = virtualFrom;
+            this.seekPoints(virtualTo);
+            remaining -= Math.abs(virtualTo - virtualFrom);
+            if (remaining > 0) {
+                virtualFrom = direction > 0 ? wrapAt : timelineEnd;
+            }
+            else {
+                virtualFrom = virtualTo;
+            }
+        }
+        this.seekRanges(getWrappedPosition(toPosition));
         this._currentTime = toPosition;
-        this.seeking = false;
     }
     seekPoints(to) {
         const from = this._currentTime;
@@ -357,6 +387,15 @@ export class Timeline {
         this.range(startPosition, duration).ease(easer).tween(from, to).apply(apply);
         return this.createChainingInterface(startPosition + duration);
     }
+    /**
+     * Adds an event at a specific position
+     *
+     * **Legacy API**
+     * @param position Position of the event
+     * @param action Handler for forward seeking
+     * @param reverse Handler for backward seeking
+     * @returns A tween/event chaining interface
+     */
     at(position, action, reverse) {
         const point = typeof position == "number" ? this.point(position) : position;
         if (reverse === true)

package/package.json

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