metal-orm 1.0.89 → 1.0.90

package/src/dto/openapi/generators/relation-filter.ts

@@ -0,0 +1,210 @@
+import type { TableDef } from '../../../schema/table.js';
+import type { EntityConstructor } from '../../../orm/entity-metadata.js';
+import {
+    RelationDef,
+    BelongsToRelation,
+    HasManyRelation,
+    HasOneRelation,
+    BelongsToManyRelation,
+    RelationKinds
+} from '../../../schema/relation.js';
+import type { OpenApiSchema } from '../types.js';
+import { columnToOpenApiSchema } from './column.js';
+import { getColumnMap } from './base.js';
+
+export function relationFilterToOpenApiSchema(
+    relation: RelationDef,
+    options?: {
+        exclude?: string[];
+        include?: string[];
+    }
+): OpenApiSchema {
+    if (relation.type === RelationKinds.BelongsTo || relation.type === RelationKinds.HasOne) {
+        return singleRelationFilterToOpenApiSchema((relation as BelongsToRelation | HasOneRelation).target, options);
+    }
+
+    if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
+        return manyRelationFilterToOpenApiSchema((relation as HasManyRelation | BelongsToManyRelation).target, options);
+    }
+
+    return { type: 'object', properties: {} };
+}
+
+function singleRelationFilterToOpenApiSchema(
+    target: TableDef | EntityConstructor,
+    options?: { exclude?: string[]; include?: string[] }
+): OpenApiSchema {
+    const columns = getColumnMap(target);
+    const properties: Record<string, OpenApiSchema> = {};
+    const required: string[] = [];
+
+    for (const [key, col] of Object.entries(columns)) {
+        if (options?.exclude?.includes(key)) {
+            continue;
+        }
+
+        if (options?.include && !options.include.includes(key)) {
+            continue;
+        }
+
+        properties[key] = columnToOpenApiSchema(col);
+
+        if (col.notNull || col.primary) {
+            required.push(key);
+        }
+    }
+
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 && { required }),
+    };
+}
+
+function manyRelationFilterToOpenApiSchema(
+    target: TableDef | EntityConstructor,
+    options?: { exclude?: string[]; include?: string[] }
+): OpenApiSchema {
+    return {
+        type: 'object',
+        properties: {
+            some: {
+                type: 'object',
+                description: 'Filter related records that match all conditions',
+                properties: generateNestedProperties(target, options),
+            },
+            every: {
+                type: 'object',
+                description: 'Filter related records where all match conditions',
+                properties: generateNestedProperties(target, options),
+            },
+            none: {
+                type: 'object',
+                description: 'Filter where no related records match',
+                properties: generateNestedProperties(target, options),
+            },
+            isEmpty: {
+                type: 'boolean',
+                description: 'Filter where relation has no related records',
+            },
+            isNotEmpty: {
+                type: 'boolean',
+                description: 'Filter where relation has related records',
+            },
+        },
+    };
+}
+
+function generateNestedProperties(
+    target: TableDef | EntityConstructor,
+    options?: { exclude?: string[]; include?: string[] }
+): Record<string, OpenApiSchema> {
+    const columns = getColumnMap(target);
+    const properties: Record<string, OpenApiSchema> = {};
+
+    for (const [key, col] of Object.entries(columns)) {
+        if (options?.exclude?.includes(key)) {
+            continue;
+        }
+
+        if (options?.include && !options.include.includes(key)) {
+            continue;
+        }
+
+        properties[key] = columnToOpenApiSchema(col);
+    }
+
+    return properties;
+}
+
+export function whereInputWithRelationsToOpenApiSchema<T extends TableDef | EntityConstructor>(
+    target: T,
+    options?: {
+        columnExclude?: string[];
+        columnInclude?: string[];
+        relationExclude?: string[];
+        relationInclude?: string[];
+        maxDepth?: number;
+    }
+): OpenApiSchema {
+    const columns = getColumnMap(target);
+    const properties: Record<string, OpenApiSchema> = {};
+    const depth = options?.maxDepth ?? 3;
+
+    for (const [key, col] of Object.entries(columns)) {
+        if (options?.columnExclude?.includes(key)) {
+            continue;
+        }
+
+        if (options?.columnInclude && !options.columnInclude.includes(key)) {
+            continue;
+        }
+
+        properties[key] = columnToOpenApiSchema(col);
+    }
+
+    const tableDef = target as TableDef;
+    if (tableDef.relations && depth > 0) {
+        for (const [relationName, relation] of Object.entries(tableDef.relations)) {
+            if (options?.relationExclude?.includes(relationName)) {
+                continue;
+            }
+
+            if (options?.relationInclude && !options.relationInclude.includes(relationName)) {
+                continue;
+            }
+
+            properties[relationName] = relationFilterToOpenApiSchema(relation, {
+                exclude: options?.columnExclude,
+                include: options?.columnInclude,
+            });
+        }
+    }
+
+    return {
+        type: 'object',
+        properties,
+    };
+}
+
+export function nestedWhereInputToOpenApiSchema<T extends TableDef | EntityConstructor>(
+    target: T,
+    depth: number = 2
+): OpenApiSchema {
+    if (depth <= 0) {
+        return { type: 'object', properties: {} };
+    }
+
+    const columns = getColumnMap(target);
+    const properties: Record<string, OpenApiSchema> = {};
+
+    for (const [key, col] of Object.entries(columns)) {
+        properties[key] = columnToOpenApiSchema(col);
+    }
+
+    const tableDef = target as TableDef;
+    if (tableDef.relations) {
+        for (const [relationName, relation] of Object.entries(tableDef.relations)) {
+            properties[relationName] = relationFilterToOpenApiSchema(relation);
+
+            if (depth > 1) {
+                if (relation.type === RelationKinds.BelongsTo || relation.type === RelationKinds.HasOne) {
+                    properties[relationName] = singleRelationFilterToOpenApiSchema((relation as BelongsToRelation | HasOneRelation).target);
+                } else if (relation.type === RelationKinds.HasMany || relation.type === RelationKinds.BelongsToMany) {
+                    properties[relationName] = {
+                        type: 'object',
+                        properties: {
+                            some: nestedWhereInputToOpenApiSchema((relation as HasManyRelation | BelongsToManyRelation).target, depth - 1),
+                            every: nestedWhereInputToOpenApiSchema((relation as HasManyRelation | BelongsToManyRelation).target, depth - 1),
+                        },
+                    };
+                }
+            }
+        }
+    }
+
+    return {
+        type: 'object',
+        properties,
+    };
+}

