metal-orm 1.0.87 → 1.0.89

package/src/openapi/schema-extractor.ts

@@ -1,20 +1,25 @@
 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 { HydrationPlan } from '../core/hydration/types.js';
 import type { ProjectionNode } from '../query-builder/select-query-state.js';
-import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 
 import type {
   OpenApiSchema,
   OpenApiSchemaBundle,
-  SchemaExtractionContext,
   SchemaOptions,
   OutputSchemaOptions,
   InputSchemaOptions,
-  JsonSchemaProperty,
-  JsonSchemaType
+  JsonSchemaProperty
 } from './schema-types.js';
-import { mapColumnType, mapRelationType } from './type-mappers.js';
+import { extractInputSchema } from './schema-extractor-input.js';
+import { extractOutputSchema } from './schema-extractor-output.js';
+import {
+  createContext,
+  hasComputedProjection,
+  registerComponentSchema,
+  resolveComponentName,
+  resolveSelectedComponentName,
+  shouldUseSelectedSchema
+} from './schema-extractor-utils.js';
 
 const DEFAULT_MAX_DEPTH = 5;
 
@@ -29,17 +34,45 @@ export const extractSchema = (
 ): OpenApiSchemaBundle => {
   const outputOptions = resolveOutputOptions(options);
   const outputContext = createContext(outputOptions.maxDepth ?? DEFAULT_MAX_DEPTH);
-  const output = extractOutputSchema(table, plan, projectionNodes, outputContext, outputOptions);
+  if (outputOptions.refMode === 'components') {
+    outputContext.components = { schemas: {} };
+  }
+  const outputSchema = extractOutputSchema(table, plan, projectionNodes, outputContext, outputOptions);
+  let output: OpenApiSchema | JsonSchemaProperty = outputSchema;
+  const useSelected = shouldUseSelectedSchema(outputOptions, plan, projectionNodes);
+  const hasComputedFields = hasComputedProjection(projectionNodes);
+  const canUseComponents = outputOptions.refMode === 'components' && outputContext.components && !hasComputedFields;
+
+  if (canUseComponents) {
+    const componentName = useSelected && plan
+      ? resolveSelectedComponentName(table, plan, outputOptions)
+      : resolveComponentName(table, outputOptions);
+    registerComponentSchema(componentName, outputSchema, outputContext);
+    if (outputOptions.outputAsRef) {
+      output = { $ref: `#/components/schemas/${componentName}` };
+    }
+  }
 
   const inputOptions = resolveInputOptions(options);
   if (!inputOptions) {
-    return { output };
+    return {
+      output,
+      components: outputContext.components && Object.keys(outputContext.components.schemas).length
+        ? outputContext.components
+        : undefined
+    };
   }
 
   const inputContext = createContext(inputOptions.maxDepth ?? DEFAULT_MAX_DEPTH);
   const input = extractInputSchema(table, inputContext, inputOptions);
 
-  return { output, input };
+  return {
+    output,
+    input,
+    components: outputContext.components && Object.keys(outputContext.components.schemas).length
+      ? outputContext.components
+      : undefined
+  };
 };
 
 const resolveOutputOptions = (options: SchemaOptions): OutputSchemaOptions => ({
@@ -49,7 +82,11 @@ const resolveOutputOptions = (options: SchemaOptions): OutputSchemaOptions => ({
   includeExamples: options.includeExamples,
   includeDefaults: options.includeDefaults,
   includeNullable: options.includeNullable,
-  maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH
+  maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+  refMode: options.refMode ?? 'inline',
+  selectedRefMode: options.selectedRefMode ?? 'inline',
+  componentName: options.componentName,
+  outputAsRef: options.outputAsRef ?? false
 });
 
 const resolveInputOptions = (options: SchemaOptions): InputSchemaOptions | undefined => {
@@ -69,515 +106,12 @@ const resolveInputOptions = (options: SchemaOptions): InputSchemaOptions | undef
     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';
-
-  const hasComputedFields = projectionNodes && projectionNodes.some(
-    node => node.type !== 'Column'
-  );
-
-  if (hasComputedFields) {
-    return extractFromProjectionNodes(table, projectionNodes!, context, options);
-  }
-
-  if (mode === 'selected' && plan) {
-    return extractSelectedSchema(table, plan, context, options);
-  }
-
-  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)
- */
-const extractFromProjectionNodes = (
-  table: TableDef,
-  projectionNodes: ProjectionNode[],
-  context: SchemaExtractionContext,
-  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;
-
-    const projection = node as { type: string; alias?: string; fn?: string; value?: unknown };
-    const propertyName = projection.alias ?? '';
-
-    if (!propertyName) continue;
-
-    if (projection.type === 'Column') {
-      const columnNode = node as { table: string; name: string };
-      const column = table.columns[columnNode.name];
-      if (!column) continue;
-
-      const property = mapColumnType(column, options);
-      properties[propertyName] = property;
-
-      if (column.notNull || column.primary) {
-        required.push(propertyName);
-      }
-    } 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, 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,
-        nullable: true
-      };
-      if (includeDescriptions) {
-        propertySchema.description = 'Computed CASE expression';
-      }
-      properties[propertyName] = propertySchema;
-    } else if (projection.type === 'ScalarSubquery') {
-      const propertySchema: JsonSchemaProperty = {
-        type: 'object' as JsonSchemaType,
-        nullable: true
-      };
-      if (includeDescriptions) {
-        propertySchema.description = 'Subquery result';
-      }
-      properties[propertyName] = propertySchema;
-    } else if (projection.type === 'CastExpression') {
-      const propertySchema: JsonSchemaProperty = {
-        type: 'string' as JsonSchemaType,
-        nullable: true
-      };
-      if (includeDescriptions) {
-        propertySchema.description = 'CAST expression result';
-      }
-      properties[propertyName] = propertySchema;
-    }
-  }
-
-  return {
-    type: 'object',
-    properties,
-    required
-  };
-};
-
-/**
- * Maps SQL aggregate functions to OpenAPI types
- */
-const mapFunctionNodeToSchema = (
-  functionName: string,
-  includeDescriptions: boolean
-): JsonSchemaProperty => {
-  const upperName = functionName.toUpperCase();
-
-  switch (upperName) {
-    case 'COUNT':
-    case 'SUM':
-    case 'AVG':
-    case 'MIN':
-    case 'MAX':
-      return withOptionalDescription({
-        type: 'number' as JsonSchemaType,
-        nullable: false
-      }, includeDescriptions, `${upperName} aggregate function result`);
-
-    case 'GROUP_CONCAT':
-    case 'STRING_AGG':
-    case 'ARRAY_AGG':
-      return withOptionalDescription({
-        type: 'string' as JsonSchemaType,
-        nullable: true
-      }, includeDescriptions, `${upperName} aggregate function result`);
-
-    case 'JSON_ARRAYAGG':
-    case 'JSON_OBJECTAGG':
-      return withOptionalDescription({
-        type: 'object' as JsonSchemaType,
-        nullable: true
-      }, includeDescriptions, `${upperName} aggregate function result`);
-
-    default:
-      return withOptionalDescription({
-        type: 'string' as JsonSchemaType,
-        nullable: true
-      }, includeDescriptions, `Unknown function: ${functionName}`);
-  }
-};
-
-/**
- * Maps SQL window functions to OpenAPI types
- */
-const mapWindowFunctionToSchema = (
-  functionName: string,
-  includeDescriptions: boolean
-): JsonSchemaProperty => {
-  const upperName = functionName.toUpperCase();
-
-  switch (upperName) {
-    case 'ROW_NUMBER':
-    case 'RANK':
-    case 'DENSE_RANK':
-    case 'NTILE':
-      return withOptionalDescription({
-        type: 'integer' as JsonSchemaType,
-        nullable: false
-      }, includeDescriptions, `${upperName} window function result`);
-
-    case 'LAG':
-    case 'LEAD':
-    case 'FIRST_VALUE':
-    case 'LAST_VALUE':
-      return withOptionalDescription({
-        type: 'string' as JsonSchemaType,
-        nullable: true
-      }, includeDescriptions, `${upperName} window function result`);
-
-    default:
-      return withOptionalDescription({
-        type: 'string' as JsonSchemaType,
-        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
- */
-const extractSelectedSchema = (
-  table: TableDef,
-  plan: HydrationPlan,
-  context: SchemaExtractionContext,
-  options: OutputSchemaOptions
-): OpenApiSchema => {
-  const properties: Record<string, JsonSchemaProperty> = {};
-  const required: string[] = [];
-
-  plan.rootColumns.forEach(columnName => {
-    const column = table.columns[columnName];
-    if (!column) return;
-
-    properties[columnName] = mapColumnType(column, options);
-
-    if (column.notNull || column.primary) {
-      required.push(columnName);
-    }
-  });
-
-  plan.relations.forEach(relationPlan => {
-    const relation = table.relations[relationPlan.name];
-    if (!relation) return;
-
-    const relationSchema = extractRelationSchema(
-      relation,
-      relationPlan,
-      relationPlan.columns,
-      context,
-      options
-    );
-
-    properties[relationPlan.name] = relationSchema;
-
-    const { isNullable } = mapRelationType(relation.type);
-    if (!isNullable && relationPlan.name) {
-      required.push(relationPlan.name);
-    }
-  });
-
-  return {
-    type: 'object',
-    properties,
-    required
+    requirePrimaryKey: input.requirePrimaryKey ?? (mode === 'update'),
+    excludeRelationForeignKeys: input.excludeRelationForeignKeys ?? false,
+    relationSelections: input.relationSelections
   };
 };
 
-/**
- * Extracts full table schema (all columns, all relations)
- */
-const extractFullTableSchema = (
-  table: TableDef,
-  context: SchemaExtractionContext,
-  options: OutputSchemaOptions
-): OpenApiSchema => {
-  const cacheKey = table.name;
-
-  if (context.schemaCache.has(cacheKey)) {
-    return context.schemaCache.get(cacheKey)!;
-  }
-
-  if (context.visitedTables.has(cacheKey) && context.depth > 0) {
-    return buildCircularReferenceSchema(table.name, 'output');
-  }
-
-  context.visitedTables.add(cacheKey);
-
-  const properties: Record<string, JsonSchemaProperty> = {};
-  const required: string[] = [];
-
-  Object.entries(table.columns).forEach(([columnName, column]) => {
-    properties[columnName] = mapColumnType(column, options);
-
-    if (column.notNull || column.primary) {
-      required.push(columnName);
-    }
-  });
-
-  Object.entries(table.relations).forEach(([relationName, relation]) => {
-    if (context.depth >= context.maxDepth) {
-      return;
-    }
-
-    const relationSchema = extractRelationSchema(
-      relation,
-      undefined,
-      [],
-      { ...context, depth: context.depth + 1 },
-      options
-    );
-
-    properties[relationName] = relationSchema;
-
-    const { isNullable } = mapRelationType(relation.type);
-    if (!isNullable) {
-      required.push(relationName);
-    }
-  });
-
-  const schema: OpenApiSchema = {
-    type: 'object',
-    properties,
-    required
-  };
-
-  context.schemaCache.set(cacheKey, schema);
-  return schema;
-};
-
-/**
- * Extracts schema for a single relation
- */
-const extractRelationSchema = (
-  relation: RelationDef,
-  relationPlan: HydrationRelationPlan | undefined,
-  selectedColumns: string[],
-  context: SchemaExtractionContext,
-  options: OutputSchemaOptions
-): JsonSchemaProperty => {
-  const targetTable = relation.target;
-  const { type: relationType, isNullable } = mapRelationType(relation.type);
-
-  let targetSchema: OpenApiSchema;
-
-  if (relationPlan && selectedColumns.length > 0) {
-    const plan: HydrationPlan = {
-      rootTable: targetTable.name,
-      rootPrimaryKey: relationPlan.targetPrimaryKey,
-      rootColumns: selectedColumns,
-      relations: []
-    };
-
-    targetSchema = extractSelectedSchema(targetTable, plan, context, options);
-  } else {
-    targetSchema = extractFullTableSchema(targetTable, context, options);
-  }
-
-  if (relationType === 'array') {
-    return {
-      type: 'array',
-      items: targetSchema as JsonSchemaProperty,
-      nullable: isNullable
-    };
-  }
-
-  return {
-    type: 'object' as JsonSchemaType,
-    properties: targetSchema.properties,
-    required: targetSchema.required,
-    nullable: isNullable,
-    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
  */

package/src/openapi/schema-types.ts

@@ -1,3 +1,5 @@
+import type { TableDef } from '../schema/table.js';
+
 /**
  * OpenAPI 3.1 JSON Schema type representation
  */
@@ -77,6 +79,13 @@ export interface OpenApiSchema {
   description?: string;
 }
 
+/**
+ * OpenAPI 3.1 components container
+ */
+export interface OpenApiComponents {
+  schemas: Record<string, OpenApiSchema>;
+}
+
 /**
  * Column-level schema flags
  */
@@ -101,11 +110,24 @@ export interface OutputSchemaOptions extends ColumnSchemaOptions {
   mode?: 'selected' | 'full';
   /** Maximum depth for relation recursion */
   maxDepth?: number;
+  /** Inline schemas vs $ref components */
+  refMode?: 'inline' | 'components';
+  /** Selected schemas inline vs components when refMode is components */
+  selectedRefMode?: 'inline' | 'components';
+  /** Customize component names */
+  componentName?: (table: TableDef) => string;
+  /** Emit output schema as a component $ref when refMode is components */
+  outputAsRef?: boolean;
 }
 
 export type InputRelationMode = 'ids' | 'objects' | 'mixed';
 export type InputSchemaMode = 'create' | 'update';
 
+export interface RelationSelection {
+  pick?: string[];
+  omit?: string[];
+}
+
 /**
  * Input schema generation options (write payloads)
  */
@@ -124,6 +146,10 @@ export interface InputSchemaOptions extends ColumnSchemaOptions {
   excludePrimaryKey?: boolean;
   /** Require primary key columns on update payloads */
   requirePrimaryKey?: boolean;
+  /** Remove relation foreign keys pointing to the parent from nested inputs */
+  excludeRelationForeignKeys?: boolean;
+  /** Per-relation field selection for nested inputs */
+  relationSelections?: Record<string, RelationSelection>;
 }
 
 /**
@@ -138,9 +164,10 @@ export interface SchemaOptions extends OutputSchemaOptions {
  * Input + output schema bundle
  */
 export interface OpenApiSchemaBundle {
-  output: OpenApiSchema;
+  output: OpenApiSchema | JsonSchemaProperty;
   input?: OpenApiSchema;
   parameters?: OpenApiParameter[];
+  components?: OpenApiComponents;
 }
 
 /**
@@ -155,4 +182,6 @@ export interface SchemaExtractionContext {
   depth: number;
   /** Maximum depth to recurse */
   maxDepth: number;
+  /** Component registry when using refMode=components */
+  components?: OpenApiComponents;
 }