@clipboard-health/json-api-nestjs 0.13.1 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/README.md +12 -5
  2. package/package.json +2 -5
  3. package/src/lib/query/cursorPaginationQuery.d.ts +12 -2
  4. package/src/lib/query/cursorPaginationQuery.js +12 -2
  5. package/src/lib/query/cursorPaginationQuery.js.map +1 -1
  6. package/src/lib/query/fieldsQuery.d.ts +12 -2
  7. package/src/lib/query/fieldsQuery.js +12 -2
  8. package/src/lib/query/fieldsQuery.js.map +1 -1
  9. package/src/lib/query/filterQuery.d.ts +12 -2
  10. package/src/lib/query/filterQuery.js +12 -2
  11. package/src/lib/query/filterQuery.js.map +1 -1
  12. package/src/lib/query/includeQuery.d.ts +12 -2
  13. package/src/lib/query/includeQuery.js +12 -2
  14. package/src/lib/query/includeQuery.js.map +1 -1
  15. package/src/lib/query/sortQuery.d.ts +12 -3
  16. package/src/lib/query/sortQuery.js +12 -3
  17. package/src/lib/query/sortQuery.js.map +1 -1
package/README.md CHANGED
@@ -21,11 +21,9 @@ npm install @clipboard-health/json-api-nestjs
21
21
 
22
22
  Create Zod schemas for your API's queries:
23
23
 
24
- <!-- prettier-ignore -->
25
- ```ts
26
- // ../example-nestjs/examples/query.ts
24
+ <embedex source="packages/example-nestjs/examples/query.ts">
27
25
 
28
- // 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
26
+ ```ts
29
27
  import { booleanString } from "@clipboard-health/contract-core";
30
28
  import {
31
29
  cursorPaginationQuery,
@@ -64,6 +62,14 @@ const userFilterMap = {
64
62
  },
65
63
  } as const satisfies FilterMap<UserAttributeFields>;
66
64
 
65
+ /**
66
+ * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
67
+ * implement them as they may require database indexes, which have a cost. **Implement only access
68
+ * patterns required by clients.**
69
+ *
70
+ * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
71
+ * Bad Request, hence the `.strict()`.
72
+ *\/
67
73
  export const query = z
68
74
  .object({
69
75
  ...cursorPaginationQuery(),
@@ -73,9 +79,10 @@ export const query = z
73
79
  ...includeQuery(userIncludeFields),
74
80
  })
75
81
  .strict();
76
-
77
82
  ```
78
83
 
84
+ </embedex>
85
+
79
86
  ## Local development commands
80
87
 
81
88
  See [`package.json`](./package.json) `scripts` for a list of commands.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@clipboard-health/json-api-nestjs",
3
3
  "description": "TypeScript-friendly utilities for adhering to the JSON:API specification with NestJS.",
4
- "version": "0.13.1",
4
+ "version": "0.15.0",
5
5
  "bugs": "https://github.com/ClipboardHealth/core-utils/issues",
6
6
  "dependencies": {
7
7
  "@clipboard-health/contract-core": "0.3.0",
@@ -10,7 +10,7 @@
10
10
  "zod": "3.23.8"
11
11
  },
12
12
  "devDependencies": {
13
- "@clipboard-health/testing-core": "0.9.1"
13
+ "@clipboard-health/testing-core": "0.11.0"
14
14
  },
15
15
  "keywords": [
16
16
  "api",
@@ -31,9 +31,6 @@
31
31
  "type": "git",
32
32
  "url": "git+https://github.com/ClipboardHealth/core-utils.git"
33
33
  },
34
- "scripts": {
35
- "embed": "embedme README.md"
36
- },
37
34
  "type": "commonjs",
38
35
  "typings": "./src/index.d.ts",
39
36
  "types": "./src/index.d.ts"
package/src/lib/query/cursorPaginationQuery.d.ts CHANGED
@@ -9,8 +9,9 @@ export declare const PAGINATION: {
9
9
  * Creates a Zod schema for JSON:API cursor pagination.
10
10
  *
11
11
  * @example
12
+ * <embedex source="packages/example-nestjs/examples/query.ts">
13
+ *
12
14
  * ```ts
13
- * // packages/example-nestjs/examples/query.ts
14
15
  * import { booleanString } from "@clipboard-health/contract-core";
15
16
  * import {
16
17
  * cursorPaginationQuery,
@@ -49,6 +50,14 @@ export declare const PAGINATION: {
49
50
  * },
50
51
  * } as const satisfies FilterMap<UserAttributeFields>;
51
52
  *
53
+ * /**
54
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
55
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
56
+ * * patterns required by clients.**
57
+ * *
58
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
59
+ * * Bad Request, hence the `.strict()`.
60
+ * *\/
52
61
  * export const query = z
53
62
  * .object({
54
63
  * ...cursorPaginationQuery(),
@@ -58,9 +67,10 @@ export declare const PAGINATION: {
58
67
  * ...includeQuery(userIncludeFields),
59
68
  * })
60
69
  * .strict();
61
- *
62
70
  * ```
63
71
  *
72
+ * </embedex>
73
+ *
64
74
  * @see {@link https://jsonapi.org/format/#fetching-pagination JSON:API pagination}
65
75
  * @see {@link https://jsonapi.org/examples/#pagination JSON:API pagination examples}
66
76
  */
