@terreno/api 0.0.18 → 0.1.0

package/dist/auth.js

@@ -377,7 +377,9 @@ function addAuthRoutes(app, userModel, authOptions) {
                                 logger_1.logger.warn("Invalid login: ".concat(info));
                                 return [2 /*return*/, res.status(401).json({ message: info === null || info === void 0 ? void 0 : info.message })];
                             }
-                            logger_1.logger.info("User logged in: ".concat(user._id, ", type: ").concat(user.type || "N/A"));
+                            if (process.env.NODE_ENV !== "test") {
+                                logger_1.logger.info("User logged in: ".concat(user._id, ", type: ").concat(user.type || "N/A"));
+                            }
                             return [4 /*yield*/, (0, exports.generateTokens)(user, authOptions)];
                         case 1:
                             tokens = _a.sent();

package/dist/errors.js

@@ -125,21 +125,24 @@ exports.APIError = APIError;
 // model.
 function errorsPlugin(schema) {
     var errorSchema = new mongoose_1.Schema({
-        code: String,
-        detail: String,
-        id: String,
+        code: { description: "Application-specific error code", type: String },
+        detail: { description: "Human-readable explanation of the error", type: String },
+        id: { description: "Unique identifier for this error occurrence", type: String },
         links: {
-            about: String,
-            type: String,
+            about: { description: "Link to documentation about this error", type: String },
+            type: { description: "Link describing the error type", type: String },
         },
-        meta: mongoose_1.Schema.Types.Mixed,
+        meta: { description: "Non-standard meta information about the error", type: mongoose_1.Schema.Types.Mixed },
         source: {
-            header: String,
-            parameter: String,
-            pointer: String,
+            header: { description: "HTTP header that caused the error", type: String },
+            parameter: { description: "Query parameter that caused the error", type: String },
+            pointer: {
+                description: "JSON pointer to the request field that caused the error",
+                type: String,
+            },
         },
-        status: Number,
-        title: { required: true, type: String },
+        status: { description: "HTTP status code for this error", type: Number },
+        title: { description: "Short summary of the error", required: true, type: String },
     });
     schema.add({ apiErrors: errorSchema });
 }

package/dist/example.js

