metal-orm 1.0.78 → 1.0.80

package/src/openapi/type-mappers.ts

@@ -0,0 +1,207 @@
+import type { ColumnDef } from '../schema/column-types.js';
+import type { JsonSchemaProperty, JsonSchemaType, JsonSchemaFormat } from './schema-types.js';
+
+/**
+ * Maps SQL column types to OpenAPI JSON Schema types
+ */
+export const mapColumnType = (column: ColumnDef): JsonSchemaProperty => {
+  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') {
+    schema.maxLength = column.args[0] as number | undefined;
+  }
+
+  if (column.args && sqlType === 'decimal' || sqlType === 'float') {
+    if (column.args.length >= 1) {
+      schema.minimum = -(10 ** (column.args[0] as number));
+    }
+  }
+
+  if (sqlType === 'enum' && column.args && column.args.length > 0) {
+    schema.enum = column.args as (string | number | boolean)[];
+  }
+
+  if (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;
+};
+
+/**
+ * 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/query-builder/select/select-operations.ts

@@ -73,43 +73,41 @@ export async function executeCount(
   if (typeof value === 'number') return value;
   if (typeof value === 'bigint') return Number(value);
   if (typeof value === 'string') return Number(value);
-  return value === null || value === undefined ? 0 : Number(value);
-}
-
-export interface PaginatedResult<T> {
-  items: T[];
-  totalItems: number;
-  page: number;
-  pageSize: number;
-}
-
-/**
- * Executes paged queries using the provided builder helpers.
- */
-export async function executePagedQuery<T, TTable extends TableDef>(
-  builder: SelectQueryBuilder<T, TTable>,
-  session: OrmSession,
-  options: { page: number; pageSize: number },
-  countCallback: (session: OrmSession) => Promise<number>
-): Promise<PaginatedResult<T>> {
-  const { page, pageSize } = options;
-
-  if (!Number.isInteger(page) || page < 1) {
-    throw new Error('executePaged: page must be an integer >= 1');
-  }
-  if (!Number.isInteger(pageSize) || pageSize < 1) {
-    throw new Error('executePaged: pageSize must be an integer >= 1');
-  }
-
-  const offset = (page - 1) * pageSize;
-
-  const [items, totalItems] = await Promise.all([
-    builder.limit(pageSize).offset(offset).execute(session),
-    countCallback(session)
-  ]);
-
-  return { items, totalItems, page, pageSize };
-}
+  return value === null || value === undefined ? 0 : Number(value);
+}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  totalItems: number;
+  page: number;
+  pageSize: number;
+}
+
+/**
+ * Executes paged queries using the provided builder helpers.
+ */
+export async function executePagedQuery<T, TTable extends TableDef>(
+  builder: SelectQueryBuilder<T, TTable>,
+  session: OrmSession,
+  options: { page: number; pageSize: number },
+  countCallback: (session: OrmSession) => Promise<number>
+): Promise<PaginatedResult<T>> {
+  const { page, pageSize } = options;
+
+  if (!Number.isInteger(page) || page < 1) {
+    throw new Error('executePaged: page must be an integer >= 1');
+  }
+  if (!Number.isInteger(pageSize) || pageSize < 1) {
+    throw new Error('executePaged: pageSize must be an integer >= 1');
+  }
+
+  const offset = (page - 1) * pageSize;
+
+  const totalItems = await countCallback(session);
+  const items = await builder.limit(pageSize).offset(offset).execute(session);
+
+  return { items, totalItems, page, pageSize };
+}
 
 /**
  * Builds an EXISTS or NOT EXISTS predicate for a related table.

package/src/query-builder/select.ts

@@ -29,17 +29,17 @@ import {
   SelectQueryBuilderEnvironment
 } from './select-query-builder-deps.js';
 import { ColumnSelector } from './column-selector.js';
-import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
-import { RelationKinds } from '../schema/relation.js';
-import {
-  RelationIncludeInput,
-  RelationIncludeNodeInput,
-  NormalizedRelationIncludeTree,
-  cloneRelationIncludeTree,
-  mergeRelationIncludeTrees,
-  normalizeRelationInclude,
-  normalizeRelationIncludeNode
-} from './relation-include-tree.js';
+import { RelationIncludeOptions, RelationTargetColumns, TypedRelationIncludeOptions } from './relation-types.js';
+import { RelationKinds } from '../schema/relation.js';
+import {
+  RelationIncludeInput,
+  RelationIncludeNodeInput,
+  NormalizedRelationIncludeTree,
+  cloneRelationIncludeTree,
+  mergeRelationIncludeTrees,
+  normalizeRelationInclude,
+  normalizeRelationIncludeNode
+} from './relation-include-tree.js';
 import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../core/sql/sql.js';
 import { EntityInstance, RelationMap } from '../schema/types.js';
 import type { ColumnToTs, InferRow } from '../schema/types.js';
@@ -50,23 +50,24 @@ import { executeHydrated, executeHydratedPlain, executeHydratedWithContexts } fr
 import { EntityConstructor } from '../orm/entity-metadata.js';
 import { materializeAs } from '../orm/entity-materializer.js';
 import { resolveSelectQuery } from './query-resolution.js';
-import {
-  applyOrderBy,
-  buildWhereHasPredicate,
-  executeCount,
-  executePagedQuery,
-  PaginatedResult,
-  RelationCallback,
-  WhereHasOptions
-} from './select/select-operations.js';
-export type { PaginatedResult };
+import {
+  applyOrderBy,
+  buildWhereHasPredicate,
+  executeCount,
+  executePagedQuery,
+  PaginatedResult,
+  RelationCallback,
+  WhereHasOptions
+} from './select/select-operations.js';
+export type { PaginatedResult };
 import { SelectFromFacet } from './select/from-facet.js';
 import { SelectJoinFacet } from './select/join-facet.js';
 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 { extractSchema, SchemaOptions, OpenApiSchema } from '../openapi/index.js';
 
 type ColumnSelectionValue =
   | ColumnDef
@@ -115,11 +116,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   private readonly predicateFacet: SelectPredicateFacet;
   private readonly cteFacet: SelectCTEFacet;
   private readonly setOpFacet: SelectSetOpFacet;
-  private readonly relationFacet: SelectRelationFacet;
-  private readonly lazyRelations: Set<string>;
-  private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
-  private readonly entityConstructor?: EntityConstructor;
-  private readonly includeTree: NormalizedRelationIncludeTree;
+  private readonly relationFacet: SelectRelationFacet;
+  private readonly lazyRelations: Set<string>;
+  private readonly lazyRelationOptions: Map<string, RelationIncludeOptions>;
+  private readonly entityConstructor?: EntityConstructor;
+  private readonly includeTree: NormalizedRelationIncludeTree;
 
   /**
    * Creates a new SelectQueryBuilder instance
@@ -128,16 +129,16 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @param hydration - Optional hydration manager
    * @param dependencies - Optional query builder dependencies
    */
