metal-orm 1.0.80 → 1.0.82

package/src/openapi/schema-types.ts

@@ -31,6 +31,8 @@ export interface JsonSchemaProperty {
   format?: JsonSchemaFormat;
   description?: string;
   nullable?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
   minimum?: number;
   maximum?: number;
   minLength?: number;
@@ -49,6 +51,22 @@ export interface JsonSchemaProperty {
   [key: string]: unknown;
 }
 
+/**
+ * OpenAPI 3.1 parameter definition
+ */
+export interface OpenApiParameter {
+  name: string;
+  in: 'query' | 'path' | 'header' | 'cookie';
+  description?: string;
+  required?: boolean;
+  deprecated?: boolean;
+  allowEmptyValue?: boolean;
+  style?: string;
+  explode?: boolean;
+  schema?: JsonSchemaProperty;
+  [key: string]: unknown;
+}
+
 /**
  * Complete OpenAPI 3.1 Schema for an entity or query result
  */
@@ -60,23 +78,71 @@ export interface OpenApiSchema {
 }
 
 /**
- * Schema generation options
+ * Column-level schema flags
  */
-export interface SchemaOptions {
-  /** Use selected columns only (from select/include) vs full entity */
-  mode?: 'selected' | 'full';
+export interface ColumnSchemaOptions {
   /** Include description from column comments */
   includeDescriptions?: boolean;
   /** Include enum values for enum columns */
   includeEnums?: boolean;
   /** Include column examples if available */
   includeExamples?: boolean;
-  /** Format output for pretty printing (debugging) */
-  pretty?: boolean;
+  /** Include column defaults */
+  includeDefaults?: boolean;
+  /** Include nullable flag when applicable */
+  includeNullable?: boolean;
+}
+
+/**
+ * Output schema generation options (query result)
+ */
+export interface OutputSchemaOptions extends ColumnSchemaOptions {
+  /** Use selected columns only (from select/include) vs full entity */
+  mode?: 'selected' | 'full';
   /** Maximum depth for relation recursion */
   maxDepth?: number;
 }
 
+export type InputRelationMode = 'ids' | 'objects' | 'mixed';
+export type InputSchemaMode = 'create' | 'update';
+
+/**
+ * Input schema generation options (write payloads)
+ */
+export interface InputSchemaOptions extends ColumnSchemaOptions {
+  /** Create vs update payload shape */
+  mode?: InputSchemaMode;
+  /** Include relation payloads */
+  includeRelations?: boolean;
+  /** How relations are represented (ids, nested objects, or both) */
+  relationMode?: InputRelationMode;
+  /** Maximum depth for relation recursion */
+  maxDepth?: number;
+  /** Omit read-only/generated columns from input */
+  omitReadOnly?: boolean;
+  /** Exclude primary key columns from input */
+  excludePrimaryKey?: boolean;
+  /** Require primary key columns on update payloads */
+  requirePrimaryKey?: boolean;
+}
+
+/**
+ * Schema generation options
+ */
+export interface SchemaOptions extends OutputSchemaOptions {
+  /** Input schema options, or false to skip input generation */
+  input?: InputSchemaOptions | false;
+}
+
+/**
+ * Input + output schema bundle
+ */
+export interface OpenApiSchemaBundle {
+  output: OpenApiSchema;
+  input?: OpenApiSchema;
+  parameters?: OpenApiParameter[];
+}
+
 /**
  * Schema extraction context for handling circular references
  */

package/src/openapi/type-mappers.ts

@@ -1,34 +1,46 @@
 import type { ColumnDef } from '../schema/column-types.js';
-import type { JsonSchemaProperty, JsonSchemaType, JsonSchemaFormat } from './schema-types.js';
+import type { ColumnSchemaOptions, JsonSchemaProperty, JsonSchemaType, JsonSchemaFormat } from './schema-types.js';
 
 /**
  * Maps SQL column types to OpenAPI JSON Schema types
  */
-export const mapColumnType = (column: ColumnDef): JsonSchemaProperty => {
+export const mapColumnType = (
+  column: ColumnDef,
+  options: ColumnSchemaOptions = {}
+): JsonSchemaProperty => {
+  const resolved = resolveColumnOptions(options);
   const sqlType = normalizeType(column.type);
   const baseSchema = mapSqlTypeToBaseSchema(sqlType, column);
 
   const schema: JsonSchemaProperty = {
     ...baseSchema,
-    description: column.comment,
-    nullable: !column.notNull && !column.primary,
   };
 
-  if (column.args && sqlType === 'varchar' || sqlType === 'char') {
+  if (resolved.includeDescriptions && column.comment) {
+    schema.description = column.comment;
+  }
+
+  if (resolved.includeNullable) {
+    schema.nullable = !column.notNull && !column.primary;
+  }
+
+  if ((sqlType === 'varchar' || sqlType === 'char') && column.args) {
     schema.maxLength = column.args[0] as number | undefined;
   }
 
-  if (column.args && sqlType === 'decimal' || sqlType === 'float') {
+  if ((sqlType === 'decimal' || sqlType === 'float') && column.args) {
     if (column.args.length >= 1) {
       schema.minimum = -(10 ** (column.args[0] as number));
     }
   }
 
-  if (sqlType === 'enum' && column.args && column.args.length > 0) {
+  if (!resolved.includeEnums) {
+    delete schema.enum;
+  } else if (sqlType === 'enum' && column.args && column.args.length > 0) {
     schema.enum = column.args as (string | number | boolean)[];
   }
 
-  if (column.default !== undefined) {
+  if (resolved.includeDefaults && column.default !== undefined) {
     schema.default = column.default;
   }
 
@@ -170,6 +182,14 @@ const inferTypeFromTsType = (tsType: unknown): JsonSchemaType => {
   return 'string' as JsonSchemaType;
 };
 
+const resolveColumnOptions = (options: ColumnSchemaOptions): Required<ColumnSchemaOptions> => ({
+  includeDescriptions: options.includeDescriptions ?? false,
+  includeEnums: options.includeEnums ?? true,
+  includeExamples: options.includeExamples ?? false,
+  includeDefaults: options.includeDefaults ?? true,
+  includeNullable: options.includeNullable ?? true
+});
+
 /**
  * Maps relation type to array or single object
  */

package/src/orm/unit-of-work.ts

@@ -198,12 +198,13 @@ export class UnitOfWork {
 
     const payload = this.extractColumns(tracked.table, tracked.entity as Record<string, unknown>);
     let builder = new InsertQueryBuilder(tracked.table).values(payload as Record<string, ValueOperandInput>);
-    if (this.dialect.supportsReturning()) {
-      builder = builder.returning(...this.getReturningColumns(tracked.table));
-    }
-    const compiled = builder.compile(this.dialect);
-    const results = await this.executeCompiled(compiled);
-    this.applyReturningResults(tracked, results);
+    if (this.dialect.supportsReturning()) {
+      builder = builder.returning(...this.getReturningColumns(tracked.table));
+    }
+    const compiled = builder.compile(this.dialect);
+    const results = await this.executeCompiled(compiled);
+    this.applyReturningResults(tracked, results);
+    this.applyInsertId(tracked, results);
 
     tracked.status = EntityStatus.Managed;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity as Record<string, unknown>);
@@ -344,18 +345,29 @@ export class UnitOfWork {
    * @param tracked - The tracked entity
    * @param results - Query results
    */
-  private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
-    if (!this.dialect.supportsReturning()) return;
-    const first = results[0];
-    if (!first || first.values.length === 0) return;
+  private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
+    if (!this.dialect.supportsReturning()) return;
+    const first = results[0];
+    if (!first || first.values.length === 0) return;
 
     const row = first.values[0];
     for (let i = 0; i < first.columns.length; i++) {
       const columnName = this.normalizeColumnName(first.columns[i]);
       if (!(columnName in tracked.table.columns)) continue;
-      (tracked.entity as Record<string, unknown>)[columnName] = row[i];
-    }
-  }
+      (tracked.entity as Record<string, unknown>)[columnName] = row[i];
+    }
+  }
+
+  private applyInsertId(tracked: TrackedEntity, results: QueryResult[]): void {
+    if (this.dialect.supportsReturning()) return;
+    if (tracked.pk != null) return;
+    const pkName = findPrimaryKey(tracked.table);
+    const pkColumn = tracked.table.columns[pkName];
+    if (!pkColumn?.autoIncrement) return;
+    const insertId = results.find(result => typeof result.insertId === 'number')?.insertId;
+    if (insertId == null) return;
+    (tracked.entity as Record<string, unknown>)[pkName] = insertId;
+  }
 
   /**
    * Normalizes a column name by removing quotes and table prefixes.

package/src/query-builder/relation-filter-utils.ts

@@ -144,6 +144,7 @@ const collectFromOperand = (node: OperandNode, collector: FilterTableCollector):
       break;
     case 'Literal':
     case 'AliasRef':
+    case 'Param':
       break;
     default:
       break;

package/src/query-builder/select.ts

@@ -67,7 +67,7 @@ import { SelectPredicateFacet } from './select/predicate-facet.js';
 import { SelectCTEFacet } from './select/cte-facet.js';
 import { SelectSetOpFacet } from './select/setop-facet.js';
 import { SelectRelationFacet } from './select/relation-facet.js';
-import { extractSchema, SchemaOptions, OpenApiSchema } from '../openapi/index.js';
+import { buildFilterParameters, extractSchema, SchemaOptions, OpenApiSchemaBundle } from '../openapi/index.js';
 
 type ColumnSelectionValue =
   | ColumnDef
@@ -1121,16 +1121,26 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   }
 
   /**
-   * Gets OpenAPI 3.1 JSON Schema for query result
+   * Gets OpenAPI 3.1 JSON Schemas for query output and optional input payloads
    * @param options - Schema generation options
-   * @returns OpenAPI 3.1 JSON Schema for query result
+   * @returns OpenAPI 3.1 JSON Schemas for query output and input payloads
    * @example
-   * const schema = qb.select('id', 'title', 'author').getSchema();
-   * console.log(JSON.stringify(schema, null, 2));
+   * const { output } = qb.select('id', 'title', 'author').getSchema();
+   * console.log(JSON.stringify(output, null, 2));
    */
-  getSchema(options?: SchemaOptions): OpenApiSchema {
+  getSchema(options?: SchemaOptions): OpenApiSchemaBundle {
     const plan = this.context.hydration.getPlan();
-    return extractSchema(this.env.table, plan, this.context.state.ast.columns, options);
+    const bundle = extractSchema(this.env.table, plan, this.context.state.ast.columns, options);
+    const parameters = buildFilterParameters(
+      this.env.table,
+      this.context.state.ast.where,
+      this.context.state.ast.from,
+      options ?? {}
+    );
+    if (parameters.length) {
+      return { ...bundle, parameters };
+    }
+    return bundle;
   }
 
   /**