Add parseUrlSearchParams

README.md

@@ -7,7 +7,34 @@ Parses URLSearchParams to JavaScript objects according to Zod schemas.
 
 ## Description
 
-TODO
+### Allowed Zod Schemas
+
+- The top-level schema must be an `z.object()` or `z.union()` of `z.object()`.
+- Properties may be a `z.object()` or `z.union()` of objects.
+- All union object types must flatten to a parseable object schema with non-conflicting property types.
+- Primitive properties must be a `z.string()`, `z.number()`, `z.boolean()` or `z.date()`.
+  - Properties must be a single-value type
+  - The primitives `z.bigint()` and `z.symbol()` are not supported.
+  - Strings with zero length are not allowed.
+    If not specified, a `z.string()` is always assumed to be `z.string().min(1)`.
+  - Using `z.enum()` is allowed and equivalent to `z.string()`.
+- Any property may be `z.optional()` or `z.never()`.
+- No property may `z.void()`, `z.undefined()`, `z.any()`, or `z.unknown()`.
+- Any property may be `z.nullable()` except `z.array()`.
+- Properties that are `z.literal()` are allowed and must still obey all of these rules.
+- A `z.array()` must be of a single value-type.
+  - The value-types must obey all the same basic rules
+    for primitive object, union, and property types.
+  - Value-types may not be `z.nullable()` or `z.undefined()`.
+  - The value-type cannot be an `z.array()` or contain a nested `z.array()` at any level.
+- A `z.record()` has less-strict schema constraints but weaker parsing guarantees:
+  - They keys must be `z.string()`.
+  - The value-type may be a single primitive type.
+  - The value-type may be a union of primitives.
+    This union must include `z.string()`
+    and all values will be parsed as `z.string()`.
+  - The value-type may be `z.nullable()`.
+  - The value-type may not be a `z.record()`, `z.array()`, or `z.object()`.
 
 ## Installation
 

examples/index.ts

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

examples/parse.ts

@@ -0,0 +1,47 @@
+import type { Builder, Command, Describe, Handler } from 'landlubber'
+import { z } from 'zod'
+
+import { parseUrlSearchParams } from '@seamapi/url-search-params-parser'
+
+interface Options {
+  query: string
+}
+
+export const command: Command = 'parse query'
+
+export const describe: Describe = 'Parse query'
+
+export const builder: Builder = {
+  query: {
+    type: 'string',
+    describe: 'Query string',
+  },
+}
+
+export const handler: Handler<Options> = async ({ query, logger }) => {
+  logger.info({ data: parseUrlSearchParams(query, schema) }, 'params')
+}
+
+const schema = z
+  .object({
+    a: z.string(),
+    b: z.number(),
+    c: z.boolean(),
+    d: z.null(),
+    e: z.array(z.union([z.string(), z.number()])),
+    f: z.array(z.string()),
+    g: z.date(),
+    h: z.date(),
+    i: z
+      .object({
+        foo: z.number(),
+        bar: z
+          .object({
+            baz: z.number(),
+            fizz: z.array(z.union([z.string(), z.number()])),
+          })
+          .optional(),
+      })
+      .optional(),
+  })
+  .optional()

package.json

@@ -67,7 +67,11 @@
     "node": ">=18.12.0",
     "npm": ">= 9.0.0"
   },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
   "devDependencies": {
+    "@seamapi/url-search-params-serializer": "^1.3.0",
     "@types/node": "^20.8.10",
     "ava": "^6.0.1",
     "c8": "^10.1.2",
@@ -83,6 +87,7 @@
     "tsc-alias": "^1.8.2",
     "tsup": "^8.0.1",
     "tsx": "^4.6.2",
-    "typescript": "~5.3.3"
+    "typescript": "~5.3.3",
+    "zod": "^3.24.2"
   }
 }

src/lib/index.ts

@@ -1 +1 @@
-export { todo } from './todo.js'
+export * from './parse.js'

src/lib/parse.test.ts

@@ -0,0 +1,25 @@
+import test from 'ava'
+import { z } from 'zod'
+
+import { parseUrlSearchParams } from './parse.js'
+
+test('parseUrlSearchParams: with string input', (t) => {
+  t.deepEqual(
+    parseUrlSearchParams(
+      'foo=d&bar=2',
+      z.object({ foo: z.string().optional(), bar: z.number().optional() }),
+    ),
+    { foo: 'd', bar: 2 },
+  )
+})
+
+test('parseUrlSearchParams: with URLSearchParams input', (t) => {
+  t.deepEqual(
+    parseUrlSearchParams(
+      new URLSearchParams('foo=d&bar=2'),
+      z.object({ foo: z.string().optional(), bar: z.number().optional() }),
+    ),
+    { foo: 'd', bar: 2 },
+    'with URLSearchParams input',
+  )
+})

src/lib/parse.ts