package/src/dto/openapi/index.ts

@@ -0,0 +1,17 @@
+export * from './types.js';
+export * from './type-mappings.js';
+export * from './utilities.js';
+export * from './generators/base.js';
+export * from './generators/column.js';
+export * from './generators/dto.js';
+export * from './generators/filter.js';
+export * from './generators/relation-filter.js';
+export * from './generators/nested-dto.js';
+export type {
+  PaginationParams,
+} from './generators/pagination.js';
+export {
+  paginationParamsSchema,
+  toPaginationParams,
+  pagedResponseToOpenApiSchema
+} from './generators/pagination.js';

package/src/dto/openapi/type-mappings.ts

@@ -0,0 +1,191 @@
+import type { ColumnDef } from '../../schema/column-types.js';
+import type { OpenApiType } from './types.js';
+
+export interface TypeMappingStrategy {
+  supports(columnType: string): boolean;
+  getOpenApiType(): OpenApiType;
+  getFormat(columnType: string): string | undefined;
+}
+
+export class IntegerTypeStrategy implements TypeMappingStrategy {
+  private readonly types = ['INT', 'INTEGER'];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'integer';
+  }
+
+  getFormat(): string | undefined {
+    return 'int32';
+  }
+}
+
+export class BigIntTypeStrategy implements TypeMappingStrategy {
+  private readonly types = ['BIGINT'];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'integer';
+  }
+
+  getFormat(): string | undefined {
+    return 'int64';
+  }
+}
+
+export class DecimalTypeStrategy implements TypeMappingStrategy {
+  private readonly types = ['DECIMAL', 'FLOAT', 'DOUBLE'];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'number';
+  }
+
+  getFormat(): string | undefined {
+    return 'double';
+  }
+}
+
+export class BooleanTypeStrategy implements TypeMappingStrategy {
+  private readonly types = ['BOOLEAN'];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'boolean';
+  }
+
+  getFormat(): undefined {
+    return undefined;
+  }
+}
+
+export class UuidTypeStrategy implements TypeMappingStrategy {
+  private readonly types = ['UUID'];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'string';
+  }
+
+  getFormat(): string {
+    return 'uuid';
+  }
+}
+
+export class DateTimeTypeStrategy implements TypeMappingStrategy {
+  private readonly types = ['DATE', 'DATETIME', 'TIMESTAMP', 'TIMESTAMPTZ'];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'string';
+  }
+
+  getFormat(columnType: string = 'DATETIME'): string {
+    return columnType.toUpperCase() === 'DATE' ? 'date' : 'date-time';
+  }
+}
+
+export class StringTypeStrategy implements TypeMappingStrategy {
+  private readonly types = [
+    'JSON', 'TEXT', 'VARCHAR', 'CHAR', 'BINARY',
+    'VARBINARY', 'BLOB', 'ENUM'
+  ];
+
+  supports(type: string): boolean {
+    return this.types.includes(type.toUpperCase());
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'string';
+  }
+
+  getFormat(): undefined {
+    return undefined;
+  }
+}
+
+export class DefaultTypeStrategy implements TypeMappingStrategy {
+  supports(): boolean {
+    return true;
+  }
+
+  getOpenApiType(): OpenApiType {
+    return 'string';
+  }
+
+  getFormat(): undefined {
+    return undefined;
+  }
+}
+
+export class TypeMappingService {
+  private readonly strategies: TypeMappingStrategy[];
+
+  constructor() {
+    this.strategies = [
+      new IntegerTypeStrategy(),
+      new BigIntTypeStrategy(),
+      new DecimalTypeStrategy(),
+      new BooleanTypeStrategy(),
+      new DateTimeTypeStrategy(),
+      new UuidTypeStrategy(),
+      new StringTypeStrategy(),
+      new DefaultTypeStrategy(),
+    ];
+  }
+
+  getOpenApiType(column: ColumnDef): OpenApiType {
+    const strategy = this.findStrategy(column.type);
+    return strategy.getOpenApiType();
+  }
+
+  getFormat(column: ColumnDef): string | undefined {
+    const strategy = this.findStrategy(column.type);
+    return strategy.getFormat(column.type);
+  }
+
+  private findStrategy(columnType: string): TypeMappingStrategy {
+    for (const strategy of this.strategies) {
+      if (strategy.supports(columnType)) {
+        return strategy;
+      }
+    }
+    return this.strategies[this.strategies.length - 1];
+  }
+
+  registerStrategy(strategy: TypeMappingStrategy, index?: number): void {
+    if (index !== undefined) {
+      this.strategies.splice(index, 0, strategy);
+    } else {
+      this.strategies.push(strategy);
+    }
+  }
+}
+
+export const typeMappingService = new TypeMappingService();
+
+export function columnTypeToOpenApiType(col: ColumnDef): OpenApiType {
+  return typeMappingService.getOpenApiType(col);
+}
+
+export function columnTypeToOpenApiFormat(col: ColumnDef): string | undefined {
+  return typeMappingService.getFormat(col);
+}

