metal-orm 1.0.89 → 1.0.91

package/src/dto/transform.ts

@@ -0,0 +1,197 @@
+/**
+ * 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'
+ * });
+ * ```
+ */
+type MappedFields<T, M extends Partial<Record<keyof T, string>>> = {
+  [K in keyof M as M[K] extends string ? M[K] : never]: K extends keyof T ? T[K] : never;
+};
+
+export function mapFields<T extends object, M extends Partial<Record<keyof T, string>>>(
+  obj: T,
+  fieldMap: M
+): Omit<T, keyof M> & MappedFields<T, M> {
+  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 as Omit<T, keyof M> & MappedFields<T, M>;
+}

package/src/index.ts

@@ -50,9 +50,8 @@ 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';
+export * from './orm/save-graph-types.js';
+export * from './decorators/index.js';
 
 // NEW: execution abstraction + helpers
 export * from './core/execution/db-executor.js';
@@ -65,3 +64,6 @@ 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/entity-context.ts

@@ -2,9 +2,9 @@ import { Dialect } from '../core/dialect/abstract.js';
 import type { DbExecutor } from '../core/execution/db-executor.js';
 import { TableDef } from '../schema/table.js';
 import { RelationDef } from '../schema/relation.js';
-import { RelationChange, RelationKey, TrackedEntity } from './runtime-types.js';
-
-export type PrimaryKey = string | number;
+import { RelationChange, RelationKey, TrackedEntity } from './runtime-types.js';
+
+export type PrimaryKey = string | number;
 
 /**
  * Interface for entity context providing entity tracking and management.
@@ -21,7 +21,7 @@ export interface EntityContext {
      * @param pk - The primary key value
      * @returns The entity or undefined
      */
-    getEntity(table: TableDef, pk: PrimaryKey): object | undefined;
+    getEntity(table: TableDef, pk: PrimaryKey): object | undefined;
 
     /**
      * Sets an entity in the context.
@@ -29,7 +29,7 @@ export interface EntityContext {
      * @param pk - The primary key value
      * @param entity - The entity to set
      */
-    setEntity(table: TableDef, pk: PrimaryKey, entity: object): void;
+    setEntity(table: TableDef, pk: PrimaryKey, entity: object): void;
 
     /**
      * Tracks a new entity.
@@ -37,7 +37,7 @@ export interface EntityContext {
      * @param entity - The new entity
      * @param pk - Optional primary key
      */
-    trackNew(table: TableDef, entity: object, pk?: PrimaryKey): void;
+    trackNew(table: TableDef, entity: object, pk?: PrimaryKey): void;
 
     /**
      * Tracks a managed entity.
@@ -45,19 +45,19 @@ export interface EntityContext {
      * @param pk - The primary key
      * @param entity - The managed entity
      */
-    trackManaged(table: TableDef, pk: PrimaryKey, entity: object): void;
+    trackManaged(table: TableDef, pk: PrimaryKey, entity: object): void;
 
     /**
      * Marks an entity as dirty.
      * @param entity - The entity to mark
      */
-    markDirty(entity: object): void;
+    markDirty(entity: object): void;
 
     /**
      * Marks an entity as removed.
      * @param entity - The entity to mark
      */
