Merge pull request #3 from neefrehman/chore/refactor-1

feature: self-aware vector population

Author: neefrehman

.prettierrc

@@ -1,9 +1,9 @@
 {
-  "printWidth": 80,
-  "tabWidth": 4,
-  "singleQuote": false,
-  "trailingComma": "none",
-  "bracketSpacing": true,
-  "arrowParens": "avoid",
-  "semi": true
+    "printWidth": 82,
+    "tabWidth": 4,
+    "singleQuote": false,
+    "trailingComma": "none",
+    "bracketSpacing": true,
+    "arrowParens": "avoid",
+    "semi": true
 }

.vscode/settings.json

@@ -72,11 +72,24 @@ const threeDimensionalStringArray = makeMatrix([2, 6, 5], "value");
 
 ### Pass a callback for dynamic initial values
 
-The `initialValues` parameter also accepts a callback, which you can use to dynamically create items for each position in the matrix.
+The `initialValues` parameter can also be a callback, which you can use to dynamically create items for each position in the matrix. The callback can accept an argument which will resolve to the current vector co-ordinates at each point in the matrix. This can allow you to populate your matrix in a "self-aware" way.
 
 ```js
-// create a 10x10x10 array, with each point a different random number between one and 10
+// create a 10x10x10 array, with each point a different random number between one and 9
 const twoDRandomNumberArray = makeMatrix([10, 10, 10], () => Math.floor(Math.random() * 10));
+
+// create a 5x5 array, with each point self described by a string
+const twoDRandomNumberArray = makeMatrix([5, 5], (vector) => vector.join());
+
+// create a 7x3,8 array, with each point transformed into a vector object
+const twoDRandomNumberArray = makeMatrix([7, 3, 8], (vector) => {
+    return {
+        x: vector.x,
+        y: vector.y,
+        z: vector.z,
+        otherData: OTHER_DATA
+    }
+});
 ```
 
 ## With TypeScript
@@ -85,7 +98,7 @@ This package comes with type definitions to provide type-safety when working wit
 
 Up to and including four dimensions, returned arrays will be given a specific type dictated by `T` and the number of dimensions, where `T` is the type of the value passed to the functions `initialValues` parameter (or `unknown` if not set).
 
-For example, a three-dimensional array of numbers will be of type `number[][][]`. Points within the matrix can then only be reassigned to numbers. TypeScript's compiler will present errors when any reassignments are of the wrong type, including if they are at an incorrect depth in the array.
+For example, a three-dimensional array of numbers will be of type `number[][][]`. Points within the matrix can then only be reassigned to numbers. TypeScript's compiler will present errors when any reassignments are of the wrong type, including if they are at an incorrect depth in the array. This type-safety also exists when callbacks are used to dynamically populate your matrix.
 
 ```ts
 const threeDNumberArray = makeMatrix([2, 6, 5], 0); // return type of number[][][]
@@ -104,7 +117,7 @@ Above four dimensions, the returned array will have the generic type `Matrix<T>`
 For more type-safety at these levels of dimensionality, it is recomended that you add more specific type annotations to your variables:
 
 ```ts
-const sixDimensionalNumberArray: number[][][][][][] = makeMatrix(6, 0);
+const sixDimensionalNumberArray: string[][][][][][] = makeMatrix(6, "this is deep");
 ```
 
 ## Example
@@ -133,9 +146,9 @@ for (let x = 0; x < matrix.length; x += res) {
 makeMatrix(dimensions, initialValues);
 
 // With types
-makeMatrix<T>(
+makeMatrix<D, T>(
     dimensions: number | number[],
-    initialValues?: T | (() => T)
+    initialValues?: (vector: VectorOfLength<D>) => T
 ): Matrix<T>;
 ```
 

README.md

