metal-orm 1.0.80 → 1.0.81

package/src/openapi/schema-extractor.ts

@@ -2,40 +2,101 @@ import type { TableDef } from '../schema/table.js';
 import type { RelationDef } from '../schema/relation.js';
 import type { HydrationPlan, HydrationRelationPlan } from '../core/hydration/types.js';
 import type { ProjectionNode } from '../query-builder/select-query-state.js';
-
-import type { OpenApiSchema, SchemaExtractionContext, SchemaOptions, JsonSchemaProperty, JsonSchemaType } from './schema-types.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+
+import type {
+  OpenApiSchema,
+  OpenApiSchemaBundle,
+  SchemaExtractionContext,
+  SchemaOptions,
+  OutputSchemaOptions,
+  InputSchemaOptions,
+  JsonSchemaProperty,
+  JsonSchemaType
+} from './schema-types.js';
 import { mapColumnType, mapRelationType } from './type-mappers.js';
 
+const DEFAULT_MAX_DEPTH = 5;
+
 /**
- * Extracts OpenAPI 3.1 schema from a query builder's hydration plan
- * @param table - Table definition
- * @param plan - Hydration plan from query builder
- * @param projectionNodes - Projection AST nodes (for computed fields)
- * @param options - Schema generation options
- * @returns OpenAPI 3.1 JSON Schema
+ * Extracts OpenAPI 3.1 schemas for output and optional input payloads.
  */
 export const extractSchema = (
   table: TableDef,
   plan: HydrationPlan | undefined,
   projectionNodes: ProjectionNode[] | undefined,
   options: SchemaOptions = {}
-): OpenApiSchema => {
-  const mode = options.mode ?? 'full';
+): OpenApiSchemaBundle => {
+  const outputOptions = resolveOutputOptions(options);
+  const outputContext = createContext(outputOptions.maxDepth ?? DEFAULT_MAX_DEPTH);
+  const output = extractOutputSchema(table, plan, projectionNodes, outputContext, outputOptions);
+
+  const inputOptions = resolveInputOptions(options);
+  if (!inputOptions) {
+    return { output };
+  }
+
+  const inputContext = createContext(inputOptions.maxDepth ?? DEFAULT_MAX_DEPTH);
+  const input = extractInputSchema(table, inputContext, inputOptions);
+
+  return { output, input };
+};
 
