feat: json-api query helpers (#6)

.github/workflows/ci.yml

@@ -33,6 +33,7 @@ jobs:
           # GitHub checks PRs out based on the merge commit; we want the branch HEAD.
           ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0
+      - run: git fetch origin main:main
       - uses: nrwl/nx-set-shas@v4
       - uses: actions/cache@v4
         with:

.husky/pre-commit

@@ -1,3 +1,5 @@
+#!/bin/sh
+
 npx lint-staged
 
 if command -v gitleaks >/dev/null; then

cspell.json

@@ -2,13 +2,16 @@
   "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
   "version": "0.2",
   "ignorePaths": [
-    "coverage",
-    "dist",
-    "node_modules",
     ".github/CODEOWNERS",
     ".vscode",
+    "coverage",
     "default.json",
-    "tmp"
+    "dist",
+    "node_modules",
+    "tmp",
+    "packages/json-api/examples/toJsonApiQuery.ts",
+    "packages/json-api/README.md",
+    "packages/json-api/src/lib/toSearchParams.spec.ts"
   ],
   "words": [
     "amannn",
@@ -17,6 +20,7 @@
     "CODEOWNERS",
     "devkit",
     "embedme",
+    "fieldsets",
     "gitleaks",
     "lcov",
     "maxage",

packages/json-api/.eslintrc.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "parserOptions": {
+    "project": "tsconfig.lint.json",
+    "tsconfigRootDir": "packages/json-api"
+  }
+}

packages/json-api/README.md

@@ -0,0 +1,70 @@
+# @clipboard-health/json-api
+
+Utilities for adhering to the [JSON:API](https://jsonapi.org/) specification.
+
+## Table of Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+npm install @clipboard-health/json-api
+```
+
+## Usage
+
+### Query helpers
+
+From the client, call `toSearchParams` to convert from `JsonApiQuery` to `URLSearchParams`:
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/toSearchParams.ts
+
+import { toSearchParams } from "@clipboard-health/json-api";
+
+import { type JsonApiQuery } from "../src/lib/types";
+
+const query: JsonApiQuery = {
+  fields: { dog: ["age", "name"] },
+  filter: { age: ["2", "5"] },
+  include: ["vet"],
+  page: { size: "10" },
+  sort: ["-age"],
+};
+
+console.log(toSearchParams(query).toString());
+// Note: actual result is URL-encoded, but unencoded below for readability
+// => fields[dog]=age,name&filter[age]=2,5&include=vet&page[size]=10&sort=-age
+
+```
+
+From the server, call `toJsonApiQuery` to convert from `URLSearchParams` to `JsonApiQuery`:
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/toJsonApiQuery.ts
+
+import { toJsonApiQuery } from "@clipboard-health/json-api";
+
+const searchParams = new URLSearchParams(
+  "fields%5Bdog%5D=age%2Cname&filter%5Bage%5D=2%2C5&include=vet&page%5Bsize%5D=10&sort=-age",
+);
+
+console.log(toJsonApiQuery(searchParams));
+// => {
+//   fields: { dog: ["age", "name"] },
+//   filter: { age: ["2", "5"] },
+//   include: ["vet"],
+//   page: { size: "10" },
+//   sort: ["-age"],
+// }
+
+```
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

packages/json-api/examples/toJsonApiQuery.ts

@@ -0,0 +1,14 @@
+import { toJsonApiQuery } from "@clipboard-health/json-api";
+
+const searchParams = new URLSearchParams(
+  "fields%5Bdog%5D=age%2Cname&filter%5Bage%5D=2%2C5&include=vet&page%5Bsize%5D=10&sort=-age",
+);
+
+console.log(toJsonApiQuery(searchParams));
+// => {
+//   fields: { dog: ["age", "name"] },
+//   filter: { age: ["2", "5"] },
+//   include: ["vet"],
+//   page: { size: "10" },
+//   sort: ["-age"],
+// }

packages/json-api/examples/toSearchParams.ts

@@ -0,0 +1,15 @@
+import { toSearchParams } from "@clipboard-health/json-api";
+
+import { type JsonApiQuery } from "../src/lib/types";
+
+const query: JsonApiQuery = {
+  fields: { dog: ["age", "name"] },
+  filter: { age: ["2", "5"] },
+  include: ["vet"],
+  page: { size: "10" },
+  sort: ["-age"],
+};
+
+console.log(toSearchParams(query).toString());
+// Note: actual result is URL-encoded, but unencoded below for readability
+// => fields[dog]=age,name&filter[age]=2,5&include=vet&page[size]=10&sort=-age

packages/json-api/jest.config.ts

@@ -0,0 +1,19 @@
+export default {
+  coverageDirectory: "../../coverage/packages/json-api",
+  coveragePathIgnorePatterns: [],
+  coverageThreshold: {
+    global: {
+      branches: 100,
+      functions: 100,
+      lines: 100,
+      statements: 100,
+    },
+  },
+  displayName: "json-api",
+  moduleFileExtensions: ["ts", "js"],
+  preset: "../../jest.preset.js",
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.[tj]s$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.spec.json" }],
+  },
+};

packages/json-api/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@clipboard-health/json-api",
+  "description": "",
+  "version": "0.0.0",
+  "bugs": "https://github.com/clipboardhealth/core-utils/issues",
+  "dependencies": {
+    "tslib": "2.6.3"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clipboardhealth/core-utils.git",
+    "directory": "packages/json-api"
+  },
+  "scripts": {
+    "embed": "embedme README.md"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts"
+}

packages/json-api/project.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "name": "json-api",
+  "projectType": "library",
+  "sourceRoot": "packages/json-api/src",
+  "tags": [],
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "options": {
+        "assets": ["packages/json-api/*.md"],
+        "main": "packages/json-api/src/index.js",
+        "outputPath": "dist/packages/json-api",
+        "tsConfig": "packages/json-api/tsconfig.lib.json"
+      },
+      "outputs": ["{options.outputPath}"]
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "lintFilePatterns": ["packages/json-api/**/*.[jt]s"],
+        "maxWarnings": 0
+      },
+      "outputs": ["{options.outputFile}"]
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "packages/json-api/jest.config.ts"
+      }
+    }
+  }
+}

packages/json-api/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./lib/toJsonApiQuery";
+export * from "./lib/toSearchParams";
+export * from "./lib/types";

packages/json-api/src/lib/toJsonApiQuery.spec.ts

@@ -0,0 +1,99 @@
+import { toJsonApiQuery } from "./toJsonApiQuery";
+
+const BASE_URL = "https://google.com";
+
+describe("toJsonApiQuery", () => {
+  it("returns empty object if no matches", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?hi=there`).searchParams)).toEqual({});
+  });
+
+  it("parses fields", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?fields[dog]=age`).searchParams)).toEqual({
+      fields: { dog: ["age"] },
+    });
+  });
+
+  it("parses fields with multiple values", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?fields[dog]=age,name`).searchParams)).toEqual({
+      fields: { dog: ["age", "name"] },
+    });
+  });
+
+  it("parses filter", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?filter[name]=alice`).searchParams)).toEqual({
+      filter: { name: ["alice"] },
+    });
+  });
+
+  it("parses multiple filters", () => {
+    expect(
+      toJsonApiQuery(new URL(`${BASE_URL}?filter[name]=alice&filter[age]=2`).searchParams),
+    ).toEqual({
+      filter: { age: ["2"], name: ["alice"] },
+    });
+  });
+
+  it("parses filters with multiple values", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?filter[name]=alice,bob`).searchParams)).toEqual({
+      filter: { name: ["alice", "bob"] },
+    });
+  });
+
+  it("parses filter type gte", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?filter[age][gte]=2`).searchParams)).toEqual({
+      filter: { age: { gte: "2" } },
+    });
+  });
+
+  it("parses include", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?include=owner`).searchParams)).toEqual({
+      include: ["owner"],
+    });
+  });
+
+  it("parses include with multiple values", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?include=owner,vet`).searchParams)).toEqual({
+      include: ["owner", "vet"],
+    });
+  });
+
+  it("parses page", () => {
+    expect(
+      toJsonApiQuery(new URL(`${BASE_URL}?page[size]=10&page[cursor]=a2c12`).searchParams),
+    ).toEqual({
+      page: {
+        cursor: "a2c12",
+        size: "10",
+      },
+    });
+  });
+
+  it("parses sort", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?sort=age`).searchParams)).toEqual({
+      sort: ["age"],
+    });
+  });
+
+  it("parses sort with multiple values", () => {
+    expect(toJsonApiQuery(new URL(`${BASE_URL}?sort=age,-name`).searchParams)).toEqual({
+      sort: ["age", "-name"],
+    });
+  });
+
+  it("parses combinations", () => {
+    expect(
+      toJsonApiQuery(
+        new URL(`${BASE_URL}?filter[age]=2&include=vet&sort=age&fields[dog]=age&page[size]=10`)
+          .searchParams,
+      ),
+    ).toEqual({
+      fields: { dog: ["age"] },
+      filter: { age: ["2"] },
+      include: ["vet"],
+      page: {
+        size: "10",
+      },
+      sort: ["age"],
+    });
+  });
+});