@xtia/timeline 1.1.11 → 1.1.13

package/README.md

@@ -145,12 +145,21 @@ Points emit `PointEvent` objects when their position is reached or passed.
 ```ts
 twoSecondsIn.apply(event => {
     // event.direction (-1 | 1) tells us the direction of the seek that
-    // triggered the point. This allows for reversible point events
-    document.body.classList.toggle("someClass", event.direction > 0);
+    // triggered the point. This allows for reversible effects:
+    element.classList.toggle("someClass", event.direction > 0);
 });
 ```
 
-*Note*, point events will be triggered in order, depending on the direction of the seek that passes over them.
+*Note*, point events will be triggered in order, depending on the direction of the seek that passes over them. To ensure consistent reversible behaviour, a point is triggered with `direction = 1` when a forward seek *passes or lands on* it, and with `direction = -1` when a backward seek *passes or departs from* it.
+
+Directionality can also be leveraged with `point.applyDirectional()`:
+
+```ts
+twoSecondsIn.applyDirectional(
+    parent.append(element), // do
+    element.remove() // undo
+);
+```
 
 We can also create ranges from points:
 
@@ -165,7 +174,7 @@ timeline
     .tween(/*...*/);
 ```
 
-*Note*, points and ranges without active listeners are not stored, so will be garbage-collected if unreferenced.
+*Note*, points and ranges are transient interfaces for adding behaviour to their Timelines; they can be garbage-collected if unreferenced even while their listeners persist.
 
 ## More on tweening
 

package/internal/emitters.d.ts

@@ -6,7 +6,7 @@ export type UnsubscribeFunc = () => void;
 export declare class Emitter<T> {
     protected onListen: ListenFunc<T>;
     protected constructor(onListen: ListenFunc<T>);
-    protected createTransformListen<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
+    protected transform<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

package/internal/emitters.js

@@ -5,9 +5,10 @@ export class Emitter {
     constructor(onListen) {
         this.onListen = onListen;
     }
-    createTransformListen(handler) {
+    transform(handler) {
         let parentUnsubscribe = null;
-        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+        const parentListen = this.onListen;
+        const { emit, listen } = createListenable(() => parentUnsubscribe = parentListen(value => {
             handler(value, emit);
         }), () => {
             parentUnsubscribe();
@@ -37,7 +38,7 @@ export class Emitter {
      * @returns Listenable: emits transformed values
      */
     map(mapFunc) {
-        const listen = this.createTransformListen((value, emit) => emit(mapFunc(value)));
+        const listen = this.transform((value, emit) => emit(mapFunc(value)));
         return new Emitter(listen);
     }
     /**
@@ -46,7 +47,7 @@ export class Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        const listen = this.createTransformListen((value, emit) => check(value) && emit(value));
+        const listen = this.transform((value, emit) => check(value) && emit(value));
         return new Emitter(listen);
     }
     /**
@@ -58,7 +59,7 @@ export class Emitter {
      */
     dedupe(compare) {
         let previous = null;
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             if (!previous || (compare
                 ? !compare(previous.value, value)
                 : (previous.value !== value))) {
@@ -80,7 +81,7 @@ export class 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) => {
+        const listen = this.transform((value, emit) => {
             cb(value);
             emit(value);
         });
@@ -114,13 +115,13 @@ export class RangeProgression extends Emitter {
             ? easers[easer]
             : easer;
         const listen = easerFunc
-            ? this.createTransformListen((value, emit) => emit(easerFunc(value)))
+            ? this.transform((value, emit) => emit(easerFunc(value)))
             : this.onListen;
         return new RangeProgression(listen);
     }
     tween(from, to) {
         const tween = createTween(from, to);
-        const listen = this.createTransformListen((progress, emit) => emit(tween(progress)));
+        const listen = this.transform((progress, emit) => emit(tween(progress)));
         return new Emitter(listen);
     }
     /**
@@ -137,7 +138,7 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits the sampled values
      */
     sample(source) {
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             const clampedProgress = clamp(value);
             const index = Math.floor(clampedProgress * (source.length - 1));
             emit(source[index]);
@@ -167,7 +168,7 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
      */
     threshold(threshold) {
-        const listen = this.createTransformListen((value, emit) => emit(value >= threshold ? 1 : 0));
+        const listen = this.transform((value, emit) => emit(value >= threshold ? 1 : 0));
         return new RangeProgression(listen);
     }
     /**
@@ -200,7 +201,7 @@ export class RangeProgression extends Emitter {
     repeat(count) {
         if (count <= 0)
             throw new RangeError("Repeat count must be greater than 0");
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             const out = (value * count) % 1;
             emit(out);
         });
@@ -212,7 +213,7 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        const listen = this.createTransformListen((value, emit) => {
+        const listen = this.transform((value, emit) => {
             if (check(value))
                 emit(value);
         });
@@ -225,7 +226,7 @@ export class RangeProgression extends Emitter {
     dedupe() {
         if (!this._dedupe) {
             let previous = null;
-            const listen = this.createTransformListen((value, emit) => {
+            const listen = this.transform((value, emit) => {
                 if (previous !== value) {
                     emit(value);
                     previous = value;
@@ -267,7 +268,7 @@ export class RangeProgression extends 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) => {
+        const listen = this.transform((value, emit) => {
             cb(value);
             emit(value);
         });

package/internal/point.js

@@ -59,7 +59,7 @@ export class TimelinePoint extends Emitter {
         return this._reverseOnly;
     }
     filter(arg) {
-        const listen = this.createTransformListen(typeof arg == "number"
+        const listen = this.transform(typeof arg == "number"
             ? (value, emit) => {
                 if (value.direction === arg)
                     emit(value);
@@ -79,7 +79,7 @@ export class TimelinePoint extends Emitter {
      */
     promise() {
         return new Promise(resolve => {
-            let remove = this.apply((ev) => {
+            let remove = this.onListen((ev) => {
                 remove();
                 resolve(ev.direction);
             });
@@ -116,7 +116,7 @@ export class TimelinePoint extends Emitter {
     dedupe() {
         if (!this._dedupe) {
             let previous = 0;
-            const listen = this.createTransformListen((value, emit) => {
+            const listen = this.transform((value, emit) => {
                 if (value.direction !== previous) {
                     previous = value.direction;
                     emit(value);

package/internal/range.js

@@ -23,8 +23,8 @@ 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");
+        if (position >= this.duration) {
+            throw new RangeError("Bisection position is at or beyond end of range");
         }
         return [
             this.timeline.range(this.startPosition, position),

package/internal/timeline.d.ts

@@ -20,6 +20,20 @@ type Period = {
  */
 export declare function animate(durationMs: number): TimelineRange;
 export declare function animate(period: Period): TimelineRange;
+type TimelineOptions = {
+    atEnd?: {
+        wrapAt: number;
+    } | {
+        restartAt: number;
+    } | keyof typeof EndAction;
+    timeScale?: number;
+} & ({
+    autoplay: true;
+    fps?: number;
+} | ({
+    autoplay?: false;
+    fps?: never;
+}));
 export declare class Timeline {
     /**
      * Multiplies the speed at which `play()` progresses through the Timeline
@@ -90,6 +104,7 @@ export declare class Timeline {
     } | {
         restartAt: number;
     } | keyof typeof EndAction);
+    constructor(options: TimelineOptions);
     /**
      * @deprecated "loop" endAction will be removed; use "restart" or `{restartAt: 0}` (disambiguates new looping strategies)
      */

package/internal/timeline.js

@@ -64,7 +64,7 @@ export class Timeline {
         }
         return this._progression.emitter;
     }
-    constructor(autoplay = false, endAction = "pause") {
+    constructor(optionsOrAutoplay = false, endAction = "pause") {
         /**
          * Multiplies the speed at which `play()` progresses through the Timeline
          *
@@ -85,13 +85,26 @@ export class Timeline {
         this.start = this.point(0);
         this._frameEvents = null;
         this._progression = null;
+        // "loop" is temporary alias for "restart":
         if (endAction == "loop")
             endAction = "restart";
-        if (autoplay === true) {
+        if (typeof optionsOrAutoplay == "object") {
+            endAction = optionsOrAutoplay.atEnd ?? "pause";
+            this.timeScale = optionsOrAutoplay.timeScale ?? 1;
+            if ("autoplay" in optionsOrAutoplay && optionsOrAutoplay.autoplay) {
+                if ("fps" in optionsOrAutoplay && optionsOrAutoplay.fps) {
+                    this.play(optionsOrAutoplay.fps);
+                }
+                else {
+                    this.play();
+                }
+            }
+        }
+        else if (optionsOrAutoplay === true) {
             this.play();
         }
-        else if (typeof autoplay == "number") {
-            this.play(autoplay);
+        else if (typeof optionsOrAutoplay == "number") {
+            this.play(optionsOrAutoplay);
         }
         if (typeof endAction == "object"
             && "restartAt" in endAction) {
@@ -213,7 +226,10 @@ export class Timeline {
             .range(0, durationMs)
             .ease(easer)
             .tween(this._currentTime, toPosition)
-            .apply(v => this.seekDirect(v));
+            .apply(v => {
+            this.seekDirect(v);
+            this._frameEvents?.emit();
+        });
         return seeker.end.promise();
     }
     seekDirect(toPosition) {

package/internal/tween.js

@@ -143,13 +143,13 @@ function tokenise(s) {
     let m;
     while ((m = tweenableTokenRegex.exec(s))) {
         const token = m[0];
-        const prefix = s.slice(lastIdx, m.index); // literal before token
+        const prefix = s.substring(lastIdx, m.index); // literal before token
         const type = getTokenType(token);
         chunks.push({ prefix, token, type });
         lastIdx = m.index + token.length;
     }
     // trailing literal after the last token – stored as a final chunk
-    const tail = s.slice(lastIdx);
+    const tail = s.substring(lastIdx);
     if (tail.length) {
         chunks.push({ prefix: tail, token: "", type: TokenTypes.none });
     }

package/package.json

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