-  constructor(
-    table: TTable,
-    state?: SelectQueryState,
-    hydration?: HydrationManager,
-    dependencies?: Partial<SelectQueryBuilderDependencies>,
-    lazyRelations?: Set<string>,
-    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
-    entityConstructor?: EntityConstructor,
-    includeTree?: NormalizedRelationIncludeTree
-  ) {
+  constructor(
+    table: TTable,
+    state?: SelectQueryState,
+    hydration?: HydrationManager,
+    dependencies?: Partial<SelectQueryBuilderDependencies>,
+    lazyRelations?: Set<string>,
+    lazyRelationOptions?: Map<string, RelationIncludeOptions>,
+    entityConstructor?: EntityConstructor,
+    includeTree?: NormalizedRelationIncludeTree
+  ) {
     const deps = resolveSelectQueryBuilderDependencies(dependencies);
     this.env = { table, deps };
     const createAstService = (nextState: SelectQueryState) => deps.createQueryAstService(table, nextState);
@@ -147,11 +148,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
       state: initialState,
       hydration: initialHydration
     };
-    this.lazyRelations = new Set(lazyRelations ?? []);
-    this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
-    this.entityConstructor = entityConstructor;
-    this.includeTree = includeTree ?? {};
-    this.columnSelector = deps.createColumnSelector(this.env);
+    this.lazyRelations = new Set(lazyRelations ?? []);
+    this.lazyRelationOptions = new Map(lazyRelationOptions ?? []);
+    this.entityConstructor = entityConstructor;
+    this.includeTree = includeTree ?? {};
+    this.columnSelector = deps.createColumnSelector(this.env);
     const relationManager = deps.createRelationManager(this.env);
     this.fromFacet = new SelectFromFacet(this.env, createAstService);
     this.joinFacet = new SelectJoinFacet(this.env, createAstService);
@@ -168,23 +169,23 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @param lazyRelations - Updated lazy relations set
    * @returns New SelectQueryBuilder instance
    */
-  private clone<TNext = T>(
-    context: SelectQueryBuilderContext = this.context,
-    lazyRelations = new Set(this.lazyRelations),
-    lazyRelationOptions = new Map(this.lazyRelationOptions),
-    includeTree = this.includeTree
-  ): SelectQueryBuilder<TNext, TTable> {
-    return new SelectQueryBuilder(
-      this.env.table as TTable,
-      context.state,
-      context.hydration,
-      this.env.deps,
-      lazyRelations,
-      lazyRelationOptions,
-      this.entityConstructor,
-      includeTree
-    ) as SelectQueryBuilder<TNext, TTable>;
-  }
+  private clone<TNext = T>(
+    context: SelectQueryBuilderContext = this.context,
+    lazyRelations = new Set(this.lazyRelations),
+    lazyRelationOptions = new Map(this.lazyRelationOptions),
+    includeTree = this.includeTree
+  ): SelectQueryBuilder<TNext, TTable> {
+    return new SelectQueryBuilder(
+      this.env.table as TTable,
+      context.state,
+      context.hydration,
+      this.env.deps,
+      lazyRelations,
+      lazyRelationOptions,
+      this.entityConstructor,
+      includeTree
+    ) as SelectQueryBuilder<TNext, TTable>;
+  }
 
   /**
    * Applies an alias to the root FROM table.
@@ -564,42 +565,42 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * qb.include('posts');
    * @example
    * qb.include('posts', { columns: ['id', 'title', 'published'] });
-   * @example
-   * qb.include('posts', {
-   *   columns: ['id', 'title'],
-   *   where: eq(postTable.columns.published, true)
-   * });
-   * @example
-   * qb.include({ posts: { include: { author: true } } });
-   */
-  include<K extends keyof TTable['relations'] & string>(
-    relationName: K,
-    options?: RelationIncludeNodeInput<TTable['relations'][K]>
-  ): SelectQueryBuilder<T, TTable>;
-  include(relations: RelationIncludeInput<TTable>): SelectQueryBuilder<T, TTable>;
-  include<K extends keyof TTable['relations'] & string>(
-    relationNameOrRelations: K | RelationIncludeInput<TTable>,
-    options?: RelationIncludeNodeInput<TTable['relations'][K]>
-  ): SelectQueryBuilder<T, TTable> {
-    if (typeof relationNameOrRelations === 'object' && relationNameOrRelations !== null) {
-      const normalized = normalizeRelationInclude(relationNameOrRelations as RelationIncludeInput<TableDef>);
-      let nextContext = this.context;
-      for (const [relationName, node] of Object.entries(normalized)) {
-        nextContext = this.relationFacet.include(nextContext, relationName, node.options);
-      }
-      const nextTree = mergeRelationIncludeTrees(this.includeTree, normalized);
-      return this.clone(nextContext, undefined, undefined, nextTree);
-    }
-
-    const relationName = relationNameOrRelations as string;
-    const normalizedNode = normalizeRelationIncludeNode(options);
-    const nextContext = this.relationFacet.include(this.context, relationName, normalizedNode.options);
-    const shouldStore = Boolean(normalizedNode.include || normalizedNode.options);
-    const nextTree = shouldStore
-      ? mergeRelationIncludeTrees(this.includeTree, { [relationName]: normalizedNode })
-      : this.includeTree;
-    return this.clone(nextContext, undefined, undefined, nextTree);
-  }
+   * @example
+   * qb.include('posts', {
+   *   columns: ['id', 'title'],
+   *   where: eq(postTable.columns.published, true)
+   * });
+   * @example
+   * qb.include({ posts: { include: { author: true } } });
+   */
+  include<K extends keyof TTable['relations'] & string>(
+    relationName: K,
+    options?: RelationIncludeNodeInput<TTable['relations'][K]>
+  ): SelectQueryBuilder<T, TTable>;
+  include(relations: RelationIncludeInput<TTable>): SelectQueryBuilder<T, TTable>;
+  include<K extends keyof TTable['relations'] & string>(
+    relationNameOrRelations: K | RelationIncludeInput<TTable>,
+    options?: RelationIncludeNodeInput<TTable['relations'][K]>
+  ): SelectQueryBuilder<T, TTable> {
+    if (typeof relationNameOrRelations === 'object' && relationNameOrRelations !== null) {
+      const normalized = normalizeRelationInclude(relationNameOrRelations as RelationIncludeInput<TableDef>);
+      let nextContext = this.context;
+      for (const [relationName, node] of Object.entries(normalized)) {
+        nextContext = this.relationFacet.include(nextContext, relationName, node.options);
+      }
+      const nextTree = mergeRelationIncludeTrees(this.includeTree, normalized);
+      return this.clone(nextContext, undefined, undefined, nextTree);
+    }
+
+    const relationName = relationNameOrRelations as string;
+    const normalizedNode = normalizeRelationIncludeNode(options);
+    const nextContext = this.relationFacet.include(this.context, relationName, normalizedNode.options);
+    const shouldStore = Boolean(normalizedNode.include || normalizedNode.options);
+    const nextTree = shouldStore
+      ? mergeRelationIncludeTrees(this.includeTree, { [relationName]: normalizedNode })
+      : this.includeTree;
+    return this.clone(nextContext, undefined, undefined, nextTree);
+  }
 
   /**
    * Includes a relation lazily in the query results
@@ -647,13 +648,13 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @example
    * qb.includePick('posts', ['id', 'title', 'createdAt']);
    */
-  includePick<
-    K extends keyof TTable['relations'] & string,
-    C extends RelationTargetColumns<TTable['relations'][K]>
-  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
-    const options = { columns: cols as readonly C[] } as unknown as RelationIncludeNodeInput<TTable['relations'][K]>;
-    return this.include(relationName, options);
-  }
+  includePick<
+    K extends keyof TTable['relations'] & string,
+    C extends RelationTargetColumns<TTable['relations'][K]>
+  >(relationName: K, cols: C[]): SelectQueryBuilder<T, TTable> {
+    const options = { columns: cols as readonly C[] } as unknown as RelationIncludeNodeInput<TTable['relations'][K]>;
+    return this.include(relationName, options);
+  }
 
   /**
    * Selects columns for the root table and relations from an array of entries
@@ -670,13 +671,13 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     let currBuilder: SelectQueryBuilder<T, TTable> = this;
 
     for (const entry of config) {
-      if (entry.type === 'root') {
-        currBuilder = currBuilder.select(...entry.columns);
-      } else {
-        const options = { columns: entry.columns } as unknown as RelationIncludeNodeInput<TTable['relations'][typeof entry.relationName]>;
-        currBuilder = currBuilder.include(entry.relationName, options);
-      }
-    }
+      if (entry.type === 'root') {
+        currBuilder = currBuilder.select(...entry.columns);
+      } else {
+        const options = { columns: entry.columns } as unknown as RelationIncludeNodeInput<TTable['relations'][typeof entry.relationName]>;
+        currBuilder = currBuilder.include(entry.relationName, options);
+      }
+    }
 
     return currBuilder;
   }
@@ -693,16 +694,16 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * Gets lazy relation include options
    * @returns Map of relation names to include options
    */
