feat: add support for Date objects

Author: aleclarson

spec.md

@@ -227,6 +227,38 @@ The following object…
 a=9007199254740992n
 ```
 
+## Dates
+
+Dates are stringified to their ISO 8601 string representation. If a date is at midnight UTC, the time component is omitted. If the year exceeds 9999, there may exist a `+` prefix, which needs to be percent-encoded.
+
+The following objects…
+
+```js
+{
+  a: new Date('2024-10-27T00:00:00.000Z')
+}
+
+{
+  b: new Date('2024-10-27T12:34:56.789Z')
+}
+
+{
+  c: new Date('+10000-01-01T00:00:00.000Z')
+}
+```
+
+…are encoded into the following query strings:
+
+```
+a=2024-10-27
+
+b=2024-10-27T12:34:56.789Z
+
+c=%2B010000-01-01
+```
+
+Unlike in strings, colons are not escaped in dates, since they're unlikely to be misread as a property name separator when judged at a glance.
+
 ## Everything Else
 
 The remaining JSON types are merely stringified:

src/decode.ts

@@ -33,7 +33,7 @@ const enum ValueMode {
   Unknown,
   Array,
   Object,
-  NumberOrBigint,
+  Numeric,
   String,
 }
 
@@ -68,15 +68,16 @@ function decodeValue(input: string, cursor = { pos: 0 }): DecodedValue {
       mode = ValueMode.Object
       break
 
+    case CharCode.Plus:
     case CharCode.Minus:
       mode = isDigit(input.charCodeAt(pos + 1))
-        ? ValueMode.NumberOrBigint
+        ? ValueMode.Numeric
         : ValueMode.String
       break
 
     default:
       if (isDigit(charCode)) {
-        mode = ValueMode.NumberOrBigint
+        mode = ValueMode.Numeric
       } else {
         endPos = nested ? findEndPos(input, pos) : input.length
 
@@ -125,14 +126,20 @@ function decodeValue(input: string, cursor = { pos: 0 }): DecodedValue {
       break
     }
 
-    case ValueMode.NumberOrBigint: {
+    case ValueMode.Numeric: {
       pos = nested ? findEndPos(input, pos + 1) : input.length
       if (input.charCodeAt(pos - 1) === CharCode.LowerN) {
         result = BigInt(input.slice(startPos, pos - 1))
       } else {
-        result = Number(input.slice(startPos, pos))
+        const slice = input.slice(startPos, pos)
+        result = Number(slice)
         if (Number.isNaN(result)) {
-          throw new SyntaxError(`Invalid number at position ${startPos}`)
+          result = new Date(slice)
+          if (Number.isNaN(result.getTime())) {
+            throw new SyntaxError(
+              `Invalid number or date at position ${startPos}`
+            )
+          }
         }
       }
       break

src/encode.ts

@@ -1,4 +1,4 @@
-import { isArray } from 'radashi'
+import { isArray, isDate } from 'radashi'
 import { CharCode, isDigit } from './charCode.js'
 import { CodableObject, CodableRecord, CodableValue } from './types.js'
 
@@ -98,6 +98,23 @@ function encodeValue(value: CodableValue): string {
     return encodeArray(value)
   }
   if (typeof value === 'object') {
+    if (isDate(value)) {
+      let iso = value.toISOString()
+      // Remove the time component if it's midnight UTC.
+      if (
+        value.getUTCHours() === 0 &&
+        value.getUTCMinutes() === 0 &&
+        value.getUTCSeconds() === 0 &&
+        value.getUTCMilliseconds() === 0
+      ) {
+        iso = iso.slice(0, -14)
+      }
+      // We also need to encode the '+' sign, if present.
+      if (iso.charCodeAt(0) === CharCode.Plus) {
+        return '%2B' + iso.slice(1)
+      }
+      return iso
+    }
     if (isRecord(value)) {
       return encodeObject(value)
     }
@@ -113,7 +130,8 @@ function isNumberLike(value: string): boolean {
   const charCode = value.charCodeAt(0)
   return (
     isDigit(charCode) ||
-    (charCode === CharCode.Minus && isDigit(value.charCodeAt(1)))
+    ((charCode === CharCode.Minus || charCode === CharCode.Plus) &&
+      isDigit(value.charCodeAt(1)))
   )
 }
 

src/types.ts

@@ -1,6 +1,6 @@
 type JsonPrimitive = string | number | boolean | null
-type CodablePrimitive = JsonPrimitive | bigint | undefined
-type DecodedPrimitive = JsonPrimitive | bigint
+type CodablePrimitive = JsonPrimitive | bigint | Date | undefined
+type DecodedPrimitive = JsonPrimitive | bigint | Date
 
 export type CodableObject = { toJSON(): CodableValue } | CodableRecord
 export type CodableRecord = { [key: string]: CodableValue }

test/cases.ts

@@ -132,6 +132,10 @@ export const cases: Record<string, Case | Case[]> = {
       decoded: { a: '-123' },
       encoded: 'a=\\-123',
     },
+    {
+      decoded: { a: '+123' },
+      encoded: 'a=\\%2B123',
+    },
     {
       decoded: { a: '\\' },
       encoded: 'a=\\\\',
@@ -242,6 +246,24 @@ export const cases: Record<string, Case | Case[]> = {
     decoded: { null: null },
     encoded: 'null=null',
   },
+  dates: [
+    {
+      decoded: { a: new Date('2024-10-27') },
+      encoded: 'a=2024-10-27',
+    },
+    {
+      decoded: { a: new Date('2024-10-27T12:34:56.789Z') },
+      encoded: 'a=2024-10-27T12:34:56.789Z',
+    },
+    {
+      decoded: { a: new Date('+100000-01-01T00:00:00.000Z') },
+      encoded: 'a=%2B100000-01-01',
+    },
+    {
+      decoded: { a: new Date('-100000-01-01T00:00:00.000Z') },
+      encoded: 'a=-100000-01-01',
+    },
+  ],
   'complex nested structures': {
     decoded: {
       user: {

test/decode.test.ts

@@ -55,6 +55,7 @@ describe('json-qs', () => {
         'a={b}',
         'a={:}',
         'a=1.n',
+        'a=2024-31-01',
       ])
 
       expect(results).toMatchInlineSnapshot(`
@@ -67,6 +68,7 @@ describe('json-qs', () => {
           "a={b}" => [SyntaxError: Failed to decode value for 'a' key: Unterminated key at position 2],
           "a={:}" => [SyntaxError: Failed to decode value for 'a' key: Unexpected end of string at position 2],
           "a=1.n" => [SyntaxError: Failed to decode value for 'a' key: Cannot convert 1. to a BigInt],
+          "a=2024-31-01" => [SyntaxError: Failed to decode value for 'a' key: Invalid number or date at position 0],
         }
       `)
     })