@@ -65,19 +65,19 @@ mongoose_1.default
     logger_1.logger.error("Error connecting to mongo ".concat(err));
 });
 var userSchema = new mongoose_1.Schema({
-    admin: { default: false, type: Boolean },
-    username: String,
+    admin: { default: false, description: "Whether the user has admin privileges", type: Boolean },
+    username: { description: "The user's username", type: String },
 });
 userSchema.plugin(passport_local_mongoose_1.default, { usernameField: "email" });
 userSchema.plugin(plugins_1.createdUpdatedPlugin);
 userSchema.plugin(plugins_1.baseUserPlugin);
 var UserModel = (0, mongoose_1.model)("User", userSchema);
 var schema = new mongoose_1.Schema({
-    calories: Number,
-    created: Date,
-    hidden: { default: false, type: Boolean },
-    name: String,
-    ownerId: { ref: "User", type: "ObjectId" },
+    calories: { description: "Number of calories in the food", type: Number },
+    created: { description: "When this food was created", type: Date },
+    hidden: { default: false, description: "Whether this food is hidden from listings", type: Boolean },
+    name: { description: "The name of the food", type: String },
+    ownerId: { description: "The user who owns this food entry", ref: "User", type: "ObjectId" },
 });
 var FoodModel = (0, mongoose_1.model)("Food", schema);
 function getBaseServer() {

package/dist/githubAuth.test.js

@@ -82,9 +82,9 @@ var logger_1 = require("./logger");
 var plugins_1 = require("./plugins");
 // Create schema for GitHub-enabled user
 var testUserSchema = new mongoose_1.Schema({
-    admin: { default: false, type: Boolean },
-    name: String,
-    username: String,
+    admin: { default: false, description: "Whether the user has admin privileges", type: Boolean },
+    name: { description: "The user's display name", type: String },
+    username: { description: "The user's username", type: String },
 });
 testUserSchema.plugin(passport_local_mongoose_1.default, {
     attemptsField: "attempts",

package/dist/index.d.ts

@@ -8,8 +8,10 @@ export * from "./middleware";
 export * from "./notifiers";
 export * from "./openApiBuilder";
 export * from "./openApiEtag";
+export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./terrenoPlugin";
 export * from "./transformers";
 export * from "./utils";

package/dist/index.js

@@ -24,8 +24,10 @@ __exportStar(require("./middleware"), exports);
 __exportStar(require("./notifiers"), exports);
 __exportStar(require("./openApiBuilder"), exports);
 __exportStar(require("./openApiEtag"), exports);
+__exportStar(require("./openApiValidator"), exports);
 __exportStar(require("./permissions"), exports);
 __exportStar(require("./plugins"), exports);
 __exportStar(require("./populate"), exports);
+__exportStar(require("./terrenoPlugin"), exports);
 __exportStar(require("./transformers"), exports);
 __exportStar(require("./utils"), exports);

package/dist/openApi.test.js

@@ -273,13 +273,13 @@ function addRoutes(router, options) {
                     // Ensure that a Number query field supports gt/gte/lt/lte and just a Number
                     (0, bun_test_1.expect)(foodQuery.schema).toEqual({
                         oneOf: [
-                            { type: "number" },
+                            { description: "Number of calories in the food", type: "number" },
                             {
                                 properties: {
-                                    $gt: { type: "number" },
-                                    $gte: { type: "number" },
-                                    $lt: { type: "number" },
-                                    $lte: { type: "number" },
+                                    $gt: { description: "Number of calories in the food", type: "number" },
+                                    $gte: { description: "Number of calories in the food", type: "number" },
+                                    $lt: { description: "Number of calories in the food", type: "number" },
+                                    $lte: { description: "Number of calories in the food", type: "number" },
                                 },
                                 type: "object",
                             },
@@ -393,6 +393,7 @@ function addRoutesPopulate(router, options) {
                                 type: "string",
                             },
                             name: {
+                                description: "The user's display name",
                                 type: "string",
                             },
                         },
@@ -406,12 +407,14 @@ function addRoutesPopulate(router, options) {
                         type: "array",
                     });
                     (0, bun_test_1.expect)(properties.likesIds).toEqual({
+                        description: "User likes for this food",
                         items: {
                             properties: {
                                 _id: {
                                     type: "string",
                                 },
                                 likes: {
+                                    description: "Whether the user liked the item",
                                     type: "boolean",
                                 },
                                 userId: {

package/dist/openApiBuilder.d.ts

@@ -153,6 +153,20 @@ export type OpenApiResponse = {
         };
     };
 };
+/**
+ * Result from building OpenAPI middleware with schemas exposed.
+ * Useful when you want to use the schemas with asyncHandler's validation.
+ */
+export interface OpenApiBuildResult {
+    /** The OpenAPI documentation middleware */
+    middleware: any;
+    /** Request body schema if defined */
+    bodySchema?: Record<string, OpenApiSchemaProperty>;
+    /** Query parameter schemas if defined */
+    querySchema?: Record<string, OpenApiSchemaProperty>;
+    /** Whether validation was enabled on this builder */
+    validationEnabled: boolean;
+}
 /**
  * A fluent builder for constructing OpenAPI middleware.
  *
@@ -184,6 +198,12 @@ export declare class OpenApiMiddlewareBuilder {
     private options;
     /** Accumulated OpenAPI configuration from builder methods */
     private config;
+    /** Validation configuration */
+    private validationConfig;
+    /** Store the raw request body schema for validation */
+    private requestBodySchema?;
+    /** Store the raw query parameter schemas for validation */
+    private queryParamSchemas;
     /**
      * Creates a new OpenApiMiddlewareBuilder instance.
      *
@@ -365,6 +385,51 @@ export declare class OpenApiMiddlewareBuilder {
     withPathParameter(name: string, schema: OpenApiSchemaProperty, options?: {
         description?: string;
     }): this;
+    /**
+     * Enables runtime validation for this route.
+     *
+     * When enabled, the built middleware will validate incoming requests
+     * against the documented schema before the handler runs.
+     *
+     * @param options - Optional configuration for validation
+     * @param options.body - Enable body validation (default: true if request body is defined)
+     * @param options.query - Enable query parameter validation (default: true if query params are defined)
+     * @param options.enabled - Override the global validation enabled setting
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .withValidation() // Enable validation
+     *   .build();
+     * ```
+     */
+    withValidation(options?: {
+        body?: boolean;
+        query?: boolean;
+        enabled?: boolean;
+    }): this;
+    /**
+     * Builds and returns the OpenAPI middleware along with schemas.
+     *
+     * This method is useful when you want to use asyncHandler's integrated
+     * validation instead of separate validation middleware.
+     *
+     * @returns Object containing middleware and schemas
+     *
+     * @example
+     * ```typescript
+     * const {middleware, bodySchema} = createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .buildWithSchemas();
+     *
+     * router.post("/users", middleware, asyncHandler(async (req, res) => {
+     *   // handler code
+     * }, {bodySchema, validate: true}));
+     * ```
+     */
+    buildWithSchemas(): OpenApiBuildResult;
     /**
      * Builds and returns the OpenAPI middleware.
      *
@@ -372,10 +437,13 @@ export declare class OpenApiMiddlewareBuilder {
      * that integrates with the OpenAPI documentation system. If no OpenAPI
      * path is configured in options, returns a no-op middleware.
      *
+     * If validation was enabled via `withValidation()`, returns an array
+     * of middleware: [openApiDocMiddleware, validationMiddleware].
+     *
      * Default error responses (400, 401, 403, 404, 405) are automatically
      * merged with the configured responses.
      *
-     * @returns Express middleware function for OpenAPI documentation
+     * @returns Express middleware function(s) for OpenAPI documentation and optional validation
      *
      * @example
      * ```typescript

package/dist/openApiBuilder.js

@@ -66,6 +66,7 @@ exports.createOpenApiBuilder = createOpenApiBuilder;
 var merge_1 = __importDefault(require("lodash/merge"));
 var logger_1 = require("./logger");
 var openApi_1 = require("./openApi");
+var openApiValidator_1 = require("./openApiValidator");
 /**
  * A fluent builder for constructing OpenAPI middleware.
  *
@@ -99,10 +100,13 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * @param options - Router options containing the OpenAPI path configuration
      */
     function OpenApiMiddlewareBuilder(options) {
+        /** Store the raw query parameter schemas for validation */
+        this.queryParamSchemas = {};
         this.options = options;
         this.config = {
             responses: {},
         };
+        this.validationConfig = {};
     }
     /**
      * Sets the tags for the OpenAPI operation.
@@ -201,6 +205,8 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
                 _c),
             required: (_e = options === null || options === void 0 ? void 0 : options.required) !== null && _e !== void 0 ? _e : true,
         };
+        // Store the schema for validation
+        this.requestBodySchema = schema;
         return this;
     };
     /**
@@ -324,6 +330,8 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
             required: (_c = options === null || options === void 0 ? void 0 : options.required) !== null && _c !== void 0 ? _c : false,
             schema: schema,
         });
+        // Store for validation
+        this.queryParamSchemas[name] = __assign(__assign({}, schema), { required: options === null || options === void 0 ? void 0 : options.required });
         return this;
     };
     /**
@@ -358,6 +366,74 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
         });
         return this;
     };
+    /**
+     * Enables runtime validation for this route.
+     *
+     * When enabled, the built middleware will validate incoming requests
+     * against the documented schema before the handler runs.
+     *
+     * @param options - Optional configuration for validation
+     * @param options.body - Enable body validation (default: true if request body is defined)
+     * @param options.query - Enable query parameter validation (default: true if query params are defined)
+     * @param options.enabled - Override the global validation enabled setting
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .withValidation() // Enable validation
+     *   .build();
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.withValidation = function (options) {
+        var _c, _d, _e;
+        this.validationConfig = {
+            enabled: (_c = options === null || options === void 0 ? void 0 : options.enabled) !== null && _c !== void 0 ? _c : true,
+            validateBody: (_d = options === null || options === void 0 ? void 0 : options.body) !== null && _d !== void 0 ? _d : true,
+            validateQuery: (_e = options === null || options === void 0 ? void 0 : options.query) !== null && _e !== void 0 ? _e : true,
+        };
+        return this;
+    };
+    /**
+     * Builds and returns the OpenAPI middleware along with schemas.
+     *
+     * This method is useful when you want to use asyncHandler's integrated
+     * validation instead of separate validation middleware.
+     *
+     * @returns Object containing middleware and schemas
+     *
+     * @example
+     * ```typescript
+     * const {middleware, bodySchema} = createOpenApiBuilder(options)
+     *   .withRequestBody<{name: string}>({name: {type: "string", required: true}})
+     *   .buildWithSchemas();
+     *
+     * router.post("/users", middleware, asyncHandler(async (req, res) => {
+     *   // handler code
+     * }, {bodySchema, validate: true}));
+     * ```
+     */
+    OpenApiMiddlewareBuilder.prototype.buildWithSchemas = function () {
+        var _c, _d, _e, _f, _g;
+        var noop = function (_a, _b, next) { return next(); };
+        // Build the OpenAPI documentation middleware only (no validation middleware)
+        var openApiMiddleware = noop;
+        if ((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path) {
+            openApiMiddleware = 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 : {}));
+        }
+        else {
+            logger_1.logger.debug("No options.openApi provided, skipping OpenApiMiddleware");
+        }
+        var globalConfig = (0, openApiValidator_1.getOpenApiValidatorConfig)();
+        var validationEnabled = (_f = this.validationConfig.enabled) !== null && _f !== void 0 ? _f : ((0, openApiValidator_1.isOpenApiValidatorConfigured)() && ((_g = globalConfig.validateRequests) !== null && _g !== void 0 ? _g : false));
+        return {
+            bodySchema: this.requestBodySchema,
+            middleware: openApiMiddleware,
+            querySchema: Object.keys(this.queryParamSchemas).length > 0 ? this.queryParamSchemas : undefined,
+            validationEnabled: validationEnabled,
+        };
+    };
     /**
      * Builds and returns the OpenAPI middleware.
      *
@@ -365,10 +441,13 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * that integrates with the OpenAPI documentation system. If no OpenAPI
      * path is configured in options, returns a no-op middleware.
      *
+     * If validation was enabled via `withValidation()`, returns an array
+     * of middleware: [openApiDocMiddleware, validationMiddleware].
+     *
      * Default error responses (400, 401, 403, 404, 405) are automatically
      * merged with the configured responses.
      *
-     * @returns Express middleware function for OpenAPI documentation
+     * @returns Express middleware function(s) for OpenAPI documentation and optional validation
      *
      * @example
      * ```typescript
@@ -381,13 +460,38 @@ var OpenApiMiddlewareBuilder = /** @class */ (function () {
      * ```
      */
     OpenApiMiddlewareBuilder.prototype.build = function () {
-        var _c, _d, _e;
+        var _c, _d, _e, _f, _g;
         var noop = function (_a, _b, next) { return next(); };
-        if (!((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path)) {
+        // Build the OpenAPI documentation middleware
+        var openApiMiddleware = noop;
+        if ((_c = this.options.openApi) === null || _c === void 0 ? void 0 : _c.path) {
+            openApiMiddleware = 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 : {}));
+        }
+        else {
             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 : {}));
+        // Check if validation should be enabled
+        var globalConfig = (0, openApiValidator_1.getOpenApiValidatorConfig)();
+        var shouldValidate = (_f = this.validationConfig.enabled) !== null && _f !== void 0 ? _f : ((0, openApiValidator_1.isOpenApiValidatorConfigured)() && ((_g = globalConfig.validateRequests) !== null && _g !== void 0 ? _g : false));
+        if (!shouldValidate) {
+            return openApiMiddleware;
+        }
+        // Build validation middleware
+        var validators = [openApiMiddleware];
+        // Add body validation if we have a request body schema
+        if (this.validationConfig.validateBody && this.requestBodySchema) {
+            validators.push((0, openApiValidator_1.validateRequestBody)(this.requestBodySchema, { enabled: true }));
+        }
+        // Add query validation if we have query parameter schemas
+        if (this.validationConfig.validateQuery && Object.keys(this.queryParamSchemas).length > 0) {
+            validators.push((0, openApiValidator_1.validateQueryParams)(this.queryParamSchemas, { enabled: true }));
+        }
+        // If only one middleware (the openApi one), return it directly
+        if (validators.length === 1) {
+            return openApiMiddleware;
+        }
+        // Return array of middleware to be spread in route definition
+        return validators;
     };
     return OpenApiMiddlewareBuilder;
 }());