npm - @twin.org/web - Versions diffs - 0.9.1-next.4 → 0.9.1-next.6 - Mend

@twin.org/web 0.9.1-next.4 → 0.9.1-next.6

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 (6) hide show

package/dist/es/utils/headerHelper.js +88 -43
package/dist/es/utils/headerHelper.js.map +1 -1
package/dist/types/utils/headerHelper.d.ts +38 -0
package/docs/changelog.md +40 -0
package/docs/reference/classes/HeaderHelper.md +76 -0
package/package.json +4 -4

package/dist/es/utils/headerHelper.js CHANGED Viewed

@@ -24,12 +24,19 @@ export class HeaderHelper {
      */
     static _ACCEPT_LANGUAGE_TAG_REGEX = /^(\*|[A-Za-z]{1,8}(?:-[\dA-Za-z]{1,8})*)$/;
     /**
-     * Regex for valid Accept-Language quality parameters.
+     * Regex for valid quality parameters in negotiation headers.
      * Supports quality values from `0` to `1` with up to three decimal places.
      * Examples: `q=1`, `q=0.9`, `q=0.875`, `q=0`, `q=1.0`.
      * @internal
      */
-    static _ACCEPT_LANGUAGE_QUALITY_REGEX = /^q=(0(?:\.\d{1,3})?|1(?:\.0{1,3})?)$/i;
+    static _QUALITY_REGEX = /^q=(0(?:\.\d{1,3})?|1(?:\.0{1,3})?)$/i;
+    /**
+     * Regex for valid media type values in Accept headers.
+     * Supports wildcards, standard types, and vendor extensions.
+     * Examples: `text/html`, `application/json`, `image/*`, `application/vnd.api+json`.
+     * @internal
+     */
+    static _ACCEPT_MEDIA_TYPE_REGEX = /^(\*|[A-Za-z0-9][\w.+-]*)\/(\*|[A-Za-z0-9][\w.+-]*)$/;
     /**
      * Regex for valid IPv4 addresses.
      * Examples: `127.0.0.1`, `192.168.1.10`, `255.255.255.255`.
@@ -81,47 +88,30 @@ export class HeaderHelper {
      * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.
      */
     static parseAcceptLanguage(acceptLanguage) {
-        let headerValues = [];
-        if (Is.array(acceptLanguage)) {
-            headerValues = acceptLanguage
-                .map(headerValue => headerValue.trim())
-                .filter(headerValue => headerValue.length > 0);
-        }
-        else if (Is.stringValue(acceptLanguage)) {
-            headerValues = [acceptLanguage.trim()];
-        }
-        if (headerValues.length > 0) {
-            const entries = headerValues
-                .flatMap(headerValue => headerValue.split(","))
-                .map(segment => segment.trim())
-                .filter(segment => segment.length > 0);
-            const parsedEntries = [];
-            for (const entry of entries) {
-                const [languagePart, ...parameterParts] = entry.split(";").map(part => part.trim());
-                if (!HeaderHelper._ACCEPT_LANGUAGE_TAG_REGEX.test(languagePart)) {
-                    return undefined;
-                }
-                let quality = 1;
-                for (const parameterPart of parameterParts) {
-                    if (parameterPart.length > 0) {
-                        if (parameterPart.startsWith("q=") || parameterPart.startsWith("Q=")) {
-                            const qualityMatch = HeaderHelper._ACCEPT_LANGUAGE_QUALITY_REGEX.exec(parameterPart);
-                            if (!qualityMatch?.[1]) {
-                                return undefined;
-                            }
-                            quality = Number(qualityMatch[1]);
-                        }
-                    }
-                }
-                parsedEntries.push({
-                    language: languagePart,
-                    quality
-                });
-            }
-            if (parsedEntries.length > 0) {
-                return parsedEntries.sort((a, b) => b.quality - a.quality);
-            }
-        }
+        const parsed = HeaderHelper.parseWeightedHeader(acceptLanguage, HeaderHelper._ACCEPT_LANGUAGE_TAG_REGEX);
+        return parsed?.map(({ value, quality }) => ({ language: value, quality }));
+    }
+    /**
+     * Extract parsed media type preferences from the Accept header.
+     * @param headers The HTTP request headers.
+     * @returns The parsed media type preferences ordered by highest quality first, or undefined if missing or invalid.
+     */
+    static extractAccept(headers) {
+        return HeaderHelper.parseAccept(headers?.[HeaderTypes.Accept]);
+    }
+    /**
+     * Parse one or more Accept header values into media type preferences.
+     * @param accept The Accept header value or values.
+     * @returns The parsed media type preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept
+     */
+    static parseAccept(accept) {
+        const parsed = HeaderHelper.parseWeightedHeader(accept, HeaderHelper._ACCEPT_MEDIA_TYPE_REGEX);
+        return parsed?.map(({ value, quality, params }) => ({
+            mimeType: value,
+            quality,
+            ...(Object.keys(params).length > 0 ? { params } : {})
+        }));
     }
     /**
      * Extract client IP addresses from HTTP request headers.
@@ -369,6 +359,61 @@ export class HeaderHelper {
                 .join("")
             : ""}`;
     }
+    /**
+     * Parse a quality-weighted comma-separated header into entries.
+     * @param header The header value or values.
+     * @param valueValidator Regex to validate the value portion of each entry.
+     * @returns Entries ordered by quality descending, or undefined if any entry is invalid.
+     */
+    static parseWeightedHeader(header, valueValidator) {
+        let headerValues = [];
+        if (Is.array(header)) {
+            headerValues = header.map(v => v.trim()).filter(v => v.length > 0);
+        }
+        else if (Is.stringValue(header)) {
+            headerValues = [header.trim()];
+        }
+        if (headerValues.length > 0) {
+            const entries = headerValues
+                .flatMap(v => v.split(","))
+                .map(s => s.trim())
+                .filter(s => s.length > 0);
+            const parsed = [];
+            for (const entry of entries) {
+                const [valuePart, ...paramParts] = entry.split(";").map(p => p.trim());
+                if (!valueValidator.test(valuePart)) {
+                    return undefined;
+                }
+                let quality = 1;
+                const params = {};
+                for (const paramPart of paramParts) {
+                    if (paramPart.length > 0) {
+                        if (paramPart.startsWith("q=") || paramPart.startsWith("Q=")) {
+                            const qualityMatch = HeaderHelper._QUALITY_REGEX.exec(paramPart);
+                            if (!qualityMatch?.[1]) {
+                                return undefined;
+                            }
+                            quality = Number(qualityMatch[1]);
+                        }
+                        else {
+                            const eqIndex = paramPart.indexOf("=");
+                            if (eqIndex > 0) {
+                                const key = paramPart.slice(0, eqIndex).trim().toLowerCase();
+                                const val = paramPart.slice(eqIndex + 1).trim();
+                                if (key.length > 0) {
+                                    params[key] = val;
+                                }
+                            }
+                        }
+                    }
+                }
+                parsed.push({ value: valuePart, quality, params });
+            }
+            if (parsed.length > 0) {
+                return parsed.sort((a, b) => b.quality - a.quality);
+            }
+        }
+    }
     /**
      * Does the relation selector match any of the link header relations.
      * @param relations The relations from the header.

package/dist/es/utils/headerHelper.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"headerHelper.js","sourceRoot":"","sources":["../../../src/utils/headerHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ArrayHelper, GeneralError, Guards, Is } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { HeaderTypes } from \"../models/headerTypes.js\";\nimport type { HttpLinkRelType } from \"../models/httpLinkRelType.js\";\nimport type { IHttpHeaders } from \"../models/IHttpHeaders.js\";\nimport type { IHttpLinkHeader } from \"../models/IHttpLinkHeader.js\";\n\n/*\n Class to helper with header operations.\n /\nexport class HeaderHelper {\n\t/\n\t Runtime name for the class.\n\t /\n\tpublic static readonly CLASS_NAME: string = nameof<HeaderHelper>();\n\n\t/\n\t Regex for valid correlation ID (alphanumeric, dash, underscore).\n\t * Examples: `request_123`, `trace-id-456`, `ABC_789`.\n\t * @internal\n\t /\n\tprivate static readonly _CORRELATION_ID_REGEX = /^[\\w-]+$/;\n\n\t/\n\t Regex for valid Accept-Language tags and wildcard values.\n\t * Supports wildcard entries and common BCP 47 style tags.\n\t * Examples: ``, `en`, `en-GB`, `es-419`, `zh-Hant`, `zh-Hant-TW`.\n\t @internal\n\t /\n\tprivate static readonly _ACCEPT_LANGUAGE_TAG_REGEX = /^(\\\|[A-Za-z]{1,8}(?:-[\\dA-Za-z]{1,8}))$/;\n\n\t/\n\t Regex for valid Accept-Language quality parameters.\n\t * Supports quality values from `0` to `1` with up to three decimal places.\n\t * Examples: `q=1`, `q=0.9`, `q=0.875`, `q=0`, `q=1.0`.\n\t * @internal\n\t /\n\tprivate static readonly _ACCEPT_LANGUAGE_QUALITY_REGEX = /^q=(0(?:\\.\\d{1,3})?\|1(?:\\.0{1,3})?)$/i;\n\n\t/\n\t Regex for valid IPv4 addresses.\n\t * Examples: `127.0.0.1`, `192.168.1.10`, `255.255.255.255`.\n\t * @internal\n\t /\n\tprivate static readonly _IP_V4_REGEX =\n\t\t/^(?:25[0-5]\|2[0-4]\\d\|1\\d\\d\|[1-9]?\\d)(?:\\.(?:25[0-5]\|2[0-4]\\d\|1\\d\\d\|[1-9]?\\d)){3}$/;\n\n\t/\n\t Regex for valid IPv6 addresses.\n\t * Examples: `2001:0db8:85a3:0000:0000:8a2e:0370:7334`, `2001:db8::`, `::1`.\n\t * @internal\n\t /\n\tprivate static readonly _IP_V6_REGEX =\n\t\t/^((?:[\\dA-Fa-f]{1,4}:){7}[\\dA-Fa-f]{1,4}\|(?:[\\dA-Fa-f]{1,4}:){1,7}:\|:(?::[\\dA-Fa-f]{1,4}){1,7})$/;\n\n\t/\n\t Create a bearer token header.\n\t * @param token The token to create the header for.\n\t * @returns The bearer token header.\n\t /\n\tpublic static createBearer(token: unknown): string {\n\t\tif (Is.stringValue(token)) {\n\t\t\tif (token.startsWith(\"Bearer \")) {\n\t\t\t\treturn token;\n\t\t\t}\n\t\t\treturn `Bearer ${token.trim()}`;\n\t\t}\n\t\treturn \"\";\n\t}\n\n\t/\n\t Extract the bearer token from a header.\n\t * @param header The header value to extract the token from.\n\t * @returns The extracted token if it exists.\n\t /\n\tpublic static extractBearer(header: unknown): string {\n\t\tif (Is.stringValue(header) && header.startsWith(\"Bearer \")) {\n\t\t\treturn header.slice(7, header.length).trim();\n\t\t}\n\t\treturn \"\";\n\t}\n\n\t/\n\t Extract parsed language preferences from the Accept-Language header.\n\t * @param headers The HTTP request headers.\n\t * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or invalid.\n\t /\n\tpublic static extractAcceptLanguage(\n\t\theaders?: IHttpHeaders\n\t): { language: string; quality: number }[] \| undefined {\n\t\treturn HeaderHelper.parseAcceptLanguage(headers?.[HeaderTypes.AcceptLanguage]);\n\t}\n\n\t/\n\t Parse one or more Accept-Language header values into language preferences.\n\t * @param acceptLanguage The Accept-Language header value or values.\n\t * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.\n\t /\n\tpublic static parseAcceptLanguage(\n\t\tacceptLanguage: string \| string[] \| undefined\n\t): { language: string; quality: number }[] \| undefined {\n\t\tlet headerValues: string[] = [];\n\n\t\tif (Is.array(acceptLanguage)) {\n\t\t\theaderValues = acceptLanguage\n\t\t\t\t.map(headerValue => headerValue.trim())\n\t\t\t\t.filter(headerValue => headerValue.length > 0);\n\t\t} else if (Is.stringValue(acceptLanguage)) {\n\t\t\theaderValues = [acceptLanguage.trim()];\n\t\t}\n\n\t\tif (headerValues.length > 0) {\n\t\t\tconst entries = headerValues\n\t\t\t\t.flatMap(headerValue => headerValue.split(\",\"))\n\t\t\t\t.map(segment => segment.trim())\n\t\t\t\t.filter(segment => segment.length > 0);\n\n\t\t\tconst parsedEntries: { language: string; quality: number }[] = [];\n\n\t\t\tfor (const entry of entries) {\n\t\t\t\tconst [languagePart, ...parameterParts] = entry.split(\";\").map(part => part.trim());\n\n\t\t\t\tif (!HeaderHelper._ACCEPT_LANGUAGE_TAG_REGEX.test(languagePart)) {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\tlet quality = 1;\n\n\t\t\t\tfor (const parameterPart of parameterParts) {\n\t\t\t\t\tif (parameterPart.length > 0) {\n\t\t\t\t\t\tif (parameterPart.startsWith(\"q=\") \|\| parameterPart.startsWith(\"Q=\")) {\n\t\t\t\t\t\t\tconst qualityMatch = HeaderHelper._ACCEPT_LANGUAGE_QUALITY_REGEX.exec(parameterPart);\n\t\t\t\t\t\t\tif (!qualityMatch?.[1]) {\n\t\t\t\t\t\t\t\treturn undefined;\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tquality = Number(qualityMatch[1]);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tparsedEntries.push({\n\t\t\t\t\tlanguage: languagePart,\n\t\t\t\t\tquality\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (parsedEntries.length > 0) {\n\t\t\t\treturn parsedEntries.sort((a, b) => b.quality - a.quality);\n\t\t\t}\n\t\t}\n\t}\n\n\t/\n\t Extract client IP addresses from HTTP request headers.\n\t * Checks all `X-Forwarded-For` and `X-Real-IP` header values for proxied requests.\n\t * @param headers The HTTP request headers.\n\t * @returns The extracted client IP addresses in header order.\n\t /\n\tpublic static extractClientIps(headers?: IHttpHeaders): string[] {\n\t\tconst ips: string[] = [];\n\n\t\tconst forwardedForValues = HeaderHelper.getHeaderValues(headers?.[\"x-forwarded-for\"]);\n\t\tfor (const forwardedFor of forwardedForValues) {\n\t\t\tconst forwardedIps = forwardedFor\n\t\t\t\t.split(\",\")\n\t\t\t\t.map(ip => ip.trim())\n\t\t\t\t.filter(ip => HeaderHelper.isIpAddress(ip));\n\n\t\t\tips.push(...forwardedIps);\n\t\t}\n\n\t\tconst realIpValues = HeaderHelper.getHeaderValues(headers?.[\"x-real-ip\"]);\n\t\tfor (const realIp of realIpValues) {\n\t\t\tif (HeaderHelper.isIpAddress(realIp)) {\n\t\t\t\tips.push(realIp);\n\t\t\t}\n\t\t}\n\n\t\treturn ips;\n\t}\n\n\t/\n\t Extract the User-Agent header from the HTTP request context.\n\t * @param headers The HTTP request headers.\n\t * @param maxLength Optional maximum length for the User-Agent string to prevent excessively long values.\n\t * @returns The user agent string or undefined if not available.\n\t /\n\tpublic static extractUserAgent(headers?: IHttpHeaders, maxLength?: number): string \| undefined {\n\t\tconst headerValues = HeaderHelper.getHeaderValues(headers?.[HeaderTypes.UserAgent]);\n\t\tfor (const headerValue of headerValues) {\n\t\t\treturn Is.integer(maxLength) ? headerValue.slice(0, maxLength) : headerValue;\n\t\t}\n\t}\n\n\t/\n\t Extract a correlation ID for request tracing from the X-Correlation-ID header.\n\t * @param headers The HTTP request headers.\n\t * @param maxLength Optional maximum length for the extracted correlation ID.\n\t * @returns The correlation ID, or undefined if the header is missing or invalid.\n\t /\n\tpublic static extractCorrelationId(\n\t\theaders?: IHttpHeaders,\n\t\tmaxLength?: number\n\t): string \| undefined {\n\t\tconst headerValues = HeaderHelper.getHeaderValues(headers?.[\"x-correlation-id\"]);\n\t\tfor (const headerValue of headerValues) {\n\t\t\tif (HeaderHelper._CORRELATION_ID_REGEX.test(headerValue)) {\n\t\t\t\treturn Is.integer(maxLength) ? headerValue.slice(0, maxLength) : headerValue;\n\t\t\t}\n\t\t}\n\t}\n\n\t/\n\t Validate if a string is a valid IP address (IPv4 or IPv6).\n\t * @param ip The IP address to validate.\n\t * @returns True if valid, false otherwise.\n\t /\n\tpublic static isIpAddress(ip: string): boolean {\n\t\tif (!Is.stringValue(ip)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn HeaderHelper.isIpAddressV4(ip) \|\| HeaderHelper.isIpAddressV6(ip);\n\t}\n\n\t/\n\t Validate if a string is a valid IP address IPv4.\n\t * @param ip The IP address to validate.\n\t * @returns True if valid, false otherwise.\n\t /\n\tpublic static isIpAddressV4(ip: string): boolean {\n\t\tif (!Is.stringValue(ip)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn HeaderHelper._IP_V4_REGEX.test(ip);\n\t}\n\n\t/\n\t Validate if a string is a valid IP address IPv6.\n\t * @param ip The IP address to validate.\n\t * @returns True if valid, false otherwise.\n\t /\n\tpublic static isIpAddressV6(ip: string): boolean {\n\t\tif (!Is.stringValue(ip)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn HeaderHelper._IP_V6_REGEX.test(ip);\n\t}\n\n\t/\n\t Extract the first occurrence of properties from a Link header for a specific relation type.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @param relation The relation type to extract.\n\t * @returns The extracted URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaderRelation(\n\t\tlinkHeader: string \| string[] \| undefined,\n\t\trelation: HttpLinkRelType \| string \| RegExp\n\t): IHttpLinkHeader \| undefined {\n\t\tconst headers = HeaderHelper.extractLinkHeaders(linkHeader);\n\t\tif (Is.arrayValue(headers)) {\n\t\t\treturn headers.find(h => HeaderHelper.matchesLinkHeaderRelation(h.rel, relation));\n\t\t}\n\t}\n\n\t/\n\t Extract multiple properties from a Link header for a specific relation type.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @param relation The relation type to extract.\n\t * @returns The extracted URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaderRelations(\n\t\tlinkHeader: string \| string[] \| undefined,\n\t\trelation: HttpLinkRelType \| string \| RegExp\n\t): IHttpLinkHeader[] \| undefined {\n\t\tconst headers = HeaderHelper.extractLinkHeaders(linkHeader);\n\t\tif (Is.arrayValue(headers)) {\n\t\t\treturn headers.filter(h => HeaderHelper.matchesLinkHeaderRelation(h.rel, relation));\n\t\t}\n\t}\n\n\t/\n\t Extract the link headers.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @returns The extracted possible array of URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaders(\n\t\tlinkHeader: string \| string[] \| undefined\n\t): IHttpLinkHeader[] \| undefined {\n\t\tconst linkHeaderArray = ArrayHelper.fromObjectOrArray<string>(linkHeader);\n\t\tif (Is.arrayValue<string>(linkHeaderArray)) {\n\t\t\tconst results = [];\n\t\t\tfor (const singleLinkHeader of linkHeaderArray) {\n\t\t\t\tconst segments = HeaderHelper.extractLinkHeaderSegments(singleLinkHeader);\n\t\t\t\tresults.push(\n\t\t\t\t\t...segments.map(l => HeaderHelper.extractLinkHeader(l)).filter(h => !Is.empty(h))\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn results;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/\n\t Split a combined Link header value into individual link-value segments, comma separated.\n\t * @param linkHeader Raw Link header string.\n\t * @returns Array of individual link-value segments.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaderSegments(linkHeader: string): string[] {\n\t\tif (!Is.stringValue(linkHeader)) {\n\t\t\treturn [];\n\t\t}\n\t\tconst trimmed = linkHeader.trim();\n\t\tif (Is.empty(trimmed)) {\n\t\t\treturn [];\n\t\t}\n\t\treturn trimmed\n\t\t\t.split(/,(?=\\s<)/)\n\t\t\t.map(s => s.trim())\n\t\t\t.filter(s => !Is.empty(s));\n\t}\n\n\t/*\n\t Extract the properties from a Link header.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @returns The extracted URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeader(linkHeader: string): IHttpLinkHeader \| undefined {\n\t\tif (!Is.stringValue(linkHeader)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst parts = linkHeader.split(\";\");\n\n\t\tif (parts.length >= 2) {\n\t\t\tlet url;\n\t\t\tlet urlQueryParams: { [id: string]: string } \| undefined;\n\n\t\t\tconst urlMatch = /<([^>]+)>/.exec(parts[0]);\n\t\t\tif (Is.stringValue(urlMatch?.[1])) {\n\t\t\t\turl = urlMatch[1];\n\n\t\t\t\tconst queryIndex = url.indexOf(\"?\");\n\t\t\t\tif (queryIndex !== -1) {\n\t\t\t\t\tconst urlParamsString = url.slice(queryIndex + 1);\n\t\t\t\t\tconst queryParts = urlParamsString.split(\"&\");\n\n\t\t\t\t\tfor (const queryPart of queryParts) {\n\t\t\t\t\t\tconst [key, value] = queryPart.split(\"=\");\n\t\t\t\t\t\tif (Is.stringValue(key) && Is.stringValue(value)) {\n\t\t\t\t\t\t\turlQueryParams ??= {};\n\t\t\t\t\t\t\turlQueryParams[key] = decodeURIComponent(value);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tlet rel: string[] \| undefined;\n\t\t\tconst params: { [id: string]: string } = {};\n\n\t\t\tfor (let i = 1; i < parts.length; i++) {\n\t\t\t\tconst relMatch = /rel=\"([^\"]+)\"/.exec(parts[i].trim());\n\t\t\t\tif (relMatch?.[1]) {\n\t\t\t\t\trel = HeaderHelper.normalizeLinkHeaderRelations(relMatch[1]);\n\t\t\t\t} else {\n\t\t\t\t\tconst paramMatch = /([^=]+)=\"([^\"]+)\"/.exec(parts[i].trim());\n\t\t\t\t\tif (paramMatch?.[1] && paramMatch?.[2]) {\n\t\t\t\t\t\tparams[paramMatch[1]] = paramMatch[2];\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (Is.stringValue(url) && Is.arrayValue(rel)) {\n\t\t\t\treturn {\n\t\t\t\t\turl,\n\t\t\t\t\turlQueryParams,\n\t\t\t\t\trel,\n\t\t\t\t\tparams: Object.keys(params).length > 0 ? params : undefined\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/\n\t Create a compliant Link header.\n\t * @param url The URL to include in the Link header.\n\t * @param urlQueryParams Optional query parameters to include in the URL.\n\t * @param rel The relation type (e.g., \"next\", \"prev\", \"self\").\n\t * @returns The formatted Link header string.\n\t * @throws GeneralError if the URL or rel are invalid.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static createLinkHeader(\n\t\turl: string,\n\t\turlQueryParams: { [id: string]: string } \| undefined,\n\t\trel: HttpLinkRelType \| HttpLinkRelType[] \| string \| string[],\n\t\tparams?: { [id: string]: string }\n\t): string {\n\t\tGuards.stringValue(HeaderHelper.CLASS_NAME, nameof(url), url);\n\n\t\tconst relationValues = Is.string(rel)\n\t\t\t? HeaderHelper.normalizeLinkHeaderRelations(rel)\n\t\t\t: ArrayHelper.fromObjectOrArray(rel);\n\n\t\tGuards.arrayValue(HeaderHelper.CLASS_NAME, nameof(rel), relationValues);\n\n\t\tif (url.includes(\">\")) {\n\t\t\tthrow new GeneralError(HeaderHelper.CLASS_NAME, \"invalidLinkHeaderURL\");\n\t\t}\n\n\t\tfor (let i = 0; i < relationValues.length; i++) {\n\t\t\tGuards.stringValue(\n\t\t\t\tHeaderHelper.CLASS_NAME,\n\t\t\t\t`${nameof(rel)}.${i.toString()}`,\n\t\t\t\trelationValues[i]\n\t\t\t);\n\t\t\tif (relationValues[i].includes('\"') \|\| relationValues[i].includes(\" \")) {\n\t\t\t\tthrow new GeneralError(HeaderHelper.CLASS_NAME, \"invalidLinkHeaderRel\");\n\t\t\t}\n\t\t}\n\n\t\tif (Is.objectValue(urlQueryParams)) {\n\t\t\tconst queryParamsString = Object.entries(urlQueryParams)\n\t\t\t\t.map(([key, value]) => `${key}=${encodeURIComponent(value)}`)\n\t\t\t\t.join(\"&\");\n\t\t\tconst queryIndex = url.indexOf(\"?\");\n\t\t\tif (queryIndex === -1) {\n\t\t\t\turl += `?${queryParamsString}`;\n\t\t\t} else if (queryIndex === url.length - 1) {\n\t\t\t\turl += queryParamsString;\n\t\t\t} else {\n\t\t\t\turl += `&${queryParamsString}`;\n\t\t\t}\n\t\t}\n\n\t\treturn `<${url}>; rel=\"${relationValues.join(\" \")}\"${\n\t\t\tparams\n\t\t\t\t? Object.entries(params)\n\t\t\t\t\t\t.map(([key, value]) => `; ${key}=\"${value}\"`)\n\t\t\t\t\t\t.join(\"\")\n\t\t\t\t: \"\"\n\t\t}`;\n\t}\n\n\t/\n\t Does the relation selector match any of the link header relations.\n\t * @param relations The relations from the header.\n\t * @param relation The relation selector to test.\n\t * @returns True if the selector matches any relation.\n\t * @internal\n\t /\n\tprivate static matchesLinkHeaderRelation(\n\t\trelations: (HttpLinkRelType \| string)[],\n\t\trelation: HttpLinkRelType \| string \| RegExp\n\t): boolean {\n\t\tif (Is.string(relation)) {\n\t\t\treturn relations.includes(relation);\n\t\t}\n\n\t\treturn relations.some(relValue => relation.test(relValue));\n\t}\n\n\t/\n\t Normalize a relation string into tokens.\n\t * @param relation The relation string.\n\t * @returns The relation tokens.\n\t * @internal\n\t /\n\tprivate static normalizeLinkHeaderRelations(relation: string): HttpLinkRelType[] {\n\t\treturn relation\n\t\t\t.split(/\\s+/)\n\t\t\t.map(relValue => relValue.trim())\n\t\t\t.filter(relValue => !Is.empty(relValue)) as HttpLinkRelType[];\n\t}\n\n\t/\n\t Get all non-empty values from a header that may be a string or string array.\n\t * @param header The header value (string, string array, or undefined).\n\t * @returns The trimmed non-empty string values.\n\t * @internal\n\t */\n\tprivate static getHeaderValues(header: string \| string[] \| undefined): string[] {\n\t\tlet headerValues: string[] = [];\n\n\t\tif (Is.array(header)) {\n\t\t\theaderValues = header;\n\t\t} else if (Is.stringValue(header)) {\n\t\t\theaderValues = [header];\n\t\t}\n\n\t\treturn headerValues\n\t\t\t.map(headerValue => headerValue.trim())\n\t\t\t.filter(headerValue => headerValue.length > 0);\n\t}\n}\n"]}
1	+ {"version":3,"file":"headerHelper.js","sourceRoot":"","sources":["../../../src/utils/headerHelper.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ArrayHelper, GeneralError, Guards, Is } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { HeaderTypes } from \"../models/headerTypes.js\";\nimport type { HttpLinkRelType } from \"../models/httpLinkRelType.js\";\nimport type { IHttpHeaders } from \"../models/IHttpHeaders.js\";\nimport type { IHttpLinkHeader } from \"../models/IHttpLinkHeader.js\";\n\n/*\n Class to helper with header operations.\n /\nexport class HeaderHelper {\n\t/\n\t Runtime name for the class.\n\t /\n\tpublic static readonly CLASS_NAME: string = nameof<HeaderHelper>();\n\n\t/\n\t Regex for valid correlation ID (alphanumeric, dash, underscore).\n\t * Examples: `request_123`, `trace-id-456`, `ABC_789`.\n\t * @internal\n\t /\n\tprivate static readonly _CORRELATION_ID_REGEX = /^[\\w-]+$/;\n\n\t/\n\t Regex for valid Accept-Language tags and wildcard values.\n\t * Supports wildcard entries and common BCP 47 style tags.\n\t * Examples: ``, `en`, `en-GB`, `es-419`, `zh-Hant`, `zh-Hant-TW`.\n\t @internal\n\t /\n\tprivate static readonly _ACCEPT_LANGUAGE_TAG_REGEX = /^(\\\|[A-Za-z]{1,8}(?:-[\\dA-Za-z]{1,8}))$/;\n\n\t/\n\t Regex for valid quality parameters in negotiation headers.\n\t * Supports quality values from `0` to `1` with up to three decimal places.\n\t * Examples: `q=1`, `q=0.9`, `q=0.875`, `q=0`, `q=1.0`.\n\t * @internal\n\t /\n\tprivate static readonly _QUALITY_REGEX = /^q=(0(?:\\.\\d{1,3})?\|1(?:\\.0{1,3})?)$/i;\n\n\t/\n\t Regex for valid media type values in Accept headers.\n\t * Supports wildcards, standard types, and vendor extensions.\n\t * Examples: `text/html`, `application/json`, `image/`, `application/vnd.api+json`.\n\t @internal\n\t /\n\tprivate static readonly _ACCEPT_MEDIA_TYPE_REGEX =\n\t\t/^(\\\|[A-Za-z0-9][\\w.+-])\\/(\\\|[A-Za-z0-9][\\w.+-])$/;\n\n\t/\n\t Regex for valid IPv4 addresses.\n\t * Examples: `127.0.0.1`, `192.168.1.10`, `255.255.255.255`.\n\t * @internal\n\t /\n\tprivate static readonly _IP_V4_REGEX =\n\t\t/^(?:25[0-5]\|2[0-4]\\d\|1\\d\\d\|[1-9]?\\d)(?:\\.(?:25[0-5]\|2[0-4]\\d\|1\\d\\d\|[1-9]?\\d)){3}$/;\n\n\t/\n\t Regex for valid IPv6 addresses.\n\t * Examples: `2001:0db8:85a3:0000:0000:8a2e:0370:7334`, `2001:db8::`, `::1`.\n\t * @internal\n\t /\n\tprivate static readonly _IP_V6_REGEX =\n\t\t/^((?:[\\dA-Fa-f]{1,4}:){7}[\\dA-Fa-f]{1,4}\|(?:[\\dA-Fa-f]{1,4}:){1,7}:\|:(?::[\\dA-Fa-f]{1,4}){1,7})$/;\n\n\t/\n\t Create a bearer token header.\n\t * @param token The token to create the header for.\n\t * @returns The bearer token header.\n\t /\n\tpublic static createBearer(token: unknown): string {\n\t\tif (Is.stringValue(token)) {\n\t\t\tif (token.startsWith(\"Bearer \")) {\n\t\t\t\treturn token;\n\t\t\t}\n\t\t\treturn `Bearer ${token.trim()}`;\n\t\t}\n\t\treturn \"\";\n\t}\n\n\t/\n\t Extract the bearer token from a header.\n\t * @param header The header value to extract the token from.\n\t * @returns The extracted token if it exists.\n\t /\n\tpublic static extractBearer(header: unknown): string {\n\t\tif (Is.stringValue(header) && header.startsWith(\"Bearer \")) {\n\t\t\treturn header.slice(7, header.length).trim();\n\t\t}\n\t\treturn \"\";\n\t}\n\n\t/\n\t Extract parsed language preferences from the Accept-Language header.\n\t * @param headers The HTTP request headers.\n\t * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or invalid.\n\t /\n\tpublic static extractAcceptLanguage(\n\t\theaders?: IHttpHeaders\n\t): { language: string; quality: number }[] \| undefined {\n\t\treturn HeaderHelper.parseAcceptLanguage(headers?.[HeaderTypes.AcceptLanguage]);\n\t}\n\n\t/\n\t Parse one or more Accept-Language header values into language preferences.\n\t * @param acceptLanguage The Accept-Language header value or values.\n\t * @returns The parsed language preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.\n\t /\n\tpublic static parseAcceptLanguage(\n\t\tacceptLanguage: string \| string[] \| undefined\n\t): { language: string; quality: number }[] \| undefined {\n\t\tconst parsed = HeaderHelper.parseWeightedHeader(\n\t\t\tacceptLanguage,\n\t\t\tHeaderHelper._ACCEPT_LANGUAGE_TAG_REGEX\n\t\t);\n\t\treturn parsed?.map(({ value, quality }) => ({ language: value, quality }));\n\t}\n\n\t/\n\t Extract parsed media type preferences from the Accept header.\n\t * @param headers The HTTP request headers.\n\t * @returns The parsed media type preferences ordered by highest quality first, or undefined if missing or invalid.\n\t /\n\tpublic static extractAccept(\n\t\theaders?: IHttpHeaders\n\t): { mimeType: string; quality: number; params?: { [key: string]: string } }[] \| undefined {\n\t\treturn HeaderHelper.parseAccept(headers?.[HeaderTypes.Accept]);\n\t}\n\n\t/\n\t Parse one or more Accept header values into media type preferences.\n\t * @param accept The Accept header value or values.\n\t * @returns The parsed media type preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept\n\t /\n\tpublic static parseAccept(\n\t\taccept: string \| string[] \| undefined\n\t): { mimeType: string; quality: number; params?: { [key: string]: string } }[] \| undefined {\n\t\tconst parsed = HeaderHelper.parseWeightedHeader(accept, HeaderHelper._ACCEPT_MEDIA_TYPE_REGEX);\n\t\treturn parsed?.map(({ value, quality, params }) => ({\n\t\t\tmimeType: value,\n\t\t\tquality,\n\t\t\t...(Object.keys(params).length > 0 ? { params } : {})\n\t\t}));\n\t}\n\n\t/\n\t Extract client IP addresses from HTTP request headers.\n\t * Checks all `X-Forwarded-For` and `X-Real-IP` header values for proxied requests.\n\t * @param headers The HTTP request headers.\n\t * @returns The extracted client IP addresses in header order.\n\t /\n\tpublic static extractClientIps(headers?: IHttpHeaders): string[] {\n\t\tconst ips: string[] = [];\n\n\t\tconst forwardedForValues = HeaderHelper.getHeaderValues(headers?.[\"x-forwarded-for\"]);\n\t\tfor (const forwardedFor of forwardedForValues) {\n\t\t\tconst forwardedIps = forwardedFor\n\t\t\t\t.split(\",\")\n\t\t\t\t.map(ip => ip.trim())\n\t\t\t\t.filter(ip => HeaderHelper.isIpAddress(ip));\n\n\t\t\tips.push(...forwardedIps);\n\t\t}\n\n\t\tconst realIpValues = HeaderHelper.getHeaderValues(headers?.[\"x-real-ip\"]);\n\t\tfor (const realIp of realIpValues) {\n\t\t\tif (HeaderHelper.isIpAddress(realIp)) {\n\t\t\t\tips.push(realIp);\n\t\t\t}\n\t\t}\n\n\t\treturn ips;\n\t}\n\n\t/\n\t Extract the User-Agent header from the HTTP request context.\n\t * @param headers The HTTP request headers.\n\t * @param maxLength Optional maximum length for the User-Agent string to prevent excessively long values.\n\t * @returns The user agent string or undefined if not available.\n\t /\n\tpublic static extractUserAgent(headers?: IHttpHeaders, maxLength?: number): string \| undefined {\n\t\tconst headerValues = HeaderHelper.getHeaderValues(headers?.[HeaderTypes.UserAgent]);\n\t\tfor (const headerValue of headerValues) {\n\t\t\treturn Is.integer(maxLength) ? headerValue.slice(0, maxLength) : headerValue;\n\t\t}\n\t}\n\n\t/\n\t Extract a correlation ID for request tracing from the X-Correlation-ID header.\n\t * @param headers The HTTP request headers.\n\t * @param maxLength Optional maximum length for the extracted correlation ID.\n\t * @returns The correlation ID, or undefined if the header is missing or invalid.\n\t /\n\tpublic static extractCorrelationId(\n\t\theaders?: IHttpHeaders,\n\t\tmaxLength?: number\n\t): string \| undefined {\n\t\tconst headerValues = HeaderHelper.getHeaderValues(headers?.[\"x-correlation-id\"]);\n\t\tfor (const headerValue of headerValues) {\n\t\t\tif (HeaderHelper._CORRELATION_ID_REGEX.test(headerValue)) {\n\t\t\t\treturn Is.integer(maxLength) ? headerValue.slice(0, maxLength) : headerValue;\n\t\t\t}\n\t\t}\n\t}\n\n\t/\n\t Validate if a string is a valid IP address (IPv4 or IPv6).\n\t * @param ip The IP address to validate.\n\t * @returns True if valid, false otherwise.\n\t /\n\tpublic static isIpAddress(ip: string): boolean {\n\t\tif (!Is.stringValue(ip)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn HeaderHelper.isIpAddressV4(ip) \|\| HeaderHelper.isIpAddressV6(ip);\n\t}\n\n\t/\n\t Validate if a string is a valid IP address IPv4.\n\t * @param ip The IP address to validate.\n\t * @returns True if valid, false otherwise.\n\t /\n\tpublic static isIpAddressV4(ip: string): boolean {\n\t\tif (!Is.stringValue(ip)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn HeaderHelper._IP_V4_REGEX.test(ip);\n\t}\n\n\t/\n\t Validate if a string is a valid IP address IPv6.\n\t * @param ip The IP address to validate.\n\t * @returns True if valid, false otherwise.\n\t /\n\tpublic static isIpAddressV6(ip: string): boolean {\n\t\tif (!Is.stringValue(ip)) {\n\t\t\treturn false;\n\t\t}\n\t\treturn HeaderHelper._IP_V6_REGEX.test(ip);\n\t}\n\n\t/\n\t Extract the first occurrence of properties from a Link header for a specific relation type.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @param relation The relation type to extract.\n\t * @returns The extracted URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaderRelation(\n\t\tlinkHeader: string \| string[] \| undefined,\n\t\trelation: HttpLinkRelType \| string \| RegExp\n\t): IHttpLinkHeader \| undefined {\n\t\tconst headers = HeaderHelper.extractLinkHeaders(linkHeader);\n\t\tif (Is.arrayValue(headers)) {\n\t\t\treturn headers.find(h => HeaderHelper.matchesLinkHeaderRelation(h.rel, relation));\n\t\t}\n\t}\n\n\t/\n\t Extract multiple properties from a Link header for a specific relation type.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @param relation The relation type to extract.\n\t * @returns The extracted URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaderRelations(\n\t\tlinkHeader: string \| string[] \| undefined,\n\t\trelation: HttpLinkRelType \| string \| RegExp\n\t): IHttpLinkHeader[] \| undefined {\n\t\tconst headers = HeaderHelper.extractLinkHeaders(linkHeader);\n\t\tif (Is.arrayValue(headers)) {\n\t\t\treturn headers.filter(h => HeaderHelper.matchesLinkHeaderRelation(h.rel, relation));\n\t\t}\n\t}\n\n\t/\n\t Extract the link headers.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @returns The extracted possible array of URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaders(\n\t\tlinkHeader: string \| string[] \| undefined\n\t): IHttpLinkHeader[] \| undefined {\n\t\tconst linkHeaderArray = ArrayHelper.fromObjectOrArray<string>(linkHeader);\n\t\tif (Is.arrayValue<string>(linkHeaderArray)) {\n\t\t\tconst results = [];\n\t\t\tfor (const singleLinkHeader of linkHeaderArray) {\n\t\t\t\tconst segments = HeaderHelper.extractLinkHeaderSegments(singleLinkHeader);\n\t\t\t\tresults.push(\n\t\t\t\t\t...segments.map(l => HeaderHelper.extractLinkHeader(l)).filter(h => !Is.empty(h))\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn results;\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t/\n\t Split a combined Link header value into individual link-value segments, comma separated.\n\t * @param linkHeader Raw Link header string.\n\t * @returns Array of individual link-value segments.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeaderSegments(linkHeader: string): string[] {\n\t\tif (!Is.stringValue(linkHeader)) {\n\t\t\treturn [];\n\t\t}\n\t\tconst trimmed = linkHeader.trim();\n\t\tif (Is.empty(trimmed)) {\n\t\t\treturn [];\n\t\t}\n\t\treturn trimmed\n\t\t\t.split(/,(?=\\s<)/)\n\t\t\t.map(s => s.trim())\n\t\t\t.filter(s => !Is.empty(s));\n\t}\n\n\t/*\n\t Extract the properties from a Link header.\n\t * @param linkHeader The Link header value in format `<url>; rel=\"...\"; param1=\"\"; param2=\"\"`.\n\t * @returns The extracted URL, rel and optional params or undefined if invalid/missing.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static extractLinkHeader(linkHeader: string): IHttpLinkHeader \| undefined {\n\t\tif (!Is.stringValue(linkHeader)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst parts = linkHeader.split(\";\");\n\n\t\tif (parts.length >= 2) {\n\t\t\tlet url;\n\t\t\tlet urlQueryParams: { [id: string]: string } \| undefined;\n\n\t\t\tconst urlMatch = /<([^>]+)>/.exec(parts[0]);\n\t\t\tif (Is.stringValue(urlMatch?.[1])) {\n\t\t\t\turl = urlMatch[1];\n\n\t\t\t\tconst queryIndex = url.indexOf(\"?\");\n\t\t\t\tif (queryIndex !== -1) {\n\t\t\t\t\tconst urlParamsString = url.slice(queryIndex + 1);\n\t\t\t\t\tconst queryParts = urlParamsString.split(\"&\");\n\n\t\t\t\t\tfor (const queryPart of queryParts) {\n\t\t\t\t\t\tconst [key, value] = queryPart.split(\"=\");\n\t\t\t\t\t\tif (Is.stringValue(key) && Is.stringValue(value)) {\n\t\t\t\t\t\t\turlQueryParams ??= {};\n\t\t\t\t\t\t\turlQueryParams[key] = decodeURIComponent(value);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tlet rel: string[] \| undefined;\n\t\t\tconst params: { [id: string]: string } = {};\n\n\t\t\tfor (let i = 1; i < parts.length; i++) {\n\t\t\t\tconst relMatch = /rel=\"([^\"]+)\"/.exec(parts[i].trim());\n\t\t\t\tif (relMatch?.[1]) {\n\t\t\t\t\trel = HeaderHelper.normalizeLinkHeaderRelations(relMatch[1]);\n\t\t\t\t} else {\n\t\t\t\t\tconst paramMatch = /([^=]+)=\"([^\"]+)\"/.exec(parts[i].trim());\n\t\t\t\t\tif (paramMatch?.[1] && paramMatch?.[2]) {\n\t\t\t\t\t\tparams[paramMatch[1]] = paramMatch[2];\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (Is.stringValue(url) && Is.arrayValue(rel)) {\n\t\t\t\treturn {\n\t\t\t\t\turl,\n\t\t\t\t\turlQueryParams,\n\t\t\t\t\trel,\n\t\t\t\t\tparams: Object.keys(params).length > 0 ? params : undefined\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/\n\t Create a compliant Link header.\n\t * @param url The URL to include in the Link header.\n\t * @param urlQueryParams Optional query parameters to include in the URL.\n\t * @param rel The relation type (e.g., \"next\", \"prev\", \"self\").\n\t * @returns The formatted Link header string.\n\t * @throws GeneralError if the URL or rel are invalid.\n\t * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link\n\t /\n\tpublic static createLinkHeader(\n\t\turl: string,\n\t\turlQueryParams: { [id: string]: string } \| undefined,\n\t\trel: HttpLinkRelType \| HttpLinkRelType[] \| string \| string[],\n\t\tparams?: { [id: string]: string }\n\t): string {\n\t\tGuards.stringValue(HeaderHelper.CLASS_NAME, nameof(url), url);\n\n\t\tconst relationValues = Is.string(rel)\n\t\t\t? HeaderHelper.normalizeLinkHeaderRelations(rel)\n\t\t\t: ArrayHelper.fromObjectOrArray(rel);\n\n\t\tGuards.arrayValue(HeaderHelper.CLASS_NAME, nameof(rel), relationValues);\n\n\t\tif (url.includes(\">\")) {\n\t\t\tthrow new GeneralError(HeaderHelper.CLASS_NAME, \"invalidLinkHeaderURL\");\n\t\t}\n\n\t\tfor (let i = 0; i < relationValues.length; i++) {\n\t\t\tGuards.stringValue(\n\t\t\t\tHeaderHelper.CLASS_NAME,\n\t\t\t\t`${nameof(rel)}.${i.toString()}`,\n\t\t\t\trelationValues[i]\n\t\t\t);\n\t\t\tif (relationValues[i].includes('\"') \|\| relationValues[i].includes(\" \")) {\n\t\t\t\tthrow new GeneralError(HeaderHelper.CLASS_NAME, \"invalidLinkHeaderRel\");\n\t\t\t}\n\t\t}\n\n\t\tif (Is.objectValue(urlQueryParams)) {\n\t\t\tconst queryParamsString = Object.entries(urlQueryParams)\n\t\t\t\t.map(([key, value]) => `${key}=${encodeURIComponent(value)}`)\n\t\t\t\t.join(\"&\");\n\t\t\tconst queryIndex = url.indexOf(\"?\");\n\t\t\tif (queryIndex === -1) {\n\t\t\t\turl += `?${queryParamsString}`;\n\t\t\t} else if (queryIndex === url.length - 1) {\n\t\t\t\turl += queryParamsString;\n\t\t\t} else {\n\t\t\t\turl += `&${queryParamsString}`;\n\t\t\t}\n\t\t}\n\n\t\treturn `<${url}>; rel=\"${relationValues.join(\" \")}\"${\n\t\t\tparams\n\t\t\t\t? Object.entries(params)\n\t\t\t\t\t\t.map(([key, value]) => `; ${key}=\"${value}\"`)\n\t\t\t\t\t\t.join(\"\")\n\t\t\t\t: \"\"\n\t\t}`;\n\t}\n\n\t/\n\t Parse a quality-weighted comma-separated header into entries.\n\t * @param header The header value or values.\n\t * @param valueValidator Regex to validate the value portion of each entry.\n\t * @returns Entries ordered by quality descending, or undefined if any entry is invalid.\n\t /\n\tpublic static parseWeightedHeader(\n\t\theader: string \| string[] \| undefined,\n\t\tvalueValidator: RegExp\n\t): { value: string; quality: number; params: { [key: string]: string } }[] \| undefined {\n\t\tlet headerValues: string[] = [];\n\n\t\tif (Is.array(header)) {\n\t\t\theaderValues = header.map(v => v.trim()).filter(v => v.length > 0);\n\t\t} else if (Is.stringValue(header)) {\n\t\t\theaderValues = [header.trim()];\n\t\t}\n\n\t\tif (headerValues.length > 0) {\n\t\t\tconst entries = headerValues\n\t\t\t\t.flatMap(v => v.split(\",\"))\n\t\t\t\t.map(s => s.trim())\n\t\t\t\t.filter(s => s.length > 0);\n\n\t\t\tconst parsed: { value: string; quality: number; params: { [key: string]: string } }[] = [];\n\n\t\t\tfor (const entry of entries) {\n\t\t\t\tconst [valuePart, ...paramParts] = entry.split(\";\").map(p => p.trim());\n\n\t\t\t\tif (!valueValidator.test(valuePart)) {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\tlet quality = 1;\n\t\t\t\tconst params: { [key: string]: string } = {};\n\n\t\t\t\tfor (const paramPart of paramParts) {\n\t\t\t\t\tif (paramPart.length > 0) {\n\t\t\t\t\t\tif (paramPart.startsWith(\"q=\") \|\| paramPart.startsWith(\"Q=\")) {\n\t\t\t\t\t\t\tconst qualityMatch = HeaderHelper._QUALITY_REGEX.exec(paramPart);\n\t\t\t\t\t\t\tif (!qualityMatch?.[1]) {\n\t\t\t\t\t\t\t\treturn undefined;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tquality = Number(qualityMatch[1]);\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\tconst eqIndex = paramPart.indexOf(\"=\");\n\t\t\t\t\t\t\tif (eqIndex > 0) {\n\t\t\t\t\t\t\t\tconst key = paramPart.slice(0, eqIndex).trim().toLowerCase();\n\t\t\t\t\t\t\t\tconst val = paramPart.slice(eqIndex + 1).trim();\n\t\t\t\t\t\t\t\tif (key.length > 0) {\n\t\t\t\t\t\t\t\t\tparams[key] = val;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\tparsed.push({ value: valuePart, quality, params });\n\t\t\t}\n\n\t\t\tif (parsed.length > 0) {\n\t\t\t\treturn parsed.sort((a, b) => b.quality - a.quality);\n\t\t\t}\n\t\t}\n\t}\n\n\t/\n\t Does the relation selector match any of the link header relations.\n\t * @param relations The relations from the header.\n\t * @param relation The relation selector to test.\n\t * @returns True if the selector matches any relation.\n\t * @internal\n\t /\n\tprivate static matchesLinkHeaderRelation(\n\t\trelations: (HttpLinkRelType \| string)[],\n\t\trelation: HttpLinkRelType \| string \| RegExp\n\t): boolean {\n\t\tif (Is.string(relation)) {\n\t\t\treturn relations.includes(relation);\n\t\t}\n\n\t\treturn relations.some(relValue => relation.test(relValue));\n\t}\n\n\t/\n\t Normalize a relation string into tokens.\n\t * @param relation The relation string.\n\t * @returns The relation tokens.\n\t * @internal\n\t /\n\tprivate static normalizeLinkHeaderRelations(relation: string): HttpLinkRelType[] {\n\t\treturn relation\n\t\t\t.split(/\\s+/)\n\t\t\t.map(relValue => relValue.trim())\n\t\t\t.filter(relValue => !Is.empty(relValue)) as HttpLinkRelType[];\n\t}\n\n\t/\n\t Get all non-empty values from a header that may be a string or string array.\n\t * @param header The header value (string, string array, or undefined).\n\t * @returns The trimmed non-empty string values.\n\t * @internal\n\t */\n\tprivate static getHeaderValues(header: string \| string[] \| undefined): string[] {\n\t\tlet headerValues: string[] = [];\n\n\t\tif (Is.array(header)) {\n\t\t\theaderValues = header;\n\t\t} else if (Is.stringValue(header)) {\n\t\t\theaderValues = [header];\n\t\t}\n\n\t\treturn headerValues\n\t\t\t.map(headerValue => headerValue.trim())\n\t\t\t.filter(headerValue => headerValue.length > 0);\n\t}\n}\n"]}

