Refactor activity log types (#127)

* prototype activity log layout

* fix types

* refactor types

* refactor names

* refactor variable names

* fix sorting bug

* docs

Author: juliangruber

main/activity-log.js

@@ -1,47 +1,46 @@
 'use strict'
 
-/** @typedef {import('./typings').ActivityEvent}  ActivityEvent */
-/** @typedef {import('./typings').ActivityEntry}  ActivityEntry */
+/** @typedef {import('./typings').Activity} Activity */
+/** @typedef {import('./typings').RecordActivityOptions}  RecordActivityOptions */
 
 const Store = require('electron-store')
+const crypto = require('node:crypto')
+
 const activityLogStore = new Store({
   name: 'activity-log'
 })
 
 class ActivityLog {
   #entries
-  #lastId
 
   constructor () {
     this.#entries = loadStoredEntries()
-    this.#lastId = Number(this.#entries.at(-1)?.id ?? 0)
   }
 
   /**
-   * @param {ActivityEvent} args
-   * @returns {ActivityEntry}
+   * @param {RecordActivityOptions} args
+   * @returns {Activity}
    */
-  recordEvent ({ source, type, message }) {
-    const nextId = ++this.#lastId
-    /** @type {ActivityEntry} */
-    const entry = {
-      id: String(nextId),
+  recordActivity ({ source, type, message }) {
+    /** @type {Activity} */
+    const activity = {
+      id: crypto.randomUUID(),
       timestamp: Date.now(),
       source,
       type,
       message
     }
     // Freeze the data to prevent ActivityLog users from accidentally changing our store
-    Object.freeze(entry)
+    Object.freeze(activity)
 
-    this.#entries.push(entry)
+    this.#entries.push(activity)
 
     if (this.#entries.length > 100) {
-      // Delete the oldest entry to keep ActivityLog at constant size
+      // Delete the oldest activity to keep ActivityLog at constant size
       this.#entries.shift()
     }
     this.#save()
-    return entry
+    return activity
   }
 
   getAllEntries () {
@@ -56,12 +55,12 @@ class ActivityLog {
   }
 
   #save () {
-    activityLogStore.set('events', this.#entries)
+    activityLogStore.set('activities', this.#entries)
   }
 }
 
 /**
- * @returns {ActivityEntry[]}
+ * @returns {Activity[]}
  */
 function loadStoredEntries () {
   // A workaround to fix false TypeScript errors

main/index.js

@@ -15,8 +15,8 @@ const { setupAppMenu } = require('./app-menu')
 const { ActivityLog } = require('./activity-log')
 const { ipcMain } = require('electron/main')
 
-/** @typedef {import('./typings').ActivityEvent} ActivityEvent */
-/** @typedef {import('./typings').ActivityEntry} ActivityEntry */
+/** @typedef {import('./typings').Activity} Activity */
+/** @typedef {import('./typings').RecordActivityOptions} RecordActivityOptions */
 
 const inTest = (process.env.NODE_ENV === 'test')
 const isDev = !app.isPackaged && !inTest
@@ -94,18 +94,18 @@ const activityLog = new ActivityLog()
 let isActivityStreamFlowing = false
 
 /**
- * @param {ActivityEvent} event
+ * @param {RecordActivityOptions} opts
  */
-function recordActivity (event) {
-  const entry = activityLog.recordEvent(event)
-  if (isActivityStreamFlowing) emitActivity(entry)
+function recordActivity (opts) {
+  const activity = activityLog.recordActivity(opts)
+  if (isActivityStreamFlowing) emitActivity(activity)
 }
 
 /**
- * @param {ActivityEntry} entry
+ * @param {Activity} activity
  */
-function emitActivity (entry) {
-  ipcMain.emit(ipcMainEvents.ACTIVITY_LOGGED, entry)
+function emitActivity (activity) {
+  ipcMain.emit(ipcMainEvents.ACTIVITY_LOGGED, activity)
 }
 
 function resumeActivityStream () {

main/preload.js

@@ -6,10 +6,10 @@ contextBridge.exposeInMainWorld('electron', {
   resumeActivityStream: () => ipcRenderer.invoke('station:resumeActivityStream'),
 
   /**
-   * @param {(activityEntry: import('./typings').ActivityEntry) => void} callback
+   * @param {(Activity: import('./typings').Activity) => void} callback
    */
   onActivityLogged (callback) {
-    ipcRenderer.on('station:activity-logged', (_event, entry) => callback(entry))
+    ipcRenderer.on('station:activity-logged', (_event, activity) => callback(activity))
   },
 
   saturnNode: {

main/test/activity-log.test.js

@@ -4,47 +4,47 @@ const assert = require('assert').strict
 const { ActivityLog } = require('../activity-log')
 const { assertTimestampIsCloseToNow, pickProps } = require('./test-helpers')
 
-/** @typedef {import('../typings').ActivityEvent} ActivityEvent */
+/** @typedef {import('../typings').RecordActivityOptions} RecordActivityOptions */
 
 describe('ActivityLog', function () {
   beforeEach(function () { return ActivityLog.reset() })
 
-  it('record events and assign them timestamp and id ', function () {
+  it('record activities and assign them timestamp and id ', function () {
     const activityLog = new ActivityLog()
-    const entryCreated = activityLog.recordEvent(givenActivity({
+    const activityCreated = activityLog.recordActivity(givenActivity({
       source: 'Station',
       type: 'info',
       message: 'Hello world!'
     }))
 
     assert.strictEqual(activityLog.getAllEntries().length, 1)
-    assert.deepStrictEqual(entryCreated, activityLog.getAllEntries()[0])
+    assert.deepStrictEqual(activityCreated, activityLog.getAllEntries()[0])
 
-    const { timestamp, ...entry } = activityLog.getAllEntries()[0]
-    assert.deepStrictEqual(entry, {
+    const { timestamp, ...activity } = activityLog.getAllEntries()[0]
+    assert.deepStrictEqual(activity, {
       id: '1',
       source: 'Station',
       type: 'info',
       message: 'Hello world!'
     })
 
-    assertTimestampIsCloseToNow(timestamp, 'event.timestamp')
+    assertTimestampIsCloseToNow(timestamp, 'activity.timestamp')
   })
 
   it('assigns unique ids', function () {
     const activityLog = new ActivityLog()
-    activityLog.recordEvent(givenActivity({ message: 'one' }))
-    activityLog.recordEvent(givenActivity({ message: 'two' }))
+    activityLog.recordActivity(givenActivity({ message: 'one' }))
+    activityLog.recordActivity(givenActivity({ message: 'two' }))
     assert.deepStrictEqual(activityLog.getAllEntries().map(it => pickProps(it, 'id', 'message')), [
       { id: '1', message: 'one' },
       { id: '2', message: 'two' }
     ])
   })
 
-  it('preserves events across restarts', function () {
-    new ActivityLog().recordEvent(givenActivity({ message: 'first run' }))
+  it('preserves activities across restarts', function () {
+    new ActivityLog().recordActivity(givenActivity({ message: 'first run' }))
     const activityLog = new ActivityLog()
-    activityLog.recordEvent(givenActivity({ message: 'second run' }))
+    activityLog.recordActivity(givenActivity({ message: 'second run' }))
     assert.deepStrictEqual(activityLog.getAllEntries().map(it => pickProps(it, 'id', 'message')), [
       { id: '1', message: 'first run' },
       { id: '2', message: 'second run' }
@@ -56,19 +56,19 @@ describe('ActivityLog', function () {
 
     const log = new ActivityLog()
     for (let i = 0; i < 110; i++) {
-      log.recordEvent(givenActivity({ message: `event ${i}` }))
+      log.recordActivity(givenActivity({ message: `activity ${i}` }))
     }
     const entries = log.getAllEntries()
     assert.deepStrictEqual(
       [entries.at(0)?.message, entries.at(-1)?.message],
-      ['event 10', 'event 109']
+      ['activity 10', 'activity 109']
     )
   })
 })
 
 /**
- * @param {Partial<ActivityEvent>} [props]
- * @returns {ActivityEvent}
+ * @param {Partial<RecordActivityOptions>} [props]
+ * @returns {RecordActivityOptions}
  */
 function givenActivity (props) {
   return {

main/typings.d.ts

@@ -1,19 +1,22 @@
 export type ActivitySource = 'Station' | 'Saturn';
-export type ActivityEventType = 'info' | 'error';
+export type ActivityType = 'info' | 'error';
 
-export interface ActivityEvent {
-  type: ActivityEventType;
+export interface Activity {
+  id: string;
+  timestamp: number;
+  type: ActivityType;
   source: ActivitySource;
   message: string;
 }
 
-export interface ActivityEntry extends ActivityEvent {
-  id: string;
-  timestamp: number;
+export interface RecordActivityOptions {
+  type: ActivityType;
+  source: ActivitySource;
+  message: string;
 }
 
 export interface Context {
-  recordActivity(event: ActivityEvent): void;
+  recordActivity(activity: RecordActivityOptions): void;
   resumeActivityStream(): void;
 
   showUI: () => void

renderer/src/main.tsx

@@ -3,6 +3,7 @@ import ReactDOM from 'react-dom/client'
 import { BrowserRouter } from 'react-router-dom'
 import App from './App'
 import './index.css'
+import { Activity } from '../../main/typings'
 
 ReactDOM.createRoot(
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -15,8 +16,22 @@ ReactDOM.createRoot(
   </React.StrictMode>
 )
 
-window.electron.onActivityLogged(entry => {
-  console.log('[ACTIVITY] %j', entry)
+const activities: Activity[] = []
+
+window.electron.onActivityLogged(activity => {
+  activities.push(activity)
+  // In case two activities were recorded in the same millisecond, fall back to
+  // sorting by their IDs, which are guaranteed to be unique and therefore
+  // provide a stable sorting.
+  activities.sort((a, b) => {
+    return a.timestamp !== b.timestamp
+      ? b.timestamp - a.timestamp
+      : a.id.localeCompare(b.id)
+  })
+  if (activities.length > 100) activities.shift()
+
+  console.log('[ACTIVITY] %j', activity)
+  console.log('[ACTIVITIES]', activities)
 })
 
 window.electron.resumeActivityStream().then(() => {

renderer/src/typings.d.ts

@@ -1,10 +1,10 @@
-import { ActivityEntry } from '../main/typings'
+import { Activity } from '../main/typings'
 
 export declare global {
   interface Window {
     electron: {
-      resumeActivityStream(): Promise<ActivityEntry[]>,
-      onActivityLogged(callback: (activityEntry: ActivityEntry) => void),
+      resumeActivityStream(): Promise<Activity[]>,
+      onActivityLogged(callback: (activity: Activity) => void),
 
       saturnNode: {
         start:() => Promise<void>,