fix: invoke toJSON methods if present

Author: aleclarson

spec.md

@@ -66,6 +66,24 @@ A property name of `__proto__` is forbidden.
 
 An empty object is encoded as `{}`.
 
+#### Object coercion
+
+If an object has a `toJSON` method, it will be invoked and the result will be encoded instead of the object itself. The `toJSON` method may have properties whose values also have `toJSON` methods, and those will be invoked recursively.
+
+```ts
+{
+  a: { ignoredKey: true, toJSON: () => ({ b: 1 }) }
+}
+```
+
+…is encoded into the following query string:
+
+```
+a={b:1}
+```
+
+Note: If the root object has a `toJSON` method, it needs to return an object.
+
 ## Strings
 
 Strings are not wrapped in quotes. If a string would lead to ambiguity, its characters may be escaped with a backslash (`\`) as required.

src/encode.ts

@@ -1,17 +1,37 @@
 import { isArray } from 'radashi'
 import { CharCode, isDigit } from './charCode.js'
-import { CodableObject, CodableValue } from './types.js'
+import { CodableObject, CodableRecord, CodableValue } from './types.js'
 
 export type EncodeOptions = {
   skippedKeys?: string[]
 }
 
 export function encode(obj: CodableObject, options?: EncodeOptions): string {
-  return encodeProperties(obj, false, options?.skippedKeys)
+  return encodeProperties(
+    isRecord(obj) ? obj : assertRecord(obj.toJSON()),
+    false,
+    options?.skippedKeys
+  )
+}
+
+function assertRecord(value: CodableValue): CodableRecord {
+  if (
+    typeof value !== 'object' ||
+    isArray(value) ||
+    value === null ||
+    !isRecord(value)
+  ) {
+    throw new Error('Expected toJSON method to return an object')
+  }
+  return value
+}
+
+function isRecord(value: CodableObject): value is CodableRecord {
+  return typeof value.toJSON !== 'function'
 }
 
 function encodeProperties(
-  obj: CodableObject,
+  obj: CodableRecord,
   nested: boolean,
   skippedKeys?: string[]
 ): string {
@@ -78,7 +98,10 @@ function encodeValue(value: CodableValue): string {
     return encodeArray(value)
   }
   if (typeof value === 'object') {
-    return encodeObject(value)
+    if (isRecord(value)) {
+      return encodeObject(value)
+    }
+    return encodeValue(value.toJSON())
   }
   if (typeof value === 'bigint') {
     return String(value) + 'n'
@@ -110,7 +133,7 @@ function encodeArray(array: readonly CodableValue[]): string {
   return `(${result})`
 }
 
-function encodeObject(obj: CodableObject): string {
+function encodeObject(obj: CodableRecord): string {
   return `{${encodeProperties(obj, true)}}`
 }
 

src/types.ts

@@ -1,4 +1,6 @@
-export type CodableObject = { [key: string]: CodableValue }
+export type CodableObject = { toJSON(): CodableValue } | CodableRecord
+
+export type CodableRecord = { [key: string]: CodableValue }
 
 export type CodableValue =
   | string

test/encode.test.ts

@@ -12,6 +12,42 @@ describe('json-qs', () => {
       })
     }
 
+    test('object with toJSON method', () => {
+      // Root object
+      expect(
+        encode({
+          ignoredKey: true,
+          toJSON: () => ({ a: 1 }),
+        })
+      ).toBe('a=1')
+
+      // Nested object
+      expect(
+        encode({
+          a: {
+            b: { toJSON: () => 1 },
+          },
+        })
+      ).toBe('a={b:1}')
+
+      // Recursive toJSON calls
+      expect(
+        encode({
+          a: {
+            b: {
+              ignoredKey: true,
+              toJSON: () => ({
+                c: {
+                  ignoredKey: true,
+                  toJSON: () => 1,
+                },
+              }),
+            },
+          },
+        })
+      ).toBe('a={b:{c:1}}')
+    })
+
     test('negative zero (not preserved)', () => {
       expect(encode({ a: -0 })).toBe('a=0')
     })