@rvoh/psychic 1.5.4 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,85 @@
+## 1.6.0
+
+enables validation to be added to both openapi configurations, as well as to `OpenAPI` decorator calls, enabling the developer to granularly control validation logic for their endpoints.
+
+To leverage global config:
+
+```ts
+// conf/app.ts
+export default async (psy: PsychicApp) => {
+  ...
+
+  psy.set('openapi', {
+    // ...
+    validate: {
+      headers: true,
+      requestBody: true,
+      query: true,
+      responseBody: AppEnv.isTest,
+    },
+  })
+}
+```
+
+To leverage endpoint config:
+
+```ts
+// controllers/PetsController
+export default class PetsController {
+  @OpenAPI(Pet, {
+    ...
+    validate: {
+      headers: true,
+      requestBody: true,
+      query: true,
+      responseBody: AppEnv.isTest,
+    }
+  })
+  public async index() {
+    ...
+  }
+}
+```
+
+This PR additionally formally introduces a new possible error type for 400 status codes, and to help distinguish, it also introduces a `type` field, which can be either `openapi` or `dream` to aid the developer in easily handling the various cases.
+
+We have made a conscious decision to render openapi errors in the exact format that ajv returns, since it empowers the developer to utilize tools which can already respond to ajv errors.
+
+For added flexibility, this PR includes the ability to provide configuration overrides for the ajv instance, as well as the ability to provide an initialization function to override ajv behavior, since much of the configuration for ajv is driven by method calls, rather than simple config.
+
+```ts
+// controllers/PetsController
+export default class PetsController {
+  @OpenAPI(Pet, {
+    ...
+    validate: {
+      ajvOptions: {
+        // this is off by default, but you will
+        // always want to keep this off in prod
+        // to avoid DoS vulnerabilities
+        allErrors: AppEnv.isTest,
+
+        // provide a custom init function to further
+        // configure your ajv instance before validating
+        init: ajv => {
+          ajv.addFormat('myFormat', {
+            type: 'string',
+            validate: data => MY_FORMAT_REGEX.test(data),
+          })
+        }
+      }
+    }
+  })
+  public async index() {
+    ...
+  }
+}
+```
+
+## 1.5.5
+
+- ensure that openapi-typescript and typescript are not required dependencies when running migrations with --skip-sync flag
+
 ## 1.5.4
 
 - fix issue when providing the `including` argument exclusively to an OpenAPI decorator's `requestBody`

package/dist/cjs/src/bin/helpers/printRoutes.js

@@ -5,12 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = printRoutes;
 const yoctocolors_1 = __importDefault(require("yoctocolors"));
