docs: adds diffs to docs

formkit · Apr 17, 2024 · 1b5d333 · 1b5d333
1 parent 809d4c6
commit 1b5d333
Show file tree

Hide file tree

Showing 10 changed files with 235 additions and 78 deletions.
diff --git a/docs/components/content/Helpers.vue b/docs/components/content/Helpers.vue
@@ -12,96 +12,154 @@ const fns: Record<
     tip?: string
   }
 > = {
-  sameSecond: {
+  diffMilliseconds: {
     description:
-      "Checks if two dates are the same second. This function is useful for comparing dates but ignoring the milliseconds.",
+      "Returns the number of milliseconds difference between two date objects.",
+    return: "number",
     arguments: [
       {
         name: "dateA",
-        type: "Date",
+        type: "string | Date",
       },
       {
         name: "dateB",
-        type: "Date",
+        type: "string | Date",
       },
     ],
-    return: "boolean",
   },
-  sameMinute: {
+  diffSeconds: {
     description:
-      "Checks if two dates are the same minute. This function is useful for comparing dates but ignoring the seconds and milliseconds.",
+      "Returns the number of seconds difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial seconds.",
+    return: "number",
     arguments: [
       {
         name: "dateA",
-        type: "Date",
+        type: "string | Date",
       },
       {
         name: "dateB",
-        type: "Date",
+        type: "string | Date",
+      },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
       },
     ],
-    return: "boolean",
   },
-  sameHour: {
+  diffMinutes: {
     description:
-      "Checks if two dates are the same hour. This function is useful for comparing dates but ignoring the minutes, seconds, and milliseconds.",
+      "Returns the number of minutes difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial minutes.",
+    return: "number",
     arguments: [
       {
         name: "dateA",
-        type: "Date",
+        type: "string | Date",
       },
       {
         name: "dateB",
-        type: "Date",
+        type: "string | Date",
+      },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
       },
     ],
-    return: "boolean",
   },
-  sameDay: {
+  diffHours: {
     description:
-      "Checks if two dates are the same day. This function is useful for comparing dates but ignoring the time.",
+      "Returns the number of hours difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial hours.",
+    return: "number",
     arguments: [
       {
         name: "dateA",
-        type: "Date",
+        type: "string | Date",
       },
       {
         name: "dateB",
-        type: "Date",
+        type: "string | Date",
+      },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
       },
     ],
-    return: "boolean",
   },
-  sameYear: {
+  diffDays: {
     description:
-      "Checks if two dates are the same year. This function is useful for comparing dates but ignoring the month, day, and time.",
+      "Returns the number of days difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial days.",
+    return: "number",
     arguments: [
       {
         name: "dateA",
-        type: "Date",
+        type: "string | Date",
       },
       {
         name: "dateB",
-        type: "Date",
+        type: "string | Date",
+      },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
       },
     ],
-    return: "boolean",
+    example: "diffDays",
   },
-  isBefore: {
+  diffWeeks: {
     description:
-      "Returns true if the first date is before the second date, otherwise false.",
-    return: "boolean",
+      "Returns the number of weeks difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial weeks.",
+    return: "number",
     arguments: [
       {
-        name: "inputDate",
+        name: "dateA",
         type: "string | Date",
       },
       {
-        name: "dateToCompare",
+        name: "dateB",
         type: "string | Date",
       },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
+      },
+    ],
+  },
+  diffMonths: {
+    description:
+      "Returns the number of months difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial months.",
+    return: "number",
+    arguments: [
+      {
+        name: "dateA",
+        type: "string | Date",
+      },
+      {
+        name: "dateB",
+        type: "string | Date",
+      },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
+      },
+    ],
+  },
+  diffYears: {
+    description:
+      "Returns the number of years difference between two date objects. An optional third argument controls what kind of “rounding” should be used for partial years.",
+    return: "number",
+    arguments: [
+      {
+        name: "dateA",
+        type: "string | Date",
+      },
+      {
+        name: "dateB",
+        type: "string | Date",
+      },
+      {
+        name: "roundingMethod",
+        type: '"trunc" | "round" | "floor" | "ceil"',
+      },
     ],
-    example: "isBefore",
   },
   isAfter: {
     description:
@@ -119,6 +177,22 @@ const fns: Record<
     ],
     example: "isAfter",
   },
+  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",
+  },
   isEqual: {
     description:
       "Returns true if the first date is equal to the second date, otherwise false.",
@@ -135,6 +209,81 @@ const fns: Record<
     ],
     example: "isEqual",
   },
