metal-orm 1.0.89 → 1.0.90

package/src/dto/transform.ts

@@ -0,0 +1,193 @@
+/**
+ * DTO transformation utilities for working with DTO instances.
+ *
+ * These helpers make it easier to convert between DTO types, apply defaults,
+ * and handle auto-generated fields without manual object construction.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transform utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Transforms a CreateDto or UpdateDto into a ResponseDto by merging with auto-generated fields.
+ *
+ * @example
+ * ```ts
+ * const newUser: UserResponse = toResponse(body, {
+ *   id: newId,
+ *   createdAt: new Date().toISOString()
+ * });
+ *
+ * // Or use the curried form for reuse
+ * const createUserResponse = toResponseBuilder<UserCreateDto, UserResponse>({
+ *   id: () => nextId++,
+ *   createdAt: () => new Date().toISOString()
+ * });
+ * const user = createUserResponse(body);
+ * ```
+ */
+export function toResponse<TInput, TOutput>(
+  input: TInput,
+  autoFields: Partial<TOutput>
+): TOutput {
+  return {
+    ...input,
+    ...autoFields
+  } as unknown as TOutput;
+}
+
+/**
+ * Creates a toResponse function with pre-configured auto-fields.
+ * Useful for reusing same transformation logic across multiple endpoints.
+ *
+ * @example
+ * ```ts
+ * const userResponseBuilder = toResponseBuilder<CreateUserDto, UserResponse>({
+ *   id: () => generateId(),
+ *   createdAt: () => new Date().toISOString(),
+ *   active: true
+ * });
+ *
+ * app.post('/users', (req, res) => {
+ *   const user = userResponseBuilder(req.body);
+ *   res.status(201).json(user);
+ * });
+ * ```
+ */
+export function toResponseBuilder<TInput, TOutput>(
+  autoFields: Partial<TOutput> | (() => Partial<TOutput>)
+): (input: TInput) => TOutput {
+  return (input: TInput) => {
+    const fields: Partial<TOutput> =
+      typeof autoFields === 'function' ? (autoFields as () => Partial<TOutput>)() : autoFields;
+    return {
+      ...input,
+      ...fields
+    } as unknown as TOutput;
+  };
+}
+
+/**
+ * Merges default values into a DTO. Returns a complete object with all defaults applied.
+ *
+ * @example
+ * ```ts
+ * const user = withDefaults(body, {
+ *   active: true,
+ *   createdAt: new Date().toISOString()
+ * });
+ * ```
+ */
+export function withDefaults<T>(dto: Partial<T>, defaults: T): T {
+  return {
+    ...defaults,
+    ...dto
+  };
+}
+
+/**
+ * Creates a withDefaults function with pre-configured defaults.
+ *
+ * @example
+ * ```ts
+ * const userWithDefaults = withDefaultsBuilder<CreateUserDto>({
+ *   active: true
+ * });
+ *
+ * app.post('/users', (req, res) => {
+ *   const userInput = userWithDefaults(req.body);
+ *   // ...
+ * });
+ * ```
+ */
+export function withDefaultsBuilder<T>(
+  defaults: T | (() => T)
+): (dto: Partial<T>) => T {
+  return (dto: Partial<T>) => {
+    const resolvedDefaults: T =
+      typeof defaults === 'function' ? (defaults as () => T)() : defaults;
+    return {
+      ...resolvedDefaults,
+      ...dto
+    };
+  };
+}
+
+/**
+ * Excludes specified fields from an object. Useful for removing sensitive fields
+ * from database results before sending to the client.
+ *
+ * @example
+ * ```ts
+ * const userFromDb = await db.select().from(users).where(...).first();
+ * const userResponse = exclude(userFromDb, 'passwordHash', 'apiKey');
+ * ```
+ */
+export function exclude<T extends object, K extends keyof T>(
+  obj: T,
+  ...keys: K[]
+): Omit<T, K> {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result as Omit<T, K>;
+}
+
+/**
+ * Picks only specified fields from an object. Useful for creating DTOs from
+ * larger database entities.
+ *
+ * @example
+ * ```ts
+ * const userFromDb = await db.select().from(users).where(...).first();
+ * const userResponse = pick(userFromDb, 'id', 'name', 'email');
+ * ```
+ */
+export function pick<T extends object, K extends keyof T>(
+  obj: T,
+  ...keys: K[]
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const key of keys) {
+    result[key] = obj[key];
+  }
+  return result;
+}
+
+/**
+ * Maps field names from one DTO to another. Useful when your DTO has different
+ * field names than your entity (e.g., camelCase vs snake_case).
+ *
+ * @example
+ * ```ts
+ * type ApiUser = { firstName: string; lastName: string };
+ * type DbUser = { first_name: string; last_name: string };
+ *
+ * const dbUser = mapFields(apiUser, {
+ *   firstName: 'first_name',
+ *   lastName: 'last_name'
+ * });
+ * ```
+ */
+export function mapFields<T extends object>(
+  obj: T,
+  fieldMap: Partial<Record<keyof T, string>>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const keys = Object.keys(fieldMap) as (keyof T)[];
+  for (const sourceKey of keys) {
+    const targetKey = fieldMap[sourceKey];
+    if (targetKey) {
+      result[targetKey] = obj[sourceKey];
+    }
+  }
+  // Copy any unmapped fields
+  for (const [key, value] of Object.entries(obj)) {
+    if (!(key in fieldMap)) {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/src/index.ts

@@ -1,67 +1,69 @@
-/**
- * MetalORM core exports.
- * Provides schema definition, query building, and ORM capabilities.
- */
-export * from './schema/table.js';
-export * from './schema/column-types.js';
-export * from './schema/relation.js';
-export * from './schema/types.js';
-export * from './query-builder/select.js';
-export * from './query-builder/select-helpers.js';
-export * from './query-builder/insert.js';
-export * from './query-builder/update.js';
-export * from './query-builder/delete.js';
-export * from './query/index.js';
-export * from './core/ast/expression.js';
-export * from './core/ast/window-functions.js';
-export * from './core/hydration/types.js';
-export * from './core/dialect/mysql/index.js';
-export * from './core/dialect/mssql/index.js';
-export * from './core/dialect/sqlite/index.js';
-export * from './core/dialect/postgres/index.js';
-export * from './core/ddl/schema-generator.js';
-export * from './core/ddl/schema-types.js';
-export * from './core/ddl/schema-diff.js';
-export * from './core/ddl/schema-introspect.js';
-export * from './core/ddl/introspect/registry.js';
-export * from './core/functions/text.js';
-export * from './core/functions/numeric.js';
-export * from './core/functions/datetime.js';
-export * from './core/functions/control-flow.js';
-export * from './core/functions/json.js';
-export * from './core/functions/array.js';
-export * from './orm/als.js';
-export * from './orm/hydration.js';
-export * from './codegen/typescript.js';
-export * from './orm/orm-session.js';
-export * from './orm/orm.js';
-export * from './orm/entity.js';
-export * from './orm/lazy-batch.js';
-export * from './orm/relations/has-many.js';
-export * from './orm/relations/belongs-to.js';
-export * from './orm/relations/many-to-many.js';
-export * from './orm/execute.js';
-export type { EntityContext } from './orm/entity-context.js';
-export type { PrimaryKey as EntityPrimaryKey } from './orm/entity-context.js';
-export * from './orm/execution-context.js';
-export * from './orm/hydration-context.js';
-export * from './orm/domain-event-bus.js';
-export * from './orm/runtime-types.js';
-export * from './orm/query-logger.js';
-export * from './orm/interceptor-pipeline.js';
-export * from './orm/jsonify.js';
+/**
+ * MetalORM core exports.
+ * Provides schema definition, query building, and ORM capabilities.
+ */
+export * from './schema/table.js';
+export * from './schema/column-types.js';
+export * from './schema/relation.js';
+export * from './schema/types.js';
+export * from './query-builder/select.js';
+export * from './query-builder/select-helpers.js';
+export * from './query-builder/insert.js';
+export * from './query-builder/update.js';
+export * from './query-builder/delete.js';
+export * from './query/index.js';
+export * from './core/ast/expression.js';
+export * from './core/ast/window-functions.js';
+export * from './core/hydration/types.js';
+export * from './core/dialect/mysql/index.js';
+export * from './core/dialect/mssql/index.js';
+export * from './core/dialect/sqlite/index.js';
+export * from './core/dialect/postgres/index.js';
+export * from './core/ddl/schema-generator.js';
+export * from './core/ddl/schema-types.js';
+export * from './core/ddl/schema-diff.js';
+export * from './core/ddl/schema-introspect.js';
+export * from './core/ddl/introspect/registry.js';
+export * from './core/functions/text.js';
+export * from './core/functions/numeric.js';
+export * from './core/functions/datetime.js';
+export * from './core/functions/control-flow.js';
+export * from './core/functions/json.js';
+export * from './core/functions/array.js';
+export * from './orm/als.js';
+export * from './orm/hydration.js';
+export * from './codegen/typescript.js';
+export * from './orm/orm-session.js';
+export * from './orm/orm.js';
+export * from './orm/entity.js';
+export * from './orm/lazy-batch.js';
+export * from './orm/relations/has-many.js';
+export * from './orm/relations/belongs-to.js';
+export * from './orm/relations/many-to-many.js';
+export * from './orm/execute.js';
+export type { EntityContext } from './orm/entity-context.js';
+export type { PrimaryKey as EntityPrimaryKey } from './orm/entity-context.js';
+export * from './orm/execution-context.js';
+export * from './orm/hydration-context.js';
+export * from './orm/domain-event-bus.js';
+export * from './orm/runtime-types.js';
+export * from './orm/query-logger.js';
+export * from './orm/interceptor-pipeline.js';
+export * from './orm/jsonify.js';
 export * from './orm/save-graph-types.js';
 export * from './decorators/index.js';
-export * from './openapi/index.js';
-
-// NEW: execution abstraction + helpers
-export * from './core/execution/db-executor.js';
-export * from './core/execution/pooling/pool-types.js';
-export * from './core/execution/pooling/pool.js';
-export * from './core/execution/executors/postgres-executor.js';
-export * from './core/execution/executors/mysql-executor.js';
-export * from './core/execution/executors/sqlite-executor.js';
-export * from './core/execution/executors/mssql-executor.js';
-
-// NEW: first-class pooling integration
-export * from './orm/pooled-executor-factory.js';
+
+// NEW: execution abstraction + helpers
+export * from './core/execution/db-executor.js';
+export * from './core/execution/pooling/pool-types.js';
+export * from './core/execution/pooling/pool.js';
+export * from './core/execution/executors/postgres-executor.js';
+export * from './core/execution/executors/mysql-executor.js';
+export * from './core/execution/executors/sqlite-executor.js';
+export * from './core/execution/executors/mssql-executor.js';
+
+// NEW: first-class pooling integration
+export * from './orm/pooled-executor-factory.js';
+
+// DTO module for REST API integration
+export * from './dto/index.js';

package/src/orm/unit-of-work.ts

@@ -198,13 +198,12 @@ export class UnitOfWork {
 
     const payload = this.extractColumns(tracked.table, tracked.entity as Record<string, unknown>);
     let builder = new InsertQueryBuilder(tracked.table).values(payload as Record<string, ValueOperandInput>);
-    if (this.dialect.supportsReturning()) {
-      builder = builder.returning(...this.getReturningColumns(tracked.table));
-    }
-    const compiled = builder.compile(this.dialect);
-    const results = await this.executeCompiled(compiled);
-    this.applyReturningResults(tracked, results);
-    this.applyInsertId(tracked, results);
+    if (this.dialect.supportsReturning()) {
+      builder = builder.returning(...this.getReturningColumns(tracked.table));
+    }
+    const compiled = builder.compile(this.dialect);
+    const results = await this.executeCompiled(compiled);
+    this.applyReturningResults(tracked, results);
 
     tracked.status = EntityStatus.Managed;
     tracked.original = this.createSnapshot(tracked.table, tracked.entity as Record<string, unknown>);
@@ -345,29 +344,18 @@ export class UnitOfWork {
    * @param tracked - The tracked entity
    * @param results - Query results
    */
-  private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
-    if (!this.dialect.supportsReturning()) return;
-    const first = results[0];
-    if (!first || first.values.length === 0) return;
+  private applyReturningResults(tracked: TrackedEntity, results: QueryResult[]): void {
+    if (!this.dialect.supportsReturning()) return;
+    const first = results[0];
+    if (!first || first.values.length === 0) return;
 
     const row = first.values[0];
     for (let i = 0; i < first.columns.length; i++) {
       const columnName = this.normalizeColumnName(first.columns[i]);
       if (!(columnName in tracked.table.columns)) continue;
-      (tracked.entity as Record<string, unknown>)[columnName] = row[i];
-    }
-  }
-
-  private applyInsertId(tracked: TrackedEntity, results: QueryResult[]): void {
-    if (this.dialect.supportsReturning()) return;
-    if (tracked.pk != null) return;
-    const pkName = findPrimaryKey(tracked.table);
-    const pkColumn = tracked.table.columns[pkName];
-    if (!pkColumn?.autoIncrement) return;
-    const insertId = results.find(result => typeof result.insertId === 'number')?.insertId;
-    if (insertId == null) return;
-    (tracked.entity as Record<string, unknown>)[pkName] = insertId;
-  }
+      (tracked.entity as Record<string, unknown>)[columnName] = row[i];
+    }
+  }
 
   /**
    * Normalizes a column name by removing quotes and table prefixes.