@xtia/timeline 1.1.4 → 1.1.6

package/README.md

@@ -464,6 +464,26 @@ timeline
 
 Returns a [`ChainingInterface`](#chaininginterface-interface) representing the point at which the tween ends.
 
+##### `apply(handler)`
+
+Registers a handler to be invoked on every seek, after points and ranges are applied.
+
+This is useful for systems that use Timeline's point and range emissions to manipulate state that is to be applied *at once* to another system.
+
+```ts
+// don't wastefully render the scene for every entity update
+timeline
+    .range(0, 1000)
+    .tween(10, 30)
+    .apply(v => scene.hero.x = v);
+timeline
+    .range(500, 1000)
+    .tween(15, 50)
+    .apply(v => scene.monster.x = v);
+// render when all updates for a frame are done:
+timeline.apply(() => renderScene(scene));
+```
+
 ##### `tween<T>(start, end, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
 
 As above, but if the second argument is a [`TimelinePoint`](#timelinepoint-class), it will specify when on the Timeline the tween will *end*.

package/internal/emitters.d.ts

@@ -68,11 +68,10 @@ export declare class Emitter<T> {
      * ```ts
      * range
      *   .tween("0%", "100%")
-     *   .fork(branch => {
-     *     branch
+     *   .fork(branch => branch
      *       .map(s => `Loading: ${s}`)
      *       .apply(s => document.title = s)
-     *   })
+     *   )
      *   .apply(v => progressBar.style.width = v);
      * ```
      * @param cb
@@ -216,4 +215,8 @@ export declare class RangeProgression extends Emitter<number> {
      */
     offset(delta: number): RangeProgression;
 }
+export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLast?: () => void): {
+    listen: (fn: (v: T) => void) => UnsubscribeFunc;
+    emit: (value: T) => void;
+};
 export {};

package/internal/emitters.js

@@ -90,26 +90,15 @@ export class Emitter {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb) {
-        const listeners = [];
         let parentUnsubscribe = null;
-        const tappedListen = (handler) => {
-            listeners.push(handler);
-            if (listeners.length === 1) {
-                parentUnsubscribe = this.onListen(value => {
-                    cb(value);
-                    listeners.slice().forEach(fn => fn(value));
-                });
-            }
-            return () => {
-                const idx = listeners.indexOf(handler);
-                listeners.splice(idx, 1);
-                if (listeners.length === 0 && parentUnsubscribe) {
-                    parentUnsubscribe();
-                    parentUnsubscribe = null;
-                }
-            };
-        };
-        return this.redirect(tappedListen);
+        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+            cb(value);
+            emit(value);
+        }), () => {
+            parentUnsubscribe();
+            parentUnsubscribe = null;
+        });
+        return this.redirect(listen);
     }
     /**
      * Immediately passes this emitter to a callback and returns this emitter
@@ -120,11 +109,10 @@ export class Emitter {
      * ```ts
      * range
      *   .tween("0%", "100%")
-     *   .fork(branch => {
-     *     branch
+     *   .fork(branch => branch
      *       .map(s => `Loading: ${s}`)
      *       .apply(s => document.title = s)
-     *   })
+     *   )
      *   .apply(v => progressBar.style.width = v);
      * ```
      * @param cb
@@ -280,3 +268,24 @@ export class RangeProgression extends Emitter {
         return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
     }
 }
+export function createListenable(onAddFirst, onRemoveLast) {
+    const handlers = [];
+    const addListener = (fn) => {
+        const unique = (v) => fn(v);
+        handlers.push(unique);
+        if (onAddFirst && handlers.length == 1)
+            onAddFirst();
+        return () => {
+            const idx = handlers.indexOf(unique);
+            if (idx === -1)
+                throw new Error("Handler already unsubscribed");
+            handlers.splice(idx, 1);
+            if (onRemoveLast && handlers.length == 0)
+                onRemoveLast();
+        };
+    };
+    return {
+        listen: addListener,
+        emit: (value) => handlers.forEach(h => h(value)),
+    };
+}

package/internal/range.d.ts

@@ -4,18 +4,20 @@ import { TimelinePoint } from "./point";
 import { Timeline } from "./timeline";
 export declare class TimelineRange extends RangeProgression {
     private timeline;
-    private startPosition;
-    /** The duration of this range */
-    readonly duration: number;
-    private endPosition;
     /** The point on the Timeline at which this range begins */
     readonly start: TimelinePoint;
     /** The point on the Timeline at which this range ends */
     readonly end: TimelinePoint;
