Add serialization methods

Author: razor-x

README.md

@@ -3,11 +3,18 @@
 [![npm](https://img.shields.io/npm/v/@seamapi/url-search-params-serializer.svg)](https://www.npmjs.com/package/@seamapi/url-search-params-serializer)
 [![GitHub Actions](https://github.com/seamapi/url-search-params-serializer/actions/workflows/check.yml/badge.svg)](https://github.com/seamapi/url-search-params-serializer/actions/workflows/check.yml)
 
-Serializes JavaScript objects to The URLSearchParams.
+Serializes JavaScript objects to URLSearchParams.
 
 ## Description
 
-TODO
+Defines the standard for how Seam SDK and Seam API consumers
+should serialize objects to [URLSearchParams] in HTTP GET requests.
+
+Serves as a reference implementation for Seam SDKs in other languages.
+
+See the test for the [Serialization behavior](./test/serialization.test.ts).
+
+[URLSearchParams]: https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
 
 ## Installation
 

examples/axios.ts

@@ -0,0 +1,31 @@
+import axios from 'axios'
+import type { Builder, Command, Describe, Handler } from 'landlubber'
+
+import { serializeUrlSearchParams } from '@seamapi/url-search-params-serializer'
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface Options {}
+
+export const command: Command = 'axios'
+
+export const describe: Describe = 'Serialize Axios params'
+
+export const builder: Builder = {}
+
+export const handler: Handler<Options> = async ({ logger }) => {
+  const client = axios.create({
+    paramsSerializer: serializeUrlSearchParams,
+    baseURL: 'https://httpbin.org',
+  })
+  const { data } = await client.get('/get', {
+    params: {
+      a: 'bar',
+      b: 2,
+      c: true,
+      d: null,
+      e: ['a', 2],
+      f: [],
+    },
+  })
+  logger.info({ data }, 'Response')
+}

examples/index.ts

@@ -2,8 +2,8 @@
 
 import landlubber from 'landlubber'
 
-import * as todo from './todo.js'
+import * as axios from './axios.js'
 
-const commands = [todo]
+const commands = [axios]
 
 await landlubber(commands).parse()

examples/todo.ts

@@ -1,7 +1,7 @@
 {
   "name": "@seamapi/url-search-params-serializer",
   "version": "1.0.0",
-  "description": "Serializes JavaScript objects to The URLSearchParams.",
+  "description": "Serializes JavaScript objects to URLSearchParams.",
   "type": "module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -60,6 +60,7 @@
   "devDependencies": {
     "@types/node": "^20.8.10",
     "ava": "^6.0.1",
+    "axios": "^1.6.5",
     "c8": "^9.0.0",
     "del-cli": "^5.0.0",
     "eslint": "^8.9.0",

package-lock.json

@@ -1,2 +1 @@
-export { default } from 'lib/index.js'
 export * from 'lib/index.js'

package.json

@@ -1,2 +1 @@
-export { todo as default } from './todo.js'
-export { todo } from './todo.js'
+export * from './serialize.js'

src/index.ts

@@ -0,0 +1,13 @@
+import test from 'ava'
+
+import { serializeUrlSearchParams, updateUrlSearchParams } from './serialize.js'
+
+test('serializeUrlSearchParams', (t) => {
+  t.is(serializeUrlSearchParams({ foo: 'd', bar: 2 }), 'bar=2&foo=d')
+})
+
+test('updateUrlSearchParams', (t) => {
+  const searchParams = new URLSearchParams()
+  updateUrlSearchParams(searchParams, { foo: 'd', bar: 2 })
+  t.is(searchParams.toString(), 'bar=2&foo=d')
+})

src/lib/index.ts

@@ -0,0 +1,50 @@
+type Params = Record<string, unknown>
+
+export const serializeUrlSearchParams = (params: Params): string => {
+  const searchParams = new URLSearchParams()
+  updateUrlSearchParams(searchParams, params)
+  return searchParams.toString()
+}
+
+export const updateUrlSearchParams = (
+  searchParams: URLSearchParams,
+  params: Record<string, unknown>,
+): void => {
+  for (const [name, value] of Object.entries(params)) {
+    if (value == null) continue
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) searchParams.set(name, '')
+      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`,
+        )
+      }
+      for (const v of value) {
+        searchParams.append(name, serialize(name, v))
+      }
+      continue
+    }
+
+    searchParams.set(name, serialize(name, value))
+  }
+
+  searchParams.sort()
+}
+
+const serialize = (k: string, v: unknown): string => {
+  if (typeof v === 'string') return v.toString()
+  if (typeof v === 'number') return v.toString()
+  if (typeof v === 'bigint') return v.toString()
+  if (typeof v === 'boolean') return v.toString()
+  throw new UnserializableParamError(k, `is a ${typeof v}`)
+}
+
+export class UnserializableParamError extends Error {
+  constructor(name: string, message: string) {
+    super(`Could not serialize parameter: '${name}' ${message}`)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+  }
+}