@clipboard-health/json-api 0.0.0

package/README.md

@@ -0,0 +1,83 @@
+# @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 `ClientJsonApiQuery` to `URLSearchParams`:
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/toSearchParams.ts
+
+import { deepEqual } from "node:assert/strict";
+
+import { toSearchParams } from "@clipboard-health/json-api";
+
+import { type ClientJsonApiQuery } from "../src/lib/types";
+
+const isoDate = "2024-01-01T15:00:00.000Z";
+const query: ClientJsonApiQuery = {
+  fields: { dog: ["age"] },
+  filter: { age: [2], createdAt: { gte: new Date(isoDate) }, isGoodDog: true },
+  include: ["owner"],
+  page: { size: 10 },
+  sort: ["-age"],
+};
+
+deepEqual(
+  toSearchParams(query).toString(),
+  new URLSearchParams(
+    "fields[dog]=age&filter[age]=2&filter[createdAt][gte]=2024-01-01T15:00:00.000Z&filter[isGoodDog]=true&include=owner&page[size]=10&sort=-age",
+  ).toString(),
+);
+
+```
+
+From the server, call `toJsonApiQuery` to convert from `URLSearchParams` to `ServerJsonApiQuery`:
+
+<!-- prettier-ignore -->
+```ts
+// ./examples/toJsonApiQuery.ts
+
+import { deepEqual } from "node:assert/strict";
+
+import { type ServerJsonApiQuery, toJsonApiQuery } from "@clipboard-health/json-api";
+
+const isoDate = "2024-01-01T15:00:00.000Z";
+// The URLSearchParams constructor also supports URL-encoded strings
+const searchParams = new URLSearchParams(
+  `fields[dog]=age&filter[age]=2&filter[createdAt][gte]=${isoDate}&filter[isGoodDog]=true&include=owner&page[size]=10&sort=-age`,
+);
+
+const query: ServerJsonApiQuery = toJsonApiQuery(searchParams);
+
+deepEqual(query, {
+  fields: { dog: ["age"] },
+  filter: { age: ["2"], createdAt: { gte: isoDate }, isGoodDog: ["true"] },
+  include: ["owner"],
+  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.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",
+  "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 ServerJsonApiQuery } from "./types";
+/**
+ * Call this function from servers to convert from {@link URLSearchParams} to {@link ServerJsonApiQuery}.
+ *
+ * @see [Example](https://github.com/ClipboardHealth/core-utils/blob/main/packages/json-api/examples/toJsonApiQuery.ts)
+ */
+export declare function toJsonApiQuery(searchParams: URLSearchParams): ServerJsonApiQuery;

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 servers to convert from {@link URLSearchParams} to {@link ServerJsonApiQuery}.
+ *
+ * @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,CAAqB,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAChF,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,7 @@
+import { type ClientJsonApiQuery } from "./types";
+/**
+ * Call this function from clients to convert from {@link ClientJsonApiQuery} to {@link URLSearchParams}.
+ *
+ * @see [Example](https://github.com/ClipboardHealth/core-utils/blob/main/packages/json-api/examples/toSearchParams.ts)
+ */
+export declare function toSearchParams(query: ClientJsonApiQuery): URLSearchParams;

package/src/lib/toSearchParams.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSearchParams = toSearchParams;
+function filterValueString(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+function join(values) {
+    return values.join(",");
+}
+/**
+ * Call this function from clients to convert from {@link ClientJsonApiQuery} 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 URLSearchParams();
+    if (query.fields) {
+        Object.entries(query.fields).forEach(([type, fields]) => {
+            searchParams.append(`fields[${type}]`, join(fields));
+        });
+    }
+    if (query.filter) {
+        Object.entries(query.filter).forEach(([field, values]) => {
+            const filterField = `filter[${field}]`;
+            if (Array.isArray(values)) {
+                searchParams.append(filterField, join(values.map((value) => filterValueString(value))));
+            }
+            else if (typeof values === "boolean") {
+                searchParams.append(filterField, String(values));
+            }
+            else if (typeof values === "object") {
+                Object.entries(values).forEach(([fieldType, value]) => {
+                    searchParams.append(`${filterField}[${fieldType}]`, filterValueString(value));
+                });
+            }
+        });
+    }
+    if (query.include) {
+        searchParams.append("include", join(query.include));
+    }
+    if (query.page) {
+        Object.entries(query.page).forEach(([key, value]) => {
+            searchParams.append(`page[${key}]`, String(value));
+        });
+    }
+    if (query.sort) {
+        searchParams.append("sort", join(query.sort));
+    }
+    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":";;AAeA,wCAuCC;AApDD,SAAS,iBAAiB,CAAC,KAAqC;IAC9D,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,IAAI,CAAC,MAAgB;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,KAAyB;IACtD,MAAM,YAAY,GAAG,IAAI,eAAe,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,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QACvD,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,MAAM,WAAW,GAAG,UAAU,KAAK,GAAG,CAAC;YACvC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC1B,YAAY,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1F,CAAC;iBAAM,IAAI,OAAO,MAAM,KAAK,SAAS,EAAE,CAAC;gBACvC,YAAY,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YACnD,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,GAAG,WAAW,IAAI,SAAS,GAAG,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;gBAChF,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,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,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,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QACf,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/src/lib/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Filter types 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 FilterType = "gt" | "gte" | "lt" | "lte" | "not";
+type PageKey = "cursor" | "limit" | "number" | "offset" | "size";
+interface JsonApiQueryTypes {
+    filterValue: unknown;
+    filterTypeValue: unknown;
+    pageValue: unknown;
+}
+export interface ClientTypes {
+    filterValue: Array<Date | number | string> | boolean;
+    filterTypeValue: Date | number | string;
+    pageValue: number | string;
+}
+interface ServerTypes {
+    filterValue: string[];
+    filterTypeValue: string;
+    pageValue: string;
+}
+/**
+ * A JSON:API URL query string.
+ */
+interface JsonApiQuery<T extends JsonApiQueryTypes> {
+    /**
+     * 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, T["filterValue"] | {
+        [K in FilterType]?: T["filterTypeValue"];
+    }>;
+    /**
+     * 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 PageKey]?: T["pageValue"];
+    };
+    /**
+     * Sorting data. Include the "-" prefix for descending order.
+     *
+     * @see {@link https://jsonapi.org/format/#fetching-sorting Sorting}
+     */
+    sort?: string[];
+}
+export type ClientJsonApiQuery = JsonApiQuery<ClientTypes>;
+export type ServerJsonApiQuery = JsonApiQuery<ServerTypes>;
+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":""}