@@ -0,0 +1,106 @@
+import makeMatrix from "../index";
+
+// Test arrays of specific dimensions, with callbacks returning "self aware" initialised values
+test("vector callback test - straight", () => {
+    expect(makeMatrix([2, 2, 2], vector => vector)).toStrictEqual([
+        [
+            [
+                [0, 0, 0],
+                [0, 0, 1]
+            ],
+            [
+                [0, 1, 0],
+                [0, 1, 1]
+            ]
+        ],
+        [
+            [
+                [1, 0, 0],
+                [1, 0, 1]
+            ],
+            [
+                [1, 1, 0],
+                [1, 1, 1]
+            ]
+        ]
+    ]);
+});
+
+test("vector callback test - joined", () => {
+    expect(
+        makeMatrix([2, 2, 2, 1], vector => `my position is ${vector.join()}`)
+    ).toStrictEqual([
+        [
+            [["my position is 0,0,0,0"], ["my position is 0,0,1,0"]],
+            [["my position is 0,1,0,0"], ["my position is 0,1,1,0"]]
+        ],
+        [
+            [["my position is 1,0,0,0"], ["my position is 1,0,1,0"]],
+            [["my position is 1,1,0,0"], ["my position is 1,1,1,0"]]
+        ]
+    ]);
+});
+
+test("vector callback test - joined", () => {
+    expect(
+        makeMatrix([3, 3, 3], ([x, y, z]) => {
+            return {
+                x,
+                y,
+                z
+            };
+        })
+    ).toStrictEqual([
+        [
+            [
+                { x: 0, y: 0, z: 0 },
+                { x: 0, y: 0, z: 1 },
+                { x: 0, y: 0, z: 2 }
+            ],
+            [
+                { x: 0, y: 1, z: 0 },
+                { x: 0, y: 1, z: 1 },
+                { x: 0, y: 1, z: 2 }
+            ],
+            [
+                { x: 0, y: 2, z: 0 },
+                { x: 0, y: 2, z: 1 },
+                { x: 0, y: 2, z: 2 }
+            ]
+        ],
+        [
+            [
+                { x: 1, y: 0, z: 0 },
+                { x: 1, y: 0, z: 1 },
+                { x: 1, y: 0, z: 2 }
+            ],
+            [
+                { x: 1, y: 1, z: 0 },
+                { x: 1, y: 1, z: 1 },
+                { x: 1, y: 1, z: 2 }
+            ],
+            [
+                { x: 1, y: 2, z: 0 },
+                { x: 1, y: 2, z: 1 },
+                { x: 1, y: 2, z: 2 }
+            ]
+        ],
+        [
+            [
+                { x: 2, y: 0, z: 0 },
+                { x: 2, y: 0, z: 1 },
+                { x: 2, y: 0, z: 2 }
+            ],
+            [
+                { x: 2, y: 1, z: 0 },
+                { x: 2, y: 1, z: 1 },
+                { x: 2, y: 1, z: 2 }
+            ],
+            [
+                { x: 2, y: 2, z: 0 },
+                { x: 2, y: 2, z: 1 },
+                { x: 2, y: 2, z: 2 }
+            ]
+        ]
+    ]);
+});

src/__tests__/callback-vector.test.ts

@@ -4,7 +4,3 @@ import makeMatrix from "../index";
 test("Array error test - When non-integer is used", () => {
     expect(() => makeMatrix([1, 0.2, 3])).toThrow(TypeError);
 });
-
-test("Number error test - When non-integer is used", () => {
-    expect(() => makeMatrix(0.2)).toThrow(TypeError);
-});

src/__tests__/non-integer-error.test.ts

@@ -1,17 +1,4 @@
-/**
- * A multidimensional array returned by `makeMatrix` for over four dimensions.
- */
-export type Matrix<T> = T[][][][][] | Matrix<T>[];
-
-/**
- * Provides type safety for values as well as functions that return values
- * for `createMatrix`'s `initialValues` parameter.
- */
-type ValueOrFunction<T> = T extends boolean
-    ? boolean | (() => boolean) // To solve boolean expanding: https://github.com/microsoft/TypeScript/issues/30029
-    : T extends any // from: https://github.com/microsoft/TypeScript/issues/37663
-    ? T | (() => T)
-    : never;
+import type { Matrix, ValueOrFunction, Vector } from "./types";
 
 /**
  * Returns a matrix (multi-dimensional array) with your desired dimensions and
@@ -36,68 +23,82 @@ type ValueOrFunction<T> = T extends boolean
  *
  * const twoDRandomNumberArray = makeMatrix([1, 4], () => Math.random()); // A 1x4 array initialised with random numbers
  */
