@xtia/timeline 1.0.4 → 1.0.6

package/README.md

@@ -93,7 +93,7 @@ eased.listen(
 const frames = eased
     .tween(0, 30)
     .map(Math.floor)
-    .noRepeat()
+    .dedupe()
     .tap(n => console.log("Showing frame #", n))
     .map(n => `animation-frame-${n}.png`)
     .listen(filename => img.src = filename);
@@ -164,7 +164,6 @@ Tween emitters can interpolate numbers, arrays of numbers, strings, and objects
 
 ```ts
 // tween four values in a CSS string
-// see this live: https://codepen.io/xtaltia/pen/PwZYbKY
 timeline
     .range(0, 2000)
     .ease("elastic")
@@ -178,6 +177,8 @@ timeline
     .listen(v => document.title = v);
 ```
 
+You can try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
+
 ## Autoplay and Looping Strategies
 
 To create a Timeline that immediately starts playing, pass `true` to its constructor:

package/internal/emitters.d.ts

@@ -1,13 +1,14 @@
 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: Omit<API, keyof Emitter<T>>): Emitter<T> & API;
+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>(onListen: ListenFunc<number>, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
+export declare function createProgressEmitter<API extends object>(listen: ListenFunc<number>, api: Omit<API, keyof RangeProgression>): RangeProgression & API;
 /** @internal */
-export declare function createProgressEmitter(onListen: ListenFunc<number>): RangeProgression;
+export declare function createProgressEmitter(listen: ListenFunc<number>): RangeProgression;
 type Handler<T> = (value: T) => void;
 type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
@@ -37,7 +38,7 @@ export interface Emitter<T> {
      * If no `compare` function is provided, values will be compared via `===`
      * @returns Listenable: emits non-repeating values
      */
-    noRepeat(compare?: (a: T, b: T) => boolean): Emitter<T>;
+    dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>;
     /**
      * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
      *
@@ -50,6 +51,25 @@ export interface Emitter<T> {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb: Handler<T>): Emitter<T>;
+    /**
+     * 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: (branch: Emitter<T>) => void): Emitter<T>;
 }
 export interface RangeProgression extends Emitter<number> {
     /**
@@ -124,7 +144,21 @@ export interface RangeProgression extends Emitter<number> {
     clamp(min?: number, max?: number): RangeProgression;
     /**
      * 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: number): RangeProgression;
     /**
@@ -149,9 +183,9 @@ export interface RangeProgression extends Emitter<number> {
      * 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
      */
-    noRepeat(): RangeProgression;
+    dedupe(): RangeProgression;
     /**
-     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping between 0 and 1
+     * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
      *
      * ```plain
      *‎	1
@@ -165,7 +199,9 @@ export interface RangeProgression extends Emitter<number> {
      * ```
      *
      * @param delta
+     * @returns Listenable: emits offset values
      */
     offset(delta: number): RangeProgression;
+    fork(cb: (branch: RangeProgression) => void): RangeProgression;
 }
 export {};

package/internal/emitters.js

@@ -7,7 +7,7 @@ const tween_1 = require("./tween");
 const utils_1 = require("./utils");
 /** @internal */
 function createEmitter(listen, api) {
-    const propertyDescriptor = Object.fromEntries(Object.entries({
+    const methods = {
         listen: (handler) => listen((value) => {
             handler(value);
         }),
@@ -18,7 +18,7 @@ function createEmitter(listen, api) {
             if (filterFunc(value))
                 handler(value);
         })),
-        noRepeat: (compare) => {
+        dedupe: (compare) => {
             let previous = null;
             return createEmitter(handler => {
                 const filteredHandler = (value) => {
@@ -30,18 +30,20 @@ function createEmitter(listen, api) {
                     }
                 };
                 return listen(filteredHandler);
-            });
+            }, api ?? {});
         },
-        tap: (cb) => createTap(cb, createEmitter, listen),
-    }).map(([key, value]) => [
-        key,
-        { value }
-    ]));
-    return Object.create(api ?? {}, propertyDescriptor);
+        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 propertyDescriptor = Object.fromEntries(Object.entries({
+function createProgressEmitter(listen, api) {
+    const methods = {
         ease: (easer) => {
             const easerFunc = typeof easer == "string"
                 ? easing_1.easers[easer]
@@ -71,37 +73,25 @@ function createProgressEmitter(listen, api = {}) {
                 handler(out);
             }));
         },
-        tap: (cb) => createTap(cb, createProgressEmitter, listen),
+        tap: (cb) => createTap(createProgressEmitter, listen, cb),
         filter: (filterFunc) => createProgressEmitter(handler => listen((value) => {
             if (filterFunc(value))
                 handler(value);
         })),
-        noRepeat: () => {
-            let previous = null;
-            return createProgressEmitter(handler => {
-                return listen((value) => {
-                    if (!previous || (previous.value !== value)) {
-                        handler(value);
-                        previous = { value };
-                    }
-                });
-            });
-        },
         offset: (delta) => createProgressEmitter(handler => listen(value => handler((value + delta) % 1))),
-    }).map(([key, value]) => [
-        key,
-        { value }
-    ]));
-    return Object.create(api ?? {}, propertyDescriptor);
+    };
+    const baseEmitter = createEmitter(listen, methods);
+    const emitter = (0, utils_1.prototypify)(baseEmitter, api ?? {});
+    return emitter;
 }
-function createTap(callback, create, parentListen) {
+function createTap(create, parentListen, cb) {
     const listeners = [];
     let parentUnsubscribe = null;
-    const tapOnListen = (handler) => {
+    const tappedListen = (handler) => {
         listeners.push(handler);
         if (listeners.length === 1) {
             parentUnsubscribe = parentListen(value => {
-                callback(value);
+                cb(value);
                 listeners.slice().forEach(fn => fn(value));
             });
         }
@@ -114,5 +104,5 @@ function createTap(callback, create, parentListen) {
             }
         };
     };
-    return create(tapOnListen);
+    return create(tappedListen);
 }

package/internal/utils.d.ts

@@ -2,3 +2,5 @@
 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,6 +1,14 @@
 "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.4",
+  "version": "1.0.6",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"