feat: add support for serializing complex objects (#49)

Adds a `shouldSerializeObject` function which determines if a value
should be serialized or should attempt to be nested.

The default implementation checks if a value is a non-date object,
meaning all objects which are not dates will trigger nesting.

README.md

@@ -201,6 +201,50 @@ parse('300=foo', {
 // {300: 'foo'}
 ```
 
+### `shouldSerializeObject`
+
+Can be set to a function which determines if an _object-like_ value should be
+serialized instead of being treated as a nested object.
+
+**All non-object primitives will always be serialized.**
+
+For example:
+
+```
+// Assuming `StringifableObject` returns its constructor value when `toString`
+// is called.
+stringify({
+  foo: new StringifiableObject('test')
+}, {
+  shouldSerializeObject(val) {
+    return val instanceof StringifableObject;
+  },
+  valueSerializer: (value) => {
+    return String(value);
+  }
+});
+
+// foo=test
+```
+
+If you want to fall back to the default logic, you can import the default
+function:
+
+```
+import {defaultShouldSerializeObject, stringify} from 'picoquery';
+
+stringify({
+  foo: new StringifiableObject('test')
+}, {
+  shouldSerializeObject(val) {
+    if (val instanceof StringifableObject) {
+      return true;
+    }
+    return defaultShouldSerializeObject(val);
+  }
+});
+```
+
 ### `valueSerializer`
 
 Can be set to a function which will be used to serialize each value during

src/object-util.ts

@@ -55,7 +55,8 @@ export function stringifyObject(
     arrayRepeatSyntax = defaultOptions.arrayRepeatSyntax,
     nesting = defaultOptions.nesting,
     delimiter = defaultOptions.delimiter,
-    valueSerializer = defaultOptions.valueSerializer
+    valueSerializer = defaultOptions.valueSerializer,
+    shouldSerializeObject = defaultOptions.shouldSerializeObject
   } = options;
   const strDelimiter =
     typeof delimiter === 'number' ? String.fromCharCode(delimiter) : delimiter;
@@ -96,7 +97,11 @@ export function stringifyObject(
       result += strDelimiter;
     }
 
-    if (typeof value === 'object' && value !== null) {
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      !shouldSerializeObject(value)
+    ) {
       valueIsProbableArray = (value as unknown[]).pop !== undefined;
 
       if (nesting || (arrayRepeat && valueIsProbableArray)) {

src/shared.ts

@@ -24,9 +24,13 @@ export type SerializeValueFunction = (
   key: PropertyKey
 ) => string;
 
+export type ShouldSerializeObjectFunction = (value: unknown) => boolean;
+
 export type DeserializeKeyFunction = (key: string) => PropertyKey;
 
-export function defaultValueSerializer(value: unknown): string {
+export const defaultValueSerializer: SerializeValueFunction = (
+  value: unknown
+): string => {
   switch (typeof value) {
     case 'string':
       // Length check is handled inside encodeString function
@@ -41,8 +45,18 @@ export function defaultValueSerializer(value: unknown): string {
       break;
   }
 
+  if (value instanceof Date) {
+    return encodeString(value.toISOString());
+  }
+
   return '';
-}
+};
+
+export const defaultShouldSerializeObject: ShouldSerializeObjectFunction = (
+  val
+) => {
+  return val instanceof Date;
+};
 
 export interface Options {
   // Enable parsing nested objects and arrays
@@ -70,6 +84,7 @@ export interface Options {
   valueDeserializer: DeserializeValueFunction;
   keyDeserializer: DeserializeKeyFunction;
   valueSerializer: SerializeValueFunction;
+  shouldSerializeObject: ShouldSerializeObjectFunction;
 }
 
 const identityFunc = <T>(v: T): T => v;
@@ -82,5 +97,6 @@ export const defaultOptions: Options = {
   delimiter: 38,
   valueDeserializer: identityFunc,
   valueSerializer: defaultValueSerializer,
-  keyDeserializer: identityFunc
+  keyDeserializer: identityFunc,
+  shouldSerializeObject: defaultShouldSerializeObject
 };

src/test/object-util_test.ts

@@ -199,4 +199,24 @@ test('stringifyObject', async (t) => {
   await t.test('null values result in empty string', () => {
     assert.deepEqual(stringifyObject({foo: null}, {}), 'foo=');
   });
+
+  await t.test('custom shouldSerializeObject function', () => {
+    const foo = {
+      toString() {
+        return 'bar';
+      }
+    };
+    const obj = {
+      foo
+    };
+    const result = stringifyObject(obj, {
+      shouldSerializeObject: (val) => {
+        return val === foo;
+      },
+      valueSerializer: (val) => {
+        return String(val);
+      }
+    });
+    assert.equal(result, 'foo=bar');
+  });
 });

src/test/stringify_test.ts

@@ -2,6 +2,7 @@ import * as assert from 'node:assert/strict';
 import {test} from 'node:test';
 import {stringify} from '../main.js';
 import {testCases} from './test-cases.js';
+import {encodeString} from '../string-util.js';
 
 test('stringify', async (t) => {
   for (const testCase of testCases) {
@@ -40,7 +41,23 @@ test('stringify', async (t) => {
     assert.equal(result, 'foo=400');
   });
 
-  await t.test('skips infinite numbers', () => {
+  await t.test('date values', () => {
+    const date = new Date('2000-01-01');
+    const result = stringify({foo: date});
+    assert.equal(result, `foo=${encodeString(date.toISOString())}`);
+  });
+
+  await t.test('complex objects', () => {
+    const cls = class {
+      foo = 123;
+      bar = 456;
+    };
+    const instance = new cls();
+    const result = stringify(instance);
+    assert.equal(result, 'foo=123&bar=456');
+  });
+
+  await t.test('stringifies infinite numbers as empty', () => {
     const result = stringify({foo: Infinity});
     assert.equal(result, 'foo=');
   });