package/src/dto/openapi/types.ts

@@ -0,0 +1,83 @@
+export type OpenApiType =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'null';
+
+export interface OpenApiSchema {
+  type?: OpenApiType | OpenApiType[];
+  properties?: Record<string, OpenApiSchema>;
+  items?: OpenApiSchema;
+  required?: string[];
+  enum?: unknown[];
+  format?: string;
+  description?: string;
+  example?: unknown;
+  nullable?: boolean;
+  minimum?: number;
+  maximum?: number;
+  default?: unknown;
+  $ref?: string;
+  allOf?: OpenApiSchema[];
+  oneOf?: OpenApiSchema[];
+}
+
+export interface OpenApiParameter {
+  name: string;
+  in: 'query' | 'path' | 'header' | 'cookie';
+  required?: boolean;
+  schema?: OpenApiSchema;
+  description?: string;
+}
+
+export interface OpenApiOperation {
+  summary?: string;
+  description?: string;
+  parameters?: OpenApiParameter[];
+  requestBody?: {
+    description?: string;
+    required?: boolean;
+    content: {
+      'application/json': {
+        schema: OpenApiSchema;
+      };
+    };
+  };
+  responses?: Record<string, {
+    description: string;
+    content?: {
+      'application/json': {
+        schema: OpenApiSchema;
+      };
+    };
+  }>;
+}
+
+export interface OpenApiDocumentInfo {
+  title: string;
+  version: string;
+  description?: string;
+}
+
+export interface ApiRouteDefinition {
+  path: string;
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+  operation: OpenApiOperation;
+}
+
+export interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export interface OpenApiComponent {
+  schemas?: Record<string, OpenApiSchema>;
+  parameters?: Record<string, OpenApiSchema>;
+  responses?: Record<string, OpenApiSchema>;
+  securitySchemes?: Record<string, unknown>;
+}

