fix(types): fix matrix types

These have been broken for at least a year. I guess related to a TS upgrade some time in that period. This change overhauls the way we create vectors to bring back type-safety.

Author: neefrehman

package.json

@@ -59,6 +59,7 @@
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
     "@semantic-release/git": "10.0.1",
+    "@total-typescript/tsconfig": "^1.0.4",
     "@types/node": "24.3.3",
     "benny": "3.7.1",
     "commitizen": "4.3.1",
@@ -81,7 +82,7 @@
       "body-max-line-length": [
         1,
         "always",
-        100
+        200
       ]
     }
   },

pnpm-lock.yaml

@@ -1,6 +1,7 @@
-import { describe, expect, test } from "vitest";
+import { assertType, describe, expect, test } from "vitest";
 
 import { makeMatrix } from "../index";
+import type { Matrix, Vector } from "../types";
 
 const testCases = [[6], [1, 1], [3, 2, 3], [1, 4, 5, 2], [2, 4, 2, 4, 2]];
 
@@ -38,3 +39,38 @@ describe("makeMatrix", () => {
     });
   });
 });
+
+describe("types", () => {
+  test("Vector", () => {
+    assertType<Vector<[1, 1, 1, 1]>>([0, 0, 0, 0]);
+
+    // @ts-expect-error
+    assertType<Vector<[1, 1, 1, 1]>>([0, 0, 0, 0, 0]);
+    // @ts-expect-error
+    assertType<Vector<[1, 1, 1, 1]>>([0, 0, 0]);
+  });
+
+  test("Matrix", () => {
+    assertType<Matrix<[1], "test">>(["test"]);
+    assertType<Matrix<[1, 1], "test">>([["test"], ["test"]]);
+    assertType<Matrix<[1, 1], number>>([[2], [1]]);
+
+    // @ts-expect-error
+    assertType<Matrix<[1, 1], "test">>(["test", "test"]);
+  });
+
+  test("makeMatrix", () => {
+    assertType<string[][][][]>(makeMatrix([1, 1, 1, 1], "hello"));
+    assertType<number[][]>(makeMatrix([4, 5], ([a]) => a));
+    assertType<string[]>(makeMatrix([4], v => v[0]?.toString()));
+    assertType<unknown[]>(makeMatrix([] as number[]));
+
+    assertType<(0 | 1)[]>(
+      makeMatrix([1], () => (Math.random() > 0.5 ? (0 as const) : (1 as const)))
+    );
+
+    assertType<{ x: number; y: number; z: number }[][][]>(
+      makeMatrix([4, 5, 6], ([x, y, z]) => ({ x, y, z }))
+    );
+  });
+});

…tests__/__snapshots__/index.test.ts.snap …_/__snapshots__/make-matrix.test.ts.snapsrc/__tests__/__snapshots__/index.test.ts.snap renamed to src/__tests__/__snapshots__/make-matrix.test.ts.snap src/__tests__/__snapshots__/index.test.ts.snap renamed to src/__tests__/__snapshots__/make-matrix.test.ts.snap

@@ -12,29 +12,29 @@ import type { Matrix, Vector } from "./types.js";
  * const twoDRandomNumberArray = makeMatrix([1, 4], () => Math.random()); // A 1x4 array containing random numbers
  * const twoDVectorArray = makeMatrix([3, 3], vector => vector.join()); // A 3x3 array containing each point's co-ordinate as a string
  */
