@clipboard-health/json-api 0.1.0

package/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.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@clipboard-health/json-api",
+  "description": "",
+  "version": "0.1.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",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

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

package/src/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/toJsonApiQuery"), exports);
+tslib_1.__exportStar(require("./lib/toSearchParams"), exports);
+tslib_1.__exportStar(require("./lib/types"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/json-api/src/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,+DAAqC;AACrC,sDAA4B"}

package/src/lib/toJsonApiQuery.d.ts

@@ -0,0 +1,7 @@
+import { type JsonApiQuery } from "./types";
+/**
+ * Call this function from clients to convert from {@link URLSearchParams} to {@link JsonApiQuery}.
+ *
+ * @see [Example](https://github.com/ClipboardHealth/core-utils/blob/main/packages/json-api/examples/toJsonApiQuery.ts)
+ */
+export declare function toJsonApiQuery(searchParams: URLSearchParams): JsonApiQuery;

package/src/lib/toJsonApiQuery.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonApiQuery = toJsonApiQuery;
+const REGEX = {
+    fields: /^fields\[(.*?)]$/i,
+    filter: /^filter\[([^\]]*?)]$/i,
+    filterType: /^filter\[(.*?)]\[(.*?)]$/i,
+    include: /^include$/i,
+    page: /^page\[(.*?)]$/i,
+    sort: /^sort$/i,
+};
+/**
+ * Call this function from clients to convert from {@link URLSearchParams} to {@link JsonApiQuery}.
+ *
+ * @see [Example](https://github.com/ClipboardHealth/core-utils/blob/main/packages/json-api/examples/toJsonApiQuery.ts)
+ */
+function toJsonApiQuery(searchParams) {
+    return [...searchParams].reduce((accumulator, [key, value]) => {
+        const match = Object.entries(REGEX).find(([, regex]) => regex.test(key));
+        if (!match) {
+            return accumulator;
+        }
+        const [type, regex] = match;
+        const groups = regex.exec(key)?.slice(1);
+        if (type === "fields" && groups?.[0]) {
+            return {
+                ...accumulator,
+                fields: {
+                    ...accumulator.fields,
+                    [groups[0]]: value.split(","),
+                },
+            };
+        }
+        if ((type === "filter" || type === "filterType") && groups?.length) {
+            const [field, fieldType] = groups;
+            if (field) {
+                return {
+                    ...accumulator,
+                    filter: {
+                        ...accumulator.filter,
+                        [field]: fieldType
+                            ? { ...accumulator.filter?.[field], [fieldType]: value }
+                            : value.split(","),
+                    },
+                };
+            }
+        }
+        if (type === "include" || type === "sort") {
+            return { ...accumulator, [type]: value.split(",") };
+        }
+        if (type === "page" && groups?.[0]) {
+            return {
+                ...accumulator,
+                page: { ...accumulator.page, [groups[0]]: value },
+            };
+        }
+        /* istanbul ignore next */
+        return accumulator;
+    }, {});
+}
+//# sourceMappingURL=toJsonApiQuery.js.map

package/src/lib/toJsonApiQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toJsonApiQuery.js","sourceRoot":"","sources":["../../../../../packages/json-api/src/lib/toJsonApiQuery.ts"],"names":[],"mappings":";;AAgBA,wCAgDC;AA9DD,MAAM,KAAK,GAAG;IACZ,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,uBAAuB;IAC/B,UAAU,EAAE,2BAA2B;IACvC,OAAO,EAAE,YAAY;IACrB,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,SAAS;CACP,CAAC;AAEX;;;;GAIG;AACH,SAAgB,cAAc,CAAC,YAA6B;IAC1D,OAAO,CAAC,GAAG,YAAY,CAAC,CAAC,MAAM,CAAe,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,KAAqC,CAAC;QAC5D,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,OAAO;gBACL,GAAG,WAAW;gBACd,MAAM,EAAE;oBACN,GAAG,WAAW,CAAC,MAAM;oBACrB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;iBAC9B;aACF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,YAAY,CAAC,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC;YACnE,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO;oBACL,GAAG,WAAW;oBACd,MAAM,EAAE;wBACN,GAAG,WAAW,CAAC,MAAM;wBACrB,CAAC,KAAK,CAAC,EAAE,SAAS;4BAChB,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE;4BACxD,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC;qBACrB;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1C,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,CAAC;QAED,IAAI,IAAI,KAAK,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnC,OAAO;gBACL,GAAG,WAAW;gBACd,IAAI,EAAE,EAAE,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE;aAClD,CAAC;QACJ,CAAC;QAED,0BAA0B;QAC1B,OAAO,WAAW,CAAC;IACrB,CAAC,EAAE,EAAE,CAAC,CAAC;AACT,CAAC"}

package/src/lib/toSearchParams.d.ts

@@ -0,0 +1,8 @@
+import { URLSearchParams } from "node:url";
+import { type JsonApiQuery } from "./types";
+/**
+ * Call this function from clients to convert from {@link JsonApiQuery} to {@link URLSearchParams}.
+ *
+ * @see [Example](https://github.com/ClipboardHealth/core-utils/blob/main/packages/json-api/examples/toSearchParams.ts)
+ */
+export declare function toSearchParams(query: JsonApiQuery): URLSearchParams;

package/src/lib/toSearchParams.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSearchParams = toSearchParams;
+const node_url_1 = require("node:url");
+/**
+ * Call this function from clients to convert from {@link JsonApiQuery} to {@link URLSearchParams}.
+ *
+ * @see [Example](https://github.com/ClipboardHealth/core-utils/blob/main/packages/json-api/examples/toSearchParams.ts)
+ */
+function toSearchParams(query) {
+    const searchParams = new node_url_1.URLSearchParams();
+    if (query.fields) {
+        Object.entries(query.fields).forEach(([type, fields]) => {
+            searchParams.append(`fields[${type}]`, fields.join(","));
+        });
+    }
+    if (query.filter) {
+        Object.entries(query.filter).forEach(([field, values]) => {
+            if (Array.isArray(values)) {
+                searchParams.append(`filter[${field}]`, values.join(","));
+            }
+            else if (typeof values === "object") {
+                Object.entries(values).forEach(([fieldType, value]) => {
+                    searchParams.append(`filter[${field}][${fieldType}]`, value);
+                });
+            }
+        });
+    }
+    if (query.include) {
+        searchParams.append("include", query.include.join(","));
+    }
+    if (query.page) {
+        Object.entries(query.page).forEach(([key, value]) => {
+            searchParams.append(`page[${key}]`, value);
+        });
+    }
+    if (query.sort) {
+        searchParams.append("sort", query.sort.join(","));
+    }
+    return searchParams;
+}
+//# sourceMappingURL=toSearchParams.js.map

package/src/lib/toSearchParams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toSearchParams.js","sourceRoot":"","sources":["../../../../../packages/json-api/src/lib/toSearchParams.ts"],"names":[],"mappings":";;AASA,wCAoCC;AA7CD,uCAA2C;AAI3C;;;;GAIG;AACH,SAAgB,cAAc,CAAC,KAAmB;IAChD,MAAM,YAAY,GAAG,IAAI,0BAAe,EAAE,CAAC;IAE3C,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE;YACtD,YAAY,CAAC,MAAM,CAAC,UAAU,IAAI,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE;YACvD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,YAAY,CAAC,MAAM,CAAC,UAAU,KAAK,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5D,CAAC;iBAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACtC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE;oBACpD,YAAY,CAAC,MAAM,CAAC,UAAU,KAAK,KAAK,SAAS,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC/D,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,YAAY,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACf,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YAClD,YAAY,CAAC,MAAM,CAAC,QAAQ,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACf,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/src/lib/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Filter operators to build complex filter queries.
+ * - gt: Greater than
+ * - gte: Greater than or equal to
+ * - lt: Less than
+ * - lte: Less than or equal to
+ * - not: Not equal to
+ */
+type FieldType = "gt" | "gte" | "lt" | "lte" | "not";
+/**
+ * A JSON:API URL query string.
+ */
+export interface JsonApiQuery {
+    /**
+     * Fields to include in the response.
+     *
+     * @see {@link https://jsonapi.org/format/#fetching-sparse-fieldsets Sparse fieldsets}
+     */
+    fields?: Record<string, string[]>;
+    /**
+     * Filters to apply to the query.
+     *
+     * @see {@link https://jsonapi.org/recommendations/#filtering Filtering}
+     * @see {@link https://discuss.jsonapi.org/t/share-propose-a-filtering-strategy/257 Filtering strategy}
+     */
+    filter?: Record<string, string[] | {
+        [K in FieldType]?: string;
+    }>;
+    /**
+     * Relationships to include in the response.
+     *
+     * @see {@link https://jsonapi.org/format/#fetching-includes Fetching includes}
+     */
+    include?: string[];
+    /**
+     * Pagination data.
+     *
+     * @see {@link https://jsonapi.org/format/#fetching-pagination Pagination}
+     * @see {@link https://jsonapi.org/examples/#pagination Pagination examples}
+     */
+    page?: {
+        [K in "cursor" | "limit" | "number" | "offset" | "size"]?: string;
+    };
+    /**
+     * Sorting data. Include the "-" prefix for descending order.
+     *
+     * @see {@link https://jsonapi.org/format/#fetching-sorting Sorting}
+     */
+    sort?: string[];
+}
+export {};

package/src/lib/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/json-api/src/lib/types.ts"],"names":[],"mappings":""}