@clipboard-health/json-api-nestjs - npm Package Compare versions

Comparing version 0.12.3 to 0.13.0

package.json

 {
   "name": "@clipboard-health/json-api-nestjs",
   "description": "TypeScript-friendly utilities for adhering to the JSON:API specification with NestJS.",
-  "version": "0.12.3",
+  "version": "0.13.0",
   "dependencies": {
@@ -12,3 +12,3 @@ "@clipboard-health/contract-core": "0.3.0",
   "devDependencies": {
-    "@clipboard-health/testing-core": "0.8.3"
+    "@clipboard-health/testing-core": "0.9.0"
   },
@@ -15,0 +15,0 @@ "keywords": [],

README.md

@@ -28,2 +28,3 @@ # @clipboard-health/json-api-nestjs <!-- omit from toc -->
 
+// packages/json-api-nestjs/src/lib/query/cursorPaginationQuery.ts,packages/json-api-nestjs/src/lib/query/fieldsQuery.ts,packages/json-api-nestjs/src/lib/query/filterQuery.ts,packages/json-api-nestjs/src/lib/query/includeQuery.ts,packages/json-api-nestjs/src/lib/query/sortQuery.ts
 import { booleanString } from "@clipboard-health/contract-core";
@@ -67,10 +68,2 @@ import {
 
-/**
- * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
- * implement them as they may require database indexes, which have a cost. **Implement only access
- * patterns required by clients.**
- *
- * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
- * Bad Request, hence the `.strict()`.
- */
 export const query = z
@@ -77,0 +70,0 @@ .object({

src/lib/query/cursorPaginationQuery.d.ts

@@ -11,5 +11,55 @@ import { z } from "zod";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-pagination JSON:API pagination}
@@ -16,0 +66,0 @@ * @see {@link https://jsonapi.org/examples/#pagination JSON:API pagination examples}

src/lib/query/cursorPaginationQuery.js

@@ -16,5 +16,55 @@ "use strict";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-pagination JSON:API pagination}
@@ -21,0 +71,0 @@ * @see {@link https://jsonapi.org/examples/#pagination JSON:API pagination examples}

src/lib/query/fieldsQuery.d.ts

@@ -16,5 +16,55 @@ import { z } from "zod";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-sparse-fieldsets JSON:API sparse fieldsets}
@@ -21,0 +71,0 @@ */

src/lib/query/fieldsQuery.js

@@ -9,5 +9,55 @@ "use strict";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-sparse-fieldsets JSON:API sparse fieldsets}
@@ -14,0 +64,0 @@ */

src/lib/query/filterQuery.d.ts

@@ -19,5 +19,55 @@ import { z } from "zod";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/recommendations/#filtering JSON:API filtering}
@@ -24,0 +74,0 @@ * @see {@link https://discuss.jsonapi.org/t/share-propose-a-filtering-strategy/257 JSON:API filtering strategy}

src/lib/query/filterQuery.js

@@ -10,5 +10,55 @@ "use strict";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/recommendations/#filtering JSON:API filtering}
@@ -15,0 +65,0 @@ * @see {@link https://discuss.jsonapi.org/t/share-propose-a-filtering-strategy/257 JSON:API filtering strategy}

src/lib/query/includeQuery.d.ts

@@ -26,5 +26,55 @@ import { type GreaterThan, type Subtract } from "type-fest";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-includes JSON:API includes}
@@ -31,0 +81,0 @@ */

src/lib/query/includeQuery.js

@@ -9,5 +9,55 @@ "use strict";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-includes JSON:API includes}
@@ -14,0 +64,0 @@ */

src/lib/query/sortQuery.d.ts

@@ -6,5 +6,55 @@ import { z } from "zod";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-sorting JSON:API sorting}
@@ -11,0 +61,0 @@ */

src/lib/query/sortQuery.js

@@ -9,5 +9,55 @@ "use strict";
  *
- * @includeExample ./packages/example-nestjs/examples/query.ts
+ * @example
+ * ```ts
+ * // packages/example-nestjs/examples/query.ts
+ * import { booleanString } from "@clipboard-health/contract-core";
+ * import {
+ *   cursorPaginationQuery,
+ *   fieldsQuery,
+ *   type FilterMap,
+ *   filterQuery,
+ *   includeQuery,
+ *   sortQuery,
+ * } from "@clipboard-health/json-api-nestjs";
+ * import { z } from "zod";
  *
- * @see [Usage example](../../../../example-nestjs/examples/query.ts)
+ * import {
+ *   type ArticleAttributeFields,
+ *   type UserAttributeFields,
+ *   type UserIncludeFields,
+ * } from "../src/contract";
+ *
+ * const articleFields = ["title"] as const satisfies readonly ArticleAttributeFields[];
+ * const userFields = ["age", "dateOfBirth"] as const satisfies readonly UserAttributeFields[];
+ * const userIncludeFields = [
+ *   "articles",
+ *   "articles.comments",
+ * ] as const satisfies readonly UserIncludeFields[];
+ * const userFilterMap = {
+ *   age: {
+ *     filters: ["eq", "gt"],
+ *     schema: z.coerce.number().int().positive().max(125),
+ *   },
+ *   dateOfBirth: {
+ *     filters: ["gte"],
+ *     schema: z.coerce.date().min(new Date("1900-01-01")).max(new Date()),
+ *   },
+ *   isActive: {
+ *     filters: ["eq"],
+ *     schema: booleanString,
+ *   },
+ * } as const satisfies FilterMap<UserAttributeFields>;
+ *
+ * export const query = z
+ *   .object({
+ *     ...cursorPaginationQuery(),
+ *     ...fieldsQuery({ article: articleFields, user: userFields }),
+ *     ...filterQuery(userFilterMap),
+ *     ...sortQuery(userFields),
+ *     ...includeQuery(userIncludeFields),
+ *   })
+ *   .strict();
+ *
+ * ```
+ *
  * @see {@link https://jsonapi.org/format/#fetching-sorting JSON:API sorting}
@@ -14,0 +64,0 @@ */

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

40917

increased by50.76%

Lines of code

911

increased by121.65%

Worsened metrics

Number of lines in readme file

82

decreased by-7.87%

No dependency changes