feat: adds isEqual, isAfter, isBefore

* feat: add `isEqual`, `isAfter`, `isBefore` functions

* revert: revert nuxt.config for nitro

* fix: rename `CommonHelpers` to `Helpers`

* Update docs/pages/index.vue

Co-authored-by: Justin Schroeder <[email protected]>

* fix: remove TSDoc inside `isEqual`

Co-authored-by: Justin Schroeder <[email protected]>

* fix: remove TSDoc inside `isBefore`

Co-authored-by: Justin Schroeder <[email protected]>

---------

Co-authored-by: Justin Schroeder <[email protected]>

docs/components/content/Helpers.vue

@@ -0,0 +1,82 @@
+<script lang="ts" setup>
+import type { FunctionRef } from "../../src/types"
+const fns: Record<
+  string,
+  {
+    description: string
+    return: string
+    arguments: FunctionRef["arguments"]
+    example?: string
+    tip?: string
+  }
+> = {
+  isBefore: {
+    description:
+      "Returns true if the first date is before the second date, otherwise false.",
+    return: "boolean",
+    arguments: [
+      {
+        name: "inputDate",
+        type: "string | Date",
+      },
+      {
+        name: "dateToCompare",
+        type: "string | Date",
+      },
+    ],
+    example: "isBefore",
+  },
+  isAfter: {
+    description:
+      "Returns true if the first date is after the second date, otherwise false.",
+    return: "boolean",
+    arguments: [
+      {
+        name: "inputDate",
+        type: "string | Date",
+      },
+      {
+        name: "dateToCompare",
+        type: "string | Date",
+      },
+    ],
+    example: "isAfter",
+  },
+  isEqual: {
+    description:
+      "Returns true if the first date is equal to the second date, otherwise false.",
+    return: "boolean",
+    arguments: [
+      {
+        name: "dateLeft",
+        type: "string | Date",
+      },
+      {
+        name: "dateRight",
+        type: "string | Date",
+      },
+    ],
+    example: "isEqual",
+  },
+}
+</script>
+
+<template>
+  <PageSection>
+    <HeadingSection title="Helpers" class="text-sky-500" />
+    <p>
+      Tempo includes a number of (tree-shakable) helper functions to assist you
+      in your date workarounds. These functions all accept either an ISO
+      8601 string or a Date object and return a <em>boolean</em>.
+    </p>
+    <div v-for="(def, fn) in fns">
+      <h3 :id="fn">{{ fn }}</h3>
+      <FunctionReference :function="fn" :arguments="def.arguments" :return="def.return" />
+      <p v-html="def.description" />
+      <CodeExample v-if="def.example" :file="def.example" />
+      <CalloutInfo v-if="def.tip">
+        <span v-html="def.tip" />
+      </CalloutInfo>
+    </div>
+  </PageSection>
+</template>

docs/examples/isAfter.ts

@@ -0,0 +1,7 @@
+import { isAfter } from "@formkit/tempo"
+
+// Compare when the first date is before the second
+isAfter("2013-03-15", "2013-03-16")
+
+// Compare when the first date is after the second
+isAfter("2013-03-17", "2013-03-16")

docs/examples/isBefore.ts

@@ -0,0 +1,7 @@
+import { isBefore } from "@formkit/tempo"
+
+// Compare when the first date is before the second
+isBefore("2013-03-15", "2013-03-16")
+
+// Compare when the first date is after the second
+isBefore("2013-03-17", "2013-03-16")

docs/examples/isEqual.ts

@@ -0,0 +1,7 @@
+import { isEqual } from "@formkit/tempo"
+
+// Compare when the first date is before the second
+isEqual("2013-03-15", "2013-03-16")
+
+// Compare when the first date is equal with the second
+isEqual("2013-03-16", "2013-03-16")

docs/pages/index.vue

