metal-orm 1.0.79 → 1.0.81

package/src/openapi/schema-types.ts

@@ -0,0 +1,158 @@
+/**
+ * OpenAPI 3.1 JSON Schema type representation
+ */
+export type JsonSchemaType = 
+  | 'string' 
+  | 'number' 
+  | 'integer' 
+  | 'boolean' 
+  | 'object' 
+  | 'array' 
+  | 'null';
+
+/**
+ * Common OpenAPI 3.1 JSON Schema formats
+ */
+export type JsonSchemaFormat = 
+  | 'date-time' 
+  | 'date' 
+  | 'time' 
+  | 'email' 
+  | 'uuid' 
+  | 'uri' 
+  | 'binary' 
+  | 'base64';
+
+/**
+ * OpenAPI 3.1 JSON Schema property definition
+ */
+export interface JsonSchemaProperty {
+  type?: JsonSchemaType | JsonSchemaType[];
+  format?: JsonSchemaFormat;
+  description?: string;
+  nullable?: boolean;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  enum?: (string | number | boolean)[];
+  default?: unknown;
+  example?: unknown;
+  properties?: Record<string, JsonSchemaProperty>;
+  required?: string[];
+  items?: JsonSchemaProperty;
+  $ref?: string;
+  anyOf?: JsonSchemaProperty[];
+  allOf?: JsonSchemaProperty[];
+  oneOf?: 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
+ */
+export interface OpenApiSchema {
+  type: 'object';
+  properties: Record<string, JsonSchemaProperty>;
+  required: string[];
+  description?: string;
+}
+
+/**
+ * Column-level schema flags
+ */
+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;
+  /** 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
+ */
+export interface SchemaExtractionContext {
+  /** Set of already visited tables to detect cycles */
+  visitedTables: Set<string>;
+  /** Map of table names to their generated schemas */
+  schemaCache: Map<string, OpenApiSchema>;
+  /** Current extraction depth */
+  depth: number;
+  /** Maximum depth to recurse */
+  maxDepth: number;
+}

package/src/openapi/type-mappers.ts

@@ -0,0 +1,227 @@
+import type { ColumnDef } from '../schema/column-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,
+  options: ColumnSchemaOptions = {}
+): JsonSchemaProperty => {
+  const resolved = resolveColumnOptions(options);
+  const sqlType = normalizeType(column.type);
+  const baseSchema = mapSqlTypeToBaseSchema(sqlType, column);
+
+  const schema: JsonSchemaProperty = {
+    ...baseSchema,
+  };
+
+  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 ((sqlType === 'decimal' || sqlType === 'float') && column.args) {
+    if (column.args.length >= 1) {
+      schema.minimum = -(10 ** (column.args[0] as number));
+    }
+  }
+
+  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 (resolved.includeDefaults && column.default !== undefined) {
+    schema.default = column.default;
+  }
+
+  return schema;
+};
+
+const normalizeType = (type: string): string => {
+  return type.toLowerCase();
+};
+
+const mapSqlTypeToBaseSchema = (
+  sqlType: string,
+  column: ColumnDef
+): Omit<JsonSchemaProperty, 'nullable' | 'description'> => {
+  const type = normalizeType(sqlType);
+
+  const hasCustomTsType = column.tsType !== undefined;
+
+  switch (type) {
+    case 'int':
+    case 'integer':
+    case 'bigint':
+      return {
+        type: hasCustomTsType ? inferTypeFromTsType(column.tsType) : ('integer' as JsonSchemaType),
+        format: type === 'bigint' ? 'int64' : 'int32',
+        minimum: column.autoIncrement ? 1 : undefined,
+      };
+
+    case 'decimal':
+    case 'float':
+    case 'double':
+      return {
+        type: hasCustomTsType ? inferTypeFromTsType(column.tsType) : ('number' as JsonSchemaType),
+      };
+
+    case 'varchar':
+      return {
+        type: 'string' as JsonSchemaType,
+        minLength: column.notNull ? 1 : undefined,
+        maxLength: column.args?.[0] as number | undefined,
+      };
+
+    case 'text':
+      return {
+        type: 'string' as JsonSchemaType,
+        minLength: column.notNull ? 1 : undefined,
+      };
+
+    case 'char':
+      return {
+        type: 'string' as JsonSchemaType,
+        minLength: column.notNull ? column.args?.[0] as number || 1 : undefined,
+        maxLength: column.args?.[0] as number,
+      };
+
+    case 'boolean':
+      return {
+        type: 'boolean' as JsonSchemaType,
+      };
+
+    case 'json':
+      return {
+        anyOf: [
+          { type: 'object' as JsonSchemaType },
+          { type: 'array' as JsonSchemaType },
+        ],
+      };
+
+    case 'blob':
+    case 'binary':
+    case 'varbinary':
+      return {
+        type: 'string' as JsonSchemaType,
+        format: 'base64' as JsonSchemaFormat,
+      };
+
+    case 'date':
+      return {
+        type: 'string' as JsonSchemaType,
+        format: 'date' as JsonSchemaFormat,
+      };
+
+    case 'datetime':
+    case 'timestamp':
+      return {
+        type: 'string' as JsonSchemaType,
+        format: 'date-time' as JsonSchemaFormat,
+      };
+
+    case 'timestamptz':
+      return {
+        type: 'string' as JsonSchemaType,
+        format: 'date-time' as JsonSchemaFormat,
+      };
+
+    case 'uuid':
+      return {
+        type: 'string' as JsonSchemaType,
+        format: 'uuid' as JsonSchemaFormat,
+        pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$',
+      };
+
+    case 'enum':
+      return {
+        type: 'string' as JsonSchemaType,
+        enum: (column.args as (string | number | boolean)[]) || [],
+      };
+
+    default:
+      if (column.dialectTypes?.postgres && column.dialectTypes.postgres === 'bytea') {
+        return {
+          type: 'string' as JsonSchemaType,
+          format: 'base64' as JsonSchemaFormat,
+        };
+      }
+
+      return {
+        type: 'string' as JsonSchemaType,
+      };
+  }
+};
+
+const inferTypeFromTsType = (tsType: unknown): JsonSchemaType => {
+  if (typeof tsType === 'string') {
+    if (tsType === 'number') return 'number' as JsonSchemaType;
+    if (tsType === 'string') return 'string' as JsonSchemaType;
+    if (tsType === 'boolean') return 'boolean' as JsonSchemaType;
+  }
+
+  if (typeof tsType === 'function') {
+    const typeStr = tsType.name?.toLowerCase();
+    if (typeStr === 'number') return 'number' as JsonSchemaType;
+    if (typeStr === 'string') return 'string' as JsonSchemaType;
+    if (typeStr === 'boolean') return 'boolean' as JsonSchemaType;
+    if (typeStr === 'array') return 'array' as JsonSchemaType;
+    if (typeStr === 'object') return 'object' as 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
+ */
+export const mapRelationType = (
+  relationType: string
+): { type: 'object' | 'array'; isNullable: boolean } => {
+  switch (relationType) {
+    case 'HAS_MANY':
+    case 'BELONGS_TO_MANY':
+      return { type: 'array', isNullable: false };
+    case 'HAS_ONE':
+    case 'BELONGS_TO':
+      return { type: 'object', isNullable: true };
+    default:
+      return { type: 'object', isNullable: true };
+  }
+};
+
+/**
+ * Gets the OpenAPI format for temporal columns
+ */
+export const getTemporalFormat = (sqlType: string): JsonSchemaFormat | undefined => {
+  const type = normalizeType(sqlType);
+
+  switch (type) {
+    case 'date':
+      return 'date' as JsonSchemaFormat;
+    case 'datetime':
+    case 'timestamp':
+    case 'timestamptz':
+      return 'date-time' as JsonSchemaFormat;
+    default:
+      return undefined;
+  }
+};

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/select.ts

@@ -66,7 +66,8 @@ import { SelectProjectionFacet } from './select/projection-facet.js';
 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 { SelectRelationFacet } from './select/relation-facet.js';
+import { buildFilterParameters, extractSchema, SchemaOptions, OpenApiSchemaBundle } from '../openapi/index.js';
 
 type ColumnSelectionValue =
   | ColumnDef
@@ -1108,16 +1109,39 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     return this.compile(dialect).sql;
   }
 
-  /**
-   * Gets the hydration plan for the query
-   * @returns Hydration plan or undefined if none exists
-   * @example
-   * const plan = qb.include('posts').getHydrationPlan();
-   * console.log(plan?.relations); // Information about included relations
-   */
-  getHydrationPlan(): HydrationPlan | undefined {
-    return this.context.hydration.getPlan();
-  }
+  /**
+   * Gets hydration plan for query
+   * @returns Hydration plan or undefined if none exists
+   * @example
+   * const plan = qb.include('posts').getHydrationPlan();
+   * console.log(plan?.relations); // Information about included relations
+   */
+  getHydrationPlan(): HydrationPlan | undefined {
+    return this.context.hydration.getPlan();
+  }
+
+  /**
+   * Gets OpenAPI 3.1 JSON Schemas for query output and optional input payloads
+   * @param options - Schema generation options
+   * @returns OpenAPI 3.1 JSON Schemas for query output and input payloads
+   * @example
+   * const { output } = qb.select('id', 'title', 'author').getSchema();
+   * console.log(JSON.stringify(output, null, 2));
+   */
+  getSchema(options?: SchemaOptions): OpenApiSchemaBundle {
+    const plan = this.context.hydration.getPlan();
+    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;
+  }
 
   /**
    * Gets the Abstract Syntax Tree (AST) representation of the query