-  const context: SchemaExtractionContext = {
-    visitedTables: new Set(),
-    schemaCache: new Map(),
-    depth: 0,
-    maxDepth: options.maxDepth ?? 5,
+const resolveOutputOptions = (options: SchemaOptions): OutputSchemaOptions => ({
+  mode: options.mode ?? 'full',
+  includeDescriptions: options.includeDescriptions,
+  includeEnums: options.includeEnums,
+  includeExamples: options.includeExamples,
+  includeDefaults: options.includeDefaults,
+  includeNullable: options.includeNullable,
+  maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH
+});
+
+const resolveInputOptions = (options: SchemaOptions): InputSchemaOptions | undefined => {
+  if (options.input === false) return undefined;
+  const input = options.input ?? {};
+  const mode = input.mode ?? 'create';
+
+  return {
+    mode,
+    includeRelations: input.includeRelations ?? true,
+    relationMode: input.relationMode ?? 'mixed',
+    includeDescriptions: input.includeDescriptions ?? options.includeDescriptions,
+    includeEnums: input.includeEnums ?? options.includeEnums,
+    includeExamples: input.includeExamples ?? options.includeExamples,
+    includeDefaults: input.includeDefaults ?? options.includeDefaults,
+    includeNullable: input.includeNullable ?? options.includeNullable,
+    maxDepth: input.maxDepth ?? options.maxDepth ?? DEFAULT_MAX_DEPTH,
+    omitReadOnly: input.omitReadOnly ?? true,
+    excludePrimaryKey: input.excludePrimaryKey ?? false,
+    requirePrimaryKey: input.requirePrimaryKey ?? (mode === 'update')
   };
+};
+
+const createContext = (maxDepth: number): SchemaExtractionContext => ({
+  visitedTables: new Set(),
+  schemaCache: new Map(),
+  depth: 0,
+  maxDepth
+});
+
+/**
+ * Output schema extraction (query results)
+ */
+const extractOutputSchema = (
+  table: TableDef,
+  plan: HydrationPlan | undefined,
+  projectionNodes: ProjectionNode[] | undefined,
+  context: SchemaExtractionContext,
+  options: OutputSchemaOptions
+): OpenApiSchema => {
+  const mode = options.mode ?? 'full';
 
-  // Detect if query contains computed fields (non-Column nodes)
   const hasComputedFields = projectionNodes && projectionNodes.some(
     node => node.type !== 'Column'
   );
 
   if (hasComputedFields) {
-    // Use projection-based extraction for computed fields + relations
     return extractFromProjectionNodes(table, projectionNodes!, context, options);
   }
 
@@ -46,22 +107,144 @@ export const extractSchema = (
   return extractFullTableSchema(table, context, options);
 };
 
+/**
+ * Input schema extraction (write payloads)
+ */
+const extractInputSchema = (
+  table: TableDef,
+  context: SchemaExtractionContext,
+  options: InputSchemaOptions
+): OpenApiSchema => {
+  const cacheKey = `${table.name}:${options.mode ?? 'create'}`;
+
+  if (context.schemaCache.has(cacheKey)) {
+    return context.schemaCache.get(cacheKey)!;
+  }
+
+  if (context.visitedTables.has(cacheKey) && context.depth > 0) {
+    return buildCircularReferenceSchema(table.name, 'input');
+  }
+
+  context.visitedTables.add(cacheKey);
+
+  const properties: Record<string, JsonSchemaProperty> = {};
+  const required: string[] = [];
+  const primaryKey = findPrimaryKey(table);
+
+  for (const [columnName, column] of Object.entries(table.columns)) {
+    const isPrimary = columnName === primaryKey || column.primary;
+    if (options.excludePrimaryKey && isPrimary) continue;
+    if (options.omitReadOnly && isReadOnlyColumn(column)) continue;
+
+    properties[columnName] = mapColumnType(column, options);
+
+    if (options.mode === 'create' && isRequiredForCreate(column)) {
+      required.push(columnName);
+    }
+
+    if (options.mode === 'update' && options.requirePrimaryKey && isPrimary) {
+      required.push(columnName);
+    }
+  }
+
+  if (options.includeRelations && context.depth < context.maxDepth) {
+    for (const [relationName, relation] of Object.entries(table.relations)) {
+      properties[relationName] = extractInputRelationSchema(
+        relation,
+        { ...context, depth: context.depth + 1 },
+        options
+      );
+    }
+  }
+
+  const schema: OpenApiSchema = {
+    type: 'object',
+    properties,
+    required
+  };
+
+  context.schemaCache.set(cacheKey, schema);
+  return schema;
+};
+
+const isReadOnlyColumn = (column: { autoIncrement?: boolean; generated?: string }): boolean =>
+  Boolean(column.autoIncrement || column.generated === 'always');
+
+const isRequiredForCreate = (column: { notNull?: boolean; primary?: boolean; default?: unknown; autoIncrement?: boolean; generated?: string }): boolean => {
+  if (isReadOnlyColumn(column)) return false;
+  if (column.default !== undefined) return false;
+  return Boolean(column.notNull || column.primary);
+};
+
+const buildPrimaryKeySchema = (
+  table: TableDef,
+  options: InputSchemaOptions
+): JsonSchemaProperty => {
+  const primaryKey = findPrimaryKey(table);
+  const column = table.columns[primaryKey];
+  if (!column) {
+    return {
+      anyOf: [
+        { type: 'string' as JsonSchemaType },
+        { type: 'number' as JsonSchemaType },
+        { type: 'integer' as JsonSchemaType }
+      ]
+    };
+  }
+
+  return mapColumnType(column, options);
+};
+
+const extractInputRelationSchema = (
+  relation: RelationDef,
+  context: SchemaExtractionContext,
+  options: InputSchemaOptions
+): JsonSchemaProperty => {
+  const { type: relationType, isNullable } = mapRelationType(relation.type);
+  const relationMode = options.relationMode ?? 'mixed';
+  const allowIds = relationMode !== 'objects';
+  const allowObjects = relationMode !== 'ids';
+
+  const variants: JsonSchemaProperty[] = [];
+
+  if (allowIds) {
+    variants.push(buildPrimaryKeySchema(relation.target, options));
+  }
+
+  if (allowObjects) {
+    const targetSchema = extractInputSchema(relation.target, context, options);
+    variants.push(targetSchema as JsonSchemaProperty);
+  }
+
+  const itemSchema: JsonSchemaProperty =
+    variants.length === 1 ? variants[0] : { anyOf: variants };
+
+  if (relationType === 'array') {
+    return {
+      type: 'array',
+      items: itemSchema,
+      nullable: isNullable
+    };
+  }
+
+  return {
+    ...itemSchema,
+    nullable: isNullable
+  };
+};
+
 /**
  * Extracts schema from projection nodes (handles computed fields)
- * @param table - Table definition
- * @param projectionNodes - Projection AST nodes
- * @param context - Schema extraction context
- * @param options - Schema generation options
- * @returns OpenAPI 3.1 JSON Schema
  */
 const extractFromProjectionNodes = (
   table: TableDef,
   projectionNodes: ProjectionNode[],
   context: SchemaExtractionContext,
-  options: SchemaOptions
+  options: OutputSchemaOptions
 ): OpenApiSchema => {
   const properties: Record<string, JsonSchemaProperty> = {};
   const required: string[] = [];
+  const includeDescriptions = Boolean(options.includeDescriptions);
 
   for (const node of projectionNodes) {
     if (!node || typeof node !== 'object') continue;
@@ -76,11 +259,7 @@ const extractFromProjectionNodes = (
       const column = table.columns[columnNode.name];
       if (!column) continue;
 
-      const property = mapColumnType(column);
-      if (!property.description && options.includeDescriptions && column.comment) {
-        property.description = column.comment;
-      }
-
+      const property = mapColumnType(column, options);
       properties[propertyName] = property;
 
       if (column.notNull || column.primary) {
@@ -89,38 +268,44 @@ const extractFromProjectionNodes = (
     } else if (projection.type === 'Function' || projection.type === 'WindowFunction') {
       const fnNode = node as { fn?: string; name?: string };
       const functionName = fnNode.fn?.toUpperCase() ?? fnNode.name?.toUpperCase() ?? '';
-      const propertySchema = projection.type === 'Function' 
-        ? mapFunctionNodeToSchema(functionName)
-        : mapWindowFunctionToSchema(functionName);
-      
+      const propertySchema = projection.type === 'Function'
+        ? mapFunctionNodeToSchema(functionName, includeDescriptions)
+        : mapWindowFunctionToSchema(functionName, includeDescriptions);
+
       properties[propertyName] = propertySchema;
 
       const isCountFunction = functionName === 'COUNT';
       const isWindowRankFunction = functionName === 'ROW_NUMBER' || functionName === 'RANK';
-      
+
       if (isCountFunction || isWindowRankFunction) {
         required.push(propertyName);
       }
     } else if (projection.type === 'CaseExpression') {
       const propertySchema: JsonSchemaProperty = {
         type: 'string' as JsonSchemaType,
-        description: 'Computed CASE expression',
-        nullable: true,
+        nullable: true
       };
+      if (includeDescriptions) {
+        propertySchema.description = 'Computed CASE expression';
+      }
       properties[propertyName] = propertySchema;
     } else if (projection.type === 'ScalarSubquery') {
       const propertySchema: JsonSchemaProperty = {
         type: 'object' as JsonSchemaType,
-        description: 'Subquery result',
-        nullable: true,
+        nullable: true
       };
+      if (includeDescriptions) {
+        propertySchema.description = 'Subquery result';
+      }
       properties[propertyName] = propertySchema;
     } else if (projection.type === 'CastExpression') {
       const propertySchema: JsonSchemaProperty = {
         type: 'string' as JsonSchemaType,
-        description: 'CAST expression result',
-        nullable: true,
+        nullable: true
       };
+      if (includeDescriptions) {
+        propertySchema.description = 'CAST expression result';
+      }
       properties[propertyName] = propertySchema;
     }
   }
@@ -128,16 +313,17 @@ const extractFromProjectionNodes = (
   return {
     type: 'object',
     properties,
-    required,
+    required
   };
 };
 
 /**
  * Maps SQL aggregate functions to OpenAPI types
- * @param functionName - SQL function name
- * @returns OpenAPI JSON Schema property
  */
-const mapFunctionNodeToSchema = (functionName: string): JsonSchemaProperty => {
+const mapFunctionNodeToSchema = (
+  functionName: string,
+  includeDescriptions: boolean
+): JsonSchemaProperty => {
   const upperName = functionName.toUpperCase();
 
   switch (upperName) {
@@ -146,44 +332,41 @@ const mapFunctionNodeToSchema = (functionName: string): JsonSchemaProperty => {
     case 'AVG':
     case 'MIN':
     case 'MAX':
-      return {
+      return withOptionalDescription({
         type: 'number' as JsonSchemaType,
-        description: `${upperName} aggregate function result`,
-        nullable: false,
-      };
+        nullable: false
+      }, includeDescriptions, `${upperName} aggregate function result`);
 
     case 'GROUP_CONCAT':
     case 'STRING_AGG':
     case 'ARRAY_AGG':
-      return {
+      return withOptionalDescription({
         type: 'string' as JsonSchemaType,
-        description: `${upperName} aggregate function result`,
-        nullable: true,
-      };
+        nullable: true
+      }, includeDescriptions, `${upperName} aggregate function result`);
 
     case 'JSON_ARRAYAGG':
     case 'JSON_OBJECTAGG':
-      return {
+      return withOptionalDescription({
         type: 'object' as JsonSchemaType,
-        description: `${upperName} aggregate function result`,
-        nullable: true,
-      };
+        nullable: true
+      }, includeDescriptions, `${upperName} aggregate function result`);
 
     default:
-      return {
+      return withOptionalDescription({
         type: 'string' as JsonSchemaType,
-        description: `Unknown function: ${functionName}`,
-        nullable: true,
-      };
+        nullable: true
+      }, includeDescriptions, `Unknown function: ${functionName}`);
   }
 };
 
 /**
  * Maps SQL window functions to OpenAPI types
- * @param functionName - SQL function name
- * @returns OpenAPI JSON Schema property
  */
-const mapWindowFunctionToSchema = (functionName: string): JsonSchemaProperty => {
+const mapWindowFunctionToSchema = (
+  functionName: string,
+  includeDescriptions: boolean
+): JsonSchemaProperty => {
   const upperName = functionName.toUpperCase();
 
   switch (upperName) {
@@ -191,44 +374,47 @@ const mapWindowFunctionToSchema = (functionName: string): JsonSchemaProperty =>
     case 'RANK':
     case 'DENSE_RANK':
     case 'NTILE':
-      return {
+      return withOptionalDescription({
         type: 'integer' as JsonSchemaType,
-        description: `${upperName} window function result`,
-        nullable: false,
-      };
+        nullable: false
+      }, includeDescriptions, `${upperName} window function result`);
 
     case 'LAG':
     case 'LEAD':
     case 'FIRST_VALUE':
     case 'LAST_VALUE':
-      return {
+      return withOptionalDescription({
         type: 'string' as JsonSchemaType,
-        description: `${upperName} window function result`,
-        nullable: true,
-      };
+        nullable: true
+      }, includeDescriptions, `${upperName} window function result`);
 
     default:
-      return {
+      return withOptionalDescription({
         type: 'string' as JsonSchemaType,
-        description: `Unknown window function: ${functionName}`,
-        nullable: true,
-      };
+        nullable: true
+      }, includeDescriptions, `Unknown window function: ${functionName}`);
+  }
+};
+
+const withOptionalDescription = (
+  schema: JsonSchemaProperty,
+  includeDescriptions: boolean,
+  description: string
+): JsonSchemaProperty => {
+  if (includeDescriptions) {
+    return { ...schema, description };
   }
+  return schema;
 };
 
 /**
  * Extracts schema with only selected columns and relations
- * @param table - Table definition
- * @param plan - Hydration plan
- * @param context - Schema extraction context
- * @param options - Schema generation options
- * @returns OpenAPI 3.1 JSON Schema
  */
 const extractSelectedSchema = (
   table: TableDef,
   plan: HydrationPlan,
   context: SchemaExtractionContext,
-  options: SchemaOptions
+  options: OutputSchemaOptions
 ): OpenApiSchema => {
   const properties: Record<string, JsonSchemaProperty> = {};
   const required: string[] = [];
@@ -237,12 +423,7 @@ const extractSelectedSchema = (
     const column = table.columns[columnName];
     if (!column) return;
 
-    const property = mapColumnType(column);
-    if (!property.description && options.includeDescriptions && column.comment) {
-      property.description = column.comment;
-    }
-
-    properties[columnName] = property;
+    properties[columnName] = mapColumnType(column, options);
 
     if (column.notNull || column.primary) {
       required.push(columnName);
@@ -272,21 +453,17 @@ const extractSelectedSchema = (
   return {
     type: 'object',
     properties,
-    required,
+    required
   };
 };
 
 /**
  * Extracts full table schema (all columns, all relations)
- * @param table - Table definition
- * @param context - Schema extraction context
- * @param options - Schema generation options
- * @returns OpenAPI 3.1 JSON Schema
  */
 const extractFullTableSchema = (
   table: TableDef,
   context: SchemaExtractionContext,
-  options: SchemaOptions
+  options: OutputSchemaOptions
 ): OpenApiSchema => {
   const cacheKey = table.name;
 
@@ -295,16 +472,7 @@ const extractFullTableSchema = (
   }
 
   if (context.visitedTables.has(cacheKey) && context.depth > 0) {
-    return {
-      type: 'object',
-      properties: {
-        _ref: {
-          type: 'string' as JsonSchemaType,
-          description: `Circular reference to ${table.name}`,
-        },
-      },
-      required: [],
-    };
+    return buildCircularReferenceSchema(table.name, 'output');
   }
 
   context.visitedTables.add(cacheKey);
@@ -313,12 +481,7 @@ const extractFullTableSchema = (
   const required: string[] = [];
 
   Object.entries(table.columns).forEach(([columnName, column]) => {
-    const property = mapColumnType(column);
-    if (!property.description && options.includeDescriptions && column.comment) {
-      property.description = column.comment;
-    }
-
-    properties[columnName] = property;
+    properties[columnName] = mapColumnType(column, options);
 
     if (column.notNull || column.primary) {
       required.push(columnName);
@@ -349,7 +512,7 @@ const extractFullTableSchema = (
   const schema: OpenApiSchema = {
     type: 'object',
     properties,
-    required,
+    required
   };
 
   context.schemaCache.set(cacheKey, schema);
@@ -358,19 +521,13 @@ const extractFullTableSchema = (
 
 /**
  * Extracts schema for a single relation
- * @param relation - Relation definition
- * @param relationPlan - Hydration plan for relation
- * @param selectedColumns - Selected columns from relation
- * @param context - Schema extraction context
- * @param options - Schema generation options
- * @returns OpenAPI JSON Schema property for relation
  */
 const extractRelationSchema = (
   relation: RelationDef,
   relationPlan: HydrationRelationPlan | undefined,
   selectedColumns: string[],
   context: SchemaExtractionContext,
-  options: SchemaOptions
+  options: OutputSchemaOptions
 ): JsonSchemaProperty => {
   const targetTable = relation.target;
   const { type: relationType, isNullable } = mapRelationType(relation.type);
@@ -382,7 +539,7 @@ const extractRelationSchema = (
       rootTable: targetTable.name,
       rootPrimaryKey: relationPlan.targetPrimaryKey,
       rootColumns: selectedColumns,
-      relations: [],
+      relations: []
     };
 
     targetSchema = extractSelectedSchema(targetTable, plan, context, options);
@@ -394,7 +551,7 @@ const extractRelationSchema = (
     return {
       type: 'array',
       items: targetSchema as JsonSchemaProperty,
-      nullable: isNullable,
+      nullable: isNullable
     };
   }
 
@@ -403,15 +560,26 @@ const extractRelationSchema = (
     properties: targetSchema.properties,
     required: targetSchema.required,
     nullable: isNullable,
-    description: targetSchema.description,
+    description: targetSchema.description
   };
 };
 
+const buildCircularReferenceSchema = (
+  tableName: string,
+  kind: 'input' | 'output'
+): OpenApiSchema => ({
+  type: 'object',
+  properties: {
+    _ref: {
+      type: 'string' as JsonSchemaType,
+      description: `Circular ${kind} reference to ${tableName}`
+    }
+  },
+  required: []
+});
+
 /**
  * Converts a schema to a JSON string with optional pretty printing
- * @param schema - OpenAPI schema
- * @param pretty - Whether to pretty print
- * @returns JSON string
  */
 export const schemaToJson = (schema: OpenApiSchema, pretty = false): string => {
   return JSON.stringify(schema, null, pretty ? 2 : 0);