@irvinebroque/http-rfc-utils 0.1.0

package/dist/link.js

@@ -0,0 +1,437 @@
+/**
+ * Link header utilities per RFC 8288.
+ * RFC 8288 §3, §3.1, §3.2, §3.3, §3.4, §6.2.2.
+ * @see https://www.rfc-editor.org/rfc/rfc8288.html
+ */
+import { decodeExtValue } from './ext-value.js';
+import { isEmptyHeader, quoteIfNeeded as quoteIfNeededImpl, unquote as unquoteImpl, } from './header-utils.js';
+/**
+ * Standard link relation types (RFC 8288 Section 6.2.2 + common extensions)
+ */
+// RFC 8288 §6.2.2: Registered relation types.
+// RFC 8594 §6: sunset link relation type.
+// RFC 9264 §6: linkset link relation type.
+// RFC 9727 §7.2: api-catalog link relation type.
+export const LinkRelation = {
+    SELF: 'self',
+    FIRST: 'first',
+    LAST: 'last',
+    NEXT: 'next',
+    PREV: 'prev',
+    PREVIOUS: 'previous', // Alias for prev
+    ALTERNATE: 'alternate',
+    CANONICAL: 'canonical',
+    AUTHOR: 'author',
+    COLLECTION: 'collection',
+    ITEM: 'item',
+    EDIT: 'edit',
+    EDIT_FORM: 'edit-form',
+    CREATE_FORM: 'create-form',
+    SEARCH: 'search',
+    DESCRIBEDBY: 'describedby',
+    SERVICE_DESC: 'service-desc',
+    SERVICE_DOC: 'service-doc',
+    SERVICE_META: 'service-meta',
+    STATUS: 'status',
+    SUNSET: 'sunset', // RFC 8594 §6
+    LINKSET: 'linkset', // RFC 9264 §6
+    API_CATALOG: 'api-catalog', // RFC 9727 §7.2
+};
+/**
+ * Quote a value if needed for Link header attribute.
+ * Values containing special characters must be quoted.
+ *
+ * @param value - The value to potentially quote
+ * @returns Quoted value if needed
+ */
+// RFC 8288 §3.2: Link-param quoting rules.
+export function quoteIfNeeded(value) {
+    return quoteIfNeededImpl(value);
+}
+/**
+ * Unquote a quoted string value, handling escapes.
+ *
+ * @param value - Potentially quoted value
+ * @returns Unquoted value with escapes resolved
+ */
+// RFC 8288 §3.2: Link-param quoted-string unescaping.
+export function unquote(value) {
+    return unquoteImpl(value);
+}
+/**
+ * Format a single link as a Link header value segment.
+ *
+ * Output format: <href>; rel="value"; [other params]
+ *
+ * @param link - Link definition
+ * @returns Formatted link string
+ */
+// RFC 8288 §3.1, §3.2, §3.3, §3.4: Link-value formatting and parameters.
+export function formatLink(link) {
+    const parts = [`<${link.href}>`];
+    // rel is always first and always quoted per convention
+    if (link.rel) {
+        parts.push(`rel="${link.rel}"`);
+    }
+    // Add other parameters in a consistent order
+    // Always quote values for consistency
+    const orderedKeys = ['type', 'title', 'media', 'anchor', 'rev'];
+    for (const key of orderedKeys) {
+        if (key in link && link[key] !== undefined) {
+            const value = link[key];
+            if (typeof value === 'string') {
+                // Always quote values - escape any quotes in the value
+                const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+                parts.push(`${key}="${escaped}"`);
+            }
+        }
+    }
+    // RFC 8288 §3.4.1: hreflang may appear multiple times
+    if (link.hreflang !== undefined) {
+        const hreflangs = Array.isArray(link.hreflang) ? link.hreflang : [link.hreflang];
+        for (const lang of hreflangs) {
+            const escaped = lang.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            parts.push(`hreflang="${escaped}"`);
+        }
+    }
+    // Add any extension attributes (skip titleLang as it's metadata)
+    const skipKeys = new Set(['href', 'rel', 'titleLang', ...orderedKeys, 'hreflang']);
+    for (const [key, value] of Object.entries(link)) {
+        if (skipKeys.has(key)) {
+            continue;
+        }
+        if (value !== undefined) {
+            if (typeof value === 'string') {
+                parts.push(`${key}=${quoteIfNeeded(value)}`);
+            }
+            else if (Array.isArray(value)) {
+                // Multiple values for extension attribute
+                for (const v of value) {
+                    parts.push(`${key}=${quoteIfNeeded(v)}`);
+                }
+            }
+        }
+    }
+    return parts.join('; ');
+}
+/**
+ * Format multiple links as a complete Link header value.
+ * Links are comma-separated.
+ *
+ * @param links - Array of link definitions
+ * @returns Complete Link header value
+ */
+// RFC 8288 §3: Link header field-value formatting.
+export function formatLinkHeader(links) {
+    return links.map(formatLink).join(', ');
+}
+/**
+ * Build Link header from PaginationLinks (backward-compatible).
+ *
+ * @param links - Pagination links object
+ * @returns Link header value
+ */
+// RFC 8288 §3, §3.3: Link header with relation types.
+export function buildLinkHeader(links) {
+    const definitions = [];
+    definitions.push({ href: links.self, rel: 'self' });
+    definitions.push({ href: links.first, rel: 'first' });
+    if (links.prev) {
+        definitions.push({ href: links.prev, rel: 'prev' });
+    }
+    if (links.next) {
+        definitions.push({ href: links.next, rel: 'next' });
+    }
+    definitions.push({ href: links.last, rel: 'last' });
+    return formatLinkHeader(definitions);
+}
+/**
+ * Parse a Link header value into link definitions.
+ *
+ * **CRITICAL IMPLEMENTATION NOTES**:
+ *
+ * 1. Commas INSIDE quoted strings are NOT separators:
+ *    `<url1>; title="Hello, World", <url2>; rel="next"`
+ *    This is TWO links, not three.
+ *
+ * 2. Escaped characters in quoted values:
+ *    `title="Say \"Hello\""`  -> title = Say "Hello"
+ *    `title="Back\\slash"`    -> title = Back\slash
+ *
+ * 3. Multiple values for same attribute (e.g., hreflang):
+ *    `<url>; rel="alternate"; hreflang="en"; hreflang="de"`
+ *    This should work but is rare.
+ *
+ * 4. Parameters without values:
+ *    `<url>; rel="prefetch"; crossorigin`
+ *    crossorigin is a boolean attribute.
+ *
+ * 5. Whitespace around delimiters should be trimmed:
+ *    `<url> ; rel = "next"` is valid
+ *
+ * @param header - Link header value
+ * @returns Array of parsed link definitions
+ */
+// RFC 8288 §3, §3.1, §3.2, §3.3: Link header parsing.
+export function parseLinkHeader(header) {
+    if (isEmptyHeader(header)) {
+        return [];
+    }
+    const results = [];
+    let state = 0 /* State.BETWEEN_LINKS */;
+    let currentLink = {};
+    let currentParamName = '';
+    let currentParamValue = '';
+    let currentUri = '';
+    let escaped = false;
+    const saveParam = () => {
+        const name = currentParamName.trim().toLowerCase();
+        const rawValue = currentParamValue.trim();
+        if (!name) {
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        // Unquote the value
+        const value = rawValue.startsWith('"') ? unquote(rawValue) : (rawValue || '');
+        // RFC 8288 §3.4.1: These params MUST NOT appear more than once (ignore duplicates)
+        const singleUseParams = new Set(['rel', 'type', 'media', 'anchor']);
+        if (singleUseParams.has(name) && currentLink[name] !== undefined) {
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        // RFC 8288 §3.4.1: title* takes precedence over title
+        // title and title* also single-use, but title* wins
+        if (name === 'title*') {
+            if (currentLink['title*'] !== undefined) {
+                // Ignore duplicate title*
+                currentParamName = '';
+                currentParamValue = '';
+                return;
+            }
+            // Decode RFC 8187 ext-value
+            const decoded = decodeExtValue(value);
+            if (decoded) {
+                currentLink.title = decoded.value;
+                currentLink.titleLang = decoded.language;
+                currentLink['title*'] = value; // Store raw for round-trip
+            }
+            else {
+                // Decoding failed, store raw value
+                currentLink['title*'] = value;
+            }
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        if (name === 'title') {
+            // Only use title if title* hasn't been seen
+            if (currentLink['title*'] !== undefined || currentLink.title !== undefined) {
+                currentParamName = '';
+                currentParamValue = '';
+                return;
+            }
+            currentLink.title = value;
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        // RFC 8288 §3.4.1: hreflang may appear multiple times
+        if (name === 'hreflang') {
+            const existing = currentLink.hreflang;
+            if (existing === undefined) {
+                currentLink.hreflang = value;
+            }
+            else if (Array.isArray(existing)) {
+                existing.push(value);
+            }
+            else {
+                currentLink.hreflang = [existing, value];
+            }
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        // RFC 8288 §3.3: rev is deprecated but should be parsed
+        if (name === 'rev') {
+            if (currentLink.rev === undefined) {
+                currentLink.rev = value;
+            }
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        // RFC 8288 §3.4.2: Extension attributes with * suffix
+        // Prefer the *-suffixed version when both are present
+        if (name.endsWith('*')) {
+            const baseName = name.slice(0, -1);
+            const decoded = decodeExtValue(value);
+            if (decoded) {
+                // Store decoded value under base name
+                currentLink[baseName] = decoded.value;
+                currentLink[name] = value; // Store raw for reference
+            }
+            else {
+                currentLink[name] = value;
+            }
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        // Regular parameter - only set if not already set by *-version
+        const starName = `${name}*`;
+        if (currentLink[starName] !== undefined) {
+            // Skip, the *-version takes precedence
+            currentParamName = '';
+            currentParamValue = '';
+            return;
+        }
+        if (currentLink[name] === undefined) {
+            currentLink[name] = value;
+        }
+        currentParamName = '';
+        currentParamValue = '';
+    };
+    const saveLink = () => {
+        if (currentLink.href) {
+            if (!currentLink.rel) {
+                currentLink = {};
+                currentUri = '';
+                return;
+            }
+            const rels = currentLink.rel
+                .split(/\s+/)
+                .map(rel => rel.trim())
+                .filter(Boolean);
+            for (const rel of rels) {
+                results.push({
+                    ...currentLink,
+                    rel,
+                });
+            }
+        }
+        currentLink = {};
+        currentUri = '';
+    };
+    for (let i = 0; i < header.length; i++) {
+        const char = header[i];
+        switch (state) {
+            case 0 /* State.BETWEEN_LINKS */:
+                if (char === '<') {
+                    currentUri = '';
+                    state = 1 /* State.IN_URI */;
+                }
+                // Ignore whitespace and commas between links
+                break;
+            case 1 /* State.IN_URI */:
+                if (char === '>') {
+                    currentLink.href = currentUri.trim();
+                    state = 2 /* State.IN_PARAMS */;
+                }
+                else {
+                    currentUri += char;
+                }
+                break;
+            case 2 /* State.IN_PARAMS */:
+                if (char === ';') {
+                    // Save any pending parameter
+                    saveParam();
+                    state = 3 /* State.IN_PARAM_NAME */;
+                }
+                else if (char === ',') {
+                    // End of this link
+                    saveParam();
+                    saveLink();
+                    state = 0 /* State.BETWEEN_LINKS */;
+                }
+                else if (char === '"') {
+                    // Starting a quoted value directly (shouldn't happen normally)
+                    currentParamValue += char;
+                    state = 5 /* State.IN_QUOTED_VALUE */;
+                }
+                else if (char !== ' ' && char !== '\t') {
+                    // Some character that's part of a param name (unusual)
+                    currentParamName += char;
+                    state = 3 /* State.IN_PARAM_NAME */;
+                }
+                break;
+            case 3 /* State.IN_PARAM_NAME */:
+                if (char === '=') {
+                    state = 4 /* State.IN_PARAM_VALUE */;
+                }
+                else if (char === ';') {
+                    // Boolean parameter with no value
+                    saveParam();
+                    // Stay in IN_PARAM_NAME for next param
+                }
+                else if (char === ',') {
+                    // End of link with boolean param
+                    saveParam();
+                    saveLink();
+                    state = 0 /* State.BETWEEN_LINKS */;
+                }
+                else if (char !== ' ' && char !== '\t') {
+                    currentParamName += char;
+                }
+                break;
+            case 4 /* State.IN_PARAM_VALUE */:
+                if (char === '"') {
+                    currentParamValue += char;
+                    state = 5 /* State.IN_QUOTED_VALUE */;
+                }
+                else if (char === ';') {
+                    saveParam();
+                    state = 3 /* State.IN_PARAM_NAME */;
+                }
+                else if (char === ',') {
+                    saveParam();
+                    saveLink();
+                    state = 0 /* State.BETWEEN_LINKS */;
+                }
+                else if (char !== ' ' && char !== '\t' || currentParamValue.length > 0) {
+                    // Only add non-whitespace, or whitespace if we've started the value
+                    // But actually, we should trim, so skip leading whitespace
+                    if (char !== ' ' && char !== '\t') {
+                        currentParamValue += char;
+                    }
+                    else if (currentParamValue.length > 0 && !currentParamValue.startsWith('"')) {
+                        // For unquoted values, stop at whitespace
+                        // This handles: rel = "next" where space before quote
+                        // Don't add whitespace, just continue
+                    }
+                }
+                break;
+            case 5 /* State.IN_QUOTED_VALUE */:
+                if (escaped) {
+                    currentParamValue += char;
+                    escaped = false;
+                }
+                else if (char === '\\') {
+                    currentParamValue += char;
+                    escaped = true;
+                }
+                else if (char === '"') {
+                    currentParamValue += char;
+                    // End of quoted value - go back to param processing
+                    state = 4 /* State.IN_PARAM_VALUE */;
+                }
+                else {
+                    currentParamValue += char;
+                }
+                break;
+        }
+    }
+    // Handle end of string
+    if (state === 3 /* State.IN_PARAM_NAME */ || state === 4 /* State.IN_PARAM_VALUE */ || state === 2 /* State.IN_PARAMS */) {
+        saveParam();
+        saveLink();
+    }
+    else if (state === 5 /* State.IN_QUOTED_VALUE */) {
+        // Unclosed quote - save what we have anyway
+        saveParam();
+        saveLink();
+    }
+    return results;
+}
+//# sourceMappingURL=link.js.map

package/dist/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../src/link.ts"],"names":[],"mappings":"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"}

package/dist/linkset.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Linkset utilities per RFC 9264.
+ * API catalog support per RFC 9727.
+ * RFC 9264 §4.1, §4.2, §5, §6.
+ * RFC 9727 §§2-4, §7.
+ * @see https://www.rfc-editor.org/rfc/rfc9264.html
+ * @see https://www.rfc-editor.org/rfc/rfc9727.html
+ */
+import type { LinkDefinition, Linkset, LinksetJsonOptions, ApiCatalog, ApiCatalogOptions } from './types.js';
+export declare const LINKSET_MEDIA_TYPE = "application/linkset+json";
+export declare const API_CATALOG_PROFILE = "https://www.rfc-editor.org/info/rfc9727";
+export declare const API_CATALOG_PATH = "/.well-known/api-catalog";
+/**
+ * Parse an application/linkset document into link definitions.
+ * RFC 9264 §4.1: Same as HTTP Link header format but allows newlines as separators.
+ *
+ * @param document - The linkset document content
+ * @returns Array of parsed link definitions, or null if parsing fails
+ */
+export declare function parseLinkset(document: string): LinkDefinition[] | null;
+/**
+ * Parse an application/linkset+json document.
+ * RFC 9264 §4.2: JSON format for link sets.
+ *
+ * @param json - The JSON string or object
+ * @returns Parsed Linkset object, or null if invalid
+ */
+export declare function parseLinksetJson(json: string | object): Linkset | null;
+/**
+ * Format link definitions as an application/linkset document.
+ * RFC 9264 §4.1: Uses Link header format with newlines for readability.
+ *
+ * @param links - Array of link definitions
+ * @returns Formatted linkset document
+ */
+export declare function formatLinkset(links: LinkDefinition[]): string;
+/**
+ * Format link definitions as an application/linkset+json object.
+ * RFC 9264 §4.2: JSON format for link sets.
+ *
+ * @param links - Array of link definitions
+ * @param options - Formatting options
+ * @returns Linkset JSON object
+ */
+export declare function formatLinksetJson(links: LinkDefinition[], options?: LinksetJsonOptions): Linkset;
+/**
+ * Convert an application/linkset document to JSON format.
+ * RFC 9264 §4.1, §4.2: Format conversion.
+ *
+ * @param document - The linkset document
+ * @returns Linkset JSON object, or null if parsing fails
+ */
+export declare function linksetToJson(document: string): Linkset | null;
+/**
+ * Convert a JSON linkset to application/linkset format.
+ * RFC 9264 §4.1, §4.2: Format conversion.
+ *
+ * @param linkset - The Linkset object
+ * @returns Formatted linkset document
+ */
+export declare function jsonToLinkset(linkset: Linkset): string;
+/**
+ * Type guard to validate a Linkset object.
+ * RFC 9264 §4.2.1: linkset must be the sole top-level member.
+ *
+ * @param obj - Object to validate
+ * @returns True if valid Linkset
+ */
+export declare function isValidLinkset(obj: unknown): obj is Linkset;
+/**
+ * Create an API catalog document.
+ * RFC 9727 §4: API catalog document structure.
+ *
+ * @param options - API catalog configuration
+ * @returns API catalog Linkset document
+ */
+export declare function createApiCatalog(options: ApiCatalogOptions): ApiCatalog;
+/**
+ * Parse an API catalog document.
+ * RFC 9727 §4: Validate and parse API catalog structure.
+ *
+ * @param json - JSON string or object
+ * @returns Parsed API catalog, or null if invalid
+ */
+export declare function parseApiCatalog(json: string | object): ApiCatalog | null;
+/**
+ * Check if a Linkset is an API catalog (has the RFC 9727 profile).
+ * RFC 9727 §4.2, §7.3: Profile URI indicates api-catalog semantics.
+ *
+ * @param linkset - Linkset to check
+ * @returns True if the linkset has the api-catalog profile
+ */
+export declare function isApiCatalog(linkset: Linkset | ApiCatalog): boolean;
+/**
+ * Convert a Linkset to an array of LinkDefinitions.
+ * Useful for converting API catalog entries to Link header format.
+ *
+ * @param linkset - Linkset to convert
+ * @returns Array of LinkDefinition objects
+ */
+export declare function linksetToLinks(linkset: Linkset): LinkDefinition[];
+/**
+ * Convert an array of LinkDefinitions to a Linkset.
+ * Useful for creating API catalogs from Link header entries.
+ *
+ * @param links - Array of link definitions
+ * @param anchor - Default anchor URI for links without one
+ * @returns Linkset object
+ */
+export declare function linksToLinkset(links: LinkDefinition[], anchor?: string): Linkset;
+//# sourceMappingURL=linkset.d.ts.map

package/dist/linkset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linkset.d.ts","sourceRoot":"","sources":["../src/linkset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACR,cAAc,EACd,OAAO,EAGP,kBAAkB,EAElB,UAAU,EACV,iBAAiB,EAGpB,MAAM,YAAY,CAAC;AAIpB,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAG7D,eAAO,MAAM,mBAAmB,4CAA4C,CAAC;AAG7E,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAE3D;;;;;;GAMG;AAEH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,GAAG,IAAI,CAUtE;AA0ED;;;;;;GAMG;AAEH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAkBtE;AAED;;;;;;GAMG;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM,CAO7D;AAED;;;;;;;GAOG;AAEH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE,kBAAuB,GACjC,OAAO,CAsDT;AA0CD;;;;;;GAMG;AAEH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAO9D;AAED;;;;;;GAMG;AAEH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAGtD;AAwFD;;;;;;GAMG;AAEH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CA0D3D;AAMD;;;;;;GAMG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAgEvE;AAED;;;;;;GAMG;AAEH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CAaxE;AAED;;;;;;GAMG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,CAKnE;AAED;;;;;;GAMG;AAEH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,EAAE,CAEjE;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAQhF"}