package/src/lib/query/cursorPaginationQuery.js CHANGED
@@ -14,8 +14,9 @@ exports.PAGINATION = {
14
14
  * Creates a Zod schema for JSON:API cursor pagination.
15
15
  *
16
16
  * @example
17
+ * <embedex source="packages/example-nestjs/examples/query.ts">
18
+ *
17
19
  * ```ts
18
- * // packages/example-nestjs/examples/query.ts
19
20
  * import { booleanString } from "@clipboard-health/contract-core";
20
21
  * import {
21
22
  * cursorPaginationQuery,
@@ -54,6 +55,14 @@ exports.PAGINATION = {
54
55
  * },
55
56
  * } as const satisfies FilterMap<UserAttributeFields>;
56
57
  *
58
+ * /**
59
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
60
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
61
+ * * patterns required by clients.**
62
+ * *
63
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
64
+ * * Bad Request, hence the `.strict()`.
65
+ * *\/
57
66
  * export const query = z
58
67
  * .object({
59
68
  * ...cursorPaginationQuery(),
@@ -63,9 +72,10 @@ exports.PAGINATION = {
63
72
  * ...includeQuery(userIncludeFields),
64
73
  * })
65
74
  * .strict();
66
- *
67
75
  * ```
68
76
  *
77
+ * </embedex>
78
+ *
69
79
  * @see {@link https://jsonapi.org/format/#fetching-pagination JSON:API pagination}
70
80
  * @see {@link https://jsonapi.org/examples/#pagination JSON:API pagination examples}
71
81
  */
package/src/lib/query/cursorPaginationQuery.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cursorPaginationQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/cursorPaginationQuery.ts"],"names":[],"mappings":";;;AAqEA,sDAeC;AApFD,mEAAiE;AACjE,6BAAwB;AAEX,QAAA,UAAU,GAAG;IACxB,IAAI,EAAE;QACJ,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,GAAG;KACb;CACO,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,SAAgB,qBAAqB,CACnC,UAAuE;IAEvE,MAAM,EAAE,IAAI,EAAE,GAAG,kBAAU,CAAC;IAC5B,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC;IAE/F,OAAO;QACL,IAAI,EAAE,OAAC;aACJ,MAAM,CAAC;YACN,MAAM,EAAE,8BAAc,CAAC,QAAQ,EAAE;YACjC,IAAI,EAAE,OAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;SAC3E,CAAC;aACD,MAAM,EAAE;aACR,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;KAClC,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"cursorPaginationQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/cursorPaginationQuery.ts"],"names":[],"mappings":";;;AA+EA,sDAeC;AA9FD,mEAAiE;AACjE,6BAAwB;AAEX,QAAA,UAAU,GAAG;IACxB,IAAI,EAAE;QACJ,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,GAAG;KACb;CACO,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,SAAgB,qBAAqB,CACnC,UAAuE;IAEvE,MAAM,EAAE,IAAI,EAAE,GAAG,kBAAU,CAAC;IAC5B,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC;IAE/F,OAAO;QACL,IAAI,EAAE,OAAC;aACJ,MAAM,CAAC;YACN,MAAM,EAAE,8BAAc,CAAC,QAAQ,EAAE;YACjC,IAAI,EAAE,OAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;SAC3E,CAAC;aACD,MAAM,EAAE;aACR,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;KAClC,CAAC;AACJ,CAAC"}
package/src/lib/query/fieldsQuery.d.ts CHANGED
@@ -14,8 +14,9 @@ export type AttributeFields<DocumentT extends JsonApiDocument> = DocumentT["data
14
14
  * Creates a Zod schema for JSON:API sparse fieldsets.
15
15
  *
16
16
  * @example
17
+ * <embedex source="packages/example-nestjs/examples/query.ts">
18
+ *
17
19
  * ```ts
18
- * // packages/example-nestjs/examples/query.ts
19
20
  * import { booleanString } from "@clipboard-health/contract-core";
20
21
  * import {
21
22
  * cursorPaginationQuery,
@@ -54,6 +55,14 @@ export type AttributeFields<DocumentT extends JsonApiDocument> = DocumentT["data
54
55
  * },
55
56
  * } as const satisfies FilterMap<UserAttributeFields>;
56
57
  *
58
+ * /**
59
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
60
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
61
+ * * patterns required by clients.**
62
+ * *
63
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
64
+ * * Bad Request, hence the `.strict()`.
65
+ * *\/
57
66
  * export const query = z
58
67
  * .object({
59
68
  * ...cursorPaginationQuery(),
@@ -63,9 +72,10 @@ export type AttributeFields<DocumentT extends JsonApiDocument> = DocumentT["data
63
72
  * ...includeQuery(userIncludeFields),
64
73
  * })
65
74
  * .strict();
66
- *
67
75
  * ```
68
76
  *
77
+ * </embedex>
78
+ *
69
79
  * @see {@link https://jsonapi.org/format/#fetching-sparse-fieldsets JSON:API sparse fieldsets}
70
80
  */
71
81
  export declare function fieldsQuery<const MapT extends FieldsMap>(parameters: Readonly<MapT>): {
package/src/lib/query/fieldsQuery.js CHANGED
@@ -7,8 +7,9 @@ const splitString_1 = require("../internal/splitString");
7
7
  * Creates a Zod schema for JSON:API sparse fieldsets.
8
8
  *
9
9
  * @example
10
+ * <embedex source="packages/example-nestjs/examples/query.ts">
11
+ *
10
12
  * ```ts
11
- * // packages/example-nestjs/examples/query.ts
12
13
  * import { booleanString } from "@clipboard-health/contract-core";
13
14
  * import {
14
15
  * cursorPaginationQuery,
@@ -47,6 +48,14 @@ const splitString_1 = require("../internal/splitString");
47
48
  * },
48
49
  * } as const satisfies FilterMap<UserAttributeFields>;
49
50
  *
51
+ * /**
52
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
53
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
54
+ * * patterns required by clients.**
55
+ * *
56
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
57
+ * * Bad Request, hence the `.strict()`.
58
+ * *\/
50
59
  * export const query = z
51
60
  * .object({
52
61
  * ...cursorPaginationQuery(),
@@ -56,9 +65,10 @@ const splitString_1 = require("../internal/splitString");
56
65
  * ...includeQuery(userIncludeFields),
57
66
  * })
58
67
  * .strict();
59
- *
60
68
  * ```
61
69
  *
70
+ * </embedex>
71
+ *
62
72
  * @see {@link https://jsonapi.org/format/#fetching-sparse-fieldsets JSON:API sparse fieldsets}
63
73
  */
64
74
  function fieldsQuery(parameters) {
package/src/lib/query/fieldsQuery.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"fieldsQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/fieldsQuery.ts"],"names":[],"mappings":";;AAqFA,kCAYC;AAjGD,6BAAwB;AAExB,yDAAsD;AAyBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,SAAgB,WAAW,CAA+B,UAA0B;IAClF,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CACrC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAiC,EAAE,EAAE,CAAC;QACpF,OAAO;QACP,OAAC,CAAC,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;KAC7E,CAAC,CAEmB,CAAC;IAExB,OAAO;QACL,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACnD,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"fieldsQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/fieldsQuery.ts"],"names":[],"mappings":";;AA+FA,kCAYC;AA3GD,6BAAwB;AAExB,yDAAsD;AAyBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,SAAgB,WAAW,CAA+B,UAA0B;IAClF,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CACrC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAiC,EAAE,EAAE,CAAC;QACpF,OAAO;QACP,OAAC,CAAC,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;KAC7E,CAAC,CAEmB,CAAC;IAExB,OAAO;QACL,MAAM,EAAE,OAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACnD,CAAC;AACJ,CAAC"}
package/src/lib/query/filterQuery.d.ts CHANGED
@@ -17,8 +17,9 @@ export type FilterSchema<MapT extends InternalFilterMap> = {
17
17
  * Creates a Zod schema for JSON:API filters.
18
18
  *
19
19
  * @example
20
+ * <embedex source="packages/example-nestjs/examples/query.ts">
21
+ *
20
22
  * ```ts
21
- * // packages/example-nestjs/examples/query.ts
22
23
  * import { booleanString } from "@clipboard-health/contract-core";
23
24
  * import {
24
25
  * cursorPaginationQuery,
@@ -57,6 +58,14 @@ export type FilterSchema<MapT extends InternalFilterMap> = {
57
58
  * },
58
59
  * } as const satisfies FilterMap<UserAttributeFields>;
59
60
  *
61
+ * /**
62
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
63
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
64
+ * * patterns required by clients.**
65
+ * *
66
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
67
+ * * Bad Request, hence the `.strict()`.
68
+ * *\/
60
69
  * export const query = z
61
70
  * .object({
62
71
  * ...cursorPaginationQuery(),
@@ -66,9 +75,10 @@ export type FilterSchema<MapT extends InternalFilterMap> = {
66
75
  * ...includeQuery(userIncludeFields),
67
76
  * })
68
77
  * .strict();
69
- *
70
78
  * ```
71
79
  *
80
+ * </embedex>
81
+ *
72
82
  * @see {@link https://jsonapi.org/recommendations/#filtering JSON:API filtering}
73
83
  * @see {@link https://discuss.jsonapi.org/t/share-propose-a-filtering-strategy/257 JSON:API filtering strategy}
74
84
  */
package/src/lib/query/filterQuery.js CHANGED
@@ -8,8 +8,9 @@ const splitString_1 = require("../internal/splitString");
8
8
  * Creates a Zod schema for JSON:API filters.
9
9
  *
10
10
  * @example
11
+ * <embedex source="packages/example-nestjs/examples/query.ts">
12
+ *
11
13
  * ```ts
12
- * // packages/example-nestjs/examples/query.ts
13
14
  * import { booleanString } from "@clipboard-health/contract-core";
14
15
  * import {
15
16
  * cursorPaginationQuery,
@@ -48,6 +49,14 @@ const splitString_1 = require("../internal/splitString");
48
49
  * },
49
50
  * } as const satisfies FilterMap<UserAttributeFields>;
50
51
  *
52
+ * /**
53
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
54
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
55
+ * * patterns required by clients.**
56
+ * *
57
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
58
+ * * Bad Request, hence the `.strict()`.
59
+ * *\/
51
60
  * export const query = z
52
61
  * .object({
53
62
  * ...cursorPaginationQuery(),
@@ -57,9 +66,10 @@ const splitString_1 = require("../internal/splitString");
57
66
  * ...includeQuery(userIncludeFields),
58
67
  * })
59
68
  * .strict();
60
- *
61
69
  * ```
62
70
  *
71
+ * </embedex>
72
+ *
63
73
  * @see {@link https://jsonapi.org/recommendations/#filtering JSON:API filtering}
64
74
  * @see {@link https://discuss.jsonapi.org/t/share-propose-a-filtering-strategy/257 JSON:API filtering strategy}
65
75
  */
package/src/lib/query/filterQuery.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"filterQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/filterQuery.ts"],"names":[],"mappings":";;AA4FA,kCAcC;AA1GD,6BAAwB;AAExB,iFAA8E;AAC9E,yDAAsD;AA8BtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,SAAgB,WAAW,CAAuC,UAA0B;IAC1F,OAAO;QACL,MAAM,EAAE,OAAC;aACN,MAAM,CACL,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAiC,EAAE,EAAE,CAAC;YACnF,OAAO;YACP,OAAC,CAAC,UAAU,CAAC,iDAAuB,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;SACtE,CAAC,CACmB,CACxB;aACA,MAAM,EAAE;aACR,QAAQ,EAAE;KACd,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,UAAuB;IAC3C,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAEvC,OAAO,OAAC;SACL,MAAM,CACL,MAAM,CAAC,WAAW,CAChB,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACtB,MAAM;QACN,OAAC,CAAC,UAAU,CAAC,yBAAW,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE;KACnF,CAAC,CACH,CACF;SACA,MAAM,EAAE;SACR,QAAQ,EAAE,CAAC;AAChB,CAAC"}
1
+ {"version":3,"file":"filterQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/filterQuery.ts"],"names":[],"mappings":";;AAsGA,kCAcC;AApHD,6BAAwB;AAExB,iFAA8E;AAC9E,yDAAsD;AA8BtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,SAAgB,WAAW,CAAuC,UAA0B;IAC1F,OAAO;QACL,MAAM,EAAE,OAAC;aACN,MAAM,CACL,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAiC,EAAE,EAAE,CAAC;YACnF,OAAO;YACP,OAAC,CAAC,UAAU,CAAC,iDAAuB,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;SACtE,CAAC,CACmB,CACxB;aACA,MAAM,EAAE;aACR,QAAQ,EAAE;KACd,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,UAAuB;IAC3C,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC;IAEvC,OAAO,OAAC;SACL,MAAM,CACL,MAAM,CAAC,WAAW,CAChB,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACtB,MAAM;QACN,OAAC,CAAC,UAAU,CAAC,yBAAW,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE;KACnF,CAAC,CACH,CACF;SACA,MAAM,EAAE;SACR,QAAQ,EAAE,CAAC;AAChB,CAAC"}
package/src/lib/query/includeQuery.d.ts CHANGED
@@ -24,8 +24,9 @@ export type RelationshipPaths<MapT extends Record<string, z.ZodTypeAny>, Documen
24
24
  * Creates a Zod schema for JSON:API include parameters.
25
25
  *
26
26
  * @example
27
+ * <embedex source="packages/example-nestjs/examples/query.ts">
28
+ *
27
29
  * ```ts
28
- * // packages/example-nestjs/examples/query.ts
29
30
  * import { booleanString } from "@clipboard-health/contract-core";
30
31
  * import {
31
32
  * cursorPaginationQuery,
@@ -64,6 +65,14 @@ export type RelationshipPaths<MapT extends Record<string, z.ZodTypeAny>, Documen
64
65
  * },
65
66
  * } as const satisfies FilterMap<UserAttributeFields>;
66
67
  *
68
+ * /**
69
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
70
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
71
+ * * patterns required by clients.**
72
+ * *
73
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
74
+ * * Bad Request, hence the `.strict()`.
75
+ * *\/
67
76
  * export const query = z
68
77
  * .object({
69
78
  * ...cursorPaginationQuery(),
@@ -73,9 +82,10 @@ export type RelationshipPaths<MapT extends Record<string, z.ZodTypeAny>, Documen
73
82
  * ...includeQuery(userIncludeFields),
74
83
  * })
75
84
  * .strict();
76
- *
77
85
  * ```
78
86
  *
87
+ * </embedex>
88
+ *
79
89
  * @see {@link https://jsonapi.org/format/#fetching-includes JSON:API includes}
80
90
  */
81
91
  export declare function includeQuery<const FieldT extends readonly string[]>(fields: FieldT): {
package/src/lib/query/includeQuery.js CHANGED
@@ -7,8 +7,9 @@ const splitString_1 = require("../internal/splitString");
7
7
  * Creates a Zod schema for JSON:API include parameters.
8
8
  *
9
9
  * @example
10
+ * <embedex source="packages/example-nestjs/examples/query.ts">
11
+ *
10
12
  * ```ts
11
- * // packages/example-nestjs/examples/query.ts
12
13
  * import { booleanString } from "@clipboard-health/contract-core";
13
14
  * import {
14
15
  * cursorPaginationQuery,
@@ -47,6 +48,14 @@ const splitString_1 = require("../internal/splitString");
47
48
  * },
48
49
  * } as const satisfies FilterMap<UserAttributeFields>;
49
50
  *
51
+ * /**
52
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
53
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
54
+ * * patterns required by clients.**
55
+ * *
56
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
57
+ * * Bad Request, hence the `.strict()`.
58
+ * *\/
50
59
  * export const query = z
51
60
  * .object({
52
61
  * ...cursorPaginationQuery(),
@@ -56,9 +65,10 @@ const splitString_1 = require("../internal/splitString");
56
65
  * ...includeQuery(userIncludeFields),
57
66
  * })
58
67
  * .strict();
59
- *
60
68
  * ```
61
69
  *
70
+ * </embedex>
71
+ *
62
72
  * @see {@link https://jsonapi.org/format/#fetching-includes JSON:API includes}
63
73
  */
64
74
  function includeQuery(fields) {
package/src/lib/query/includeQuery.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"includeQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/includeQuery.ts"],"names":[],"mappings":";;AA2GA,oCAuBC;AAjID,6BAAwB;AAExB,yDAAsD;AA8CtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,SAAgB,YAAY,CAAyC,MAAc;IACjF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO;QACL,OAAO,EAAE,OAAC;aACP,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;aACtE,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"}
1
+ {"version":3,"file":"includeQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/includeQuery.ts"],"names":[],"mappings":";;AAqHA,oCAuBC;AA3ID,6BAAwB;AAExB,yDAAsD;AA8CtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,SAAgB,YAAY,CAAyC,MAAc;IACjF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAEjC,OAAO;QACL,OAAO,EAAE,OAAC;aACP,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;aACtE,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/sortQuery.d.ts CHANGED
@@ -3,9 +3,9 @@ import { type Field } from "../types";
3
3
  /**
4
4
  * Creates a Zod schema for JSON:API sort parameters.
5
5
  *
6
- * @example
6
+ * <embedex source="packages/example-nestjs/examples/query.ts">
7
+ *
7
8
  * ```ts
8
- * // packages/example-nestjs/examples/query.ts
9
9
  * import { booleanString } from "@clipboard-health/contract-core";
10
10
  * import {
11
11
  * cursorPaginationQuery,
@@ -44,6 +44,14 @@ import { type Field } from "../types";
44
44
  * },
45
45
  * } as const satisfies FilterMap<UserAttributeFields>;
46
46
  *
47
+ * /**
48
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
49
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
50
+ * * patterns required by clients.**
51
+ * *
52
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
53
+ * * Bad Request, hence the `.strict()`.
54
+ * *\/
47
55
  * export const query = z
48
56
  * .object({
49
57
  * ...cursorPaginationQuery(),
@@ -53,9 +61,10 @@ import { type Field } from "../types";
53
61
  * ...includeQuery(userIncludeFields),
54
62
  * })
55
63
  * .strict();
56
- *
57
64
  * ```
58
65
  *
66
+ * </embedex>
67
+ *
59
68
  * @see {@link https://jsonapi.org/format/#fetching-sorting JSON:API sorting}
60
69
  */
61
70
  export declare function sortQuery<const FieldT extends readonly [Field, ...Field[]]>(fields: FieldT): {
package/src/lib/query/sortQuery.js CHANGED
@@ -6,9 +6,9 @@ const splitString_1 = require("../internal/splitString");
6
6
  /**
7
7
  * Creates a Zod schema for JSON:API sort parameters.
8
8
  *
9
- * @example
9
+ * <embedex source="packages/example-nestjs/examples/query.ts">
10
+ *
10
11
  * ```ts
11
- * // packages/example-nestjs/examples/query.ts
12
12
  * import { booleanString } from "@clipboard-health/contract-core";
13
13
  * import {
14
14
  * cursorPaginationQuery,
@@ -47,6 +47,14 @@ const splitString_1 = require("../internal/splitString");
47
47
  * },
48
48
  * } as const satisfies FilterMap<UserAttributeFields>;
49
49
  *
50
+ * /**
51
+ * * Disclaimer: Just because JSON:API supports robust querying doesn’t mean your service should
52
+ * * implement them as they may require database indexes, which have a cost. **Implement only access
53
+ * * patterns required by clients.**
54
+ * *
55
+ * * The spec says that if clients provide fields the server doesn’t support, it **MUST** return 400
56
+ * * Bad Request, hence the `.strict()`.
57
+ * *\/
50
58
  * export const query = z
51
59
  * .object({
52
60
  * ...cursorPaginationQuery(),
@@ -56,9 +64,10 @@ const splitString_1 = require("../internal/splitString");
56
64
  * ...includeQuery(userIncludeFields),
57
65
  * })
58
66
  * .strict();
59
- *
60
67
  * ```
61
68
  *
69
+ * </embedex>
70
+ *
62
71
  * @see {@link https://jsonapi.org/format/#fetching-sorting JSON:API sorting}
63
72
  */
64
73
  function sortQuery(fields) {
package/src/lib/query/sortQuery.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"sortQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/sortQuery.ts"],"names":[],"mappings":";;AA+DA,8BAsBC;AArFD,6BAAwB;AAExB,yDAAsD;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,SAAgB,SAAS,CAAoD,MAAc;IACzF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO;QACL,IAAI,EAAE,OAAC;aACJ,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;aACtE,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"}
1
+ {"version":3,"file":"sortQuery.js","sourceRoot":"","sources":["../../../../../../packages/json-api-nestjs/src/lib/query/sortQuery.ts"],"names":[],"mappings":";;AAwEA,8BAsBC;AA9FD,6BAAwB;AAExB,yDAAsD;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,SAAgB,SAAS,CAAoD,MAAc;IACzF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO;QACL,IAAI,EAAE,OAAC;aACJ,UAAU,CAAC,yBAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;aACtE,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"}