-    markRemoved(entity: object): void;
+    markRemoved(entity: object): void;
 
     /**
      * Gets all tracked entities for a table.

package/src/orm/entity.ts

@@ -7,20 +7,20 @@ import { RelationIncludeOptions } from '../query-builder/relation-types.js';
 import { populateHydrationCache } from './entity-hydration.js';
 import { getRelationWrapper, RelationEntityFactory } from './entity-relations.js';
 
-export { relationLoaderCache } from './entity-relation-cache.js';
-
-const isRelationWrapperLoaded = (value: unknown): boolean => {
-  if (!value || typeof value !== 'object') return false;
-  return Boolean((value as { loaded?: boolean }).loaded);
-};
-
-type JsonSource<TTable extends TableDef> = EntityInstance<TTable> & Record<string, unknown>;
-
-/**
- * Creates an entity proxy with lazy loading capabilities.
- * @template TTable - The table type
- * @template TLazy - The lazy relation keys
- * @param ctx - The entity context
+export { relationLoaderCache } from './entity-relation-cache.js';
+
+const isRelationWrapperLoaded = (value: unknown): boolean => {
+  if (!value || typeof value !== 'object') return false;
+  return Boolean((value as { loaded?: boolean }).loaded);
+};
+
+type JsonSource<TTable extends TableDef> = EntityInstance<TTable> & Record<string, unknown>;
+
+/**
+ * Creates an entity proxy with lazy loading capabilities.
+ * @template TTable - The table type
+ * @template TLazy - The lazy relation keys
+ * @param ctx - The entity context
  * @param table - The table definition
  * @param row - The database row
  * @param lazyRelations - Optional lazy relations
@@ -35,39 +35,39 @@ export const createEntityProxy = <
   row: Record<string, unknown>,
   lazyRelations: TLazy[] = [] as TLazy[],
   lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
-): EntityInstance<TTable> => {
-  const target: Record<string, unknown> = { ...row };
-  const meta: EntityMeta<TTable> = {
-    ctx,
-    table,
+): EntityInstance<TTable> => {
+  const target: Record<string, unknown> = { ...row };
+  const meta: EntityMeta<TTable> = {
+    ctx,
+    table,
     lazyRelations: [...lazyRelations],
     lazyRelationOptions: new Map(lazyRelationOptions),
     relationCache: new Map(),
-    relationHydration: new Map(),
-    relationWrappers: new Map()
-  };
-  const createRelationEntity: RelationEntityFactory = (relationTable, relationRow) =>
-    createEntityFromRow(meta.ctx, relationTable, relationRow);
-
-  const buildJson = (self: JsonSource<TTable>): Record<string, unknown> => {
-    const json: Record<string, unknown> = {};
-    for (const key of Object.keys(target)) {
-      json[key] = self[key];
-    }
-    for (const [relationName, wrapper] of meta.relationWrappers) {
-      if (Object.prototype.hasOwnProperty.call(json, relationName)) continue;
-      if (isRelationWrapperLoaded(wrapper)) {
-        json[relationName] = wrapper;
-      }
-    }
-    return json;
-  };
-
-  Object.defineProperty(target, ENTITY_META, {
-    value: meta,
-    enumerable: false,
-    writable: false
-  });
+    relationHydration: new Map(),
+    relationWrappers: new Map()
+  };
+  const createRelationEntity: RelationEntityFactory = (relationTable, relationRow) =>
+    createEntityFromRow(meta.ctx, relationTable, relationRow);
+
+  const buildJson = (self: JsonSource<TTable>): Record<string, unknown> => {
+    const json: Record<string, unknown> = {};
+    for (const key of Object.keys(target)) {
+      json[key] = self[key];
+    }
+    for (const [relationName, wrapper] of meta.relationWrappers) {
+      if (Object.prototype.hasOwnProperty.call(json, relationName)) continue;
+      if (isRelationWrapperLoaded(wrapper)) {
+        json[relationName] = wrapper;
+      }
+    }
+    return json;
+  };
+
+  Object.defineProperty(target, ENTITY_META, {
+    value: meta,
+    enumerable: false,
+    writable: false
+  });
 
   const handler: ProxyHandler<object> = {
     get(targetObj, prop, receiver) {
@@ -75,28 +75,28 @@ export const createEntityProxy = <
         return meta;
       }
 
-      if (prop === '$load') {
-        return async (relationName: RelationKey<TTable>) => {
-          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
-          if (wrapper && typeof wrapper.load === 'function') {
-            return wrapper.load();
-          }
-          return undefined;
-        };
-      }
-
-      if (prop === 'toJSON') {
-        if (prop in targetObj) {
-          return Reflect.get(targetObj, prop, receiver);
-        }
-        return () => buildJson(receiver as JsonSource<TTable>);
-      }
-
-      if (typeof prop === 'string' && table.relations[prop]) {
-        return getRelationWrapper(meta, prop as RelationKey<TTable>, receiver, createRelationEntity);
-      }
-
-      return Reflect.get(targetObj, prop, receiver);
+      if (prop === '$load') {
+        return async (relationName: RelationKey<TTable>) => {
+          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
+          if (wrapper && typeof wrapper.load === 'function') {
+            return wrapper.load();
+          }
+          return undefined;
+        };
+      }
+
+      if (prop === 'toJSON') {
+        if (prop in targetObj) {
+          return Reflect.get(targetObj, prop, receiver);
+        }
+        return () => buildJson(receiver as JsonSource<TTable>);
+      }
+
+      if (typeof prop === 'string' && table.relations[prop]) {
+        return getRelationWrapper(meta, prop as RelationKey<TTable>, receiver, createRelationEntity);
+      }
+
+      return Reflect.get(targetObj, prop, receiver);
     },
 
     set(targetObj, prop, value, receiver) {
@@ -104,14 +104,14 @@ export const createEntityProxy = <
       if (typeof prop === 'string' && table.columns[prop]) {
         ctx.markDirty(receiver);
       }
-      return result;
-    }
-  };
-
-  const proxy = new Proxy(target, handler) as EntityInstance<TTable>;
-  populateHydrationCache(proxy, row, meta);
-  return proxy;
-};
+      return result;
+    }
+  };
+
+  const proxy = new Proxy(target, handler) as EntityInstance<TTable>;
+  populateHydrationCache(proxy, row, meta);
+  return proxy;
+};
 
 /**
  * Creates an entity instance from a database row.