metal-orm 1.0.88 → 1.0.89

package/package.json

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

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

@@ -1,11 +1,13 @@
 import type { TableDef } from '../schema/table.js';
 import type { RelationDef } from '../schema/relation.js';
+import { RelationKinds } from '../schema/relation.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 
 import type {
   OpenApiSchema,
   SchemaExtractionContext,
   InputSchemaOptions,
+  RelationSelection,
   JsonSchemaProperty,
   JsonSchemaType
 } from './schema-types.js';
@@ -55,6 +57,7 @@ export const extractInputSchema = (
   if (options.includeRelations && context.depth < context.maxDepth) {
     for (const [relationName, relation] of Object.entries(table.relations)) {
       properties[relationName] = extractInputRelationSchema(
+        relationName,
         relation,
         { ...context, depth: context.depth + 1 },
         options
@@ -101,6 +104,7 @@ const buildPrimaryKeySchema = (
 };
 
 const extractInputRelationSchema = (
+  relationName: string,
   relation: RelationDef,
   context: SchemaExtractionContext,
   options: InputSchemaOptions
@@ -117,7 +121,11 @@ const extractInputRelationSchema = (
   }
 
   if (allowObjects) {
-    const targetSchema = extractInputSchema(relation.target, context, options);
+    let targetSchema = extractInputSchema(relation.target, context, options);
+    targetSchema = applyRelationSelection(targetSchema, options.relationSelections?.[relationName]);
+    if (options.excludeRelationForeignKeys && isRelationForeignKeyToParent(relation)) {
+      targetSchema = removeForeignKey(targetSchema, relation.foreignKey);
+    }
     variants.push(targetSchema as JsonSchemaProperty);
   }
 
@@ -137,3 +145,49 @@ const extractInputRelationSchema = (
     nullable: isNullable
   };
 };
+
+const applyRelationSelection = (
+  schema: OpenApiSchema,
+  selection?: RelationSelection
+): OpenApiSchema => {
+  if (!selection || (selection.pick === undefined && selection.omit === undefined)) {
+    return schema;
+  }
+
+  const hasPick = selection.pick !== undefined;
+  const pick = hasPick ? new Set(selection.pick ?? []) : undefined;
+  const omit = selection.omit !== undefined ? new Set(selection.omit ?? []) : undefined;
+  const properties = Object.entries(schema.properties).reduce<Record<string, JsonSchemaProperty>>(
+    (acc, [key, value]) => {
+      if (pick && !pick.has(key)) return acc;
+      if (omit && omit.has(key)) return acc;
+      acc[key] = value;
+      return acc;
+    },
+    {}
+  );
+  const required = schema.required.filter(name => properties[name] !== undefined);
+
+  return {
+    ...schema,
+    properties,
+    required
+  };
+};
+
+const removeForeignKey = (schema: OpenApiSchema, foreignKey?: string): OpenApiSchema => {
+  if (!foreignKey || !schema.properties[foreignKey]) return schema;
+  const properties = { ...schema.properties };
+  delete properties[foreignKey];
+  const required = schema.required.filter(name => name !== foreignKey);
+
+  return {
+    ...schema,
+    properties,
+    required
+  };
+};
+
+const isRelationForeignKeyToParent = (relation: RelationDef): relation is RelationDef & { foreignKey: string } => {
+  return relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne;
+};

package/src/openapi/schema-extractor.ts

@@ -7,7 +7,8 @@ import type {
   OpenApiSchemaBundle,
   SchemaOptions,
   OutputSchemaOptions,
-  InputSchemaOptions
+  InputSchemaOptions,
+  JsonSchemaProperty
 } from './schema-types.js';
 import { extractInputSchema } from './schema-extractor-input.js';
 import { extractOutputSchema } from './schema-extractor-output.js';
@@ -36,15 +37,20 @@ export const extractSchema = (
   if (outputOptions.refMode === 'components') {
     outputContext.components = { schemas: {} };
   }
-  const output = extractOutputSchema(table, plan, projectionNodes, outputContext, outputOptions);
+  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 (outputOptions.refMode === 'components' && outputContext.components && !hasComputedFields) {
+  if (canUseComponents) {
     const componentName = useSelected && plan
       ? resolveSelectedComponentName(table, plan, outputOptions)
       : resolveComponentName(table, outputOptions);
-    registerComponentSchema(componentName, output, outputContext);
+    registerComponentSchema(componentName, outputSchema, outputContext);
+    if (outputOptions.outputAsRef) {
+      output = { $ref: `#/components/schemas/${componentName}` };
+    }
   }
 
   const inputOptions = resolveInputOptions(options);
@@ -79,7 +85,8 @@ const resolveOutputOptions = (options: SchemaOptions): OutputSchemaOptions => ({
   maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
   refMode: options.refMode ?? 'inline',
   selectedRefMode: options.selectedRefMode ?? 'inline',
-  componentName: options.componentName
+  componentName: options.componentName,
+  outputAsRef: options.outputAsRef ?? false
 });
 
 const resolveInputOptions = (options: SchemaOptions): InputSchemaOptions | undefined => {
@@ -99,7 +106,9 @@ 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')
+    requirePrimaryKey: input.requirePrimaryKey ?? (mode === 'update'),
+    excludeRelationForeignKeys: input.excludeRelationForeignKeys ?? false,
+    relationSelections: input.relationSelections
   };
 };
 

package/src/openapi/schema-types.ts

@@ -116,11 +116,18 @@ export interface OutputSchemaOptions extends ColumnSchemaOptions {
   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)
  */
@@ -139,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>;
 }
 
 /**
@@ -153,7 +164,7 @@ export interface SchemaOptions extends OutputSchemaOptions {
  * Input + output schema bundle
  */
 export interface OpenApiSchemaBundle {
-  output: OpenApiSchema;
+  output: OpenApiSchema | JsonSchemaProperty;
   input?: OpenApiSchema;
   parameters?: OpenApiParameter[];
   components?: OpenApiComponents;