+  sameSecond: {
+    description:
+      "Checks if two dates are the same second. This function is useful for comparing dates but ignoring the milliseconds.",
+    arguments: [
+      {
+        name: "dateA",
+        type: "Date",
+      },
+      {
+        name: "dateB",
+        type: "Date",
+      },
+    ],
+    return: "boolean",
+  },
+  sameMinute: {
+    description:
+      "Checks if two dates are the same minute. This function is useful for comparing dates but ignoring the seconds and milliseconds.",
+    arguments: [
+      {
+        name: "dateA",
+        type: "Date",
+      },
+      {
+        name: "dateB",
+        type: "Date",
+      },
+    ],
+    return: "boolean",
+  },
+  sameHour: {
+    description:
+      "Checks if two dates are the same hour. This function is useful for comparing dates but ignoring the minutes, seconds, and milliseconds.",
+    arguments: [
+      {
+        name: "dateA",
+        type: "Date",
+      },
+      {
+        name: "dateB",
+        type: "Date",
+      },
+    ],
+    return: "boolean",
+  },
+  sameDay: {
+    description:
+      "Checks if two dates are the same day. This function is useful for comparing dates but ignoring the time.",
+    arguments: [
+      {
+        name: "dateA",
+        type: "Date",
+      },
+      {
+        name: "dateB",
+        type: "Date",
+      },
+    ],
+    return: "boolean",
+  },
+  sameYear: {
+    description:
+      "Checks if two dates are the same year. This function is useful for comparing dates but ignoring the month, day, and time.",
+    arguments: [
+      {
+        name: "dateA",
+        type: "Date",
+      },
+      {
+        name: "dateB",
+        type: "Date",
+      },
+    ],
+    return: "boolean",
+  },
 }
 </script>
 
@@ -143,19 +292,25 @@ const fns: Record<
     <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>.
+      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">
       <div class="flex items-center justify-between mb-3">
         <h3 :id="fn" class="!m-0">{{ fn }}</h3>
         <GithubLinkAndSize
-          :githubLink="'https://github.com/formkit/tempo/blob/main/src/' + fn + '.ts'"
+          :githubLink="
+            'https://github.com/formkit/tempo/blob/main/src/' + fn + '.ts'
+          "
           :functionSize="sizes[fn]?.esm?.formattedSize"
         />
       </div>
 
-      <FunctionReference :function="fn" :arguments="def.arguments" :return="def.return" />
+      <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">

diff --git a/docs/examples/diffDays.ts b/docs/examples/diffDays.ts
@@ -0,0 +1,5 @@
+import { diffDays } from "@formkit/tempo"
+
+diffDays("2021-07-03", "2021-01-01")
+// lets round the difference
+diffDays("2025-02-07T18:31:00Z", "2025-02-05T05:31:00Z", "round")
diff --git a/src/diffDays.ts b/src/diffDays.ts
@@ -4,17 +4,17 @@ import { diffRound, type DiffRoundingMethod } from "./diffRound"
 
 /**
  * Returns the difference between 2 dates in days.
- * @param leftDate A date to compare with the right date
- * @param rightDate A date to compare with the left date
+ * @param dateA A date to compare with the right date
+ * @param dateB A date to compare with the left date
  * @param roundingMethod the rounding method to use, default: trunc
  */
 export function diffDays(
-  leftDate: DateInput,
-  rightDate: DateInput,
+  dateA: DateInput,
+  dateB: DateInput,
   roundingMethod?: DiffRoundingMethod
 ) {
   return diffRound(
-    diffMilliseconds(leftDate, rightDate) / 86_400_000, // hour * 24
+    diffMilliseconds(dateA, dateB) / 86_400_000, // hour * 24
     roundingMethod
   )
 }
diff --git a/src/diffHours.ts b/src/diffHours.ts
@@ -4,17 +4,17 @@ import { DateInput } from "./types"
 
 /**
  * Returns the difference between 2 dates in hours.
- * @param leftDate A date to compare with the right date
- * @param rightDate A date to compare with the left date
+ * @param dateA A date to compare with the right date
+ * @param dateB A date to compare with the left date
  * @param roundingMethod the rounding method to use, default: trunc
  */
 export function diffHours(
-  leftDate: DateInput,
-  rightDate: DateInput,
+  dateA: DateInput,
+  dateB: DateInput,
   roundingMethod?: DiffRoundingMethod
 ) {
   return diffRound(
-    diffMilliseconds(leftDate, rightDate) / 3_600_000, // 1000 * 60 * 60
+    diffMilliseconds(dateA, dateB) / 3_600_000, // 1000 * 60 * 60
     roundingMethod
   )
 }
diff --git a/src/diffMilliseconds.ts b/src/diffMilliseconds.ts
@@ -3,11 +3,11 @@ import { DateInput } from "./types"
 
 /**
  * Returns the difference between 2 dates in milliseconds.
- * @param leftDate A date to compare with the right date
- * @param rightDate A date to compare with the left date
+ * @param dateA A date to compare with the right date
+ * @param dateB A date to compare with the left date
  */
-export function diffMilliseconds(leftDate: DateInput, rightDate: DateInput) {
-  const left = date(leftDate)
-  const right = date(rightDate)
+export function diffMilliseconds(dateA: DateInput, dateB: DateInput) {
+  const left = date(dateA)
+  const right = date(dateB)
   return +left - +right
 }