feat: add millisecond support to format, parse, and helpers

Author: justin-schroeder

docs/components/content/Format.vue

@@ -368,6 +368,11 @@ import sizes from "../../assets/func-sizes.json"
           <td>07, 17</td>
           <td>The second 00-59</td>
         </tr>
+        <tr>
+          <td><code>SSS</code></td>
+          <td>007, 123, 789</td>
+          <td>The millisecond, 3 digits (000-999). When parsing, accepts variable-length fractional seconds (1-9 digits).</td>
+        </tr>
         <tr>
           <td><code>a</code></td>
           <td>{{ format(new Date(), "a") }}</td>
@@ -391,6 +396,14 @@ import sizes from "../../assets/func-sizes.json"
       </tbody>
     </table>
     <CodeExample file="format-tokens" />
+    <h3 id="milliseconds">Milliseconds</h3>
+    <p>
+      The <code>SSS</code> token formats milliseconds as 3 digits (000-999).
+      When parsing, it graciously accepts variable-length fractional seconds
+      (1-9 digits), making it compatible with high-precision timestamps like
+      those from databases or APIs.
+    </p>
+    <CodeExample file="milliseconds" />
     <h3 id="format-options">Format options</h3>
     <p>
       The <code>format()</code> function can accept an object of options as its

docs/components/content/Helpers.vue

@@ -209,6 +209,21 @@ const fns: Record<
     ],
     example: "isEqual",
   },
+  sameMillisecond: {
+    description:
+      "Checks if two dates have the same millisecond value (0-999). This compares only the millisecond component, ignoring the rest of the timestamp.",
+    arguments: [
+      {
+        name: "dateA",
+        type: "Date",
+      },
+      {
+        name: "dateB",
+        type: "Date",
+      },
+    ],
+    return: "boolean",
+  },
   sameSecond: {
     description:
       "Checks if two dates are the same second. This function is useful for comparing dates but ignoring the milliseconds.",

docs/components/content/Modify.vue

@@ -62,6 +62,22 @@ const fns: Record<
       },
     ],
   },
+  addMillisecond: {
+    name: "add-millisecond",
+    description:
+      "Returns a new Date object with a positive or negative number of milliseconds applied to date argument. To subtract milliseconds, use a negative number.",
+    return: "Date",
+    arguments: [
+      {
+        name: "date",
+        type: "string | Date",
+      },
+      {
+        name: "amount",
+        type: "number",
+      },
+    ],
+  },
   addMonth: {
     name: "add-month",
     description: `Returns a new Date object with a positive or negative number of

docs/examples/format-tokens.ts

@@ -35,3 +35,5 @@ format(t, "h:mm:ss A Z", l)
 format(t, "YY/MM/DD", l)
 format(t, "YYYY MMMM D", l)
 format(t, "M-D-YY", l)
+format(t, "HH:mm:ss.SSS", l)
+format(t, "YYYY-MM-DDTHH:mm:ss.SSSZ", l)

docs/examples/milliseconds.ts

@@ -0,0 +1,19 @@
+import { format, parse } from "@formkit/tempo"
+
+// Format with milliseconds using SSS token
+const d = new Date("2024-01-15T10:30:45.789Z")
+format({ date: d, format: "HH:mm:ss.SSS", tz: "UTC" })
+format({ date: d, format: "YYYY-MM-DDTHH:mm:ss.SSSZ", tz: "UTC" })
+
+// SSS always outputs 3 digits, padding with zeros
+const d2 = new Date("2024-01-15T10:30:45.007Z")
+format({ date: d2, format: "ss.SSS", tz: "UTC" })
+
+// Parse milliseconds - SSS accepts variable-length input
+parse("10:30:45.789", "HH:mm:ss.SSS")
+// 1 digit -> 700ms
+parse("10:30:45.7", "HH:mm:ss.SSS")
+// 2 digits -> 780ms
+parse("10:30:45.78", "HH:mm:ss.SSS")
+// 6 digits -> 123ms (truncates to ms)
+parse("10:30:45.123456", "HH:mm:ss.SSS")

docs/nuxt.config.ts

@@ -97,15 +97,20 @@ export default defineNuxtConfig({
     worker: {
       format: "es",
     },
+    optimizeDeps: {
+      exclude: ["@formkit/tempo"],
+    },
   },
   nitro: {
     storage: {
-      kv: {
-        driver: process.env.KV_DRIVER,
-        accountId: process.env.KV_ACCOUNT_ID,
-        namespaceId: process.env.KV_NAMESPACE_ID,
-        apiToken: process.env.KV_API_TOKEN,
-      },
+      kv: process.env.KV_DRIVER
+        ? {
+            driver: process.env.KV_DRIVER,
+            accountId: process.env.KV_ACCOUNT_ID,
+            namespaceId: process.env.KV_NAMESPACE_ID,
+            apiToken: process.env.KV_API_TOKEN,
+          }
+        : { driver: "memory" },
     },
   },
 })

docs/package.json

@@ -11,19 +11,19 @@
   },
   "devDependencies": {
     "@nuxt/devtools": "latest",
-    "@nuxtjs/color-mode": "^3.3.2",
-    "@nuxtjs/tailwindcss": "^6.11.2",
-    "@types/node": "^18.17.0",
-    "@vueuse/core": "^10.7.2",
-    "@vueuse/nuxt": "^10.7.2",
-    "nuxt": "^3.10.0",
-    "nuxt-fathom": "^0.0.1",
-    "vitest": "^1.2.2"
+    "@nuxtjs/color-mode": "^4.0.0",
+    "@nuxtjs/tailwindcss": "^6.14.0",
+    "@types/node": "^25.0.3",
+    "@vueuse/core": "^14.1.0",
+    "@vueuse/nuxt": "^14.1.0",
+    "nuxt": "^4.2.2",
+    "nuxt-fathom": "^0.0.3",
+    "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@docsearch/js": "3",
-    "@formkit/auto-animate": "^0.8.1",
+    "@docsearch/js": "^4.3.2",
+    "@formkit/auto-animate": "^0.9.0",
     "@formkit/tempo": "workspace:*",
-    "monaco-editor": "^0.40.0"
+    "monaco-editor": "^0.55.1"
   }
 }

package.json

@@ -55,17 +55,17 @@
   "author": "Justin Schroeder <justin@formkit.com>",
   "license": "MIT",
   "devDependencies": {
-    "@size-limit/esbuild": "^11.1.1",
-    "@size-limit/file": "^11.1.1",
-    "@size-limit/preset-small-lib": "^11.0.2",
-    "@types/node": "^20.11.10",
-    "bumpp": "^9.3.0",
+    "@size-limit/esbuild": "^12.0.0",
+    "@size-limit/file": "^12.0.0",
+    "@size-limit/preset-small-lib": "^12.0.0",
+    "@types/node": "^25.0.3",
+    "bumpp": "^10.3.2",
     "bytes-iec": "^3.1.1",
-    "esbuild-plugin-file-path-extensions": "^2.0.0",
-    "publint": "^0.2.7",
-    "size-limit": "^11.0.2",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.1"
+    "esbuild-plugin-file-path-extensions": "^2.1.4",
+    "publint": "^0.3.16",
+    "size-limit": "^12.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   }
 }