-const makeMatrix = <D extends number, T>(
-  dimensions: Vector<D>,
+const makeMatrix = <const D extends readonly number[], T>(
+  dimensions: D,
   initialValues: T | ((currentPosition: Vector<D>) => T) | null = null
 ): Matrix<D, T> => {
-  const initialPosition = Array(dimensions.length).fill(0) as Vector<D>;
-  return _makeMatrix(dimensions, initialValues, initialPosition);
+  const initialPosition = Array(dimensions.length).fill(0);
+  return _makeMatrix(dimensions, initialValues, initialPosition as Vector<D>);
 };
 
 /**
  * Recursively creates a matrix (depth first), and keeps track of the current position's vector.
  */
-function _makeMatrix<D extends number, T>(
-  dimensions: Vector<D>,
+function _makeMatrix<const D extends readonly number[], T>(
+  dimensions: D,
   initialValues: T | ((currentPosition: Vector<D>) => T) | null,
-  currentPosition: Vector<D>
+  currentPosition: number[]
 ): Matrix<D, T> {
   const [currentDimensionLength, ...remainingDimensions] = dimensions;
   const currentDimension = currentPosition.length - remainingDimensions.length - 1;
 
   return [...Array(currentDimensionLength)].map((_, i) => {
     currentPosition[currentDimension] = i;
     return remainingDimensions.length > 0
-      ? _makeMatrix(remainingDimensions as Vector<D>, initialValues, currentPosition)
+      ? _makeMatrix(remainingDimensions as unknown as D, initialValues, currentPosition)
       : initialValues instanceof Function
         ? initialValues(currentPosition.slice() as Vector<D>)
         : initialValues;

src/__tests__/index.test.ts src/__tests__/make-matrix.test.tssrc/__tests__/index.test.ts renamed to src/__tests__/make-matrix.test.ts

@@ -1,26 +1,33 @@
 /**
- * A typed multidimensional array returned by `makeMatrix`.
+ * Stops intellisense from expanding types and exposing their more complicated internals to users.
+ *
+ * @see {@link https://github.com/microsoft/TypeScript/issues/31940} for discussion
  */
-export type Matrix<D extends number, T = unknown> = Brand<_Matrix<D, T, []>>;
+type Brand<D> = D & {};
 
 /**
- * Recursively constructs a `Matrix` type and keeps track of the number of recursions.
+ * A typed multidimensional array.
  *
  * @remarks
- * When a `_Matrix` is created without knowing it's exact size or number of dimensions, such
+ * When a `Matrix` is created without knowing it's exact size or number of dimensions, such
  * as when creating one dynamically, it's impossible recursively construct a type for it.
  * Instead, we short circuit the type to resolve to `unknown[]`. This ensures an array of at
  * least one dimension is returned, but is unable to provide any more safety than that.
  */
-type _Matrix<
-  D extends number,
-  T = unknown,
-  RecursionCountArray extends number[] = [],
-> = number extends D
-  ? unknown[]
-  : D extends RecursionCountArray["length"]
-    ? T
-    : _Matrix<D, T[], [...RecursionCountArray, D]>;
+export type Matrix<D extends readonly number[], T = unknown> = Brand<
+  number extends D[number] ? unknown[] : BuildMatrix<D, T>
+>;
+
+/**
+ * Recursively builds a matrix type based on an array of dimensions
+ */
+type BuildMatrix<D extends readonly number[], T> = D extends readonly []
+  ? T
+  : D extends readonly [infer _First, ...infer Rest]
+    ? Rest extends readonly number[]
+      ? BuildMatrix<Rest, T>[]
+      : never
+    : unknown[];
 
 /**
  * An array of numbers with defined length, corresponding to points in a `Matrix`.
@@ -33,13 +40,15 @@ type _Matrix<
  * creating one dynamically, we short circuit the type to resolve to `number[]` so that
  * `makeMatrix` can accept a dynamically created `dimensions` parameter.
  */
-export type Vector<D extends number> = Brand<
-  number extends D ? number[] : [number, ...number[]] & { readonly length: D }
+export type Vector<D extends readonly number[]> = Brand<
+  number extends D[number] ? number[] : BuildTuple<D["length"], number>
 >;
 
 /**
- * Stops intellisense from expanding types and exposing their more complicated internals to users.
- *
- * @see {@link https://github.com/microsoft/TypeScript/issues/31940} for discussion
+ * Recursively builds a tuple of a specific length with a given type
  */
-type Brand<D> = D & {};
+type BuildTuple<
+  Length extends number,
+  T,
+  Acc extends T[] = [],
+> = Acc["length"] extends Length ? Acc : BuildTuple<Length, T, [...Acc, T]>;

src/__tests__/types.test.ts

@@ -1,26 +1,5 @@
 {
-  "$schema": "https://json.schemastore.org/tsconfig",
-  // Taken from @total-typescript/tsconfig/bundler/no-dom/library, which doesn't work well with ts-node
-  "compilerOptions": {
-    /* Base Options: */
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "target": "es2022",
-    "allowJs": true,
-    "resolveJsonModule": true,
-    "moduleDetection": "force",
-    "isolatedModules": true,
-    "verbatimModuleSyntax": true,
-    /* Strictness */
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    /* If NOT transpiling with TypeScript: */
-    "module": "preserve",
-    "noEmit": true,
-    /* If your code doesn't run in the DOM: */
-    "lib": ["es2022"]
-  },
+  "extends": "@total-typescript/tsconfig/bundler/no-dom/library",
   "include": ["src"],
-  "exclude": ["node_modules", "**/__tests__/*"]
+  "exclude": ["node_modules"]
 }