DEV Community: Kev

Making a Speedrun Timer: Chapter 4

Kev — Tue, 18 Apr 2023 07:38:36 +0000

Another migration.. I'm sorry 😅

I know, it's the last thing you want to see. But I'm hoping this will be the last major one! Since migrating to an Electron.js in the previous post, our code has essentially been broken up into two parts:

Node.js code
Chromium browser code

The chromium code houses the frontend responsible for displaying our timer (the Vue.js stuff). The Node.js code is responsible for our communication to the operating system. However, Node.js handles the importing of modules differently from the V8 engine that powers the chromium browser. Not only that, but a lot of APIs are different between the two.

As a result of this migration, our code is starting to become a bit messy and all over the place. Furthermore, it would be nice to share code between the Node.js API and the Chromium browser API without having to worry about the entanglement of importing strategies. Therefore, I think it would be wise to migrate our app to TypeScript!

Migrating To TypeScript

Once again, I don't really want to go over EVERY single change that went into this. You'll have to checkout the GitHub repo for that.

The Obvious Changes

First thing we want to do is change all of our .js file extensions to .ts. Next, we need to run npm i --save-dev typescript ts-node to install the packages we need.

These changes might seem obvious, but I think the next few changes might be more helpful to those migrating from a Vite + Vue 3 + Electron.js vanilla JavaScript app to a TypeScript version.

The Major Changes

Quite a few changes occur in our forge.config.ts file. We'll be switching a lot of code over to module imports:

// forge.config.ts

// Taken from https://github.com/caoxiemeihao/electron-forge-vite/blob/main/vite-typescript/tmpl/forge.config.ts 
import type { ForgeConfig } from '@electron-forge/shared-types';
import { MakerSquirrel } from '@electron-forge/maker-squirrel';
import { MakerZIP } from '@electron-forge/maker-zip';
import { MakerDeb } from '@electron-forge/maker-deb';
import { MakerRpm } from '@electron-forge/maker-rpm';
import { VitePlugin } from '@electron-forge/plugin-vite';

const config: ForgeConfig = {
  packagerConfig: {},
  rebuildConfig: {},
  makers: [new MakerSquirrel({}), new MakerZIP({}, ['darwin']), new MakerRpm({}), new MakerDeb({})],
  plugins: [
    new VitePlugin(
    {
      // `build` can specify multiple entry builds, which can be Main process, Preload scripts, Worker process, etc.
      // If you are familiar with Vite configuration, it will look really familiar.
      build: [
        {
          // `entry` is just an alias for `build.lib.entry` in the corresponding file of `config`.
          entry: 'src/main/main.ts',
          config: 'vite.main.config.mts',
        },
        {
          entry: 'src/main/preload.ts',
          config: 'vite.preload.config.mts',
        },
      ],
      renderer: [
        {
          name: 'main_window',
          config: 'vite.renderer.config.mts',
        },
      ],
    }),
  ],
};

export default config;

Another major change we needed to make was exposing certain types at the top of our main.ts file:

// This allows TypeScript to pick up the magic constants that's auto-generated by Forge's Vite
// plugin that tells the Electron app where to look for the Vite-bundled app code (depending on
// whether you're running in development or production).
declare const MAIN_WINDOW_VITE_DEV_SERVER_URL: string;
declare const MAIN_WINDOW_VITE_NAME: string;

Lastly, we just want to redirect our renderer reference in our index.html file

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Speedrun Timer</title>

  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/renderer/renderer.ts"></script>
  </body>
</html>

The Final Changes

Beyond that, most of the remaining code changes modify the Node.js code to use import statements instead of require, adds declarative types to our code, and explicitly informs the vue files to use TypeScript in the script code via <script setup lang="ts">.

Here's our tsconfig.json for reference:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "node",
    "target": "ESNext",
    "outDir": "../../dist",
    "strict": true,
    "sourceMap": true,
    "experimentalDecorators": true,
    "esModuleInterop": true,
    "declaration": true,
    "skipLibCheck": true
  },
  "include": ["**/*.ts", "vite.renderer.config.mts", "vite.renderer.config.mts", "vite.preload.config.mts", "vite.preload.config.mts", "vite.main.config.mts", "vite.main.config.mts"]
}

Conclusion

It was pretty hard to figure out how to migrate this project TypeScript, as it didn't seem like there was a lot of documentation on my specific configuration. Hopefully somebody finds this useful. I'd like to shoutout this repo for guiding me on how to make this happen.

If you'd like a detailed list of changes, you can look here.

UPDATE: In a follow-up change, we fixed some IDE issues and added a linter.

Next chapter we'll look to finally write new stuff instead of migrating everything!

Making a Speedrun Timer: Chapter 3

Kev — Sun, 09 Apr 2023 21:08:31 +0000

Abandon Ship 🚢

Well after a few successful blog posts, we've finally hit our first big problem, and it's a show-stopper. What do I mean by that? Well it has to do with initial design considerations.

