metal-orm 1.0.89 → 1.0.91

package/src/dto/dto-types.ts

@@ -0,0 +1,229 @@
+/**
+ * DTO (Data Transfer Object) type utilities for metal-orm.
+ * Derives API types from TableDef/Entity metadata.
+ */
+
+import type { TableDef } from '../schema/table.js';
+import type { ColumnDef } from '../schema/column-types.js';
+import type { ColumnToTs, InferRow } from '../schema/types.js';
+import type { EntityConstructor } from '../orm/entity-metadata.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Entity support: Extract row type from entity constructor
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Checks if a type is a TableDef.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IsTableDef<T> = T extends { name: string; columns: any } ? true : false;
+
+/**
+ * Extracts the row type from either a TableDef or EntityConstructor.
+ */
+type ExtractRow<T> = IsTableDef<T> extends true
+  ? InferRow<T extends TableDef<infer C> ? TableDef<C> : never>
+  : T extends EntityConstructor<infer E>
+  ? E
+  : never;
+
+/**
+ * Utility to flatten intersection types for better IDE display.
+ */
+export type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * Response DTO - excludes specified columns from the entity.
+ * Use this to hide sensitive fields like passwordHash, apiKey, etc.
+ *
+ * @example
+ * ```ts
+ * // With TableDef
+ * type UserResponse = Dto<typeof usersTable, 'passwordHash'>;
+ *
+ * // With Entity class
+ * type UserResponse = Dto<User, 'passwordHash'>;
+ *
+ * // Exclude multiple fields
+ * type UserPublic = Dto<User, 'passwordHash' | 'email'>;
+ *
+ * // Include all fields (no exclusions)
+ * type UserFull = Dto<User>;
+ * ```
+ */
+export type Dto<
+  T extends TableDef | EntityConstructor,
+  TExclude extends keyof ExtractRow<T> = never
+> = Simplify<Omit<ExtractRow<T>, TExclude>>;
+
+/**
+ * Compose a DTO with relations.
+ *
+ * @example
+ * ```ts
+ * type UserWithPosts = WithRelations<UserResponse, {
+ *   posts: PostResponse[]
+ * }>;
+ *
+ * type PostWithAuthor = WithRelations<PostResponse, {
+ *   author: Dto<User, 'passwordHash' | 'email'>
+ * }>;
+ * ```
+ */
+export type WithRelations<TBase, TRelations> = Simplify<TBase & TRelations>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Column classification helpers for TableDef (for Create/Update DTOs)
+// ─────────────────────────────────────────────────────────────────────────────
+
+type ColumnMap<T extends TableDef> = T['columns'];
+
+/**
+ * Checks if a column has a default value.
+ */
+type HasDefault<TCol extends ColumnDef> =
+  TCol['default'] extends undefined ? false : true;
+
+/**
+ * Checks if a column is auto-generated (autoIncrement or generated always/byDefault).
+ */
+type IsAutoGenerated<TCol extends ColumnDef> =
+  TCol['autoIncrement'] extends true ? true :
+  TCol['generated'] extends 'always' | 'byDefault' ? true :
+  false;
+
+/**
+ * Checks if a column is insertable (not auto-generated).
+ */
+type IsInsertable<TCol extends ColumnDef> =
+  IsAutoGenerated<TCol> extends true ? false : true;
+
+/**
+ * Checks if a column is required for insert (notNull, no default, not auto-generated).
+ */
+type IsRequiredInsert<TCol extends ColumnDef> =
+  TCol['notNull'] extends true
+    ? IsAutoGenerated<TCol> extends true ? false :
+      HasDefault<TCol> extends true ? false :
+      true
+    : false;
+
+/**
+ * Keys that are required for insert (notNull, no default, not auto-generated).
+ */
+type RequiredInsertKeys<T extends TableDef> = {
+  [K in keyof ColumnMap<T>]: ColumnMap<T>[K] extends ColumnDef
+    ? IsInsertable<ColumnMap<T>[K]> extends true
+      ? IsRequiredInsert<ColumnMap<T>[K]> extends true ? K : never
+      : never
+    : never;
+}[keyof ColumnMap<T>];
+
+/**
+ * Keys that are optional for insert (nullable, has default, or optional).
+ */
+type OptionalInsertKeys<T extends TableDef> = {
+  [K in keyof ColumnMap<T>]: ColumnMap<T>[K] extends ColumnDef
+    ? IsInsertable<ColumnMap<T>[K]> extends true
+      ? IsRequiredInsert<ColumnMap<T>[K]> extends false ? K : never
+      : never
+    : never;
+}[keyof ColumnMap<T>];
+
+/**
+ * Create DTO - includes only insertable columns with proper optionality.
+ * Auto-generated columns (autoIncrement, generated) are excluded.
+ * Columns with defaults or nullable are optional.
+ *
+ * Works with both TableDef and EntityConstructor:
+ * - For TableDef: Uses column metadata to determine required/optional fields
+ * - For EntityConstructor: All fields are optional (simpler type inference)
+ *
+ * @example
+ * ```ts
+ * // With TableDef - auto-excludes id (autoIncrement), createdAt (has default)
+ * type CreateUserDto = CreateDto<typeof usersTable>;
+ * // → { name: string; email: string; bio?: string }
+ *
+ * // With Entity class - simpler inference, all fields optional
+ * type CreateUserDto = CreateDto<User>;
+ *
+ * // Exclude additional fields (e.g., authorId comes from context)
+ * type CreatePostDto = CreateDto<typeof Post, 'authorId'>;
+ * ```
+ */
+export type CreateDto<
+  T extends TableDef | EntityConstructor,
+  TExclude extends keyof ExtractRow<T> = never
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+> = T extends TableDef<any>
+  ? Simplify<
+      { [K in Exclude<RequiredInsertKeys<T>, TExclude>]: ColumnToTs<ColumnMap<T>[K]> } &
+      { [K in Exclude<OptionalInsertKeys<T>, TExclude>]?: ColumnToTs<ColumnMap<T>[K]> }
+    >
+  : Simplify<{
+      [K in Exclude<keyof ExtractRow<T>, TExclude>]?: ExtractRow<T>[K];
+    }>;
+
+/**
+ * Update DTO - all columns are optional (partial update).
+ * Excludes specified columns (e.g., id, createdAt).
+ *
+ * @example
+ * ```ts
+ * // With TableDef
+ * type UpdateUserDto = UpdateDto<typeof User>;
+ * // → { name?: string; email?: string; bio?: string; ... }
+ *
+ * // With Entity class
+ * type UpdateUserDto = UpdateDto<User>;
+ *
+ * // Exclude fields that shouldn't be updated
+ * type UpdateUserDto = UpdateDto<typeof User, 'id' | 'createdAt'>;
+ * ```
+ */
+export type UpdateDto<
+  T extends TableDef | EntityConstructor,
+  TExclude extends keyof ExtractRow<T> = never
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+> = T extends TableDef<any>
+  ? Simplify<{
+      [K in Exclude<keyof ColumnMap<T>, TExclude>]?: ColumnToTs<ColumnMap<T>[K]>;
+    }>
+  : Simplify<{
+      [K in Exclude<keyof ExtractRow<T>, TExclude>]?: ExtractRow<T>[K];
+    }>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Enhanced Pagination DTO types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Enhanced paginated response with computed navigation metadata.
+ * Extends the basic PaginatedResult with additional convenience fields.
+ *
+ * @example
+ * ```ts
+ * type UsersPagedResponse = PagedResponse<UserResponse>;
+ *
+ * // Response:
+ * // {
+ * //   items: UserResponse[];
+ * //   totalItems: number;
+ * //   page: number;
+ * //   pageSize: number;
+ * //   totalPages: number;
+ * //   hasNextPage: boolean;
+ * //   hasPrevPage: boolean;
+ * // }
+ * ```
+ */
+export type PagedResponse<T> = {
+  items: T[];
+  totalItems: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPrevPage: boolean;
+};