-  getLazyRelationOptions(): Map<string, RelationIncludeOptions> {
-    return new Map(this.lazyRelationOptions);
-  }
-
-  /**
-   * Gets normalized nested include information for runtime preloading.
-   */
-  getIncludeTree(): NormalizedRelationIncludeTree {
-    return cloneRelationIncludeTree(this.includeTree);
-  }
+  getLazyRelationOptions(): Map<string, RelationIncludeOptions> {
+    return new Map(this.lazyRelationOptions);
+  }
+
+  /**
+   * Gets normalized nested include information for runtime preloading.
+   */
+  getIncludeTree(): NormalizedRelationIncludeTree {
+    return cloneRelationIncludeTree(this.includeTree);
+  }
 
   /**
    * Gets the table definition for this query builder
@@ -794,19 +795,19 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     return executeCount(this.context, this.env, session);
   }
 
-  /**
-   * Executes the query and returns both the paged items and the total.
-   *
-   * @example
-   * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
-   */
-  async executePaged(
-    session: OrmSession,
-    options: { page: number; pageSize: number }
-  ): Promise<PaginatedResult<T>> {
-    const builder = this.ensureDefaultSelection();
-    return executePagedQuery(builder, session, options, sess => this.count(sess));
-  }
+  /**
+   * Executes the query and returns both the paged items and the total.
+   *
+   * @example
+   * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
+   */
+  async executePaged(
+    session: OrmSession,
+    options: { page: number; pageSize: number }
+  ): Promise<PaginatedResult<T>> {
+    const builder = this.ensureDefaultSelection();
+    return executePagedQuery(builder, session, options, sess => builder.count(sess));
+  }
 
   /**
    * Executes the query with provided execution and hydration contexts
@@ -1108,16 +1109,29 @@ 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 Schema for query result
+   * @param options - Schema generation options
+   * @returns OpenAPI 3.1 JSON Schema for query result
+   * @example
+   * const schema = qb.select('id', 'title', 'author').getSchema();
+   * console.log(JSON.stringify(schema, null, 2));
+   */
+  getSchema(options?: SchemaOptions): OpenApiSchema {
+    const plan = this.context.hydration.getPlan();
+    return extractSchema(this.env.table, plan, this.context.state.ast.columns, options);
+  }
 
   /**
    * Gets the Abstract Syntax Tree (AST) representation of the query