@thi.ng/timestep 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-06-14T07:58:51Z
+- **Last updated**: 2023-06-19T09:41:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/timestep@0.4.0) (2023-06-19)
+
+#### 🚀 Features
+
+- update Numeric/VectorState, add 2/3/4d versions ([65ace1e](https://github.com/thi-ng/umbrella/commit/65ace1e))
+  - remove abstract AState class
+  - update NumericState
+  - add new VectorState impl
+  - add defVector2/3/4()
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/timestep@0.3.0) (2023-05-05)
 
 #### 🚀 Features

package/README.md

@@ -50,14 +50,16 @@ the two main phases of the frame update:
 
 In other words, this means any updatable state value will require 3 versions:
 previous, current (next), interpolated. **Only the interpolated version is to be
-used for rendering (or other outside purposes).** For that reason, the package
+used for rendering (or other userland purposes).** For that reason, the package
 also provides wrappers for
 [numeric](https://docs.thi.ng/umbrella/timestep/functions/defNumeric.html) and
 [vector-based](https://docs.thi.ng/umbrella/timestep/functions/defVector.html)
-state variables, illustrated in the following short example:
+(arbitrary length and optimized 2D/3D/4D versions) state variables, illustrated
+in the following short example:
 
 ```ts tangle:export/readme.ts
-import { defTimeStep, defNumeric, defVector } from "@thi.ng/timestep";
+import { defTimeStep, defNumeric, defVector2 } from "@thi.ng/timestep";
+import { maddN2 } from "@thi.ng/vectors";
 
 // initialize with default options (i.e. dt = 1/60 = 60 fps)
 // start time is given in milliseconds but will be converted to seconds
@@ -67,9 +69,10 @@ const sim = defTimeStep({ dt: 1 / 60, startTime: Date.now() });
 // define numeric state variable, increase using @ 10 units per second
 const a = defNumeric(0, (x, dt) => x + dt * 10);
 
-// define vector state variable, update using velocity of [-10, 20] (per second)
-// also see thi.ng/vectors for hundreds of useful vector operations to simplify...
-const b = defVector([0, 0], (x, dt) => [x[0] - 10 * dt, x[1] + 20 * dt]);
+// define vector state variable, update by applying velocity of [-10, 20] (per second)
+// also see thi.ng/vectors for hundreds of other useful vector operations...
+// the update function MUST write its result in given vector (1st arg)
+const b = defVector2([0, 0], (v, dt) => maddN2(v, [-10, 20], dt, v));
 
 // even though the sim will update at a fixed (theoretical) 60 fps,
 // the simulated render frame rate here is only 25 fps...
@@ -148,7 +151,7 @@ For Node.js REPL:
 const timestep = await import("@thi.ng/timestep");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 758 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 817 bytes
 
 ## Dependencies
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/timestep",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Deterministic fixed timestep simulation updates with state interpolation",
   "type": "module",
   "module": "./index.js",
@@ -88,5 +88,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "a6a6217de89c2875aa78c516d3b5de11ee444834\n"
+  "gitHead": "db8b3ed2ab79e513d378a465a6d8cacf3243b052\n"
 }

package/state.d.ts

@@ -1,31 +1,41 @@
 import type { IDeref } from "@thi.ng/api";
-import type { ReadonlyVec } from "@thi.ng/vectors";
-import type { ITimeStep, ReadonlyTimeStep, StateInterpolation, StateUpdate } from "./api.js";
-/**
- * Abstract base class for simulation state wrappers.
- *
- * @remarks
- * See {@link defNumeric} and {@link defVector}.
- */
-export declare abstract class AState<T> implements IDeref<T>, ITimeStep {
-    value: T;
-    update: StateUpdate<T>;
-    mix: StateInterpolation<T>;
-    curr: T;
-    prev: T;
-    constructor(value: T, update: StateUpdate<T>, mix: StateInterpolation<T>);
-    deref(): T;
-    integrate(dt: number, ctx: ReadonlyTimeStep): void;
-    interpolate(alpha: number, ctx: ReadonlyTimeStep): void;
-    abstract reset(value: T): void;
-}
-export declare class NumericState extends AState<number> {
-    constructor(x: number, update: StateUpdate<number>);
+import type { ReadonlyVec, Vec, VecOpV, VecOpVVN } from "@thi.ng/vectors";
+import type { ITimeStep, ReadonlyTimeStep, StateUpdate } from "./api.js";
+export declare class NumericState implements IDeref<number>, ITimeStep {
+    value: number;
+    update: StateUpdate<number>;
+    curr: number;
+    prev: number;
+    constructor(value: number, update: StateUpdate<number>);
+    deref(): number;
+    /**
+     * Sets {@link NumericState.prev}, {@link NumericState.curr} and
+     * {@link NumericState.value} to given new value.
+     *
+     * @param value
+     */
     reset(value: number): void;
+    integrate(dt: number, ctx: ReadonlyTimeStep): void;
+    interpolate(alpha: number): void;
 }
-export declare class VectorState extends AState<ReadonlyVec> {
-    constructor(x: ReadonlyVec, update: StateUpdate<ReadonlyVec>);
+export declare class VectorState implements IDeref<ReadonlyVec>, ITimeStep {
+    value: Vec;
+    setFn: VecOpV;
+    mixFn: VecOpVVN;
+    update: StateUpdate<ReadonlyVec>;
+    prev: Vec;
+    curr: Vec;
+    constructor(value: Vec, setFn: VecOpV, mixFn: VecOpVVN, update: StateUpdate<ReadonlyVec>);
+    deref(): ReadonlyVec;
+    /**
+     * Copies given vector to {@link VectorState.prev}, {@link VectorState.curr}
+     * and {@link VectorState.value}.
+     *
+     * @param value
+     */
     reset(value: ReadonlyVec): void;
+    integrate(dt: number, ctx: ReadonlyTimeStep): void;
+    interpolate(alpha: number): void;
 }
 /**
  * Returns a new {@link NumericState} wrapper for given value `x` and its update
@@ -36,15 +46,38 @@ export declare class VectorState extends AState<ReadonlyVec> {
  */
 export declare const defNumeric: (x: number, update: StateUpdate<number>) => NumericState;
 /**
- * Returns a new {@link VectorState} wrapper for given vector `v` and its update
- * function for use with {@link TimeStep.update}.
+ * Returns a new {@link VectorState} wrapper for given vector `v` (arbitrary
+ * length) and its update function for use with {@link TimeStep.update}.
  *
  * @remarks
- * **IMPORTANT:** The `update` function MUST return a new vector and not mutate
- * the existing one!
+ * **IMPORTANT:** The `update` function MUST manipulate the vector received as
+ * 1st arg (which is {@link VectorState.curr}).
+ *
+ * Also see {@link defVector2}, {@link defVector3}, {@link defVector4}.
  *
  * @param x
  * @param update
  */
 export declare const defVector: (v: ReadonlyVec, update: StateUpdate<ReadonlyVec>) => VectorState;
+/**
+ * 2D optimized version of {@link defVector}.
+ *
+ * @param v
+ * @param update
+ */
+export declare const defVector2: (v: ReadonlyVec, update: StateUpdate<ReadonlyVec>) => VectorState;
+/**
+ * 3D optimized version of {@link defVector}.
+ *
+ * @param v
+ * @param update
+ */
+export declare const defVector3: (v: ReadonlyVec, update: StateUpdate<ReadonlyVec>) => VectorState;
+/**
+ * 4D optimized version of {@link defVector}.
+ *
+ * @param v
+ * @param update
+ */
+export declare const defVector4: (v: ReadonlyVec, update: StateUpdate<ReadonlyVec>) => VectorState;
 //# sourceMappingURL=state.d.ts.map

package/state.js

@@ -1,47 +1,63 @@
 import { mix } from "@thi.ng/math/mix";
-import { mixN } from "@thi.ng/vectors/mixn";
-import { set } from "@thi.ng/vectors/set";
-/**
- * Abstract base class for simulation state wrappers.
- *
- * @remarks
- * See {@link defNumeric} and {@link defVector}.
- */
-export class AState {
-    constructor(value, update, mix) {
+import { mixN, mixN2, mixN3, mixN4 } from "@thi.ng/vectors/mixn";
+import { set, set2, set3, set4 } from "@thi.ng/vectors/set";
+export class NumericState {
+    constructor(value, update) {
         this.value = value;
         this.update = update;
-        this.mix = mix;
-        this.prev = this.curr = value;
+        this.reset(value);
     }
     deref() {
         return this.value;
     }
+    /**
+     * Sets {@link NumericState.prev}, {@link NumericState.curr} and
+     * {@link NumericState.value} to given new value.
+     *
+     * @param value
+     */
+    reset(value) {
+        this.prev = this.curr = this.value = value;
+    }
     integrate(dt, ctx) {
         this.prev = this.curr;
         this.curr = this.update(this.curr, dt, ctx);
     }
-    interpolate(alpha, ctx) {
-        this.value = this.mix(this.prev, this.curr, alpha, ctx);
+    interpolate(alpha) {
+        this.value = mix(this.prev, this.curr, alpha);
     }
 }
-export class NumericState extends AState {
-    constructor(x, update) {
-        super(x, update, mix);
-    }
-    reset(value) {
-        this.prev = this.curr = this.value = value;
+export class VectorState {
+    constructor(value, setFn, mixFn, update) {
+        this.value = value;
+        this.setFn = setFn;
+        this.mixFn = mixFn;
+        this.update = update;
+        this.prev = [...value];
+        this.curr = [...value];
     }
-}
-export class VectorState extends AState {
-    constructor(x, update) {
-        super(x, update, (a, b, t) => mixN([], a, b, t));
+    deref() {
+        return this.value;
     }
+    /**
+     * Copies given vector to {@link VectorState.prev}, {@link VectorState.curr}
+     * and {@link VectorState.value}.
+     *
+     * @param value
+     */
     reset(value) {
+        const set = this.setFn;
         set(this.prev, value);
         set(this.curr, value);
         set(this.value, value);
     }
+    integrate(dt, ctx) {
+        this.setFn(this.prev, this.curr);
+        this.update(this.curr, dt, ctx);
+    }
+    interpolate(alpha) {
+        this.mixFn(this.value, this.prev, this.curr, alpha);
+    }
 }
 /**
  * Returns a new {@link NumericState} wrapper for given value `x` and its update
@@ -52,14 +68,37 @@ export class VectorState extends AState {
  */
 export const defNumeric = (x, update) => new NumericState(x, update);
 /**
- * Returns a new {@link VectorState} wrapper for given vector `v` and its update
- * function for use with {@link TimeStep.update}.
+ * Returns a new {@link VectorState} wrapper for given vector `v` (arbitrary
+ * length) and its update function for use with {@link TimeStep.update}.
  *
  * @remarks
- * **IMPORTANT:** The `update` function MUST return a new vector and not mutate
- * the existing one!
+ * **IMPORTANT:** The `update` function MUST manipulate the vector received as
+ * 1st arg (which is {@link VectorState.curr}).
+ *
+ * Also see {@link defVector2}, {@link defVector3}, {@link defVector4}.
  *
  * @param x
  * @param update
  */
-export const defVector = (v, update) => new VectorState(v, update);
+export const defVector = (v, update) => new VectorState(v, set, mixN, update);
+/**
+ * 2D optimized version of {@link defVector}.
+ *
+ * @param v
+ * @param update
+ */
+export const defVector2 = (v, update) => new VectorState(v, set2, mixN2, update);
+/**
+ * 3D optimized version of {@link defVector}.
+ *
+ * @param v
+ * @param update
+ */
+export const defVector3 = (v, update) => new VectorState(v, set3, mixN3, update);
+/**
+ * 4D optimized version of {@link defVector}.
+ *
+ * @param v
+ * @param update
+ */
+export const defVector4 = (v, update) => new VectorState(v, set4, mixN4, update);