package/src/dto/openapi/utilities.ts

@@ -0,0 +1,45 @@
+import type { OpenApiSchema, OpenApiOperation, OpenApiDocumentInfo, ApiRouteDefinition } from './types.js';
+
+export function schemaToJson(schema: OpenApiSchema): string {
+  return JSON.stringify(schema, null, 2);
+}
+
+export function deepCloneSchema(schema: OpenApiSchema): OpenApiSchema {
+  return JSON.parse(JSON.stringify(schema));
+}
+
+export function mergeSchemas(base: OpenApiSchema, override: Partial<OpenApiSchema>): OpenApiSchema {
+  return {
+    ...base,
+    ...override,
+    properties: {
+      ...base.properties,
+      ...(override.properties || {}),
+    },
+    required: override.required ?? base.required,
+  };
+}
+
+export function generateOpenApiDocument(
+  info: OpenApiDocumentInfo,
+  routes: ApiRouteDefinition[]
+): Record<string, unknown> {
+  const paths: Record<string, Record<string, OpenApiOperation>> = {};
+
+  for (const route of routes) {
+    if (!paths[route.path]) {
+      paths[route.path] = {};
+    }
+    paths[route.path][route.method] = route.operation;
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: {
+      title: info.title,
+      version: info.version,
+      description: info.description,
+    },
+    paths,
+  };
+}

package/src/dto/pagination-utils.ts

