@terreno/api 0.0.1

package/dist/openApiBuilder.js

@@ -0,0 +1,424 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiMiddlewareBuilder = void 0;
+exports.createOpenApiBuilder = createOpenApiBuilder;
+/**
+ * OpenAPI Middleware Builder
+ *
+ * This module provides a fluent builder pattern for constructing OpenAPI middleware
+ * for Express routes that don't directly map to Mongoose models. It allows you to
+ * define custom API documentation with full control over request/response schemas.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import {createOpenApiBuilder} from "./openApiBuilder";
+ *
+ * // Create middleware with custom documentation
+ * const middleware = createOpenApiBuilder(options)
+ *   .withTags(["users"])
+ *   .withSummary("Get user statistics")
+ *   .withDescription("Returns aggregated statistics for the current user")
+ *   .withQueryParameter("period", {type: "string"}, {
+ *     description: "Time period for statistics",
+ *     required: false,
+ *   })
+ *   .withResponse<{count: number; average: number}>(200, {
+ *     count: {type: "number", description: "Total count"},
+ *     average: {type: "number", description: "Average value"},
+ *   })
+ *   .build();
+ *
+ * router.get("/stats", middleware, statsHandler);
+ * ```
+ */
+var merge_1 = __importDefault(require("lodash/merge"));
+var logger_1 = require("./logger");
+var openApi_1 = require("./openApi");
+/**
+ * A fluent builder for constructing OpenAPI middleware.
+ *
+ * This class provides a chainable API for defining OpenAPI documentation
+ * for Express routes. It supports defining tags, summaries, descriptions,
+ * request bodies, responses, and parameters.
+ *
+ * The builder pattern allows for flexible, readable configuration that
+ * produces middleware compatible with the express-openapi-validator library.
+ *
+ * @example
+ * ```typescript
+ * const middleware = new OpenApiMiddlewareBuilder(options)
+ *   .withTags(["users"])
+ *   .withSummary("Create a new user")
+ *   .withRequestBody<{name: string; email: string}>({
+ *     name: {type: "string", required: true},
+ *     email: {type: "string", format: "email", required: true},
+ *   })
+ *   .withResponse<{id: string; name: string}>(201, {
+ *     id: {type: "string"},
+ *     name: {type: "string"},
+ *   })
+ *   .build();
+ * ```
+ */
+var OpenApiMiddlewareBuilder = /** @class */ (function () {
+    /**
+     * Creates a new OpenApiMiddlewareBuilder instance.
+     *
+     * @param options - Router options containing the OpenAPI path configuration
+     */
+    function OpenApiMiddlewareBuilder(options) {
+        this.options = options;
+        this.config = {
+            responses: {},
+        };
+    }
+    /**
+     * Sets the tags for the OpenAPI operation.
+     *
+     * Tags are used to group operations in the API documentation.
+     *
+     * @param tags - Array of tag names
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withTags(["users", "authentication"]);
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withTags = function (tags) {
+        this.config.tags = tags;
+        return this;
+    };
+    /**
+     * Sets the summary for the OpenAPI operation.
+     *
+     * The summary is a brief description shown in API documentation listings.
+     *
+     * @param summary - Short description of the operation
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withSummary("Get user by ID");
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withSummary = function (summary) {
+        this.config.summary = summary;
+        return this;
+    };
+    /**
+     * Sets the description for the OpenAPI operation.
+     *
+     * The description provides detailed information about the operation,
+     * including usage notes, examples, and caveats.
+     *
+     * @param description - Detailed description of the operation
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withDescription("Retrieves a user by their unique identifier. Returns 404 if not found.");
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withDescription = function (description) {
+        this.config.description = description;
+        return this;
+    };
+    /**
+     * Sets the request body schema for the OpenAPI operation.
+     *
+     * Properties marked with `required: true` will be added to the schema's
+     * required array automatically.
+     *
+     * @typeParam T - Type representing the request body structure
+     * @param schema - Object mapping property names to their OpenAPI schema definitions
+     * @param options - Optional configuration for the request body
+     * @param options.required - Whether the request body itself is required (default: true)
+     * @param options.mediaType - Media type for the request body (default: "application/json")
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withRequestBody<{name: string; age: number}>({
+     *   name: {type: "string", description: "User name", required: true},
+     *   age: {type: "number", description: "User age"},
+     * });
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withRequestBody = function (schema, options) {
+        var _c;
+        var _d, _e;
+        var required = Object.entries(schema)
+            .filter(function (_c) {
+            var _d = __read(_c, 2), _ = _d[0], prop = _d[1];
+            return prop.required;
+        })
+            .map(function (_c) {
+            var _d = __read(_c, 2), key = _d[0], _ = _d[1];
+            return key;
+        });
+        this.config.requestBody = {
+            content: (_c = {},
+                _c[(_d = options === null || options === void 0 ? void 0 : options.mediaType) !== null && _d !== void 0 ? _d : "application/json"] = {
+                    schema: {
+                        properties: schema,
+                        required: required.length > 0 ? required : undefined,
+                        type: "object",
+                    },
+                },
+                _c),
+            required: (_e = options === null || options === void 0 ? void 0 : options.required) !== null && _e !== void 0 ? _e : true,
+        };
+        return this;
+    };
+    /**
+     * Adds a response definition to the OpenAPI operation.
+     *
+     * Can accept either an object schema or a simple string description
+     * for responses without a body (e.g., 204 No Content).
+     *
+     * @typeParam T - Type representing the response body structure
+     * @param statusCode - HTTP status code for this response
+     * @param schema - Either an object schema or a description string
+     * @param options - Optional configuration for the response
+     * @param options.description - Description of the response (default: "Success")
+     * @param options.mediaType - Media type for the response (default: "application/json")
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Response with body
+     * builder.withResponse<{id: string}>(200, {
+     *   id: {type: "string", description: "Created resource ID"},
+     * }, {description: "Resource created successfully"});
+     *
+     * // Response without body
+     * builder.withResponse(204, "No content");
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withResponse = function (statusCode, schema, options) {
+        var _c;
+        var _d, _e;
+        if (typeof schema === "string") {
+            this.config.responses[statusCode] = {
+                description: schema,
+            };
+        }
+        else {
+            this.config.responses[statusCode] = {
+                content: (_c = {},
+                    _c[(_d = options === null || options === void 0 ? void 0 : options.mediaType) !== null && _d !== void 0 ? _d : "application/json"] = {
+                        schema: {
+                            properties: schema,
+                            type: "object",
+                        },
+                    },
+                    _c),
+                description: (_e = options === null || options === void 0 ? void 0 : options.description) !== null && _e !== void 0 ? _e : "Success",
+            };
+        }
+        return this;
+    };
+    /**
+     * Adds an array response definition to the OpenAPI operation.
+     *
+     * Use this method when the response is an array of objects rather
+     * than a single object.
+     *
+     * @typeParam T - Type representing the structure of each array item
+     * @param statusCode - HTTP status code for this response
+     * @param itemSchema - Schema for each item in the response array
+     * @param options - Optional configuration for the response
+     * @param options.description - Description of the response (default: "Success")
+     * @param options.mediaType - Media type for the response (default: "application/json")
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withArrayResponse<{id: string; name: string}>(200, {
+     *   id: {type: "string"},
+     *   name: {type: "string"},
+     * }, {description: "List of users"});
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withArrayResponse = function (statusCode, itemSchema, options) {
+        var _c;
+        var _d, _e;
+        this.config.responses[statusCode] = {
+            content: (_c = {},
+                _c[(_d = options === null || options === void 0 ? void 0 : options.mediaType) !== null && _d !== void 0 ? _d : "application/json"] = {
+                    schema: {
+                        items: {
+                            properties: itemSchema,
+                            type: "object",
+                        },
+                        type: "array",
+                    },
+                },
+                _c),
+            description: (_e = options === null || options === void 0 ? void 0 : options.description) !== null && _e !== void 0 ? _e : "Success",
+        };
+        return this;
+    };
+    /**
+     * Adds a query parameter to the OpenAPI operation.
+     *
+     * Query parameters are passed in the URL query string (e.g., `?limit=10`).
+     *
+     * @param name - Name of the query parameter
+     * @param schema - Schema defining the parameter's type and format
+     * @param options - Optional configuration for the parameter
+     * @param options.required - Whether the parameter is required (default: false)
+     * @param options.description - Human-readable description of the parameter
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withQueryParameter("limit", {type: "number"}, {
+     *   required: false,
+     *   description: "Maximum number of results to return",
+     * });
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withQueryParameter = function (name, schema, options) {
+        var _c;
+        if (!this.config.parameters) {
+            this.config.parameters = [];
+        }
+        this.config.parameters.push({
+            description: options === null || options === void 0 ? void 0 : options.description,
+            in: "query",
+            name: name,
+            required: (_c = options === null || options === void 0 ? void 0 : options.required) !== null && _c !== void 0 ? _c : false,
+            schema: schema,
+        });
+        return this;
+    };
+    /**
+     * Adds a path parameter to the OpenAPI operation.
+     *
+     * Path parameters are embedded in the URL path (e.g., `/users/:id`).
+     * Path parameters are always required per OpenAPI specification.
+     *
+     * @param name - Name of the path parameter (must match the route parameter)
+     * @param schema - Schema defining the parameter's type and format
+     * @param options - Optional configuration for the parameter
+     * @param options.description - Human-readable description of the parameter
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withPathParameter("id", {type: "string", format: "uuid"}, {
+     *   description: "Unique identifier of the user",
+     * });
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withPathParameter = function (name, schema, options) {
+        if (!this.config.parameters) {
+            this.config.parameters = [];
+        }
+        this.config.parameters.push({
+            description: options === null || options === void 0 ? void 0 : options.description,
+            in: "path",
+            name: name,
+            required: true,
+            schema: schema,
+        });
+        return this;
+    };
+    /**
+     * Builds and returns the OpenAPI middleware.
+     *
+     * This method finalizes the configuration and returns Express middleware
+     * that integrates with the OpenAPI documentation system. If no OpenAPI
+     * path is configured in options, returns a no-op middleware.
+     *
+     * Default error responses (400, 401, 403, 404, 405) are automatically
+     * merged with the configured responses.
+     *
+     * @returns Express middleware function for OpenAPI documentation
+     *
+     * @example
+     * ```typescript
+     * const middleware = builder
+     *   .withTags(["users"])
+     *   .withResponse(200, {id: {type: "string"}})
+     *   .build();
+     *
+     * router.get("/users/:id", middleware, getUserHandler);
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.build = function () {
+        var _c, _d, _e;
+        var noop = function (_a, _b, next) { return next(); };
+        if (!((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path)) {
+            logger_1.logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
+            return noop;
+        }
+        return this.options.openApi.path((0, merge_1.default)(__assign(__assign({}, this.config), { responses: __assign(__assign({}, this.config.responses), openApi_1.defaultOpenApiErrorResponses) }), (_e = (_d = this.options.openApiOverwrite) === null || _d === void 0 ? void 0 : _d.get) !== null && _e !== void 0 ? _e : {}));
+    };
+    return OpenApiMiddlewareBuilder;
+}());
+exports.OpenApiMiddlewareBuilder = OpenApiMiddlewareBuilder;
+/**
+ * Creates a new OpenAPI middleware builder.
+ *
+ * This is the recommended entry point for creating custom OpenAPI middleware.
+ * It returns a fluent builder that allows you to chain configuration methods.
+ *
+ * @param options - Router options containing the OpenAPI configuration
+ * @returns A new OpenApiMiddlewareBuilder instance
+ *
+ * @example
+ * ```typescript
+ * import {createOpenApiBuilder} from "./openApiBuilder";
+ *
+ * const statsMiddleware = createOpenApiBuilder(options)
+ *   .withTags(["analytics"])
+ *   .withSummary("Get usage statistics")
+ *   .withQueryParameter("startDate", {type: "string", format: "date"})
+ *   .withQueryParameter("endDate", {type: "string", format: "date"})
+ *   .withResponse<{totalUsers: number; activeUsers: number}>(200, {
+ *     totalUsers: {type: "number", description: "Total registered users"},
+ *     activeUsers: {type: "number", description: "Users active in period"},
+ *   })
+ *   .build();
+ *
+ * router.get("/analytics/stats", statsMiddleware, getStatsHandler);
+ * ```
+ */
+function createOpenApiBuilder(options) {
+    return new OpenApiMiddlewareBuilder(options);
+}

package/dist/openApiBuilder.test.d.ts

@@ -0,0 +1 @@
+export {};