@rvoh/psychic 0.34.4 → 0.35.0

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

@@ -71,7 +71,7 @@ class PsychicBin {
         await PsychicBin.syncOpenapiJson();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let output = {};
-        for (const hook of psychicApp.specialHooks.sync) {
+        for (const hook of psychicApp.specialHooks.cliSync) {
             // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
             const res = await hook();
             if ((0, typechecks_js_1.isObject)(res)) {

package/dist/cjs/src/controller/helpers/isPaginatedResult.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = isPaginatedResult;
+const typechecks_js_1 = require("../../helpers/typechecks.js");
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isPaginatedResult(result) {
+    if (!(0, typechecks_js_1.isObject)(result))
+        return false;
+    const paginatedFields = ['currentPage', 'pageCount', 'recordCount', 'results'];
+    const keys = Object.keys(result);
+    if (keys.length !== paginatedFields.length)
+        return false;
+    for (const paginatedField of paginatedFields) {
+        if (!keys.includes(paginatedField))
+            return false;
+    }
+    return true;
+}

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

@@ -39,6 +39,7 @@ const UnsupportedMediaType_js_1 = __importDefault(require("../error/http/Unsuppo
 const params_js_1 = __importDefault(require("../server/params.js"));
 const index_js_1 = __importDefault(require("../session/index.js"));
 const ParamValidationError_js_1 = __importDefault(require("../error/controller/ParamValidationError.js"));
+const isPaginatedResult_js_1 = __importDefault(require("./helpers/isPaginatedResult.js"));
 exports.PsychicParamsPrimitiveLiterals = [
     'bigint',
     'bigint[]',
@@ -294,6 +295,11 @@ The key in question is: "${serializerKey}"`);
             return this.res.json(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({
+                ...data,
+                results: data.results.map(result => this.singleObjectJson(result, opts)),
+            });
         return this.res.json(this.singleObjectJson(data, opts));
     }
     defaultSerializerPassthrough = {};

package/dist/cjs/src/generate/helpers/reduxBindings/writeApiFile.js

@@ -65,7 +65,7 @@ export const ${apiImport} = createApi({
   keepUnusedDataFor: 0,
 
   baseQuery: fetchBaseQuery({
-    baseUrl: baseURL(),
+    baseUrl: baseUrl(),
     credentials: 'include',
 
     // we recommend that you use a function like this for preparing

package/dist/cjs/src/openapi-renderer/endpoint.js

@@ -15,11 +15,14 @@ const openapiRoute_js_1 = __importDefault(require("./helpers/openapiRoute.js"));
 const primitiveOpenapiStatementToOpenapi_js_1 = __importDefault(require("./helpers/primitiveOpenapiStatementToOpenapi.js"));
 const serializer_js_1 = __importDefault(require("./serializer.js"));
 const FailedToLookupSerializerForEndpoint_js_1 = __importDefault(require("../error/openapi/FailedToLookupSerializerForEndpoint.js"));
+const pageParamOpenapiProperty_js_1 = __importDefault(require("./helpers/pageParamOpenapiProperty.js"));
+const safelyAttachPaginationParamsToBodySegment_js_1 = __importDefault(require("./helpers/safelyAttachPaginationParamsToBodySegment.js"));
 class OpenapiEndpointRenderer {
     dreamsOrSerializers;
     controllerClass;
     action;
     many;
+    paginate;
     responses;
     serializerKey;
     pathParams;
@@ -50,13 +53,14 @@ class OpenapiEndpointRenderer {
      * const json = JSON.encode(openapiJsonContents, null, 2)
      * ```
      */
-    constructor(dreamsOrSerializers, controllerClass, action, { requestBody, headers, many, query, responses, serializerKey, status, tags, security, pathParams, description, summary, omitDefaultHeaders, omitDefaultResponses, defaultResponse, } = {}) {
+    constructor(dreamsOrSerializers, controllerClass, action, { requestBody, headers, many, paginate, query, responses, serializerKey, status, tags, security, pathParams, description, summary, omitDefaultHeaders, omitDefaultResponses, defaultResponse, } = {}) {
         this.dreamsOrSerializers = dreamsOrSerializers;
         this.controllerClass = controllerClass;
         this.action = action;
         this.requestBody = requestBody;
         this.headers = headers;
         this.many = many;
+        this.paginate = paginate;
         this.query = query;
         this.responses = responses;
         this.serializerKey = serializerKey;
@@ -297,7 +301,7 @@ class OpenapiEndpointRenderer {
      * "parameters" field for a single endpoint.
      */
     queryArray(openapiName) {
-        return (Object.keys(this.query || {}).map((queryName) => {
+        const queryParams = Object.keys(this.query || {}).map((queryName) => {
             const queryParam = this.query[queryName];
             let output = {
                 in: 'query',
@@ -323,7 +327,21 @@ class OpenapiEndpointRenderer {
                 };
             }
             return output;
-        }) || []);
+        }) || [];
+        const paginationName = this.paginate?.query;
+        if (paginationName) {
+            queryParams.push({
+                in: 'query',
+                required: false,
+                name: paginationName,
+                description: 'Page number',
+                allowReserved: true,
+                schema: {
+                    type: 'string',
+                },
+            });
+        }
+        return queryParams;
     }
     /**
      * @internal
@@ -333,17 +351,22 @@ class OpenapiEndpointRenderer {
     computedRequestBody(openapiName, processedSchemas, routes) {
         const method = this.computedMethod(routes);
         if (this.requestBody === null)
-            return undefined;
+            return this.defaultRequestBody();
         const httpMethodsThatAllowBody = ['post', 'patch', 'put'];
         if (!httpMethodsThatAllowBody.includes(method))
-            return undefined;
+            return this.defaultRequestBody();
         if (this.shouldAutogenerateBody()) {
             return this.generateRequestBodyForModel(openapiName, processedSchemas);
         }
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const schema = this.recursivelyParseBody(openapiName, this.requestBody, processedSchemas, {
+        let schema = this.recursivelyParseBody(openapiName, this.requestBody, processedSchemas, {
             target: 'request',
         });
+        const bodyPageParam = this.paginate?.body;
+        if (bodyPageParam) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            schema = (0, safelyAttachPaginationParamsToBodySegment_js_1.default)(bodyPageParam, schema);
+        }
         if (!schema)
             return undefined;
         return {
@@ -355,6 +378,24 @@ class OpenapiEndpointRenderer {
             },
         };
     }
+    defaultRequestBody() {
+        const bodyPageParam = this.paginate?.body;
+        if (bodyPageParam) {
+            return {
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                [bodyPageParam]: (0, pageParamOpenapiProperty_js_1.default)(),
+                            },
+                        },
+                    },
+                },
+            };
+        }
+        return undefined;
+    }
     /**
      * @internal
      *
@@ -388,7 +429,7 @@ class OpenapiEndpointRenderer {
         const forDreamClass = this.requestBody?.for;
         const dreamClass = forDreamClass || this.getSingleDreamModelClass();
         if (!dreamClass)
-            return undefined;
+            return this.defaultRequestBody();
         let paramSafeColumns = dreamClass.paramSafeColumnsOrFallback();
         const only = this.requestBody?.only;
         if (only) {
@@ -539,12 +580,17 @@ class OpenapiEndpointRenderer {
                     }
             }
         }
+        let processedSchema = this.recursivelyParseBody(openapiName, paramsShape, processedSchemas, {
+            target: 'request',
+        });
+        const bodyPageParam = this.paginate?.body;
+        if (bodyPageParam) {
+            processedSchema = (0, safelyAttachPaginationParamsToBodySegment_js_1.default)(bodyPageParam, processedSchema);
+        }
         return {
             content: {
                 'application/json': {
-                    schema: this.recursivelyParseBody(openapiName, paramsShape, processedSchemas, {
-                        target: 'request',
-                    }),
+                    schema: processedSchema,
                 },
             },
         };
@@ -659,16 +705,9 @@ class OpenapiEndpointRenderer {
         const serializerClass = this.getSerializerClasses()[0];
         if (serializerClass === undefined)
             throw new FailedToLookupSerializerForEndpoint_js_1.default(this.controllerClass, this.action);
-        const serializerKey = serializerClass.openapiName;
-        const serializerObject = { $ref: `#/components/schemas/${serializerKey}` };
-        const baseSchema = this.many
-            ? {
-                type: 'array',
-                items: serializerObject,
-            }
-            : this.defaultResponse?.maybeNull
-                ? { anyOf: [serializerObject, { type: 'null' }] }
-                : serializerObject;
+        const baseSchema = this.baseSchemaForSerializerObject({
+            $ref: `#/components/schemas/${serializerClass.openapiName}`,
+        });
         const finalOutput = {
             content: {
                 'application/json': {
@@ -680,6 +719,46 @@ class OpenapiEndpointRenderer {
         };
         return finalOutput;
     }
+    /**
+     * @internal
+     *
+     * takes a base serializer object (i.e. { $ref: '#/components/schemas/MySerializer' })
+     * and transforms it based on the openapi renderer options.
+     *
+     * if many, it will return an array of this serializer object.
+     * if paginate, it will return a pagination object with an array of this serializer object
+     * if defaultResponse.maybeNull is set, it will optionally return null as well (only for non-many and non-paginate cases)
+     */
+    baseSchemaForSerializerObject(serializerObject) {
+        if (this.paginate)
+            return {
+                type: 'object',
+                required: ['recordCount', 'pageCount', 'currentPage', 'results'],
+                properties: {
+                    recordCount: {
+                        type: 'number',
+                    },
+                    pageCount: {
+                        type: 'number',
+                    },
+                    currentPage: {
+                        type: 'number',
+                    },
+                    results: {
+                        type: 'array',
+                        items: serializerObject,
+                    },
+                },
+            };
+        if (this.many)
+            return {
+                type: 'array',
+                items: serializerObject,
+            };
+        if (this.defaultResponse?.maybeNull)
+            return { anyOf: [serializerObject, { type: 'null' }] };
+        return serializerObject;
+    }
     /**
      * @internal
      *

package/dist/cjs/src/openapi-renderer/helpers/pageParamOpenapiProperty.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = openapiPageParamProperty;
+function openapiPageParamProperty() {
+    return {
+        type: 'integer',
+        description: 'Page number',
+    };
+}

package/dist/cjs/src/openapi-renderer/helpers/safelyAttachPaginationParamsToBodySegment.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = safelyAttachPaginationParamToRequestBodySegment;
+const pageParamOpenapiProperty_js_1 = __importDefault(require("./pageParamOpenapiProperty.js"));
+/**
+ * @internal
+ *
+ * Used to carefully bind implicit pagination params
+ * to the requestBody properties. It will not apply
+ * the pagination param unless the provided bodySegment
+ * is:
+ *
+ * a.) falsey (null, undefined, etc...)
+ * b.) an openapi object (must have { type: 'object'})
+ *
+ * If neither of these apply, it will simply return
+ * what was given to it, without any modifications
+ */
+function safelyAttachPaginationParamToRequestBodySegment(paramName, bodySegment) {
+    bodySegment ||= {
+        type: 'object',
+        properties: {},
+    };
+    if (bodySegment.type === 'object') {
+        ;
+        bodySegment.properties = {
+            ...bodySegment.properties,
+            [paramName]: (0, pageParamOpenapiProperty_js_1.default)(),
+        };
+    }
+    return bodySegment;
+}

package/dist/cjs/src/psychic-app/index.js

@@ -220,19 +220,10 @@ Try setting it to something valid, like:
     get inflections() {
         return this._inflections;
     }
-    _bootHooks = {
-        boot: [],
-        load: [],
-        'load:dev': [],
-        'load:test': [],
-        'load:prod': [],
-    };
-    get bootHooks() {
-        return this._bootHooks;
-    }
     _specialHooks = {
-        sync: [],
-        serverInit: [],
+        cliSync: [],
+        serverInitBeforeMiddleware: [],
+        serverInitAfterMiddleware: [],
         serverInitAfterRoutes: [],
         serverStart: [],
         serverError: [],
@@ -297,18 +288,6 @@ Try setting it to something valid, like:
         if (this.booted && !force)
             return;
         // await new IntegrityChecker().check()
-        await this.runHooksFor('load');
-        switch (EnvInternal_js_1.default.nodeEnv) {
-            case 'development':
-                await this.runHooksFor('load:dev');
-                break;
-            case 'production':
-                await this.runHooksFor('load:prod');
-                break;
-            case 'test':
-                await this.runHooksFor('load:test');
-                break;
-        }
         await this.inflections?.();
         this.booted = true;
     }
@@ -320,8 +299,11 @@ Try setting it to something valid, like:
             case 'server:error':
                 this._specialHooks.serverError.push(cb);
                 break;
-            case 'server:init':
-                this._specialHooks.serverInit.push(cb);
+            case 'server:init:before-middleware':
+                this._specialHooks.serverInitBeforeMiddleware.push(cb);
+                break;
+            case 'server:init:after-middleware':
+                this._specialHooks.serverInitAfterMiddleware.push(cb);
                 break;
             case 'server:start':
                 this._specialHooks.serverStart.push(cb);
@@ -332,12 +314,10 @@ Try setting it to something valid, like:
             case 'server:init:after-routes':
                 this._specialHooks.serverInitAfterRoutes.push(cb);
                 break;
-            case 'sync':
+            case 'cli:sync':
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                this._specialHooks['sync'].push(cb);
+                this._specialHooks['cliSync'].push(cb);
                 break;
-            default:
-                this.bootHooks[hookEventType].push(cb);
         }
     }
     set(option, unknown1, unknown2) {
@@ -429,11 +409,6 @@ Try setting it to something valid, like:
                 this.overrides['server:start'] = value;
         }
     }
-    async runHooksFor(hookEventType) {
-        for (const hook of this.bootHooks[hookEventType]) {
-            await hook(this);
-        }
-    }
 }
 exports.default = PsychicApp;
 exports.PsychicAppAllowedPackageManagersEnumValues = ['yarn', 'npm', 'pnpm'];

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

@@ -73,7 +73,9 @@ class PsychicServer {
             });
             next();
         });
-        await this.config['runHooksFor']('boot');
+        for (const serverInitBeforeMiddlewareHook of this.config.specialHooks.serverInitBeforeMiddleware) {
+            await serverInitBeforeMiddlewareHook(this);
+        }
         this.initializeCors();
         this.initializeJSON();
         try {
@@ -87,8 +89,8 @@ class PsychicServer {
           ${error.message}
       `);
         }
-        for (const expressInitHook of this.config.specialHooks.serverInit) {
-            await expressInitHook(this);
+        for (const serverInitAfterMiddlewareHook of this.config.specialHooks.serverInitAfterMiddleware) {
+            await serverInitAfterMiddlewareHook(this);
         }
         this.initializeOpenapiValidation();
         await this.buildRoutes();

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

@@ -43,7 +43,7 @@ export default class PsychicBin {
         await PsychicBin.syncOpenapiJson();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let output = {};
-        for (const hook of psychicApp.specialHooks.sync) {
+        for (const hook of psychicApp.specialHooks.cliSync) {
             // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
             const res = await hook();
             if (isObject(res)) {

package/dist/esm/src/controller/helpers/isPaginatedResult.js

@@ -0,0 +1,15 @@
+import { isObject } from '../../helpers/typechecks.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export default function isPaginatedResult(result) {
+    if (!isObject(result))
+        return false;
+    const paginatedFields = ['currentPage', 'pageCount', 'recordCount', 'results'];
+    const keys = Object.keys(result);
+    if (keys.length !== paginatedFields.length)
+        return false;
+    for (const paginatedField of paginatedFields) {
+        if (!keys.includes(paginatedField))
+            return false;
+    }
+    return true;
+}

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

@@ -33,6 +33,7 @@ import HttpStatusUnsupportedMediaType from '../error/http/UnsupportedMediaType.j
 import Params from '../server/params.js';
 import Session from '../session/index.js';
 import ParamValidationError from '../error/controller/ParamValidationError.js';
+import isPaginatedResult from './helpers/isPaginatedResult.js';
 export const PsychicParamsPrimitiveLiterals = [
     'bigint',
     'bigint[]',
@@ -288,6 +289,11 @@ The key in question is: "${serializerKey}"`);
             return this.res.json(data.map(d => 
             // eslint-disable-next-line @typescript-eslint/no-unsafe-return
             this.singleObjectJson(d, opts)));
+        if (isPaginatedResult(data))
+            return this.res.json({
+                ...data,
+                results: data.results.map(result => this.singleObjectJson(result, opts)),
+            });
         return this.res.json(this.singleObjectJson(data, opts));
     }
     defaultSerializerPassthrough = {};

package/dist/esm/src/generate/helpers/reduxBindings/writeApiFile.js

@@ -39,7 +39,7 @@ export const ${apiImport} = createApi({
   keepUnusedDataFor: 0,
 
   baseQuery: fetchBaseQuery({
-    baseUrl: baseURL(),
+    baseUrl: baseUrl(),
     credentials: 'include',
 
     // we recommend that you use a function like this for preparing

package/dist/esm/src/openapi-renderer/endpoint.js

@@ -9,11 +9,14 @@ import openapiRoute from './helpers/openapiRoute.js';
 import primitiveOpenapiStatementToOpenapi from './helpers/primitiveOpenapiStatementToOpenapi.js';
 import OpenapiSerializerRenderer from './serializer.js';
 import OpenApiFailedToLookupSerializerForEndpoint from '../error/openapi/FailedToLookupSerializerForEndpoint.js';
+import openapiPageParamProperty from './helpers/pageParamOpenapiProperty.js';
+import safelyAttachPaginationParamToRequestBodySegment from './helpers/safelyAttachPaginationParamsToBodySegment.js';
 export default class OpenapiEndpointRenderer {
     dreamsOrSerializers;
     controllerClass;
     action;
     many;
+    paginate;
     responses;
     serializerKey;
     pathParams;
@@ -44,13 +47,14 @@ export default class OpenapiEndpointRenderer {
      * const json = JSON.encode(openapiJsonContents, null, 2)
      * ```
      */
-    constructor(dreamsOrSerializers, controllerClass, action, { requestBody, headers, many, query, responses, serializerKey, status, tags, security, pathParams, description, summary, omitDefaultHeaders, omitDefaultResponses, defaultResponse, } = {}) {
+    constructor(dreamsOrSerializers, controllerClass, action, { requestBody, headers, many, paginate, query, responses, serializerKey, status, tags, security, pathParams, description, summary, omitDefaultHeaders, omitDefaultResponses, defaultResponse, } = {}) {
         this.dreamsOrSerializers = dreamsOrSerializers;
         this.controllerClass = controllerClass;
         this.action = action;
         this.requestBody = requestBody;
         this.headers = headers;
         this.many = many;
+        this.paginate = paginate;
         this.query = query;
         this.responses = responses;
         this.serializerKey = serializerKey;
@@ -291,7 +295,7 @@ export default class OpenapiEndpointRenderer {
      * "parameters" field for a single endpoint.
      */
     queryArray(openapiName) {
-        return (Object.keys(this.query || {}).map((queryName) => {
+        const queryParams = Object.keys(this.query || {}).map((queryName) => {
             const queryParam = this.query[queryName];
             let output = {
                 in: 'query',
@@ -317,7 +321,21 @@ export default class OpenapiEndpointRenderer {
                 };
             }
             return output;
-        }) || []);
+        }) || [];
+        const paginationName = this.paginate?.query;
+        if (paginationName) {
+            queryParams.push({
+                in: 'query',
+                required: false,
+                name: paginationName,
+                description: 'Page number',
+                allowReserved: true,
+                schema: {
+                    type: 'string',
+                },
+            });
+        }
+        return queryParams;
     }
     /**
      * @internal
@@ -327,17 +345,22 @@ export default class OpenapiEndpointRenderer {
     computedRequestBody(openapiName, processedSchemas, routes) {
         const method = this.computedMethod(routes);
         if (this.requestBody === null)
-            return undefined;
+            return this.defaultRequestBody();
         const httpMethodsThatAllowBody = ['post', 'patch', 'put'];
         if (!httpMethodsThatAllowBody.includes(method))
-            return undefined;
+            return this.defaultRequestBody();
         if (this.shouldAutogenerateBody()) {
             return this.generateRequestBodyForModel(openapiName, processedSchemas);
         }
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const schema = this.recursivelyParseBody(openapiName, this.requestBody, processedSchemas, {
+        let schema = this.recursivelyParseBody(openapiName, this.requestBody, processedSchemas, {
             target: 'request',
         });
+        const bodyPageParam = this.paginate?.body;
+        if (bodyPageParam) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            schema = safelyAttachPaginationParamToRequestBodySegment(bodyPageParam, schema);
+        }
         if (!schema)
             return undefined;
         return {
@@ -349,6 +372,24 @@ export default class OpenapiEndpointRenderer {
             },
         };
     }
+    defaultRequestBody() {
+        const bodyPageParam = this.paginate?.body;
+        if (bodyPageParam) {
+            return {
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                [bodyPageParam]: openapiPageParamProperty(),
+                            },
+                        },
+                    },
+                },
+            };
+        }
+        return undefined;
+    }
     /**
      * @internal
      *
@@ -382,7 +423,7 @@ export default class OpenapiEndpointRenderer {
         const forDreamClass = this.requestBody?.for;
         const dreamClass = forDreamClass || this.getSingleDreamModelClass();
         if (!dreamClass)
-            return undefined;
+            return this.defaultRequestBody();
         let paramSafeColumns = dreamClass.paramSafeColumnsOrFallback();
         const only = this.requestBody?.only;
         if (only) {
@@ -533,12 +574,17 @@ export default class OpenapiEndpointRenderer {
                     }
             }
         }
+        let processedSchema = this.recursivelyParseBody(openapiName, paramsShape, processedSchemas, {
+            target: 'request',
+        });
+        const bodyPageParam = this.paginate?.body;
+        if (bodyPageParam) {
+            processedSchema = safelyAttachPaginationParamToRequestBodySegment(bodyPageParam, processedSchema);
+        }
         return {
             content: {
                 'application/json': {
-                    schema: this.recursivelyParseBody(openapiName, paramsShape, processedSchemas, {
-                        target: 'request',
-                    }),
+                    schema: processedSchema,
                 },
             },
         };
@@ -653,16 +699,9 @@ export default class OpenapiEndpointRenderer {
         const serializerClass = this.getSerializerClasses()[0];
         if (serializerClass === undefined)
             throw new OpenApiFailedToLookupSerializerForEndpoint(this.controllerClass, this.action);
-        const serializerKey = serializerClass.openapiName;
-        const serializerObject = { $ref: `#/components/schemas/${serializerKey}` };
-        const baseSchema = this.many
-            ? {
-                type: 'array',
-                items: serializerObject,
-            }
-            : this.defaultResponse?.maybeNull
-                ? { anyOf: [serializerObject, { type: 'null' }] }
-                : serializerObject;
+        const baseSchema = this.baseSchemaForSerializerObject({
+            $ref: `#/components/schemas/${serializerClass.openapiName}`,
+        });
         const finalOutput = {
             content: {
                 'application/json': {
@@ -674,6 +713,46 @@ export default class OpenapiEndpointRenderer {
         };
         return finalOutput;
     }
+    /**
+     * @internal
+     *
+     * takes a base serializer object (i.e. { $ref: '#/components/schemas/MySerializer' })
+     * and transforms it based on the openapi renderer options.
+     *
+     * if many, it will return an array of this serializer object.
+     * if paginate, it will return a pagination object with an array of this serializer object
+     * if defaultResponse.maybeNull is set, it will optionally return null as well (only for non-many and non-paginate cases)
+     */
+    baseSchemaForSerializerObject(serializerObject) {
+        if (this.paginate)
+            return {
+                type: 'object',
+                required: ['recordCount', 'pageCount', 'currentPage', 'results'],
+                properties: {
+                    recordCount: {
+                        type: 'number',
+                    },
+                    pageCount: {
+                        type: 'number',
+                    },
+                    currentPage: {
+                        type: 'number',
+                    },
+                    results: {
+                        type: 'array',
+                        items: serializerObject,
+                    },
+                },
+            };
+        if (this.many)
+            return {
+                type: 'array',
+                items: serializerObject,
+            };
+        if (this.defaultResponse?.maybeNull)
+            return { anyOf: [serializerObject, { type: 'null' }] };
+        return serializerObject;
+    }
     /**
      * @internal
      *

package/dist/esm/src/openapi-renderer/helpers/pageParamOpenapiProperty.js

@@ -0,0 +1,6 @@
+export default function openapiPageParamProperty() {
+    return {
+        type: 'integer',
+        description: 'Page number',
+    };
+}

package/dist/esm/src/openapi-renderer/helpers/safelyAttachPaginationParamsToBodySegment.js

@@ -0,0 +1,29 @@
+import openapiPageParamProperty from './pageParamOpenapiProperty.js';
+/**
+ * @internal
+ *
+ * Used to carefully bind implicit pagination params
+ * to the requestBody properties. It will not apply
+ * the pagination param unless the provided bodySegment
+ * is:
+ *
+ * a.) falsey (null, undefined, etc...)
+ * b.) an openapi object (must have { type: 'object'})
+ *
+ * If neither of these apply, it will simply return
+ * what was given to it, without any modifications
+ */
+export default function safelyAttachPaginationParamToRequestBodySegment(paramName, bodySegment) {
+    bodySegment ||= {
+        type: 'object',
+        properties: {},
+    };
+    if (bodySegment.type === 'object') {
+        ;
+        bodySegment.properties = {
+            ...bodySegment.properties,
+            [paramName]: openapiPageParamProperty(),
+        };
+    }
+    return bodySegment;
+}

package/dist/esm/src/psychic-app/index.js

@@ -191,19 +191,10 @@ Try setting it to something valid, like:
     get inflections() {
         return this._inflections;
     }
-    _bootHooks = {
-        boot: [],
-        load: [],
-        'load:dev': [],
-        'load:test': [],
-        'load:prod': [],
-    };
-    get bootHooks() {
-        return this._bootHooks;
-    }
     _specialHooks = {
-        sync: [],
-        serverInit: [],
+        cliSync: [],
+        serverInitBeforeMiddleware: [],
+        serverInitAfterMiddleware: [],
         serverInitAfterRoutes: [],
         serverStart: [],
         serverError: [],
@@ -268,18 +259,6 @@ Try setting it to something valid, like:
         if (this.booted && !force)
             return;
         // await new IntegrityChecker().check()
-        await this.runHooksFor('load');
-        switch (EnvInternal.nodeEnv) {
-            case 'development':
-                await this.runHooksFor('load:dev');
-                break;
-            case 'production':
-                await this.runHooksFor('load:prod');
-                break;
-            case 'test':
-                await this.runHooksFor('load:test');
-                break;
-        }
         await this.inflections?.();
         this.booted = true;
     }
@@ -291,8 +270,11 @@ Try setting it to something valid, like:
             case 'server:error':
                 this._specialHooks.serverError.push(cb);
                 break;
-            case 'server:init':
-                this._specialHooks.serverInit.push(cb);
+            case 'server:init:before-middleware':
+                this._specialHooks.serverInitBeforeMiddleware.push(cb);
+                break;
+            case 'server:init:after-middleware':
+                this._specialHooks.serverInitAfterMiddleware.push(cb);
                 break;
             case 'server:start':
                 this._specialHooks.serverStart.push(cb);
@@ -303,12 +285,10 @@ Try setting it to something valid, like:
             case 'server:init:after-routes':
                 this._specialHooks.serverInitAfterRoutes.push(cb);
                 break;
-            case 'sync':
+            case 'cli:sync':
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                this._specialHooks['sync'].push(cb);
+                this._specialHooks['cliSync'].push(cb);
                 break;
-            default:
-                this.bootHooks[hookEventType].push(cb);
         }
     }
     set(option, unknown1, unknown2) {
@@ -400,10 +380,5 @@ Try setting it to something valid, like:
                 this.overrides['server:start'] = value;
         }
     }
-    async runHooksFor(hookEventType) {
-        for (const hook of this.bootHooks[hookEventType]) {
-            await hook(this);
-        }
-    }
 }
 export const PsychicAppAllowedPackageManagersEnumValues = ['yarn', 'npm', 'pnpm'];

package/dist/esm/src/server/index.js

@@ -45,7 +45,9 @@ export default class PsychicServer {
             });
             next();
         });
-        await this.config['runHooksFor']('boot');
+        for (const serverInitBeforeMiddlewareHook of this.config.specialHooks.serverInitBeforeMiddleware) {
+            await serverInitBeforeMiddlewareHook(this);
+        }
         this.initializeCors();
         this.initializeJSON();
         try {
@@ -59,8 +61,8 @@ export default class PsychicServer {
           ${error.message}
       `);
         }
-        for (const expressInitHook of this.config.specialHooks.serverInit) {
-            await expressInitHook(this);
+        for (const serverInitAfterMiddlewareHook of this.config.specialHooks.serverInitAfterMiddleware) {
+            await serverInitAfterMiddlewareHook(this);
         }
         this.initializeOpenapiValidation();
         await this.buildRoutes();

package/dist/types/src/controller/helpers/isPaginatedResult.d.ts

@@ -0,0 +1 @@
+export default function isPaginatedResult(result: any): boolean;

package/dist/types/src/openapi-renderer/endpoint.d.ts

@@ -9,6 +9,7 @@ export default class OpenapiEndpointRenderer<DreamsOrSerializersOrViewModels ext
     private controllerClass;
     private action;
     private many;
+    private paginate;
     private responses;
     private serializerKey;
     private pathParams;
@@ -39,7 +40,7 @@ export default class OpenapiEndpointRenderer<DreamsOrSerializersOrViewModels ext
      * const json = JSON.encode(openapiJsonContents, null, 2)
      * ```
      */
-    constructor(dreamsOrSerializers: DreamsOrSerializersOrViewModels | null, controllerClass: typeof PsychicController, action: string, { requestBody, headers, many, query, responses, serializerKey, status, tags, security, pathParams, description, summary, omitDefaultHeaders, omitDefaultResponses, defaultResponse, }?: OpenapiEndpointRendererOpts<DreamsOrSerializersOrViewModels>);
+    constructor(dreamsOrSerializers: DreamsOrSerializersOrViewModels | null, controllerClass: typeof PsychicController, action: string, { requestBody, headers, many, paginate, query, responses, serializerKey, status, tags, security, pathParams, description, summary, omitDefaultHeaders, omitDefaultResponses, defaultResponse, }?: OpenapiEndpointRendererOpts<DreamsOrSerializersOrViewModels>);
     /**
      * @internal
      *
@@ -136,6 +137,7 @@ export default class OpenapiEndpointRenderer<DreamsOrSerializersOrViewModels ext
      * Generates the requestBody portion of the endpoint
      */
     private computedRequestBody;
+    private defaultRequestBody;
     /**
      * @internal
      *
@@ -189,6 +191,17 @@ export default class OpenapiEndpointRenderer<DreamsOrSerializersOrViewModels ext
      * ```
      */
     private parseSingleEntitySerializerResponseShape;
+    /**
+     * @internal
+     *
+     * takes a base serializer object (i.e. { $ref: '#/components/schemas/MySerializer' })
+     * and transforms it based on the openapi renderer options.
+     *
+     * if many, it will return an array of this serializer object.
+     * if paginate, it will return a pagination object with an array of this serializer object
+     * if defaultResponse.maybeNull is set, it will optionally return null as well (only for non-many and non-paginate cases)
+     */
+    private baseSchemaForSerializerObject;
     /**
      * @internal
      *
@@ -248,26 +261,282 @@ export declare class MissingControllerActionPairingInRoutes extends Error {
     get message(): string;
 }
 export interface OpenapiEndpointRendererOpts<I extends DreamSerializable | DreamSerializableArray | undefined = undefined> {
+    /**
+     * when true, it will render an openapi document which produces an array of serializables,
+     * rather than a single one.
+     */
     many?: boolean;
+    /**
+     * when true, it will render an openapi document which
+     * produces an object containing pagination data. This
+     * output is formatted to match the format returned
+     * when calling the `paginate` method
+     * within Dream, i.e.
+     *
+     * ```ts
+     * \@OpenAPI(Post, {
+     *   paginate: true,
+     *   status: 200,
+     * })
+     * public async index() {
+     *   const page = this.castParam('page', 'integer')
+     *   const posts = await Post.where(...).paginate({ pageSize: 100, page })
+     *   this.ok(posts)
+     * }
+     * ```
+     */
+    paginate?: boolean | CustomPaginationOpts;
+    /**
+     * specify path params. This is usually not necessary, since path params
+     * are automatically computed for your endpoint by matching against the
+     * corresponding routes.ts entry.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    pathParams: { id: { description: 'The ID of the User' } },
+     *  })
+     * ```
+     */
     pathParams?: OpenapiPathParams;
+    /**
+     * specify additional headers for this request
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    headers: {
+     *      myDate: {
+     *        required: true,
+     *        description: 'my date',
+     *        format: 'date'
+     *      }
+     *    }
+     *  })
+     * ```
+     */
     headers?: OpenapiHeaders;
+    /**
+     * specify query parameters for the request
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    query: {
+     *      search: {
+     *        required: false,
+     *        description: 'my query param',
+     *        schema: {
+     *          type: 'string',
+     *        },
+     *        allowReserved: true,
+     *        allowEmptyValue: true,
+     *      },
+     *    },
+     *  })
+     * ```
+     */
     query?: OpenapiQueries;
+    /**
+     * specify the shape of the request body. For POST, PATCH, and PUT,
+     * this will automatically be done for you if you provide a Dream
+     * class as the first argument. Otherwise, you can specify this
+     * manually, like so:
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    requestBody: {
+     *      type: 'object',
+     *      properties: {
+     *        myFiend: 'string',
+     *      }
+     *    }
+     *  })
+     * ```
+     */
     requestBody?: OpenapiSchemaBodyShorthand | OpenapiSchemaRequestBodyOnlyOption | null;
+    /**
+     * an array of tag names you wish to apply to this endpoint.
+     * tag names will determine placement of this request within
+     * the swagger editor, which is used for previewing openapi
+     * documents.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    tags: ['users']
+     *  })
+     * ```
+     */
     tags?: string[];
+    /**
+     * The top-level description for this endpoint.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    description: 'my endpoint description'
+     *  })
+     * ```
+     */
     description?: string;
+    /**
+     * The top-level summary for this endpoint.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    summary: 'my endpoint summary'
+     *  })
+     * ```
+     */
     summary?: string;
+    /**
+     * which security scheme to use for this endpoint.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 204,
+     *    security: { customAuth: [] },
+     *  })
+     * ```
+     */
     security?: OpenapiSecurity;
+    /**
+     * a list of responses to provide for this endpoint. Only
+     * provide this if you intend to override the automatic
+     * response generation mechanisms built into Psychic.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 201,
+     *    responses: {
+     *      201: {
+     *        type: 'string'
+     *      }
+     *    }
+     *  })
+     * ```
+     */
     responses?: Partial<Record<HttpStatusCode, (OpenapiSchemaBodyShorthand & {
         description?: string;
     }) | {
         description: string;
     }>>;
+    /**
+     * enables you to augment the default response that Psychic
+     * renders. This enables you to allow Psychic to mix in your
+     * custom options with the default response it provides.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 201,
+     *    defaultResponse: {
+     *      description: 'my custom description',
+     *    }
+     *  })
+     * ```
+     */
     defaultResponse?: OpenapiEndpointRendererDefaultResponseOption;
+    /**
+     * provide a custom serializerKey to specify which
+     * serializer should be used when rendering your
+     * serializable entity, i.e.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 201,
+     *    many: true,
+     *    serializerKey: 'summary'
+     *  })
+     * ```
+     */
     serializerKey?: I extends undefined ? never : I extends DreamSerializableArray ? DreamOrViewModelClassSerializerArrayKeys<I> : I extends typeof Dream | ViewModelClass ? DreamOrViewModelClassSerializerKey<I> : never;
+    /**
+     * the status code that your endpoint will render
+     * when it succeeds.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    status: 201,
+     *  })
+     * ```
+     */
     status?: HttpStatusCodeNumber;
+    /**
+     * Whether or not to omit the default headers provided
+     * by your Psychic and your application. When set to true,
+     * you will have to manually specify all headers that
+     * are required for this endpoint.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    omitDefaultHeaders: true
+     *  })
+     * ```
+     */
     omitDefaultHeaders?: boolean;
+    /**
+     * Whether or not to omit the default response provided
+     * by your Psychic and your application. When set to true,
+     * you will have to manually specify the response shape.
+     *
+     * ```ts
+     * \@OpenAPI(User, {
+     *    omitDefaultResponses: true
+     *  })
+     * ```
+     */
     omitDefaultResponses?: boolean;
 }
+export type CustomPaginationOpts = {
+    /**
+     * if provided, a query param will be added to the
+     * openapi spec with the name provided.
+     *
+     * ```ts
+     * @OpenAPI(Post, {
+     *   paginate: {
+     *     query: 'page'
+     *   },
+     * })
+     * public async index() {
+     *   this.ok(
+     *     await this.currentUser
+     *      .associationQuery('posts')
+     *      .paginate({
+     *        page: this.castParam('page', 'integer')
+     *      })
+     *   )
+     * }
+     * ```
+     */
+    query: string;
+} | {
+    /**
+     * if provided, a requestBody field will be added
+     * to the openapi spec with the name provided.
+     *
+     * ```ts
+     * @OpenAPI(Post, {
+     *   paginate: {
+     *     body: 'page'
+     *   },
+     * })
+     * public async index() {
+     *   this.ok(
+     *     await this.currentUser
+     *      .associationQuery('posts')
+     *      .paginate({
+     *        page: this.castParam('page', 'integer')
+     *      })
+     *   )
+     * }
+     * ```
+     */
+    body: string;
+};
 export interface OpenapiEndpointRendererDefaultResponseOption {
     description?: string;
     maybeNull?: boolean;

package/dist/types/src/openapi-renderer/helpers/pageParamOpenapiProperty.d.ts

@@ -0,0 +1,4 @@
+export default function openapiPageParamProperty(): {
+    readonly type: "integer";
+    readonly description: "Page number";
+};

package/dist/types/src/openapi-renderer/helpers/safelyAttachPaginationParamsToBodySegment.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @internal
+ *
+ * Used to carefully bind implicit pagination params
+ * to the requestBody properties. It will not apply
+ * the pagination param unless the provided bodySegment
+ * is:
+ *
+ * a.) falsey (null, undefined, etc...)
+ * b.) an openapi object (must have { type: 'object'})
+ *
+ * If neither of these apply, it will simply return
+ * what was given to it, without any modifications
+ */
+export default function safelyAttachPaginationParamToRequestBodySegment<T>(paramName: string, bodySegment: T): T;

package/dist/types/src/psychic-app/index.d.ts

@@ -7,7 +7,7 @@ import * as http from 'node:http';
 import { OpenapiContent, OpenapiHeaders, OpenapiResponses, OpenapiSecurity, OpenapiSecuritySchemes, OpenapiServer } from '../openapi-renderer/endpoint.js';
 import PsychicRouter from '../router/index.js';
 import PsychicServer from '../server/index.js';
-import { PsychicHookEventType, PsychicHookLoadEventTypes } from './types.js';
+import { PsychicHookEventType } from './types.js';
 import { Command } from 'commander';
 export default class PsychicApp {
     static init(cb: (app: PsychicApp) => void | Promise<void>, dreamCb: (app: DreamApp) => void | Promise<void>, opts?: PsychicAppInitOptions): Promise<PsychicApp>;
@@ -70,8 +70,6 @@ export default class PsychicApp {
     get paths(): Required<PsychicPathOptions>;
     private _inflections?;
     get inflections(): (() => void | Promise<void>) | undefined;
-    private _bootHooks;
-    get bootHooks(): Record<PsychicHookLoadEventTypes, ((conf: PsychicApp) => void | Promise<void>)[]>;
     private _specialHooks;
     get specialHooks(): PsychicAppSpecialHooks;
     private _overrides;
@@ -93,18 +91,18 @@ export default class PsychicApp {
     private booted;
     boot(force?: boolean): Promise<void>;
     plugin(cb: (app: PsychicApp) => void | Promise<void>): void;
-    on<T extends PsychicHookEventType>(hookEventType: T, cb: T extends 'server:error' ? (err: Error, req: Request, res: Response) => void | Promise<void> : T extends 'server:init' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:start' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:shutdown' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-routes' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'cli:start' ? (program: Command) => void | Promise<void> : T extends 'sync' ? () => any : (conf: PsychicApp) => void | Promise<void>): void;
+    on<T extends PsychicHookEventType>(hookEventType: T, cb: T extends 'server:error' ? (err: Error, req: Request, res: Response) => void | Promise<void> : T extends 'server:init:before-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:start' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:shutdown' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-routes' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'cli:start' ? (program: Command) => void | Promise<void> : T extends 'cli:sync' ? () => any : (conf: PsychicApp) => void | Promise<void>): void;
     set(option: 'openapi', name: string, value: NamedPsychicOpenapiOptions): void;
     set<Opt extends PsychicAppOption>(option: Opt, value: Opt extends 'appName' ? string : Opt extends 'apiOnly' ? boolean : Opt extends 'defaultResponseHeaders' ? Record<string, string | null> : Opt extends 'encryption' ? PsychicAppEncryptionOptions : Opt extends 'cors' ? CorsOptions : Opt extends 'cookie' ? CustomCookieOptions : Opt extends 'apiRoot' ? string : Opt extends 'sessionCookieName' ? string : Opt extends 'clientRoot' ? string : Opt extends 'json' ? bodyParser.Options : Opt extends 'logger' ? PsychicLogger : Opt extends 'client' ? PsychicClientOptions : Opt extends 'ssl' ? PsychicSslCredentials : Opt extends 'openapi' ? DefaultPsychicOpenapiOptions : Opt extends 'paths' ? PsychicPathOptions : Opt extends 'port' ? number : Opt extends 'saltRounds' ? number : Opt extends 'packageManager' ? PsychicAppAllowedPackageManagersEnum : Opt extends 'inflections' ? () => void | Promise<void> : Opt extends 'routes' ? (r: PsychicRouter) => void | Promise<void> : never): void;
     override<Override extends keyof PsychicAppOverrides>(override: Override, value: PsychicAppOverrides[Override]): void;
-    private runHooksFor;
 }
 export type PsychicAppOption = 'appName' | 'apiOnly' | 'apiRoot' | 'encryption' | 'sessionCookieName' | 'client' | 'clientRoot' | 'cookie' | 'cors' | 'defaultResponseHeaders' | 'inflections' | 'json' | 'logger' | 'openapi' | 'packageManager' | 'paths' | 'port' | 'routes' | 'saltRounds' | 'ssl';
 export declare const PsychicAppAllowedPackageManagersEnumValues: readonly ["yarn", "npm", "pnpm"];
 export type PsychicAppAllowedPackageManagersEnum = (typeof PsychicAppAllowedPackageManagersEnumValues)[number];
 export interface PsychicAppSpecialHooks {
-    sync: (() => any)[];
-    serverInit: ((server: PsychicServer) => void | Promise<void>)[];
+    cliSync: (() => any)[];
+    serverInitBeforeMiddleware: ((server: PsychicServer) => void | Promise<void>)[];
+    serverInitAfterMiddleware: ((server: PsychicServer) => void | Promise<void>)[];
     serverInitAfterRoutes: ((server: PsychicServer) => void | Promise<void>)[];
     serverStart: ((server: PsychicServer) => void | Promise<void>)[];
     serverShutdown: ((server: PsychicServer) => void | Promise<void>)[];

package/dist/types/src/psychic-app/types.d.ts

@@ -1,7 +1,6 @@
 import PsychicApp from './index.js';
 export type UUID = string;
-export type PsychicHookEventType = 'boot' | 'sync' | 'load' | 'load:dev' | 'load:prod' | 'load:test' | 'server:init' | 'server:init:after-routes' | 'server:start' | 'server:error' | 'server:shutdown';
-export type PsychicHookLoadEventTypes = Exclude<PsychicHookEventType, 'server:error' | 'server:init' | 'server:init:after-routes' | 'server:start' | 'server:shutdown' | 'sync'>;
+export type PsychicHookEventType = 'cli:sync' | 'server:init:before-middleware' | 'server:init:after-middleware' | 'server:init:after-routes' | 'server:start' | 'server:error' | 'server:shutdown';
 export type PsychicAppInitializerCb = (psychicApp: PsychicApp) => void | Promise<void>;
 type Only<T, U> = T & Partial<Record<Exclude<keyof U, keyof T>, never>>;
 export type Either<T, U> = Only<T, U> | Only<U, T>;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "0.34.4",
+  "version": "0.35.0",
   "author": "RVOHealth",
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
   "devDependencies": {
     "@eslint/js": "^9.19.0",
     "@jest-mock/express": "^3.0.0",
-    "@rvoh/dream": "^0.42.0",
+    "@rvoh/dream": "^0.42.3",
     "@rvoh/dream-spec-helpers": "^0.2.4",
     "@rvoh/psychic-spec-helpers": "^0.6.0",
     "@types/express": "^5.0.1",
@@ -83,7 +83,7 @@
     "typedoc": "^0.26.6",
     "typescript": "^5.5.4",
     "typescript-eslint": "=7.18.0",
-    "vitest": "^3.1.1",
+    "vitest": "^3.1.3",
     "winston": "^3.14.2"
   },
   "packageManager": "yarn@4.7.0"