package/dist/types/utils/headerHelper.d.ts CHANGED Viewed

@@ -39,6 +39,31 @@ export declare class HeaderHelper {
         language: string;
         quality: number;
     }[] | undefined;
+    /**
+     * Extract parsed media type preferences from the Accept header.
+     * @param headers The HTTP request headers.
+     * @returns The parsed media type preferences ordered by highest quality first, or undefined if missing or invalid.
+     */
+    static extractAccept(headers?: IHttpHeaders): {
+        mimeType: string;
+        quality: number;
+        params?: {
+            [key: string]: string;
+        };
+    }[] | undefined;
+    /**
+     * Parse one or more Accept header values into media type preferences.
+     * @param accept The Accept header value or values.
+     * @returns The parsed media type preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept
+     */
+    static parseAccept(accept: string | string[] | undefined): {
+        mimeType: string;
+        quality: number;
+        params?: {
+            [key: string]: string;
+        };
+    }[] | undefined;
     /**
      * Extract client IP addresses from HTTP request headers.
      * Checks all `X-Forwarded-For` and `X-Real-IP` header values for proxied requests.
@@ -129,4 +154,17 @@ export declare class HeaderHelper {
     } | undefined, rel: HttpLinkRelType | HttpLinkRelType[] | string | string[], params?: {
         [id: string]: string;
     }): string;
+    /**
+     * Parse a quality-weighted comma-separated header into entries.
+     * @param header The header value or values.
+     * @param valueValidator Regex to validate the value portion of each entry.
+     * @returns Entries ordered by quality descending, or undefined if any entry is invalid.
+     */
+    static parseWeightedHeader(header: string | string[] | undefined, valueValidator: RegExp): {
+        value: string;
+        quality: number;
+        params: {
+            [key: string]: string;
+        };
+    }[] | undefined;
 }