When I first designed our app, I went down the PWA route, thinking that the browser had everything we needed for our app to function properly.

But I was wrong. I overlooked one of the most crucial features to our speedrun timer, global shortcuts.

Global shortcuts are keys or key combinations that you can type on your keyboard to trigger some sort of functionality on your app or operating system (e.g. the windows key opening the app launcher).

If you're familiar with LiveSplit and you've been a speed-runner for a decent amount of time, you'll know that global shortcut keys are a lifesaver when it comes to tracking your splits. It's not practical to make sure that your timer remains in the foreground while you're speed-running a game. Too often can you accidentally leave another application open and completely mess up your split times or your entire run!

So do you know what CAN'T perform global shortcuts? The browser.

Migrating from PWA to Electron

Oh boy, what do we do about this? Well fortunately, we're not out of options. In fact, I sort of accounted for this in the beginning.

One of the reasons I chose to write the frontend for this project in Vue/JavaScript, is that if I needed to, I could easily migrate to an Electron application. Electron.js gives us a way to build cross-platform desktop applications in JavaScript. So through this migration, we can utilize global shortcuts and run our app on all major desktop platforms!

Code Changes

I won't go over ever single code change, as that would make for an insanely long post. Furthermore, our code is going to largely remain the same. What will change is our project structure and the added global shortcut functionality.

Our project structure will be divided into 3 parts:

The node.js code that communicates between our app and the operating system.
The renderer code, which is essentially just our frontend.
The preloader code, which serves as a bridge between node.js and the frontend.

Node.js Code

Our node.js code is mostly given to us by default when scaffolding a Electron Forge project. A lot of the comments are generated from it as well. The only code we'll change is we want to register the global shortcuts once the application is ready. We handle this with node.js because we need to listen to keyboard input on an operating system level, not just on the application itself. Once the callback function is triggered, we then send the commands to the mainWindow to interact with our timer.

It's important to note that once binding a keyboard shortcut (like the number "1" shown here), you won't be able to type with or use that key on any other application 😬. This limitation was a design choice by the Electron team to prevent the development of a keylogger. There may be some sort of work-around but I won't get into that here. Feel free to comment if you know of another solution!

// main.js
const { app, BrowserWindow, globalShortcut } = require('electron');
const path = require('path');

// Handle creating/removing shortcuts on Windows when installing/uninstalling.
if (require('electron-squirrel-startup')) {
  app.quit();
}

let mainWindow;
const createWindow = () => {
  // Create the browser window.
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });

  // and load the index.html of the app.
  if (MAIN_WINDOW_VITE_DEV_SERVER_URL) {
    mainWindow.loadURL(MAIN_WINDOW_VITE_DEV_SERVER_URL);
  } else {
    mainWindow.loadFile(path.join(__dirname, `../renderer/${MAIN_WINDOW_VITE_NAME}/index.html`));
  }

  // Open the DevTools.
  mainWindow.webContents.openDevTools();
};

// This method will be used to setup our global shortcuts code.
// https://electronjs.org/docs/latest/api/global-shortcut
app.whenReady().then(() => {
  globalShortcut.register('1', () => {
    mainWindow.webContents.send("global-timer", 0);
  })
  globalShortcut.register('2', () => {
    mainWindow.webContents.send("global-timer", 1);
  })
  globalShortcut.register('3', () => {
    mainWindow.webContents.send("global-timer", 2);
  })
}).then(createWindow);

// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  // On OS X it's common to re-create a window in the app when the
  // dock icon is clicked and there are no other windows open.
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and import them here.

Preloader

As mentioned before, this code will serve as a bridge between the node.js code (operating system communication) and the renderer code (frontend). Currently, all we need to do is to expose the ipcRenderer API to allow the renderer to communicate with node.

// preloader.js
// See the Electron documentation for details on how to use preload scripts:
// https://www.electronjs.org/docs/latest/tutorial/process-model#preload-scripts
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
    listenForTimerCommands: (listener) => ipcRenderer.on('global-timer', listener)
});

Renderer

Finally, we have our renderer. This code is simply our entry file (the old main.js) from our PWA before.

// renderer.js
import { createApp } from "vue";
import "./style.css";
import App from "./App.vue";

createApp(App).mount("#app");

Let's go ahead and add the code on the frontend to react to a global shortcut input.

// Stopwatch.vue
<script setup>
import { onMounted, onUnmounted } from 'vue';
import { useStopwatch } from '../composables/stopwatch';
import { WorkerCommands } from '../helpers/timer-worker-helper';

const {
  timerTxt,
  onTimerStart,
  onTimerStop,
  onTimerReset,
  onTimerInit,
  onTimerTeardown
} = useStopwatch();

onMounted(() => {
  onTimerInit();
  window.electronAPI.listenForTimerCommands((_, data) => {
    switch(data) {
      case WorkerCommands.START:
        onTimerStart();
        break;
      case WorkerCommands.STOP:
        onTimerStop();
        break;
      case WorkerCommands.RESET:
        onTimerReset();
        break;
      }
  });
});

