Add documentation for utils and filters (#264)

Author: edwardhorsford

app/filters/form-attributes.js

@@ -38,7 +38,15 @@ const formatAnswer = (value, options = {}) => {
   return yesValue ? `${yesPrefix} - ${yesValue}` : yesPrefix
 }
 
-// Convert an integer to its ordinal name (first, second, third, etc)
+/**
+ * Convert a 1-based integer to its ordinal name
+ *
+ * @param {number} integer - Integer between 1 and 10
+ * @returns {string} Ordinal name
+ * @example
+ * getOrdinalName(1) // 'first'
+ * getOrdinalName(3) // 'third'
+ */
 const getOrdinalName = (integer) =>
 {
   const ordinals = [
@@ -66,7 +74,15 @@ const getOrdinalName = (integer) =>
   return ordinals[parsedInteger]
 }
 
-// Convert a zero-based index to its ordinal name (0 => first, 1 => second, etc)
+/**
+ * Convert a 0-based index to its ordinal name (0 → 'first', 1 → 'second', etc)
+ *
+ * @param {number} integer - 0-based index
+ * @returns {string} Ordinal name
+ * @example
+ * getOrdinalNameIndex0(0) // 'first'
+ * getOrdinalNameIndex0(2) // 'third'
+ */
 const getOrdinalNameIndex0 = (integer) => getOrdinalName(Number(integer) + 1)
 
 module.exports = {

app/filters/formatting.js

@@ -2,6 +2,13 @@
 
 const { safe: nunjucksSafe } = require('nunjucks/src/filters')
 
+/**
+ * Render a value to the browser console via an inline script tag (for template debugging)
+ *
+ * @param {*} a - Value to log
+ * @param {string | null} [description] - Optional label shown before the value
+ * @returns {string} Safe HTML containing an inline script
+ */
 const log = (a, description = null) => {
   if (description) {
     description = `console.log("${description}:");`
@@ -127,8 +134,9 @@ const getUsername = function (userId, options = {}) {
 }
 
 /**
+ * Return the full Nunjucks template context — useful for debugging
  *
- * @returns {object} The context data
+ * @returns {object} The current Nunjucks context object
  */
 const getContext = function () {
   return this.ctx

app/filters/nunjucks.js

@@ -14,6 +14,13 @@ const findById = (array, id) => {
   return array.find((item) => item.id === id)
 }
 
+/**
+ * Append an item to an array, returning a new array (deep clones the item)
+ *
+ * @param {Array} array - Array to append to
+ * @param {*} item - Item to append (will be deep cloned)
+ * @returns {Array} New array with item appended
+ */
 const push = (array, item) => {
   const newArray = [...array]
   newArray.push(_.cloneDeep(item)) // clone needed to stop this mutating original

app/lib/utils/arrays.js

@@ -8,6 +8,7 @@ const config = require('../../config')
  * Get today's clinics
  *
  * @param {Array} clinics - Array of all clinics
+ * @returns {Array} Clinics scheduled for today
  */
 const getTodaysClinics = (clinics) => {
   const today = dayjs().startOf('day')
@@ -19,6 +20,7 @@ const getTodaysClinics = (clinics) => {
  *
  * @param {Array} events - Array of all events
  * @param {string} clinicId - Clinic ID to filter by
+ * @returns {Array} Events belonging to the given clinic
  */
 const getClinicEvents = (events, clinicId) => {
   if (!events || !clinicId) return []
@@ -31,6 +33,7 @@ const getClinicEvents = (events, clinicId) => {
  * Format clinic time slot
  *
  * @param {string} dateTime - ISO date string
+ * @returns {string} Time formatted as HH:MM
  */
 const formatTimeSlot = (dateTime) => {
   const date = new Date(dateTime)
@@ -74,7 +77,8 @@ const getClinicHours = (clinic) => {
  * Get clinics filtered by time period
  *
  * @param {Array} clinics - Array of all clinics
- * @param {string} filter - Filter to apply (today, upcoming, completed, all)
+ * @param {string} [filter='all'] - Filter to apply: 'today', 'upcoming', 'completed', or 'all'; excludes clinics older than 2 weeks
+ * @returns {Array} Filtered and sorted clinics
  */
 const getFilteredClinics = (clinics, filter = 'all') => {
   const today = dayjs().startOf('day')

app/lib/utils/clinics.js

@@ -146,7 +146,8 @@ const isValidDate = (dateInput) => {
  * Format a date in UK format
  *
  * @param {string | Array | object} dateString - ISO date string, array [day, month, year], [month, year], or object {day, month, year}, {month, year}
- * @param {string} format - Optional format string
+ * @param {string} [format='D MMMM YYYY'] - Optional format string
+ * @returns {string} Formatted date string, or empty string if invalid
  */
 const formatDate = (dateString, format = 'D MMMM YYYY') => {
   if (!dateString) return ''
@@ -262,7 +263,8 @@ const formatMonthYear = (input, format = 'MMMM YYYY') => {
  * Format a time in UK format
  *
  * @param {string} dateString - ISO date string
- * @param {string} format - Optional format string
+ * @param {string} [format='H:mm'] - Optional format string
+ * @returns {string} Formatted time string
  */
 const formatTime = (dateString, format = 'H:mm') => {
   if (!dateString) return ''
@@ -312,7 +314,8 @@ const formatTimeRange = (times) => {
  * Format a date and time
  *
  * @param {string} dateString - ISO date string
- * @param {string} format - Optional format string
+ * @param {string} [format='D MMMM YYYY, HH:mm'] - Optional format string
+ * @returns {string} Formatted date-time string
  */
 const formatDateTime = (dateString, format = 'D MMMM YYYY, HH:mm') => {
   if (!dateString) return ''
@@ -385,8 +388,12 @@ const formatRelativeDate = (dateInput, withoutSuffix = false) => {
 
 /**
  * Format a year as relative to the current year
+ *
  * @param {string|number|object} yearInput - Year as number, string, or object {year: 2024}
- * @returns {string} Relative year description (e.g., "this year", "last year", "3 years ago")
+ * @returns {string} Relative year description
+ * @example
+ * relativeYear(2025) // 'last year' (if current year is 2026)
+ * relativeYear(2020) // '6 years ago'
  */
 const relativeYear = (yearInput) => {
   if (!yearInput) return ''
@@ -436,10 +443,14 @@ const relativeYear = (yearInput) => {
 }
 
 /**
- * Calculate the number of days since a given date
- * @param {string | object | array } dateInput - Input date in one of ISO date string, keyed object, array of [day, month, year], [month, year], or {month, year}
+ * Calculate the number of days since a given date (positive = past, negative = future)
+ *
+ * @param {string | object | Array} dateInput - ISO date string, array [day, month, year], or object {day, month, year}
  * @param {string | Dayjs | null} [compareDate] - Optional reference date (defaults to today)
- * @returns {number} Number of days since the date (positive integer for past dates)
+ * @returns {number} Days since the date (positive for past dates)
+ * @example
+ * daysSince('2026-03-05') // 7 (if today is 2026-03-12)
+ * daysSince('2026-03-15') // -3 (future date)
  */
 const daysSince = (dateInput, compareDate = null) => {
   if (!dateInput) return 0
@@ -592,10 +603,11 @@ const now = () => {
 }
 
 /**
- * Format a date range
+ * Format a date range, collapsing shared day/month/year as appropriate
  *
- * @param {string} startDate - ISO date string
- * @param {string} endDate - ISO date string
+ * @param {string} startDate - ISO date string for range start
+ * @param {string} endDate - ISO date string for range end
+ * @returns {string} Formatted range, e.g. '1 - 5 March 2026' or '1 March - 5 April 2026'
  */
 const formatDateRange = (startDate, endDate) => {
   if (!startDate || !endDate) return ''

app/lib/utils/dates.js

@@ -12,6 +12,14 @@ const getEvent = (data, eventId) => {
   return data.events.find((e) => e.id === eventId) || null
 }
 
+/**
+ * Get event data bundle for a given clinic and event ID
+ *
+ * @param {object} data - Session data
+ * @param {string} clinicId - Clinic ID
+ * @param {string} eventId - Event ID
+ * @returns {object | null} Bundle of {clinic, event, participant, location, unit} or null if not found
+ */
 const getEventData = (data, clinicId, eventId) => {
   const clinic = data.clinics.find((c) => c.id === clinicId)
   if (!clinic) return null

app/lib/utils/event-data.js

@@ -15,9 +15,10 @@ const getParticipant = (data, participantId) => {
 }
 
 /**
- * Get full name of participant
+ * Get full name (first, middle, last) of a participant as a Nunjucks-safe string
  *
  * @param {object} participant - Participant object
+ * @returns {string} Full name, or empty string if unavailable
  */
 const getFullName = (participant) => {
   if (!participant?.demographicInformation) return ''
@@ -28,9 +29,12 @@ const getFullName = (participant) => {
 }
 
 /**
- * Get full name of participant
+ * Get full name in reversed 'Last, First Middle' format
  *
  * @param {object} participant - Participant object
+ * @returns {string} Reversed full name, or empty string if unavailable
+ * @example
+ * getFullNameReversed(participant) // 'Smith, Jane Louise'
  */
 const getFullNameReversed = (participant) => {
   if (!participant?.demographicInformation) return ''
@@ -39,9 +43,10 @@ const getFullNameReversed = (participant) => {
 }
 
 /**
- * Get short name (first + last) of participant
+ * Get short name (first + last only) of participant as a Nunjucks-safe string
  *
  * @param {object} participant - Participant object
+ * @returns {string} Short name, or empty string if unavailable
  */
 const getShortName = (participant) => {
   if (!participant?.demographicInformation) return ''
@@ -54,6 +59,7 @@ const getShortName = (participant) => {
  *
  * @param {Array} participants - Array of all participants
  * @param {string} sxNumber - SX number to search for
+ * @returns {object | undefined} Matching participant or undefined
  */
 const findBySXNumber = (participants, sxNumber) => {
   return participants.find((p) => p.sxNumber === sxNumber)
@@ -157,12 +163,14 @@ const getParticipantClinicHistory = (data, participantId, options = {}) => {
 }
 
 // Helper functions for common use cases
+/** Get the most recent historic clinic/event pair for a participant */
 const getParticipantMostRecentClinic = (data, participantId) =>
   getParticipantClinicHistory(data, participantId, {
     filter: 'historic',
     mostRecent: true
   })
 
+/** Get the start time of the participant's most recent clinic, or false if none */
 const getParticipantMostRecentClinicDate = (data, participantId) => {
   const clinic = getParticipantClinicHistory(data, participantId, {
     filter: 'historic',
@@ -173,9 +181,11 @@ const getParticipantMostRecentClinicDate = (data, participantId) => {
   } else return false
 }
 
+/** Get all past clinic/event pairs for a participant */
 const getParticipantHistoricClinics = (data, participantId) =>
   getParticipantClinicHistory(data, participantId, { filter: 'historic' })
 
+/** Get all upcoming clinic/event pairs for a participant */
 const getParticipantUpcomingClinics = (data, participantId) =>
   getParticipantClinicHistory(data, participantId, { filter: 'upcoming' })