docs: document codec inversion

Author: colinhacks

packages/docs/content/api.mdx

@@ -2564,6 +2564,15 @@ To perform the *reverse transform*, use the inverse: `z.encode()`.
 z.encode(stringToDate, new Date("2024-01-15")); // => "2024-01-15T00:00:00.000Z"
 ```
 
+Use `z.invertCodec()` to derive a new codec with the input and output schemas swapped.
+
+```ts
+const dateToString = z.invertCodec(stringToDate);
+
+z.decode(dateToString, new Date("2024-01-15")); // => string
+z.encode(dateToString, "2024-01-15T00:00:00.000Z"); // => Date
+```
+
 Refer to the dedicated [Codecs](/codecs) page for more information. That page contains implementations for commonly-needed codecs that you can copy/paste into your project:
 
 - [**`stringToNumber`**](/codecs#stringtonumber)

packages/docs/content/codecs.mdx

@@ -92,6 +92,37 @@ This is particularly useful when parsing data at a network boundary. You can sha
   alt="Codecs encoding and decoding data across a network boundary" 
 />
 
+### Inverting codecs
+
+Use `z.invertCodec()` to derive the reverse codec from an existing one. The returned codec swaps the input and output schemas, then swaps the `decode` and `encode` transforms.
+
+<Tabs items={['Zod', 'Zod Mini']}>
+<Tab value="Zod">
+```ts
+const dateToString = z.invertCodec(stringToDate);
+
+dateToString.decode(new Date("2024-01-15T10:30:00.000Z"));
+// => string
+
+dateToString.encode("2024-01-15T10:30:00.000Z");
+// => Date
+```
+</Tab>
+<Tab value="Zod Mini">
+```ts
+const dateToString = z.invertCodec(stringToDate);
+
+z.decode(dateToString, new Date("2024-01-15T10:30:00.000Z"));
+// => string
+
+z.encode(dateToString, "2024-01-15T10:30:00.000Z");
+// => Date
+```
+</Tab>
+</Tabs>
+
+`z.invertCodec()` only inverts the codec you pass to it. It does not recursively invert codecs nested inside another schema; invert those codecs where you define the reversed schema.
+
 ### Composability
 
 > **Note** — You can use `z.encode()` and `z.decode()` with any schema. It doesn't have to be a ZodCodec.