@rvoh/psychic 3.2.0 → 3.3.0

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

@@ -74,3 +74,40 @@ export function OpenAPI(modelOrSerializer, _opts) {
         });
     };
 }
+// eslint-disable-next-line @typescript-eslint/no-namespace
+(function (OpenAPI) {
+    /**
+     * Type-narrowed helper for nesting a Dream-model-driven shape inside a
+     * request body. Returns the same `{ for, only, including, required,
+     * combining }` shape the renderer recognizes natively, but typed via a
+     * function-level generic so `only` / `including` / `required` are
+     * constrained to columns of the model passed as the first argument.
+     *
+     * ```ts
+     * @OpenAPI(ActionPlan, {
+     *   requestBody: {
+     *     including: ['type', 'clientId'],
+     *     combining: {
+     *       planItems: {
+     *         type: 'array',
+     *         items: OpenAPI.forDream(ActionItem, {
+     *           required: ['title', 'type'],
+     *         }),
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * Wrong column names raise a compile-time error:
+     *
+     * ```ts
+     * OpenAPI.forDream(Pet, { including: ['notARealColumn'] })
+     * //                                  ^^^^^^^^^^^^^^^^^ type error
+     * ```
+     */
+    function forDream(model, opts = {}) {
+        return { for: model, ...opts };
+    }
+    OpenAPI.forDream = forDream;
+})(OpenAPI || (OpenAPI = {}));

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

@@ -1,4 +1,4 @@
-import { Ajv } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 /**
  * @internal
@@ -99,7 +99,7 @@ export function createValidator(schema, options = {}) {
         ...options,
         init: undefined,
     };
-    const ajv = new Ajv({
+    const ajv = new Ajv2020({
         removeAdditional: false,
         useDefaults: true,
         strict: false,

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

@@ -51,11 +51,15 @@ export default class SerializerOpenapiRenderer {
         alreadyExtractedDescendantSerializers[this.serializer.globalName] = true;
         const referencedSerializersAndOpenapiSchemaBodyShorthand = this._renderedOpenapi(alreadyExtractedDescendantSerializers);
         if (this.allOfSiblings.length) {
-            const openapi = referencedSerializersAndOpenapiSchemaBodyShorthand.openapi;
+            // Property-level locks live only at the `allOf` wrapper (never on the
+            // inline branch or the `$ref`'d siblings) so that all branches'
+            // properties are visible to `unevaluatedProperties` for the union check.
             return {
                 ...referencedSerializersAndOpenapiSchemaBodyShorthand,
                 openapi: {
-                    allOf: [openapi, ...this.allOfSiblings],
+                    type: 'object',
+                    allOf: [referencedSerializersAndOpenapiSchemaBodyShorthand.openapi, ...this.allOfSiblings],
+                    unevaluatedProperties: false,
                 },
             };
         }
@@ -98,7 +102,13 @@ export default class SerializerOpenapiRenderer {
                 type: 'object',
                 required: sort(uniq(requiredProperties.map(property => this.setCase(property)))),
                 properties: sortObjectByKey(referencedSerializersAndAttributes.attributes),
-                additionalProperties: false,
+                // Property-level locks (`additionalProperties` / `unevaluatedProperties`)
+                // are not emitted on leaf schemas: when a leaf is composed via `$ref`
+                // inside an `allOf`, neither keyword sees properties contributed by
+                // sibling branches, so a per-leaf lock incorrectly rejects flattened
+                // properties. Strictness is enforced at the `allOf`-wrapper level
+                // (`unevaluatedProperties: false`) when flattening occurs, and at the
+                // validation-pipeline level for top-level schemas.
             },
         };
     }

package/dist/cjs/src/openapi-renderer/body-segment.js

@@ -3,6 +3,7 @@ import { DreamApp } from '@rvoh/dream';
 import { openapiShorthandPrimitiveTypes, } from '@rvoh/dream/openapi';
 import NonSerializerSuppliedToSerializerBodySegment from '../error/openapi/NonSerializerSuppliedToSerializerBodySegment.js';
 import isArrayParamName from '../helpers/isArrayParamName.js';
+import buildDreamRequestBodyShape from './helpers/buildDreamRequestBodyShape.js';
 import isBlankDescription from './helpers/isBlankDescription.js';
 import maybeNullOpenapiShorthandToOpenapiShorthand from './helpers/maybeNullOpenapiShorthandToOpenapiShorthand.js';
 import primitiveOpenapiStatementToOpenapi from './helpers/primitiveOpenapiStatementToOpenapi.js';
@@ -20,6 +21,7 @@ import SerializerOpenapiRenderer from './SerializerOpenapiRenderer.js';
  * - Nullable array shorthands like `['string[]', 'null']` → `{ type: ['array', 'null'], items: { type: 'string' } }`
  * - Serializer references like `{ $serializer: SomeSerializer }` → `{ $ref: '#/components/schemas/SerializerOpenapiName' }`
  * - Serializable references like `{ $serializable: SomeModel, key: 'summary' }` → resolved serializer reference
+ * - Nested model-derived request-body references like `{ for: SomeModel, including, only, required, combining }` → an inline object schema derived from the model's param-safe columns (request-only)
  *
  * The class recursively processes nested structures (objects, arrays, unions) and maintains
  * a collection of referenced serializers that need to be included in the final OpenAPI document.
@@ -52,17 +54,19 @@ export default class OpenapiSegmentExpander {
     casing;
     suppressResponseEnums;
     target;
+    source;
     /**
      * @internal
      *
      * Used to recursively expand nested object structures
      * within nested openapi objects
      */
