tests: Add test cases and documentation for parsers

src/api/parsers/colormap.test.ts

@@ -0,0 +1,47 @@
+import { expect, describe, it } from "vitest";
+import { parseColormapRaw } from "./colormap";
+
+describe("parseColormapRaw", () => {
+  it("should handle an empty string", () => {
+    expect(parseColormapRaw("", 2)).toEqual([]);
+  });
+
+  it("should handle 3 whitespace characters", () => {
+    expect(parseColormapRaw("  ", 2)).toEqual([]);
+  });
+
+  it("GAP: places NaN into result if given non-decimal numbers", () => {
+    expect(parseColormapRaw("9 F", 2)).toEqual([
+      [9, NaN],
+    ]);
+  });
+
+  it("GAP: does not produce an array of the correct length if not enough numbers ", () => {
+    expect(parseColormapRaw("9", 2)).toEqual([
+      [9],
+    ]);
+  });
+
+  it("should split into multiple groups", () => {
+    expect(parseColormapRaw("10 20 30 40", 2)).toEqual([
+      [10, 20],
+      [30, 40],
+    ]);
+  });
+
+  it("GAP: allows negative numbers", () => {
+    expect(parseColormapRaw("-10 2", 2)).toEqual([
+      [-10, 2],
+    ]);
+  });
+
+  it("GAP: allows numbers larger than the palette", () => {
+    expect(parseColormapRaw("400 10", 2)).toEqual([
+      [400, 10],
+    ]);
+  });
+
+  it("should not care about extra whitespace", () => {
+    expect(parseColormapRaw("  10   20 30  40  ", 4)).toEqual([[10, 20, 30, 40]]);
+  });
+});

src/api/parsers/colormap.ts

@@ -1,3 +1,11 @@
+/**
+ * Parses a string of space separated base 10 integers representing palette index values into arrays of the specified length.
+ * Example: parseColormapRaw("1 2 3 4 5 6", 2) => [ [1, 2], [3, 4], [5, 6] ]
+ *
+ * @param {string} colormap A string of space separated index values
+ * @param {number} ColorLayerSize The length of the chunk to create
+ * @returns {number[][]} The values contained within the supplied colormap parsed to numbers and grouped into arrays of ColorLayerSize length.
+ */
 export const parseColormapRaw = (colormap: string, ColorLayerSize: number): number[][] =>
   colormap
     .split(" ")

src/api/parsers/keymap.test.ts

@@ -0,0 +1,78 @@
+import { expect, describe, it } from "vitest";
+import { parseKeymapRaw, serializeKeymap } from "./keymap";
+
+describe("parseKeymapRaw", () => {
+  it("should handle an empty string", () => {
+    expect(parseKeymapRaw("", 2)).toEqual([]);
+  });
+
+  it("should handle 3 whitespace characters", () => {
+    expect(parseKeymapRaw("  ", 2)).toEqual([]);
+  });
+
+  it("GAP: places NaN into result if given non-decimal numbers", () => {
+    expect(parseKeymapRaw("9 F", 2)).toEqual([
+      [9, NaN],
+    ]);
+  });
+
+  it("GAP: does not produce an array of the correct length if not enough numbers ", () => {
+    expect(parseKeymapRaw("9", 2)).toEqual([
+      [9],
+    ]);
+  });
+
+  it("should split into multiple groups", () => {
+    expect(parseKeymapRaw("10 20 30 40", 2)).toEqual([
+      [10, 20],
+      [30, 40],
+    ]);
+  });
+
+  it("GAP: allows negative numbers", () => {
+    expect(parseKeymapRaw("-10 2", 2)).toEqual([
+      [-10, 2],
+    ]);
+  });
+
+  it("GAP: allows numbers larger than the palette", () => {
+    expect(parseKeymapRaw("400 10", 2)).toEqual([
+      [400, 10],
+    ]);
+  });
+
+  it("should not care about extra whitespace", () => {
+    expect(parseKeymapRaw("  10   20 30  40  ", 4)).toEqual([[10, 20, 30, 40]]);
+  });
+});
+
+describe("serializeKeymap", () => {
+  it("should serialize []", () => {
+    expect(serializeKeymap([])).toEqual("");
+  });
+
+  it("should serialize [[],[]]", () => {
+    expect(serializeKeymap([[], []])).toEqual("");
+  });
+
+  it("should serialize a numeric keymap with one key", () => {
+    expect(serializeKeymap([
+      [{ keyCode: 10, label: "test" }],
+    ])).toEqual("10");
+  });
+
+  it("should serialize a single nested keymap with 2 keys", () => {
+    expect(
+      serializeKeymap([
+        [{ keyCode: 10, label: "test" }, { keyCode: 20, label: "test_2" }],
+      ]),
+    ).toEqual("10 20");
+  });
+
+  it("should serialize two nested arrays with one key each", () => {
+    expect(serializeKeymap([
+      [{ keyCode: 10, label: "test" }],
+      [{ keyCode: 20, label: "test_2" }],
+    ])).toEqual("10 20");
+  });
+});

src/api/parsers/keymap.ts

@@ -3,6 +3,14 @@ import { KeymapDB } from "../keymap";
 
 const keymapDB = new KeymapDB();
 
+/**
+ * Parses a string of space separated base 10 integers representing key codes into arrays of the specified length.
+ * Example: parseKeymapRaw("1 2 3 4 5 6", 2) => [ [1, 2], [3, 4], [5, 6] ]
+ *
+ * @param {string} keymap A string of space separated index values
+ * @param {number} keyLayerSize The length of the chunk to create
+ * @returns {number[][]} The values contained within the supplied keymap parsed to numbers and grouped into arrays of keyLayerSize length.
+ */
 export const parseKeymapRaw = (keymap: string, keyLayerSize: number): number[][] =>
   keymap
     .split(" ")
@@ -19,7 +27,17 @@ export const parseKeymapRaw = (keymap: string, keyLayerSize: number): number[][]
       return localResult;
     }, []);
 
-export const serializeKeymap = (keymap: KeyType[][]) =>
+/**
+ * Serializes a 2d array of KeyTypes into a string of space separated keyCode values.
+ * Example: serializeKeymap([
+ *   [{ keyCode: 10, label: "test" }],
+ *   [{ keyCode: 20, label: "test_2" }],
+ * ]) => "10 20"
+ *
+ * @param {KeyType[][]} keymap A string of space separated index values
+ * @returns {string} A space separated string of keyCode values.
+ */
+export const serializeKeymap = (keymap: KeyType[][]): string =>
   keymap
     .flat()
     .map(k => (typeof k === "number" ? String(k) : keymapDB.serialize(k).toString()))