feat: add date template helper functions

Signed-off-by: Manuel Ruck <[email protected]>

core/src/template-string/date-functions.ts

@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2018-2024 Garden Technologies, Inc. <[email protected]>
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+import type { TemplateHelperFunction } from "./functions.js"
+import { joi } from "../config/common.js"
+import { format as formatFns, add } from "date-fns"
+
+export const dateHelperFunctionSpecs: TemplateHelperFunction[] = [
+  {
+    name: "formatDate",
+    description: "Formats the given date using the specified format.",
+    arguments: {
+      date: joi.string().required().description("The date to format."),
+      format: joi
+        .string()
+        .required()
+        .description("The format to use. See https://date-fns.org/v2.21.1/docs/format for details."),
+    },
+    outputSchema: joi.string(),
+    exampleArguments: [
+      { input: ["2021-01-01T00:00:00Z", "yyyy-MM-dd"], output: "2021-01-01", skipTest: true },
+      { input: ["2021-01-01T00:00:00Z", "yyyy-MM-dd HH:mm:ss"], output: "2021-01-01 00:00:00", skipTest: true },
+    ],
+    fn: (date: Date, format: string) => {
+      return formatFns(date, format)
+    },
+  },
+  {
+    name: "modifyDate",
+    description: "Modifies or sets a unit of the given date to the specified amount based on the mode.",
+    arguments: {
+      date: joi.string().required().description("The date to modify."),
+      amount: joi.number().required().description("The amount to modify or set the date by."),
+      unit: joi
+        .string()
+        .valid("years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds")
+        .required()
+        .description("The unit to modify or set."),
+      mode: joi.string().valid("add", "set").description("Mode to either add or set the unit.").default("add"),
+    },
+    outputSchema: joi.string(),
+    exampleArguments: [
+      { input: ["2021-01-01T00:00:00Z", 1, "days", "add"], output: "2021-01-02T00:00:00.000Z" },
+      { input: ["2021-01-01T00:00:00Z", -1, "days", "add"], output: "2020-12-31T00:00:00.000Z" },
+      { input: ["2021-01-01T00:00:00Z", 30, "seconds", "set"], output: "2021-01-01T00:00:30.000Z" },
+    ],
+    fn: (date: string, amount: number, unit: string, mode: string) => {
+      const dateClone = new Date(date)
+      switch (mode) {
+        case "add":
+          return add(dateClone, { [unit]: amount }).toISOString()
+        case "set":
+          switch (unit) {
+            case "years":
+              dateClone.setFullYear(amount)
+              break
+            case "months":
+              dateClone.setMonth(amount)
+              break
+            case "days":
+              dateClone.setDate(amount)
+              break
+            case "hours":
+              dateClone.setHours(amount)
+              break
+            case "minutes":
+              dateClone.setMinutes(amount)
+              break
+            case "seconds":
+              dateClone.setSeconds(amount)
+              break
+            case "milliseconds":
+              dateClone.setMilliseconds(amount)
+              break
+            default:
+              throw new Error("Invalid unit")
+          }
+          return dateClone.toISOString()
+        default:
+          throw new Error("Invalid mode")
+      }
+    },
+  },
+]

core/src/template-string/functions.ts

@@ -18,14 +18,15 @@ import { load, loadAll } from "js-yaml"
 import { safeDumpYaml } from "../util/serialization.js"
 import indentString from "indent-string"
 import { mayContainTemplateString } from "./template-string.js"
+import { dateHelperFunctionSpecs } from "./date-functions.js"
 
 interface ExampleArgument {
   input: any[]
   output: any // Used to validate expected output
   skipTest?: boolean
 }
 
-interface TemplateHelperFunction {
+export interface TemplateHelperFunction {
   name: string
   description: string
   arguments: { [name: string]: Joi.Schema }
@@ -407,6 +408,7 @@ const helperFunctionSpecs: TemplateHelperFunction[] = [
       }
     },
   },
+  ...dateHelperFunctionSpecs,
 ]
 
 interface ResolvedHelperFunction extends TemplateHelperFunction {

docs/reference/template-strings/functions.md

@@ -51,6 +51,17 @@ Examples:
 * `${concat([1,2,3], [4,5])}` -> `[1,2,3,4,5]`
 * `${concat("string1", "string2")}` -> `"string1string2"`
 
+## formatDate
+
+Formats the given date using the specified format.
+
+Usage: `formatDate(date, format)`
+
+Examples:
+
+* `${formatDate("2021-01-01T00:00:00Z", "yyyy-MM-dd")}` -> `"2021-01-01"`
+* `${formatDate("2021-01-01T00:00:00Z", "yyyy-MM-dd HH:mm:ss")}` -> `"2021-01-01 00:00:00"`
+
 ## indent
 
 Indents each line in the given string with the specified number of spaces.
@@ -134,6 +145,18 @@ Examples:
 
 * `${lower("Some String")}` -> `"some string"`
 
+## modifyDate
+
+Modifies or sets a unit of the given date to the specified amount based on the mode.
+
+Usage: `modifyDate(date, amount, unit, [mode])`
+
+Examples:
+
+* `${modifyDate("2021-01-01T00:00:00Z", 1, "days", "add")}` -> `"2021-01-02T00:00:00.000Z"`
+* `${modifyDate("2021-01-01T00:00:00Z", -1, "days", "add")}` -> `"2020-12-31T00:00:00.000Z"`
+* `${modifyDate("2021-01-01T00:00:00Z", 30, "seconds", "set")}` -> `"2021-01-01T00:00:30.000Z"`
+
 ## replace
 
 Replaces all occurrences of a given substring in a string.