@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/middleware/content-negotiation/accept-header-parser.js

@@ -0,0 +1,106 @@
+/**
+ * Parser for Accept headers with quality value support (RFC 7231).
+ */
+export class AcceptHeaderParser {
+    /**
+     * Parses an Accept header string into an array of AcceptHeaderEntry objects.
+     * Supports quality values, wildcards, and parameters.
+     * @param acceptHeader - The Accept header value (e.g., "application/json;q=0.9, application/xml;q=0.8")
+     * @returns Array of parsed accept header entries, sorted by quality (highest first)
+     */
+    static parse(acceptHeader) {
+        if (!acceptHeader || acceptHeader.trim() === "") {
+            return [];
+        }
+        const entries = [];
+        const parts = acceptHeader.split(",");
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const entry = this.parseEntry(trimmed);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        // Sort by quality (highest first), then by type specificity
+        return entries.sort((a, b) => {
+            if (b.quality !== a.quality) {
+                return b.quality - a.quality;
+            }
+            // Prefer more specific types (e.g., "application/json" over "application/*")
+            const aSpecificity = a.subtype === "*" ? 0 : a.mainType === "*" ? 0 : 1;
+            const bSpecificity = b.subtype === "*" ? 0 : b.mainType === "*" ? 0 : 1;
+            return bSpecificity - aSpecificity;
+        });
+    }
+    /**
+     * Parses a single Accept header entry.
+     * @param entry - The entry string (e.g., "application/json;q=0.9;version=1.0")
+     * @returns Parsed entry or undefined if invalid
+     */
+    static parseEntry(entry) {
+        const parts = entry.split(";").map((p) => p.trim());
+        if (parts.length === 0)
+            return undefined;
+        const type = parts[0].trim();
+        if (!type)
+            return undefined;
+        // Parse type and subtype
+        const [mainType, subtype] = type.split("/");
+        if (!mainType)
+            return undefined;
+        // Parse parameters
+        const parameters = {};
+        let quality = 1.0;
+        for (let i = 1; i < parts.length; i++) {
+            const param = parts[i];
+            const [key, value] = param.split("=").map((p) => p.trim());
+            if (key === "q" && value) {
+                const qValue = parseFloat(value);
+                if (!isNaN(qValue) && qValue >= 0 && qValue <= 1) {
+                    quality = qValue;
+                }
+            }
+            else if (key && value) {
+                parameters[key] = value;
+            }
+        }
+        return {
+            type,
+            quality,
+            mainType,
+            subtype: subtype || "*",
+            parameters: Object.keys(parameters).length > 0 ? parameters : undefined,
+        };
+    }
+    /**
+     * Finds the best matching content type from Accept header entries.
+     * @param entries - Parsed Accept header entries
+     * @param availableTypes - Array of available content types
+     * @returns Best matching content type, or undefined if no match
+     */
+    static findBestMatch(entries, availableTypes) {
+        for (const entry of entries) {
+            // Exact match
+            if (availableTypes.includes(entry.type)) {
+                return entry.type;
+            }
+            // Partial match (e.g., "application/*" matches "application/json")
+            if (entry.subtype === "*" && entry.mainType) {
+                const match = availableTypes.find((type) => {
+                    const [mainType] = type.split("/");
+                    return mainType === entry.mainType;
+                });
+                if (match) {
+                    return match;
+                }
+            }
+            // Wildcard match (*/*)
+            if (entry.mainType === "*" && availableTypes.length > 0) {
+                return availableTypes[0]; // Return first available
+            }
+        }
+        return undefined;
+    }
+}

package/lib/esm/middleware/content-negotiation/content-negotiation-service.js