onUnmounted(() => {
  onTimerTeardown();
});

</script>

<template>
  <div>
    <p>{{ timerTxt }}</p>
    <button @mousedown="onTimerStart">Start</button>
    <button @mousedown="onTimerStop">Stop</button>
    <button @mousedown="onTimerReset">Reset</button>
  </div>
</template>

<style scoped>
button {
  margin: 0 5px;
}
</style>

Conclusion

There you have it! We have now successfully migrated from PWA to Electron. I'm actually very excited to see what desktop development will have in store for us. I've already learned a lot!

If there's any other code changes you want to see or want me to go over, feel free to comment on the post with your questions. You can also follow along in the GitHub repo.

Making a Speedrun Timer: Chapter 2

Kev — Mon, 03 Apr 2023 08:22:05 +0000

Enhancing the Timer 💪

In the previous post, we started our project by developing the building blocks of our application and creating a simple stopwatch timer. In this chapter, I would like to abstract the timer functionality and put it in a web worker. Running our code in a web worker will allow our app to run in the background, so we don't have to worry about throttling from the browser. It will also permit our timer to maintain optimal performance by operating asynchronously on another thread. You can read and learn more about a web worker here.

Abstracting the Timer

When abstracting our code, we should split our timer code into two parts:

The timer's core functionality, which will be running inside of a web worker.
The web worker's functionality, which will be the code we use to initialize our web worker and to send messages to and from the worker.

Separating the code this way will give us code clarity and allow us to unit test the code to the fullest extent.

The Timer's Core Functionality

This code won't be too complex as we are just going to port our timer functions over to their file to be used by the web worker:

// timer-worker.js
import { WorkerCommands, WorkerCommunicator } from "../helpers/timer-worker-helper";

let [milliseconds, seconds, minutes, hours] = [0, 0, 0, 0];
let timer;
let paused = false;
let prevTime;

// Initialize the function to be used when receiving a message 
(function init() {
  WorkerCommunicator.setOnMessageFunc(onMessageFunc);
})();

// The function to be called when receiving a message
export function onMessageFunc(event) {
  switch(event.data.command) {
    case WorkerCommands.START:
      timerStart();
      break;
    case WorkerCommands.STOP:
      timerStop();
      break;
    case WorkerCommands.RESET:
      timerReset();
      break;
  }
}

export function timerStart() {
  if (timer) {
    return;
  }

  paused = false;
  prevTime = new Date();
  timer = setInterval(incrementTimer, 10);
}

export function timerStop() {
  paused = true;
  clearInterval(timer);
  timer = null;
}

export function timerReset() {
  paused = true;
  clearInterval(timer);
  [milliseconds, seconds, minutes, hours] = [0, 0, 0, 0];
  paused = false;
  WorkerCommunicator.postMessageToMainThread({ 
    timerTxt: getTimeFormatString() 
  });
  timer = null;
}

// Increments the tracked time values and sends message back to main thread
function incrementTimer() {
  if (paused) {
    return;
  }

  const elapsedMilliseconds = ((new Date()) - prevTime);
  setTimeValues(elapsedMilliseconds);
  WorkerCommunicator.postMessageToMainThread({ 
    timerTxt: getTimeFormatString() 
  });
  prevTime = new Date();
}

// Helps remove redundant logic that would be used on setTimeValues
function setTimeValueHelper(prevVal, currVal, incrementor) {
  if (prevVal < incrementor) {
    return [ prevVal, currVal ];
  }

  currVal += (prevVal - (prevVal % incrementor)) / incrementor ;
  prevVal = prevVal % incrementor;
  return [ prevVal, currVal ];
}

// Set timer values to be formatted
function setTimeValues(elapsedMilliseconds) {
  milliseconds += elapsedMilliseconds;

  [ milliseconds, seconds ] = setTimeValueHelper(milliseconds, seconds, 1000);
  [ seconds, minutes ] = setTimeValueHelper(seconds, minutes, 60);
  [ minutes, hours ] = setTimeValueHelper(minutes, hours, 60);
}

// Formats the message to be sent to main thread
export function getTimeFormatString() {
  const h = hours.toLocaleString('en-US', {
    minimumIntegerDigits: 2,
    useGrouping: false
  });
  const min = minutes.toLocaleString('en-US', {
    minimumIntegerDigits: 2,
    useGrouping: false
  });
  const s = seconds.toLocaleString('en-US', {
    minimumIntegerDigits: 2,
    useGrouping: false
  });
  const ms = milliseconds.toLocaleString('en-US', {
    minimumIntegerDigits: 3,
    useGrouping: false
  });

  return `${h}:${min}:${s}.${ms}`;
}

One notable change is the refactored setTimeValues function, which now contains less nesting and repetitive code.

