Merge pull request #18295 from backstage/freben/toms

introduce durationToMilliseconds

.changeset/hip-mugs-visit.md

@@ -0,0 +1,5 @@
+---
+'@backstage/types': minor
+---
+
+Added a `durationToMilliseconds` function to help with the conversion to a single duration number

.changeset/purple-cheetahs-grow.md

@@ -0,0 +1,6 @@
+---
+'@backstage/backend-app-api': patch
+'@backstage/config-loader': patch
+---
+
+Use `durationToMilliseconds` from `@backstage/types` instead of our own

packages/backend-app-api/src/services/implementations/httpRouter/createLifecycleMiddleware.ts

@@ -16,32 +16,11 @@
 
 import { LifecycleService } from '@backstage/backend-plugin-api';
 import { ServiceUnavailableError } from '@backstage/errors';
-import { HumanDuration } from '@backstage/types';
+import { HumanDuration, durationToMilliseconds } from '@backstage/types';
 import { RequestHandler } from 'express';
 
 export const DEFAULT_TIMEOUT = { seconds: 5 };
 
-function durationToMs(duration: HumanDuration): number {
-  const {
-    years = 0,
-    months = 0,
-    weeks = 0,
-    days = 0,
-    hours = 0,
-    minutes = 0,
-    seconds = 0,
-    milliseconds = 0,
-  } = duration;
-
-  const totalDays = years * 365 + months * 30 + weeks * 7 + days;
-  const totalHours = totalDays * 24 + hours;
-  const totalMinutes = totalHours * 60 + minutes;
-  const totalSeconds = totalMinutes * 60 + seconds;
-  const totalMilliseconds = totalSeconds * 1000 + milliseconds;
-
-  return totalMilliseconds;
-}
-
 /**
  * Options for {@link createLifecycleMiddleware}.
  * @public
@@ -102,7 +81,7 @@ export function createLifecycleMiddleware(
     waiting.clear();
   });
 
-  const timeoutMs = durationToMs(startupRequestPauseTimeout);
+  const timeoutMs = durationToMilliseconds(startupRequestPauseTimeout);
 
   return (_req, _res, next) => {
     if (state === 'up') {

packages/config-loader/src/sources/RemoteConfigSource.ts

@@ -15,7 +15,11 @@
  */
 
 import { ResponseError } from '@backstage/errors';
-import { HumanDuration, JsonObject } from '@backstage/types';
+import {
+  HumanDuration,
+  JsonObject,
+  durationToMilliseconds,
+} from '@backstage/types';
 import isEqual from 'lodash/isEqual';
 import fetch from 'node-fetch';
 import yaml from 'yaml';
@@ -29,27 +33,6 @@ import {
 
 const DEFAULT_RELOAD_INTERVAL = { seconds: 60 };
 
-function durationToMs(duration: HumanDuration): number {
-  const {
-    years = 0,
-    months = 0,
-    weeks = 0,
-    days = 0,
-    hours = 0,
-    minutes = 0,
-    seconds = 0,
-    milliseconds = 0,
-  } = duration;
-
-  const totalDays = years * 365 + months * 30 + weeks * 7 + days;
-  const totalHours = totalDays * 24 + hours;
-  const totalMinutes = totalHours * 60 + minutes;
-  const totalSeconds = totalMinutes * 60 + seconds;
-  const totalMilliseconds = totalSeconds * 1000 + milliseconds;
-
-  return totalMilliseconds;
-}
-
 /**
  * Options for {@link RemoteConfigSource.create}.
  *
@@ -104,7 +87,7 @@ export class RemoteConfigSource implements ConfigSource {
 
   private constructor(options: RemoteConfigSourceOptions) {
     this.#url = options.url;
-    this.#reloadIntervalMs = durationToMs(
+    this.#reloadIntervalMs = durationToMilliseconds(
       options.reloadInterval ?? DEFAULT_RELOAD_INTERVAL,
     );
     this.#transformer = createConfigTransformer({

packages/types/api-report.md

@@ -3,6 +3,9 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+// @public
+export function durationToMilliseconds(duration: HumanDuration): number;
+
 // @public
 export type HumanDuration = {
   years?: number;

packages/types/src/index.ts

@@ -22,4 +22,4 @@
 
 export type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './json';
 export type { Observable, Observer, Subscription } from './observable';
-export type { HumanDuration } from './time';
+export { type HumanDuration, durationToMilliseconds } from './time';

packages/types/src/time.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { HumanDuration } from './time';
+import { HumanDuration, durationToMilliseconds } from './time';
 import { Duration } from 'luxon';
 
 describe('time', () => {
@@ -33,4 +33,38 @@ describe('time', () => {
       expect(Duration.fromObject(d).toObject()).toEqual(d);
     });
   });
+
+  describe('durationToMilliseconds', () => {
+    it('converts a compound duration to milliseconds', () => {
+      const duration: HumanDuration = {
+        years: 1,
+        months: 1,
+        weeks: 1,
+        days: 1,
+        hours: 1,
+        minutes: 1,
+        seconds: 1,
+        milliseconds: 1,
+      };
+      expect(durationToMilliseconds(duration)).toBe(
+        ((((365 + 30 + 7 + 1) * 24 + 1) * 60 + 1) * 60 + 1) * 1000 + 1,
+      );
+    });
+
+    const durations: HumanDuration[] = [
+      { years: 1 },
+      { months: 1 },
+      { weeks: 1 },
+      { days: 1 },
+      { hours: 1 },
+      { minutes: 1 },
+      { seconds: 1 },
+      { milliseconds: 1 },
+    ];
+    it.each(durations)('computes milliseconds like luxon does, %p', d => {
+      expect(Duration.fromObject(d).as('milliseconds')).toEqual(
+        durationToMilliseconds(d),
+      );
+    });
+  });
 });

packages/types/src/time.ts

@@ -29,3 +29,38 @@ export type HumanDuration = {
   seconds?: number;
   milliseconds?: number;
 };
+
+/**
+ * Converts a {@link HumanDuration} to milliseconds.
+ *
+ * @public
+ * @remarks
+ *
+ * Note that this conversion by definition is an approximation in the absence of
+ * an anchor to a point in time and time zone, as the number of milliseconds is
+ * not constant for many units. So the conversion assumes 365-day years, 30-day
+ * months, and fixed 24-hour days.
+ *
+ * @param duration - A human friendly duration object.
+ * @returns The number of approximate milliseconds that the duration represents.
+ */
+export function durationToMilliseconds(duration: HumanDuration): number {
+  const {
+    years = 0,
+    months = 0,
+    weeks = 0,
+    days = 0,
+    hours = 0,
+    minutes = 0,
+    seconds = 0,
+    milliseconds = 0,
+  } = duration;
+
+  const totalDays = years * 365 + months * 30 + weeks * 7 + days;
+  const totalHours = totalDays * 24 + hours;
+  const totalMinutes = totalHours * 60 + minutes;
+  const totalSeconds = totalMinutes * 60 + seconds;
+  const totalMilliseconds = totalSeconds * 1000 + milliseconds;
+
+  return totalMilliseconds;
+}