Release 1.1.0 PR rollup

docs/components/content/Data.vue

@@ -17,7 +17,7 @@ const fns: Record<
   ap: {
     name: "ap",
     description: "Returns either am or pm but in any given locale.",
-    return: "Date",
+    return: "string",
     arguments: [
       {
         name: "amOrPm",
@@ -80,7 +80,7 @@ const fns: Record<
         type: "Date",
       },
     ],
-    return: "string",
+    return: "boolean",
   },
   monthDays: {
     name: "month-days",

docs/components/content/Helpers.vue

@@ -1,6 +1,30 @@
 <script lang="ts" setup>
 import sizes from "../../assets/func-sizes.json"
-import type { FunctionRef } from "../../src/types"
+import type { FunctionRef, ObjectRef } from "../../src/types"
+
+const durationProperties: ObjectRef["properties"] = [
+  { name: "years?", type: "number", jsdoc: ["Years in the duration."] },
+  { name: "months?", type: "number", jsdoc: ["Months in the duration."] },
+  { name: "weeks?", type: "number", jsdoc: ["Weeks in the duration."] },
+  { name: "days?", type: "number", jsdoc: ["Days in the duration."] },
+  { name: "hours?", type: "number", jsdoc: ["Hours in the duration."] },
+  { name: "minutes?", type: "number", jsdoc: ["Minutes in the duration."] },
+  { name: "seconds?", type: "number", jsdoc: ["Seconds in the duration."] },
+  { name: "milliseconds?", type: "number", jsdoc: ["Milliseconds in the duration."] },
+]
+
+const diffOptionsProperties: ObjectRef["properties"] = [
+  {
+    name: "abs?",
+    type: "boolean",
+    jsdoc: ["Return absolute values instead of signed values."],
+  },
+  {
+    name: "skip?",
+    type: "Array<keyof Duration> | Set<keyof Duration>",
+    jsdoc: ["Units to omit while calculating the duration."],
+  },
+]
 
 const fns: Record<
   string,
@@ -12,6 +36,27 @@ const fns: Record<
     tip?: string
   }
 > = {
+  diff: {
+    description:
+      "Returns the difference between two dates as a duration object. The result can be passed to <code>add</code> or formatted with <code>Intl.DurationFormat</code>.",
+    return: "Duration",
+    arguments: [
+      {
+        name: "dateA",
+        type: "string | Date | null",
+      },
+      {
+        name: "dateB",
+        type: "string | Date",
+      },
+      {
+        name: "options",
+        type: "DiffOptions",
+        comment: "abs, skip",
+      },
+    ],
+    example: "diff",
+  },
   diffMilliseconds: {
     description:
       "Returns the number of milliseconds difference between two date objects.",
@@ -326,6 +371,10 @@ const fns: Record<
         :arguments="def.arguments"
         :return="def.return"
       />
+      <template v-if="fn === 'diff'">
+        <ObjectReference type="Duration" :properties="durationProperties" />
+        <ObjectReference type="DiffOptions" :properties="diffOptionsProperties" />
+      </template>
       <p v-html="def.description" />
       <CodeExample v-if="def.example" :file="def.example" />
       <CalloutInfo v-if="def.tip">

docs/components/content/Modify.vue

@@ -1,6 +1,17 @@
 <script lang="ts" setup>
 import sizes from "../../assets/func-sizes.json"
-import type { FunctionRef } from "../../src/types"
+import type { FunctionRef, ObjectRef } from "../../src/types"
+
+const durationProperties: ObjectRef["properties"] = [
+  { name: "years?", type: "number", jsdoc: ["Years to add."] },
+  { name: "months?", type: "number", jsdoc: ["Months to add."] },
+  { name: "weeks?", type: "number", jsdoc: ["Weeks to add."] },
+  { name: "days?", type: "number", jsdoc: ["Days to add."] },
+  { name: "hours?", type: "number", jsdoc: ["Hours to add."] },
+  { name: "minutes?", type: "number", jsdoc: ["Minutes to add."] },
+  { name: "seconds?", type: "number", jsdoc: ["Seconds to add."] },
+  { name: "milliseconds?", type: "number", jsdoc: ["Milliseconds to add."] },
+]
 
 const fns: Record<
   string,
@@ -13,6 +24,28 @@ const fns: Record<
     tip?: string
   }
 > = {
+  add: {
+    name: "add",
+    description:
+      "Returns a new Date object with a duration object applied. To subtract time, use negative values. Month and year overflow behavior matches <code>addMonth</code> and <code>addYear</code>.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "duration",
+        type: "Duration",
+      },
+      {
+        name: "dateOverflow",
+        type: "boolean",
+        comment: "default: false",
+      },
+    ],
+    example: "add",
+  },
   addDay: {
     name: "add-day",
     description:
@@ -282,6 +315,138 @@ const fns: Record<
       },
     ],
   },