You'll also notice new code where we used to set the timerTxt component variable. Since our worker will have no context of timerTxt, we have to utilize the worker's built-in functions postMessage and onmessage to provide communication from the web worker to the main thread that has access to the component. I've created a wrapper called WorkerCommunicator that encapsulates this functionality.

I've also created an object structure (WorkerCommands) that helps us define what our stopwatch worker's "start", "stop", and "reset" commands look like.

Here is the code for this abstraction:

// timer-worker-helper.js
export const WorkerCommands = {
  START: 0,
  STOP: 1,
  RESET: 2
}

// Communicates with Web Worker from main thread
export const WorkerCommunicator = {
  setOnMessageFunc: (func) => {
    onmessage = func;
  },
  postMessageToMainThread: (data) => {
    postMessage(data);
  }
};

With this abstraction, we can isolate the worker code from the timer code and unit test the timer code extensively.

The Web Worker's Functionality

We've now moved the timer code out from the stopwatch.js composable and into it's own file called timer-worker.js. Now we need our composable to initialize a timer worker and send and receive messages from it. To do this, let's add more to our timer-worker-helper.js code:

// timer-worker-helper.js
import Worker from '../workers/timer-worker?worker';

/* NEW CODE START */
// Class wrapper for stopwatch Web Worker
export class TimerWorker {
  constructor() {
    this.worker = new Worker();
  }

  setOnMessageFunc(onMsgFunc) {
    this.worker.onmessage = onMsgFunc;
  }

  postMessageToWorker(data) {
    this.worker.postMessage(data);
  }

  terminate() {
    this.worker.terminate();
  }
}
/* NEW CODE END */

export const WorkerCommands = {
  START: 0,
  STOP: 1,
  RESET: 2
}

// Communicates with Web Worker from main thread
export const WorkerCommunicator = {
  setOnMessageFunc: (func) => {
    onmessage = func;
  },
  postMessageToWorker: (data) => {
    postMessage(data);
  }
};

This code is very straight-forward as we create a wrapper class called TimerWorker and initialize a Worker within it. Creating a wrapper will allow us to customize the worker's functionality later on and abstract the code for testing.

Now we can implement this new TimerWorker class into our composable:

// stopwatch.js
import { ref } from 'vue';
import { TimerWorker, WorkerCommands } from '../helpers/timer-worker-helper';

export function useStopwatch() {
  let timerWorker;

  const timerTxt = ref('00:00:00.000');

  function onTimerInit() {
    if (timerWorker) {
      return;
    }

    timerWorker = new TimerWorker();
    timerWorker.setOnMessageFunc(updateTimerTxtFromWorkerMsg);
  }

  function updateTimerTxtFromWorkerMsg(event) {
    timerTxt.value = event.data.timerTxt;
  }

  function onTimerStart() {
    timerWorker.postMessageToWorker({
      command: WorkerCommands.START
    });
  }

  function onTimerStop() {
    timerWorker.postMessageToWorker({
      command: WorkerCommands.STOP
    });
  }

  function onTimerReset() {
    timerWorker.postMessageToWorker({
      command: WorkerCommands.RESET
    });
  }

  function onTimerTeardown() {
    if (!timerWorker) {
      return;
    }

    timerWorker.terminate();
    timerWorker = undefined;
  }

  return {
    timerTxt,
    onTimerStart, 
    onTimerStop, 
    onTimerReset,
    onTimerInit,
    onTimerTeardown,
    updateTimerTxtFromWorkerMsg
  };
}

As you can see, our composable becomes a simple and easy to understand component.

We added some code here that introduced two new event functions titled onTimerInit and onTimerTeardown. We'll need to call these functions in our component when the component is mounted and unmounted:

// Stopwatch.vue
<script setup>
import { onMounted, onUnmounted } from 'vue';
import { useStopwatch } from '../composables/stopwatch';

const {
  timerTxt,
  onTimerStart,
  onTimerStop,
  onTimerReset,
  onTimerInit,
  onTimerTeardown
} = useStopwatch();

onMounted(() => {
  onTimerInit();
});

onUnmounted(() => {
  onTimerTeardown();
});

</script>

<template>
  <div>
    <p>{{ timerTxt }}</p>
    <button @mousedown="onTimerStart">Start</button>
    <button @mousedown="onTimerStop">Stop</button>
    <button @mousedown="onTimerReset">Reset</button>
  </div>
</template>

<style scoped>
button {
  margin: 0 5px;
}
</style>

Lastly, let's check to see if our browser supports web workers. If it doesn't, you probably shouldn't be using this application. So let's tell our users that 😉

// App.vue
<script setup>
import { onMounted, ref } from 'vue';
import Stopwatch from './components/Stopwatch.vue';

const isSupported = ref(false);

onMounted(() => {
  isSupported.value = typeof(Worker) !== "undefined";
});

</script>

