@xtia/timeline 1.1.2 → 1.1.3

package/README.md

@@ -40,7 +40,7 @@ timeline
 timeline
     .range(1000, 2000)
     .tween(0, 255)
-    .listen(value => microcontroller.setPWM(value))
+    .apply(value => microcontroller.setPWM(value))
 
 // make it go
 timeline.play();

package/internal/point.d.ts

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

package/internal/point.js

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

package/internal/range.d.ts

@@ -48,6 +48,7 @@ export declare class TimelineRange extends RangeProgression {
      * Progresses the Timeline across the range at 1000 units per second
      * @param easer Optional easing function
      * @returns Promise, resolved when the end is reached
+     * @deprecated Use timeline.play(range, easer?)
      */
     play(easer?: Easer | keyof typeof easers): Promise<void>;
     /**

package/internal/range.js

@@ -1,6 +1,5 @@
 import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
-import { clamp } from "./utils";
 export class TimelineRange extends RangeProgression {
     /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
     constructor(onListen, timeline, startPosition, 
@@ -28,8 +27,8 @@ export class TimelineRange extends RangeProgression {
      */
     bisect(position = this.duration / 2) {
         return [
-            this.timeline.range(position, this.startPosition),
-            this.timeline.range(position + this.startPosition, this.duration - this.startPosition),
+            this.timeline.range(this.startPosition, position),
+            this.timeline.range(position + this.startPosition, this.duration - position),
         ];
     }
     /**
@@ -65,11 +64,12 @@ export class TimelineRange extends RangeProgression {
      * Progresses the Timeline across the range at 1000 units per second
      * @param easer Optional easing function
      * @returns Promise, resolved when the end is reached
+     * @deprecated Use timeline.play(range, easer?)
      */
     play(easer) {
         this.timeline.pause();
         this.timeline.currentTime = this.startPosition;
-        return this.timeline.seek(this.startPosition + this.duration, this.duration, easer);
+        return this.timeline.seek(this.end, this.duration, easer);
     }
     /**
      * Creates a new range representing a direct expansion of this one
@@ -78,16 +78,7 @@ export class TimelineRange extends RangeProgression {
      * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
     grow(delta, anchor = 0) {
-        const clampedAnchor = clamp(anchor, 0, 1);
-        const leftDelta = -delta * (1 - clampedAnchor);
-        const rightDelta = delta * clampedAnchor;
-        const newStart = this.startPosition + leftDelta;
-        const newEnd = this.startPosition + this.duration + rightDelta;
-        if (newEnd < newStart) {
-            const mid = (newStart + newEnd) / 2;
-            return this.timeline.range(mid, 0);
-        }
-        return this.timeline.range(newStart, newEnd - newStart);
+        return this.timeline.range(this.startPosition - (delta * anchor), this.duration + delta);
     }
     /**
      * Creates a new range representing a multiplicative expansion of this one
@@ -99,16 +90,7 @@ export class TimelineRange extends RangeProgression {
         if (factor <= 0) {
             throw new RangeError('Scale factor must be > 0');
         }
-        const clampedAnchor = clamp(anchor, 0, 1);
-        const oldLen = this.endPosition - this.startPosition;
-        const pivot = this.startPosition + oldLen * clampedAnchor;
-        const newStart = pivot - (pivot - this.startPosition) * factor;
-        const newEnd = pivot + (this.endPosition - pivot) * factor;
-        if (newEnd < newStart) {
-            const mid = (newStart + newEnd) / 2;
-            return this.timeline.range(mid, 0);
-        }
-        return this.timeline.range(newStart, newEnd - newStart);
+        return this.grow((factor - 1) * this.duration, anchor);
     }
     contains(target) {
         const [targetStart, targetEnd] = target instanceof TimelinePoint

package/internal/timeline.d.ts

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

package/internal/timeline.js

@@ -179,12 +179,12 @@ export class Timeline {
             ? to
             : to.position;
         if (this.seeking) {
-            throw new Error("Can't seek while seeking");
+            throw new Error("Can't seek while a seek event is processed");
         }
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
             // ensure any awaits are resolved for the previous seek
-            this.smoothSeeker.end.seek();
+            this.smoothSeeker.seek(this.smoothSeeker.end);
             this.smoothSeeker = null;
         }
         if (duration === 0) {
@@ -193,8 +193,12 @@ export class Timeline {
         }
         const seeker = new Timeline(true);
         this.smoothSeeker = seeker;
-        seeker.range(0, duration).ease(easer).tween(this.currentTime, toPosition).apply(v => this.seekDirect(v));
-        return new Promise(r => seeker.end.apply(() => r()));
+        seeker
+            .range(0, duration)
+            .ease(easer)
+            .tween(this.currentTime, toPosition)
+            .apply(v => this.seekDirect(v));
+        return seeker.end.promise();
     }
     seekDirect(toPosition) {
         const fromPosition = this._currentTime;
@@ -252,7 +256,7 @@ export class Timeline {
                 range.handlers.slice().forEach(h => h(progress));
             }
         });
-        this.progressionHandlers.slice().forEach(h => h(fromTime / this._endPosition));
+        this.progressionHandlers.slice().forEach(h => h(toTime / this._endPosition));
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -263,9 +267,18 @@ export class Timeline {
             ? sortTweens
             : sortReverse);
     }
-    play(fps = default_fps) {
+    play(arg = default_fps, easer) {
         if (this.interval !== null)
             this.pause();
+        if (this.smoothSeeker) {
+            this.smoothSeeker.pause();
+            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker = null;
+        }
+        if (arg instanceof TimelineRange) {
+            this.seek(arg.start);
+            return this.seek(arg.end, arg.duration / this.timeScale, easer);
+        }
         let previousTime = Date.now();
         this.interval = setInterval(() => {
             const newTime = Date.now();
@@ -303,8 +316,14 @@ export class Timeline {
                 return;
             }
             this.currentTime += delta;
-        }, 1000 / fps);
+        }, 1000 / arg);
     }
+    /**
+     * Stops normal progression instigated by play()
+     *
+     * Does not affect ongoing smooth-seek operations or play(range)
+     *
+     */
     pause() {
         if (this.interval === null)
             return;

package/package.json

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