@@ -0,0 +1,150 @@
+/**
+ * Pagination utility functions for DTO responses.
+ * Converts basic PaginatedResult to enhanced PagedResponse with computed metadata.
+ */
+
+import type { PaginatedResult } from '../query-builder/select.js';
+import type { PagedResponse } from './dto-types.js';
+
+/**
+ * Converts PaginatedResult to PagedResponse with computed metadata.
+ *
+ * @param result - The basic paginated result from executePaged()
+ * @returns Enhanced paginated response with totalPages, hasNextPage, hasPrevPage
+ *
+ * @example
+ * ```ts
+ * // In your controller
+ * const basic = await qb.executePaged(session, { page: 2, pageSize: 20 });
+ * const response = toPagedResponse(basic);
+ * return res.json(response);
+ * // → { items: [...], totalItems: 150, page: 2, pageSize: 20,
+ * //     totalPages: 8, hasNextPage: true, hasPrevPage: true }
+ * ```
+ */
+export function toPagedResponse<T>(
+  result: PaginatedResult<T>
+): PagedResponse<T> {
+  const { items, totalItems, page, pageSize } = result;
+
+  const totalPages = calculateTotalPages(totalItems, pageSize);
+  const next = hasNextPage(page, totalPages);
+  const prev = hasPrevPage(page);
+
+  return {
+    items,
+    totalItems,
+    page,
+    pageSize,
+    totalPages,
+    hasNextPage: next,
+    hasPrevPage: prev,
+  };
+}
+
+/**
+ * Creates a reusable toPagedResponse function with fixed pageSize.
+ * Useful when your API uses a consistent page size across all endpoints.
+ *
+ * @param fixedPageSize - The fixed page size to use
+ * @returns A function that converts PaginatedResult to PagedResponse
+ *
+ * @example
+ * ```ts
+ * const toUserPagedResponse = toPagedResponseBuilder<UserResponse>(20);
+ *
+ * app.get('/users', async (req, res) => {
+ *   const basic = await qb.executePaged(session, { page: req.query.page || 1, pageSize: 20 });
+ *   const response = toUserPagedResponse(basic);
+ *   res.json(response);
+ * });
+ * ```
+ */
+export function toPagedResponseBuilder<T>(
+  fixedPageSize: number
+): (result: Omit<PaginatedResult<T>, 'pageSize'> & { pageSize?: number }) => PagedResponse<T> {
+  return (result) => toPagedResponse({
+    ...result,
+    pageSize: fixedPageSize,
+  });
+}
+
+/**
+ * Calculates total pages from total items and page size.
+ *
+ * @param totalItems - Total number of items
+ * @param pageSize - Number of items per page
+ * @returns Total number of pages (minimum 1)
+ *
+ * @example
+ * ```ts
+ * const totalPages = calculateTotalPages(150, 20); // → 8
+ * const totalPages = calculateTotalPages(150, 50); // → 3
+ * ```
+ */
+export function calculateTotalPages(totalItems: number, pageSize: number): number {
+  if (pageSize <= 0) {
+    throw new Error('pageSize must be greater than 0');
+  }
+  return Math.max(1, Math.ceil(totalItems / pageSize));
+}
+
+/**
+ * Checks if there is a next page.
+ *
+ * @param currentPage - Current page number (1-based)
+ * @param totalPages - Total number of pages
+ * @returns true if there is a next page
+ *
+ * @example
+ * ```ts
+ * const hasNext = hasNextPage(2, 8); // → true
+ * const hasNext = hasNextPage(8, 8); // → false
+ * ```
+ */
+export function hasNextPage(currentPage: number, totalPages: number): boolean {
+  return currentPage < totalPages;
+}
+
+/**
+ * Checks if there is a previous page.
+ *
+ * @param currentPage - Current page number (1-based)
+ * @returns true if there is a previous page
+ *
+ * @example
+ * ```ts
+ * const hasPrev = hasPrevPage(2); // → true
+ * const hasPrev = hasPrevPage(1); // → false
+ * ```
+ */
+export function hasPrevPage(currentPage: number): boolean {
+  return currentPage > 1;
+}
+
+/**
+ * Computes all pagination metadata from basic pagination info.
+ *
+ * @param totalItems - Total number of items
+ * @param page - Current page number (1-based)
+ * @param pageSize - Number of items per page
+ * @returns Object with totalPages, hasNextPage, hasPrevPage
+ *
+ * @example
+ * ```ts
+ * const meta = computePaginationMetadata(150, 2, 20);
+ * // → { totalPages: 8, hasNextPage: true, hasPrevPage: true }
+ * ```
+ */
+export function computePaginationMetadata(
+  totalItems: number,
+  page: number,
+  pageSize: number
+): Pick<PagedResponse<unknown>, 'totalPages' | 'hasNextPage' | 'hasPrevPage'> {
+  const totalPages = calculateTotalPages(totalItems, pageSize);
+  return {
+    totalPages,
+    hasNextPage: hasNextPage(page, totalPages),
+    hasPrevPage: hasPrevPage(page),
+  };
+}