Merge pull request #15 from seamapi/beta

Version 2

Author: razor-x

README.md

@@ -11,26 +11,29 @@ Defines the standard for how the Seam SDKs and other Seam API consumers
 should serialize objects to [URLSearchParams] in HTTP GET requests.
 Serves as a reference implementation for Seam SDKs in other languages.
 
-See this test for the [serialization behavior](./test/serialization.test.ts).
+This serializer may be used as a true inverse operation to [@seamapi/url-search-params-parser][@url-search-params-parser].
 
 [URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+[@url-search-params-parser]: https://github.com/seamapi/url-search-params-parser
 
 ### Serialization strategy
 
 Serialization uses
 [`URLSearchParams.toString()`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/toString#return_value)
 which encodes most non-alphanumeric characters.
 
-Serialization is guaranteed to be well-defined within each type, i.e.,
-if the type of value for a given key in the query string is fixed and known by
-the consumer parsing the string, it can be unambigously parsed back to the original primitive value.
-
+- The primitive `null` is serialized to an empty value,
+  e.g., `{ foo: null }` serializes to `foo=`.
+- Any `undefined` values are removed,
+  e.g., `{ foo: undefined, bar: 1 }` serializes to `bar=1`.
 - The primitive type `string` is serialized using `.toString()`.
+  - Serialization of the empty string
+    is not supported and will throw an `UnserializableParamError`.
+    Otherwise, the serialization of `{ foo: null }` would conflict with `{ foo: '' }`.
+    This serializer chooses to support the more common and more useful case of `null`.
 - The primitive `number` and `bigint` types are serialized using `.toString()`.
 - The primitive `boolean` type is serialized using `.toString()`,
   e.g., `{ foo: true, bar: false }` serializes to `foo=true&bar=false`.
-- The primitive `null` and `undefined` values are removed,
-  e.g., `{ foo: null, bar: undefined, baz: 1 }` serializes to `baz=1`.
 - `Date` objects are detected and serialized using `Date.toISOString()`,
   e.g., `{ foo: new Date(0) }` serializes to `foo=1970-01-01T00%3A00%3A00.000Z`.
 - `Temporal.Instant` objects are detected and serialized by first converting them to `Date`
@@ -41,20 +44,60 @@ the consumer parsing the string, it can be unambigously parsed back to the origi
   - The array `{ foo: [1, 2] }` serializes to `foo=1&foo=2`.
   - The single element array `{ foo: [1] }` serializes to `foo=1`.
   - The empty array `{ foo: [] }` serializes to `foo=`.
+    As this serialization overlaps with `null`, parser implementations are advised
+    not to support nullable array parameters and parse this as the empty array.
+  - To support typed tuples, serialization of arrays containing mixed values is allowed.
   - Serialization of arrays containing `null` or `undefined` values
     is not supported and will throw an `UnserializableParamError`.
-  - Serialization of the single element array containing the empty string
+  - Serialization of arrays containing the empty string
     is not supported and will throw an `UnserializableParamError`.
     Otherwise, the serialization of `{ foo: [''] }` would conflict with `{ foo: [] }`.
     This serializer chooses to support the more common and more useful case of an empty array.
 - Serialization of objects and nested objects first serializes the keys
   to dot-path format and then serializes the values as above, e.g.,
   `{ foo: 'a', bar: { baz: 'b', fizz: [1, 2] } }` serializes to
   `foo=a&bar.baz=b&bar.fizz=1&bar.fizz=2`.
+- Serialization of keys containing a `.`
+  is not supported and will throw an `UnserializableParamError`.
 - Serialization of nested arrays or objects nested inside arrays
   is not supported and will throw an `UnserializableParamError`.
 - Serialization of functions or other objects is
   is not supported and will throw an `UnserializableParamError`.
+- Serialization of `NaN`, `Infinity`, and `-Infinity`
+  is not supported and will throw an `UnserializableParamError`.
+
+### Compatible parsing strategy
+
+Serialization is guaranteed to be well-defined within each type, i.e.,
+if the value-type for a given key in the query string is fixed and known by
+the consumer parsing the string, it can be unambigously parsed back to the original primitive value:
+
+- A parser can implement a inverse function to the serialization if it uses a schema which,
+  for each node, defines a type matching exactly one of the primitive or nested types below.
+- Any node may be marked optional, i.e., `undefined`, which corresponds to the absence of the key in the query string.
+- The parser may choose `Temporal.Instant` as an equivalent alternative to `Date`.
+- Object keys must not include a `.`.
+
+##### Primitive
+
+- `string | null`.
+  - Excludes zero-length strings.
+- `number | null`.
+- `bigint | null`.
+- `boolean | null`.
+- `Date | null`.
+- `Array<string | number | bigint | boolean | Date>`.
+  - Excludes zero-length strings.
+  - Arrays must use a single value-type.
+  - Otherwise, the array may be a tuple which may use a different value-type per slot.
+
+#### Nested
+
+- `object | null`.
+  - Must meet the same constraints as the top level schema.
+- `Record | null`.
+  - The record type must use a `string` type for the key,
+    and a single primitive or single nested type for the value.
 
 ## Installation
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamapi/url-search-params-serializer",
-  "version": "1.3.0",
+  "version": "2.0.0-beta.1",
   "description": "Serializes JavaScript objects to URLSearchParams.",
   "type": "module",
   "main": "index.js",

package.json

@@ -1,7 +1,7 @@
 import { isDateLike, isTemporalInstantLike } from './date.js'
 import { isPlainObject } from './object.js'
 
-type Params = Record<string, unknown>
+export type Params = Record<string, unknown>
 
 export const serializeUrlSearchParams = (params: Params): string => {
   const searchParams = new URLSearchParams()
@@ -23,6 +23,13 @@ const nestedUpdateUrlSearchParams = (
   path: string[],
 ): void => {
   for (const [key, value] of Object.entries(params)) {
+    if (key.includes('.')) {
+      throw new UnserializableParamError(
+        key,
+        'contains one or more dots "." in its name which is unsupported',
+      )
+    }
+
     const currentPath = [...path, key]
     if (isPlainObject(value)) {
       nestedUpdateUrlSearchParams(searchParams, value, currentPath)
@@ -31,14 +38,32 @@ const nestedUpdateUrlSearchParams = (
 
     const name = currentPath.join('.')
 
-    if (value == null) continue
+    if (value == null && value !== null) {
+      continue
+    }
 
     if (Array.isArray(value)) {
-      if (value.length === 0) searchParams.set(name, '')
+      if (value.length === 0) {
+        searchParams.set(name, '')
+        continue
+      }
+
       if (value.length === 1 && value[0] === '') {
         throw new UnserializableParamError(
           name,
-          `is a single element array containing the empty string which is unsupported because it serializes to the empty array`,
+          'is a single element array containing the empty string which is unsupported',
+        )
+      }
+      if (value.some((v) => v === '')) {
+        throw new UnserializableParamError(
+          name,
+          'is an array containing the empty string which is unsupported',
+        )
+      }
+      if (value.some((v) => v == null)) {
+        throw new UnserializableParamError(
+          name,
+          'is an array containing null or undefined values which is unsupported',
         )
       }
       for (const v of value) {
@@ -52,8 +77,29 @@ const nestedUpdateUrlSearchParams = (
 }
 
 const serialize = (k: string, v: unknown): string => {
-  if (typeof v === 'string') return v.toString()
-  if (typeof v === 'number') return v.toString()
+  if (v === null) return ''
+  if (typeof v === 'string') {
+    if (v.length === 0) {
+      throw new UnserializableParamError(
+        k,
+        'is the empty string which is unsupported',
+      )
+    }
+    return v.toString()
+  }
+  if (typeof v === 'number') {
+    if (
+      isNaN(v) ||
+      v === Infinity ||
+      v === -Infinity ||
+      v.toString() === 'NaN' ||
+      v.toString() === 'Infinity' ||
+      v.toString() === '-Infinity'
+    ) {
+      throw new UnserializableParamError(k, `is ${v}`)
+    }
+    return v.toString()
+  }
   if (typeof v === 'bigint') return v.toString()
   if (typeof v === 'boolean') return v.toString()
   if (isDateLike(v)) return v.toISOString()

src/lib/serialize.ts

@@ -32,9 +32,9 @@ test('removes undefined params', (t) => {
   t.is(serializeUrlSearchParams({ foo: 1, bar: undefined }), 'foo=1')
 })
 
-test('removes null params', (t) => {
-  t.is(serializeUrlSearchParams({ bar: null }), '')
-  t.is(serializeUrlSearchParams({ foo: 1, bar: null }), 'foo=1')
+test('serializes null params', (t) => {
+  t.is(serializeUrlSearchParams({ bar: null }), 'bar=')
+  t.is(serializeUrlSearchParams({ foo: 1, bar: null }), 'bar=&foo=1')
 })
 
 test('serializes empty array params', (t) => {
@@ -56,24 +56,6 @@ test('serializes array params with many values', (t) => {
     serializeUrlSearchParams({ foo: 1, bar: ['null', '2', 'undefined'] }),
     'bar=null&bar=2&bar=undefined&foo=1',
   )
-  t.is(
-    serializeUrlSearchParams({ foo: 1, bar: ['', '', ''] }),
-    'bar=&bar=&bar=&foo=1',
-  )
-  t.is(
-    serializeUrlSearchParams({ foo: 1, bar: ['', 'a', '2'] }),
-    'bar=&bar=a&bar=2&foo=1',
-  )
-  t.is(
-    serializeUrlSearchParams({ foo: 1, bar: ['', 'a', ''] }),
-    'bar=&bar=a&bar=&foo=1',
-  )
-})
-
-test('cannot serialize single element array params with empty string', (t) => {
-  t.throws(() => serializeUrlSearchParams({ foo: [''] }), {
-    instanceOf: UnserializableParamError,
-  })
 })
 
 test('serializes Date', (t) => {
@@ -116,7 +98,7 @@ test('serializes plain objects', (t) => {
       foo: 1,
       bar: { baz: { x: { z: null } } },
     }),
-    'foo=1',
+    'bar.baz.x.z=&foo=1',
   )
 
   t.is(
@@ -128,12 +110,33 @@ test('serializes plain objects', (t) => {
   )
 })
 
+test('cannot serialize keys containing a .', (t) => {
+  t.throws(() => serializeUrlSearchParams({ 'foo.bar': 1 }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: { 'bar.baz': 1 } }), {
+    instanceOf: UnserializableParamError,
+  })
+})
+
 test('cannot serialize functions', (t) => {
   t.throws(() => serializeUrlSearchParams({ foo: () => {} }), {
     instanceOf: UnserializableParamError,
   })
 })
 
+test('cannot serialize number pointers', (t) => {
+  t.throws(() => serializeUrlSearchParams({ foo: Infinity }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: -Infinity }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: -NaN }), {
+    instanceOf: UnserializableParamError,
+  })
+})
+
 test('cannot serialize non-plain objects', (t) => {
   class Foo {
     bar: string
@@ -147,6 +150,9 @@ test('cannot serialize non-plain objects', (t) => {
 })
 
 test('cannot serialize array params with unserializable values', (t) => {
+  t.throws(() => serializeUrlSearchParams({ foo: [''] }), {
+    instanceOf: UnserializableParamError,
+  })
   t.throws(() => serializeUrlSearchParams({ bar: ['a', null] }), {
     instanceOf: UnserializableParamError,
   })
@@ -171,4 +177,13 @@ test('cannot serialize array params with unserializable values', (t) => {
   t.throws(() => serializeUrlSearchParams({ bar: ['a', () => {}] }), {
     instanceOf: UnserializableParamError,
   })
+  t.throws(() => serializeUrlSearchParams({ foo: 1, bar: ['', 'a', ''] }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: 1, bar: ['', 'a', '2'] }), {
+    instanceOf: UnserializableParamError,
+  })
+  t.throws(() => serializeUrlSearchParams({ foo: 1, bar: ['', '', ''] }), {
+    instanceOf: UnserializableParamError,
+  })
 })