README.md

@clipboard-health/json-api

TypeScript-friendly utilities for adhering to the JSON:API specification.

Table of contents

• Install
• Usage
  • Query helpers
• Local development commands

Install

npm install @clipboard-health/json-api

Usage

Query helpers

From the client, call toClientSearchParams to convert from ClientJsonApiQuery to URLSearchParams:

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`:

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.