@rvoh/psychic 3.7.0 → 3.8.0

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

@@ -78,9 +78,9 @@ export function OpenAPI(modelOrSerializer, _opts) {
 (function (OpenAPI) {
     /**
      * Type-narrowed helper for nesting a Dream-model-driven shape inside a
-     * request body. Returns the same `{ for, only, including, required,
+     * request body. Returns the same `{ for, params, including, required,
      * combining }` shape the renderer recognizes natively, but typed via a
-     * function-level generic so `only` / `including` / `required` are
+     * function-level generic so `params` / `including` / `required` are
      * constrained to columns of the model passed as the first argument.
      *
      * ```ts

package/dist/cjs/src/generate/helpers/generateControllerContent.js

@@ -51,7 +51,7 @@ export default function generateControllerContent({ ancestorName, ancestorImport
     description: 'Create ${aOrAnDreamModelName(modelClassName)}',${defaultOpenapiSerializerKeyProperty}
     fastJsonStringify: true,
     requestBody: {
-      only: paramSafeColumns,
+      params: paramSafeColumns,
     },
   })
   public async create() {
@@ -130,7 +130,7 @@ export default function generateControllerContent({ ancestorName, ancestorImport
     description: 'Update ${aOrAnDreamModelName(modelClassName)}',
     fastJsonStringify: true,
     requestBody: {
-      only: paramSafeColumns,
+      params: paramSafeColumns,
     },
   })
   public async update() {

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

@@ -21,7 +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)
+ * - Nested model-derived request-body references like `{ for: SomeModel, params, including, 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.
@@ -483,6 +483,7 @@ The following values will be allowed:
         }
         const ref = bodySegment;
         const paramsShape = buildDreamRequestBodyShape(ref.for, {
+            params: ref.params,
             only: ref.only,
             including: ref.including,
             required: ref.required,

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

@@ -492,6 +492,8 @@ export default class OpenapiEndpointRenderer {
         const body = this.requestBody;
         if (!body)
             return true;
+        if (body.params)
+            return true;
         if (body.only)
             return true;
         if (body.including)
@@ -518,10 +520,11 @@ export default class OpenapiEndpointRenderer {
         const dreamClass = forDreamClass || this.getSingleDreamModelClass();
         if (!dreamClass)
             return this.defaultRequestBody();
-        const { only, including, required, combining } = (this.requestBody ||
+        const { params, only, including, required, combining } = (this.requestBody ||
             {});
         const source = this.controllerClass.controllerActionPath(this.action);
         const paramsShape = buildDreamRequestBodyShape(dreamClass, {
+            params: params,
             only: only,
             including: including,
             required: required,

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

@@ -11,8 +11,11 @@ import { dreamColumnOpenapiShape } from './dreamColumnOpenapiShape.js';
  * 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 { params, only, including, required, combining } = opts;
+    const paramSafeColumns = openapiParamNamesForDreamClass(dreamClass, {
+        only: params ?? only,
+        including,
+    });
     const paramsShape = {
         type: 'object',
         properties: {},

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

@@ -53,7 +53,8 @@ export default class Params {
                     returnObj[columnName] = this.cast(params, columnName.toString(), castType, { allowNull: columnMetadata.allowNull });
                 }
                 else if (dreamClass.isVirtualColumn(columnName)) {
-                    returnObj[columnName] = params[columnName];
+                    const virtualCast = virtualAttributeCast(dreamClass, columnName);
+                    returnObj[columnName] = this.cast(params, columnName.toString(), virtualCast.expectedType, { allowNull: virtualCast.allowNull });
                 }
                 else if (columnMetadata?.enumValues) {
                     const paramValue = params[columnName];
@@ -167,9 +168,10 @@ export default class Params {
         if (paramValue === null || paramValue === undefined) {
             if (expectedType === 'null')
                 return null;
-            if (!this.shouldUseOpenapiValidation(expectedType)) {
-                this.throwUnlessAllowNull(paramName, paramValue, typeToError(expectedType), opts);
+            if (this.shouldUseOpenapiValidation(expectedType)) {
+                return this.validateOpenapiOrThrow(paramName, paramValue, expectedType);
             }
+            this.throwUnlessAllowNull(paramName, paramValue, typeToError(expectedType), opts);
             return paramValue;
         }
         const integerRegexp = /^-?\d+$/;
@@ -298,13 +300,7 @@ export default class Params {
                 return paramValue.map(param => this.cast(paramName, param, arrayTypeToNonArrayType(expectedType), { ...opts, allowNull: true }));
             default:
                 if (this.shouldUseOpenapiValidation(expectedType)) {
-                    const res = validateObject(paramValue, expectedType, { coerceTypes: true });
-                    if (res.isValid) {
-                        return res.data;
-                    }
-                    else {
-                        throw new ParamValidationError(paramName, res.errors?.map(err => err.message) || ['openapi validation failed']);
-                    }
+                    return this.validateOpenapiOrThrow(paramName, paramValue, expectedType);
                 }
                 // TODO: serialize/sanitize before printing, handle array types
                 throw new Error(`Unexpected point reached in code. need to handle type for ${expectedType}`);
@@ -313,6 +309,12 @@ export default class Params {
     shouldUseOpenapiValidation(expectedType) {
         return isObject(expectedType);
     }
+    validateOpenapiOrThrow(paramName, paramValue, expectedType) {
+        const res = validateObject(paramValue, expectedType, { coerceTypes: true });
+        if (res.isValid)
+            return res.data;
+        throw new ParamValidationError(paramName, res.errors?.map(err => err.message) || ['openapi validation failed']);
+    }
     restrict(allowed) {
         const params = this.$params;
         const permitted = {};
@@ -403,6 +405,121 @@ const DB_TYPE_TO_CAST_TYPE = {
     numeric: 'number',
     'numeric[]': 'number[]',
 };
+function virtualAttributeCast(dreamClass, columnName) {
+    const metadata = dreamClass['virtualAttributes'].find(statement => statement.property === columnName);
+    const primitiveCast = primitiveCastFromOpenapi(metadata?.type);
+    if (!primitiveCast)
+        throw new Error(`Unable to infer params cast type for virtual column: ${columnName}`);
+    return primitiveCast;
+}
+function primitiveCastFromOpenapi(openapi) {
+    if (!openapi)
+        return null;
+    if (Array.isArray(openapi)) {
+        const nonNullOpenapi = openapi.find(type => type !== 'null');
+        const primitiveCast = primitiveCastFromOpenapi(nonNullOpenapi);
+        if (!primitiveCast)
+            return null;
+        return { ...primitiveCast, allowNull: true };
+    }
+    if (typeof openapi === 'string') {
+        const expectedType = shorthandToCastType(openapi);
+        return expectedType ? { expectedType, allowNull: false } : null;
+    }
+    if (!('type' in openapi))
+        return null;
+    const openapiType = openapi.type;
+    const allowNull = Array.isArray(openapiType) && openapiType.includes('null');
+    const nonNullType = Array.isArray(openapiType) ? openapiType.find(type => type !== 'null') : openapiType;
+    if (nonNullType === 'array') {
+        if (!('items' in openapi))
+            return null;
+        const item = openapi.items;
+        const itemType = item && 'type' in item ? item.type : undefined;
+        const itemFormat = item && 'format' in item ? item.format : undefined;
+        if (Array.isArray(itemType))
+            return null;
+        const itemCastType = openapiTypeToCastType(itemType, itemFormat);
+        if (!itemCastType)
+            return null;
+        return { expectedType: `${itemCastType}[]`, allowNull };
+    }
+    const expectedType = openapiTypeToCastType(nonNullType, 'format' in openapi ? openapi.format : undefined);
+    return expectedType ? { expectedType, allowNull } : null;
+}
+function shorthandToCastType(openapi) {
+    switch (openapi) {
+        case 'date-time':
+            return 'datetime';
+        case 'date-time[]':
+            return 'datetime[]';
+        case 'decimal':
+            return 'number';
+        case 'decimal[]':
+            return 'number[]';
+        case 'json':
+            return 'json';
+        case 'null':
+            return 'null';
+        default:
+            return PARAM_CAST_TYPES.includes(openapi)
+                ? openapi
+                : null;
+    }
+}
+function openapiTypeToCastType(openapiType, format) {
+    switch (openapiType) {
+        case 'boolean':
+            return 'boolean';
+        case 'integer':
+            return 'integer';
+        case 'number':
+            return 'number';
+        case 'null':
+            return 'null';
+        case 'object':
+            return 'json';
+        case 'string':
+            switch (format) {
+                case 'date':
+                    return 'date';
+                case 'date-time':
+                    return 'datetime';
+                case 'uuid':
+                    return 'uuid';
+                default:
+                    return 'string';
+            }
+        default:
+            return null;
+    }
+}
+const PARAM_CAST_TYPES = [
+    'bigint',
+    'bigint[]',
+    'boolean',
+    'boolean[]',
+    'date',
+    'date[]',
+    'datetime',
+    'datetime[]',
+    'integer',
+    'integer[]',
+    'json',
+    'json[]',
+    'null',
+    'null[]',
+    'number',
+    'number[]',
+    'string',
+    'string[]',
+    'time',
+    'time[]',
+    'timetz',
+    'timetz[]',
+    'uuid',
+    'uuid[]',
+];
 const typeToErrorMap = {
     bigint: 'expected bigint',
     boolean: 'expected boolean',

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

@@ -78,9 +78,9 @@ export function OpenAPI(modelOrSerializer, _opts) {
 (function (OpenAPI) {
     /**
      * Type-narrowed helper for nesting a Dream-model-driven shape inside a
-     * request body. Returns the same `{ for, only, including, required,
+     * request body. Returns the same `{ for, params, including, required,
      * combining }` shape the renderer recognizes natively, but typed via a
-     * function-level generic so `only` / `including` / `required` are
+     * function-level generic so `params` / `including` / `required` are
      * constrained to columns of the model passed as the first argument.
      *
      * ```ts

package/dist/esm/src/generate/helpers/generateControllerContent.js

@@ -51,7 +51,7 @@ export default function generateControllerContent({ ancestorName, ancestorImport
     description: 'Create ${aOrAnDreamModelName(modelClassName)}',${defaultOpenapiSerializerKeyProperty}
     fastJsonStringify: true,
     requestBody: {
-      only: paramSafeColumns,
+      params: paramSafeColumns,
     },
   })
   public async create() {
@@ -130,7 +130,7 @@ export default function generateControllerContent({ ancestorName, ancestorImport
     description: 'Update ${aOrAnDreamModelName(modelClassName)}',
     fastJsonStringify: true,
     requestBody: {
-      only: paramSafeColumns,
+      params: paramSafeColumns,
     },
   })
   public async update() {

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

@@ -21,7 +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)
+ * - Nested model-derived request-body references like `{ for: SomeModel, params, including, 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.
@@ -483,6 +483,7 @@ The following values will be allowed:
         }
         const ref = bodySegment;
         const paramsShape = buildDreamRequestBodyShape(ref.for, {
+            params: ref.params,
             only: ref.only,
             including: ref.including,
             required: ref.required,

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

@@ -492,6 +492,8 @@ export default class OpenapiEndpointRenderer {
         const body = this.requestBody;
         if (!body)
             return true;
+        if (body.params)
+            return true;
         if (body.only)
             return true;
         if (body.including)
@@ -518,10 +520,11 @@ export default class OpenapiEndpointRenderer {
         const dreamClass = forDreamClass || this.getSingleDreamModelClass();
         if (!dreamClass)
             return this.defaultRequestBody();
-        const { only, including, required, combining } = (this.requestBody ||
+        const { params, only, including, required, combining } = (this.requestBody ||
             {});
         const source = this.controllerClass.controllerActionPath(this.action);
         const paramsShape = buildDreamRequestBodyShape(dreamClass, {
+            params: params,
             only: only,
             including: including,
             required: required,

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

@@ -11,8 +11,11 @@ import { dreamColumnOpenapiShape } from './dreamColumnOpenapiShape.js';
  * 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 { params, only, including, required, combining } = opts;
+    const paramSafeColumns = openapiParamNamesForDreamClass(dreamClass, {
+        only: params ?? only,
+        including,
+    });
     const paramsShape = {
         type: 'object',
         properties: {},

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

@@ -53,7 +53,8 @@ export default class Params {
                     returnObj[columnName] = this.cast(params, columnName.toString(), castType, { allowNull: columnMetadata.allowNull });
                 }
                 else if (dreamClass.isVirtualColumn(columnName)) {
-                    returnObj[columnName] = params[columnName];
+                    const virtualCast = virtualAttributeCast(dreamClass, columnName);
+                    returnObj[columnName] = this.cast(params, columnName.toString(), virtualCast.expectedType, { allowNull: virtualCast.allowNull });
                 }
                 else if (columnMetadata?.enumValues) {
                     const paramValue = params[columnName];
@@ -167,9 +168,10 @@ export default class Params {
         if (paramValue === null || paramValue === undefined) {
             if (expectedType === 'null')
                 return null;
-            if (!this.shouldUseOpenapiValidation(expectedType)) {
-                this.throwUnlessAllowNull(paramName, paramValue, typeToError(expectedType), opts);
+            if (this.shouldUseOpenapiValidation(expectedType)) {
+                return this.validateOpenapiOrThrow(paramName, paramValue, expectedType);
             }
+            this.throwUnlessAllowNull(paramName, paramValue, typeToError(expectedType), opts);
             return paramValue;
         }
         const integerRegexp = /^-?\d+$/;
@@ -298,13 +300,7 @@ export default class Params {
                 return paramValue.map(param => this.cast(paramName, param, arrayTypeToNonArrayType(expectedType), { ...opts, allowNull: true }));
             default:
                 if (this.shouldUseOpenapiValidation(expectedType)) {
-                    const res = validateObject(paramValue, expectedType, { coerceTypes: true });
-                    if (res.isValid) {
-                        return res.data;
-                    }
-                    else {
-                        throw new ParamValidationError(paramName, res.errors?.map(err => err.message) || ['openapi validation failed']);
-                    }
+                    return this.validateOpenapiOrThrow(paramName, paramValue, expectedType);
                 }
                 // TODO: serialize/sanitize before printing, handle array types
                 throw new Error(`Unexpected point reached in code. need to handle type for ${expectedType}`);
@@ -313,6 +309,12 @@ export default class Params {
     shouldUseOpenapiValidation(expectedType) {
         return isObject(expectedType);
     }
+    validateOpenapiOrThrow(paramName, paramValue, expectedType) {
+        const res = validateObject(paramValue, expectedType, { coerceTypes: true });
+        if (res.isValid)
+            return res.data;
+        throw new ParamValidationError(paramName, res.errors?.map(err => err.message) || ['openapi validation failed']);
+    }
     restrict(allowed) {
         const params = this.$params;
         const permitted = {};
@@ -403,6 +405,121 @@ const DB_TYPE_TO_CAST_TYPE = {
     numeric: 'number',
     'numeric[]': 'number[]',
 };
+function virtualAttributeCast(dreamClass, columnName) {
+    const metadata = dreamClass['virtualAttributes'].find(statement => statement.property === columnName);
+    const primitiveCast = primitiveCastFromOpenapi(metadata?.type);
+    if (!primitiveCast)
+        throw new Error(`Unable to infer params cast type for virtual column: ${columnName}`);
+    return primitiveCast;
+}
+function primitiveCastFromOpenapi(openapi) {
+    if (!openapi)
+        return null;
+    if (Array.isArray(openapi)) {
+        const nonNullOpenapi = openapi.find(type => type !== 'null');
+        const primitiveCast = primitiveCastFromOpenapi(nonNullOpenapi);
+        if (!primitiveCast)
+            return null;
+        return { ...primitiveCast, allowNull: true };
+    }
+    if (typeof openapi === 'string') {
+        const expectedType = shorthandToCastType(openapi);
+        return expectedType ? { expectedType, allowNull: false } : null;
+    }
+    if (!('type' in openapi))
+        return null;
+    const openapiType = openapi.type;
+    const allowNull = Array.isArray(openapiType) && openapiType.includes('null');
+    const nonNullType = Array.isArray(openapiType) ? openapiType.find(type => type !== 'null') : openapiType;
+    if (nonNullType === 'array') {
+        if (!('items' in openapi))
+            return null;
+        const item = openapi.items;
+        const itemType = item && 'type' in item ? item.type : undefined;
+        const itemFormat = item && 'format' in item ? item.format : undefined;
+        if (Array.isArray(itemType))
+            return null;
+        const itemCastType = openapiTypeToCastType(itemType, itemFormat);
+        if (!itemCastType)
+            return null;
+        return { expectedType: `${itemCastType}[]`, allowNull };
+    }
+    const expectedType = openapiTypeToCastType(nonNullType, 'format' in openapi ? openapi.format : undefined);
+    return expectedType ? { expectedType, allowNull } : null;
+}
+function shorthandToCastType(openapi) {
+    switch (openapi) {
+        case 'date-time':
+            return 'datetime';
+        case 'date-time[]':
+            return 'datetime[]';
+        case 'decimal':
+            return 'number';
+        case 'decimal[]':
+            return 'number[]';
+        case 'json':
+            return 'json';
+        case 'null':
+            return 'null';
+        default:
+            return PARAM_CAST_TYPES.includes(openapi)
+                ? openapi
+                : null;
+    }
+}
+function openapiTypeToCastType(openapiType, format) {
+    switch (openapiType) {
+        case 'boolean':
+            return 'boolean';
+        case 'integer':
+            return 'integer';
+        case 'number':
+            return 'number';
+        case 'null':
+            return 'null';
+        case 'object':
+            return 'json';
+        case 'string':
+            switch (format) {
+                case 'date':
+                    return 'date';
+                case 'date-time':
+                    return 'datetime';
+                case 'uuid':
+                    return 'uuid';
+                default:
+                    return 'string';
+            }
+        default:
+            return null;
+    }
+}
+const PARAM_CAST_TYPES = [
+    'bigint',
+    'bigint[]',
+    'boolean',
+    'boolean[]',
+    'date',
+    'date[]',
+    'datetime',
+    'datetime[]',
+    'integer',
+    'integer[]',
+    'json',
+    'json[]',
+    'null',
+    'null[]',
+    'number',
+    'number[]',
+    'string',
+    'string[]',
+    'time',
+    'time[]',
+    'timetz',
+    'timetz[]',
+    'uuid',
+    'uuid[]',
+];
 const typeToErrorMap = {
     bigint: 'expected bigint',
     boolean: 'expected boolean',

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

@@ -12,9 +12,9 @@ export declare function OpenAPI<const I extends DreamSerializable | DreamSeriali
 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,
+     * request body. Returns the same `{ for, params, including, required,
      * combining }` shape the renderer recognizes natively, but typed via a
-     * function-level generic so `only` / `including` / `required` are
+     * function-level generic so `params` / `including` / `required` are
      * constrained to columns of the model passed as the first argument.
      *
      * ```ts
@@ -41,6 +41,11 @@ export declare namespace OpenAPI {
      * ```
      */
     function forDream<const M extends typeof Dream>(model: M, opts?: {
+        params?: readonly (keyof DreamParamSafeAttributes<InstanceType<M>>)[];
+        /**
+         * @deprecated Use `params` instead. `only` remains as a compatibility alias
+         * for apps written before `extractParams` made request params explicit.
+         */
         only?: readonly (keyof DreamParamSafeAttributes<InstanceType<M>>)[];
         including?: readonly Exclude<keyof UpdateableProperties<InstanceType<M>>, keyof DreamParamSafeAttributes<InstanceType<M>>>[];
         required?: readonly (keyof UpdateableProperties<InstanceType<M>>)[];

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

@@ -24,7 +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)
+ * - Nested model-derived request-body references like `{ for: SomeModel, params, including, 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.

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

@@ -784,8 +784,13 @@ type DreamShorthandPrev = [never, 0, 1, 2, 3];
  */
 export type OpenapiSchemaNestedFor<Depth extends 0 | 1 | 2 | 3 = 3> = {
     for: typeof Dream;
-    including?: readonly string[];
+    params?: readonly string[];
+    /**
+     * @deprecated Use `params` instead. `only` remains as a compatibility alias
+     * for apps written before `extractParams` made request params explicit.
+     */
     only?: readonly string[];
+    including?: readonly string[];
     required?: readonly string[];
     combining?: Depth extends 0 ? OpenapiSchemaPropertiesShorthand : OpenapiSchemaRequestPropertiesShorthandWithFor<DreamShorthandPrev[Depth] & (0 | 1 | 2 | 3)>;
 };
@@ -837,15 +842,14 @@ export interface OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof
      */
     for: ForOption;
     /**
-     * Narrow down which fields on the model you would like
-     * to include. If a `for` option is provided, the fields
-     * will be derived from that model class. Otherwise, it
-     * will be derrived from the first argument passed to
-     * the OpenAPI decorator, provided it is a dream model.
+     * Explicitly list which request params to include from the model. If a `for`
+     * option is provided, the params will be derived from that model class.
+     * Otherwise, they will be derived from the first argument passed to the
+     * OpenAPI decorator, provided it is a Dream model.
      *
      * ```ts
      * @OpenAPI({
-     *   requestBody: { for: Pet, only: ['species', 'name'] }
+     *   requestBody: { for: Pet, params: ['species', 'name'] }
      * })
      * public create() {
      *   ...
@@ -856,13 +860,18 @@ export interface OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof
      *
      * ```ts
      * @OpenAPI(Pet, {
-     *   requestBody: { only: ['species', 'name'] }
+     *   requestBody: { params: ['species', 'name'] }
      * })
      * public create() {
      *   ...
      * }
      * ```
      */
+    params?: (keyof DreamParamSafeAttributes<InstanceType<ForOption>>)[];
+    /**
+     * @deprecated Use `params` instead. `only` remains as a compatibility alias
+     * for apps written before `extractParams` made request params explicit.
+     */
     only?: (keyof DreamParamSafeAttributes<InstanceType<ForOption>>)[];
     /**
      * expand the included fields to allow fields that
@@ -911,7 +920,7 @@ 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` /
+     * columns and accepts the same `params` / `including` / `required` /
      * `combining` siblings.
      *
      * ```ts
@@ -965,21 +974,25 @@ export interface OpenapiSchemaRequestBodyForDreamClass<ForOption extends typeof
 export interface OpenapiSchemaRequestBodyForBaseDreamClass<Serializable extends DreamSerializable | DreamSerializableArray | undefined, T extends Serializable extends typeof Dream ? Serializable : undefined = Serializable extends typeof Dream ? Serializable : undefined, I extends T extends typeof Dream ? InstanceType<T> : undefined = T extends typeof Dream ? InstanceType<T> : undefined, Only extends I extends Dream ? readonly (keyof DreamParamSafeAttributes<I>)[] : string[] = I extends Dream ? readonly (keyof DreamParamSafeAttributes<I>)[] : string[], Including extends I extends Dream ? Exclude<keyof DreamAttributes<I>, keyof DreamParamSafeAttributes<I>>[] : string[] = I extends Dream ? Exclude<keyof DreamAttributes<I>, keyof DreamParamSafeAttributes<I>>[] : string[], RequiredFields extends I extends Dream ? readonly (keyof DreamAttributes<I>)[] : string[] = I extends Dream ? readonly (keyof DreamAttributes<I>)[] : string[]> {
     for?: never;
     /**
-     * Narrow down which fields on the model you would like
-     * to include. If a `for` option is provided, the fields
-     * will be derived from that model class. Otherwise, it
-     * will be derrived from the first argument passed to
-     * the OpenAPI decorator, provided it is a dream model.
+     * Explicitly list which request params to include from the model. If a `for`
+     * option is provided, the params will be derived from that model class.
+     * Otherwise, they will be derived from the first argument passed to the
+     * OpenAPI decorator, provided it is a Dream model.
      *
      * ```ts
      * @OpenAPI(Pet, {
-     *   requestBody: { only: ['species', 'name'] }
+     *   requestBody: { params: ['species', 'name'] }
      * })
      * public create() {
      *   ...
      * }
      * ```
      */
+    params?: Only;
+    /**
+     * @deprecated Use `params` instead. `only` remains as a compatibility alias
+     * for apps written before `extractParams` made request params explicit.
+     */
     only?: Only;
     /**
      * expand the included fields to allow fields that
@@ -1017,7 +1030,7 @@ 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` /
+     * columns and accepts the same `params` / `including` / `required` /
      * `combining` siblings.
      *
      * ```ts

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

@@ -1,6 +1,7 @@
 import { Dream } from '@rvoh/dream';
 import { OpenapiSchemaObject } from '@rvoh/dream/openapi';
 export interface BuildDreamRequestBodyShapeOpts {
+    params?: readonly string[] | undefined;
     only?: readonly string[] | undefined;
     including?: readonly string[] | undefined;
     required?: readonly string[] | undefined;

package/dist/types/src/server/helpers/openapiParamNamesForDreamClass.d.ts

@@ -1,6 +1,6 @@
 import { Dream } from '@rvoh/dream';
 import { DreamParamSafeAttributes, DreamParamSafeColumnNames, StrictInterface, UpdateableProperties } from '@rvoh/dream/types';
-import { OpenAPIDreamModelRequestBodyModifications } from '../params.js';
+import type { OpenAPIDreamModelRequestBodyModifications } from '../params.js';
 export default function openapiParamNamesForDreamClass<T extends typeof Dream, I extends InstanceType<T>, const OnlyArray extends readonly (keyof DreamParamSafeAttributes<I>)[], const IncludingArray extends Exclude<keyof UpdateableProperties<I>, OnlyArray[number]>[], ForOpts extends StrictInterface<ForOpts, OpenAPIDreamModelRequestBodyModifications<OnlyArray, IncludingArray>>, ParamSafeColumnsOverride extends I['paramSafeColumns' & keyof I] extends never ? undefined : I['paramSafeColumns' & keyof I] & string[], ParamSafeColumns extends ParamSafeColumnsOverride extends string[] | Readonly<string[]> ? Extract<DreamParamSafeColumnNames<I>, ParamSafeColumnsOverride[number] & DreamParamSafeColumnNames<I>>[] : DreamParamSafeColumnNames<I>[], ParamSafeAttrs extends DreamParamSafeAttributes<InstanceType<T>>, ReturnPartialType extends ForOpts['only'] extends readonly (keyof DreamParamSafeAttributes<InstanceType<T>>)[] ? Partial<{
     [K in ForOpts['only'][number] & keyof ParamSafeAttrs]: ParamSafeAttrs[K & keyof ParamSafeAttrs];
 }> : Partial<{

package/dist/types/src/server/helpers/paramNamesForDreamClass.d.ts

@@ -1,6 +1,6 @@
 import { Dream } from '@rvoh/dream';
 import { DreamParamSafeAttributes, DreamParamSafeColumnNames, StrictInterface } from '@rvoh/dream/types';
-import { ParamsForOpts } from '../params.js';
+import type { ParamsForOpts } from '../params.js';
 export default function paramNamesForDreamClass<T extends typeof Dream, I extends InstanceType<T>, const OnlyArray extends readonly (keyof DreamParamSafeAttributes<I>)[], ForOpts extends StrictInterface<ForOpts, ParamsForOpts<OnlyArray>>, ParamSafeColumnsOverride extends I['paramSafeColumns' & keyof I] extends never ? undefined : I['paramSafeColumns' & keyof I] & string[], ParamSafeColumns extends ParamSafeColumnsOverride extends string[] | Readonly<string[]> ? Extract<DreamParamSafeColumnNames<I>, ParamSafeColumnsOverride[number] & DreamParamSafeColumnNames<I>>[] : DreamParamSafeColumnNames<I>[], ParamSafeAttrs extends DreamParamSafeAttributes<InstanceType<T>>, ReturnPartialType extends ForOpts['only'] extends readonly (keyof DreamParamSafeAttributes<InstanceType<T>>)[] ? Partial<{
     [K in ForOpts['only'][number] & keyof ParamSafeAttrs]: ParamSafeAttrs[K & keyof ParamSafeAttrs];
 }> : Partial<{

package/dist/types/src/server/params.d.ts

@@ -74,6 +74,7 @@ export default class Params {
     casing(casing: 'snake' | 'camel'): this;
     cast<EnumType extends readonly string[], OptsType extends StrictInterface<OptsType, ParamsCastOptions<EnumType>>, ExpectedType extends PsychicParamsPrimitiveLiteral | RegExp | OpenapiSchemaBody, ValidatedType extends ValidatedReturnType<ExpectedType, OptsType>, AllowNullOrUndefined extends ValidatedAllowsNull<ExpectedType, OptsType>, ReturnType extends AllowNullOrUndefined extends true ? ValidatedType | null | undefined : ValidatedType>(paramName: string, paramValue: PsychicParamsPrimitive | PsychicParamsDictionary | PsychicParamsDictionary[], expectedType: ExpectedType, opts?: OptsType): AllowNullOrUndefined extends true ? ValidatedType | null | undefined : ValidatedType;
     private shouldUseOpenapiValidation;
+    private validateOpenapiOrThrow;
     restrict(allowed: string[]): PsychicParamsDictionary;
     private matchRegexOrThrow;
     private throwUnlessAllowNull;
@@ -130,6 +131,7 @@ export interface ExtractParamsOpts {
     key?: string;
 }
 export interface OpenAPIDreamModelRequestBodyModifications<OnlyArray, IncludingArray> extends ParamsForOptsBase<OnlyArray> {
+    params?: OnlyArray;
     combining?: OpenapiSchemaPropertiesShorthand;
     including?: IncludingArray;
 }

package/package.json

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