@naturalcycles/js-lib 14.72.0 → 14.73.0

package/dist/math/stack.util.d.ts

@@ -1,9 +1,11 @@
 /**
- * Implements a "round-robin" Stack with a limited size.
+ * Implements a "round-robin" Stack ("first-in last-out" aka FILO) with a limited size.
  * Like an array of a fixed size. When it runs out of space - it starts writing on top of itself
  * from index 0.
+ *
+ *
  */
-export declare class SizeLimitedStack<T> {
+export declare class Stack<T> {
     readonly size: number;
     constructor(size: number);
     /**
@@ -12,10 +14,36 @@ export declare class SizeLimitedStack<T> {
      */
     private nextIndex;
     readonly items: T[];
-    push(item: T): void;
+    push(item: T): this;
+    /**
+     * Fill (overwrite) the whole Stack (all its items) with the passed `item`.
+     */
+    fill(item: T): this;
     /**
      * Returns last items in the right order.
      * Unlike raw `items` property that returns "items buffer" as-is (not ordered properly).
      */
     get itemsOrdered(): T[];
 }
+/**
+ * Fixed-size FILO stack of Numbers.
+ * Has convenience stat methods, e.g percentile, avg, etc.
+ */
+export declare class NumberStack extends Stack<number> {
+    avg(): number;
+    /**
+     * Returns null if Stack is empty.
+     */
+    avgOrNull(): number | null;
+    /**
+     * `pc` is a number from 0 to 100 inclusive.
+     */
+    percentile(pc: number): number;
+    /**
+     * `pc` is a number from 0 to 100 inclusive.
+     * Returns null if Stack is empty.
+     */
+    percentileOrNull(pc: number): number | null;
+    median(): number;
+    medianOrNull(): number | null;
+}

package/dist/math/stack.util.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SizeLimitedStack = void 0;
+exports.NumberStack = exports.Stack = void 0;
+const index_1 = require("../index");
 /**
- * Implements a "round-robin" Stack with a limited size.
+ * Implements a "round-robin" Stack ("first-in last-out" aka FILO) with a limited size.
  * Like an array of a fixed size. When it runs out of space - it starts writing on top of itself
  * from index 0.
+ *
+ *
  */
-class SizeLimitedStack {
+class Stack {
     constructor(size) {
         this.size = size;
         /**
@@ -19,6 +22,14 @@ class SizeLimitedStack {
     push(item) {
         this.items[this.nextIndex] = item;
         this.nextIndex = this.nextIndex === this.size - 1 ? 0 : this.nextIndex + 1;
+        return this;
+    }
+    /**
+     * Fill (overwrite) the whole Stack (all its items) with the passed `item`.
+     */
+    fill(item) {
+        (0, index_1._range)(this.size).forEach(i => (this.items[i] = item));
+        return this;
     }
     /**
      * Returns last items in the right order.
@@ -33,4 +44,41 @@ class SizeLimitedStack {
         return [...this.items.slice(this.nextIndex), ...this.items.slice(0, this.nextIndex)];
     }
 }
-exports.SizeLimitedStack = SizeLimitedStack;
+exports.Stack = Stack;
+/**
+ * Fixed-size FILO stack of Numbers.
+ * Has convenience stat methods, e.g percentile, avg, etc.
+ */
+class NumberStack extends Stack {
+    avg() {
+        // _assert(this.items.length, 'NumberStack.avg cannot be called on empty stack')
+        return (0, index_1._average)(this.items);
+    }
+    /**
+     * Returns null if Stack is empty.
+     */
+    avgOrNull() {
+        return this.items.length === 0 ? null : (0, index_1._average)(this.items);
+    }
+    /**
+     * `pc` is a number from 0 to 100 inclusive.
+     */
+    percentile(pc) {
+        // _assert(this.items.length, 'NumberStack.percentile cannot be called on empty stack')
+        return (0, index_1._percentile)(this.items, pc);
+    }
+    /**
+     * `pc` is a number from 0 to 100 inclusive.
+     * Returns null if Stack is empty.
+     */
+    percentileOrNull(pc) {
+        return this.items.length === 0 ? null : (0, index_1._percentile)(this.items, pc);
+    }
+    median() {
+        return (0, index_1._percentile)(this.items, 50);
+    }
+    medianOrNull() {
+        return this.items.length === 0 ? null : (0, index_1._percentile)(this.items, 50);
+    }
+}
+exports.NumberStack = NumberStack;

package/dist/number/number.util.d.ts

@@ -44,7 +44,7 @@ export declare function _toFixed(n: number, fractionDigits: number): number;
  * _toPrecision(1634.56, 1)
  * // 2000
  *
- * _toPrecision(1234.56, 2)
+ * _toPrecision(1634.56, 2)
  * // 1600
  */
 export declare function _toPrecision(n: number, precision: number): number;

package/dist/number/number.util.js

@@ -67,7 +67,7 @@ exports._toFixed = _toFixed;
  * _toPrecision(1634.56, 1)
  * // 2000
  *
- * _toPrecision(1234.56, 2)
+ * _toPrecision(1634.56, 2)
  * // 1600
  */
 function _toPrecision(n, precision) {

package/dist-esm/math/stack.util.js

@@ -1,9 +1,12 @@
+import { _average, _percentile, _range } from '../index';
 /**
- * Implements a "round-robin" Stack with a limited size.
+ * Implements a "round-robin" Stack ("first-in last-out" aka FILO) with a limited size.
  * Like an array of a fixed size. When it runs out of space - it starts writing on top of itself
  * from index 0.
+ *
+ *
  */
-export class SizeLimitedStack {
+export class Stack {
     constructor(size) {
         this.size = size;
         /**
@@ -16,6 +19,14 @@ export class SizeLimitedStack {
     push(item) {
         this.items[this.nextIndex] = item;
         this.nextIndex = this.nextIndex === this.size - 1 ? 0 : this.nextIndex + 1;
+        return this;
+    }
+    /**
+     * Fill (overwrite) the whole Stack (all its items) with the passed `item`.
+     */
+    fill(item) {
+        _range(this.size).forEach(i => (this.items[i] = item));
+        return this;
     }
     /**
      * Returns last items in the right order.
@@ -30,3 +41,39 @@ export class SizeLimitedStack {
         return [...this.items.slice(this.nextIndex), ...this.items.slice(0, this.nextIndex)];
     }
 }
+/**
+ * Fixed-size FILO stack of Numbers.
+ * Has convenience stat methods, e.g percentile, avg, etc.
+ */
+export class NumberStack extends Stack {
+    avg() {
+        // _assert(this.items.length, 'NumberStack.avg cannot be called on empty stack')
+        return _average(this.items);
+    }
+    /**
+     * Returns null if Stack is empty.
+     */
+    avgOrNull() {
+        return this.items.length === 0 ? null : _average(this.items);
+    }
+    /**
+     * `pc` is a number from 0 to 100 inclusive.
+     */
+    percentile(pc) {
+        // _assert(this.items.length, 'NumberStack.percentile cannot be called on empty stack')
+        return _percentile(this.items, pc);
+    }
+    /**
+     * `pc` is a number from 0 to 100 inclusive.
+     * Returns null if Stack is empty.
+     */
+    percentileOrNull(pc) {
+        return this.items.length === 0 ? null : _percentile(this.items, pc);
+    }
+    median() {
+        return _percentile(this.items, 50);
+    }
+    medianOrNull() {
+        return this.items.length === 0 ? null : _percentile(this.items, 50);
+    }
+}

package/dist-esm/number/number.util.js

@@ -58,7 +58,7 @@ export function _toFixed(n, fractionDigits) {
  * _toPrecision(1634.56, 1)
  * // 2000
  *
- * _toPrecision(1234.56, 2)
+ * _toPrecision(1634.56, 2)
  * // 1600
  */
 export function _toPrecision(n, precision) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.72.0",
+  "version": "14.73.0",
   "scripts": {
     "prepare": "husky install",
     "build-prod": "build-prod-esm-cjs",

package/src/math/stack.util.ts

@@ -1,9 +1,13 @@
+import { _average, _percentile, _range } from '../index'
+
 /**
- * Implements a "round-robin" Stack with a limited size.
+ * Implements a "round-robin" Stack ("first-in last-out" aka FILO) with a limited size.
  * Like an array of a fixed size. When it runs out of space - it starts writing on top of itself
  * from index 0.
+ *
+ *
  */
-export class SizeLimitedStack<T> {
+export class Stack<T> {
   constructor(public readonly size: number) {}
 
   /**
@@ -14,9 +18,18 @@ export class SizeLimitedStack<T> {
 
   readonly items: T[] = []
 
-  push(item: T): void {
+  push(item: T): this {
     this.items[this.nextIndex] = item
     this.nextIndex = this.nextIndex === this.size - 1 ? 0 : this.nextIndex + 1
+    return this
+  }
+
+  /**
+   * Fill (overwrite) the whole Stack (all its items) with the passed `item`.
+   */
+  fill(item: T): this {
+    _range(this.size).forEach(i => (this.items[i] = item))
+    return this
   }
 
   /**
@@ -33,3 +46,45 @@ export class SizeLimitedStack<T> {
     return [...this.items.slice(this.nextIndex), ...this.items.slice(0, this.nextIndex)]
   }
 }
+
+/**
+ * Fixed-size FILO stack of Numbers.
+ * Has convenience stat methods, e.g percentile, avg, etc.
+ */
+export class NumberStack extends Stack<number> {
+  avg(): number {
+    // _assert(this.items.length, 'NumberStack.avg cannot be called on empty stack')
+    return _average(this.items)
+  }
+
+  /**
+   * Returns null if Stack is empty.
+   */
+  avgOrNull(): number | null {
+    return this.items.length === 0 ? null : _average(this.items)
+  }
+
+  /**
+   * `pc` is a number from 0 to 100 inclusive.
+   */
+  percentile(pc: number): number {
+    // _assert(this.items.length, 'NumberStack.percentile cannot be called on empty stack')
+    return _percentile(this.items, pc)
+  }
+
+  /**
+   * `pc` is a number from 0 to 100 inclusive.
+   * Returns null if Stack is empty.
+   */
+  percentileOrNull(pc: number): number | null {
+    return this.items.length === 0 ? null : _percentile(this.items, pc)
+  }
+
+  median(): number {
+    return _percentile(this.items, 50)
+  }
+
+  medianOrNull(): number | null {
+    return this.items.length === 0 ? null : _percentile(this.items, 50)
+  }
+}

package/src/number/number.util.ts

@@ -65,7 +65,7 @@ export function _toFixed(n: number, fractionDigits: number): number {
  * _toPrecision(1634.56, 1)
  * // 2000
  *
- * _toPrecision(1234.56, 2)
+ * _toPrecision(1634.56, 2)
  * // 1600
  */
 export function _toPrecision(n: number, precision: number): number {