@@ -0,0 +1,73 @@
+import type { ZodTypeAny } from 'zod'
+
+import {
+  type ParamSchema,
+  type ValueType,
+  zodSchemaToParamSchema,
+} from './schema.js'
+import { isZodObject } from './zod.js'
+
+export const parseUrlSearchParams = (
+  query: URLSearchParams | string,
+  schema: ZodTypeAny,
+): Record<string, unknown> => {
+  const searchParams =
+    typeof query === 'string' ? new URLSearchParams(query) : query
+
+  if (!isZodObject(schema)) {
+    throw new Error(
+      'The Zod schema to parse URL search params must be an ZodObject schema',
+    )
+  }
+
+  const paramSchema = zodSchemaToParamSchema(schema)
+  return parseFromParamSchema(searchParams, paramSchema, []) as Record<
+    string,
+    unknown
+  >
+}
+
+const parseFromParamSchema = (
+  searchParams: URLSearchParams,
+  node: ParamSchema | ValueType,
+  path: string[],
+): Record<string, unknown> | unknown => {
+  if (typeof node === 'string') {
+    // TODO: For array parsing, try to lookup foo=, then foo[]= patterns,
+    // if only one match, try to detect commas, otherwise ignore commas.
+    // if both foo= and foo[]= this is a parse error
+    // more generally, try to find a matching key for this node in the searchParams
+    // and throw if conflicting keys are found, e.g, both foo= and foo[]=
+    const key = path.join('.')
+    return parse(key, searchParams.getAll(key), node)
+  }
+
+  const entries = Object.entries(node).reduce<
+    Array<[string, Record<string, unknown> | unknown]>
+  >((acc, entry) => {
+    const [k, v] = entry
+    const currentPath = [...path, k]
+    return [...acc, [k, parseFromParamSchema(searchParams, v, currentPath)]]
+  }, [])
+
+  return Object.fromEntries(entries)
+}
+
+const parse = (k: string, values: string[], type: ValueType): unknown => {
+  // TODO: Add better errors with coercion. If coercion fails, passthough?
+  // TODO: Is this Number parsing safe?
+  if (values.length === 0) return undefined
+  if (type === 'number') return Number(values[0])
+  if (type === 'boolean') return values[0] === 'true'
+  if (type === 'string') return String(values[0])
+  if (type === 'string_array') return values
+  if (type === 'number_array') return values.map((v) => Number(v))
+  throw new UnparseableSearchParamError(k, 'unsupported type')
+}
+
+export class UnparseableSearchParamError extends Error {
+  constructor(name: string, message: string) {
+    super(`Could not parse parameter: '${name}' ${message}`)
+    this.name = this.constructor.name
+  }
+}

src/lib/schema.test.ts

@@ -0,0 +1,80 @@
+import test from 'ava'
+import { z } from 'zod'
+
+import { UnparseableSchemaError, zodSchemaToParamSchema } from './schema.js'
+
+test('zodSchemaToParamSchema: parses flat object schemas', (t) => {
+  t.deepEqual(zodSchemaToParamSchema(z.object({ foo: z.string() })), {
+    foo: 'string',
+  })
+  t.deepEqual(
+    zodSchemaToParamSchema(
+      z.object({
+        a: z.string(),
+        b: z.number(),
+        c: z.boolean(),
+        d: z.array(z.string()),
+      }),
+    ),
+    {
+      a: 'string',
+      b: 'number',
+      c: 'boolean',
+      d: 'string_array',
+    },
+  )
+})
+
+test('zodSchemaToParamSchema: parses nested object schemas', (t) => {
+  t.deepEqual(zodSchemaToParamSchema(z.object({ foo: z.string() })), {
+    foo: 'string',
+  })
+  t.deepEqual(
+    zodSchemaToParamSchema(
+      z.object({
+        a: z.string(),
+        b: z.object({
+          c: z.boolean(),
+          d: z.array(z.string()),
+          e: z.object({
+            f: z.boolean(),
+          }),
+        }),
+      }),
+    ),
+    {
+      a: 'string',
+      b: {
+        c: 'boolean',
+        d: 'string_array',
+        e: {
+          f: 'boolean',
+        },
+      },
+    },
+  )
+})
+
+test('zodSchemaToParamSchema: cannot parse non-object schemas', (t) => {
+  t.throws(() => zodSchemaToParamSchema(z.number()), {
+    instanceOf: UnparseableSchemaError,
+  })
+  t.throws(() => zodSchemaToParamSchema(z.enum(['foo'])), {
+    instanceOf: UnparseableSchemaError,
+  })
+  t.throws(() => zodSchemaToParamSchema(z.string()), {
+    instanceOf: UnparseableSchemaError,
+  })
+  t.throws(() => zodSchemaToParamSchema(z.map(z.string(), z.string())), {
+    instanceOf: UnparseableSchemaError,
+  })
+  t.throws(() => zodSchemaToParamSchema(z.array(z.string())), {
+    instanceOf: UnparseableSchemaError,
+  })
+  t.throws(() => zodSchemaToParamSchema(z.null()), {
+    instanceOf: UnparseableSchemaError,
+  })
+  t.throws(() => zodSchemaToParamSchema(z.union([z.number(), z.string()])), {
+    instanceOf: UnparseableSchemaError,
+  })
+})