--- title: Transforming data on fetch --- import FrameworkPlayground from '@site/src/components/FrameworkPlayground'; import { RestEndpoint } from '@data-client/rest'; Transform data in [RestEndpoint](../api/RestEndpoint.md) members: [process()](../api/RestEndpoint.md#process) for responses, [getRequestInit()](../api/RestEndpoint.md#getRequestInit) for request bodies, and [parseResponse()](../api/RestEndpoint.md#parseResponse) for headers and raw bodies. To change one Entity's fields wherever it appears, including lists and nested data, use [Entity.process()](../api/Entity.md#process). :::tip If you control the API, change the data it sends instead. A thin client is faster and simpler. Use these transforms for APIs you do not control. ::: ## Snakes to camels Many APIs use `snake_case` keys. To use `camelCase` in TypeScript, transform the keys in both directions. ```typescript title="CamelResource.ts" import { camelCase, snakeCase } from 'lodash'; import { RestEndpoint, RestGenerics } from '@data-client/rest'; function deeplyApplyKeyTransform(obj: any, transform: (key: string) => string) { const ret: Record = Array.isArray(obj) ? [] : {}; Object.keys(obj).forEach(key => { if (obj[key] != null && typeof obj[key] === 'object') { ret[transform(key)] = deeplyApplyKeyTransform(obj[key], transform); } else { ret[transform(key)] = obj[key]; } }); return ret; } class CamelEndpoint extends RestEndpoint { getRequestInit(body) { // we'll need to do the inverse operation when sending data back to the server if (body) { return super.getRequestInit(deeplyApplyKeyTransform(body, snakeCase)); } return super.getRequestInit(body); } process(value) { // a 204 response has no body return value && deeplyApplyKeyTransform(value, camelCase); } } ``` ## Deserializing fields JSON has few types, so APIs send many values as strings. Examples are [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) dates and high-precision decimals ([floats can be lossy](https://floating-point-gui.de/)). Strings are fine to display. To compute with them, such as adding time to a date or multiplying two numbers, deserialize them. Use [Entity.schema](../api/Entity.md#schema) with [Temporal.Instant](https://tc39.es/proposal-temporal/) and [BigNumber](https://github.com/MikeMcl/bignumber.js): ```tsx title="api/Price" import { Entity, RestEndpoint } from '@data-client/rest'; import { Temporal } from 'temporal-polyfill'; import BigNumber from 'bignumber.js'; export class ExchangePrice extends Entity { exchangePair = ''; updatedAt = Temporal.Instant.fromEpochMilliseconds(0); price = new BigNumber(0); pk() { return this.exchangePair; } static key = 'ExchangePrice'; static schema = { updatedAt: Temporal.Instant.from, price: BigNumber, }; } export const getPrice = new RestEndpoint({ path: '/price/:exchangePair', schema: ExchangePrice, }); ``` :::react ```tsx title="PricePage" import { useSuspense } from '@data-client/react'; import { getPrice } from './api/Price'; function PricePage() { const currentPrice = useSuspense(getPrice, { exchangePair: 'btc-usd', }); return (
{currentPrice.exchangePair.toUpperCase()}, as of{' '}
${currentPrice.price.toFormat(2)}
); } render(); ``` ::: :::vue ```html title="PricePage.vue" ``` :::
### Deserializing Date To use the legacy [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), wrap its constructor in a function [schema](../api/schema.md). ```ts export class ExchangePrice extends Entity { exchangePair = ''; updatedAt = new Date(0); price = new BigNumber(0); pk() { return this.exchangePair; } static key = 'ExchangePrice'; static schema = { // highlight-next-line updatedAt: iso => new Date(iso), price: BigNumber, }; } ``` ## Case of the missing `Id` Some APIs leave the primary key out of the response. For example, `https://mystreamsite.tv/[username]/` returns a stream without its `username`, which is the stream's only unique identifier. Add the `username` from the endpoint's arguments in [RestEndpoint.process()](../api/RestEndpoint.md#process). ```json title="GET https://mystreamsite.tv/ntucker/" { "title": "When I'm Grandmaster, I will play faster.", "game": "Starcraft II", "current_viewers": 1337, "live": true } ``` ```typescript title="api/Stream.ts" class Stream extends Entity { username = ''; title = ''; game = ''; currentViewers = 0; live = false; pk() { return this.username; } static key = 'Stream'; } const getStream = new RestEndpoint({ urlPrefix: 'https://mystreamsite.tv', path: '/:username', schema: Stream, // highlight-start process(value, { username }) { value.username = username; return value; }, // highlight-end }); ``` ### Ticker prices Coinbase's ticker response does not include its primary key `product_id`. [RestEndpoint.process()](../api/RestEndpoint.md#process) adds it from the `productId` argument. ```typescript title="Ticker" {29-32} import { Entity, RestEndpoint } from '@data-client/rest'; import { Temporal } from 'temporal-polyfill'; export class Ticker extends Entity { product_id = ''; trade_id = 0; price = 0; size = '0'; time = Temporal.Instant.fromEpochMilliseconds(0); bid = '0'; ask = '0'; volume = ''; pk(): string { return this.product_id; } static key = 'Ticker'; static schema = { price: Number, time: Temporal.Instant.from, }; } export const getTicker = new RestEndpoint({ urlPrefix: 'https://api.exchange.coinbase.com', path: '/products/:productId/ticker', schema: Ticker, process(value, { productId }) { value.product_id = productId; return value; }, pollFrequency: 2000, }); ``` :::react ```tsx title="AssetPrice" {6} collapsed import { useLive } from '@data-client/react'; import NumberFlow from '@number-flow/react'; import { getTicker } from './Ticker'; function AssetPrice({ productId }: Props) { const ticker = useLive(getTicker, { productId }); return (
{productId}
); } interface Props { productId: string; } render(); ``` ::: :::vue ```html title="AssetPrice.vue" {8} collapsed ``` :::
### Key in a nested object Some APIs put the primary key inside a nested object, such as `{ post: { id }, creator, saved }`. Copy it to a top-level `id` in [Entity.process()](../api/Entity.md#process), so lookups take `{ id }`. See [Primary key in a nested object](../api/Entity.md#primary-key-in-a-nested-object) for the example. ## Using HTTP Headers To read HTTP [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers), override [RestEndpoint.parseResponse()](../api/RestEndpoint.md#parseResponse). It receives the fetch [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). For example, cursor-based [pagination](./pagination.md#tokens-in-http-headers) can send its cursor in a header. ```typescript import { RestEndpoint, RestGenerics } from '@data-client/rest'; class GithubEndpoint< O extends RestGenerics = any, > extends RestEndpoint { async parseResponse(response: Response) { const results = await super.parseResponse(response); if ( (response.headers && response.headers.has('link')) || Array.isArray(results) ) { return { link: response.headers.get('link'), results, }; } return results; } } ``` ## File download {#file-download} For endpoints that return binary data (files, images, PDFs), set [`content: 'blob'`](../api/RestEndpoint.md#content). The return type is `Blob` and `schema` defaults to `undefined` (binary data isn't normalizable). Use `dataExpiryLength: 0` to avoid caching large blobs in memory. ```typescript title="downloadFile.ts" import { RestEndpoint } from '@data-client/rest'; export const downloadFile = new RestEndpoint({ path: '/files/:id/download', content: 'blob', dataExpiryLength: 0, }); ``` :::react ```tsx title="DownloadButton.tsx" import { useController } from '@data-client/react'; import { downloadFile } from './downloadFile'; function DownloadButton({ id }: { id: string }) { const ctrl = useController(); const handleDownload = async () => { const blob: Blob = await ctrl.fetch(downloadFile, { id }); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'download'; a.click(); URL.revokeObjectURL(url); }; return ; } ``` ::: :::vue ```html title="DownloadButton.vue" ``` ::: To extract the filename from the `Content-Disposition` header, override [parseResponse](../api/RestEndpoint.md#parseResponse): ```typescript title="downloadFile.ts" import { RestEndpoint } from '@data-client/rest'; export const downloadFile = new RestEndpoint({ path: '/files/:id/download', content: 'blob', dataExpiryLength: 0, async parseResponse(response) { const blob = await response.blob(); const disposition = response.headers.get('Content-Disposition'); const filename = disposition?.match(/filename="?(.+?)"?$/)?.[1] ?? 'download'; return { blob, filename }; }, process(value): { blob: Blob; filename: string } { return value; }, }); ``` For `ArrayBuffer` responses (useful for processing binary data in-memory), use `content: 'arrayBuffer'` the same way. ## Name calling To rename a key the API uses, map it in both directions: the Entity's [process()](../api/Entity.md#process) renames it in every response that contains the Entity, including lists and nested data, and the endpoint's [getRequestInit()](../api/RestEndpoint.md#getRequestInit) renames it back in request bodies. Components then use only your name. ```typescript title="Article.ts" import { Entity, RestEndpoint, RestGenerics } from '@data-client/rest'; export class Article extends Entity { id = ''; carrotsUsed = 0; static process(value: any, parent: any, key: string, args: any[]) { const processed = super.process(value, parent, key, args); if ('carrotsUsedIsThisNameTooLong' in processed) { processed.carrotsUsed = processed.carrotsUsedIsThisNameTooLong; delete processed.carrotsUsedIsThisNameTooLong; } return processed; } } export class RenamedEndpoint< O extends RestGenerics = any, > extends RestEndpoint { getRequestInit(body: any) { if (body && 'carrotsUsed' in body) { const { carrotsUsed, ...rest } = body; return super.getRequestInit({ ...rest, carrotsUsedIsThisNameTooLong: carrotsUsed, }); } return super.getRequestInit(body); } } export const updateArticle = new RenamedEndpoint({ path: '/articles/:id', method: 'PATCH', schema: Article, }); ```