metal-orm 1.0.86 → 1.0.88

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.86",
+  "version": "1.0.88",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/openapi/schema-extractor-input.ts

@@ -0,0 +1,139 @@
+import type { TableDef } from '../schema/table.js';
+import type { RelationDef } from '../schema/relation.js';
+import { findPrimaryKey } from '../query-builder/hydration-planner.js';
+
+import type {
+  OpenApiSchema,
+  SchemaExtractionContext,
+  InputSchemaOptions,
+  JsonSchemaProperty,
+  JsonSchemaType
+} from './schema-types.js';
+import { mapColumnType, mapRelationType } from './type-mappers.js';
+import { buildCircularReferenceSchema } from './schema-extractor-utils.js';
+
+/**
+ * Input schema extraction (write payloads)
+ */
+export 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
+  };
+};

package/src/openapi/schema-extractor-output.ts

@@ -0,0 +1,427 @@
+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,
+  OutputSchemaOptions,
+  JsonSchemaProperty,
+  JsonSchemaType
+} from './schema-types.js';
+import { mapColumnType, mapRelationType } from './type-mappers.js';
+import {
+  buildCircularReferenceSchema,
+  ensureComponentRef,
+  hasComputedProjection,
+  resolveComponentName,
+  resolveSelectedComponentName,
+  shouldUseSelectedSchema
+} from './schema-extractor-utils.js';
+
+/**
+ * Output schema extraction (query results)
+ */
+export const extractOutputSchema = (
+  table: TableDef,
+  plan: HydrationPlan | undefined,
+  projectionNodes: ProjectionNode[] | undefined,
+  context: SchemaExtractionContext,
+  options: OutputSchemaOptions
+): OpenApiSchema => {
+  const hasComputedFields = hasComputedProjection(projectionNodes);
+
+  if (hasComputedFields) {
+    return extractFromProjectionNodes(table, projectionNodes!, context, options);
+  }
+
+  if (shouldUseSelectedSchema(options, plan, projectionNodes)) {
+    return extractSelectedSchema(table, plan, context, options);
+  }
+
+  return extractFullTableSchema(table, context, options);
+};
+
+/**
+ * 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
+  };
+};
+
+/**
+ * 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);
+
+  if (options.refMode === 'components' && context.components) {
+    if (relationPlan && selectedColumns.length > 0 && options.selectedRefMode === 'components') {
+      const plan: HydrationPlan = {
+        rootTable: targetTable.name,
+        rootPrimaryKey: relationPlan.targetPrimaryKey,
+        rootColumns: selectedColumns,
+        relations: []
+      };
+      const componentName = resolveSelectedComponentName(targetTable, plan, options);
+      const ref = ensureComponentRef(
+        targetTable,
+        componentName,
+        context,
+        () => extractSelectedSchema(targetTable, plan, context, options)
+      );
+
+      if (relationType === 'array') {
+        return {
+          type: 'array',
+          items: ref,
+          nullable: isNullable
+        };
+      }
+
+      return {
+        ...ref,
+        nullable: isNullable
+      };
+    }
+
+    const componentName = resolveComponentName(targetTable, options);
+    const ref = ensureComponentRef(
+      targetTable,
+      componentName,
+      context,
+      () => extractFullTableSchema(targetTable, context, options)
+    );
+
+    if (relationType === 'array') {
+      return {
+        type: 'array',
+        items: ref,
+        nullable: isNullable
+      };
+    }
+
+    return {
+      ...ref,
+      nullable: isNullable
+    };
+  }
+
+  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
+  };
+};

package/src/openapi/schema-extractor-utils.ts

@@ -0,0 +1,110 @@
+import type { TableDef } from '../schema/table.js';
+import type { HydrationPlan } from '../core/hydration/types.js';
+import type { ProjectionNode } from '../query-builder/select-query-state.js';
+import type {
+  OpenApiSchema,
+  SchemaExtractionContext,
+  OutputSchemaOptions,
+  JsonSchemaProperty,
+  JsonSchemaType
+} from './schema-types.js';
+
+export const hasComputedProjection = (projectionNodes?: ProjectionNode[]): boolean =>
+  Boolean(projectionNodes && projectionNodes.some(node => node.type !== 'Column'));
+
+export const shouldUseSelectedSchema = (
+  options: OutputSchemaOptions,
+  plan: HydrationPlan | undefined,
+  projectionNodes: ProjectionNode[] | undefined
+): boolean => {
+  if (!plan || options.mode !== 'selected') return false;
+  if (hasComputedProjection(projectionNodes)) return false;
+  if (options.refMode === 'components' && options.selectedRefMode !== 'components') return false;
+  return true;
+};
+
+export const resolveComponentName = (table: TableDef, options: OutputSchemaOptions): string =>
+  options.componentName ? options.componentName(table) : table.name;
+
+const normalizeColumns = (columns: string[]): string[] =>
+  Array.from(new Set(columns)).sort((a, b) => a.localeCompare(b));
+
+const buildSelectionSignature = (plan: HydrationPlan): string => {
+  const relations = plan.relations
+    .map(relation => ({
+      name: relation.name,
+      columns: normalizeColumns(relation.columns)
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return JSON.stringify({
+    root: normalizeColumns(plan.rootColumns),
+    relations
+  });
+};
+
+const hashString = (value: string): string => {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = (hash * 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+};
+
+export const resolveSelectedComponentName = (
+  table: TableDef,
+  plan: HydrationPlan,
+  options: OutputSchemaOptions
+): string => {
+  const base = resolveComponentName(table, options);
+  const signature = buildSelectionSignature(plan);
+  return `${base}__sel_${hashString(signature)}`;
+};
+
+export const ensureComponentRef = (
+  table: TableDef,
+  componentName: string,
+  context: SchemaExtractionContext,
+  schemaFactory: () => OpenApiSchema
+): JsonSchemaProperty => {
+  if (context.components && !context.components.schemas[componentName]) {
+    if (!context.visitedTables.has(table.name)) {
+      context.components.schemas[componentName] = schemaFactory();
+    }
+  }
+
+  return { $ref: `#/components/schemas/${componentName}` };
+};
+
+export const registerComponentSchema = (
+  name: string,
+  schema: OpenApiSchema,
+  context: SchemaExtractionContext
+): void => {
+  if (!context.components) return;
+  if (!context.components.schemas[name]) {
+    context.components.schemas[name] = schema;
+  }
+};
+
+export const createContext = (maxDepth: number): SchemaExtractionContext => ({
+  visitedTables: new Set(),
+  schemaCache: new Map(),
+  depth: 0,
+  maxDepth
+});
+
+export const buildCircularReferenceSchema = (
+  tableName: string,
+  kind: 'input' | 'output'
+): OpenApiSchema => ({
+  type: 'object',
+  properties: {
+    _ref: {
+      type: 'string' as JsonSchemaType,
+      description: `Circular ${kind} reference to ${tableName}`
+    }
+  },
+  required: []
+});