-const index_js_1 = __importDefault(require("../../server/index.js"));
-async function printRoutes() {
-    const server = new index_js_1.default();
-    await server.boot();
-    const routes = await server.routes();
-    const expressions = buildExpressions(routes);
+const index_js_1 = __importDefault(require("../../psychic-app/index.js"));
+function printRoutes() {
+    const expressions = buildExpressions(index_js_1.default.getOrFail().routesCache);
     // NOTE: intentionally doing this outside of the expression loop below
     // to avoid N+1
     const desiredFirstGapSpaceCount = calculateNumSpacesInFirstGap(expressions);

package/dist/cjs/src/bin/index.js

@@ -35,11 +35,9 @@ const resource_js_1 = __importDefault(require("../generate/resource.js"));
 const isObject_js_1 = __importDefault(require("../helpers/isObject.js"));
 const app_js_1 = __importDefault(require("../openapi-renderer/app.js"));
 const index_js_1 = __importDefault(require("../psychic-app/index.js"));
-const index_js_2 = __importDefault(require("../server/index.js"));
 const enumsFileStr_js_1 = __importDefault(require("./helpers/enumsFileStr.js"));
 const generateRouteTypes_js_1 = __importDefault(require("./helpers/generateRouteTypes.js"));
 const printRoutes_js_1 = __importDefault(require("./helpers/printRoutes.js"));
-const syncOpenapiTypescriptFiles_js_1 = __importDefault(require("./helpers/syncOpenapiTypescriptFiles.js"));
 class PsychicBin {
     static async generateController(controllerName, actions) {
         await (0, controller_js_1.default)({
@@ -51,8 +49,8 @@ class PsychicBin {
     static async generateResource(route, fullyQualifiedModelName, columnsWithTypes, options) {
         await (0, resource_js_1.default)({ route, fullyQualifiedModelName, columnsWithTypes, options });
     }
-    static async routes() {
-        await (0, printRoutes_js_1.default)();
+    static printRoutes() {
+        (0, printRoutes_js_1.default)();
     }
     static async sync({ bypassDreamSync = false, schemaOnly = false, } = {}) {
         if (!bypassDreamSync)
@@ -77,7 +75,7 @@ class PsychicBin {
         try {
             await this.syncOpenapiJson();
             await this.runCliHooksAndUpdatePsychicTypesFileWithOutput();
-            await this.syncTypescriptOpenapiFiles();
+            await this.syncOpenapiTypescriptFiles();
         }
         catch (error) {
             console.error(error);
@@ -90,9 +88,16 @@ class PsychicBin {
         await TypesBuilder_js_1.default.sync(customTypes);
         dream_1.DreamCLI.logger.logEndProgress();
     }
-    static async syncTypescriptOpenapiFiles() {
+    static async syncOpenapiTypescriptFiles() {
         dream_1.DreamCLI.logger.logStartProgress(`syncing openapi types...`);
-        await (0, syncOpenapiTypescriptFiles_js_1.default)();
+        // https://rvohealth.atlassian.net/browse/PDTC-8359
+        // by dynamically importing this file, we prevent both openapi-typescript
+        // and typescript from being required as dependencies, since in production
+        // environments these won't be installed. By running migrations with
+        // --skip-sync, this function will never run, preventing the file which
+        // requires the dev dependencies from ever being imported.
+        const syncOpenapiTypescriptFiles = (await Promise.resolve().then(() => __importStar(require('./helpers/syncOpenapiTypescriptFiles.js')))).default;
+        await syncOpenapiTypescriptFiles();
         dream_1.DreamCLI.logger.logEndProgress();
     }
     static async syncOpenapiJson() {
@@ -102,10 +107,7 @@ class PsychicBin {
     }
     static async syncRoutes() {
         dream_1.DreamCLI.logger.logStartProgress(`syncing routes...`);
-        const server = new index_js_2.default();
-        await server.boot();
-        const routes = await server.routes();
-        await (0, generateRouteTypes_js_1.default)(routes);
+        await (0, generateRouteTypes_js_1.default)(index_js_1.default.getOrFail().routesCache);
         dream_1.DreamCLI.logger.logEndProgress();
     }
     static async syncClientEnums(outfile) {

package/dist/cjs/src/cli/index.js

@@ -132,7 +132,7 @@ class PsychicCLI {
             .description('examines your current models, building a type-map of the associations so that the ORM can understand your relational setup. This is commited to your repo, and synced to the dream repo for consumption within the underlying library.')
             .action(async () => {
             await initializePsychicApp();
-            await index_js_1.default.routes();
+            index_js_1.default.printRoutes();
             process.exit();
         });
         program

package/dist/cjs/src/controller/index.js

@@ -37,6 +37,7 @@ const Unauthorized_js_1 = __importDefault(require("../error/http/Unauthorized.js
 const UnavailableForLegalReasons_js_1 = __importDefault(require("../error/http/UnavailableForLegalReasons.js"));
 const UnprocessableContent_js_1 = __importDefault(require("../error/http/UnprocessableContent.js"));
 const UnsupportedMediaType_js_1 = __importDefault(require("../error/http/UnsupportedMediaType.js"));
+const OpenapiPayloadValidator_js_1 = __importDefault(require("../openapi-renderer/helpers/OpenapiPayloadValidator.js"));
 const params_js_1 = __importDefault(require("../server/params.js"));
 const index_js_1 = __importDefault(require("../session/index.js"));
 const isPaginatedResult_js_1 = __importDefault(require("./helpers/isPaginatedResult.js"));
@@ -205,9 +206,33 @@ class PsychicController {
             casing: 'camel',
         };
     }
+    /**
+     * @returns the request headers
+     *
+     * @example
+     * ```ts
+     * class MyController extends ApplicationController {
+     *   public index() {
+     *     console.log(this.headers)
+     *   }
+     * }
+     * ```
+     */
     get headers() {
         return this.req.headers;
     }
+    /**
+     * @returns the combination of the request uri params, request body, and query
+     *
+     * @example
+     * ```ts
+     * class MyController extends ApplicationController {
+     *   public index() {
+     *     console.log(this.params)
+     *   }
+     * }
+     * ```
+     */
     get params() {
         const params = {
             ...this.req.params,
@@ -216,9 +241,49 @@ class PsychicController {
         };
         return params;
     }
+    /**
+     * @returns the value found for a particular param
+     *
+     * @example
+     * ```ts
+     * class MyController extends ApplicationController {
+     *   public index() {
+     *     console.log(this.param('myParam'))
+     *   }
+     * }
+     * ```
+     */
     param(key) {
         return this.params[key];
     }
+    /**
+     * finds the specified param, and validates it against
+     * the provided type. If the param does not match the specified
+     * validation arguments, ParamValidationError is raised, which
+     * Psychic will catch and convert into a 400 response.
+     *
+     * @returns the value found for a particular param
+     *
+     * @example
+     * ```ts
+     * class MyController extends ApplicationController {
+     *   public index() {
+     *     const id = this.castParam('id', 'bigint')
+     *   }
+     * }
+     * ```
+     *
+     * You can provide additional restrictions using the options arg:
+     *
+     * @example
+     * ```ts
+     * class MyController extends ApplicationController {
+     *   public index() {
+     *     const type = this.castParam('type', 'string', { enum: ['Type1', 'Type2'], allowNull: true })
+     *   }
+     * }
+     * ```
+     */
     castParam(key, expectedType, opts) {
         try {
             return this._castParam(key.split('.'), this.params, expectedType, opts);
@@ -247,6 +312,28 @@ class PsychicController {
         }
         return this._castParam(keys, nestedParams, expectedType, opts);
     }
+    /**
+     * Captures params for the provided model. Will exclude params that are not
+     * considered "safe" by default. It will use `castParam` for each of the
+     * params, and will raise an exception if any of those params does not
+     * pass validation.
+     *
+     * @param dreamClass - the dream class you wish to retreive params for
+     * @param opts - optional configuration object
+     * @param opts.only - optional: restrict the list of allowed params
+     * @param opts.including - optional: include params that would normally be excluded.
+     *
+     * @returns a typed object, containing the casted params for this dream class
+     *
+     * @example
+     * ```ts
+     * class MyController extends ApplicationController {
+     *   public index() {
+     *     const params = this.paramsFor(User, { only: ['email'], including: ['createdAt'] })
+     *   }
+     * }
+     * ```
+     */
     paramsFor(dreamClass, opts) {
         return params_js_1.default.for(opts?.key ? this.params[opts.key] || {} : this.params, dreamClass, 
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -313,15 +400,27 @@ class PsychicController {
     }
     json(data, opts = {}) {
         if (Array.isArray(data))
-            return this.res.json(data.map(d => 
+            return this.validateAndRenderJsonResponse(data.map(d => 
             // eslint-disable-next-line @typescript-eslint/no-unsafe-return
             this.singleObjectJson(d, opts)));
         if ((0, isPaginatedResult_js_1.default)(data))
-            return this.res.json({
+            return this.validateAndRenderJsonResponse({
                 ...data,
                 results: data.results.map(result => this.singleObjectJson(result, opts)),
             });
-        return this.res.json(this.singleObjectJson(data, opts));
+        return this.validateAndRenderJsonResponse(this.singleObjectJson(data, opts));
+    }
+    /**
+     * Runs the data through openapi response validation, and then renders
+     * the data if no errors were found.
+     *
+     * @param data - the data to validate and render
+     */
+    validateAndRenderJsonResponse(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data) {
+        this.validateOpenapiResponseBody(data);
+        this.res.json(data);
     }
     defaultSerializerPassthrough = {};
     serializerPassthrough(passthrough) {
@@ -343,7 +442,8 @@ class PsychicController {
         const realStatus = (typeof status_codes_js_1.default[status] === 'string'
             ? status_codes_js_1.default[status_codes_js_1.default[status]]
             : status_codes_js_1.default[status]);
-        this.res.status(realStatus).json(body);
+        this.res.status(realStatus);
+        this.json(body);
     }
     redirect(path) {
         this.res.redirect(path);
@@ -380,12 +480,14 @@ class PsychicController {
     // 205
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     resetContent(message = undefined) {
-        this.res.status(205).send(message);
+        this.res.status(205);
+        this.json(message);
     }
     // 208
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     alreadyReported(message = undefined) {
-        this.res.status(208).send(message);
+        this.res.status(208);
+        this.json(message);
     }
     // 301
     movedPermanently(newLocation) {
@@ -562,13 +664,104 @@ class PsychicController {
         throw new NotExtended_js_1.default(message);
     }
     // end: http status codes
+    /**
+     * @internal
+     *
+     * Called by the psychic router when the endpoint for
+     * this controller was hit.
+     *
+     * @param action - the action to use when validating the query params.
+     */
     async runAction(action) {
         await this.runBeforeActionsFor(action);
         if (this.res.headersSent)
             return;
+        this.validateOpenapiHeadersForAction(action);
+        this.validateOpenapiQueryForAction(action);
+        this.validateOpenapiRequestBodyForAction(action);
         // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
         await this[action]();
     }
+    /**
+     * Validates the request body.
+     * If an OpenAPI decorator was attached to this endpoint,
+     * the computed headers for that decorator will
+     * be used to validate this endpoint.
+     *
+     * @param action - the action to use when validating the query params.
+     */
+    validateOpenapiRequestBodyForAction(action) {
+        const openapiEndpointRenderer = this.constructor.openapi?.[action];
+        if (!openapiEndpointRenderer)
+            return;
+        this.computedOpenapiNames.forEach(openapiName => {
+            new OpenapiPayloadValidator_js_1.default(openapiName, openapiEndpointRenderer).validateOpenapiRequestBody(this.req.body);
+        });
+    }
+    /**
+     * Validates the request headers.
+     * If an OpenAPI decorator was attached to this endpoint,
+     * the computed headers for that decorator will
+     * be used to validate this endpoint.
+     *
+     * @param action - the action to use when validating the query params.
+     */
+    validateOpenapiHeadersForAction(action) {
+        const openapiEndpointRenderer = this.constructor.openapi?.[action];
+        if (!openapiEndpointRenderer)
+            return;
+        this.computedOpenapiNames.forEach(openapiName => {
+            new OpenapiPayloadValidator_js_1.default(openapiName, openapiEndpointRenderer).validateOpenapiHeaders(this.req.headers);
+        });
+    }
+    /**
+     * Validates the request query params.
+     * If an OpenAPI decorator was attached to this endpoint,
+     * the computed query params for that decorator will
+     * be used to validate this endpoint.
+     *
+     * @param action - the action to use when validating the query params.
+     */
+    validateOpenapiQueryForAction(action) {
+        const openapiEndpointRenderer = this.constructor.openapi?.[action];
+        if (!openapiEndpointRenderer)
+            return;
+        this.computedOpenapiNames.forEach(openapiName => {
+            new OpenapiPayloadValidator_js_1.default(openapiName, openapiEndpointRenderer).validateOpenapiQuery(this.req.query);
+        });
+    }
+    /**
+     * Validates the data in the context of a response body.
+     * If an OpenAPI decorator was attached to this endpoint,
+     * the computed response schema for that decorator will
+     * be used to validate this endpoint based on the status code
+     * set.
+     *
+     * @param data - the response body data to render
+     */
+    validateOpenapiResponseBody(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data) {
+        const openapiEndpointRenderer = this.constructor.openapi?.[this.action];
+        if (!openapiEndpointRenderer)
+            return;
+        this.computedOpenapiNames.forEach(openapiName => {
+            new OpenapiPayloadValidator_js_1.default(openapiName, openapiEndpointRenderer).validateOpenapiResponseBody(data, this.res.statusCode);
+        });
+    }
+    /**
+     * @internal
+     *
+     * @returns the openapiNames set on the constructor, or else ['default']
+     */
+    get computedOpenapiNames() {
+        return this.constructor.openapiNames || ['default'];
+    }
+    /**
+     * @internal
+     *
+     * Runs the before actions for a particular action on a controller
+     */
     async runBeforeActionsFor(action) {
         const beforeActions = this.constructor.controllerHooks.filter(hook => hook.shouldFireForAction(action));
         for (const hook of beforeActions) {

package/dist/cjs/src/error/openapi/OpenapResponseValidationFailure.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const OpenapiValidationFailure_js_1 = __importDefault(require("./OpenapiValidationFailure.js"));
+class OpenapiResponseValidationFailure extends OpenapiValidationFailure_js_1.default {
+}
+exports.default = OpenapiResponseValidationFailure;

package/dist/cjs/src/error/openapi/OpenapiRequestValidationFailure.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const OpenapiValidationFailure_js_1 = __importDefault(require("./OpenapiValidationFailure.js"));
+class OpenapiRequestValidationFailure extends OpenapiValidationFailure_js_1.default {
+}
+exports.default = OpenapiRequestValidationFailure;

package/dist/cjs/src/error/openapi/OpenapiValidationFailure.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class OpenapiValidationFailure extends Error {
+    errors;
+    target;
+    constructor(errors, target) {
+        super();
+        this.errors = errors;
+        this.target = target;
+    }
+}
+exports.default = OpenapiValidationFailure;

package/dist/cjs/src/error/psychic-app/must-call-psychic-app-init-first.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class MustCallPsychicAppInitFirst extends Error {
+    constructor() {
+        super();
+    }
+    get message() {
+        return `
+      For some reason, PsychicApp.init was never called. In order for the
+      execution context to proceed, you must first ensure that PsychicApp.init
+      has been called. Usually, this is done by calling
+
+        await initializePsychicApp()
+
+      which is set up in your application boilerplate for you by default for
+      the relevant execution contexts. Perhaps it was mistakenly removed, or
+      otherwise you are trying to implement a new entrypoint into psychic, at
+      which case, please make sure to call 'await initializePsychicApp()' first
+    `;
+    }
+}
+exports.default = MustCallPsychicAppInitFirst;

package/dist/cjs/src/helpers/validateOpenApiSchema.js

@@ -0,0 +1,146 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = validateOpenApiSchema;
+exports.validateObject = validateObject;
+exports.createValidator = createValidator;
+const ajv_1 = require("ajv");
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
+/**
+ * @internal
+ *
+ * Validates an object against an OpenAPI schema
+ * Convenience wrapper around validateObject with OpenAPI-friendly defaults.
+ *
+ * This function is used internally by the OpenapiPayloadValidator
+ * class to correctly validate request body, query, headers,
+ * and response body.
+ *
+ * @param data - Object to validate
+ * @param openapiSchema - OpenAPI schema object
+ * @param options - (Optional) options to provide when initializing the ajv instance
+ * @returns ValidationResult
+ *
+ * @example
+ *
+ * ```ts
+ * const schema = {
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string' },
+ *     age: { type: 'integer', minimum: 0 }
+ *   },
+ *   required: ['name']
+ * }
+ *
+ * const result = validateOpenApiSchema({ name: 'John', age: 30 }, schema)
+ * if (result.isValid) {
+ *   console.log('Valid data:', result.data)
+ * } else {
+ *   console.log('Validation errors:', result.errors)
+ * }
+ * ```
+ */
+function validateOpenApiSchema(data, openapiSchema, options = {}) {
+    return validateObject(data, openapiSchema, {
+        removeAdditional: 'failing', // Remove properties that fail validation
+        useDefaults: true,
+        coerceTypes: true,
+        ...options,
+    });
+}
+/**
+ * @internal
+ *
+ * Validates an object against a JSON schema using AJV
+ *
+ * @param data - Object to validate
+ * @param schema - JSON Schema to validate against
+ * @param options - Validation options
+ * @returns ValidationResult with success status, validated data, and any errors
+ */
+function validateObject(data, schema, options = {}) {
+    try {
+        const validate = createValidator(schema, options);
+        // Clone the data to prevent AJV from mutating the original object
+        const clonedData = structuredClone(data);
+        const isValid = validate(clonedData);
+        if (isValid) {
+            return {
+                isValid: true,
+                data: clonedData,
+            };
+        }
+        else {
+            return {
+                isValid: false,
+                errors: formatAjvErrors(validate.errors || []),
+            };
+        }
+    }
+    catch (error) {
+        // Handle schema compilation errors
+        return {
+            isValid: false,
+            errors: [
+                {
+                    instancePath: '',
+                    schemaPath: '',
+                    keyword: 'schema',
+                    message: error instanceof Error ? error.message : 'Schema compilation failed',
+                },
+            ],
+        };
+    }
+}
+/**
+ * @internal
+ *
+ * Creates an AJV validator function for validating objects against JSON schemas
+ *
+ * @param schema - JSON Schema to validate against
+ * @param options - Validation options
+ * @returns A validator function that can be reused for multiple validations
+ */
+function createValidator(schema, options = {}) {
+    const ajvOptions = {
+        ...options,
+        init: undefined,
+    };
+    const ajv = new ajv_1.Ajv({
+        removeAdditional: false,
+        useDefaults: true,
+        coerceTypes: true,
+        strict: false, // Allow unknown keywords for OpenAPI compatibility
+        allErrors: options.allErrors || false, // Collect all errors, not just the first one
+        validateFormats: true, // Enable format validation for date-time, email, etc.
+        ...ajvOptions,
+    });
+    ajv_formats_1.default(ajv);
+    ajv.addFormat('decimal', {
+        type: 'string',
+        validate: data => DECIMAL_REGEX.test(data),
+    });
+    ajv.addFormat('bigint', {
+        type: 'string',
+        validate: data => BIGINT_REGEX.test(data),
+    });
+    options?.init?.(ajv);
+    return ajv.compile(schema);
+}
+const DECIMAL_REGEX = /^-?(\d+\.?\d*|\.\d+)$/;
+const BIGINT_REGEX = /^-?\d+(\.0*)?$/;
+/**
+ * Formats AJV errors into a more readable format
+ */
+function formatAjvErrors(ajvErrors) {
+    return ajvErrors.map(error => ({
+        instancePath: error.instancePath,
+        schemaPath: error.schemaPath,
+        keyword: error.keyword,
+        message: error.message || 'Validation failed',
+        params: error.params,
+    }));
+}