flocc 0.5.18 → 0.5.21

package/dist/utils/gaussian.d.ts

@@ -1,9 +1,15 @@
 /**
  * Given a mean and standard deviation,
  * returns a value from a normal/Gaussian distribution.
- * @param {number} mean
- * @param {number} sd
- * @returns {number}
+ *
+ * ```js
+ * // returns values mostly between 5 and 15 (but sometimes lower or higher)
+ * gaussian(10, 5);
+ *
+ * // no parameters defaults to mean = 0, std. dev. = 1
+ * gaussian(); // mostly values between -1 and 1
+ * ```
+ *
  * @since 0.0.8
  */
 export default function gaussian(mean?: number, sd?: number): number;

package/dist/utils/gcd.d.ts

@@ -1,4 +1,12 @@
 /**
+ * Finds the {@link https://en.wikipedia.org/wiki/Greatest_common_divisor | greatest common divisor} of `a` and `b`.
+ *
+ * ```js
+ * gcd(7, 13); // returns 1
+ * gcd(9, 15); // returns 3
+ * gcd(12, 24); // returns 12
+ * ```
+ *
  * @since 0.4.5
  */
 export default function gcd(a: number, b: number): number;

package/dist/utils/internal/copyArray.d.ts

@@ -2,7 +2,7 @@
  * Copies the values of `source` to `arr`
  * or to a new Array.
  *
- * @private
+ * @hidden
  * @param {Array} source The Array to copy values from.
  * @param {Array} [arr=[]] The Array to copy values to.
  * @returns {Array}

package/dist/utils/lerp.d.ts

@@ -1,8 +1,17 @@
 /**
- * Linearly interpolate between two values.
- * @param x {number} - The first value.
- * @param y {number} - The second value.
- * @param t {number} - The amount by which to interpolate (0 returns x, 1 returns y).
+ * Linearly interpolates between `x` and `y`. The third parameter `t` (usually
+ * a value between `0` and `1`) is the amount by which to interpolate — a value of `0`
+ * returns the `x` value and `1` returns the `y` value.
+ *
+ * ```js
+ * lerp(5, 10, 0.5); // returns 7.5
+ * lerp(0, 100, 0.1); // returns 10
+ * lerp(22, 79, 1); // returns 79
+ * ```
+ *
+ * @param x The first value.
+ * @param y The second value.
+ * @param t The amount by which to interpolate (0 returns x, 1 returns y).
  * @since 0.2.4
  */
 export default function lerp(x: number, y: number, t: number): number;

package/dist/utils/manhattanDistance.d.ts

@@ -1,13 +1,21 @@
 /// <reference path="../src/types/Point.d.ts" />
 import { Agent } from "../agents/Agent";
 /**
- * Finds the Manhattan distance between `p1` and `p2`.
- * The inputs may be plain objects
- * with `x`, `y`, and/or `z` keys, or Agent-like objects who have
- * `x`, `y`, and/or `z` data.
- * @param {Point|Agent} p1
- * @param {Point|Agent} p2
- * @return {number} The Manhattan distance between p1 and p2.
+ * Finds the {@link https://en.wikipedia.org/wiki/Taxicab_geometry | Manhattan distance} between `p1` and `p2`.
+ *
+ * The inputs may be plain objects with `x`, `y`, and/or `z` keys, {@linkcode Vector}s,
+ * or {@linkcode Agent}s with `x`, `y`, and/or `z` data.
+ *
+ * ```js
+ * const a1 = new Agent();
+ * const a2 = new Agent({ x: 3, y: 4 });
+ * manhattanDistance(a1, a2); // returns 7 (defaults to x = 0 and y = 0 for a1)
+ *
+ * const p1 = { x: 3, y: 2 };
+ * const p2 = { x: 0, y: 4 };
+ * manhattanDistance(p1, p2); // returns 5
+ * ```
+ *
  * @since 0.0.12
  */
 export default function manhattanDistance(p1: Point | Agent, p2: Point | Agent): number;

package/dist/utils/max.d.ts

@@ -1,4 +1,13 @@
 /**
+ * Return the maximum value from an array of numbers.
+ *
+ * ```js
+ * max([1, 2, 3]); // returns 3
+ * max([10]); // returns 10
+ *
+ * max([]); // returns null for empty arrays
+ * ```
+ *
  * @since 0.2.0
  */
 export default function max(arr: Array<number>): number;

