feat: addHour, addMinute, addSecond

Author: justin-schroeder

Diff for: docs/app.vue

@@ -1,10 +1,11 @@
 <script setup lang="ts"></script>
 
 <template>
-  <TheHeader />
+  <!-- <TheHeader /> -->
   <ContainerSection>
-    <TheSearch />
+    <!-- <TheSearch /> -->
     <main class="mt-20">
+      <ContentModify />
       <ContentIntroduction />
       <ContentInstallation />
       <ContentFormat />

Diff for: docs/components/FunctionReference.vue

@@ -16,7 +16,7 @@ const props = defineProps<{
         >: <span class="text-sky-500">{{ arg.type }}</span
         >{{ index < props.arguments.length - 1 ? ", " : ""
         }}<span v-if="arg.comment" class="text-gray-400"
-          >// {{ arg.comment }}</span
+          >&nbsp;// {{ arg.comment }}</span
         >
       </div> </template
     >): <span class="text-sky-500">{{ props.return }}</span>

Diff for: docs/components/content/Modify.vue

@@ -0,0 +1,237 @@
+<script lang="ts" setup>
+const fns = {
+  addDay: {
+    description:
+      "Returns a new Date object with a positive or negative number of days applied to date argument. To subtract days, use a negative number.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+    ],
+  },
+  addHour: {
+    description:
+      "Returns a new Date object with a positive or negative number of hours applied to date argument. To subtract hours, use a negative number.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+    ],
+  },
+  addMinute: {
+    description:
+      "Returns a new Date object with a positive or negative number of minutes applied to date argument. To subtract minutes, use a negative number.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+    ],
+  },
+  addMonth: {
+    description: `Returns a new Date object with a positive or negative number of
+    months applied to date argument. To subtract months, use a negative number.
+    Sometimes the result will "overflow" the available days of
+    the result month. For example when adding 1 month to January 31st the
+    resulting date would be February 31st, which does not exist. By default, the
+    date will be set to the last day of February but you could opt for it
+    to "overflow" into March by setting <code>dateOverflow</code> to
+    <code>true</code>.`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+      {
+        name: "dateOverflow",
+        type: "boolean",
+      },
+    ],
+  },
+  addSecond: {
+    description:
+      "Returns a new Date object with a positive or negative number of seconds applied to date argument. To subtract seconds, use a negative number.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+    ],
+  },
+  addYear: {
+    description: `Returns a new Date object with a positive or negative number of years
+      applied to date argument. To subtract years, use a negative number.
+      Sometimes the result will "overflow" the available days of
+      the result month. For example when adding 1 year to February 29, 2024 the
+      resulting date would be February 29, 2025, which does not exist (2025 is
+      not a leap year). By default, the date will be set to February 28, 2025 but
+      you could opt for it to "overflow" into March by setting
+      <code>dateOverflow</code> to <code>true</code>.`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+      {
+        name: "dateOverflow",
+        type: "boolean",
+      },
+    ],
+  },
+  applyOffset: {
+    description: `Returns a new Date object with a timezone offset applied to date argument
+      — this function does fundamentally change the date but can be very useful
+      when working with timezones. Read more in the timezone section.`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "offset",
+        type: "string",
+        comment: "+-HHmm, ex: -0800",
+      },
+    ],
+  },
+  dayStart: {
+    description: `Returns a new Date object with the time set to 00:00:00.000 (local time).`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+    ],
+  },
+  dayEnd: {
+    description: `Returns a new Date object with the time set to 23:59:59 (local).`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+    ],
+  },
+  monthEnd: {
+    description: `Returns a new Date object with the date set to the last day of the current month (does not modify the time).`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+    ],
+  },
+  monthStart: {
+    description: `Returns a new Date object with the date set to the first day of the current month and the time set to 00:00:00 (local).`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+    ],
+  },
+  removeOffset: {
+    description: `Returns a new Date object with the inverse of the specified timezone offset removed. This can be helpful to normalize time information across timezones.`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "offset",
+        type: "string",
+        comment: "+-HHmm, ex: -0800",
+      },
+    ],
+  },
+  weekStart: {
+    description: `Returns a new Date object with the date set to the first day of the current week with the time set to 00:00:00 (local).`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "startOfWeekDay",
+        type: "number",
+        comment: "0-6, 0 is Sunday",
+      },
+    ],
+  },
+  weekEnd: {
+    description: `Returns a new Date object with the date set to the last day of the current week with the time set to 23:59:59 (local).`,
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "startOfWeekDay",
+        type: "number",
+        comment: "0-6, 0 is Sunday",
+      },
+    ],
+  },
+}
+</script>
+
+<template>
+  <PageSection id="modify">
+    <HeadingSection title="Modify" class="text-sky-500" />
+    <p>
+      Tempo includes a number of (tree-shakable) utility functions to assist you
+      in your date modifying needs. These functions all accept either an ISO
+      8601 string or a Date object and return a <em>new Date object</em> (they
+      do not change the date argument).
+    </p>
+    <div v-for="(def, fn) in fns">
+      <h4>{{ fn }}</h4>
+      <p v-html="def.description" />
+      <FunctionReference
+        :function="fn"
+        :arguments="def.arguments"
+        :return="def.return"
+      />
+    </div>
+  </PageSection>
+</template>

