@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentNegotiationService = void 0;
+const formatter_registry_js_1 = require("./formatter-registry.js");
+const accept_header_parser_js_1 = require("./accept-header-parser.js");
+const index_js_1 = require("./formatters/index.js");
+/**
+ * Service for handling content negotiation.
+ */
+class ContentNegotiationService {
+    constructor(container) {
+        this.enabled = false;
+        this.registry = new formatter_registry_js_1.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 = [
+            index_js_1.JsonFormatter,
+            index_js_1.XmlFormatter,
+            index_js_1.CsvFormatter,
+            index_js_1.YamlFormatter,
+            index_js_1.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 = accept_header_parser_js_1.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 = accept_header_parser_js_1.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 index_js_1.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;
+    }
+}
+exports.ContentNegotiationService = ContentNegotiationService;

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

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormatterRegistry = void 0;
+/**
+ * Registry for managing content formatters with DI support and caching.
+ */
+class FormatterRegistry {
+    constructor(container) {
+        this.formatters = new Map();
+        this.formatterClasses = new Map();
+        this.cacheEnabled = true;
+        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();
+    }
+}
+exports.FormatterRegistry = FormatterRegistry;

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

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsvFormatter = void 0;
+/**
+ * CSV formatter for content negotiation.
+ * Formats data as CSV with configurable options.
+ */
+class CsvFormatter {
+    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;
+    }
+}
+exports.CsvFormatter = CsvFormatter;

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlainTextFormatter = exports.YamlFormatter = exports.CsvFormatter = exports.XmlFormatter = exports.JsonFormatter = void 0;
+/**
+ * Built-in content formatters for ExpressoTS.
+ */
+var json_formatter_js_1 = require("./json-formatter.js");
+Object.defineProperty(exports, "JsonFormatter", { enumerable: true, get: function () { return json_formatter_js_1.JsonFormatter; } });
+var xml_formatter_js_1 = require("./xml-formatter.js");
+Object.defineProperty(exports, "XmlFormatter", { enumerable: true, get: function () { return xml_formatter_js_1.XmlFormatter; } });
+var csv_formatter_js_1 = require("./csv-formatter.js");
+Object.defineProperty(exports, "CsvFormatter", { enumerable: true, get: function () { return csv_formatter_js_1.CsvFormatter; } });
+var yaml_formatter_js_1 = require("./yaml-formatter.js");
+Object.defineProperty(exports, "YamlFormatter", { enumerable: true, get: function () { return yaml_formatter_js_1.YamlFormatter; } });
+var plain_text_formatter_js_1 = require("./plain-text-formatter.js");
+Object.defineProperty(exports, "PlainTextFormatter", { enumerable: true, get: function () { return plain_text_formatter_js_1.PlainTextFormatter; } });

package/lib/cjs/middleware/content-negotiation/formatters/json-formatter.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonFormatter = void 0;
+/**
+ * JSON formatter for content negotiation.
+ * Formats data as JSON with pretty printing support.
+ */
+class JsonFormatter {
+    constructor(prettyPrint = false) {
+        this.prettyPrint = false;
+        this.prettyPrint = prettyPrint;
+    }
+    canFormat(contentType) {
+        return (contentType === "application/json" ||
+            contentType === "application/*" ||
+            contentType === "*/*");
+    }
+    format(data) {
+        if (this.prettyPrint) {
+            return JSON.stringify(data, null, 2);
+        }
+        return JSON.stringify(data);
+    }
+    getContentType() {
+        return "application/json";
+    }
+    getSupportedTypes() {
+        return ["application/json"];
+    }
+    getPriority() {
+        return 1.0; // Highest priority for JSON
+    }
+}
+exports.JsonFormatter = JsonFormatter;

package/lib/cjs/middleware/content-negotiation/formatters/plain-text-formatter.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlainTextFormatter = void 0;
+/**
+ * Plain text formatter for content negotiation.
+ * Formats data as plain text.
+ */
+class PlainTextFormatter {
+    canFormat(contentType) {
+        return (contentType === "text/plain" ||
+            contentType === "text/*" ||
+            contentType === "*/*");
+    }
+    format(data) {
+        if (data === null || data === undefined) {
+            return "";
+        }
+        if (typeof data === "string") {
+            return data;
+        }
+        if (typeof data === "object") {
+            // For objects, create a simple text representation
+            if (Array.isArray(data)) {
+                return data.map((item) => this.format(item)).join("\n");
+            }
+            // For objects, format as key-value pairs
+            const entries = Object.entries(data);
+            return entries
+                .map(([key, value]) => `${key}: ${String(value)}`)
+                .join("\n");
+        }
+        return String(data);
+    }
+    getContentType() {
+        return "text/plain";
+    }
+    getSupportedTypes() {
+        return ["text/plain"];
+    }
+    getPriority() {
+        return 0.5; // Lower priority, used as fallback
+    }
+}
+exports.PlainTextFormatter = PlainTextFormatter;