-    constructor(bodySegment, { renderOpts, target }) {
+    constructor(bodySegment, { renderOpts, target, source }) {
         this.bodySegment = bodySegment;
         this.casing = renderOpts.casing;
         this.suppressResponseEnums = renderOpts.suppressResponseEnums;
         this.target = target;
+        this.source = source ?? 'unknown';
     }
     /**
      * returns the shorthanded body segment, rendered
@@ -118,6 +122,8 @@ export default class OpenapiSegmentExpander {
                 return this.serializerStatement(bodySegment);
             case '$serializable':
                 return this.serializableStatement(bodySegment);
+            case '$for':
+                return this.forStatement(bodySegment);
             case 'unknown_object':
                 return {
                     referencedSerializers: [],
@@ -153,6 +159,8 @@ export default class OpenapiSegmentExpander {
             return '$serializer';
         if (serializableRefBodySegment.$serializable)
             return '$serializable';
+        if (typeof bodySegment?.for === 'function')
+            return '$for';
         if (refBodySegment.$ref)
             return '$ref';
         if (schemaRefBodySegment.$schema)
@@ -448,6 +456,40 @@ The following values will be allowed:
         }
         return { referencedSerializers: [serializer], openapi: serializerRef };
     }
+    /**
+     * @internal
+     *
+     * Expand a nested `for:` request-body sentinel into a fully-resolved
+     * `OpenapiSchemaObject`. The sentinel takes the same shape as the
+     * top-level model-driven `requestBody`:
+     *
+     * ```ts
+     * { for: SomeModel, including?, only?, required?, combining? }
+     * ```
+     *
+     * and produces the same shape that the top-level model-driven
+     * `requestBody` produces — param-safe columns inferred from the model,
+     * with `combining` entries (which themselves may contain further `for:`
+     * sentinels) merged into the resulting properties.
+     *
+     * The `for:` sentinel is request-only at the type level. If it is
+     * encountered while expanding a response shape, this method throws —
+     * the type system should have prevented this, so reaching here indicates
+     * a misuse that bypassed type checking (e.g., via `as any`).
+     */
+    forStatement(bodySegment) {
+        if (this.target !== 'request') {
+            throw new Error(`'for:' sentinel is only valid inside request body shorthand; encountered while expanding a response.`);
+        }
+        const ref = bodySegment;
+        const paramsShape = buildDreamRequestBodyShape(ref.for, {
+            only: ref.only,
+            including: ref.including,
+            required: ref.required,
+            combining: ref.combining,
+        }, this.source);
+        return this.recursivelyParseBody(paramsShape);
+    }
     serializableStatement(bodySegment) {
         const serializableRef = bodySegment;
         const key = serializableRef.$serializableSerializerKey || serializableRef.key || 'default';

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

@@ -6,10 +6,9 @@ import NonSerializerDerivedInToSchemaObjects from '../error/openapi/NonSerialize
 import OpenApiSerializerForEndpointNotAFunction from '../error/openapi/SerializerForEndpointNotAFunction.js';
 import isObject from '../helpers/isObject.js';
 import PsychicApp from '../psychic-app/index.js';
-import openapiParamNamesForDreamClass from '../server/helpers/openapiParamNamesForDreamClass.js';
 import OpenapiSegmentExpander from './body-segment.js';
 import { DEFAULT_OPENAPI_RESPONSES } from './defaults.js';
-import { dreamColumnOpenapiShape } from './helpers/dreamColumnOpenapiShape.js';
+import buildDreamRequestBodyShape from './helpers/buildDreamRequestBodyShape.js';
 import openapiOpts from './helpers/openapiOpts.js';
 import openapiRoute from './helpers/openapiRoute.js';
 import safelyAttachCursorPaginationParamToRequestBodySegment from './helpers/safelyAttachCursorPaginationParamToRequestBodySegment.js';
@@ -519,30 +518,19 @@ export default class OpenapiEndpointRenderer {
         const dreamClass = forDreamClass || this.getSingleDreamModelClass();
         if (!dreamClass)
             return this.defaultRequestBody();
-        const { only, including, combining } = (this.requestBody || {});
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const paramSafeColumns = openapiParamNamesForDreamClass(dreamClass, { only, including });
-        const paramsShape = {
-            type: 'object',
-            properties: {},
-        };
-        const required = this.requestBody?.required;
-        if (required) {
-            paramsShape.required = required;
-        }
-        paramsShape.properties = paramSafeColumns.reduce((acc, columnName) => {
-            acc[columnName] = dreamColumnOpenapiShape(this.controllerClass.controllerActionPath(this.action), dreamClass, columnName, undefined, {
-                allowGenericJson: true,
-            });
-            return acc;
-        }, paramsShape.properties);
-        paramsShape.properties = {
-            ...paramsShape.properties,
-            ...(combining || {}),
-        };
+        const { only, including, required, combining } = (this.requestBody ||
+            {});
+        const source = this.controllerClass.controllerActionPath(this.action);
+        const paramsShape = buildDreamRequestBodyShape(dreamClass, {
+            only: only,
+            including: including,
+            required: required,
+            combining: combining,
+        }, source);
         let processedSchema = new OpenapiSegmentExpander(paramsShape, {
             renderOpts,
             target: 'request',
+            source,
         }).render().openapi;
         const bodyPaginationPageParam = this.paginate?.body;
         if (bodyPaginationPageParam) {

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

@@ -0,0 +1,34 @@
+import openapiParamNamesForDreamClass from '../../server/helpers/openapiParamNamesForDreamClass.js';
+import { dreamColumnOpenapiShape } from './dreamColumnOpenapiShape.js';
+/**
+ * @internal
+ *
+ * Builds an unexpanded `OpenapiSchemaObject` for a Dream model's request-body shape,
+ * resolving param-safe columns, attaching `required`, and merging `combining` entries.
+ *
+ * Used by both the top-level model-driven `requestBody` path in `OpenapiEndpointRenderer`
+ * and the `$dream` sentinel expansion inside `OpenapiSegmentExpander`. Single source of
+ * truth keeps top-level and nested semantics identical.
+ */
+export default function buildDreamRequestBodyShape(dreamClass, opts, source) {
+    const { only, including, required, combining } = opts;
+    const paramSafeColumns = openapiParamNamesForDreamClass(dreamClass, { only, including });
+    const paramsShape = {
+        type: 'object',
+        properties: {},
+    };
+    if (required) {
+        paramsShape.required = required;
+    }
+    paramsShape.properties = paramSafeColumns.reduce((acc, columnName) => {
+        acc[columnName] = dreamColumnOpenapiShape(source, dreamClass, columnName, undefined, {
+            allowGenericJson: true,
+        });
+        return acc;
+    }, paramsShape.properties);
+    paramsShape.properties = {
+        ...paramsShape.properties,
+        ...(combining || {}),
+    };
+    return paramsShape;
+}

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

@@ -4,7 +4,10 @@ import CannotInferControllerFromTopLevelRouteError from '../error/router/cannot-
 import pascalizeFileName from '../helpers/pascalizeFileName.js';
 import PsychicApp from '../psychic-app/index.js';
 export function routePath(routePath) {
-    return `/${routePath.replace(/^\//, '')}`;
+    const normalized = `/${routePath.replace(/^\//, '')}`;
+    if (normalized === '/')
+        return normalized;
+    return normalized.replace(/\/+$/, '');
 }
 export function resourcePath(routePath) {
     return `/${routePath}/:id`;

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

@@ -72,7 +72,8 @@ export default class PsychicRouter {
     prefixPathWithNamespaces(str) {
         if (!this.currentNamespaces.length)
             return str;
-        return '/' + this.currentNamespacePaths.join('/') + '/' + str;
+        const prefix = '/' + this.currentNamespacePaths.join('/');
+        return str ? `${prefix}/${str}` : prefix;
     }
     crud(httpMethod, path, controllerOrMiddleware, action) {
         this.checkPathForInvalidChars(path);

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

@@ -74,3 +74,40 @@ export function OpenAPI(modelOrSerializer, _opts) {
         });
     };
 }
+// eslint-disable-next-line @typescript-eslint/no-namespace
+(function (OpenAPI) {
+    /**
+     * Type-narrowed helper for nesting a Dream-model-driven shape inside a
+     * request body. Returns the same `{ for, only, including, required,
+     * combining }` shape the renderer recognizes natively, but typed via a
+     * function-level generic so `only` / `including` / `required` are
+     * constrained to columns of the model passed as the first argument.
+     *
+     * ```ts
+     * @OpenAPI(ActionPlan, {
+     *   requestBody: {
+     *     including: ['type', 'clientId'],
+     *     combining: {
+     *       planItems: {
+     *         type: 'array',
+     *         items: OpenAPI.forDream(ActionItem, {
+     *           required: ['title', 'type'],
+     *         }),
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * Wrong column names raise a compile-time error:
+     *
+     * ```ts
+     * OpenAPI.forDream(Pet, { including: ['notARealColumn'] })
+     * //                                  ^^^^^^^^^^^^^^^^^ type error
+     * ```
+     */
+    function forDream(model, opts = {}) {
+        return { for: model, ...opts };
+    }
+    OpenAPI.forDream = forDream;
+})(OpenAPI || (OpenAPI = {}));

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

@@ -1,4 +1,4 @@
-import { Ajv } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 /**
  * @internal
@@ -99,7 +99,7 @@ export function createValidator(schema, options = {}) {
         ...options,
         init: undefined,
     };
-    const ajv = new Ajv({
+    const ajv = new Ajv2020({
         removeAdditional: false,
         useDefaults: true,
         strict: false,

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

@@ -51,11 +51,15 @@ export default class SerializerOpenapiRenderer {
         alreadyExtractedDescendantSerializers[this.serializer.globalName] = true;
         const referencedSerializersAndOpenapiSchemaBodyShorthand = this._renderedOpenapi(alreadyExtractedDescendantSerializers);
         if (this.allOfSiblings.length) {
-            const openapi = referencedSerializersAndOpenapiSchemaBodyShorthand.openapi;
+            // Property-level locks live only at the `allOf` wrapper (never on the
+            // inline branch or the `$ref`'d siblings) so that all branches'
+            // properties are visible to `unevaluatedProperties` for the union check.
             return {
                 ...referencedSerializersAndOpenapiSchemaBodyShorthand,
                 openapi: {
-                    allOf: [openapi, ...this.allOfSiblings],
+                    type: 'object',
+                    allOf: [referencedSerializersAndOpenapiSchemaBodyShorthand.openapi, ...this.allOfSiblings],
+                    unevaluatedProperties: false,
                 },
             };
         }
@@ -98,7 +102,13 @@ export default class SerializerOpenapiRenderer {
                 type: 'object',
                 required: sort(uniq(requiredProperties.map(property => this.setCase(property)))),
                 properties: sortObjectByKey(referencedSerializersAndAttributes.attributes),
-                additionalProperties: false,
+                // Property-level locks (`additionalProperties` / `unevaluatedProperties`)
+                // are not emitted on leaf schemas: when a leaf is composed via `$ref`
+                // inside an `allOf`, neither keyword sees properties contributed by
+                // sibling branches, so a per-leaf lock incorrectly rejects flattened
+                // properties. Strictness is enforced at the `allOf`-wrapper level
+                // (`unevaluatedProperties: false`) when flattening occurs, and at the
+                // validation-pipeline level for top-level schemas.
             },
         };
     }

package/dist/esm/src/openapi-renderer/body-segment.js

@@ -3,6 +3,7 @@ import { DreamApp } from '@rvoh/dream';
 import { openapiShorthandPrimitiveTypes, } from '@rvoh/dream/openapi';
 import NonSerializerSuppliedToSerializerBodySegment from '../error/openapi/NonSerializerSuppliedToSerializerBodySegment.js';
 import isArrayParamName from '../helpers/isArrayParamName.js';
+import buildDreamRequestBodyShape from './helpers/buildDreamRequestBodyShape.js';
 import isBlankDescription from './helpers/isBlankDescription.js';
 import maybeNullOpenapiShorthandToOpenapiShorthand from './helpers/maybeNullOpenapiShorthandToOpenapiShorthand.js';
 import primitiveOpenapiStatementToOpenapi from './helpers/primitiveOpenapiStatementToOpenapi.js';
@@ -20,6 +21,7 @@ import SerializerOpenapiRenderer from './SerializerOpenapiRenderer.js';
  * - Nullable array shorthands like `['string[]', 'null']` → `{ type: ['array', 'null'], items: { type: 'string' } }`
  * - Serializer references like `{ $serializer: SomeSerializer }` → `{ $ref: '#/components/schemas/SerializerOpenapiName' }`
  * - Serializable references like `{ $serializable: SomeModel, key: 'summary' }` → resolved serializer reference
+ * - Nested model-derived request-body references like `{ for: SomeModel, including, only, required, combining }` → an inline object schema derived from the model's param-safe columns (request-only)
  *
  * The class recursively processes nested structures (objects, arrays, unions) and maintains
  * a collection of referenced serializers that need to be included in the final OpenAPI document.
@@ -52,17 +54,19 @@ export default class OpenapiSegmentExpander {
     casing;
     suppressResponseEnums;
     target;
+    source;
     /**
      * @internal
      *
      * Used to recursively expand nested object structures
      * within nested openapi objects
      */
-    constructor(bodySegment, { renderOpts, target }) {
+    constructor(bodySegment, { renderOpts, target, source }) {
         this.bodySegment = bodySegment;
         this.casing = renderOpts.casing;
         this.suppressResponseEnums = renderOpts.suppressResponseEnums;
         this.target = target;
+        this.source = source ?? 'unknown';
     }
     /**
      * returns the shorthanded body segment, rendered
@@ -118,6 +122,8 @@ export default class OpenapiSegmentExpander {
                 return this.serializerStatement(bodySegment);
             case '$serializable':
                 return this.serializableStatement(bodySegment);
+            case '$for':
+                return this.forStatement(bodySegment);
             case 'unknown_object':
                 return {
                     referencedSerializers: [],
@@ -153,6 +159,8 @@ export default class OpenapiSegmentExpander {
             return '$serializer';
         if (serializableRefBodySegment.$serializable)
             return '$serializable';
+        if (typeof bodySegment?.for === 'function')
+            return '$for';
         if (refBodySegment.$ref)
             return '$ref';
         if (schemaRefBodySegment.$schema)
@@ -448,6 +456,40 @@ The following values will be allowed:
         }
         return { referencedSerializers: [serializer], openapi: serializerRef };
     }
+    /**
+     * @internal
+     *
+     * Expand a nested `for:` request-body sentinel into a fully-resolved
+     * `OpenapiSchemaObject`. The sentinel takes the same shape as the
+     * top-level model-driven `requestBody`:
+     *
+     * ```ts
+     * { for: SomeModel, including?, only?, required?, combining? }
+     * ```
+     *
+     * and produces the same shape that the top-level model-driven
+     * `requestBody` produces — param-safe columns inferred from the model,
+     * with `combining` entries (which themselves may contain further `for:`
+     * sentinels) merged into the resulting properties.
+     *
+     * The `for:` sentinel is request-only at the type level. If it is
+     * encountered while expanding a response shape, this method throws —
+     * the type system should have prevented this, so reaching here indicates
+     * a misuse that bypassed type checking (e.g., via `as any`).
+     */
+    forStatement(bodySegment) {
+        if (this.target !== 'request') {
+            throw new Error(`'for:' sentinel is only valid inside request body shorthand; encountered while expanding a response.`);
+        }
+        const ref = bodySegment;
+        const paramsShape = buildDreamRequestBodyShape(ref.for, {
+            only: ref.only,
+            including: ref.including,
+            required: ref.required,
+            combining: ref.combining,
+        }, this.source);
+        return this.recursivelyParseBody(paramsShape);
+    }
     serializableStatement(bodySegment) {
         const serializableRef = bodySegment;
         const key = serializableRef.$serializableSerializerKey || serializableRef.key || 'default';

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

@@ -6,10 +6,9 @@ import NonSerializerDerivedInToSchemaObjects from '../error/openapi/NonSerialize
 import OpenApiSerializerForEndpointNotAFunction from '../error/openapi/SerializerForEndpointNotAFunction.js';
 import isObject from '../helpers/isObject.js';
 import PsychicApp from '../psychic-app/index.js';
-import openapiParamNamesForDreamClass from '../server/helpers/openapiParamNamesForDreamClass.js';
 import OpenapiSegmentExpander from './body-segment.js';
 import { DEFAULT_OPENAPI_RESPONSES } from './defaults.js';
-import { dreamColumnOpenapiShape } from './helpers/dreamColumnOpenapiShape.js';
+import buildDreamRequestBodyShape from './helpers/buildDreamRequestBodyShape.js';
 import openapiOpts from './helpers/openapiOpts.js';
 import openapiRoute from './helpers/openapiRoute.js';
 import safelyAttachCursorPaginationParamToRequestBodySegment from './helpers/safelyAttachCursorPaginationParamToRequestBodySegment.js';
@@ -519,30 +518,19 @@ export default class OpenapiEndpointRenderer {
         const dreamClass = forDreamClass || this.getSingleDreamModelClass();
         if (!dreamClass)
             return this.defaultRequestBody();
-        const { only, including, combining } = (this.requestBody || {});
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const paramSafeColumns = openapiParamNamesForDreamClass(dreamClass, { only, including });
-        const paramsShape = {
-            type: 'object',
-            properties: {},
-        };
-        const required = this.requestBody?.required;
-        if (required) {
-            paramsShape.required = required;
-        }
-        paramsShape.properties = paramSafeColumns.reduce((acc, columnName) => {
-            acc[columnName] = dreamColumnOpenapiShape(this.controllerClass.controllerActionPath(this.action), dreamClass, columnName, undefined, {
-                allowGenericJson: true,
-            });
-            return acc;
-        }, paramsShape.properties);
-        paramsShape.properties = {
-            ...paramsShape.properties,
-            ...(combining || {}),
-        };
+        const { only, including, required, combining } = (this.requestBody ||
+            {});
+        const source = this.controllerClass.controllerActionPath(this.action);
+        const paramsShape = buildDreamRequestBodyShape(dreamClass, {
+            only: only,
+            including: including,
+            required: required,
+            combining: combining,
+        }, source);
         let processedSchema = new OpenapiSegmentExpander(paramsShape, {
             renderOpts,
             target: 'request',
+            source,
         }).render().openapi;
         const bodyPaginationPageParam = this.paginate?.body;
         if (bodyPaginationPageParam) {

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

@@ -0,0 +1,34 @@
+import openapiParamNamesForDreamClass from '../../server/helpers/openapiParamNamesForDreamClass.js';
+import { dreamColumnOpenapiShape } from './dreamColumnOpenapiShape.js';
+/**
+ * @internal
+ *
+ * Builds an unexpanded `OpenapiSchemaObject` for a Dream model's request-body shape,
+ * resolving param-safe columns, attaching `required`, and merging `combining` entries.
+ *
+ * Used by both the top-level model-driven `requestBody` path in `OpenapiEndpointRenderer`
+ * and the `$dream` sentinel expansion inside `OpenapiSegmentExpander`. Single source of
+ * truth keeps top-level and nested semantics identical.
+ */
+export default function buildDreamRequestBodyShape(dreamClass, opts, source) {
+    const { only, including, required, combining } = opts;
+    const paramSafeColumns = openapiParamNamesForDreamClass(dreamClass, { only, including });
+    const paramsShape = {
+        type: 'object',
+        properties: {},
+    };
+    if (required) {
+        paramsShape.required = required;
+    }
+    paramsShape.properties = paramSafeColumns.reduce((acc, columnName) => {
+        acc[columnName] = dreamColumnOpenapiShape(source, dreamClass, columnName, undefined, {
+            allowGenericJson: true,
+        });
+        return acc;
+    }, paramsShape.properties);
+    paramsShape.properties = {
+        ...paramsShape.properties,
+        ...(combining || {}),
+    };
+    return paramsShape;
+}

package/dist/esm/src/router/helpers.js

@@ -4,7 +4,10 @@ import CannotInferControllerFromTopLevelRouteError from '../error/router/cannot-
 import pascalizeFileName from '../helpers/pascalizeFileName.js';
 import PsychicApp from '../psychic-app/index.js';
 export function routePath(routePath) {
-    return `/${routePath.replace(/^\//, '')}`;
+    const normalized = `/${routePath.replace(/^\//, '')}`;
+    if (normalized === '/')
+        return normalized;
+    return normalized.replace(/\/+$/, '');
 }
 export function resourcePath(routePath) {
     return `/${routePath}/:id`;

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

@@ -72,7 +72,8 @@ export default class PsychicRouter {
     prefixPathWithNamespaces(str) {
         if (!this.currentNamespaces.length)
             return str;
-        return '/' + this.currentNamespacePaths.join('/') + '/' + str;
+        const prefix = '/' + this.currentNamespacePaths.join('/');
+        return str ? `${prefix}/${str}` : prefix;
     }
     crud(httpMethod, path, controllerOrMiddleware, action) {
         this.checkPathForInvalidChars(path);

package/dist/types/src/controller/decorators.d.ts

@@ -1,6 +1,6 @@
 import { Dream } from '@rvoh/dream';
-import { DreamSerializable, DreamSerializableArray } from '@rvoh/dream/types';
-import { OpenapiEndpointRendererOpts } from '../openapi-renderer/endpoint.js';
+import { DreamParamSafeAttributes, DreamSerializable, DreamSerializableArray, UpdateableProperties } from '@rvoh/dream/types';
+import { OpenapiEndpointRendererOpts, OpenapiSchemaNestedFor, OpenapiSchemaRequestPropertiesShorthandWithFor } from '../openapi-renderer/endpoint.js';
 export declare function BeforeAction(opts?: {
     isStatic?: boolean;
     only?: string[];
@@ -9,3 +9,41 @@ export declare function BeforeAction(opts?: {
 export declare function OpenAPI(): any;
 export declare function OpenAPI<const ForOption extends typeof Dream>(opts: OpenapiEndpointRendererOpts<undefined, ForOption>): any;
 export declare function OpenAPI<const I extends DreamSerializable | DreamSerializableArray, const ForOption extends typeof Dream>(modelOrSerializer: I, opts?: OpenapiEndpointRendererOpts<I, ForOption>): any;
+export declare namespace OpenAPI {
+    /**
+     * Type-narrowed helper for nesting a Dream-model-driven shape inside a
+     * request body. Returns the same `{ for, only, including, required,
+     * combining }` shape the renderer recognizes natively, but typed via a
+     * function-level generic so `only` / `including` / `required` are
+     * constrained to columns of the model passed as the first argument.
+     *
+     * ```ts
+     * @OpenAPI(ActionPlan, {
+     *   requestBody: {
+     *     including: ['type', 'clientId'],
+     *     combining: {
+     *       planItems: {
+     *         type: 'array',
+     *         items: OpenAPI.forDream(ActionItem, {
+     *           required: ['title', 'type'],
+     *         }),
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * Wrong column names raise a compile-time error:
+     *
+     * ```ts
+     * OpenAPI.forDream(Pet, { including: ['notARealColumn'] })
+     * //                                  ^^^^^^^^^^^^^^^^^ type error
+     * ```
+     */
+    function forDream<const M extends typeof Dream>(model: M, opts?: {
+        only?: readonly (keyof DreamParamSafeAttributes<InstanceType<M>>)[];
+        including?: readonly Exclude<keyof UpdateableProperties<InstanceType<M>>, keyof DreamParamSafeAttributes<InstanceType<M>>>[];
+        required?: readonly (keyof UpdateableProperties<InstanceType<M>>)[];
+        combining?: OpenapiSchemaRequestPropertiesShorthandWithFor;
+    }): OpenapiSchemaNestedFor;
+}

package/dist/types/src/helpers/validateOpenApiSchema.d.ts

@@ -1,4 +1,5 @@
-import { Ajv, type ErrorObject, type JSONSchemaType, type ValidateFunction } from 'ajv';
+import { type ErrorObject, type JSONSchemaType, type ValidateFunction } from 'ajv';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 /**
  * @internal
  *
@@ -72,8 +73,8 @@ export interface ValidationError {
     message: string;
     params?: Record<string, unknown>;
 }
-export type AjvValidationOpts = ConstructorParameters<typeof Ajv>[0];
+export type AjvValidationOpts = ConstructorParameters<typeof Ajv2020>[0];
 export type ValidateOpenapiSchemaOptions = AjvValidationOpts & CustomOpenapiValidationOptions;
 export interface CustomOpenapiValidationOptions {
-    init?: (ajv: Ajv) => void;
+    init?: (ajv: Ajv2020) => void;
 }

package/dist/types/src/openapi-renderer/body-segment.d.ts

@@ -4,6 +4,13 @@ import { OpenapiEndpointResponse, OpenapiRenderOpts, OpenapiResponses } from './
 export interface OpenapiBodySegmentRendererOpts {
     renderOpts: OpenapiRenderOpts;
     target: OpenapiBodyTarget;
+    /**
+     * Identifier (typically a controller-action path) used to enrich error
+     * messages emitted by `dreamColumnOpenapiShape` when an unrecognized DB
+     * type is encountered while expanding a `$dream` sentinel. Optional —
+     * defaults to `'unknown'` when not supplied.
+     */
+    source?: string;
 }
 /**
  * @internal
@@ -17,6 +24,7 @@ export interface OpenapiBodySegmentRendererOpts {
  * - Nullable array shorthands like `['string[]', 'null']` → `{ type: ['array', 'null'], items: { type: 'string' } }`
  * - Serializer references like `{ $serializer: SomeSerializer }` → `{ $ref: '#/components/schemas/SerializerOpenapiName' }`
  * - Serializable references like `{ $serializable: SomeModel, key: 'summary' }` → resolved serializer reference
+ * - Nested model-derived request-body references like `{ for: SomeModel, including, only, required, combining }` → an inline object schema derived from the model's param-safe columns (request-only)
  *
  * The class recursively processes nested structures (objects, arrays, unions) and maintains
  * a collection of referenced serializers that need to be included in the final OpenAPI document.
@@ -49,13 +57,14 @@ export default class OpenapiSegmentExpander {
     private casing;
     private suppressResponseEnums;
     private target;
+    private source;
     /**
      * @internal
      *
      * Used to recursively expand nested object structures
      * within nested openapi objects
      */
-    constructor(bodySegment: OpenapiBodySegment, { renderOpts, target }: OpenapiBodySegmentRendererOpts);
+    constructor(bodySegment: OpenapiBodySegment, { renderOpts, target, source }: OpenapiBodySegmentRendererOpts);
     /**
      * returns the shorthanded body segment, rendered
      * to the appropriate openapi shape
@@ -138,6 +147,28 @@ export default class OpenapiSegmentExpander {
      * recursively a $ref statement
      */
     private serializerStatement;
+    /**
+     * @internal
+     *
+     * Expand a nested `for:` request-body sentinel into a fully-resolved
+     * `OpenapiSchemaObject`. The sentinel takes the same shape as the
+     * top-level model-driven `requestBody`:
+     *
+     * ```ts
+     * { for: SomeModel, including?, only?, required?, combining? }
+     * ```
+     *
+     * and produces the same shape that the top-level model-driven
+     * `requestBody` produces — param-safe columns inferred from the model,
+     * with `combining` entries (which themselves may contain further `for:`
+     * sentinels) merged into the resulting properties.
+     *
+     * The `for:` sentinel is request-only at the type level. If it is
+     * encountered while expanding a response shape, this method throws —
+     * the type system should have prevented this, so reaching here indicates
+     * a misuse that bypassed type checking (e.g., via `as any`).
+     */
+    private forStatement;
     private serializableStatement;
     /**
      * @internal

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

@@ -1,5 +1,5 @@
 import { Dream } from '@rvoh/dream';
-import { OpenapiAllTypes, OpenapiFormats, OpenapiSchemaArray, OpenapiSchemaBody, OpenapiSchemaBodyShorthand, OpenapiSchemaExpressionAllOf, OpenapiSchemaExpressionAnyOf, OpenapiSchemaExpressionOneOf, OpenapiSchemaExpressionRef, OpenapiSchemaObject, OpenapiSchemaProperties, OpenapiSchemaPropertiesShorthand } from '@rvoh/dream/openapi';
+import { OpenapiAllTypes, OpenapiFormats, OpenapiSchemaArray, OpenapiSchemaBody, OpenapiSchemaBodyShorthand, OpenapiSchemaExpressionAllOf, OpenapiSchemaExpressionAnyOf, OpenapiSchemaExpressionOneOf, OpenapiSchemaExpressionRef, OpenapiSchemaObject, OpenapiSchemaProperties, OpenapiSchemaPropertiesShorthand, OpenapiShorthandPrimitiveTypes } from '@rvoh/dream/openapi';
 import { DreamAttributes, DreamOrViewModelClassSerializerKey, DreamParamSafeAttributes, DreamSerializable, DreamSerializableArray, SerializerCasing, UpdateableProperties, ViewModelClass } from '@rvoh/dream/types';
 import PsychicController from '../controller/index.js';
 import { HttpStatusCode, HttpStatusCodeNumber } from '../error/http/status-codes.js';
@@ -453,7 +453,7 @@ export interface OpenapiEndpointRendererOpts<I extends DreamSerializable | Dream
      *  })
      * ```
      */
-    requestBody?: OpenapiSchemaBodyShorthand | OpenapiSchemaRequestBodyForOption<I, ForOption> | null;
+    requestBody?: OpenapiSchemaRequestBodyShorthandWithFor | OpenapiSchemaRequestBodyForOption<I, ForOption> | null;
     /**
      * an array of tag names you wish to apply to this endpoint.
      * tag names will determine placement of this request within
@@ -745,6 +745,80 @@ export interface OpenapiEndpointRendererDefaultResponseOption {
     description?: string;
     maybeNull?: boolean;
 }
+/**
+ * @internal
+ *
+ * Predecessor map used to decrement a depth counter inside recursive
+ * `$dream` shorthand types. Capped at 3 levels of `$dream`-aware
+ * recursion; beyond that the shape falls back to the unconstrained
+ * Dream-side `OpenapiSchemaPropertiesShorthand` and accepts but does
+ * not narrow further nesting.
+ */
+type DreamShorthandPrev = [never, 0, 1, 2, 3];
+/**
+ * Nested model-derived request-body shorthand. Same shape as the
+ * top-level model-driven `requestBody` (with `for:` naming the model),
+ * but usable at any nesting site — inside `combining`, inside raw
+ * `properties` of a non-model body, and inside `items` of an array.
+ *
+ * Mirrors the response-side `$serializable` / `$serializer` keys
+ * recognized by `OpenapiSegmentExpander`, but expands via param-safe
+ * column derivation instead of serializer resolution.
+ *
+ * `for:` at this nesting position is request-only at the type level.
+ * Response shorthand types do not include it.
+ *
+ * ```ts
+ * @OpenAPI(ActionPlan, {
+ *   requestBody: {
+ *     including: ['type', 'clientId'],
+ *     combining: {
+ *       planItems: {
+ *         type: 'array',
+ *         items: { for: ActionItem, required: ['title', 'type'] },
+ *       },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export type OpenapiSchemaNestedFor<Depth extends 0 | 1 | 2 | 3 = 3> = {
+    for: typeof Dream;
+    including?: readonly string[];
+    only?: readonly string[];
+    required?: readonly string[];
+    combining?: Depth extends 0 ? OpenapiSchemaPropertiesShorthand : OpenapiSchemaRequestPropertiesShorthandWithFor<DreamShorthandPrev[Depth] & (0 | 1 | 2 | 3)>;
+};
+/**
+ * Property-shorthand record (request-only) whose values may be any of
+ * the existing Dream-side body shorthands OR a nested `for:` sentinel.
+ * Used as the type of `combining` and as the value type of nested
+ * `properties` / `items` in request bodies.
+ *
+ * `for:`-aware recursion is depth-bounded (cap = 3); past the cap the
+ * value type falls back to the unconstrained Dream-side shorthand to
+ * avoid TypeScript "type instantiation is excessively deep" errors.
+ */
+export interface OpenapiSchemaRequestPropertiesShorthandWithFor<Depth extends 0 | 1 | 2 | 3 = 3> {
+    [key: string]: OpenapiSchemaRequestBodyShorthandWithFor<Depth> | OpenapiShorthandPrimitiveTypes;
+}
+/**
+ * Body-shorthand value (request-only) — a Dream-side shorthand OR a
+ * nested `for:` sentinel OR an object/array shape whose nested values
+ * may themselves contain `for:`. Recurses through `items` and
+ * `properties` with a bounded depth.
+ */
+export type OpenapiSchemaRequestBodyShorthandWithFor<Depth extends 0 | 1 | 2 | 3 = 3> = OpenapiSchemaBodyShorthand | OpenapiSchemaNestedFor<Depth> | {
+    type: 'array' | readonly ['array', 'null'] | readonly ['null', 'array'];
+    items: OpenapiSchemaRequestBodyShorthandWithFor<Depth>;
+    description?: string;
+} | {
+    type: 'object' | readonly ['object', 'null'] | readonly ['null', 'object'];
+    properties?: OpenapiSchemaRequestPropertiesShorthandWithFor<Depth>;
+    required?: readonly string[];
+    description?: string;
+    additionalProperties?: boolean | OpenapiSchemaRequestBodyShorthandWithFor<Depth>;
+};
 export type OpenapiSchemaRequestBodyForOption<Serializable extends DreamSerializable | DreamSerializableArray | undefined, ForOption extends typeof Dream | undefined = undefined> = OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof Dream ? ForOption : typeof Dream> | OpenapiSchemaRequestBodyForBaseDreamClass<Serializable>;
 export interface OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof Dream> {
     /**
@@ -818,7 +892,7 @@ export interface OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof
     including?: Exclude<keyof UpdateableProperties<InstanceType<ForOption>>, keyof DreamParamSafeAttributes<InstanceType<ForOption>>>[];
     /**
      * expand the included fields to allow additional fields
-     * that are unrelated to the model's params
+     * that are unrelated to the model's params.
      *
      * ```ts
      * @OpenAPI({
@@ -833,8 +907,35 @@ export interface OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof
      *   ...
      * }
      * ```
+     *
+     * `combining` values may also be a nested `for:` sentinel — the same
+     * shape as the top-level model-driven `requestBody`, just nested. It
+     * derives an object schema from another Dream model's param-safe
+     * columns and accepts the same `including` / `only` / `required` /
+     * `combining` siblings.
+     *
+     * ```ts
+     * @OpenAPI(ActionPlan, {
+     *   requestBody: {
+     *     including: ['type', 'clientId'],
+     *     combining: {
+     *       planItems: {
+     *         type: 'array',
+     *         items: {
+     *           for: ActionItem,
+     *           required: ['title', 'type'],
+     *         },
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * The nested `for:` sentinel is request-only; it is not accepted in
+     * `responses` shorthand (use the existing `$serializable` / `$serializer`
+     * keys there).
      */
-    combining?: OpenapiSchemaPropertiesShorthand;
+    combining?: OpenapiSchemaRequestPropertiesShorthandWithFor;
     /**
      * Specify which fields are required for your openapi
      * request body.
@@ -897,7 +998,7 @@ export interface OpenapiSchemaRequestBodyForBaseDreamClass<Serializable extends
     including?: Including;
     /**
      * expand the included fields to allow additional fields
-     * that are unrelated to the model's params
+     * that are unrelated to the model's params.
      *
      * ```ts
      * @OpenAPI({
@@ -912,8 +1013,35 @@ export interface OpenapiSchemaRequestBodyForBaseDreamClass<Serializable extends
      *   ...
      * }
      * ```
+     *
+     * `combining` values may also be a nested `for:` sentinel — the same
+     * shape as the top-level model-driven `requestBody`, just nested. It
+     * derives an object schema from another Dream model's param-safe
+     * columns and accepts the same `including` / `only` / `required` /
+     * `combining` siblings.
+     *
+     * ```ts
+     * @OpenAPI(ActionPlan, {
+     *   requestBody: {
+     *     including: ['type', 'clientId'],
+     *     combining: {
+     *       planItems: {
+     *         type: 'array',
+     *         items: {
+     *           for: ActionItem,
+     *           required: ['title', 'type'],
+     *         },
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * The nested `for:` sentinel is request-only; it is not accepted in
+     * `responses` shorthand (use the existing `$serializable` / `$serializer`
+     * keys there).
      */
-    combining?: OpenapiSchemaPropertiesShorthand;
+    combining?: OpenapiSchemaRequestPropertiesShorthandWithFor;
     /**
      * Specify which fields are required for your openapi
      * request body.
@@ -1051,3 +1179,4 @@ export interface ReferencedSerializersAndOpenapiContent {
     referencedSerializers: SerializerArray;
     openapi: OpenapiContent;
 }
+export {};

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

@@ -0,0 +1,19 @@
+import { Dream } from '@rvoh/dream';
+import { OpenapiSchemaObject } from '@rvoh/dream/openapi';
+export interface BuildDreamRequestBodyShapeOpts {
+    only?: readonly string[] | undefined;
+    including?: readonly string[] | undefined;
+    required?: readonly string[] | undefined;
+    combining?: Record<string, unknown> | undefined;
+}
+/**
+ * @internal
+ *
+ * Builds an unexpanded `OpenapiSchemaObject` for a Dream model's request-body shape,
+ * resolving param-safe columns, attaching `required`, and merging `combining` entries.
+ *
+ * Used by both the top-level model-driven `requestBody` path in `OpenapiEndpointRenderer`
+ * and the `$dream` sentinel expansion inside `OpenapiSegmentExpander`. Single source of
+ * truth keeps top-level and nested semantics identical.
+ */
+export default function buildDreamRequestBodyShape(dreamClass: typeof Dream, opts: BuildDreamRequestBodyShapeOpts, source: string): OpenapiSchemaObject;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "author": "RVOHealth",
   "repository": {
     "type": "git",