chore: Add docs (#6)

CONVENTIONS.md

@@ -2,3 +2,4 @@
 - Avoid unsafe types like any
 - Prefer checking for presence with 'val == null' instead of '!val'
 - Use unique test identifiers
+- Don't add comments

README.markdown

@@ -1,3 +1,66 @@
 # zod urlsearchparams
 
-a work in progress
+convert a zod object to a URLSearchParam and vice versa.
+
+- minimal urls, scalars are readable and editable by humans
+- vectors are encoded with base64
+- allows gracefully falling back to defaults with `lenientParse` 
+- zero dependencies outside of zod
+
+## install
+
+```bash
+npm i zod-urlsearchparams
+pnpm i zod-urlsearchparams
+yarn add zod-urlsearchparams
+ni zod-urlsearchparams
+```
+
+## examples
+
+note: the following examples use the ZodURLSearchParamSerializer class api, but `serialize`, `parse`, `shape`, `lenientParse` etc are exported on their own too.
+
+### serializing
+
+```ts
+import assert from "node:assert"
+import { z } from "zod"
+import { ZodURLSearchParamSerializer } from "zod-urlsearchparams"
+
+// 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)
+
+// serialize some data to url params
+const data = { name: "John Doe", age: 30, hobbies: ["reading", "cycling"] }
+const params = serializer.serialize(data)
+
+// see how it looks–
+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=nope&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 'nope' can't be parsed as a number
+	hobbies: ["reading", "gardening"],
+})
+```