Add a few more utilities for working with sound frequencies (#495)

Author: miorel

workspaces/simon-game/src/app/constants.ts

@@ -1,24 +1,27 @@
+import { arpeggiate } from "@code-chronicles/util/arpeggiate";
 import { getConcertPitch } from "@code-chronicles/util/getConcertPitch";
 
+const [note1, note2, note3, note4] = arpeggiate(getConcertPitch("C4"), 1);
+
 export const config = {
   soundDurationMs: 300,
   volumePct: 0.1,
   boxes: [
     {
       color: "red",
-      frequency: getConcertPitch("C4"),
+      frequency: note1,
     },
     {
       color: "#0050B5", // cobalt blue
-      frequency: getConcertPitch("E4"),
+      frequency: note2,
     },
     {
       color: "green",
-      frequency: getConcertPitch("G4"),
+      frequency: note3,
     },
     {
       color: "yellow",
-      frequency: getConcertPitch("C5"),
+      frequency: note4,
     },
   ],
 };

workspaces/util/src/__tests__/getConcertPitch-test.ts

@@ -55,5 +55,45 @@ describe("getConcertPitch", () => {
 
   // TODO: test that note can be uppercase or lowercase
 
-  // TODO: test some invalid inputs
+  it.each([
+    // Invalid note:
+    "H4",
+    "I4",
+    "Do4",
+
+    // Invalid accidental:
+    "A%4",
+    "BB4",
+    "C++11",
+
+    // Invalid octave:
+    "Aa",
+
+    // Out-of-order note:
+    "4A",
+    "C4#",
+
+    // Extra characters in the octave:
+    "A04",
+    "A+4",
+    "A4.",
+    "A4.0",
+
+    // Missing note:
+    "4",
+    "#4",
+
+    // Missing octave:
+    "A",
+    "Ab",
+    "C#",
+
+    // Other fun stuff:
+    "",
+    "440",
+    "Doe, a deer",
+    "Hello, World!",
+  ])("throws on invalid input %p", (s) => {
+    expect(() => getConcertPitch(s)).toThrow();
+  });
 });

workspaces/util/src/arpeggiate.ts

@@ -0,0 +1,21 @@
+import { lastOrThrow } from "@code-chronicles/util/lastOrThrow";
+import type { NonEmptyArray } from "@code-chronicles/util/NonEmptyArray";
+import { shiftSemitones } from "@code-chronicles/util/shiftSemitones";
+import { shiftOctaves } from "@code-chronicles/util/shiftOctaves";
+
+export function arpeggiate(
+  freq: number,
+  octaves: number,
+): NonEmptyArray<number> {
+  const res: NonEmptyArray<number> = [freq];
+  for (let i = 0; i < octaves; ++i) {
+    const last = lastOrThrow(res);
+    res.push(
+      shiftSemitones(last, 4),
+      shiftSemitones(last, 7),
+      shiftOctaves(last, 1),
+    );
+  }
+
+  return res;
+}

workspaces/util/src/assertIsIntegerString.ts

@@ -0,0 +1,10 @@
+import invariant from "invariant";
+
+export function assertIsIntegerString(s: string): number {
+  const n = parseInt(s, 10);
+  invariant(
+    !Number.isNaN(n) && String(n) === s,
+    "Parsed integer doesn't restringify to the same input.",
+  );
+  return n;
+}

workspaces/util/src/first.ts

@@ -1,5 +1,20 @@
-export function first<T>(array: readonly [T, ...T[]]): T;
+import type { NonEmptyArray } from "@code-chronicles/util/NonEmptyArray";
+
+export function first<T>(array: Readonly<NonEmptyArray<T>>): T;
+
 export function first<T>(array: readonly T[]): T | undefined;
-export function first<T>(array: readonly T[]): T | undefined {
-  return array[0];
+
+export function first<T>(iterable: Iterable<T>): T | undefined;
+
+export function first<T>(iterable: Iterable<T>): T | undefined {
+  if (Array.isArray(iterable)) {
+    return iterable[0];
+  }
+
+  // eslint-disable-next-line no-unreachable-loop -- Intentional single iteration.
+  for (const element of iterable) {
+    return element;
+  }
+
+  return undefined;
 }

workspaces/util/src/getConcertPitch.ts

@@ -1,6 +1,9 @@
-import invariant from "invariant";
 import nullthrows from "nullthrows";
 
+import { assertIsIntegerString } from "@code-chronicles/util/assertIsIntegerString";
+import { shiftOctaves } from "@code-chronicles/util/shiftOctaves";
+import { shiftSemitones } from "@code-chronicles/util/shiftSemitones";
+
 const NOTES = {
   c: -9,
   d: -7,
@@ -27,9 +30,7 @@ export function getConcertPitch(note: string, a4Pitch: number = 440): number {
     semitones += ACCIDENTALS[note[index++] as keyof typeof ACCIDENTALS];
   }
 
-  const octaveString = note.slice(index);
-  invariant(/^-?\d+/.test(octaveString), "Invalid octave!");
-  const octaves = parseInt(octaveString, 10) - 4;
+  const octaves = assertIsIntegerString(note.slice(index)) - 4;
 
-  return a4Pitch * Math.pow(2, octaves + semitones / 12);
+  return shiftSemitones(shiftOctaves(a4Pitch, octaves), semitones);
 }

workspaces/util/src/last.ts

@@ -0,0 +1,20 @@
+import type { NonEmptyArray } from "@code-chronicles/util/NonEmptyArray";
+
+export function last<T>(array: Readonly<NonEmptyArray<T>>): T;
+
+export function last<T>(array: readonly T[]): T | undefined;
+
+export function last<T>(iterable: Iterable<T>): T | undefined;
+
+export function last<T>(iterable: Iterable<T>): T | undefined {
+  if (Array.isArray(iterable)) {
+    return iterable.at(-1);
+  }
+
+  let res = undefined;
+  for (const element of iterable) {
+    res = element;
+  }
+
+  return res;
+}

workspaces/util/src/lastOrThrow.ts

@@ -0,0 +1,6 @@
+import invariant from "invariant";
+
+export function lastOrThrow<T>(array: readonly T[]): T {
+  invariant(array.length > 0, "Expected a non-empty array!");
+  return array.at(-1) as T;
+}

workspaces/util/src/shiftOctaves.ts

@@ -0,0 +1,3 @@
+export function shiftOctaves(freq: number, octaves: number): number {
+  return freq * 2 ** octaves;
+}

workspaces/util/src/shiftSemitones.ts

@@ -0,0 +1,5 @@
+import { shiftOctaves } from "@code-chronicles/util/shiftOctaves";
+
+export function shiftSemitones(freq: number, semitones: number): number {
+  return shiftOctaves(freq, semitones / 12);
+}