package/dist/utils/mean.d.ts

@@ -1,7 +1,13 @@
 /**
- * Find the mean value of an Array of numbers.
- * @param {Array<number>} arr
- * @returns {number}
+ * Return the mean value from an array of numbers.
+ *
+ * ```js
+ * mean([1, 2, 3]); // returns 2
+ * mean([10]); // returns 10
+ *
+ * mean([]); // returns null for empty arrays
+ * ```
+ *
  * @since 0.0.16
  */
 declare function mean(arr: Array<number>): number;

package/dist/utils/median.d.ts

@@ -1,6 +1,14 @@
 /**
- * Find the median value of an array of numbers. If there are an even number
- * of elements in the array, takes the mean of the two values closest to the median.
+ * Return the mean value from an array of numbers.
+ *
+ * ```js
+ * median([1, 2, 3]); // returns 2
+ * median([10]); // returns 10
+ * median([1, 2, 3, 4]); // returns 2.5 (the mean of the two median values)
+ *
+ * median([]); // returns null for empty arrays
+ * ```
+ *
  * @param {number[]} arr
  * @since 0.2.0
  */

package/dist/utils/min.d.ts

@@ -1,4 +1,12 @@
 /**
+ * Return the minimum value from an array of numbers.
+ *
+ * ```js
+ * min([1, 2, 3]); // returns 1
+ * min([10]); // returns 10
+ *
+ * min([]); // returns null for empty arrays
+ * ```
  * @since 0.2.0
  */
 export default function min(arr: Array<number>): number;

package/dist/utils/sample.d.ts

@@ -4,6 +4,8 @@ interface SampleFunc {
 interface MultipleSampleFunc {
     <T>(array: T[], weights?: number[]): T[];
 }
+export declare function isSampleFunc(f: Function): f is SampleFunc;
+export declare function isMultipleSampleFunc(f: Function): f is MultipleSampleFunc;
 declare let sample: SampleFunc;
 export default sample;
 /**

package/dist/version.d.ts

@@ -1,2 +1,5 @@
+/**
+ * The current version of the Flocc library.
+ */
 declare const version: string;
 export default version;

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "flocc",
-  "version": "0.5.18",
+  "version": "0.5.21",
   "description": "Agent-based modeling in JavaScript in the browser or server.",
   "main": "dist/flocc.js",
   "module": "dist/flocc.es.js",
   "typings": "dist/main.d.ts",
   "scripts": {
     "build": "rollup -c && node replace-version",
+    "docs": "typedoc src/main.ts --watch --out docs/$npm_package_version",
+    "docs-build": "typedoc src/main.ts --out docs/$npm_package_version",
+    "docs-redirect": "cat _redirects > docs/_redirects && sed -i \"s/{{ VERSION }}/$npm_package_version/g\" docs/_redirects",
     "watch": "rollup -cw",
     "dev": "concurrently 'npm run watch' 'node client/app.js' 'browser-sync start --watch dist/flocc.js'",
     "format": "prettier --write src",
@@ -18,7 +21,7 @@
   "devDependencies": {
     "@rollup/plugin-json": "^4.1.0",
     "@types/node": "^14.0.19",
-    "browser-sync": "^2.26.13",
+    "browser-sync": "^2.26.14",
     "concurrently": "5.1.0",
     "ejs": "^3.0.2",
     "express": "^4.17.1",
@@ -30,7 +33,8 @@
     "puppeteer": "^2.1.1",
     "rollup": "2.1.0",
     "rollup-plugin-typescript2": "0.26.0",
-    "typescript": "3.8.3",
+    "typedoc": "^0.20.28",
+    "typescript": "4.1.3",
     "yargs": "^15.3.1"
   },
   "files": [

package/dist/helpers/Data.d.ts

@@ -1,5 +0,0 @@
-declare class Data {
-    [key: string]: any;
-    constructor();
-}
-export default Data;

package/dist/utils/internal/torusNormalize.d.ts

@@ -1 +0,0 @@
-export default function torusNormalize(value: number, max: number): number;