metal-orm 1.1.10 → 1.1.16

package/src/dto/dto-types.ts

@@ -1,226 +1,226 @@
-/**
- * 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, ColumnType } 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.
- */
-type IsTableDef<T> = T extends { name: string; columns: Record<string, unknown> } ? 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
-> = T extends TableDef<Record<string, ColumnDef<ColumnType, unknown>>>
-  ? 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
-> = T extends TableDef<Record<string, ColumnDef<ColumnType, unknown>>>
-  ? 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;
-};
+/**
+ * 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, ColumnType } 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.
+ */
+type IsTableDef<T> = T extends { name: string; columns: Record<string, unknown> } ? 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
+> = T extends TableDef<Record<string, ColumnDef<ColumnType, unknown>>>
+  ? 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
+> = T extends TableDef<Record<string, ColumnDef<ColumnType, unknown>>>
+  ? 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;
+};