std-json-api - npm Package Compare versions

Comparing version 1.9.0 to 1.10.0

package.json

 {
   "name": "std-json-api",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "JSON-API standard utilities for NestJS",
@@ -5,0 +5,0 @@ "main": "index.js",

parser.d.ts

@@ -169,1 +169,36 @@ /**
 export declare function parser(searchString: string): JsonApiQuery;
+/**
+ * Serializes a JSON:API query object into a URL query string.
+ *
+ * This function is the inverse of `parser` and handles the standard JSON:API query parameters:
+ * - `sort`: Converted to comma-separated field names, `-` prefix for descending order
+ * - `page.offset` and `page.limit`: Converted to `page[offset]` and `page[limit]`
+ * - `page.cursor`, `page.field` and `page.limit`: Converted to cursor-based pagination params
+ * - `filter`: Converted to `filter[field]` format (supports nested structures)
+ * - `fields`: Converted to `fields[type]=field1,field2` format
+ * - `include`: Converted to comma-separated relationship paths
+ *
+ * @param query - The JSON:API query object to serialize
+ * @returns URL query string (without leading `?`)
+ *
+ * @example
+ * ```ts
+ * const queryString = serializer({
+ *   sort: { created: -1, title: 1 },
+ *   page: { offset: 20, limit: 10 }
+ * });
+ * // Returns: "sort=-created,title&page[offset]=20&page[limit]=10"
+ * ```
+ *
+ * @example
+ * ```ts
+ * const queryString = serializer({
+ *   filter: { status: "published" },
+ *   include: ["author", "comments"]
+ * });
+ * // Returns: "filter[status]=published&include=author,comments"
+ * ```
+ *
+ * @see https://jsonapi.org/format/#fetching
+ */
+export declare function serializer(query: JsonApiQuery): string;

parser.js

@@ -7,2 +7,3 @@ "use strict";
 exports.parser = parser;
+exports.serializer = serializer;
 const qs_1 = __importDefault(require("qs"));
@@ -238,1 +239,122 @@ /**
 }
+/**
+ * Serializes a JSON:API query object into a URL query string.
+ *
+ * This function is the inverse of `parser` and handles the standard JSON:API query parameters:
+ * - `sort`: Converted to comma-separated field names, `-` prefix for descending order
+ * - `page.offset` and `page.limit`: Converted to `page[offset]` and `page[limit]`
+ * - `page.cursor`, `page.field` and `page.limit`: Converted to cursor-based pagination params
+ * - `filter`: Converted to `filter[field]` format (supports nested structures)
+ * - `fields`: Converted to `fields[type]=field1,field2` format
+ * - `include`: Converted to comma-separated relationship paths
+ *
+ * @param query - The JSON:API query object to serialize
+ * @returns URL query string (without leading `?`)
+ *
+ * @example
+ * ```ts
+ * const queryString = serializer({
+ *   sort: { created: -1, title: 1 },
+ *   page: { offset: 20, limit: 10 }
+ * });
+ * // Returns: "sort=-created,title&page[offset]=20&page[limit]=10"
+ * ```
+ *
+ * @example
+ * ```ts
+ * const queryString = serializer({
+ *   filter: { status: "published" },
+ *   include: ["author", "comments"]
+ * });
+ * // Returns: "filter[status]=published&include=author,comments"
+ * ```
+ *
+ * @see https://jsonapi.org/format/#fetching
+ */
+function serializer(query) {
+    const obj = {};
+    // Serialize sort parameter
+    if (query.sort && Object.keys(query.sort).length > 0) {
+        obj.sort = serializeSortParameter(query.sort);
+    }
+    // Serialize page parameters
+    if (query.page) {
+        obj.page = serializePageParameter(query.page);
+    }
+    // Serialize filter parameters (pass through as-is, qs handles nested objects)
+    if (query.filter && Object.keys(query.filter).length > 0) {
+        obj.filter = query.filter;
+    }
+    // Serialize fields parameters
+    if (query.fields && Object.keys(query.fields).length > 0) {
+        obj.fields = serializeFieldsParameter(query.fields);
+    }
+    // Serialize include parameter
+    if (query.include && query.include.length > 0) {
+        obj.include = query.include.join(",");
+    }
+    // Pass through custom query parameters
+    for (const [key, value] of Object.entries(query)) {
+        if (!["sort", "page", "filter", "fields", "include"].includes(key)) {
+            obj[key] = value;
+        }
+    }
+    return qs_1.default.stringify(obj, { allowDots: false });
+}
+/**
+ * Converts sort object to comma-separated string format.
+ *
+ * @param sort - Sort object mapping field names to directions (1 or -1)
+ * @returns Comma-separated field names with optional `-` prefix for descending
+ *
+ * @internal
+ */
+function serializeSortParameter(sort) {
+    return Object.entries(sort)
+        .map(([field, direction]) => direction === -1 ? `-${field}` : field)
+        .join(",");
+}
+/**
+ * Converts page object to qs-compatible structure.
+ *
+ * @param page - Pagination object (OffsetPagination or CursorPagination)
+ * @returns Object suitable for qs.stringify
+ *
+ * @internal
+ */
+function serializePageParameter(page) {
+    if ("cursor" in page) {
+        const result = {
+            cursor: page.cursor,
+            limit: page.limit,
+        };
+        if (page.field && page.field !== "id") {
+            result.field = page.field;
+        }
+        return result;
+    }
+    return {
+        offset: page.offset,
+        limit: page.limit,
+    };
+}
+/**
+ * Converts fields object to qs-compatible structure with comma-separated values.
+ *
+ * @param fields - Fields object mapping resource types to field selections
+ * @returns Object with resource types as keys and comma-separated field names as values
+ *
+ * @internal
+ */
+function serializeFieldsParameter(fields) {
+    const result = {};
+    for (const [resourceType, fieldMap] of Object.entries(fields)) {
+        const includedFields = Object.entries(fieldMap)
+            .filter(([, included]) => included === 1)
+            .map(([fieldName]) => fieldName);
+        if (includedFields.length > 0) {
+            result[resourceType] = includedFields.join(",");
+        }
+    }
+    return result;
+}

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

73828

7.82%

Lines of code

2406

6.98%

No dependency changes