-    /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
-    constructor(onListen: ListenFunc<number>, timeline: Timeline, startPosition: number, 
+    private startPosition;
+    private endPosition;
     /** The duration of this range */
-    duration: number);
+    readonly duration: number;
+    /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
+    constructor(onListen: ListenFunc<number>, timeline: Timeline, 
+    /** The point on the Timeline at which this range begins */
+    start: TimelinePoint, 
+    /** The point on the Timeline at which this range ends */
+    end: TimelinePoint);
     protected redirect(listen: ListenFunc<number>): TimelineRange;
     /**
      * Creates two ranges by seperating one at a given point

package/internal/range.js

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

package/internal/timeline.d.ts

@@ -1,5 +1,5 @@
 import { Easer, easers } from "./easing";
-import { RangeProgression } from "./emitters";
+import { RangeProgression, UnsubscribeFunc } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { Tweenable } from "./tween";
@@ -41,13 +41,15 @@ export declare class Timeline {
     private smoothSeeker;
     private seeking;
     readonly start: TimelinePoint;
-    private progressionHandlers;
+    private _frameEvents;
+    /**
+     * Registers a handler to be invoked on every seek, after points and ranges are applied
+     */
+    apply(handler: () => void): UnsubscribeFunc;
     private _progression;
     /**
-     * Listenable: emits a progression value (0..1) when the Timeline's internal
-     * position changes, and when the Timeline's total duration is extended
-     *
-     * **Experimental**
+     * 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();
@@ -100,10 +102,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
@@ -121,6 +122,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;

package/internal/timeline.js

@@ -1,4 +1,4 @@
-import { RangeProgression } from "./emitters";
+import { createListenable, RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { clamp } from "./utils";
@@ -27,15 +27,31 @@ export class Timeline {
         return this.point(this._endPosition);
     }
     /**
-     * Listenable: emits a progression value (0..1) when the Timeline's internal
-     * position changes, and when the Timeline's total duration is extended
-     *
-     * **Experimental**
+     * Registers a handler to be invoked on every seek, after points and ranges are applied
+     */
+    apply(handler) {
+        if (this._frameEvents === null) {
+            const { emit, listen } = createListenable();
+            this._frameEvents = {
+                listen,
+                emit,
+            };
+        }
+        return this._frameEvents.listen(handler);
+    }
+    /**
+     * Listenable: emits a progression value (0..1), 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)
-            this._progression = new TimelineProgressionEmitter(this.progressionHandlers);
-        return this._progression;
+        if (this._progression === null) {
+            const { emit, listen } = createListenable();
+            this._progression = {
+                emitter: new TimelineProgressionEmitter(listen),
+                emit,
+            };
+        }
+        return this._progression.emitter;
     }
     constructor(autoplay = false, endAction = "pause") {
         /**
@@ -53,7 +69,7 @@ export class Timeline {
         this.smoothSeeker = null;
         this.seeking = false;
         this.start = this.point(0);
-        this.progressionHandlers = [];
+        this._frameEvents = null;
         this._progression = null;
         if (endAction == "loop")
             endAction = "restart";
@@ -91,32 +107,25 @@ export class Timeline {
     point(position) {
         if (position > this._endPosition) {
             this._endPosition = position;
-            this.progressionHandlers.slice().forEach(h => h(this._currentTime / position));
+            this._progression?.emit(this._currentTime / position);
         }
-        const handlers = [];
-        const data = {
-            handlers,
-            position,
-        };
+        const { emit, listen } = createListenable(() => this.points.push(data), () => {
+            const idx = this.points.indexOf(data);
+            this.points.splice(idx, 1);
+        });
         const addHandler = (handler) => {
             if (this.seeking)
                 throw new Error("Can't add a listener while seeking");
-            // we're adding and removing points and ranges to the internal registry according to whether any subscriptions are active, to allow obsolete points and ranges to be garbage-collected
-            if (handlers.length == 0) {
-                this.points.push(data);
-                this.currentSortDirection = 0;
+            if (position == this._currentTime) {
+                emit({
+                    direction: 1
+                });
             }
-            handlers.push(handler);
-            return () => {
-                const idx = handlers.indexOf(handler);
-                if (idx === -1)
-                    throw new Error("Internal error: attempting to remove a non-present handler");
-                handlers.splice(idx, 1);
-                if (handlers.length == 0) {
-                    const idx = this.points.indexOf(data);
-                    this.points.splice(idx, 1);
-                }
-            };
+            return listen(handler);
+        };
+        const data = {
+            emit,
+            position,
         };
         return new TimelinePoint(addHandler, this, position);
     }
@@ -126,62 +135,36 @@ export class Timeline {
             : start;
         const startPosition = startPoint.position;
         const duration = optionalDuration ?? this._endPosition - startPosition;
-        // const endPosition = startPosition + duration;
-        //if (endPosition > this._endPosition) this._endPosition = endPosition;
-        // ^ leave this to range's point() calls
-        const handlers = [];
+        const endPoint = this.point(startPosition + duration);
+        const { emit, listen } = createListenable(() => this.ranges.push(rangeData), () => {
+            const idx = this.ranges.indexOf(rangeData);
+            this.ranges.splice(idx, 1);
+        });
         const rangeData = {
             position: startPosition,
             duration,
-            handlers,
+            emit,
         };
-        const addHandler = (handler) => {
-            if (this.seeking)
-                throw new Error("Can't add a listener while seeking");
-            if (handlers.length == 0) {
-                this.ranges.push(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);
+        const addHandler = duration == 0
+            ? () => {
+                throw new Error("Zero-duration ranges may not be listened");
             }
-            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(rangeData);
-                    this.ranges.splice(idx, 1);
+            : (handler) => {
+                if (this.seeking)
+                    throw new Error("Can't add a listener while seeking");
+                if (range.contains(this._currentTime)) {
+                    let progress = clamp((this._currentTime - startPosition) / duration, 0, 1);
+                    handler(progress);
                 }
+                return listen(handler);
             };
-        };
-        const range = new TimelineRange(addHandler, this, startPosition, duration);
+        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 = 0, easer) {
-        const durationMs = typeof duration == "number"
-            ? duration
-            : duration.asMilliseconds;
+    seek(to, duration, easer) {
+        const durationMs = typeof duration == "object"
+            ? duration.asMilliseconds
+            : duration;
         const toPosition = typeof to == "number"
             ? to
             : to.position;
@@ -192,21 +175,24 @@ export class Timeline {
             this.smoothSeeker.pause();
             // ensure any awaits are resolved for the interrupted seek
             const interruptPosition = this._currentTime;
-            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker.seekDirect(this.smoothSeeker.end.position);
             this.smoothSeeker = null;
             // and jump back to where we were interrupted
-            this.seek(interruptPosition);
+            this.seekDirect(interruptPosition);
         }
-        if (durationMs === 0) {
+        if (!durationMs) {
+            const fromTime = this._currentTime;
             this.seekDirect(toPosition);
-            return Promise.resolve();
+            this._frameEvents?.emit();
+            // only add Promise overhead if duration is explicitly 0
+            return durationMs === 0 ? Promise.resolve() : undefined;
         }
         const seeker = new Timeline(true);
         this.smoothSeeker = seeker;
         seeker
             .range(0, durationMs)
             .ease(easer)
-            .tween(this.currentTime, toPosition)
+            .tween(this._currentTime, toPosition)
             .apply(v => this.seekDirect(v));
         return seeker.end.promise();
     }
@@ -214,31 +200,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;
@@ -252,7 +272,7 @@ export class Timeline {
         pointsBetween.slice().forEach(p => {
             this.seekRanges(p.position);
             this._currentTime = p.position;
-            p.handlers.slice().forEach(h => h(eventData));
+            p.emit(eventData);
         });
     }
     seekRanges(to) {
@@ -265,10 +285,10 @@ export class Timeline {
             const overlaps = fromTime <= rangeEnd && toTime >= range.position;
             if (overlaps) {
                 let progress = clamp((to - range.position) / range.duration, 0, 1);
-                range.handlers.slice().forEach(h => h(progress));
+                range.emit(progress);
             }
         });
-        this.progressionHandlers.slice().forEach(h => h(toTime / this._endPosition));
+        this._progression?.emit(toTime / this._endPosition);
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -391,15 +411,8 @@ export class Timeline {
     }
 }
 class TimelineProgressionEmitter extends RangeProgression {
-    constructor(handlers) {
-        super((handler) => {
-            const unique = (n) => handler(n);
-            handlers.push(unique);
-            return () => {
-                const idx = handlers.indexOf(unique);
-                handlers.splice(idx, 1);
-            };
-        });
+    constructor(listen) {
+        super(listen);
     }
 }
 const sortEvents = (a, b) => {

package/internal/tween.js

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

package/package.json

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