Diff for: docs/components/content/Parse.vue

@@ -82,13 +82,21 @@ const parseOptionsProperties = [
       familiar, but what is <code>partFilter</code> and
       <code>dataOverflow</code>?
     </p>
-    <h4><code>partFilter</code></h4>
+    <h4>partFilter</h4>
     <p>
       The <code>partFilter</code> option gives you fine grained control over
       which pieces and parts of a date you’d like to include in the final parsed
       date (remember, missing "parts" will default to the current date at
       midnight local).
     </p>
     <CodeExample file="part-filter" />
+    <h4>dateOverflow</h4>
+    <p>
+      The <code>dateOverflow</code> option determines how an “out of range” date
+      should be parsed. Options are <code>backward</code> (default),
+      <code>forward</code>, <code>throw</code>.
+    </p>
+    <CodeExample file="date-overflow" />
+    <CodeExample file="date-overflow-throw" />
   </PageSection>
 </template>

Diff for: docs/examples/date-overflow-throw.ts

@@ -0,0 +1,12 @@
+import { parse } from "@formkit/tempo"
+
+// Nov 31 does not exist!
+const date = "2011-11-31"
+
+// Overflows can throw an error
+parse({
+  date,
+  format: "YYYY-MM-DD",
+  locale: "en-US",
+  dateOverflow: "throw",
+})

Diff for: docs/examples/date-overflow.ts

@@ -0,0 +1,15 @@
+import { parse } from "@formkit/tempo"
+
+// Nov 31 does not exist!
+const date = "2011-11-31"
+
+// Default overflow is "backward"
+parse(date, "YYYY-MM-DD", "en-US")
+
+// Parse "forward" into December
+parse({
+  date,
+  format: "YYYY-MM-DD",
+  locale: "en-US",
+  dateOverflow: "forward",
+})

Diff for: src/__tests__/tempo.spec.ts

@@ -10,6 +10,9 @@ import {
   addDay,
   addYear,
   addMonth,
+  addMinute,
+  addSecond,
+  addHour,
   format,
   formatStr,
   sameDay,
@@ -233,6 +236,45 @@ describe("addDay", () => {
   })
 })
 
+describe("addHour", () => {
+  it("can increment a normal hour", () => {
+    expect(addHour("2022-01-01T00:00:00Z").toISOString()).toBe(
+      "2022-01-01T01:00:00.000Z"
+    )
+  })
+  it("can increment the last hours of the day into a new day", () => {
+    expect(addHour("2022-01-01T23:11:00Z", 3).toISOString()).toBe(
+      "2022-01-02T02:11:00.000Z"
+    )
+  })
+})
+
+describe("addMinute", () => {
+  it("can increment a normal hour", () => {
+    expect(addMinute("2022-01-01T00:00:00Z").toISOString()).toBe(
+      "2022-01-01T00:01:00.000Z"
+    )
+  })
+  it("can increment the last hours of the day into a new day", () => {
+    expect(addMinute("2022-01-01T23:11:00Z", 181).toISOString()).toBe(
+      "2022-01-02T02:12:00.000Z"
+    )
+  })
+})
+
+describe("addSecond", () => {
+  it("can increment a normal hour", () => {
+    expect(addSecond("2022-01-01T00:00:00Z").toISOString()).toBe(
+      "2022-01-01T00:00:01.000Z"
+    )
+  })
+  it("can increment the last hours of the day into a new day", () => {
+    expect(addSecond("2022-01-01T23:11:00Z", 3600 * 3 + 1).toISOString()).toBe(
+      "2022-01-02T02:11:01.000Z"
+    )
+  })
+})
+
 describe("addMonth", () => {
   it("gets the next month on the first", () => {
     expect(addMonth("2022-01-01").toISOString()).toBe(

Diff for: src/addHour.ts

@@ -0,0 +1,11 @@
+import { date } from "./date"
+
+/**
+ * Returns a new date object 1/n hours after the original one.
+ * @param inputDate - A date to increment by 1 day.
+ */
+export function addHour(inputDate: DateInput, count = 1) {
+  const d = date(inputDate)
+  d.setHours(d.getHours() + count)
+  return d
+}

Diff for: src/addMinute.ts

@@ -0,0 +1,11 @@
+import { date } from "./date"
+
+/**
+ * Returns a new date object 1/n seconds after the original one.
+ * @param inputDate - A date to increment by 1 day.
+ */
+export function addMinute(inputDate: DateInput, count = 1) {
+  const d = date(inputDate)
+  d.setMinutes(d.getMinutes() + count)
+  return d
+}