refactor: organize aoc-related functions

README.md

@@ -48,7 +48,7 @@ It follows the directory structure:
 > [!NOTE]
 > 📂 dist<br>
 > 📂 src<br>
-> └─ 📂 utils<br>
+> └─ 📂 aoc<br>
 > └─ 📂 sample<br>
 > └─ 📂 2024<br>
 > └─── 📂 2024-12-01<br>
@@ -77,7 +77,7 @@ Each Advent of Code (AOC) event quiz has its folder under **`"/src/<YEAR>/<YYYY-
 
 #### Other Items
 
-- **/src/utils**: Folder containing generic utility helper functions
+- **/src/aoc**: 🗃️ Folder containing generic utility and common AoC helper functions
 - **/src/dist**: Folder containing the JavaScript files compiled from TypeScript (not committed to the repository)
 - **/src/sample**: Miscellaneous random examples
 - **/src/index.ts**: Exports all solutions to AOC quiz answer functions

src/2024/2024-12-01/lib/fileReader.ts

@@ -1,5 +1,5 @@
 import path from 'path'
-import { readFile, directory } from '@/utils/file.js'
+import { readFile, directory } from '@/aoc/file/utils.js'
 
 export type arrayLists = {
   list1: string[];

src/2024/2024-12-01/lib/listTotalDistance.ts

@@ -1,4 +1,4 @@
-import { arrangeArray, ARRAY_ORDERING } from '@/utils/arrays.js'
+import { arrangeArray, ARRAY_ORDERING } from '@/aoc/array/utils.js'
 
 /**
  * Calculates the total distance between the smallest value-pairs from list `a` and list `b`

src/2024/2024-12-02/lib/fileReader.ts

@@ -1,5 +1,5 @@
 import path from 'path'
-import { readFile, directory } from '@/utils/file.js'
+import { readFile, directory } from '@/aoc/file/utils.js'
 
 /**
  * Reads the quiz's input file into two (2) string arrays

src/2024/2024-12-03/main.ts

@@ -1,5 +1,5 @@
 import path from 'path'
-import { directory, readFile } from '@/utils/file.js'
+import { directory, readFile } from '@/aoc/file/utils.js'
 import { extractMultiply, extractMultiplyCondition } from './lib/extractMultiply.js'
 
 const dir = directory(import.meta.url)

src/2024/2024-12-04/lib/wordCheckerUtils.ts

@@ -1,19 +1,8 @@
-export type CharacterArray = string[][]
-
-interface CoordinateBase {
-  x: number;
-  y: number;
-}
-
-interface Coordinate extends CoordinateBase {
-  direction: 1 | -1;
-}
-
-interface CoordinateData {
-  xDirection: 1 | -1;
-  yDirection: 1 | -1;
-  data: CharacterArray
-}
+import type {
+  Coordinate,
+  Point,
+  CoordinateData
+} from '@/aoc/point/types.js'
 
 /**
  * Finds the `WORD` input parameter in the vertical directions (up/down) from an (x,y) coordinate
@@ -23,11 +12,11 @@ interface CoordinateData {
  * @param coord.direction {number} Up or down letter-checking direction
  *   - `-1` for "up" going to (0,0)
  *   - `1` for "down" going to (N,N) from the `coord`
- * @param fullData {CharacterArray} 2D array of strings consisting of letters per item
+ * @param fullData {string[][]} 2D array of strings consisting of letters per item
  * @param WORD {string} Word to find
  * @returns {boolean} Flag indicating the existence of the `WORD`
  */
-export const checkVertical = (coord: Coordinate, fullData: CharacterArray, WORD: string): boolean => {
+export const checkVertical = (coord: Coordinate, fullData: string[][], WORD: string): boolean => {
   let yIndex = coord.y
   let subWord = ''
 
@@ -79,11 +68,11 @@ export const checkHorizontal = (coord: Coordinate, rowData: string[], WORD: stri
  * @typedef param {CoordinateData} Direction and data object
  * @param param.xDirection {number} `-1` for "left" going to (0,0) or `1` for "right" going to (N,N) from the `coord`
  * @param param.yDirection {number} `-1` for "up" going to (0,0) or `1` for "down" going to (N,N) from the `coord`
- * @param param.data {CharacterArray} 2D string array containing the input text
+ * @param param.data {string[][]} 2D string array containing the input text
  * @returns {boolean} Flag indicating the existence of the `WORD`
  * @param WORD {string} Word to find
  */
-export const checkDiagonal = (coord: CoordinateBase, param: CoordinateData, WORD: string): boolean => {
+export const checkDiagonal = (coord: Point, param: CoordinateData, WORD: string): boolean => {
   let xIndex = coord.x
   let yIndex = coord.y
   let subWord = ''

src/2024/2024-12-04/lib/wordCount.ts

@@ -2,7 +2,7 @@ import { checkVertical, checkHorizontal, checkDiagonal } from './wordCheckerUtil
 
 /**
  * Counts the number of occurence of the `WORD` from a set of input
- * @param data {CharacterArray} 2D string array containing the input text
+ * @param data {string[][]} 2D string array containing the input text
  * @param WORD_TO_FIND {string} Word to find
  * @returns {number} Number of `WORD`s
  */

src/2024/2024-12-04/main.ts

@@ -1,5 +1,5 @@
 import path from 'path'
-import { directory, readFile } from '@/utils/file.js'
+import { directory, readFile } from '@/aoc/file/utils.js'
 import { wordCount } from './lib/wordCount.js'
 import { countMASword } from './lib/xmasCount.js'
 

src/2024/2024-12-05/lib/fileReader.ts

@@ -1,6 +1,6 @@
 import path from 'path'
-import { directory, readFile } from '@/utils/file.js'
-import { uniformArrayElements } from '@/utils/arrays.js'
+import { directory, readFile } from '@/aoc/file/utils.js'
+import { uniformArrayElements } from '@/aoc/array/utils.js'
 
 export type Rules = Record<number, number[]>
 

src/2024/2024-12-05/lib/fixOrderingUpdates.ts

@@ -1,5 +1,5 @@
 import { isOrderedReport } from './orderedUpdates.js'
-import { arrayMiddleIndex, uniformArrayElements } from '@/utils/arrays.js'
+import { arrayMiddleIndex, uniformArrayElements } from '@/aoc/array/utils.js'
 
 import type { Rules } from './fileReader.js'
 import type { QuizData } from './fileReader.js'

src/2024/2024-12-05/lib/orderedUpdates.ts

@@ -1,5 +1,5 @@
 import type { QuizData, Rules } from './fileReader.js'
-import { uniformArrayElements, arrayMiddleIndex } from '@/utils/arrays.js'
+import { arrayMiddleIndex, uniformArrayElements } from '@/aoc/array/utils.js'
 
 /**
  * Checks if an "update" list is correct according to defined "rules"

src/2024/2024-12-06/README.md

@@ -7,19 +7,25 @@ Visit the Advent of Code website for more information on this puzzle at:
 
 ## Code
 
-1. **grid.ts**
-   - `Grid` - class that has a 2D array object containing paths and obstacles in which a `Guard` runs.
+### `grid.ts`
+
+**`Grid`** class
+   - class that has a 2D array object containing paths and obstacles in which a `Guard` runs.
    - Has functions and methods for managing a `Grid` object
 
-2. **guard.ts**
-   - `Guard` - class representing an object that can walk in the `Grid` map.
+### `guard.ts`
+
+**`Guard`** class
+   - class representing an object that can walk in the `Grid` map.
    - Have methods for moving around in the `Grid`.
 
-3. **guardController.ts**
-   - `guardController()` - Runs the `Guard` on the `Grid`, counting distinct positions/steps.
+### `guardController.ts`
+
+- **`guardController()`** - Runs the `Guard` on the `Grid`, counting distinct positions/steps.
+
+### `guardControllerLoop.ts`
+- **`gridHasInfiniteLoop()`**
+   - Runs the `Guard` on a `Grid` with obstacles, checking the placement of paths and obstacles that will make the `Guard` walk in an infinite loop
+- **`findObstructionPositions()`** - Counts the number of positions in the `Grid` in which inserting one (1) obstruction symbol # will cause the `Guard` to walk in an infinite loop.
+   - > _**WARNING:** This is a very slow, unoptimized program execution that takes about ~3 mins to complete using the actual AoC input text._
 
-5. **guardControllerLoop.ts**
-   - `gridHasInfiniteLoop()`
-      - Runs the `Guard` on a `Grid` with obstacles, checking the placement of paths and obstacles that will make the `Guard` walk in an infinite loop
-   - `findObstructionPositions()` - Counts the number of positions in the `Grid` in which inserting one (1) obstruction symbol # will cause the `Guard` to walk in an infinite loop.
-      - > _**WARNING:** This is a very slow, unoptimized program execution that takes about ~3 mins to complete using the actual AoC input text._

src/2024/2024-12-06/lib/grid.ts

@@ -1,7 +1,6 @@
 import { GuardStatus, GuardDirection } from './guard.types.js'
 import type { GuardState } from './guard.types.js'
 
-
 /**
  * @class Grid
  * @description Object containing a 2D array of strings and other data in which a `Guard` object runs. Each item represents an open path or obstacle.

src/2024/2024-12-06/main.ts

@@ -1,6 +1,6 @@
 import path from 'path'
-import { readAOCInputFile, AOC_OUTPUT_TYPE } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { readAOCInputFile, AOC_OUTPUT_TYPE } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { guardController } from './lib/guardController.js'
 import { findObstructionPositions } from './lib/guardControllerLoop.js'

src/2024/2024-12-06/sample.test.ts

@@ -1,8 +1,8 @@
 import path from 'path'
 import { test, expect } from 'vitest'
 
-import { readAOCInputFile, AOC_OUTPUT_TYPE } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { readAOCInputFile, AOC_OUTPUT_TYPE } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { guardController } from './lib/guardController.js'
 import { findObstructionPositions } from './lib/guardControllerLoop.js'

src/2024/2024-12-07/main.ts

@@ -1,6 +1,6 @@
 import path from 'path'
-import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { totalCalibrationResult } from './lib/totalCalibration.js'
 import { totalCalibrationConcat } from './lib/totalCalibrationConcat.js'

src/2024/2024-12-07/sample.test.ts

@@ -1,8 +1,8 @@
 import path from 'path'
 import { test, expect } from 'vitest'
 
-import { readAOCInputFile, AOC_OUTPUT_TYPE } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { readAOCInputFile, AOC_OUTPUT_TYPE } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { totalCalibrationResult } from './lib/totalCalibration.js'
 import { totalCalibrationConcat } from './lib/totalCalibrationConcat.js'

src/2024/2024-12-08/README.md

@@ -9,14 +9,14 @@ Visit the Advent of Code website for more information on this puzzle at:
 
 ### `GridAntinodes.ts`
 
-- `GridAntiNodes` class - Object that tracks and manages `Antennas` and `Antinodes` in a 2D grid array
+- **`GridAntiNodes`** class - Object that tracks and manages `Antennas` and `Antinodes` in a 2D grid array
 
 ### `uniqueAntinodes.ts`
 
-- `uniqueAntinodes()` - Counts the unique locations in the grid that contains an antinode
+- **`countAntinodes()`** - Counts the unique locations in the grid that contains an antinode
 
 ### `allAntinodes.ts`
 
-- `getAntinodesInPath()` - Finds all `Antinode` coordinates along a path within a 2D array (grid) given a `Point`, increment steps and a +/- direction
+- **`getAntinodesInPath()`** - Finds all `Antinode` coordinates along a path within a 2D array (grid) given a `Point`, increment steps and a +/- direction
 
-- `countAllAntinodes()` - Counts the unique locations in the grid that contains all locations of antinodes along a path
+- **`countAllAntinodes()`** - Counts the unique locations in the grid that contains all locations of antinodes along a path

src/2024/2024-12-08/lib/allAntinodes.ts

@@ -1,4 +1,5 @@
-import type { Antenna, Point } from './types.js'
+import type { Antenna } from './types.js'
+import type { Point } from '@/aoc/point/types.js'
 import { GridAntiNodes } from './GridAntinodes.js'
 
 /**

src/2024/2024-12-08/lib/types.ts

@@ -1,7 +1,4 @@
-export interface Point {
-  x: number;
-  y: number;
-}
+import type { Point } from '@/aoc/point/types.js'
 
 export interface Antenna extends Point {
   frequency: string;

src/2024/2024-12-08/lib/uniqueAntinodes.ts

@@ -1,4 +1,5 @@
-import type { Antenna, Point } from './types.js'
+import type { Antenna } from './types.js'
+import type { Point } from '@/aoc/point/types.js'
 import { GridAntiNodes } from './GridAntinodes.js'
 
 /**

src/2024/2024-12-08/main.ts

@@ -1,6 +1,6 @@
 import path from 'path'
-import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { countAntinodes } from './lib/uniqueAntinodes.js'
 import { countAllAntinodes } from './lib/allAntinodes.js'

src/2024/2024-12-08/sample.test.ts

@@ -1,8 +1,8 @@
 import path from 'path'
 import { test, expect } from 'vitest'
 
-import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { countAntinodes } from './lib/uniqueAntinodes.js'
 import { countAllAntinodes } from './lib/allAntinodes.js'

src/2024/2024-12-09/main.ts

@@ -1,7 +1,7 @@
 import path from 'path'
 
-import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { CompactDisk } from './lib/compact.js'
 import { WholeDisk } from './lib/whole.js'

src/2024/2024-12-09/sample.test.ts

@@ -1,8 +1,8 @@
 import path from 'path'
 import { test, expect } from 'vitest'
 
-import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/utils/aocInputFile.js'
-import { directory } from '@/utils/file.js'
+import { AOC_OUTPUT_TYPE, readAOCInputFile } from '@/aoc/file/aocfile.js'
+import { directory } from '@/aoc/file/utils.js'
 
 import { CompactDisk } from './lib/compact.js'
 import { WholeDisk } from './lib/whole.js'

src/2024/2024-12-10/README.md

@@ -13,6 +13,6 @@ Visit the Advent of Code website for more information on this puzzle at:
 
 ### `scoresRatings.ts`
 
-- `countTrailScores()`
+- **`countTrailScores()`**
    - Finds valid hiking trails (trailheads) from a point coordinate in a 2D array starting with `0` and ending in `9` symbol and calculates the **scores** for each trailhead.
    - Calculates the trailhead **ratings** instead of the trailhead scores if provided with the optional `{ isRating: true }` parameter. Defaults to `false`

src/2024/2024-12-10/lib/scoresRatings.ts

@@ -1,11 +1,8 @@
-import type { Point } from '../../2024-12-08/lib/types.js'
-import type { InputOptions, PointSteps, PointDirection, TrailScores } from './types.js'
-
-import {
-  findValidSteps,
-  findZeroCoordinatePositions,
-  getCoordinateSymbol
-} from './utils.js'
+import type { Point, PointDirection, PointSteps } from '@/aoc/point/types.js'
+import type { InputOptions, TrailScores } from './types.js'
+
+import { getCoordinateSymbol } from '@/aoc/grid/utils.js'
+import { findValidSteps, findZeroCoordinatePositions } from './utils.js'
 
 // List of trailhead scores
 const scores: Record<string, string[]> = {}

src/2024/2024-12-10/lib/types.ts

@@ -1,44 +1,3 @@
-/**
- * Point (y,x) coordinate in a 2D array with direction
- * @type {Object} PointSteps
- * @property {number} x - x-coordinate of the point
- * @property {number} y - y-coordinate of the point
- * @property {Object} direction - Direction vector
- * @property {number} direction.x - Left/right x-direction denoted by `+1` or `-1`
- * @property {number} direction.y - Up/down y-direction denoted by `-1` or `+1`
- */
-export type PointSteps = {
-  x: number;
-  y: number;
-  direction: {
-    x: number;
-    y: number;
-  }
-}
-
-/**
- * Point (y,x) coordinate in a 2D array with a list of valid coordinates from its location.
- * @type {Object} PointDirection
- * @property {number} x - x-coordinate of the point
- * @property {number} y - y-coordinate of the point
- * @property {PointSteps[]} validSteps - List of valid up/down/left/right coordinates from the (y,x) position.
- */
-export type PointDirection = {
-  x: number;
-  y: number;
-  validSteps: PointSteps[]
-}
-
-/**
- * Represents a "(y,x)" coordinate in string and its value from a 2D array.
- * @param {string} coordinate - String version of an "(y,x)" coordinate
- * @param {string | number} symbol - Number or character in a 2D arary denoted by the (y,x) coordinate
- */
-export type GridCoordinateSymbol = {
-  coordinate: string;
-  symbol: string | number;
-}
-
 /**
  * Data returned by the trailhead scores counting function.
  * @param {Record<string, string[]>} scores - Object list of trailhead scores per (y,x) coordinate that starts with a unique `0` and ends with a `9`