diff --git a/docs/1.getting-started/6.data-fetching.md b/docs/1.getting-started/6.data-fetching.md index 214ffd80a1..d79a894087 100644 --- a/docs/1.getting-started/6.data-fetching.md +++ b/docs/1.getting-started/6.data-fetching.md @@ -135,26 +135,26 @@ You can make use of the `refresh()` method returned from the `useFetch()` compos ```vue ``` The key to making this work is to call the `refresh()` method returned from the `useFetch()` composable when a query parameter has changed. -By default, `refresh()` will cancel any pending requests; their result will not update the data or pending state. Any previously awaited promises will not resolve until this new request resolves. You can prevent this behaviour by setting the `dedupe` option, which will instead return the promise for the currently-executing request, if there is one. +By default, `refresh()` will cancel any pending requests their result will not update the data or pending state. Any previously awaited promises will not resolve until this new request resolves. You can prevent this behaviour by setting the `dedupe` option, which will instead return the promise for the currently-executing request, if there is one. ```js refresh({ dedupe: true }) @@ -387,3 +387,100 @@ export default defineComponent({ ``` +## Serialization + +When fetching data from the `server` directory, the response is serialized using `JSON.stringify`. However, since serialization is limited to only JavaScript primitive types, Nuxt does its best to convert the return type of `$fetch` and `useFetch` to match the actual value. + +::alert{icon=👉} +You can learn more about `JSON.stringify` limitations [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description). +:: + +### Example + +```ts [server/api/foo.ts] +export default defineEventHandler(() => { + return new Date() +}) +``` + +```vue [app.vue] + +``` + +### Custom serializer function + +To customize the serialization behavior, you can define a `toJSON` function on your returned object. If you define a `toJSON` method, Nuxt will respect the return type of the function and will not try to convert the types. + +```ts [server/api/bar.ts] +export default defineEventHandler(() => { + const data = { + createdAt: new Date(), + + toJSON() { + return { + createdAt: { + year: this.createdAt.getFullYear(), + month: this.createdAt.getMonth(), + day: this.createdAt.getDate(), + }, + } + }, + } + return data +}) + +``` + +```vue [app.vue] + +``` + +### Using an alternative serializer + +Nuxt does not currently support an alternative serializer to `JSON.stringify`. However, you can return your payload as a normal string and utilize the `toJSON` method to maintain type safety. + +In the example below, we use [superjson](github.com/blitz-js/superjson) as our serializer. + +```ts [server/api/superjson.ts] +import superjson from 'superjson' + +export default defineEventHandler(() => { + const data = { + createdAt: new Date(), + + // Workaround the type conversion + toJSON() { + return this + } + } + + // Serialize the output to string, using superjson + return superjson.stringify(data) as unknown as typeof data +}) +``` + +```vue [app.vue] + +```