@prtcl/plonk 1.0.10 → 1.1.0

package/dist/index.cjs

@@ -24,6 +24,7 @@ var index_exports = {};
 __export(index_exports, {
   Drunk: () => Drunk,
   Env: () => Env,
+  Fold: () => Fold,
   Frames: () => Frames,
   MS_IN_HOUR: () => MS_IN_HOUR,
   MS_IN_MINUTE: () => MS_IN_MINUTE,
@@ -35,11 +36,21 @@ __export(index_exports, {
   Scale: () => Scale,
   Sine: () => Sine,
   TimeFormat: () => TimeFormat,
+  Wrap: () => Wrap,
   clamp: () => clamp,
+  drunk: () => drunk,
+  env: () => env,
   expo: () => expo,
+  fold: () => fold,
+  frames: () => frames,
+  metro: () => metro,
   ms: () => ms,
   now: () => now,
-  wait: () => wait
+  rand: () => rand,
+  scale: () => scale,
+  sine: () => sine,
+  wait: () => wait,
+  wrap: () => wrap
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -59,7 +70,7 @@ function clamp(n, min, max) {
   return Math.min(Math.max(n, a), b);
 }
 
-// src/Rand.ts
+// src/rand.ts
 var parseOptions = (opts) => {
   return {
     min: 0,
@@ -74,9 +85,11 @@ var Rand = class _Rand {
     this.state = { max, min, value: 0 };
     this.next();
   }
+  /** Returns a single random value. One-off form of `new Rand(opts).value()`. */
   static rand(opts) {
     return new _Rand(opts).value();
   }
+  /** Updates the range bounds, clamping the current value if needed. */
   setRange(partialOpts) {
     const { value = 0 } = this.state;
     const { min, max } = {
@@ -90,9 +103,11 @@ var Rand = class _Rand {
       value: clamp(value, min, max)
     };
   }
+  /** Returns the current value. */
   value() {
     return this.state.value;
   }
+  /** Generates a new random value within the range. */
   next() {
     const { min, max } = this.state;
     const updates = Math.random() * (max - min) + min;
@@ -100,8 +115,9 @@ var Rand = class _Rand {
     return updates;
   }
 };
+var rand = Rand.rand;
 
-// src/Drunk.ts
+// src/drunk.ts
 var DEFAULT_DRUNK_STEP = 0.1;
 var parseStepSize = (step) => typeof step !== "undefined" ? clamp(step, 0, 1) : DEFAULT_DRUNK_STEP;
 var parseOptions2 = (opts) => {
@@ -115,7 +131,7 @@ var parseOptions2 = (opts) => {
     ...restOpts
   };
 };
-var Drunk = class {
+var Drunk = class _Drunk {
   constructor(opts) {
     __publicField(this, "state");
     __publicField(this, "_initialValue");
@@ -132,6 +148,11 @@ var Drunk = class {
       value: initialValue
     };
   }
+  /** Creates a new Drunk instance. Alternative form of `new Drunk(opts)`. */
+  static drunk(opts) {
+    return new _Drunk(opts);
+  }
+  /** Updates the walk bounds, clamping the current value if needed. */
   setRange(partialOpts) {
     const { max, min } = {
       min: this.state.min,
@@ -152,6 +173,7 @@ var Drunk = class {
       }
     };
   }
+  /** Updates the maximum step size. */
   setStepSize(partialOpts) {
     const step = parseStepSize(partialOpts?.step);
     this.state = {
@@ -159,6 +181,7 @@ var Drunk = class {
       step
     };
   }
+  /** Resets the walk with optional new options. */
   reset(opts) {
     const { min, max, startsAt, step } = parseOptions2(opts);
     this.setRange({ min, max });
@@ -170,9 +193,11 @@ var Drunk = class {
       value: initialValue
     };
   }
+  /** Returns the current value. */
   value() {
     return this.state.value;
   }
+  /** Advances one step and returns the new value. */
   next() {
     const { min, max, step, value } = this.state;
     const updates = clamp(value + max * this._step.next() * step, min, max);
@@ -180,8 +205,29 @@ var Drunk = class {
     return updates;
   }
 };
+var drunk = Drunk.drunk;
 
-// src/Scale.ts
+// src/now.ts
+var innerNow = (() => {
+  if (typeof performance !== "undefined" && "now" in performance) {
+    return () => performance.now();
+  }
+  if (typeof process === "object" && process.toString() === "[object process]") {
+    const ts = () => {
+      const hr = process.hrtime();
+      return hr[0] * 1e9 + hr[1];
+    };
+    const initialNow2 = ts();
+    return () => (ts() - initialNow2) / 1e6;
+  }
+  const initialNow = Date.now();
+  return () => Date.now() - initialNow;
+})();
+function now() {
+  return innerNow();
+}
+
+// src/scale.ts
 var computeRatio = (from, to) => (to.max - to.min) / (from.max - from.min);
 var parseInitialState = (opts) => {
   const initialRange = {
@@ -225,18 +271,23 @@ var Scale = class _Scale {
     __publicField(this, "state");
     this.state = parseInitialState(opts);
   }
+  /** Scales a single value. One-off form of `new Scale(opts).scale(n)`. */
   static scale(n, opts) {
     return new _Scale(opts).scale(n);
   }
+  /** Updates input and/or output ranges, recomputing the internal ratio. */
   setRanges(opts) {
     this.state = updateStateFromOptions(opts, this.state);
   }
+  /** Resets with new range options. */
   reset(opts) {
     this.state = parseInitialState(opts);
   }
+  /** Returns the last scaled value. */
   value() {
     return this.state.value;
   }
+  /** Maps a value from the input range to the output range. */
   scale(n) {
     const { from, to, ratio } = this.state;
     const updates = to.min + (clamp(n, from.min, from.max) - from.min) * ratio;
@@ -244,28 +295,9 @@ var Scale = class _Scale {
     return updates;
   }
 };
+var scale = Scale.scale;
 
-// src/now.ts
-var innerNow = (() => {
-  if (typeof performance !== "undefined" && "now" in performance) {
-    return () => performance.now();
-  }
-  if (typeof process === "object" && process.toString() === "[object process]") {
-    const ts = () => {
-      const hr = process.hrtime();
-      return hr[0] * 1e9 + hr[1];
-    };
-    const initialNow2 = ts();
-    return () => (ts() - initialNow2) / 1e6;
-  }
-  const initialNow = Date.now();
-  return () => Date.now() - initialNow;
-})();
-function now() {
-  return innerNow();
-}
-
-// src/Env.ts
+// src/env.ts
 var parseOptions3 = (opts) => {
   return {
     duration: 0,
@@ -297,7 +329,7 @@ var updateStateFromOptions2 = (opts, prevState) => {
     totalElapsed: 0
   };
 };
-var Env = class {
+var Env = class _Env {
   constructor(opts) {
     __publicField(this, "state");
     __publicField(this, "_interpolator");
@@ -314,6 +346,11 @@ var Env = class {
       }
     });
   }
+  /** Creates a new Env instance. Alternative form of `new Env(opts)`. */
+  static env(opts) {
+    return new _Env(opts);
+  }
+  /** Updates the envelope duration. */
   setDuration(duration) {
     const { to, totalElapsed } = this.state;
     this.state = {
@@ -324,6 +361,7 @@ var Env = class {
       } : { duration }
     };
   }
+  /** Restarts the envelope with optional new options. */
   reset(opts) {
     const updates = updateStateFromOptions2(opts, this.state);
     this.state = {
@@ -342,9 +380,11 @@ var Env = class {
       }
     });
   }
+  /** Returns true when the envelope has completed. */
   done() {
     return this.state.duration <= this.state.totalElapsed;
   }
+  /** Returns the current interpolated value. */
   value() {
     const { to, value } = this.state;
     if (this.done()) {
@@ -352,6 +392,7 @@ var Env = class {
     }
     return value;
   }
+  /** Advances the envelope and returns the new value. */
   next() {
     if (this.done()) {
       return this.value();
@@ -367,8 +408,73 @@ var Env = class {
     return updates;
   }
 };
+var env = Env.env;
 
-// src/Sine.ts
+// src/fold.ts
+var parseOptions4 = (opts) => {
+  return {
+    min: 0,
+    max: 1,
+    ...opts
+  };
+};
+var Fold = class _Fold {
+  constructor(opts) {
+    __publicField(this, "state");
+    const { min, max } = parseOptions4(opts);
+    this.state = { min, max, value: min };
+  }
+  /** Folds a single value. One-off form of `new Fold(opts).fold(n)`. */
+  static fold(n, opts) {
+    return new _Fold(opts).fold(n);
+  }
+  /** Updates the range bounds, folding the current value into the new range. */
+  setRange(partialOpts) {
+    const { min, max } = { ...this.state, ...partialOpts };
+    this.state = {
+      ...this.state,
+      min,
+      max,
+      value: transform(this.state.value, min, max)
+    };
+  }
+  /** Returns the last folded value. */
+  value() {
+    return this.state.value;
+  }
+  /** Folds a value into the configured range and caches the result. */
+  fold(n) {
+    const { min, max } = this.state;
+    const updates = transform(n, min, max);
+    this.state.value = updates;
+    return updates;
+  }
+};
+var fold = Fold.fold;
+function transform(n, min, max) {
+  let a = 0;
+  let b = 1;
+  if (typeof min === "number") {
+    if (typeof max === "number") {
+      a = min;
+      b = max;
+    } else {
+      a = 0;
+      b = min;
+    }
+  }
+  const lo = Math.min(a, b);
+  const hi = Math.max(a, b);
+  const range = hi - lo;
+  if (range === 0) return lo;
+  const period = range * 2;
+  const offset = n - lo;
+  const normalized = (offset % period + period) % period;
+  const value = normalized <= range ? lo + normalized : lo + period - normalized;
+  return clamp(value, lo, hi);
+}
+
+// src/sine.ts
 var SINE_PERIOD = Math.PI * 2 - 1e-4;
 var getInitialState2 = (duration) => ({
   cycle: 0,
@@ -377,7 +483,7 @@ var getInitialState2 = (duration) => ({
   totalElapsed: 0,
   value: 0
 });
-var Sine = class {
+var Sine = class _Sine {
   constructor(opts) {
     __publicField(this, "state");
     __publicField(this, "_interpolator");
@@ -394,12 +500,18 @@ var Sine = class {
     });
     this.state = getInitialState2(duration);
   }
+  /** Creates a new Sine instance. Alternative form of `new Sine(opts)`. */
+  static sine(opts) {
+    return new _Sine(opts);
+  }
+  /** Updates the cycle duration. */
   setDuration(duration) {
     this.state = {
       ...this.state,
       duration
     };
   }
+  /** Resets the oscillator with optional new options. */
   reset(opts) {
     const { duration } = {
       ...this.state,
@@ -407,9 +519,11 @@ var Sine = class {
     };
     this.state = getInitialState2(duration);
   }
+  /** Returns the current oscillator value. */
   value() {
     return this.state.value;
   }
+  /** Advances the oscillator and returns the new value. */
   next() {
     const { cycle, duration, prev, totalElapsed: prevTotalElapsed } = this.state;
     const curr = now();
@@ -427,6 +541,70 @@ var Sine = class {
     return updates;
   }
 };
+var sine = Sine.sine;
+
+// src/wrap.ts
+var parseOptions5 = (opts) => {
+  return {
+    min: 0,
+    max: 1,
+    ...opts
+  };
+};
+var Wrap = class _Wrap {
+  constructor(opts) {
+    __publicField(this, "state");
+    const { min, max } = parseOptions5(opts);
+    this.state = { min, max, value: min };
+  }
+  /** Wraps a single value. One-off form of `new Wrap(opts).wrap(n)`. */
+  static wrap(n, opts) {
+    return new _Wrap(opts).wrap(n);
+  }
+  /** Updates the range bounds, wrapping the current value into the new range. */
+  setRange(partialOpts) {
+    const { min, max } = {
+      ...this.state,
+      ...partialOpts
+    };
+    this.state = {
+      ...this.state,
+      min,
+      max,
+      value: transform2(this.state.value, min, max)
+    };
+  }
+  /** Returns the last wrapped value. */
+  value() {
+    return this.state.value;
+  }
+  /** Wraps a value into the configured range and caches the result. */
+  wrap(n) {
+    const { min, max } = this.state;
+    const updates = transform2(n, min, max);
+    this.state.value = updates;
+    return updates;
+  }
+};
+var wrap = Wrap.wrap;
+function transform2(n, min, max) {
+  let a = 0;
+  let b = 1;
+  if (typeof min === "number") {
+    if (typeof max === "number") {
+      a = min;
+      b = max;
+    } else {
+      a = 0;
+      b = min;
+    }
+  }
+  const lo = Math.min(a, b);
+  const range = Math.max(a, b) - lo;
+  if (range === 0) return lo;
+  const offset = n - lo;
+  return lo + (offset % range + range) % range;
+}
 
 // src/constants.ts
 var SIXTY_FPS = 1e3 / 60;
@@ -434,7 +612,7 @@ var MS_IN_SECOND = 1e3;
 var MS_IN_MINUTE = 60 * MS_IN_SECOND;
 var MS_IN_HOUR = MS_IN_MINUTE * 60;
 
-// src/Metro.ts
+// src/metro.ts
 var getInitialState3 = (initialTime) => {
   return {
     initialTime,
@@ -468,26 +646,29 @@ var processTimerState = (state) => {
     totalElapsed: totalElapsed + tickInterval
   };
 };
-var parseOptions4 = (opts) => {
+var parseOptions6 = (opts) => {
   return {
     time: SIXTY_FPS,
     ...opts
   };
 };
-var Metro = class {
+var Metro = class _Metro {
   constructor(callback, opts) {
     __publicField(this, "state");
     __publicField(this, "_listeners");
+    /** Stops the timer and returns total elapsed time in milliseconds. */
     __publicField(this, "stop", () => {
       const { totalElapsed } = this.state;
       this.reset();
       this.clearAsyncHandler();
       return totalElapsed;
     });
+    /** Resets state to initial values. */
     __publicField(this, "reset", () => {
       const { initialTime } = this.state;
       this.state = getInitialState3(initialTime);
     });
+    /** Updates the tick interval in milliseconds. */
     __publicField(this, "setTime", (updatedTime = this.state.time) => {
       const time = Math.max(updatedTime, 0);
       this.state = {
@@ -496,6 +677,7 @@ var Metro = class {
         initialTime: time
       };
     });
+    /** Starts the timer loop. */
     __publicField(this, "run", () => {
       if (this.state.isRunning) {
         this.stop();
@@ -519,10 +701,14 @@ var Metro = class {
       };
       tick();
     });
-    const { time } = parseOptions4(opts);
+    const { time } = parseOptions6(opts);
     this.state = getInitialState3(time);
     this._listeners = [callback];
   }
+  /** Creates a new Metro instance. Alternative form of `new Metro(callback, opts)`. */
+  static metro(callback, opts) {
+    return new _Metro(callback, opts);
+  }
   asyncHandler(callback) {
     this._timerId = setTimeout(callback, SIXTY_FPS);
   }
@@ -530,6 +716,7 @@ var Metro = class {
     clearTimeout(this._timerId);
   }
 };
+var metro = Metro.metro;
 
 // src/ms.ts
 var TimeFormat = /* @__PURE__ */ ((TimeFormat2) => {
@@ -598,9 +785,9 @@ function ms(val, format) {
   return formatter(parsedValue);
 }
 
-// src/Frames.ts
+// src/frames.ts
 var DEFAULT_FPS = 60;
-var parseOptions5 = (opts) => {
+var parseOptions7 = (opts) => {
   const { fps } = {
     fps: DEFAULT_FPS,
     ...opts
@@ -609,13 +796,18 @@ var parseOptions5 = (opts) => {
     time: ms(fps, "fps" /* FPS */)
   };
 };
-var Frames = class extends Metro {
+var Frames = class _Frames extends Metro {
   constructor(callback, opts) {
-    super(() => callback(this), parseOptions5(opts));
+    super(() => callback(this), parseOptions7(opts));
+    /** Updates the target frames per second. */
     __publicField(this, "setFPS", (fps = DEFAULT_FPS) => {
       this.setTime(ms(fps, "fps" /* FPS */));
     });
   }
+  /** Creates a new Frames instance. Alternative form of `new Frames(callback, opts)`. */
+  static frames(callback, opts) {
+    return new _Frames(callback, opts);
+  }
   asyncHandler(callback) {
     if (typeof window === "undefined" || !("requestAnimationFrame" in window)) {
       super.asyncHandler(callback);
@@ -631,6 +823,7 @@ var Frames = class extends Metro {
     }
   }
 };
+var frames = Frames.frames;
 
 // src/expo.ts
 function expo(n) {
@@ -645,6 +838,7 @@ function wait(time) {
 0 && (module.exports = {
   Drunk,
   Env,
+  Fold,
   Frames,
   MS_IN_HOUR,
   MS_IN_MINUTE,
@@ -656,10 +850,20 @@ function wait(time) {
   Scale,
   Sine,
   TimeFormat,
+  Wrap,
   clamp,
+  drunk,
+  env,
   expo,
+  fold,
+  frames,
+  metro,
   ms,
   now,
-  wait
+  rand,
+  scale,
+  sine,
+  wait,
+  wrap
 });
 //# sourceMappingURL=index.cjs.map