<template>
  <div>
    <stopwatch v-if="isSupported"></stopwatch>
    <div v-else>
      <p>Sorry, your browser does not support this application</p>
    </div>
  </div>
</template>

Writing the Tests

Writing the unit tests that involved web workers turned out to be more difficult than I expected. After time it was clear I needed to abstract the code to keep it portable and testable. I won't get into too much more detail, but here's the code for unit testing in vitest:

// stopwatch.spec.js
import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
import { useStopwatch } from "../../src/composables/stopwatch";
import { waitForTime } from "../helpers/mock-time-helper";
import  { TimerWorker, WorkerCommunicator } from "../../src/helpers/timer-worker-helper";
import { onMessageFunc } from "../../src/workers/timer-worker";

vi.mock("../../src/helpers/timer-worker-helper", () => ({
  WorkerCommunicator: {
    postMessageToMainThread: vi.fn(),
    setOnMessageFunc: vi.fn(),
  },
  TimerWorker: vi.fn().mockImplementation(() => {
    return {
      setOnMessageFunc: vi.fn(),
      postMessageToWorker: vi.fn().mockImplementation((data) => {
        onMessageFunc({
          data: {
            command: data.command,
          },
        });
      }),
      terminate: vi.fn(),
    };
  }),
  WorkerCommands: {
    START: 0,
    STOP: 1,
    RESET: 2
  }
}));

describe("Stopwatch unit tests", () => {
  beforeEach(() => {
    vi.useFakeTimers();
  });

  afterEach(() => {
    vi.clearAllTimers();
    vi.useRealTimers();
  });

  it("Timer start, stop, and reset", async () => {
    const {
      timerTxt,
      onTimerInit,
      onTimerTeardown,
      onTimerStart,
      onTimerStop,
      onTimerReset,
      updateTimerTxtFromWorkerMsg,
    } = useStopwatch();

    WorkerCommunicator.postMessageToMainThread.mockImplementation((data) => {
      updateTimerTxtFromWorkerMsg({
        data: {
          timerTxt: data.timerTxt,
        },
      });
    });

    onTimerInit();

    onTimerStart();
    await vi.advanceTimersByTimeAsync(10);

    expect(timerTxt.value).toEqual("00:00:00.010");
    expect(vi.getTimerCount(), "The timer was not started").toEqual(1);

    onTimerStop();
    await vi.advanceTimersByTimeAsync(10);

    expect(vi.getTimerCount(), "A timer still exists").toEqual(0);
    expect(timerTxt.value).toEqual("00:00:00.010");

    onTimerReset();
    await vi.advanceTimersByTimeAsync(10);

    expect(vi.getTimerCount(), "A timer still exists").toEqual(0);
    expect(timerTxt.value).toEqual("00:00:00.000");

    onTimerTeardown();
  });

  it("Prevent duplicate start timers", async () => {
    const { timerTxt, onTimerInit, onTimerStart, onTimerReset, onTimerTeardown, updateTimerTxtFromWorkerMsg } = useStopwatch();

    WorkerCommunicator.postMessageToMainThread.mockImplementation((data) => {
      updateTimerTxtFromWorkerMsg({
        data: {
          timerTxt: data.timerTxt,
        },
      });
    });

    onTimerInit();

    onTimerStart();
    await vi.advanceTimersByTimeAsync(10);

    expect(vi.getTimerCount(), "The timer was not started").toEqual(1);
    expect(timerTxt.value).toEqual("00:00:00.010");

    onTimerStart();
    await vi.advanceTimersByTimeAsync(10);

    expect(vi.getTimerCount(), "Invalid number of timers").toEqual(1);
    expect(timerTxt.value).toEqual("00:00:00.020");

    onTimerReset();
    await vi.advanceTimersByTimeAsync(10);

    onTimerTeardown();
  });

  it("Ensure timer increments appropriately", async () => {
    const { timerTxt, onTimerInit, onTimerTeardown, onTimerStart, onTimerReset, updateTimerTxtFromWorkerMsg } = useStopwatch();

    WorkerCommunicator.postMessageToMainThread.mockImplementation((data) => {
      updateTimerTxtFromWorkerMsg({
        data: {
          timerTxt: data.timerTxt,
        },
      });
    });

    onTimerInit();

    vi.setSystemTime(vi.getRealSystemTime());

    onTimerStart();
    await waitForTime(15);

    expect(timerTxt.value).toEqual("00:00:00.025");

    await waitForTime(2000);

    expect(timerTxt.value).toEqual("00:00:02.025");

    await waitForTime(2000 * 60);

    expect(timerTxt.value).toEqual("00:02:02.025");

    await waitForTime(1000 * 60 * 60);

    expect(timerTxt.value).toEqual("01:02:02.025");

    onTimerReset();
    await vi.advanceTimersByTimeAsync(10);

    onTimerTeardown();
  });
});

