feat: add examples for serializing and parsing URL search params

README.markdown

@@ -2,7 +2,48 @@
 
 A library for serializing and parsing URLSearchParams using Zod schemas.
 
-## Example
+## examples
 
-For a usage example, see [docs/readme-example.ts](docs/readme-example.ts).
+### serializing
 
+```ts
+import assert from "node:assert"
+import { z } from "zod"
+import { ZodURLSearchParamSerializer } from "../dist"
+
+// setup your schema
+const schema = z.object({ name: z.string(), age: z.number(), hobbies: z.array(z.string()) })
+
+// setup the serializer
+const serializer = new ZodURLSearchParamSerializer(schema)
+
+const data = { name: "John Doe", age: 30, hobbies: ["reading", "cycling"] }
+
+// serialize it to url params, see how it looks–
+const params = serializer.serialize(data)
+assert.strictEqual(params.toString(), "name=John+Doe&age=30&hobbies=reading&hobbies=cycling")
+```
+
+### parsing
+
+```ts
+// sometimes people will visit a url that doesn't conform
+const invalidParams = new URLSearchParams("name=Jane+Doe&age=invalid&hobbies=reading&hobbies=gardening")
+
+// so we provide defaults to fall back to
+const defaultData: z.infer<typeof schema> = {
+	name: "Default Name",
+	age: 25,
+	hobbies: ["default hobby"],
+}
+
+// parse it :4)
+const lenientResult = serializer.lenientParse(invalidParams, defaultData)
+
+// it'll drop the invalid field and use the default value
+assert.deepStrictEqual(lenientResult, {
+	name: "Jane Doe",
+	age: 25, // Uses default value because 'invalid' can't be parsed as a number
+	hobbies: ["reading", "gardening"],
+})
+```

docs/readme-example.ts

@@ -2,12 +2,14 @@ import assert from "node:assert"
 import { z } from "zod"
 import { ZodURLSearchParamSerializer } from "../dist"
 
+// setup your schema
 const schema = z.object({
 	name: z.string(),
 	age: z.number(),
 	hobbies: z.array(z.string()),
 })
 
+// setup the serializer
 const serializer = new ZodURLSearchParamSerializer(schema)
 
 const data = {
@@ -17,21 +19,22 @@ const data = {
 }
 
 const params = serializer.serialize(data)
-
 assert.strictEqual(params.toString(), "name=John+Doe&age=30&hobbies=reading&hobbies=cycling")
 
-// Example of lenientParse
-const invalidParams = new URLSearchParams(
-	"name=Jane+Doe&age=invalid&hobbies=reading&hobbies=gardening",
-)
-const defaultData = {
+// sometimes people will visit a url that doesn't conform
+const invalidParams = new URLSearchParams("name=Jane+Doe&age=invalid&hobbies=reading&hobbies=gardening")
+
+// so we provide defaults to fall back to
+const defaultData: z.infer<typeof schema> = {
 	name: "Default Name",
 	age: 25,
 	hobbies: ["default hobby"],
 }
 
+// parse it :4)
 const lenientResult = serializer.lenientParse(invalidParams, defaultData)
 
+// it'll drop the invalid field and use the default value
 assert.deepStrictEqual(lenientResult, {
 	name: "Jane Doe",
 	age: 25, // Uses default value because 'invalid' can't be parsed as a number