+  setDayOfMonth: {
+    name: "set-day-of-month",
+    description:
+      "Returns a new Date object with the day of the month set. By default, days beyond the end of the month clamp to the last day; set <code>dateOverflow</code> to <code>true</code> to allow overflow.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "day",
+        type: "number",
+      },
+      {
+        name: "dateOverflow",
+        type: "boolean",
+        comment: "default: false",
+      },
+    ],
+  },
+  setHour: {
+    name: "set-hour",
+    description:
+      "Returns a new Date object with the hour set. Values outside 0-23 use the native Date overflow behavior.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "hour",
+        type: "number",
+        comment: "0-23",
+      },
+    ],
+  },
+  setMilliseconds: {
+    name: "set-milliseconds",
+    description:
+      "Returns a new Date object with the millisecond value set. Values outside 0-999 use the native Date overflow behavior.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "milliseconds",
+        type: "number",
+        comment: "0-999",
+      },
+    ],
+  },
+  setMinutes: {
+    name: "set-minutes",
+    description:
+      "Returns a new Date object with the minute set. Values outside 0-59 use the native Date overflow behavior.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "minute",
+        type: "number",
+        comment: "0-59",
+      },
+    ],
+  },
+  setMonth: {
+    name: "set-month",
+    description:
+      "Returns a new Date object with the zero-based month set. By default, invalid days clamp to the last day of the target month; set <code>dateOverflow</code> to <code>true</code> to allow overflow.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "month",
+        type: "number",
+        comment: "0-11, 0 is January",
+      },
+      {
+        name: "dateOverflow",
+        type: "boolean",
+        comment: "default: false",
+      },
+    ],
+  },
+  setSeconds: {
+    name: "set-seconds",
+    description:
+      "Returns a new Date object with the second set. Values outside 0-59 use the native Date overflow behavior.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "second",
+        type: "number",
+        comment: "0-59",
+      },
+    ],
+  },
+  setYear: {
+    name: "set-year",
+    description:
+      "Returns a new Date object with the year set. By default, invalid leap days clamp to the last day of the target month; set <code>dateOverflow</code> to <code>true</code> to allow overflow.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date | null",
+      },
+      {
+        name: "year",
+        type: "number",
+      },
+      {
+        name: "dateOverflow",
+        type: "boolean",
+        comment: "default: false",
+      },
+    ],
+  },
   tzDate: {
     name: "tz-date",
     description: `Converts an ISO 8601 like string into a Date object with a timezone applied. For example, <code>tzDate('2021-01-01T00:00', 'America/Los_Angeles')</code> will return a Date object representing 2021-01-01 00:00 in L.A.`,
@@ -383,6 +548,11 @@ const fns: Record<
         :arguments="def.arguments"
         :return="def.return"
       />
+      <ObjectReference
+        v-if="fn === 'add'"
+        type="Duration"
+        :properties="durationProperties"
+      />
       <p v-html="def.description" />
       <CodeExample v-if="def.example" :file="def.example" />
       <CalloutInfo v-if="def.tip">

docs/examples/add.ts

@@ -0,0 +1,17 @@
+import { add } from "@formkit/tempo"
+
+// Add multiple units at once
+add("2024-01-01 12:00:00", {
+  years: 1,
+  months: 3,
+  days: 15,
+  hours: 2,
+  minutes: 8,
+  seconds: 40,
+})
+
+// Subtract 5 weeks
+add("2024-02-05", { weeks: -5 })
+
+// Allow month overflow
+add("2024-01-30", { months: 1 }, true)

docs/examples/diff.ts

@@ -0,0 +1,12 @@
+import { add, diff } from "@formkit/tempo"
+
+// Get a duration object
+diff("2025-04-01 12:00:50", "2024-01-01 12:00:00")
+
+// Skip units you do not want in the result
+diff("2025-07-01 12:01:00", "2024-01-01 12:00:00", {
+  skip: ["years", "minutes"],
+})
+
+// Apply a duration to another date
+add("2024-01-30", diff("2024-03-01", "2024-01-30"))

src/__tests__/add.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest"
+import { add, date, diff } from "../index"
+
+describe("add", () => {
+  it("adds multiple duration units", () => {
+    expect(
+      add("2024-01-01 12:00:00", {
+        years: 1,
+        months: 3,
+        days: 15,
+        hours: 2,
+        minutes: 8,
+        seconds: 40,
+      })
+    ).toEqual(date("2025-04-16 14:08:40"))
+  })
+
+  it("allows month overflow when requested", () => {
+    expect(add("2024-01-30", { months: 1 }, true)).toEqual(date("2024-03-01"))
+  })
+
+  it("adds weeks and milliseconds", () => {
+    expect(add("2024-02-05 10:00:00.250", { weeks: -5, milliseconds: 100 })).toEqual(
+      date("2024-01-01 10:00:00.350")
+    )
+  })
+
+  it("round-trips a positive duration returned by diff", () => {
+    const start = "2024-01-30"
+    const end = "2024-03-01"
+
+    expect(add(start, diff(end, start))).toEqual(date(end))
+  })
+
+  it("round-trips a negative duration returned by diff", () => {
+    const start = "2024-01-30"
+    const end = "2024-03-01"
+
+    expect(add(end, diff(start, end))).toEqual(date(start))
+  })
+})