@prtcl/plonk 1.0.10 → 1.1.0

package/dist/index.d.ts

@@ -17,12 +17,21 @@ type RandState = {
  */
 declare class Rand {
     state: RandState;
+    /** Returns a single random value. One-off form of `new Rand(opts).value()`. */
     static rand(opts?: RandOptions): number;
     constructor(opts?: RandOptions);
+    /** Updates the range bounds, clamping the current value if needed. */
     setRange(partialOpts: RandOptions): void;
+    /** Returns the current value. */
     value(): number;
+    /** Generates a new random value within the range. */
     next(): number;
 }
+/**
+ * Random number generator that produces values within a bounded range.
+ * One-off form of `new Rand(opts).value()`.
+ */
+declare const rand: typeof Rand.rand;
 
 /** Options for configuring a Drunk random walk. */
 type DrunkOptions = {
@@ -51,13 +60,25 @@ declare class Drunk {
     state: DrunkState;
     protected _initialValue: Rand;
     protected _step: Rand;
+    /** Creates a new Drunk instance. Alternative form of `new Drunk(opts)`. */
+    static drunk(opts?: DrunkOptions): Drunk;
     constructor(opts?: DrunkOptions);
+    /** Updates the walk bounds, clamping the current value if needed. */
     setRange(partialOpts?: Pick<DrunkOptions, 'min' | 'max'>): void;
+    /** Updates the maximum step size. */
     setStepSize(partialOpts?: Pick<DrunkOptions, 'step'>): void;
+    /** Resets the walk with optional new options. */
     reset(opts?: DrunkOptions): void;
+    /** Returns the current value. */
     value(): number;
+    /** Advances one step and returns the new value. */
     next(): number;
 }
+/**
+ * Stochastic random walk generator that produces values within a bounded range.
+ * Alternative form of `new Drunk(opts)`.
+ */
+declare const drunk: typeof Drunk.drunk;
 
 /** A numeric range with min and max bounds. */
 type ScaleRange = {
@@ -88,13 +109,23 @@ type ScaleState = {
  */
 declare class Scale {
     state: ScaleState;
+    /** Scales a single value. One-off form of `new Scale(opts).scale(n)`. */
     static scale(n: number, opts?: ScaleOptions): number;
     constructor(opts?: ScaleOptions);
+    /** Updates input and/or output ranges, recomputing the internal ratio. */
     setRanges(opts: ScaleOptions): void;
+    /** Resets with new range options. */
     reset(opts: ScaleOptions): void;
+    /** Returns the last scaled value. */
     value(): number;
+    /** Maps a value from the input range to the output range. */
     scale(n: number): number;
 }
+/**
+ * Linear map of values from one range to another, supports negative values and inversion.
+ * One-off form of `new Scale(opts).scale(n)`.
+ */
+declare const scale: typeof Scale.scale;
 
 /** Snapshot of an Env's internal state. */
 type EnvState = {
@@ -121,13 +152,60 @@ type EnvOptions = {
 declare class Env {
     state: EnvState;
     protected _interpolator: Scale;
+    /** Creates a new Env instance. Alternative form of `new Env(opts)`. */
+    static env(opts: EnvOptions): Env;
     constructor(opts: EnvOptions);
+    /** Updates the envelope duration. */
     setDuration(duration: number): void;
+    /** Restarts the envelope with optional new options. */
     reset(opts?: EnvOptions): void;
+    /** Returns true when the envelope has completed. */
     done(): boolean;
+    /** Returns the current interpolated value. */
     value(): number;
+    /** Advances the envelope and returns the new value. */
     next(): number;
 }
+/**
+ * Linear envelope which interpolates between two values over a duration. Useful for audio envelopes, transitions, and animations.
+ * Alternative form of `new Env(opts)`.
+ */
+declare const env: typeof Env.env;
+
+/** Options for configuring a Fold transformer. */
+type FoldOptions = {
+    /** Lower bound of the range. Defaults to 0. */
+    min?: number;
+    /** Upper bound of the range. Defaults to 1. */
+    max?: number;
+};
+/** Snapshot of a Fold transformer's internal state. */
+type FoldState = {
+    min: number;
+    max: number;
+    value: number;
+};
+/**
+ * Folds (reflects) values back and forth within a configured range.
+ * @param opts - {@link FoldOptions} for configuring the range.
+ */
+declare class Fold {
+    state: FoldState;
+    /** Folds a single value. One-off form of `new Fold(opts).fold(n)`. */
+    static fold(n: number, opts?: FoldOptions): number;
+    constructor(opts?: FoldOptions);
+    /** Updates the range bounds, folding the current value into the new range. */
+    setRange(partialOpts: FoldOptions): void;
+    /** Returns the last folded value. */
+    value(): number;
+    /** Folds a value into the configured range and caches the result. */
+    fold(n: number): number;
+}
+/**
+ * Folds (reflects) values back and forth within a configured range.
+ * One-off form of `new Fold(opts).fold(n)`.
+ */
+declare const fold: typeof Fold.fold;
 
 declare const SINE_PERIOD: number;
 /** Options for configuring a Sine oscillator. */
@@ -150,12 +228,58 @@ type SineState = {
 declare class Sine {
     state: SineState;
     protected _interpolator: Scale;
+    /** Creates a new Sine instance. Alternative form of `new Sine(opts)`. */
+    static sine(opts: SineOptions): Sine;
     constructor(opts: SineOptions);
+    /** Updates the cycle duration. */
     setDuration(duration: number): void;
+    /** Resets the oscillator with optional new options. */
     reset(opts?: SineOptions): void;
+    /** Returns the current oscillator value. */
     value(): number;
+    /** Advances the oscillator and returns the new value. */
     next(): number;
 }
+/**
+ * Time-based sine wave oscillator that outputs values between -1 and 1.
+ * Alternative form of `new Sine(opts)`.
+ */
+declare const sine: typeof Sine.sine;
+
+/** Options for configuring a Wrap transformer. */
+type WrapOptions = {
+    /** Lower bound of the range. Defaults to 0. */
+    min?: number;
+    /** Upper bound of the range. Defaults to 1. */
+    max?: number;
+};
+/** Snapshot of a Wrap transformer's internal state. */
+type WrapState = {
+    min: number;
+    max: number;
+    value: number;
+};
+/**
+ * Wraps values around a configured range using modular arithmetic.
+ * @param opts - {@link WrapOptions} for configuring the range.
+ */
+declare class Wrap {
+    state: WrapState;
+    /** Wraps a single value. One-off form of `new Wrap(opts).wrap(n)`. */
+    static wrap(n: number, opts?: WrapOptions): number;
+    constructor(opts?: WrapOptions);
+    /** Updates the range bounds, wrapping the current value into the new range. */
+    setRange(partialOpts: WrapOptions): void;
+    /** Returns the last wrapped value. */
+    value(): number;
+    /** Wraps a value into the configured range and caches the result. */
+    wrap(n: number): number;
+}
+/**
+ * Wraps values around a configured range using modular arithmetic.
+ * One-off form of `new Wrap(opts).wrap(n)`.
+ */
+declare const wrap: typeof Wrap.wrap;
 
 /** Snapshot of a running timer's internal state. */
 type TimerState = {
@@ -183,14 +307,25 @@ declare class Metro {
     state: TimerState;
     protected _listeners: TimerCallback<Metro>[];
     protected _timerId: ReturnType<typeof setTimeout> | number;
+    /** Creates a new Metro instance. Alternative form of `new Metro(callback, opts)`. */
+    static metro(callback: TimerCallback<Metro>, opts?: MetroOptions): Metro;
     constructor(callback: TimerCallback<Metro>, opts?: MetroOptions);
     protected asyncHandler(callback: () => void): void;
     protected clearAsyncHandler(): void;
+    /** Stops the timer and returns total elapsed time in milliseconds. */
     stop: () => number;
+    /** Resets state to initial values. */
     reset: () => void;
+    /** Updates the tick interval in milliseconds. */
     setTime: (updatedTime?: number) => void;
+    /** Starts the timer loop. */
     run: () => void;
 }
+/**
+ * High-resolution recursive timer with variable interval, provides runtime metrics via callback for time-based calculations.
+ * Alternative form of `new Metro(callback, opts)`.
+ */
+declare const metro: typeof Metro.metro;
 
 type FPS = 15 | 30 | 60;
 declare enum TimeFormat {
@@ -217,11 +352,19 @@ type FramesOptions = {
  */
 declare class Frames extends Metro {
     protected _timerId: ReturnType<typeof requestAnimationFrame>;
+    /** Creates a new Frames instance. Alternative form of `new Frames(callback, opts)`. */
+    static frames(callback: TimerCallback<Frames>, opts?: FramesOptions): Frames;
     constructor(callback: TimerCallback<Frames>, opts?: FramesOptions);
     protected asyncHandler(callback: () => void): void;
     protected clearAsyncHandler(): void;
+    /** Updates the target frames per second. */
     setFPS: (fps?: FPS) => void;
 }
+/**
+ * Animation-loop timer that uses requestAnimationFrame when available.
+ * Alternative form of `new Frames(callback, opts)`.
+ */
+declare const frames: typeof Frames.frames;
 
 declare function clamp(n: number): number;
 declare function clamp(n: number, max: number): number;
@@ -252,4 +395,4 @@ declare const MS_IN_SECOND = 1000;
 declare const MS_IN_MINUTE: number;
 declare const MS_IN_HOUR: number;
 
-export { Drunk, type DrunkOptions, type DrunkState, Env, type EnvOptions, type EnvState, type FPS, Frames, type FramesOptions, MS_IN_HOUR, MS_IN_MINUTE, MS_IN_SECOND, Metro, type MetroOptions, Rand, type RandOptions, type RandState, SINE_PERIOD, SIXTY_FPS, Scale, type ScaleOptions, type ScaleRange, type ScaleState, Sine, type SineOptions, type SineState, TimeFormat, type TimerCallback, clamp, expo, ms, now, wait };
+export { Drunk, type DrunkOptions, type DrunkState, Env, type EnvOptions, type EnvState, type FPS, Fold, type FoldOptions, type FoldState, Frames, type FramesOptions, MS_IN_HOUR, MS_IN_MINUTE, MS_IN_SECOND, Metro, type MetroOptions, Rand, type RandOptions, type RandState, SINE_PERIOD, SIXTY_FPS, Scale, type ScaleOptions, type ScaleRange, type ScaleState, Sine, type SineOptions, type SineState, TimeFormat, type TimerCallback, Wrap, type WrapOptions, type WrapState, clamp, drunk, env, expo, fold, frames, metro, ms, now, rand, scale, sine, wait, wrap };