Merge pull request #15682 from Budibase/labday/add-date-helpers

Add extra date helpers

packages/string-templates/scripts/gen-collection-info.ts

@@ -44,6 +44,19 @@ const ADDED_HELPERS = {
       description:
         "Produce a humanized duration left/until given an amount of time and the type of time measurement.",
     },
+    difference: {
+      args: ["from", "to", "[unitType=ms]"],
+      example:
+        '{{ difference "2025-09-30" "2025-06-17" "seconds" }} -> 9072000',
+      description:
+        "Gets the difference between two dates, in milliseconds. Pass a third parameter to adjust the unit measurement.",
+    },
+    durationFromNow: {
+      args: ["time"],
+      example: '{{durationFromNow "2021-09-30"}} -> 8 months',
+      description:
+        "Produce a humanized duration left/until given an amount of time and the type of time measurement.",
+    },
   },
 }
 

packages/string-templates/src/helpers/date.ts

@@ -1,4 +1,4 @@
-import dayjs from "dayjs"
+import dayjs, { UnitType } from "dayjs"
 
 import dayjsDurationPlugin from "dayjs/plugin/duration"
 import dayjsAdvancedFormatPlugin from "dayjs/plugin/advancedFormat"
@@ -121,7 +121,7 @@ export const date = (str: any, pattern: any, options: any) => {
   return date.format(config.pattern)
 }
 
-export const duration = (str: any, pattern: any, format: any) => {
+export const duration = (str: any, pattern: any, format?: any) => {
   const config = initialConfig(str, pattern)
 
   setLocale(config.str, config.pattern)
@@ -133,3 +133,13 @@ export const duration = (str: any, pattern: any, format: any) => {
     return duration.humanize()
   }
 }
+
+export const difference = (from: string, to: string, units?: UnitType) => {
+  const result = dayjs(new Date(from)).diff(dayjs(new Date(to)), units)
+  return result
+}
+
+export const durationFromNow = (from: string) => {
+  const diff = difference(from, new Date().toISOString(), "ms")
+  return duration(diff, "ms")
+}

packages/string-templates/src/helpers/external.ts

@@ -1,7 +1,7 @@
 // @ts-ignore we don't have types for it
 import helpers from "@budibase/handlebars-helpers"
 
-import { date, duration } from "./date"
+import { date, difference, duration, durationFromNow } from "./date"
 import {
   HelperFunctionBuiltin,
   EXTERNAL_FUNCTION_COLLECTIONS,
@@ -9,8 +9,10 @@ import {
 import Handlebars from "handlebars"
 
 const ADDED_HELPERS = {
-  date: date,
-  duration: duration,
+  date,
+  duration,
+  difference,
+  durationFromNow,
 }
 
 export const externalCollections = EXTERNAL_FUNCTION_COLLECTIONS

packages/string-templates/src/manifest.json

@@ -1222,6 +1222,22 @@
       ],
       "example": "{{duration 8 \"seconds\"}} -> a few seconds",
       "description": "<p>Produce a humanized duration left/until given an amount of time and the type of time measurement.</p>\n"
+    },
+    "difference": {
+      "args": [
+        "from",
+        "to",
+        "[unitType=ms]"
+      ],
+      "example": "{{ difference \"2025-09-30\" \"2025-06-17\" \"seconds\" }} -> 9072000",
+      "description": "<p>Gets the difference between two dates, in milliseconds. Pass a third parameter to adjust the unit measurement.</p>\n"
+    },
+    "durationFromNow": {
+      "args": [
+        "time"
+      ],
+      "example": "{{durationFromNow \"2021-09-30\"}} -> 8 months",
+      "description": "<p>Produce a humanized duration left/until given an amount of time and the type of time measurement.</p>\n"
     }
   }
 }

packages/string-templates/test/helpers/date.spec.ts

@@ -0,0 +1,54 @@
+import tk from "timekeeper"
+import * as date from "../../src/helpers/date"
+
+const frozenDate = new Date("2025-03-06T11:38:41.000Z")
+tk.freeze(frozenDate)
+
+describe("date helper", () => {
+  describe("difference", () => {
+    it("should return the difference between two dates", () => {
+      const result = date.difference(
+        "2021-01-02T12:34:56.789Z",
+        "2021-01-01T01:00:00.000Z"
+      )
+      const expected =
+        1 * 24 * 60 * 60 * 1000 + // 1 day
+        11 * 60 * 60 * 1000 + // 11 hours
+        34 * 60 * 1000 + // 34 minutes
+        56 * 1000 + // seconds
+        789 // milliseconds
+      expect(result).toEqual(expected)
+    })
+
+    it("should be able to set the time unit", () => {
+      const result = date.difference(
+        "2021-01-02T12:34:56",
+        "2021-01-01T01:00:00",
+        "days"
+      )
+      expect(result).toEqual(1)
+    })
+  })
+
+  describe("durationFromNow", () => {
+    it("should return the difference between two close dates", () => {
+      const result = date.durationFromNow("2025-03-06T11:38:43.000Z")
+      expect(result).toEqual("a few seconds")
+    })
+
+    it("should return the difference between two days hours apart", () => {
+      const result = date.durationFromNow("2025-03-06T01:00:00.000Z")
+      expect(result).toEqual("11 hours")
+    })
+
+    it("accepts days in the past", () => {
+      const result = date.durationFromNow("2025-03-01")
+      expect(result).toEqual("5 days")
+    })
+
+    it("accepts days in the future", () => {
+      const result = date.durationFromNow("2025-03-08")
+      expect(result).toEqual("2 days")
+    })
+  })
+})