@clipboard-health/json-api-nestjs 0.2.0 → 0.3.0

package/README.md

@@ -24,6 +24,40 @@ Create Zod schemas for your API's queries:
 <!-- prettier-ignore -->
 ```ts
 // ./examples/query.ts
+
+import {
+  booleanString,
+  createCursorPagination,
+  createFields,
+  createFilter,
+  createInclude,
+  createSort,
+} from "@clipboard-health/json-api-nestjs";
+import { z } from "zod";
+
+export const query = z
+  .object({
+    ...createCursorPagination(),
+    ...createFields({ user: ["age", "name"], article: ["title"] }),
+    ...createFilter({
+      age: {
+        filters: ["eq", "gt"],
+        schema: z.coerce.number().int().positive().max(125),
+      },
+      isActive: {
+        filters: ["eq"],
+        schema: booleanString,
+      },
+      dateOfBirth: {
+        filters: ["gte"],
+        schema: z.coerce.date().min(new Date("1900-01-01")),
+      },
+    }),
+    ...createSort(["age", "name"]),
+    ...createInclude(["articles", "articles.comments"]),
+  })
+  .strict();
+
 ```
 
 ## Local development commands

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clipboard-health/json-api-nestjs",
   "description": "Utilities for adhering to the JSON:API specification with NestJS.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "dependencies": {
     "tslib": "2.7.0",
     "zod": "3.23.8"
@@ -12,6 +12,9 @@
   "publishConfig": {
     "access": "restricted"
   },
+  "scripts": {
+    "embed": "embedme README.md"
+  },
   "type": "commonjs",
   "typings": "./src/index.d.ts",
   "types": "./src/index.d.ts"

package/src/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./lib/query/createCursorPagination";
 export * from "./lib/query/createFields";
 export * from "./lib/query/createFilter";
+export * from "./lib/query/createInclude";
 export * from "./lib/query/createSort";
 export * from "./lib/schemas";
 export * from "./lib/types";

package/src/index.js

@@ -4,6 +4,7 @@ const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./lib/query/createCursorPagination"), exports);
 tslib_1.__exportStar(require("./lib/query/createFields"), exports);
 tslib_1.__exportStar(require("./lib/query/createFilter"), exports);
+tslib_1.__exportStar(require("./lib/query/createInclude"), exports);
 tslib_1.__exportStar(require("./lib/query/createSort"), exports);
 tslib_1.__exportStar(require("./lib/schemas"), exports);
 tslib_1.__exportStar(require("./lib/types"), exports);

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/json-api-nestjs/src/index.ts"],"names":[],"mappings":";;;AAAA,6EAAmD;AACnD,mEAAyC;AACzC,mEAAyC;AACzC,iEAAuC;AACvC,wDAA8B;AAC9B,sDAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/json-api-nestjs/src/index.ts"],"names":[],"mappings":";;;AAAA,6EAAmD;AACnD,mEAAyC;AACzC,mEAAyC;AACzC,oEAA0C;AAC1C,iEAAuC;AACvC,wDAA8B;AAC9B,sDAA4B"}

package/src/lib/query/createInclude.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/**
+ * Creates a Zod schema for JSON:API include parameters.
+ *
+ * @param fields An array of valid include fields.
+ * @returns A Zod schema for the include parameter.
+ *
+ * @see {@link https://jsonapi.org/format/#fetching-includes JSON:API includes}
+ */
+export declare function createInclude<const FieldT extends readonly string[]>(fields: FieldT): {
+    include: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodString, "many">>, string[] | undefined, unknown>, string[] | undefined, unknown>, FieldT[number][] | undefined, unknown>;
+};

package/src/lib/query/createInclude.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInclude = createInclude;
+const zod_1 = require("zod");
+const splitString_1 = require("../internal/splitString");
+/**
+ * Creates a Zod schema for JSON:API include parameters.
+ *
+ * @param fields An array of valid include fields.
+ * @returns A Zod schema for the include parameter.
+ *
+ * @see {@link https://jsonapi.org/format/#fetching-includes JSON:API includes}
+ */
+function createInclude(fields) {
+    const fieldSet = new Set(fields);
+    return {
+        include: zod_1.z
+            .preprocess(splitString_1.splitString, zod_1.z.array(zod_1.z.string()).optional())
+            .superRefine((value, context) => {
+            if (!value) {
+                return;
+            }
+            for (const field of value) {
+                if (!fieldSet.has(field)) {
+                    context.addIssue({
+                        code: zod_1.z.ZodIssueCode.custom,
+                        message: `Invalid include field: '${field}'`,
+                        path: ["include", field],
+                    });
+                }
+            }
+        })
+            .transform((value) => value),
+    };
+}
+//# sourceMappingURL=createInclude.js.map

package/src/lib/query/createInclude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createInclude.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/createInclude.ts"],"names":[],"mappings":";;AAYA,sCAuBC;AAnCD,6BAAwB;AAExB,yDAAsD;AAEtD;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAyC,MAAc;IAClF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO;QACL,OAAO,EAAE,OAAC;aACP,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;aACvD,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YAED,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO,CAAC,QAAQ,CAAC;wBACf,IAAI,EAAE,OAAC,CAAC,YAAY,CAAC,MAAM;wBAC3B,OAAO,EAAE,2BAA2B,KAAK,GAAG;wBAC5C,IAAI,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC;qBACzB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC,CAAC;aACD,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAA0C,CAAC;KACpE,CAAC;AACJ,CAAC"}

package/src/lib/query/createSort.d.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { type Field } from "../types";
-export type SortSchema<T extends readonly Field[]> = z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString>>>, Array<`-${T[number]}` | T[number]> | undefined, unknown>>;
 /**
  * Creates a Zod schema for JSON:API sort parameters.
  *

package/src/lib/query/createSort.js

@@ -25,6 +25,7 @@ function createSort(fields) {
                     context.addIssue({
                         code: zod_1.z.ZodIssueCode.custom,
                         message: `Invalid sort field: '${field}'`,
+                        path: ["sort", field],
                     });
                 }
             }

package/src/lib/query/createSort.js.map

@@ -1 +1 @@
-{"version":3,"file":"createSort.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/createSort.ts"],"names":[],"mappings":";;AAqBA,gCAqBC;AA1CD,6BAAwB;AAExB,yDAAsD;AAWtD;;;;;;;GAOG;AACH,SAAgB,UAAU,CAAoD,MAAc;IAC1F,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO;QACL,IAAI,EAAE,OAAC;aACJ,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;aACvD,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YAED,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;oBAClE,OAAO,CAAC,QAAQ,CAAC;wBACf,IAAI,EAAE,OAAC,CAAC,YAAY,CAAC,MAAM;wBAC3B,OAAO,EAAE,wBAAwB,KAAK,GAAG;qBAC1C,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC,CAAC;aACD,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAiE,CAAC;KAC3F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createSort.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/createSort.ts"],"names":[],"mappings":";;AAaA,gCAsBC;AAnCD,6BAAwB;AAExB,yDAAsD;AAGtD;;;;;;;GAOG;AACH,SAAgB,UAAU,CAAoD,MAAc;IAC1F,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO;QACL,IAAI,EAAE,OAAC;aACJ,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;aACvD,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YAED,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;gBAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;oBAClE,OAAO,CAAC,QAAQ,CAAC;wBACf,IAAI,EAAE,OAAC,CAAC,YAAY,CAAC,MAAM;wBAC3B,OAAO,EAAE,wBAAwB,KAAK,GAAG;wBACzC,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC;qBACtB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC,CAAC;aACD,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAiE,CAAC;KAC3F,CAAC;AACJ,CAAC"}