Refactor Determine Returns Period (#1676)

* Refactor Determine Returns Period

https://eaflood.atlassian.net/browse/WATER-4776

As part of the work to implement notifications in the system repo we have found some logic that will need to be duplicated in upcoming work.

This change lifts the determine returns periods logic into a shared service.

This can / will be used in multiple places and is complex enough to justify lifting into it own service and associated tests.

app/services/notifications/setup/determine-returns-period.service.js

@@ -0,0 +1,58 @@
+'use strict'
+
+/**
+ * Determines the returns period data for the provided returns period
+ * @module DetermineReturnsPeriod
+ */
+
+const { determineUpcomingReturnPeriods } = require('../../../lib/return-periods.lib.js')
+
+/**
+ * Determines the returns period data for the provided returns period
+ *
+ * All the returns periods will be calculated from the upcoming return periods.
+ *
+ * The `returnsPeriod` will be found and returned
+ *
+ * @param {string} returnsPeriod
+ *
+ * @returns {object} - the returns period and the if the period is `summer`
+ */
+function go(returnsPeriod) {
+  return {
+    returnsPeriod: _returnsPeriod(returnsPeriod),
+    summer: _summer(returnsPeriod)
+  }
+}
+
+/**
+ * Finds the provided returns period from the determined upcoming return periods.
+ *
+ * @private
+ */
+function _returnsPeriod(returnsPeriod) {
+  const periods = determineUpcomingReturnPeriods()
+
+  return periods.find((period) => {
+    return period.name === returnsPeriod
+  })
+}
+
+/**
+ * When the returns period is summer then need return 'true'
+ *
+ * The string value is used when querying crm which expects a string and not a boolean
+ *
+ * @param {string} returnsPeriod
+ *
+ *  @returns {string} - CRM expects a string of the boolean value ("true" | "false")
+ *
+ * @private
+ */
+function _summer(returnsPeriod) {
+  return returnsPeriod === 'summer' ? 'true' : 'false'
+}
+
+module.exports = {
+  go
+}

app/services/notifications/setup/review.service.js

@@ -6,11 +6,11 @@
  */
 
 const DetermineRecipientsService = require('./determine-recipients.service.js')
+const DetermineReturnsPeriodService = require('./determine-returns-period.service.js')
 const PaginatorPresenter = require('../../../presenters/paginator.presenter.js')
 const RecipientsService = require('./fetch-recipients.service.js')
 const ReviewPresenter = require('../../../presenters/notifications/setup/review.presenter.js')
 const SessionModel = require('../../../models/session.model.js')
-const { determineUpcomingReturnPeriods } = require('../../../lib/return-periods.lib.js')
 
 /**
  * Orchestrates fetching and presenting the data needed for the notifications setup review page
@@ -23,11 +23,9 @@ const { determineUpcomingReturnPeriods } = require('../../../lib/return-periods.
 async function go(sessionId, page = 1) {
   const session = await SessionModel.query().findById(sessionId)
 
-  const { returnsPeriod } = session
-  const selectedReturnsPeriod = _extractReturnPeriod(returnsPeriod)
-  const summer = _summer(returnsPeriod)
+  const { returnsPeriod, summer } = DetermineReturnsPeriodService.go(session.returnsPeriod)
 
-  const recipientsData = await RecipientsService.go(selectedReturnsPeriod.dueDate, summer)
+  const recipientsData = await RecipientsService.go(returnsPeriod.dueDate, summer)
 
   const recipients = DetermineRecipientsService.go(recipientsData)
 
@@ -47,18 +45,6 @@ async function go(sessionId, page = 1) {
   }
 }
 
-function _extractReturnPeriod(returnsPeriod) {
-  const periods = determineUpcomingReturnPeriods()
-
-  return periods.find((period) => {
-    return period.name === returnsPeriod
-  })
-}
-
-function _summer(returnsPeriod) {
-  return returnsPeriod === 'summer' ? 'true' : 'false'
-}
-
 module.exports = {
   go
 }

test/services/notifications/setup/determine-returns-period.service.test.js

@@ -0,0 +1,65 @@
+'use strict'
+
+// Test framework dependencies
+const Lab = require('@hapi/lab')
+const Code = require('@hapi/code')
+const Sinon = require('sinon')
+
+const { describe, it, afterEach, before, beforeEach } = (exports.lab = Lab.script())
+const { expect } = Code
+
+// Thing under test
+const DetermineReturnsPeriodService = require('../../../../app/services/notifications/setup/determine-returns-period.service.js')
+
+describe('Notifications Setup - Determine returns period service', () => {
+  const year = 2025
+
+  let clock
+  let returnsPeriod
+
+  before(async () => {
+    clock = Sinon.useFakeTimers(new Date(`${year}-01-01`))
+
+    returnsPeriod = 'quarterFour'
+  })
+
+  afterEach(() => {
+    clock.restore()
+  })
+
+  describe('when the returns period is not for summer', () => {
+    it('should return the returns period and summer "false"', () => {
+      const result = DetermineReturnsPeriodService.go(returnsPeriod)
+
+      expect(result).to.equal({
+        returnsPeriod: {
+          dueDate: new Date('2025-04-28'),
+          endDate: new Date('2025-03-31'),
+          name: 'quarterFour',
+          startDate: new Date('2025-01-01')
+        },
+        summer: 'false'
+      })
+    })
+  })
+
+  describe('when the returns period is for summer', () => {
+    beforeEach(async () => {
+      returnsPeriod = 'summer'
+    })
+
+    it('should return the returns period and summer "true"', () => {
+      const result = DetermineReturnsPeriodService.go(returnsPeriod)
+
+      expect(result).to.equal({
+        returnsPeriod: {
+          dueDate: new Date('2025-11-28'),
+          endDate: new Date('2025-10-31'),
+          name: 'summer',
+          startDate: new Date('2024-11-01')
+        },
+        summer: 'true'
+      })
+    })
+  })
+})

test/services/notifications/setup/review.service.test.js

@@ -5,7 +5,7 @@ const Lab = require('@hapi/lab')
 const Code = require('@hapi/code')
 const Sinon = require('sinon')
 
-const { describe, it, afterEach, before, beforeEach } = (exports.lab = Lab.script())
+const { describe, it, afterEach, before } = (exports.lab = Lab.script())
 const { expect } = Code
 
 // Test helpers
@@ -58,28 +58,4 @@ describe('Notifications Setup - Review service', () => {
       recipientsAmount: 1
     })
   })
-
-  describe('when the returns period is not for summer', () => {
-    beforeEach(async () => {
-      session = await SessionHelper.add({ data: { returnsPeriod: 'quarterFour' } })
-    })
-
-    it('should call the "ReviewService" with the returns period due date and summer "false"', async () => {
-      await ReviewService.go(session.id)
-
-      expect(RecipientsService.go.calledWith(new Date(`${year}-04-28`), 'false')).to.be.true()
-    })
-  })
-
-  describe('when the returns period is for summer', () => {
-    beforeEach(async () => {
-      session = await SessionHelper.add({ data: { returnsPeriod: 'summer' } })
-    })
-
-    it('should call the "ReviewService" with the returns period due date and summer "false"', async () => {
-      await ReviewService.go(session.id)
-
-      expect(RecipientsService.go.calledWith(new Date(`${year}-11-28`), 'true')).to.be.true()
-    })
-  })
 })