From 711745860d0d9940401b90f12f18ed00a877c068 Mon Sep 17 00:00:00 2001
From: rich <rich.james@dxw.com>
Date: Fri, 13 Sep 2024 10:46:20 +0100
Subject: [PATCH] Describe utils in with JS Doc

JS Doc is a widely used method of documenting Javascript.
It is widely supported by IDEs and runs in IDEs so doesn't require an
application depedencies - it's on the developer to keep their env up to
date.
It gives many of the benefits of Typescript without the learning curve
and the build step. It can (and should) be added optionally to improve
documentation and developer experience but it is optional won't effect
the run time code.
---
 utils.js | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/utils.js b/utils.js
index c8aa7b3..4a9feb7 100644
--- a/utils.js
+++ b/utils.js
@@ -1,4 +1,22 @@
 import { readFile } from "fs/promises";
+
+/**
+ * @typedef {Object} PersistedData
+ * @property {StoredRepo[]} repos - An array of repos.
+ * @property {number} totalRepos - The total number of repos.
+ * @property {string} org - The name of the Github organisation the repos belong to.
+ */
+
+/**
+ * @typedef {PersistedData} RepoData
+ * @property {UiRepo[]} repos - An array of repos.
+ */
+
+/**
+ * Maps the persisted repo data from storage to a format suitable for the UI
+ * @param {PersistedData} persistedData
+ * @returns {RepoData}
+ */
 export const mapRepoFromStorageToUi = (persistedData) => {
   const mappedRepos = persistedData.repos.map((repo) => {
     const newDate = new Date(repo.updatedAt).toLocaleDateString();
@@ -13,6 +31,11 @@ export const mapRepoFromStorageToUi = (persistedData) => {
   return { ...persistedData, repos: mappedRepos, totalRepos };
 };
 
+/**
+ * Reads the persisted repo data from a JSON file
+ * @param {string} filePath - The path to the file to read from
+ * @returns {PersistedData}
+ */
 export const getReposFromJson = async (filePath) => {
   const reposJson = await readFile(filePath, { encoding: "utf-8" });
   const persistedData = JSON.parse(reposJson);
@@ -20,6 +43,45 @@ export const getReposFromJson = async (filePath) => {
   return persistedData;
 };
 
+/**
+ * @typedef {Object} ApiRepo
+ * @property {string} name - The name of the repo Eg "dalmation".
+ * @property {string} description - A brief description of the repo.
+ * @property {string} html_url - The URL to the repo on GitHub for humans.
+ * @property {string} pulls_url - The API url to get more info on pull requests for this repo.
+ * @property {string} issues_url - The API url to get more info on issues for this repo.
+ * @property {string} updated_at - The date the repo was last updated in ISO8601 format.
+ * @property {string} language - The primary language the repo is written in.
+ * @property {string[]} topics - An array of topics associated with the repo - conventially in dxw this is used to list the owners of the repo (EG govpress, delivery-plus).
+ * @property {number} open_issues - The number of open issues on the repo.
+ * @property {string[]} dependencies - An array of dependencies used by the repo.
+ */
+
+/**
+ * @typedef {Object} StoredRepo
+ * @property {string} name - The name of the repo Eg "dalmation".
+ * @property {string} description - A brief description of the repo.
+ * @property {string} htmlUrl - The URL to the repo on GitHub for humans.
+ * @property {string} apiUrl - The URL to the repo on GitHub for computers.
+ * @property {string} pullsUrl - The API url to get more info on pull requests for this repo.
+ * @property {string} issuesUrl - The API url to get more info on issues for this repo.
+ * @property {string} updatedAt - The date the repo was last updated in ISO8601 format.
+ * @property {string} language - The primary language the repo is written in.
+ * @property {string[]} topics - An array of topics associated with the repo - conventially in dxw this is used to list the owners of the repo (EG govpress, delivery-plus).
+ * @property {number} openIssues - The number of open issues on the repo.
+ * @property {string[]} dependencies - An array of dependencies used by the repo.
+ */
+
+/**
+ * @typedef {StoredRepo} UiRepo
+ * @property {Date} date - The date the repo was last updated in JS date format.
+ */
+
+/**
+ * Maps from an API repo to a StoredRepo
+ * @param {ApiRepo} repo
+ * @returns {StoredRepo}
+ */
 export const mapRepoFromApiForStorage = (repo) => ({
   name: repo.name,
   description: repo.description,