package/docs/changelog.md CHANGED Viewed

@@ -1,5 +1,45 @@
 # Changelog
+## [0.9.1-next.6](https://github.com/iotaledger/twin-framework/compare/web-v0.9.1-next.5...web-v0.9.1-next.6) (2026-07-03)
+### Miscellaneous Chores
+* **web:** Synchronize repo versions
+### Dependencies
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.9.1-next.5 to 0.9.1-next.6
+    * @twin.org/crypto bumped from 0.9.1-next.5 to 0.9.1-next.6
+    * @twin.org/nameof bumped from 0.9.1-next.5 to 0.9.1-next.6
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.1-next.5 to 0.9.1-next.6
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.1-next.5 to 0.9.1-next.6
+    * @twin.org/validate-locales bumped from 0.9.1-next.5 to 0.9.1-next.6
+## [0.9.1-next.5](https://github.com/iotaledger/twin-framework/compare/web-v0.9.1-next.4...web-v0.9.1-next.5) (2026-06-29)
+### Features
+* urn and header helper extensions ([#395](https://github.com/iotaledger/twin-framework/issues/395)) ([5976756](https://github.com/iotaledger/twin-framework/commit/5976756886d22e5063671052abc4dfa04ce23a53))
+### Dependencies
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.9.1-next.4 to 0.9.1-next.5
+    * @twin.org/crypto bumped from 0.9.1-next.4 to 0.9.1-next.5
+    * @twin.org/nameof bumped from 0.9.1-next.4 to 0.9.1-next.5
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.1-next.4 to 0.9.1-next.5
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.1-next.4 to 0.9.1-next.5
+    * @twin.org/validate-locales bumped from 0.9.1-next.4 to 0.9.1-next.5
 ## [0.9.1-next.4](https://github.com/iotaledger/twin-framework/compare/web-v0.9.1-next.3...web-v0.9.1-next.4) (2026-06-26)

package/docs/reference/classes/HeaderHelper.md CHANGED Viewed

@@ -110,6 +110,54 @@ The parsed language preferences ordered by highest quality first, or undefined i
 ***
+### extractAccept() {#extractaccept}
+> `static` **extractAccept**(`headers?`): `object`[] \| `undefined`
+Extract parsed media type preferences from the Accept header.
+#### Parameters
+##### headers?
+[`IHttpHeaders`](../interfaces/IHttpHeaders.md)
+The HTTP request headers.
+#### Returns
+`object`[] \| `undefined`
+The parsed media type preferences ordered by highest quality first, or undefined if missing or invalid.
+***
+### parseAccept() {#parseaccept}
+> `static` **parseAccept**(`accept`): `object`[] \| `undefined`
+Parse one or more Accept header values into media type preferences.
+#### Parameters
+##### accept
+`string` \| `string`[] \| `undefined`
+The Accept header value or values.
+#### Returns
+`object`[] \| `undefined`
+The parsed media type preferences ordered by highest quality first, or undefined if missing or if any entry is invalid.
+#### See
+https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept
+***
 ### extractClientIps() {#extractclientips}
 > `static` **extractClientIps**(`headers?`): `string`[]
@@ -438,3 +486,31 @@ GeneralError if the URL or rel are invalid.
 #### See
 https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link
+***
+### parseWeightedHeader() {#parseweightedheader}
+> `static` **parseWeightedHeader**(`header`, `valueValidator`): `object`[] \| `undefined`
+Parse a quality-weighted comma-separated header into entries.
+#### Parameters
+##### header
+`string` \| `string`[] \| `undefined`
+The header value or values.
+##### valueValidator
+`RegExp`
+Regex to validate the value portion of each entry.
+#### Returns
+`object`[] \| `undefined`
+Entries ordered by quality descending, or undefined if any entry is invalid.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/web",
-	"version": "0.9.1-next.4",
+	"version": "0.9.1-next.6",
 	"description": "Classes for use with web operations",
 	"repository": {
 		"type": "git",
@@ -14,9 +14,9 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.9.1-next.4",
-		"@twin.org/crypto": "0.9.1-next.4",
-		"@twin.org/nameof": "0.9.1-next.4",
+		"@twin.org/core": "0.9.1-next.6",
+		"@twin.org/crypto": "0.9.1-next.6",
+		"@twin.org/nameof": "0.9.1-next.6",
 		"jose": "6.2.3"
 	},
 	"main": "./dist/es/index.js",