@@ -13,6 +13,7 @@ definePageMeta({
     <ContentParse />
     <ContentModify />
     <ContentData />
+    <ContentHelpers />
     <ContentTimezones />
     <ContentSupport />
   </main>

package.json

@@ -25,17 +25,8 @@
     "publint": "publint",
     "release": "pnpm build && bumpp && pnpm publish"
   },
-  "files": [
-    "dist",
-    "docs/public/read-the-docs.png",
-    "docs/public/tempo.png"
-  ],
-  "keywords": [
-    "date",
-    "time",
-    "internationalization",
-    "date format"
-  ],
+  "files": ["dist", "docs/public/read-the-docs.png", "docs/public/tempo.png"],
+  "keywords": ["date", "time", "internationalization", "date format"],
   "author": "Justin Schroeder <[email protected]>",
   "license": "MIT",
   "devDependencies": {

src/__tests__/isAfter.spec.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest"
+import { isAfter } from "../isAfter"
+process.env.TZ = "America/New_York"
+
+describe("isAfter", () => {
+  it("returns true if first date is after second", () => {
+    expect(isAfter("2022-01-02", "2022-01-01")).toBe(true)
+  })
+  it("returns true if first date is before second", () => {
+    expect(isAfter("2022-01-01", "2022-01-02")).toBe(false)
+  })
+  it("returns error if date is not valid", () => {
+    expect(() => isAfter("invalid", "2022-01-01")).toThrowError(
+      "Non ISO 8601 compliant date",
+    )
+  })
+})

src/__tests__/isBefore.spec.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest"
+import { isBefore } from "../isBefore"
+process.env.TZ = "America/New_York"
+
+describe("isBefore", () => {
+  it("returns true if first date is before second", () => {
+    expect(isBefore("2022-01-01", "2022-01-02")).toBe(true)
+  })
+  it("returns false if first date is after second", () => {
+    expect(isBefore("2022-01-02", "2022-01-01")).toBe(false)
+  })
+  it("returns error if date is not valid", () => {
+    expect(() => isBefore("invalid", "2022-01-01")).toThrowError(
+      "Non ISO 8601 compliant date",
+    )
+  })
+})

src/__tests__/isEqual.spec.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from "vitest"
+import { isEqual } from "../isEqual"
+process.env.TZ = "America/New_York"
+
+describe("isEqual", () => {
+  it("returns false if the given dates are not equal", () => {
+    expect(isEqual("2022-01-01", "2022-01-02")).toBe(false)
+  })
+  it("returns true if the given dates are equal", () => {
+    expect(isEqual("2022-01-01", "2022-01-01")).toBe(true)
+  })
+  it("returns error if date is not valid", () => {
+    expect(() => isEqual("invalid", "2022-01-01")).toThrowError(
+      "Non ISO 8601 compliant date",
+    )
+  })
+})

src/index.ts

@@ -33,4 +33,7 @@ export { sameDay } from "./sameDay"
 export { weekEnd } from "./weekEnd"
 export { weekStart } from "./weekStart"
 export { yearDays } from "./yearDays"
+export { isBefore } from "./isBefore"
+export { isAfter } from "./isAfter"
+export { isEqual } from "./isEqual"
 export * from "./types"

src/isAfter.ts

@@ -0,0 +1,22 @@
+import { date } from "./date"
+import type { DateInput } from "./types"
+
+/**
+ * @name isAfter
+ * @category Common Helpers
+ * @summary Is the first date after the second one?
+ *
+ * @description
+ * Is the first date after the second one?
+ *
+ * @param inputDate - The date that should be after the other one to return true
+ * @param dateToCompare - The date to compare with
+ *
+ * @returns The first date is after the second date.
+ */
+export function isAfter(inputDate: DateInput, dateToCompare: DateInput) {
+  const _date = date(inputDate)
+  const _dateToCompare = date(dateToCompare)
+
+  return +_date > +_dateToCompare
+}

src/isBefore.ts

@@ -0,0 +1,17 @@
+import { date } from "./date"
+import type { DateInput } from "./types"
+
+/**
+ * Is the first date before the second one?
+ *
+ * @param inputDate - The date that should be before the other one to return true
+ * @param dateToCompare - The date to compare with
+ *
+ * @returns The first date is before the second date.
+ */
+export function isBefore(inputDate: DateInput, dateToCompare: DateInput) {
+  const _date = date(inputDate)
+  const _dateToCompare = date(dateToCompare)
+
+  return +_date < +_dateToCompare
+}

src/isEqual.ts

@@ -0,0 +1,17 @@
+import { date } from "./date"
+import type { DateInput } from "./types"
+
+/**
+ * Are the given dates equal?
+ *
+ * @param dateLeft - The first date to compare
+ * @param dateRight - The second date to compare
+ *
+ * @returns The dates are equal.
+ */
+export function isEqual(dateLeft: DateInput, dateRight: DateInput) {
+  const _dateLeft = date(dateLeft)
+  const _dateRight = date(dateRight)
+
+  return +_dateLeft === +_dateRight
+}