When writing the unit tests, I ran into a problem with them timing out. I thought this was very odd, since I was using mocked time. Theoretically the tests should be completed instantly. It turns out that this is because when you call vi.advanceTimersByTimeAsync() with a large number, it calls all timers that could be invoked within that time frame recursively. For example, if I called vi.advanceTimersByTimeAsync(1000 * 60 * 60), which is simply an hour, it would recursively call incrementTimer that many times. You would need a pretty hefty computer to compute that in a short amount of time. So, I had to work around it by writing this function:

// mock-time-helper.js
import { vi } from "vitest";

export async function waitForTime(timeToWait) {
  await vi.runOnlyPendingTimersAsync();
  vi.setSystemTime(new Date(vi.getMockedSystemTime()).getTime() + timeToWait);
  await vi.advanceTimersToNextTimerAsync();
}

Now we can utilize the system time set at the beginning of each timer test, skip the system time ahead by the elapsed time, and only run the timer code once after that.

Conclusion

Code abstraction has allowed the code to be more portable and enhance the timer by running the code in its own thread. The code also has become more testable this way, ensuring the reliability of it as we progress in development.

Here's the GitHub repo for this project. If you haven't already, be sure to give me a follow on here and other socials to see updates to this series and more!

Making a Speedrun Timer: Chapter 1

Kev — Thu, 30 Mar 2023 18:10:18 +0000

Making the Timer ⏱️

In the previous post, we explained what we're making (a speedrun timer), why we're making it, and how to setup the project. Now we're ready to get to the good stuff! To start, we'll want to get the basic core functionality of our app working.

The Stopwatch Component 🏗️

A "speedrun timer" is essentially just a stopwatch with speedrun-related functionality built on top of it, so we can begin by creating a simple stopwatch component with a composable:

// Stopwatch.vue
<script setup>
import { useStopwatch } from '../composables/stopwatch';

const {
  timerTxt,
  onTimerStart,
  onTimerStop,
  onTimerReset
} = useStopwatch();

</script>

<template>
  <div>
    <p>{{ timerTxt }}</p>
    <button @mousedown="onTimerStart">Start</button>
    <button @mousedown="onTimerStop">Stop</button>
    <button @mousedown="onTimerReset">Reset</button>
  </div>
</template>

<style scoped>
button {
  margin: 0 5px;
}
</style>

As you can see, there's nothing fancy here, just 3 buttons with event functions and some text to display our timer.

We'll use it directly in App.vue for now:

// App.vue
<script setup>
import Stopwatch from './components/Stopwatch.vue';
</script>

<template>
  <div>
    <stopwatch></stopwatch>
  </div>
</template>

The Stopwatch Composable 📝

Now let's build our stopwatch composable. We can begin by declaring some necessary variables. I've commented on their uses in the code below:

let [milliseconds, seconds, minutes, hours] = [0, 0, 0, 0]; // state of the values used for the stopwatch display
let timer; // keeps track of an active timer
let paused = false; // keeps track of paused state
let prevTime; // the last time the timer was updated

const timerTxt = ref(getTimeFormatString()); // the timer display text value

onTimerStart() 🏃

Next, we'll want to create our onTimerStart function that will be triggered on a start button press (we'll likely move this to a keypress later, but we'll keep the buttons for now):

function onTimerStart() {
  if (timer) {
    return;
  }

  paused = false;
  prevTime = new Date();
  timer = setInterval(incrementTimer, 10);
}

Breaking this down, first we'll want to detect if the timer is already running. If it is, we can short circuit the function and do nothing. Next we ensure our timer isn't in a paused state, update the time our timer was last ran, and start the timer by calling setInterval and telling it to run our function incrementTimer every 10 milliseconds.

Non-Event Functions 🤓

Speaking of the incrementTimer function, let's go ahead and define that function and the other functions it will reference:

function incrementTimer() {
  if (paused) {
    return;
  }

  const elapsedMilliseconds = ((new Date()) - prevTime);
  setTimeValues(elapsedMilliseconds);
  timerTxt.value = getTimeFormatString();
  prevTime = new Date();
}

function setTimeValues(elapsedMilliseconds) {
  milliseconds += elapsedMilliseconds;

  if (milliseconds >= 1000) {
    seconds += (milliseconds - (milliseconds % 1000)) / 1000;
    milliseconds = milliseconds % 1000;
    if (seconds >= 60) {
      minutes += (seconds - (seconds % 60)) / 60;
      seconds = seconds % 60;
      if (minutes >= 60) {
        hours += (minutes - (minutes % 60)) / 60;
        minutes = minutes % 60;
      }
    }
  }
}

function getTimeFormatString() {
  const h = hours.toLocaleString('en-US', {
    minimumIntegerDigits: 2,
    useGrouping: false
  });
  const min = minutes.toLocaleString('en-US', {
    minimumIntegerDigits: 2,
    useGrouping: false
  });
  const s = seconds.toLocaleString('en-US', {
    minimumIntegerDigits: 2,
    useGrouping: false
  });
  const ms = milliseconds.toLocaleString('en-US', {
    minimumIntegerDigits: 3,
    useGrouping: false
  });

  return `${h}:${min}:${s}.${ms}`;
}

