@clipboard-health/json-api 0.2.3 → 0.2.5

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

@@ -0,0 +1,29 @@
+{
+  "name": "@clipboard-health/json-api",
+  "description": "Utilities for adhering to the JSON:API specification.",
+  "version": "0.2.5",
+  "bugs": "https://github.com/clipboardhealth/core-utils/issues",
+  "dependencies": {
+    "tslib": "2.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [],
+  "license": "MIT",
+  "main": "./dist/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/dist/src/index.js.map

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

package/dist/src/lib/toJsonApiQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toJsonApiQuery.js","sourceRoot":"","sources":["../../../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/dist/src/lib/toSearchParams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toSearchParams.js","sourceRoot":"","sources":["../../../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/dist/src/lib/types.js.map

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

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@clipboard-health/json-api",
-  "description": "",
-  "version": "0.2.3",
+  "description": "Utilities for adhering to the JSON:API specification.",
+  "version": "0.2.5",
   "bugs": "https://github.com/clipboardhealth/core-utils/issues",
   "dependencies": {
-    "tslib": "2.6.3"
+    "tslib": "2.7.0"
   },
+  "files": [
+    "dist"
+  ],
   "keywords": [],
   "license": "MIT",
-  "main": "./src/index.js",
+  "main": "./dist/src/index.js",
   "publishConfig": {
     "access": "public"
   },
@@ -21,6 +24,5 @@
     "embed": "embedme README.md"
   },
   "type": "commonjs",
-  "typings": "./src/index.d.ts",
-  "types": "./src/index.d.ts"
+  "typings": "./src/index.d.ts"
 }

package/src/index.js.map

@@ -1 +0,0 @@
-{"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.js.map

@@ -1 +0,0 @@
-{"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.js.map

@@ -1 +0,0 @@
-{"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.js.map

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