package/src/dto/filter-types.ts

@@ -0,0 +1,193 @@
+/**
+ * Filter types for building type-safe query filters from JSON input.
+ * Designed for REST API query parameters.
+ */
+
+import type { TableDef } from '../schema/table.js';
+import type { ColumnDef } from '../schema/column-types.js';
+import type { EntityConstructor } from '../orm/entity-metadata.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Entity support: Extract columns from entity constructor
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Checks if a type is a TableDef.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type IsTableDef<T> = T extends { name: string; columns: any } ? true : false;
+
+/**
+ * Maps TypeScript types to SQL column types for EntityConstructor columns.
+ */
+type TsTypeToColumnType<T> =
+  T extends string ? 'VARCHAR' :
+  T extends number ? 'INT' :
+  T extends boolean ? 'BOOLEAN' :
+  T extends Date ? 'TIMESTAMP' :
+  'VARCHAR';
+
+/**
+ * Extracts the column map from either a TableDef or EntityConstructor.
+ * For EntityConstructor, infers column type from TypeScript property type.
+ */
+type ExtractColumns<T> = IsTableDef<T> extends true
+  ? T extends TableDef<infer C> ? C : never
+  : T extends EntityConstructor<infer E>
+  ? {
+      [K in keyof E]: ColumnDef<TsTypeToColumnType<E[K]>, E[K]>;
+    }
+  : never;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scalar filter types per data type
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Filter operators for string columns.
+ */
+export interface StringFilter {
+  equals?: string;
+  not?: string;
+  in?: string[];
+  notIn?: string[];
+  contains?: string;
+  startsWith?: string;
+  endsWith?: string;
+  /** Case-insensitive matching (for contains, startsWith, endsWith) */
+  mode?: 'default' | 'insensitive';
+}
+
+/**
+ * Filter operators for numeric columns (number, bigint).
+ */
+export interface NumberFilter {
+  equals?: number;
+  not?: number;
+  in?: number[];
+  notIn?: number[];
+  lt?: number;
+  lte?: number;
+  gt?: number;
+  gte?: number;
+}
+
+/**
+ * Filter operators for boolean columns.
+ */
+export interface BooleanFilter {
+  equals?: boolean;
+  not?: boolean;
+}
+
+/**
+ * Filter operators for date/datetime columns.
+ * Accepts ISO date strings.
+ */
+export interface DateFilter {
+  equals?: string;
+  not?: string;
+  in?: string[];
+  notIn?: string[];
+  lt?: string;
+  lte?: string;
+  gt?: string;
+  gte?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type mapping: ColumnDef → appropriate filter type
+// ─────────────────────────────────────────────────────────────────────────────
+
+type NormalizedType<T extends ColumnDef> = Lowercase<T['type'] & string>;
+
+/**
+ * Maps a column definition to its appropriate filter type.
+ */
+export type FieldFilter<TCol extends ColumnDef> =
+  NormalizedType<TCol> extends 'int' | 'integer' | 'bigint' | 'decimal' | 'float' | 'double'
+    ? NumberFilter
+  : NormalizedType<TCol> extends 'boolean'
+    ? BooleanFilter
+  : NormalizedType<TCol> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz'
+    ? DateFilter
+  : StringFilter; // default to string for varchar, text, uuid, etc.
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SimpleWhereInput: field-only filters (no AND/OR/NOT logic)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Full where input with all columns filterable.
+ * All conditions are implicitly AND-ed.
+ * Works with both TableDef and EntityConstructor.
+ *
+ * @example
+ * ```ts
+ * // With TableDef
+ * type UserFilter = WhereInput<typeof usersTable>;
+ *
+ * // With Entity class
+ * type UserFilter = WhereInput<User>;
+ * ```
+ */
+export type WhereInput<T extends TableDef | EntityConstructor> = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [K in keyof ExtractColumns<T>]?: ExtractColumns<T>[K] extends ColumnDef<any, any>
+    ? FieldFilter<ExtractColumns<T>[K]>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    : FieldFilter<ColumnDef<any, any>>;
+};
+
+/**
+ * Restricted where input - only specified columns are filterable.
+ * Use this to limit which fields can be filtered via API.
+ *
+ * Works with both TableDef and EntityConstructor.
+ *
+ * @example
+ * ```ts
+ * // With TableDef - only allow filtering by name and email
+ * type UserFilter = SimpleWhereInput<typeof usersTable, 'name' | 'email'>;
+ *
+ * // With Entity class
+ * type UserFilter = SimpleWhereInput<User, 'name' | 'email'>;
+ *
+ * // Request: { "name": { "contains": "john" }, "email": { "endsWith": "@gmail.com" } }
+ * ```
+ */
+export type SimpleWhereInput<
+  T extends TableDef | EntityConstructor,
+  K extends keyof ExtractColumns<T>
+> = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [P in K]?: ExtractColumns<T>[P] extends ColumnDef<any, any>
+    ? FieldFilter<ExtractColumns<T>[P]>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    : FieldFilter<ColumnDef<any, any>>;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Filter operator value types (for runtime processing)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * All possible filter operators.
+ */
+export type FilterOperator =
+  | 'equals'
+  | 'not'
+  | 'in'
+  | 'notIn'
+  | 'lt'
+  | 'lte'
+  | 'gt'
+  | 'gte'
+  | 'contains'
+  | 'startsWith'
+  | 'endsWith';
+
+/**
+ * Generic filter value that covers all operator types.
+ */
+export type FilterValue = StringFilter | NumberFilter | BooleanFilter | DateFilter;