-function makeMatrix<T>(
+function makeMatrix<D extends number, T>(
     dimensions: 1 | [number],
-    initialValues?: ValueOrFunction<T> | null
+    initialValues?: ValueOrFunction<D, T>
 ): T[];
 
-function makeMatrix<T>(
+function makeMatrix<D extends number, T>(
     dimensions: 2 | [number, number],
-    initialValues?: ValueOrFunction<T> | null
+    initialValues?: ValueOrFunction<D, T>
 ): T[][];
 
-function makeMatrix<T>(
+function makeMatrix<D extends number, T>(
     dimensions: 3 | [number, number, number],
-    initialValues?: ValueOrFunction<T> | null
+    initialValues?: ValueOrFunction<D, T>
 ): T[][][];
 
-function makeMatrix<T>(
+function makeMatrix<D extends number, T>(
     dimensions: 4 | [number, number, number, number],
-    initialValues?: ValueOrFunction<T> | null
+    initialValues?: ValueOrFunction<D, T>
 ): T[][][][];
 
-function makeMatrix<T>(
+function makeMatrix<D extends number, T>(
     dimensions: number | number[],
-    initialValues?: ValueOrFunction<T> | null
+    initialValues?: ValueOrFunction<D, T>
 ): Matrix<T>;
 
-function makeMatrix<T>(
+function makeMatrix<D extends number, T>(
     dimensions: number | number[],
-    initialValues: ValueOrFunction<T> | null = null
+    initialValues: ValueOrFunction<D, T> = null
+): Matrix<T> {
+    const dimensionCount =
+        typeof dimensions === "number" ? dimensions : dimensions.length;
+    const intialPosition = Array(dimensionCount).fill(0) as Vector<D>;
+
+    return _makeMatrix(dimensions, initialValues, intialPosition) as Matrix<T>;
+}
+
+function _makeMatrix<D extends number, T>(
+    dimensions: number | number[],
+    initialValues: ValueOrFunction<D, T> = null,
+    currentPosition: Vector<D>
 ): Matrix<T> {
     let currentDimensionLength: number;
-    let remainingDimensions: number | number[];
+    let remainingDimensions: number | Vector;
+    let remainingDimensionCount: number;
     let needsRecursion: boolean;
 
     if (typeof dimensions === "number") {
         currentDimensionLength = dimensions;
         remainingDimensions = dimensions - 1;
+        remainingDimensionCount = remainingDimensions;
         needsRecursion = remainingDimensions > 0;
     } else {
         currentDimensionLength = dimensions[0];
         remainingDimensions = dimensions.slice(1);
+        remainingDimensionCount = remainingDimensions.length;
         needsRecursion = remainingDimensions.length > 0;
     }
 
     if (!Number.isInteger(currentDimensionLength)) {
         throw new TypeError(`Dimensions must be integers`);
     }
 
-    // Spread operator used as as constructed array's can't be mapped:
-    // https://itnext.io/heres-why-mapping-a-constructed-array-doesn-t-work-in-javascript-f1195138615a
-    const currentMatrix = [...Array(currentDimensionLength)];
+    const currentDimension = currentPosition.length - 1 - remainingDimensionCount;
 
-    const finalMatrix = needsRecursion
-        ? currentMatrix.map(() =>
-              makeMatrix(remainingDimensions, initialValues)
-          )
-        : currentMatrix.map(() => {
-              return typeof initialValues === "function"
-                  ? initialValues()
-                  : initialValues;
-          });
+    const finalMatrix = [...Array(currentDimensionLength)].map((_, i) => {
+        currentPosition[currentDimension] = i;
+        return needsRecursion
+            ? _makeMatrix(remainingDimensions, initialValues, currentPosition)
+            : typeof initialValues === "function" // @ts-expect-error: "expression is not callable" https://github.com/microsoft/TypeScript/issues/37663
+            ? initialValues(currentPosition.slice())
+            : initialValues;
+    });
 
-    return finalMatrix;
+    return finalMatrix as Matrix<T>;
 }
 
 export default makeMatrix;
+
+export type { Matrix };