metal-orm 1.0.90 → 1.0.92

package/src/dto/openapi/utilities.ts

@@ -1,45 +1,90 @@
-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,
-  };
-}
+import type { OpenApiSchema, OpenApiOperation, OpenApiDocumentInfo, ApiRouteDefinition, OpenApiDocument, OpenApiDialect, OpenApiType } 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 applyNullability(
+  schema: OpenApiSchema,
+  isNullable: boolean,
+  dialect: OpenApiDialect
+): OpenApiSchema {
+  if (!isNullable) {
+    const { nullable: _, ...clean } = schema;
+    return clean;
+  }
+
+  if (dialect === 'openapi-3.0') {
+    return { ...schema, nullable: true };
+  }
+
+  const type = schema.type;
+  if (Array.isArray(type)) {
+    if (!type.includes('null')) {
+      const { nullable: _, ...clean } = schema;
+      return { ...clean, type: [...type, 'null'] as OpenApiType[] };
+    }
+  } else if (type) {
+    const { nullable: _, ...clean } = schema;
+    return { ...clean, type: [type, 'null'] as OpenApiType[] };
+  } else {
+    const { nullable: _, ...clean } = schema;
+    return { ...clean, type: ['null'] as OpenApiType[] };
+  }
+
+  const { nullable: _, ...clean } = schema;
+  return clean;
+}
+
+export function isNullableColumn(col: { notNull?: boolean }): boolean {
+  return !col.notNull;
+}
+
+export function getOpenApiVersionForDialect(dialect: OpenApiDialect): string {
+  return dialect === 'openapi-3.0' ? '3.0.3' : '3.1.0';
+}
+
+export function generateOpenApiDocument(
+  info: OpenApiDocumentInfo,
+  routes: ApiRouteDefinition[],
+  options?: {
+    dialect?: OpenApiDialect;
+    allowScalarEquals?: boolean;
+  }
+): OpenApiDocument {
+  const dialect: OpenApiDialect = options?.dialect ?? 'openapi-3.1';
+  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: getOpenApiVersionForDialect(dialect),
+    info: {
+      title: info.title,
+      version: info.version,
+      description: info.description,
+    },
+    paths,
+  };
+}

package/src/dto/pagination-utils.ts

@@ -1,150 +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),
-  };
-}
+/**
+ * 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),
+  };
+}