@rvoh/psychic 0.37.0-beta.4 → 0.37.0-beta.6

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

@@ -1,23 +1,60 @@
 import { DreamModelSerializerType, OpenapiSchemaBody, OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes, SimpleObjectSerializerType } from '@rvoh/dream';
 import { OpenapiEndpointResponse, OpenapiRenderOpts, OpenapiResponses } from './endpoint.js';
 export interface OpenapiBodySegmentRendererOpts {
-    openapiName: string;
     renderOpts: OpenapiRenderOpts;
     target: OpenapiBodyTarget;
 }
-export default class OpenapiBodySegmentRenderer {
+/**
+ * @internal
+ *
+ * Internal class used to recursively expand OpenAPI shorthand notation into full OpenAPI schema objects.
+ *
+ * This class handles the transformation of various shorthand formats:
+ * - Primitive shorthands like `'string'` → `{ type: 'string' }`
+ * - Nullable shorthands like `['string', 'null']` → `{ type: ['string', 'null'] }`
+ * - Array shorthands like `'string[]'` → `{ type: 'array', items: { type: 'string' } }`
+ * - 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
+ *
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * // Input shorthand
+ * {
+ *   type: 'object',
+ *   properties: {
+ *     name: 'string',
+ *     tags: 'string[]',
+ *     user: { $serializer: UserSerializer }
+ *   }
+ * }
+ *
+ * // Output expanded
+ * {
+ *   type: 'object',
+ *   properties: {
+ *     name: { type: 'string' },
+ *     tags: { type: 'array', items: { type: 'string' } },
+ *     user: { $ref: '#/components/schemas/UserSerializer' }
+ *   }
+ * }
+ * ```
+ */
+export default class OpenapiSegmentExpander {
     private bodySegment;
     private casing;
     private suppressResponseEnums;
     private target;
-    private openapiName;
     /**
      * @internal
      *
-     * Used to recursively parse nested object structures
+     * Used to recursively expand nested object structures
      * within nested openapi objects
      */
-    constructor(bodySegment: OpenapiBodySegment, { openapiName, renderOpts, target }: OpenapiBodySegmentRendererOpts);
+    constructor(bodySegment: OpenapiBodySegment, { renderOpts, target }: OpenapiBodySegmentRendererOpts);
     /**
      * returns the shorthanded body segment, rendered
      * to the appropriate openapi shape
@@ -26,7 +63,7 @@ export default class OpenapiBodySegmentRenderer {
     /**
      * @internal
      *
-     * Recursively parses nested objects and arrays,
+     * Recursively expand nested objects and arrays,
      * as well as primitive types
      */
     recursivelyParseBody(bodySegment: OpenapiBodySegment): ReferencedSerializersAndOpenapiSchemaBody;
@@ -40,50 +77,50 @@ export default class OpenapiBodySegmentRenderer {
     /**
      * @internal
      *
-     * recursively parses a oneOf statement
+     * recursively expands a oneOf statement
      */
     private oneOfStatement;
     /**
      * @internal
      *
-     * recursively parses an anyOf statement
+     * recursively expand an anyOf statement
      */
     private anyOfStatement;
     /**
      * @internal
      *
-     * recursively parses an allOf statement
+     * recursively expand an allOf statement
      */
     private allOfStatement;
     /**
      * @internal
      *
-     * recursively parses an array statement
+     * recursively expand an array statement
      */
     private arrayStatement;
     /**
      * @internal
      *
-     * recursively parses an object statement
+     * recursively expand an object statement
      */
     private objectStatement;
     /**
      * @internal
      *
-     * parses either the `properties` or `additionalProperties` values
+     * expand either the `properties` or `additionalProperties` values
      * on an object
      */
     private parseObjectPropertyStatement;
     /**
      * @internal
      *
-     * recursively parses a primitive literal type (i.e. string or boolean[])
+     * recursively expand a primitive literal type (i.e. string or boolean[])
      */
     private primitiveLiteralStatement;
     /**
      * @internal
      *
-     * recursively parses a primitive object type (i.e. { type: 'string[]' })
+     * recursively expand a primitive object type (i.e. { type: 'string[]' })
      */
     private primitiveObjectStatement;
     private typeIsOpenapiArrayPrimitive;

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

@@ -1,6 +1,7 @@
-import { Dream, DreamOrViewModelClassSerializerArrayKeys, DreamOrViewModelClassSerializerKey, DreamSerializable, DreamSerializableArray, OpenapiAllTypes, OpenapiFormats, OpenapiSchemaArray, OpenapiSchemaBody, OpenapiSchemaBodyShorthand, OpenapiSchemaExpressionAllOf, OpenapiSchemaExpressionAnyOf, OpenapiSchemaExpressionOneOf, OpenapiSchemaExpressionRef, OpenapiSchemaObject, OpenapiSchemaProperties, SerializerCasing, ViewModelClass } from '@rvoh/dream';
+import { Dream, DreamOrViewModelClassSerializerKey, DreamSerializable, DreamSerializableArray, OpenapiAllTypes, OpenapiFormats, OpenapiSchemaArray, OpenapiSchemaBody, OpenapiSchemaBodyShorthand, OpenapiSchemaExpressionAllOf, OpenapiSchemaExpressionAnyOf, OpenapiSchemaExpressionOneOf, OpenapiSchemaExpressionRef, OpenapiSchemaObject, OpenapiSchemaProperties, SerializerCasing, ViewModelClass } from '@rvoh/dream';
 import PsychicController from '../controller/index.js';
 import { HttpStatusCode, HttpStatusCodeNumber } from '../error/http/status-codes.js';
+import { DreamOrViewModelClassSerializerArrayKeys } from '../helpers/typeHelpers.js';
 import { RouteConfig } from '../router/route-manager.js';
 import { HttpMethod } from '../router/types.js';
 import { OpenapiBodySegment, ReferencedSerializersAndOpenapiEndpointResponse, SerializerArray } from './body-segment.js';

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

@@ -1,2 +1,41 @@
 import { DreamModelSerializerType, OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes, SimpleObjectSerializerType } from '@rvoh/dream';
+/**
+ * @internal
+ *
+ * Recursively scans an OpenAPI schema structure and returns an array of all Serializers referenced within it.
+ *
+ * This function traverses the provided OpenAPI schema definition looking for `$serializer` properties
+ * and collects all unique serializer references found. It performs a deep scan of nested objects and
+ * arrays to find all serializer references at any level of nesting.
+ *
+ * **Important**: This function does _not_ recurse into the OpenAPI schemas generated by the discovered
+ * Serializers themselves. It only extracts serializers from the hand-written OpenAPI structure provided
+ * as input.
+ *
+ * @param openapi - The OpenAPI schema definition to scan for serializer references
+ * @returns An array of unique serializers found in the schema structure
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   properties: {
+ *     user: { $serializer: UserSerializer },
+ *     posts: {
+ *       type: 'array',
+ *       items: { $serializer: PostSerializer }
+ *     },
+ *     metadata: {
+ *       type: 'object',
+ *       properties: {
+ *         author: { $serializer: UserSerializer } // Duplicate, will be deduplicated
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * const serializers = allSerializersFromHandWrittenOpenapi(schema)
+ * // Returns: [UserSerializer, PostSerializer]
+ * ```
+ */
 export default function allSerializersFromHandWrittenOpenapi(openapi: OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes | undefined): (DreamModelSerializerType | SimpleObjectSerializerType)[];

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

@@ -1,2 +1,46 @@
 import { OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from '@rvoh/dream';
+/**
+ * @internal
+ *
+ * Transforms OpenAPI schema definitions by replacing serializer shorthand references with proper `$ref` statements.
+ *
+ * This function is used by the SerializerOpenapiRenderer to ensure that the schemas it generates from
+ * Serializers contain `$ref` statements instead of `$serializer` or `$serializable` statements. This
+ * transformation enables consistent ordering of `anyOf` statements since `anyOf` arrays are sorted by
+ * the `$ref` value, which follows the pattern `'#/components/schemas/TheSerializerOpenapiName'`.
+ *
+ * The function recursively traverses the schema and transforms:
+ * - `{ $serializer: SomeSerializer }` → `{ $ref: '#/components/schemas/SerializerOpenapiName' }`
+ * - `{ $serializable: SomeModel, key: 'summary' }` → `{ $ref: '#/components/schemas/ModelSummarySerializer' }`
+ *
+ * @param openapi - The OpenAPI schema definition that may contain serializer shorthand references
+ * @returns The transformed schema with `$ref` statements replacing serializer shorthands
+ *
+ * @example
+ * ```typescript
+ * const input = {
+ *   type: 'object',
+ *   properties: {
+ *     user: { $serializer: UserSerializer },
+ *     posts: {
+ *       type: 'array',
+ *       items: { $serializer: PostSerializer }
+ *     }
+ *   }
+ * }
+ *
+ * const output = allSerializersToRefsInOpenapi(input)
+ * // Returns:
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     user: { $ref: '#/components/schemas/UserSerializer' },
+ * //     posts: {
+ * //       type: 'array',
+ * //       items: { $ref: '#/components/schemas/PostSerializer' }
+ * //     }
+ * //   }
+ * // }
+ * ```
+ */
 export default function allSerializersToRefsInOpenapi(openapi: OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes | undefined): OpenapiSchemaBodyShorthand;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "0.37.0-beta.4",
+  "version": "0.37.0-beta.6",
   "author": "RVOHealth",
   "repository": {
     "type": "git",
@@ -58,7 +58,7 @@
   "devDependencies": {
     "@eslint/js": "^9.19.0",
     "@jest-mock/express": "^3.0.0",
-    "@rvoh/dream": "^0.43.0-beta.6",
+    "@rvoh/dream": "^0.43.0-beta.9",
     "@rvoh/dream-spec-helpers": "^0.2.4",
     "@rvoh/psychic-spec-helpers": "^0.6.0",
     "@types/express": "^5.0.1",