feat: setup vscode debugging in docker

README.md

@@ -149,6 +149,40 @@ Using Docker
    docker run -it -v ${pwd}:/opt/app -v /opt/app/node_modules --rm weaponsforge/adventofcode:dev <AVAILABLE_SCRIPT>
    ```
 
+- Run a script and debug it with the VSCode Debugger.
+   - Prepare a function for debugging with VSCode in Docker. Wrap it in the `AOCRunScript()` function.
+   - Assign the path to a TypeScript file from the previous step to the package.json file's `"dev:debug:docker"` script, replacing `src/sample/sample.ts`.
+      - `"dev:debug:docker": "export IS_DOCKER=true && node --inspect=0.0.0.0:9229 ./node_modules/.bin/vite-node src/path/to/script.ts"`
+   - Run the script with VSCode debugging:
+      ```
+      docker run -it -v ${pwd}:/opt/app -v /opt/app/node_modules --rm weaponsforge/adventofcode:dev npm run dev:debug:docker
+      ```
+   > **INFO:** This process requires attaching a debugger with the VSCode launch config defined in Issue [#53](https://github.com/weaponsforge/adventofcode/issues/53)
+
+   <details>
+   <summary>VSCode Launch Configuration</summary>
+
+   ```json
+   {
+     "version": "0.2.0",
+     "configurations": [
+       {
+         "type": "node",
+         "request": "attach",
+         "name": "Attach to Docker",
+         "address": "localhost",
+         "port": 9229,
+         "restart": true,
+         "skipFiles": ["<node_internals>/**"],
+         "localRoot": "${workspaceFolder}",
+         "remoteRoot": "/opt/app"
+       }
+     ]
+   }
+   ```
+
+   </details>
+
 ## 📜 Available Scripts
 
 <details>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "adventofcode",
-  "version": "1.1.0",
+  "version": "1.2.3",
   "description": "Solutions for Advent of Code https://adventofcode.com/ event puzzles",
   "main": "dist/index.js",
   "type": "module",
@@ -11,6 +11,7 @@
   "scripts": {
     "dev": "vitest",
     "dev:debug": "vite-node src/sample/sample.ts",
+    "dev:debug:docker": "export IS_DOCKER=true && node --inspect=0.0.0.0:9229 ./node_modules/.bin/vite-node src/sample/sample.ts",
     "transpile": "tsc -p tsconfig.json && tsc-alias",
     "transpile:noemit": "tsc -p tsconfig.json --noEmit",
     "watch": "tsc -p tsconfig.json --watch",

src/aoc/README.md

@@ -18,6 +18,15 @@ A collection handler functions for manipulating regular arrays.
 - **`utils.ts`** - ES modules file and directory handlers
 - **`aocfile.ts`** - Functions for reading common-format AoC file input (arrays of `strings` or `numbers`)
 
+### 📂 `function`
+
+#### `aocFunctions.ts`
+
+A collection of utility helper functions for running AoC functions.
+
+- **`AOCDeferExecution()`** - Defers executing a function by `timeout` milliseconds.
+- **`AOCRunScript()`** - A wrapper that runs a function or defers running a function by `timeout` milliseconds if it runs in a Docker container. The `IS_DOCKER=true` environment variable indicates running inside a Docker container.
+
 ### 📂 `grid`
 
 #### `utils.ts`

src/aoc/function/aocFunctions.ts

@@ -0,0 +1,24 @@
+/**
+ * Defers executing a function by `timeout` milliseconds.
+ * @param {Function} callback - A function declaration or expression
+ * @param {number} [timeout] - (Optional) Number in milliseconds to defer executing the `callback` function. Default value is `5000` (5 seconds)
+ */
+export const AOCDeferExecution = (callback: () => void, timeout: number = 5000): void => {
+  setTimeout(() => {
+    callback()
+  }, timeout)
+}
+
+/**
+ * A wrapper that runs a function or defers running a function by `timeout` milliseconds if it runs in a Docker container.
+ * The `IS_DOCKER=true` environment variable indicates running inside a Docker container.
+ * @param {Function} callback - A function declaration or expression
+ * @param {number} [timeout] - (Optional) Number in milliseconds to defer executing the `callback` function. Default value is `5000` (5 seconds)
+ */
+export const AOCRunScript = (callback: () => void, timeout: number = 5000): void => {
+  if (process.env.IS_DOCKER) {
+    AOCDeferExecution(callback, timeout)
+  } else {
+    callback()
+  }
+}

src/sample/sample.ts

@@ -1,2 +1,4 @@
 import { greet } from './greet.js'
-greet('World Wide Web')
+import { AOCRunScript } from '@/aoc/function/aocFunctions.js'
+
+AOCRunScript(() => greet('World Wide Web'))