We'll examine these functions and their usage below:

incrementTimer() ➕

This code was designed to be called at any given moment and increment the timer display based on how much time has elapsed from the previous call to the current one. We can't guarantee that incrementTimer will be called every 10 milliseconds as setInterval merely places incrementTimer into a queue after 10 seconds. The actual execution time of the function can easily vary, making it very apparent why we should measure the time between one call to the next instead!

setTimeValues(elapsedMilliseconds) ⌚

This function is designed to take in any amount of elapsed time and increment the time values appropriately. We could have assumed a consistent time frame between each execution (e.g. 1 second/1000 milliseconds), but that would not have been a reliable solution given the single-threaded nature of JavaScript and the potential for the thread to hang, sleep, or freeze. Therefore, we need our timer to pick up where it left off. To do this, I needed the algorithm to account for any amount of time passed (even if it took 5 minutes from one call to the next) and take in that parameter and increment it onto the timer values. Which is why you see code like this: seconds += (milliseconds - (milliseconds % 1000)) / 1000; and milliseconds = milliseconds % 1000;

For example, if our function was called 5001 milliseconds from the last call, then we know we should be adding 5 seconds and 1 millisecond to our time values:

seconds += (5001 - (5001 % 1000)) / 1000; //This equals 5
milliseconds = 5001 % 1000; //This equals 1

getTimeFormatString() 📝

This code just formats the timer values into the time display format that we want.

onTimerStop() 🛑

Moving on to the onTimerStop function, things get less complicated. We need to set paused = true;, stop the timer, and finally clear the timer.

function onTimerStop() {
  paused = true;
  clearInterval(timer);
  timer = null;
}

onTimerReset() 🔃

Last but not least, we'll want to reset our timer. This code is very similar to onTimerStop, but we also want to reset our timer values to their default values after stopping and clearing the timer.

function onTimerReset() {
  paused = true;
  clearInterval(timer);
  [milliseconds, seconds, minutes, hours] = [0, 0, 0, 0];
  paused = false;
  timerTxt.value = getTimeFormatString();
  timer = null;
}

Full Composable 💯

That'll be everything we need for now so here's the full composable code:

// stopwatch.js
import { ref } from "vue";

export function useStopwatch() {
  let [milliseconds, seconds, minutes, hours] = [0, 0, 0, 0];
  let timer;
  let paused = false;
  let prevTime;

  const timerTxt = ref(getTimeFormatString());

  function setTimeValues(elapsedMilliseconds) {
    milliseconds += elapsedMilliseconds;

    if (milliseconds >= 1000) {
      seconds += (milliseconds - (milliseconds % 1000)) / 1000;
      milliseconds = milliseconds % 1000;
      if (seconds >= 60) {
        minutes += (seconds - (seconds % 60)) / 60;
        seconds = seconds % 60;
        if (minutes >= 60) {
          hours += (minutes - (minutes % 60)) / 60;
          minutes = minutes % 60;
        }
      }
    }
  }

  function getTimeFormatString() {
    const h = hours.toLocaleString("en-US", {
      minimumIntegerDigits: 2,
      useGrouping: false,
    });
    const min = minutes.toLocaleString("en-US", {
      minimumIntegerDigits: 2,
      useGrouping: false,
    });
    const s = seconds.toLocaleString("en-US", {
      minimumIntegerDigits: 2,
      useGrouping: false,
    });
    const ms = milliseconds.toLocaleString("en-US", {
      minimumIntegerDigits: 3,
      useGrouping: false,
    });

    return `${h}:${min}:${s}.${ms}`;
  }

  function incrementTimer() {
    if (paused) {
      return;
    }

    const elapsedMilliseconds = new Date() - prevTime;
    setTimeValues(elapsedMilliseconds);
    timerTxt.value = getTimeFormatString();
    prevTime = new Date();
  }

  function onTimerStart() {
    if (timer) {
      return;
    }

    paused = false;
    prevTime = new Date();
    timer = setInterval(incrementTimer, 10);
  }

  function onTimerStop() {
    paused = true;
    clearInterval(timer);
    timer = null;
  }

  function onTimerReset() {
    paused = true;
    clearInterval(timer);
    [milliseconds, seconds, minutes, hours] = [0, 0, 0, 0];
    paused = false;
    timerTxt.value = getTimeFormatString();
    timer = null;
  }

  return {
    timerTxt,
    onTimerStart,
    onTimerStop,
    onTimerReset,
  };
}

Seeing the Code in Action! 🎬

Now to run our code and see it in action! I've put the code for Chapter 1 inside of a CodeSandbox so we can visualize what our code looks like while it's running:

Conclusion 💭

Ta-da! We now have a basic stopwatch timer working. In Chapter 2, we'll enhance the timer a bit and abstract the logic to make the code more portable.