@@ -0,0 +1,286 @@
+import { FormatterRegistry } from "./formatter-registry.js";
+import { AcceptHeaderParser } from "./accept-header-parser.js";
+import { JsonFormatter, XmlFormatter, CsvFormatter, YamlFormatter, PlainTextFormatter, } from "./formatters/index.js";
+/**
+ * Service for handling content negotiation.
+ */
+export class ContentNegotiationService {
+    registry;
+    options;
+    enabled = false;
+    constructor(container) {
+        this.registry = new FormatterRegistry(container);
+        this.options = this.getDefaultOptions();
+    }
+    /**
+     * Configures content negotiation with the provided options.
+     */
+    configure(options) {
+        this.options = { ...this.getDefaultOptions(), ...options };
+        this.enabled = true;
+        // Register built-in formatters
+        const builtInFormatters = [
+            JsonFormatter,
+            XmlFormatter,
+            CsvFormatter,
+            YamlFormatter,
+            PlainTextFormatter,
+        ];
+        const formattersToRegister = [
+            ...(this.options.formatters || []),
+            ...builtInFormatters,
+        ];
+        // Register custom formatters
+        if (this.options.customFormatters) {
+            formattersToRegister.push(...this.options.customFormatters);
+        }
+        this.registry.registerAll(formattersToRegister);
+        // Configure registry
+        this.registry.setCacheEnabled(this.options.cacheFormatters);
+        // Preload formatters if specified
+        if (this.options.preload && this.options.preload.length > 0) {
+            for (const contentType of this.options.preload) {
+                this.registry.getFormatter(contentType);
+            }
+        }
+    }
+    /**
+     * Checks if content negotiation is enabled.
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Negotiates the best content type based on the Accept header.
+     * @param req - Express request object
+     * @param availableTypes - Optional array of explicitly available types (from decorators)
+     * @returns Negotiation result or undefined if no match
+     */
+    negotiate(req, availableTypes) {
+        if (!this.enabled) {
+            return undefined;
+        }
+        const acceptHeader = req.headers.accept;
+        const entries = AcceptHeaderParser.parse(acceptHeader);
+        // If no Accept header and no explicit types, use default
+        if (entries.length === 0 && !availableTypes) {
+            return this.getDefaultFormatter();
+        }
+        // Get all available types - if decorator provides types, use those; otherwise use all formatter types
+        let allAvailableTypes;
+        if (availableTypes && availableTypes.length > 0) {
+            // Use decorator-provided types, but verify formatters support them
+            allAvailableTypes = availableTypes;
+        }
+        else {
+            // Use all formatter-supported types
+            allAvailableTypes = this.getAllAvailableTypes();
+        }
+        // Find best match
+        let bestMatch;
+        if (this.options.qualityValueSupport && entries.length > 0) {
+            // Use quality value negotiation
+            bestMatch = this.negotiateWithQuality(entries, allAvailableTypes);
+        }
+        else if (entries.length > 0) {
+            // Simple negotiation without quality values
+            const bestType = AcceptHeaderParser.findBestMatch(entries, allAvailableTypes);
+            if (bestType) {
+                // Try to find formatter - use findFormatter for better matching
+                const formatter = this.registry.findFormatter(bestType) ||
+                    this.registry.getFormatter(bestType);
+                if (formatter) {
+                    bestMatch = {
+                        formatter,
+                        contentType: bestType,
+                        quality: 1.0,
+                    };
+                }
+            }
+        }
+        // Fallback to default if no match
+        if (!bestMatch) {
+            if (this.options.strictMode) {
+                return undefined; // Will return 406
+            }
+            return this.getDefaultFormatter();
+        }
+        return bestMatch;
+    }
+    /**
+     * Formats response data using the negotiated formatter.
+     * @param data - Data to format
+     * @param result - Negotiation result
+     * @returns Formatted data
+     */
+    async formatResponse(data, result) {
+        const formatted = await result.formatter.format(data);
+        return formatted;
+    }
+    /**
+     * Handles response formatting with content negotiation.
+     * @param req - Express request object
+     * @param res - Express response object
+     * @param data - Data to send
+     * @param availableTypes - Optional explicitly available types
+     * @returns True if response was handled, false otherwise
+     */
+    async handleResponse(req, res, data, availableTypes) {
+        if (!this.enabled) {
+            return false;
+        }
+        const result = this.negotiate(req, availableTypes);
+        if (!result) {
+            if (this.options.strictMode) {
+                res.status(406).json({
+                    error: "Not Acceptable",
+                    message: "The requested content type is not supported",
+                });
+                return true;
+            }
+            return false; // Fall back to default behavior
+        }
+        try {
+            const formatted = await this.formatResponse(data, result);
+            res.setHeader("Content-Type", result.contentType);
+            if (formatted instanceof Buffer) {
+                res.send(formatted);
+            }
+            else {
+                res.send(formatted);
+            }
+            return true;
+        }
+        catch (error) {
+            // Silently fall back to default behavior on error
+            return false;
+        }
+    }
+    /**
+     * Negotiates with quality value support.
+     */
+    negotiateWithQuality(entries, availableTypes) {
+        for (const entry of entries) {
+            // Try exact match
+            if (availableTypes.includes(entry.type)) {
+                const formatter = this.registry.findFormatter(entry.type) ||
+                    this.registry.getFormatter(entry.type);
+                if (formatter) {
+                    return {
+                        formatter,
+                        contentType: entry.type,
+                        quality: entry.quality,
+                    };
+                }
+            }
+            // Try partial match
+            if (this.options.negotiatePartial &&
+                entry.subtype === "*" &&
+                entry.mainType) {
+                const match = availableTypes.find((type) => {
+                    const [mainType] = type.split("/");
+                    return mainType === entry.mainType;
+                });
+                if (match) {
+                    const formatter = this.registry.findFormatter(match) ||
+                        this.registry.getFormatter(match);
+                    if (formatter) {
+                        return {
+                            formatter,
+                            contentType: match,
+                            quality: entry.quality,
+                        };
+                    }
+                }
+            }
+            // Try wildcard
+            if (this.options.negotiateWildcards && entry.mainType === "*") {
+                const match = availableTypes[0];
+                if (match) {
+                    const formatter = this.registry.findFormatter(match) ||
+                        this.registry.getFormatter(match);
+                    if (formatter) {
+                        return {
+                            formatter,
+                            contentType: match,
+                            quality: entry.quality,
+                        };
+                    }
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Gets all available content types from registered formatters.
+     */
+    getAllAvailableTypes() {
+        const types = [];
+        const formatters = this.registry.getAllFormatters();
+        for (const formatter of formatters) {
+            types.push(...formatter.getSupportedTypes());
+        }
+        return Array.from(new Set(types));
+    }
+    /**
+     * Gets the default formatter.
+     */
+    getDefaultFormatter() {
+        const formatter = this.registry.getFormatter(this.options.defaultFormat);
+        if (!formatter) {
+            // Fallback to JSON formatter
+            const jsonFormatter = new JsonFormatter();
+            return {
+                formatter: jsonFormatter,
+                contentType: "application/json",
+                quality: 1.0,
+            };
+        }
+        return {
+            formatter,
+            contentType: this.options.defaultFormat,
+            quality: 1.0,
+        };
+    }
+    /**
+     * Gets default options.
+     */
+    getDefaultOptions() {
+        return {
+            defaultFormat: "application/json",
+            formatters: [],
+            customFormatters: [],
+            strictMode: false,
+            fallbackChain: ["application/json", "application/xml", "text/plain"],
+            negotiateWildcards: true,
+            negotiatePartial: true,
+            qualityValueSupport: true,
+            cacheFormatters: true,
+            lazyLoad: true,
+            preload: ["application/json"],
+            formatDefaults: {
+                csv: {
+                    includeHeaders: true,
+                    delimiter: ",",
+                    escape: true,
+                },
+                xml: {
+                    prettyPrint: false,
+                    rootElement: "root",
+                    xmlDeclaration: true,
+                },
+                yaml: {
+                    indent: 2,
+                    quoteStrings: false,
+                    lineWidth: 80,
+                },
+            },
+        };
+    }
+    /**
+     * Gets the formatter registry (for advanced usage).
+     */
+    getRegistry() {
+        return this.registry;
+    }
+}

package/lib/esm/middleware/content-negotiation/formatter-registry.js

@@ -0,0 +1,165 @@
+/**
+ * Registry for managing content formatters with DI support and caching.
+ */
+export class FormatterRegistry {
+    formatters = new Map();
+    formatterClasses = new Map();
+    cacheEnabled = true;
+    container;
+    constructor(container) {
+        this.container = container;
+    }
+    /**
+     * Registers a formatter class.
+     * @param formatterClass - The formatter class constructor
+     */
+    register(formatterClass) {
+        const instance = this.createFormatterInstance(formatterClass);
+        const contentType = instance.getContentType();
+        const supportedTypes = instance.getSupportedTypes();
+        // Register by primary content type
+        this.formatterClasses.set(contentType, formatterClass);
+        // Cache instance if caching is enabled
+        if (this.cacheEnabled) {
+            this.formatters.set(contentType, instance);
+        }
+        // Register all supported types
+        supportedTypes.forEach((type) => {
+            if (!this.formatterClasses.has(type)) {
+                this.formatterClasses.set(type, formatterClass);
+            }
+        });
+    }
+    /**
+     * Registers multiple formatter classes.
+     * @param formatterClasses - Array of formatter class constructors
+     */
+    registerAll(formatterClasses) {
+        formatterClasses.forEach((formatterClass) => {
+            try {
+                this.register(formatterClass);
+            }
+            catch {
+                // Silently skip failed formatter registrations
+            }
+        });
+    }
+    /**
+     * Gets a formatter for the given content type.
+     * @param contentType - The content type to get a formatter for
+     * @returns The formatter instance, or undefined if not found
+     */
+    getFormatter(contentType) {
+        // Try exact match first
+        if (this.cacheEnabled && this.formatters.has(contentType)) {
+            return this.formatters.get(contentType);
+        }
+        // Try class-based lookup
+        const formatterClass = this.formatterClasses.get(contentType);
+        if (formatterClass) {
+            const instance = this.createFormatterInstance(formatterClass);
+            if (this.cacheEnabled) {
+                this.formatters.set(contentType, instance);
+            }
+            return instance;
+        }
+        return undefined;
+    }
+    /**
+     * Finds a formatter that can handle the given content type (supports wildcards).
+     * @param contentType - The content type to find a formatter for
+     * @returns The formatter instance, or undefined if not found
+     */
+    findFormatter(contentType) {
+        // Try exact match
+        const exact = this.getFormatter(contentType);
+        if (exact) {
+            return exact;
+        }
+        // Try partial match (e.g., "application/*" matches "application/json")
+        const [mainType, subtype] = contentType.split("/");
+        if (subtype === "*" && mainType) {
+            // Find first formatter with matching main type
+            for (const [type, formatterClass] of this.formatterClasses.entries()) {
+                const [fmtMainType] = type.split("/");
+                if (fmtMainType === mainType) {
+                    return this.createFormatterInstance(formatterClass);
+                }
+            }
+        }
+        // Try wildcard match (*/*)
+        if (contentType === "*/*") {
+            // Return highest priority formatter
+            let highestPriority = -1;
+            let bestFormatter;
+            for (const formatterClass of this.formatterClasses.values()) {
+                const instance = this.createFormatterInstance(formatterClass);
+                const priority = instance.getPriority?.() ?? 1.0;
+                if (priority > highestPriority) {
+                    highestPriority = priority;
+                    bestFormatter = instance;
+                }
+            }
+            return bestFormatter;
+        }
+        return undefined;
+    }
+    /**
+     * Gets all registered formatters.
+     * @returns Array of formatter instances
+     */
+    getAllFormatters() {
+        const formatters = [];
+        for (const formatterClass of this.formatterClasses.values()) {
+            const instance = this.createFormatterInstance(formatterClass);
+            formatters.push(instance);
+        }
+        return formatters;
+    }
+    /**
+     * Checks if a formatter is registered for the given content type.
+     * @param contentType - The content type to check
+     * @returns True if a formatter is registered
+     */
+    hasFormatter(contentType) {
+        return (this.formatterClasses.has(contentType) ||
+            this.findFormatter(contentType) !== undefined);
+    }
+    /**
+     * Enables or disables formatter caching.
+     * @param enabled - Whether to enable caching
+     */
+    setCacheEnabled(enabled) {
+        this.cacheEnabled = enabled;
+        if (!enabled) {
+            this.formatters.clear();
+        }
+    }
+    /**
+     * Clears the formatter cache.
+     */
+    clearCache() {
+        this.formatters.clear();
+    }
+    /**
+     * Creates a formatter instance, trying DI container first, then direct instantiation.
+     * @param formatterClass - The formatter class constructor
+     * @returns Formatter instance
+     */
+    createFormatterInstance(formatterClass) {
+        // Try to resolve from DI container first
+        if (this.container) {
+            try {
+                const identifier = Symbol.for(formatterClass.name);
+                if (this.container.isBound(identifier)) {
+                    return this.container.get(identifier);
+                }
+            }
+            catch {
+                // Fall through to direct instantiation
+            }
+        }
+        // Direct instantiation
+        return new formatterClass();
+    }
+}

package/lib/esm/middleware/content-negotiation/formatters/csv-formatter.js

@@ -0,0 +1,111 @@
+/**
+ * CSV formatter for content negotiation.
+ * Formats data as CSV with configurable options.
+ */
+export class CsvFormatter {
+    options;
+    constructor(options = {}) {
+        this.options = {
+            includeHeaders: true,
+            delimiter: ",",
+            escape: true,
+            ...options,
+        };
+    }
+    canFormat(contentType) {
+        return (contentType === "text/csv" ||
+            contentType === "application/csv" ||
+            contentType === "text/*" ||
+            contentType === "*/*");
+    }
+    format(data) {
+        if (data === null || data === undefined) {
+            return "";
+        }
+        if (Array.isArray(data)) {
+            return this.formatArray(data);
+        }
+        // Single object
+        return this.formatArray([data]);
+    }
+    getContentType() {
+        return "text/csv";
+    }
+    getSupportedTypes() {
+        return ["text/csv", "application/csv"];
+    }
+    getPriority() {
+        return 0.8;
+    }
+    /**
+     * Formats an array of objects as CSV.
+     */
+    formatArray(data) {
+        if (data.length === 0) {
+            return "";
+        }
+        const rows = data.map((item) => {
+            if (this.options.transform) {
+                return this.options.transform(item);
+            }
+            return item;
+        });
+        // Extract fields
+        const fields = this.options.fields || this.extractFields(rows[0]);
+        const lines = [];
+        // Add headers
+        if (this.options.includeHeaders) {
+            lines.push(this.formatRow(fields));
+        }
+        // Add data rows
+        for (const row of rows) {
+            const values = fields.map((field) => this.getFieldValue(row, field));
+            lines.push(this.formatRow(values));
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Extracts field names from an object.
+     */
+    extractFields(obj) {
+        if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+            return Object.keys(obj);
+        }
+        return [];
+    }
+    /**
+     * Gets a field value from an object.
+     */
+    getFieldValue(obj, field) {
+        if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+            const value = obj[field];
+            if (value === null || value === undefined) {
+                return "";
+            }
+            return String(value);
+        }
+        return "";
+    }
+    /**
+     * Formats a row of values as CSV.
+     */
+    formatRow(values) {
+        const delimiter = this.options.delimiter || ",";
+        if (this.options.escape) {
+            return values.map((value) => this.escapeCsvValue(value)).join(delimiter);
+        }
+        return values.join(delimiter);
+    }
+    /**
+     * Escapes a CSV value.
+     */
+    escapeCsvValue(value) {
+        // If value contains delimiter, newline, or quote, wrap in quotes and escape quotes
+        if (value.includes(this.options.delimiter || ",") ||
+            value.includes("\n") ||
+            value.includes('"')) {
+            return `"${value.replace(/"/g, '""')}"`;
+        }
+        return value;
+    }
+}

package/lib/esm/middleware/content-negotiation/formatters/index.js

@@ -0,0 +1,8 @@
+/**
+ * Built-in content formatters for ExpressoTS.
+ */
+export { JsonFormatter } from "./json-formatter.js";
+export { XmlFormatter } from "./xml-formatter.js";
+export { CsvFormatter } from "./csv-formatter.js";
+export { YamlFormatter } from "./yaml-formatter.js";
+export { PlainTextFormatter } from "./plain-text-formatter.js";