@clipboard-health/json-api
v0.14.1
Published
TypeScript-friendly utilities for adhering to the JSON:API specification.
Downloads
9,534
Keywords
Readme
@clipboard-health/json-api
TypeScript-friendly utilities for adhering to the JSON:API specification.
Table of contents
Install
npm install @clipboard-health/json-api
Usage
Query helpers
From the client, call toClientSearchParams
to convert from ClientJsonApiQuery
to URLSearchParams
:
// ./examples/toClientSearchParams.ts
import { deepEqual } from "node:assert/strict";
import { toClientSearchParams } from "@clipboard-health/json-api";
import { type ClientJsonApiQuery } from "../src/lib/types";
const [date1, date2] = ["2024-01-01", "2024-01-02"];
const query: ClientJsonApiQuery = {
fields: { user: ["age", "dateOfBirth"] },
filter: {
age: { eq: ["2"] },
dateOfBirth: { gt: [date1], lt: [date2] },
isActive: { eq: ["true"] },
},
include: ["article"],
page: {
size: "10",
},
sort: ["-age"],
};
deepEqual(
toClientSearchParams(query).toString(),
new URLSearchParams(
`fields[user]=age,dateOfBirth&filter[age]=2&filter[dateOfBirth][gt]=${date1}&filter[dateOfBirth][lt]=${date2}&filter[isActive]=true&include=article&page[size]=10&sort=-age`,
).toString(),
);
From the server, call toServerJsonApiQuery
to convert from URLSearchParams
to ServerJsonApiQuery
:
// ./examples/toServerJsonApiQuery.ts
import { deepEqual } from "node:assert/strict";
import { type ServerJsonApiQuery, toServerJsonApiQuery } from "@clipboard-health/json-api";
const [date1, date2] = ["2024-01-01", "2024-01-02"];
// The URLSearchParams constructor also supports URL-encoded strings
const searchParams = new URLSearchParams(
`fields[user]=age,dateOfBirth&filter[age]=2&filter[dateOfBirth][gt]=${date1}&filter[dateOfBirth][lt]=${date2}&filter[isActive]=true&include=article&page[size]=10&sort=-age`,
);
const query: ServerJsonApiQuery = toServerJsonApiQuery(searchParams);
deepEqual(query, {
fields: { user: ["age", "dateOfBirth"] },
filter: {
age: { eq: ["2"] },
dateOfBirth: { gt: [date1], lt: [date2] },
isActive: { eq: ["true"] },
},
include: ["article"],
page: {
size: "10",
},
sort: ["-age"],
});
Local development commands
See package.json
scripts
for a list of commands.