Here's the GitHub repo for this project. If you haven't already, be sure to give me a follow on here and other socials to see updates to this series and more!

Making a Speedrun Timer: Prologue

Kev — Mon, 27 Mar 2023 06:45:49 +0000

Introduction 👋

Since 2015, I've been a part of the speedrunning community by running a game called Banjo Kazooie on the Nintendo 64. A common tool used amongst the community is a speedrun timer known as LiveSplit. While this timer is already a phenomenal tool, I figured I would make my own as part of a fun passion project and write a dev blog series about it!

Requirements:

In terms of requirements for this project, I'll say there won't be many initially. Since it's purely a passion project, I'll keep it simple to start with and add new functionality over time as I see fit.

To start I think we'll just need:

A Stopwatch ⏱️

A accurate stopwatch timer with hours, minutes, seconds, and milliseconds displayed back to the user. Special care is needed around accuracy, as we want to make sure the correct times can be reported when submitting a time for a speedrun.

Event Triggers ⚡

We'll need event triggers for "start", "pause", "reset", "split", and "undo split". These events will be triggered by button press or key press. It's likely that we'll need to add more events but this will get us started.

Split Tracking 📊

We need a way to keep track of splits and appropriate split data like the name, best time for that split, split history, etc. After all, what good would this timer be without splits?

Import/Export Functionality 💾

Not only do we need to track our splits, but we need to be able to import and export split data to keep the application portable and accessible on multiple platforms and multiple users.

A Customizable Interface 🎨🧑‍🎨

One of the biggest complaints I have about LiveSplit is its lack of interface customization. I shouldn't say lack because it's actually pretty customizable, but I feel as though the interface leaves a lot to be desired. It feels like EVERY timer looks the same barring different color schemes, and what you can do with the space you're given feels very limited. If you attempt to use horizontal splits it just becomes a nightmare. Therefore, I want to see if we can create a highly customizable and sleek user interface for displaying speedrun data.

A Creative Mindset! 🧠💡

A creative mindset to have the ability to add unique functionality whenever and idea pops in the brain. This is where YOU, the community, can also contribute! Feel free to message me or comment with any features you'd like to see on a speedrun timer!

Tech Stack 🧑‍💻

I debated for some time on whether or not I wanted to make this a command line app, a desktop GUI app, or a web app. Ultimately I decided to go with a PWA built in Vue due to the accessibility and portability of the browser. Building an app with Vue will allow us to make our interface highly customizable and utilize Vue's amazing developer experience to build our application in an efficient manner 💪.

At this point in the project, I'm not sure if we'll end up needing a backend (as that insinuates cost💲) but if we do, we'll cross that bridge when we get to it. Potential technologies we could use on the backend include GoLang, Python, or C# (.NET) with probably some sort of serverless database. These are just backend technologies I'm familiar with and are quick to get up and running.

Project Setup 🔧

Vite

To setup our new Vue + PWA application we'll need to start by creating our project directory structure. To do this we will be using vite to create our initial application and take out things we don't need and add in the components needed to make our application PWA compliant.

First we'll run: npm create vite@latest

Vue

After that we'll fill out the necessary prompts to get our vanilla JavaScript Vue 3 application up and running and remove all components (only the HelloWorld component should exist) and assets (icons, .svg, .png, etc).

PWA Compliance

Next we need to make our application PWA compliant so we can download it as an application from the browser. To make this easy on ourselves we will be using an npm package called vite-plugin-pwa which will take care of a lot of the setup.

Install with: npm i vite-plugin-pwa -D

However, that won't be all. We need to modify our project's vite.config.js and index.html files with the appropriate information and references to icons. I won't go into too much detail on how or why to do this but you can read the documentation here on what you need to get started.

Here's what I've written in my files:

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="favicon" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Speedrun Timer</title>
    <meta name="description" content="A highly customizable speedrun timer">
    <link rel="apple-touch-icon" href="/apple-touch-icon.png" sizes="180x180">
    <link rel="mask-icon" href="favicon" color="#FFFFFF">
    <meta name="theme-color" content="#ffffff">
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

vite.config.js

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { VitePWA } from "vite-plugin-pwa";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    VitePWA({
      registerType: "autoUpdate",
      devOptions: {
        enabled: true,
      },
      manifest: {
        name: 'Speedrun Timer',
        short_name: 'STA',
        description: 'A highly customizable speedrun timer app',
        theme_color: '#ffffff',
        icons: [
          {
            src: 'logo-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: 'logo-512x512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      }
    }),
  ],
});

Once that's done we should be good to get started on our project! In the next chapter of this series we'll begin building out this application and start coding.

Follow Along 🤳

I'm completely new to writing dev blogs, so take it easy one me! I've wanted to write a dev blog for a long time so I'm excited to see how it goes!

If you'd like to follow along, be sure give me a follow on here, my socials, and the GitHub Repository for this project!