pacer-js 1.0.7 → 1.0.9

package/Pacer.js

@@ -1,4 +1,4 @@
-//  Copyright ©️ 2025 Stewart Smith. See LICENSE for details.
+//  Copyright ©️ 2025–2026 Stewart Smith. See LICENSE for details.
 
 
 
@@ -27,7 +27,7 @@ import {
 	normalize01,
 	lerp
 
-} from 'shoes-js'
+} from 'snacks-js'
 
 
 
@@ -53,11 +53,19 @@ class Pacer {
 	constructor( label, units ){
 		
 		this._label = isUsefulString( label ) ? label : 'Untitled Pacer instance'
-		this._units = isUsefulString( units ) ? units : 'ms'// ms, milliseconds, s, seconds, #, n, norm, normalize, normalized, %, percent
+
+		
+		//  This is purely to help humans reason around their Pacers.
+		//  No particular value is required. 
+		//  All that matters is that YOU, the human, are consisent with your units.
+		//  If you want to make use of this property, some suggested values:
+		//  ms, milliseconds, s, seconds, #, n, norm, normalize, normalized, %, percent
+
+		this._units = isUsefulString( units ) ? units : 'ms'
 
 		this.keys = []
 		this.keyIndex = -1
-		this.lastTouchedKey = null
+		this.lastCreatedKey = null
 		
 		this.values = {}
 		this.n = 0
@@ -72,7 +80,16 @@ class Pacer {
 	
 
 
-	//  Non-chainable.
+
+
+	    ////////////////////////
+	   //                    //
+	  //   Non-chainables   //
+	 //                    //
+	////////////////////////
+
+
+	//  ie. They do not return `this` (your Pacer instance).
 
 	inspect( useRelative ){
 
@@ -120,7 +137,6 @@ class Pacer {
 		//  This logic is unnecessary,
 		//  but leaving it here for future reference.
 
-
 		// const tweenLabel = keyA.tween.label
 		// if( direction < 0 && tweenLabel !== 'linear' ){
 			
@@ -135,9 +151,9 @@ class Pacer {
 		method = this.isClamped ? normalize01 : normalize,
 		n = method(
 
-			now,
 			keyA.timeAbsolute,
-			keyB.timeAbsolute
+			keyB.timeAbsolute,
+			now
 		),
 		a = Object.keys( keyA.values ),
 		b = Object.keys( keyB.values ),
@@ -147,7 +163,7 @@ class Pacer {
 			if( isNotUsefulNumber( a )) return output
 			const b = keyB.values[ key ]	
 			if( isNotUsefulNumber( b )) return output
-			output[ key ] = lerp( tween( n ), a, b )
+			output[ key ] = lerp( a, b, tween( n ))
 			return output
 		
 		}, {})
@@ -162,7 +178,17 @@ class Pacer {
 
 
 
-	//  Chainable key-focussed methods.
+
+
+	    ////////////////////
+	   //                //
+	  //   Chainables   //
+	 //                //
+	////////////////////
+
+
+	//  ie. They all return `this` (your Pacer instance),
+	//  so you can pipe from one method to another, to another… 
 
 	setTimeBounds(){
 
@@ -182,7 +208,7 @@ class Pacer {
 
 
 			//  Yes, we have to operate directly on the `keys` Array
-			//  rather than `key` element reference
+			//  rather than a `key` element reference
 			//  if we want to actually write this property.
 			//  Otherwise it silently fails. Lovely. 
 			//  And we don’t want to use Array.map 
@@ -190,10 +216,21 @@ class Pacer {
 
 			keys[ i ].index = i
 
+
+			//  You know what?
+			//  Let’s also keep track of _relative_ time
+			//  so it’s as easy as pie 
+			//  to shift key times without more overhead. 
+
+			keys[ i ].timeRelative = i === 0 
+				? 0 
+				: key.timeAbsolute - keys[ i - 1 ].timeAbsolute
+
 			
 			//  Also, here’s a nicety:
 			//  if there’s a key with no values,
 			//  let’s just copy the values from the previous key.
+			// (I have some further ideas about this… Stay tuned!)
 
 			if( key.values instanceof Object !== true &&
 				typeof keys[ i - 1 ] !== 'undefined' &&
@@ -201,23 +238,31 @@ class Pacer {
 
 				keys[ i ].values = keys[ i - 1 ].values
 
-				//  There’s an argument to made for this instead of the above:
-				// keys[ i ].values = Object.assign( {}, keys[ i - 1 ].values )
+
+				//  There’s an argument to be made for this instead of the above:
+				//  keys[ i ].values = Object.assign( {}, keys[ i - 1 ].values )
+				//  Remove ability for original object owner to mutate values? Thoughts? 
 			}
 		})
 		this.setTimeBounds()
 		return this
 	}
+
+
+	//  CHAINABLE “Key-based” methods,
+	//  ie. creates or relies on `this.lastCreatedKey`.
+
 	key( time, values, callback, isAbsolute ){
 
 		if( isAbsolute !== true &&//  Making a theoretical `isRelative` the default for backwards compatibility.
 			this.keys.length > 0 ){
 			
-			time += this.getLastKey().timeAbsolute
+			// time += this.getLastKey().timeAbsolute
+			time += this.lastCreatedKey.timeAbsolute//  IT’S TRICKY TO ROCK A RHYME !
 		}
 		if( this.keys.length === 0 ) this.values = values
 		const key = new Key( time, values, callback )
-		this.lastTouchedKey = key
+		this.lastCreatedKey = key
 		this.keys.push( key )
 		this.sortKeys()
 		if( this.keys.length === 1 ) this.timeCursor = this.timeStart - 1
@@ -231,121 +276,185 @@ class Pacer {
 
 		return this.key( timeAbsolute, values, callback, true )
 	}
-
-
-	labelPacer( s ){
-
-		this._label = s
-		return this
-	}
 	label( s ){
 
-		this.lastTouchedKey.label = s
+		this.lastCreatedKey.label = s
 		return this
 	}
+	//  Well this was stupid…
+	//  Need to meditate on best approach for avoiding name collisions between
+	//  1. Regular old instance object properties,
+	//  2. Setters on this Pacer instance,
+	//  3. Setters actually intended for a Key instance.
+	//  Particularly acute when it comes to .label(), for example.
+	// (I don’t love `label` vs `labelPacer`, but will do for now.)
 	// values( v ){
 
-	// 	this.lastTouchedKey.values = v
+	// 	this.lastCreatedKey.values = v
 	// 	return this
 	// }
-	tween( fn ){
+	onKey( fn ){
 
-		this.lastTouchedKey.tween = fn
+		this.lastCreatedKey.onKey = fn
 		return this
 	}
-	clamp(){
+	tween( fn ){
 
-		this.isClamped = true
+		this.lastCreatedKey.tween = fn
 		return this
 	}
-	unclamp(){
-
+	onTween( fn ){
 
-		this.isClamped = false
+		this.lastCreatedKey.onTween = fn
 		return this
 	}
-	units( u ){
+	onCancel( fn ){
 
-		this._units = u
+		this.lastCreatedKey.onCancel = fn
 		return this
 	}
 
 
-	onKey( fn ){
+	//  CHAINABLE “instance-wide” callback setters,
+	//  ie. These do _not_ rely on `this.lastCreatedKey`
+	//  and set callbacks for the instance to use.
+
+	onEveryKey( fn ){
 
-		this.lastTouchedKey.onKey = fn
+		this._onEveryKey = fn
 		return this
 	}
-	onTween( fn ){
+	onEveryTween( fn ){
 
-		this.lastTouchedKey.onTween = fn
+		this._onEveryTween = fn
 		return this
 	}
-	onCancel( fn ){
+	onBeforeAll( fn ){
+
+		this._onBefore = fn
+		return this
+	}
+	onAfterAll( fn ){
 
-		this.lastTouchedKey.onCancel = fn
+		this._onAfter = fn
 		return this
 	}
 
 
-	//  Chainable instance-wide methods.
+	//  CHAINABLE “instance-wide” commands,
+	//  ie. These do _not_ rely on `this.lastCreatedKey`
+	//  and issue simple property setters.
 
-	onBeforeAll( fn ){
+	labelPacer( s ){//  This naming gives me pause.
 
-		this._onBefore = fn
+		this._label = s
 		return this
 	}
-	onAfterAll( fn ){
+	units( u ){
 
-		this._onAfter = fn
+		this._units = u
 		return this
 	}
-	onEveryKey( fn ){
+	clamp(){
 
-		this._onEveryKey = fn
+		this.isClamped = true
 		return this
 	}
-	onEveryTween( fn ){
+	unclamp(){
 
-		this._onEveryTween = fn
+		this.isClamped = false
 		return this
 	}
 
 
-	//  Chainable commands.
+	//  A quick way to turn individual instances on/off,
+	//  particuarly convenient if doing bulk updates
+	//  like `Pacer.update()` ← Note that’s the Class method itself,
+	//  not an instance method.
+
+	enable(){
+
+		this.isEnabled = true
+		return this
+	}
+	disable(){
+
+		this.isEnabled = false
+		return this
+	}
+
+
+	//  All those moments will be lost in time, 
+	//  like tears in rain. 
+	//  Time to die.
+
+	remove(){
+		
+		Pacer.remove( this )
+		return this
+	}
+
+
+
+
+	    ////////////////
+	   //            //
+	  //   Update   //
+	 //            //
+	////////////////
+
+	
+	//  Yeah. This one method deserves its own rhombus comment block, 
+	//  because if it were a pickle it would wear a shirt that says
+	// “I’m a big dill.” Pho real.
+	//  See also `onKey` and `onTween` below.
 
 	update( now ){
 
 
 		//  We only need to update
-		//  if we are enabled
-		//  and we have at least one keyframe
-		//    that might have either a values object, 
-		//    an onKey callback,
-		//    or would be included if there’s an onEveryKey callback.
+		//  if our instance is enabled
+		//  and we have at least one keyframe:
+		//    that might have either a values{} object, 
+		//    an onKey() callback,
+		//    or would be included if there’s an onEveryKey() callback.
 
 		if( this.isEnabled !== true ) return this
 		if( this.keys.length < 1 ) return this
 
-		
-		//  So I guess we’re doing this.
+
 		//  What time is it?
-		//  And what direction are we flowing?
+		//  Remember that “time” is just a numeric value…
+		//  You’ll likely use it for time, sure,
+		//  but you could also follow Scroll Pacer’s example
+		//  and instead send pixel values 
+		//  describing an element’s relationship to the viewport.
 
 		if( isNotUsefulNumber( now )) now = Date.now()
-		if( now === this.timeCursor ) return this//  Unlikely for standalone animations, but very likely for scroll animations.
-		const direction = now < this.timeCursor ? -1 : 1
 
 
+		//  The following is unlikely to be true for standalone animations, 
+		//  but very likely for scroll animations.
+
+		if( now === this.timeCursor ) return this
+
+
+		//  If we made it to here, I guess we’re actually doing this.
+		//  So what direction is our time flowing?
+
+		const direction = now < this.timeCursor ? -1 : 1
+
+		
 		//  What’s our total N gain for the this entire instance?
 
 		const method = this.isClamped ? normalize01 : normalize
-		this.n = method( now, this.timeStart, this.timeStop )
+		this.n = method( this.timeStart, this.timeStop, now )
 
 
 		//  We know our keys are already sorted by time,
 		//  and we’ve previously set the convenience variables
 		// `timeStart` and `timeStop`.
+		// (This sorting happens automagically with every key creation.)
 		
 		//  Note 1: Direction has no effect on the order of
 		//  keyA and keyB, because we always want this to be true:
@@ -354,6 +463,7 @@ class Pacer {
 		
 		//  Note 2: For this step, it is perfectly reasonable
 		//  for keyA or keyB to be undefined. 
+		//  That is a signal itself, not a lack of signal.
 
 		let 
 		targetIndex = 0,
@@ -413,9 +523,10 @@ class Pacer {
 		}
 
 
-		//  Let’s prep for calling onKey --
+		//  Let’s prep for any onKey callbacks;
 		//  You never know what someone’s callbacks
-		//  are going to ask for on this instance!
+		//  are going to ask for on this instance
+		//  so it’s best to be kind and sharing.
 
 		const keyIndexPrior = this.keyIndex
 		this.direction = direction
@@ -423,8 +534,6 @@ class Pacer {
 
 
 
-
-
 		    ///////////////
 		   //           //
 		  //   onKey   //
@@ -490,6 +599,12 @@ class Pacer {
 
 						tempKey.onKey( tempKey.values, this )
 					}
+
+
+					//  In the future we may wish to distinguish
+					//  between `onEveryKeyEarly` and `onEveryKeyLate`
+					//  in order to allow users finer control.
+
 					if( typeof this._onEveryKey === 'function' ){
 
 						this._onEveryKey( tempKey.values, this )
@@ -503,8 +618,6 @@ class Pacer {
 
 
 
-
-
 		    /////////////////
 		   //             //
 		  //   onTween   //
@@ -512,10 +625,14 @@ class Pacer {
 		/////////////////
 
 
-		//  If we have just keyframed during this update() loop,
-		//  no need to attempt to tween -- in fact that could
-		//  cause an awful stutter or bounce.
-
+		//  It is possible that our `now` is _exactly_ on a 
+		//  keyframe’s intended firing time.
+		//  If that’s the case, isn’t it redundant to tween?
+		//  YES. But the moment we tried removing the ability to 
+		//  fire tween callbacks when it aligned with a keyframe, 
+		//  we ran into unintended logical “gotchas” on the user side.
+		//  If you are incredibly anxious about performance, 
+		//  you may want to give more thought to your callbacks here. 
 
 		//  We need TWO valid keyframes in order to tween anything.
 		//  If we don’t got, we bail now.
@@ -553,19 +670,21 @@ class Pacer {
 
 				keyA._onTween( this.values, this )
 			}
+
+
+			//  In the future we may wish to distinguish
+			//  between `onEveryTweenEarly` and `onEveryTweenLate`
+			//  in order to allow users finer control.
+
 			if( typeof this._onEveryTween === 'function' ){
 
 				this._onEveryTween( this.values, this )
 			}
 		}
-		
-			
 		return this
 	}
-
-
-
-
+	
+	
 	reset( newTimeStartAbsolute ){
 
 		this.disable()
@@ -576,7 +695,11 @@ class Pacer {
 		.forEach( function( key, i, keys ){
 
 			timeCursor += key.timeRelative
-			keys[ i ].timeAbsolute = timeCursor//  Again, see reasoning above for using .forEach rather than .reduce or .map here.
+			
+			
+			//  Again, see reasoning above for using .forEach rather than .reduce or .map here.
+
+			keys[ i ].timeAbsolute = timeCursor
 		})
 		this.setTimeBounds()
 		this.keyIndex   = -1
@@ -586,37 +709,18 @@ class Pacer {
 	}
 
 
-	//  A quick way to turn individual pacers on/off,
-	//  particuarly convenient if doing builk updates
-	//  like Pacer.update() ← Note that’s the Class method itself,
-	//  not an instance method.
-
-	enable(){
-
-		this.isEnabled = true
-		return this
-	}
-	disable(){
-
-		this.isEnabled = false
-		return this
-	}
-
 
-	//  All those moments will be lost in time, 
-	//  like tears in rain. 
-	//  Time to die.
 
-	remove(){
-		
-		Pacer.remove( this )
-		return this
-	}
 
 
+	    /////////////////
+	   //             //
+	  //   Statics   //
+	 //             //
+	/////////////////
 
 
-	//  STATICS: `this === Pacer`
+	//  ie `this === Pacer`
 
 	static all = []
 	static update( now ){
@@ -665,15 +769,28 @@ class Pacer {
 
 
 
+
+
+    ////////////////
+   //            //
+  //   Easing   //
+ //            //
+////////////////
+
+
 //  Tweening functions, aka Easing functions.
 // “Tween” is of course short for “between”, as in _between_ the keyframes.
-//  We’ll start with our default tween (no easing):
+//  We’ll start with our default tween (no fancy easing):
 
 Pacer.linear = function( n ){ return n }
 Pacer.linear.label = 'linear'
 
 
-//  Look how ’purty these symetric functions are boxed up.
+//  Robert Penner’s collection of easing functions.
+//  https://robertpenner.com/easing/
+//  Look how ’purty I’ve boxed up these symetric functions!
+//  Compare to how much lengthier and complicated this looks:
+//  https://github.com/danro/jquery-easing/blob/master/jquery.easing.js
 //  Down the road we ought to add Bezier() and Custom options.
 
 Object.entries({
@@ -707,6 +824,10 @@ Object.entries({
 	key = entry[ 0 ],
 	val = entry[ 1 ]
 
+
+	//  Graft our easing logic right onto Pacer
+	//  so it’s trivial to access.
+
 	Pacer[ key ] = {
 
 		label: key,
@@ -735,8 +856,7 @@ Object.entries({
 Pacer.bounce = {
 
 	label: 'bounce',
-	in: n => 1 - val( 1 - n ),
-	out: function( n, n1, d1 ){
+	out: function( n, n1, d1 ){//  Oddly, must be defined before `in` and `inOut`.
 
 		if( isNotUsefulNumber( n1 )) n1 = 7.5625
 		if( isNotUsefulNumber( d1 )) d1 = 2.75
@@ -745,7 +865,10 @@ Pacer.bounce = {
 		else if( n < 2.5 / d1 ) return n1 * ( n -= 2.25 / d1 ) * n + 0.9375
 		else return n1 * ( n -= 2.625 / d1 ) * n + 0.984375
 	},
-	inOut: n => n < 0.5 ? val( n * 2 ) / 2 : val( n * 2 - 1 ) / 2 + 0.5
+	in: n => 1 - Pacer.bounce.out( 1 - n ),
+	inOut: n => n < 0.5 
+		? Pacer.bounce.out( n * 2 ) / 2 
+		: Pacer.bounce.out( n * 2 - 1 ) / 2 + 0.5
 }
 Pacer.bounce.in.label = 'bounce'
 Pacer.bounce.in.style = 'in'

package/README.md

@@ -1,13 +1,11 @@
 <img src="./pacer.svg?raw=true" width="100%">  
 
-<br>
-
 
 
 
 ##  TL;DR
 
-__Pacer__ is a light-weight keyframing toolkit inspired by [Soledad Penadés](https://soledadpenades.com/)’ original [tween.js](https://soledadpenades.com/projects/tween-js/) masterpiece. List your keyframes as time / value pairs, and __Pacer__ will ✨ tween your numbers and 📞 call your callbacks. __It’s minimal__. Only does what it needs to. __It’s reliable__. We use this in our own professional projects. We found the bumps and sanded them down ✅ (so you won’t have to). Either include the `Pacer.js` ES6 module in your codebase, or install the [Node package](https://www.npmjs.com/package/pacer-js):
+__Pacer__ is a light-weight keyframing toolkit inspired by [Soledad Penadés](https://soledadpenades.com/)’ original [tween.js](https://soledadpenades.com/projects/tween-js/) masterpiece. List your keyframes as time / value pairs, and __Pacer__ will ✨ tween your numbers and 📞 call your callbacks. __It’s minimal__. Only does what it needs to. __It’s reliable__. We use this in our own professional projects. We found the bumps and sanded them down ✅ (so you won’t have to). Either include the [`Pacer.js`](./Pacer.js) ES6 module (and its [one dependency](https://github.com/stewdio/snacks-js)) in your codebase, or install the [Node package](https://www.npmjs.com/package/pacer-js):
 
 ```shell
 npm install pacer-js
@@ -42,7 +40,7 @@ That’s it. You’re good to go 👍
 
 
 
-<br><br><br><br>
+<br><br><br>
 
 
 
@@ -131,7 +129,7 @@ Expanding on the above, a code block should read like a normal paragraph of text
 
 ###  Relative _and_ absolute timestamps
 
-By default, keyframes are specificed by _relative_ time. (“Do this two seconds after that last keyframe.”) This makes it trivial to swap pieces of an animation around—just cut and paste—without having to redo all the keyframe timings. Our TL;DR example uses the `key` command to illustrate this workflow, but we could have also used the slightly more descriptive `rel` (“relative”) alias to accomplish the exact same thing. All relative times are relative to the chronologically-latest keyframe as determined the moment the `key` or `rel` command is processed. (And yes, you can specify a _negative_ relative time—if you’re into that sort of thing.) What about your _first_ keyframe—which has no prior keyframe to be relative to? Consider it relative to _zero_—which makes it both relative _and_ absolute. Note the use of the alias `rel` here rather than `key`:
+By default, keyframes are specificed by _relative_ time. (“Do this two seconds after that last keyframe.”) This makes it trivial to swap pieces of an animation around—just cut and paste—without having to redo all the keyframe timings. Our [TL;DR example](#tldr) uses the `key` command to illustrate this workflow, but we could have also used the slightly more descriptive `rel` (“relative”) alias to accomplish the exact same thing. All relative times are relative to the _most recently created keyframe_ as determined the moment the `key` or `rel` command is processed. (And yes, you can specify a _negative_ relative time—if you’re into that sort of thing.) What about your _first_ keyframe—which has no prior keyframe to be relative to? Consider it relative to _zero_—which makes it both relative _and_ absolute. Note the use of the alias `rel` here rather than `key`:
 
 ```javascript
 var now = Date.now()
@@ -174,7 +172,7 @@ new Pacer()
 .onKey(()=> console.log( '2nd keyframe' ))
 ```
 
-When you create a keyframe, it is added to your instance’s `keys` array, and that array of keyframes is then sorted in chronological order according to each keyframe’s absolute time. Meanwhile, your instance also keeps track of the last keyframe you have “touched” via a `lastTouchedKey` property, so that subsequent commands like `onKey` or `tween` always refer to that last mentioned keyframe. 
+When you create a keyframe, it is added to your instance’s `keys` array, and that array of keyframes is then sorted in chronological order according to each keyframe’s absolute time. (This ensures your `keys` array is always tidy.) Meanwhile, your instance also keeps track of the last keyframe you have created via a `lastCreatedKey` property, so that subsequent commands like `onKey` or `tween` always refer to the “intuitively correct” keyframe. Your code reads like a short story.
 
 
 
@@ -240,7 +238,7 @@ Each easing equation includes its `in`, `out`, and `inOut` variants, eg. `Pacer.
 
 ###  Every key, every tween
 
-If you find you’re running the same callback over and over, perhaps you’d prefer to declare that just once? We’ve got you covered. Use `onEveryKey` to declare a callback that will fire on _every_ keyframe, and `onEveryTween` to do the same for all tweens. [Something borrowed, something blue. Every tween callback for you](https://youtu.be/4YR_Mft7yIM).  
+If you find you’re running the same callback over and over, perhaps you’d prefer to declare that just once? We’ve got you covered. Use `onEveryKey` to declare a callback that will fire on _every_ keyframe, and `onEveryTween` to do the same for all tweens. [Something borrowed, something blue. Every key and tween for you](https://youtu.be/4YR_Mft7yIM).  
 
 
 ```javascript
@@ -462,7 +460,7 @@ Another thing to note is that `update` expects an _absolute_ number, rather than
 
 ###  Forward _and_ backward
 
-Mathematically, [time can flow both forward _and_ backward](https://en.wikipedia.org/wiki/Tenet_(film)). Why would __Pacer__ ignore that reality? The ability to scrub a timeline back and forth is incredibly valuable, and literally the mechanism that our __ScrollPacer__ toolkit uses for scroll-based animations. (More on this to come.) Rest assured that your `update` call can handle time flowing in either direction (and at any speed). It just works.
+Mathematically, [time can flow both forward _and_ backward](https://en.wikipedia.org/wiki/Tenet_(film)). Why would __Pacer__ ignore that reality? The ability to scrub a timeline back and forth is incredibly valuable, and literally the mechanism that our [__Scroll Pacer__](https://github.com/stewdio/scroll-pacer-js) toolkit uses for scroll-based animations. (More on this to come.) Rest assured that your `update` call can handle time flowing in either direction (and at any speed). It just works.