package/src/dto/index.ts

@@ -0,0 +1,97 @@
+/**
+ * DTO (Data Transfer Object) module for metal-orm.
+ *
+ * Provides type utilities and runtime helpers for building REST APIs
+ * with automatic DTO generation from entity/table definitions.
+ *
+ * Supports both TableDef and Entity classes as type sources.
+ *
+ * @example
+ * ```ts
+ * import { Dto, WithRelations, CreateDto, UpdateDto, SimpleWhereInput, applyFilter, PagedResponse, toPagedResponse } from 'metal-orm/dto';
+ *
+ * // Using Entity classes
+ * type UserResponse = Dto<User, 'passwordHash'>;
+ * type PostResponse = Dto<Post, 'authorId'>;
+ * type UserWithPosts = WithRelations<UserResponse, { posts: PostResponse[] }>;
+ * type CreateUserDto = CreateDto<User>;
+ * type UpdateUserDto = UpdateDto<User>;
+ * type UserFilter = SimpleWhereInput<User, 'name' | 'email'>;
+ *
+ * // Enhanced pagination
+ * type UsersPagedResponse = PagedResponse<UserResponse>;
+ *
+ * // Using TableDef directly
+ * type UserResponse = Dto<typeof UserTable, 'passwordHash'>;
+ * type PostResponse = Dto<typeof PostTable, 'authorId'>;
+ * type UserWithPosts = WithRelations<UserResponse, { posts: PostResponse[] }>;
+ * type CreateUserDto = CreateDto<typeof UserTable>;
+ * type UpdateUserDto = UpdateDto<typeof UserTable>;
+ * type UserFilter = SimpleWhereInput<typeof UserTable, 'name' | 'email'>;
+ *
+ * // Apply filter in controller
+ * let query = selectFromEntity(User);
+ * query = applyFilter(query, User, where);
+ *
+ * // Apply enhanced pagination
+ * const basic = await qb.executePaged(session, { page: 2, pageSize: 20 });
+ * const response = toPagedResponse(basic);
+ * // → { items: [...], totalItems: 150, page: 2, pageSize: 20,
+ * //     totalPages: 8, hasNextPage: true, hasPrevPage: true }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// DTO type utilities
+export type {
+  Simplify,
+  Dto,
+  WithRelations,
+  CreateDto,
+  UpdateDto,
+  PagedResponse
+} from './dto-types.js';
+
+// Filter types
+export type {
+  StringFilter,
+  NumberFilter,
+  BooleanFilter,
+  DateFilter,
+  FieldFilter,
+  WhereInput,
+  SimpleWhereInput,
+  FilterOperator,
+  FilterValue
+} from './filter-types.js';
+
+// Runtime filter application
+export {
+  applyFilter,
+  buildFilterExpression
+} from './apply-filter.js';
+
+// Transformation utilities
+export {
+  toResponse,
+  toResponseBuilder,
+  withDefaults,
+  withDefaultsBuilder,
+  exclude,
+  pick,
+  mapFields
+} from './transform.js';
+
+// Pagination utilities
+export {
+  toPagedResponse,
+  toPagedResponseBuilder,
+  calculateTotalPages,
+  hasNextPage as hasNextPageMeta,
+  hasPrevPage as hasPrevPageMeta,
+  computePaginationMetadata
+} from './pagination-utils.js';
+
+// OpenAPI 3.1 Schema generation
+export * from './openapi/index.js';

package/src/dto/openapi/generators/base.ts

@@ -0,0 +1,29 @@
+import type { TableDef } from '../../../schema/table.js';
+import type { ColumnDef } from '../../../schema/column-types.js';
+import type { EntityConstructor } from '../../../orm/entity-metadata.js';
+import { getEntityMetadata } from '../../../orm/entity-metadata.js';
+
+export function isTableDef(target: TableDef | EntityConstructor): target is TableDef {
+  return 'columns' in target && 'name' in target;
+}
+
+export function getColumnMap(target: TableDef | EntityConstructor): Record<string, ColumnDef> {
+  if (isTableDef(target)) {
+    return target.columns;
+  }
+  const meta = getEntityMetadata(target);
+  if (meta && meta.columns) {
+    const columns: Record<string, ColumnDef> = {};
+    for (const [key, def] of Object.entries(meta.columns)) {
+      columns[key] = {
+        ...def as object,
+        name: key,
+        table: meta.tableName
+      } as ColumnDef;
+    }
+    return columns;
+  }
+  return {};
+}
+
+export type TargetType<T extends TableDef | EntityConstructor> = T;

package/src/dto/openapi/generators/column.ts

@@ -0,0 +1,34 @@
+import type { ColumnDef } from '../../../schema/column-types.js';
+import type { OpenApiSchema } from '../types.js';
+import { columnTypeToOpenApiType, columnTypeToOpenApiFormat } from '../type-mappings.js';
+
+export function columnToOpenApiSchema(col: ColumnDef): OpenApiSchema {
+  const schema: OpenApiSchema = {
+    type: columnTypeToOpenApiType(col),
+    format: columnTypeToOpenApiFormat(col),
+  };
+
+  if (!col.notNull) {
+    schema.nullable = true;
+  }
+
+  if (col.comment) {
+    schema.description = col.comment;
+  }
+
+  if (col.type.toUpperCase() === 'ENUM' && col.args && Array.isArray(col.args) && col.args.every(v => typeof v === 'string')) {
+    schema.enum = col.args as string[];
+  }
+
+  const args = col.args;
+  if (args && args.length > 0) {
+    if (col.type.toUpperCase() === 'VARCHAR' || col.type.toUpperCase() === 'CHAR') {
+      const length = args[0] as number;
+      if (length) {
+        schema.example = 'a'.repeat(length);
+      }
+    }
+  }
+
+  return schema;
+}

package/src/dto/openapi/generators/dto.ts

@@ -0,0 +1,94 @@
+import type { TableDef } from '../../../schema/table.js';
+import type { EntityConstructor } from '../../../orm/entity-metadata.js';
+import type { OpenApiSchema } from '../types.js';
+import { columnToOpenApiSchema } from './column.js';
+import { getColumnMap } from './base.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function dtoToOpenApiSchema<T extends TableDef | EntityConstructor, TExclude extends keyof any>(
+  target: T,
+  exclude?: TExclude[]
+): OpenApiSchema {
+  const columns = getColumnMap(target);
+  const properties: Record<string, OpenApiSchema> = {};
+  const required: string[] = [];
+
+  for (const [key, col] of Object.entries(columns)) {
+    if (exclude?.includes(key as TExclude)) {
+      continue;
+    }
+
+    properties[key] = columnToOpenApiSchema(col);
+
+    if (col.notNull || col.primary) {
+      required.push(key);
+    }
+  }
+
+  return {
+    type: 'object',
+    properties,
+    ...(required.length > 0 && { required }),
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createDtoToOpenApiSchema<T extends TableDef | EntityConstructor, TExclude extends keyof any>(
+  target: T,
+  exclude?: TExclude[]
+): OpenApiSchema {
+  const columns = getColumnMap(target);
+  const properties: Record<string, OpenApiSchema> = {};
+  const required: string[] = [];
+
+  for (const [key, col] of Object.entries(columns)) {
+    if (exclude?.includes(key as TExclude)) {
+      continue;
+    }
+
+    if (col.autoIncrement || col.generated) {
+      continue;
+    }
+
+    properties[key] = columnToOpenApiSchema(col);
+
+    if (col.notNull && !col.default) {
+      required.push(key);
+    }
+  }
+
+  return {
+    type: 'object',
+    properties,
+    ...(required.length > 0 && { required }),
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function updateDtoToOpenApiSchema<T extends TableDef | EntityConstructor, TExclude extends keyof any>(
+  target: T,
+  exclude?: TExclude[]
+): OpenApiSchema {
+  const columns = getColumnMap(target);
+  const properties: Record<string, OpenApiSchema> = {};
+
+  for (const [key, col] of Object.entries(columns)) {
+    if (exclude?.includes(key as TExclude)) {
+      continue;
+    }
+
+    if (col.autoIncrement || col.generated) {
+      continue;
+    }
+
+    properties[key] = {
+      ...columnToOpenApiSchema(col),
+      ...(!col.notNull ? { nullable: true } : {}),
+    };
+  }
+
+  return {
+    type: 'object',
+    properties,
+  };
+}