typemold 1.0.0

package/dist/cjs/utils.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - Utility Functions
+ * Helper functions for the mapping engine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestedValue = getNestedValue;
+exports.isPlainObject = isPlainObject;
+exports.isClassInstance = isClassInstance;
+exports.pickKeys = pickKeys;
+exports.omitKeys = omitKeys;
+exports.getAllPropertyKeys = getAllPropertyKeys;
+exports.deepClone = deepClone;
+/**
+ * Gets a nested value from an object using dot notation path.
+ * Optimized for performance with caching of path segments.
+ *
+ * @example
+ * getNestedValue({ profile: { avatar: 'url' } }, 'profile.avatar')
+ * // Returns: 'url'
+ */
+const pathCache = new Map();
+// Dangerous property names for prototype pollution
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function getNestedValue(obj, path) {
+    if (obj == null)
+        return undefined;
+    // Simple path - check for prototype pollution
+    if (!path.includes(".")) {
+        if (BLOCKED_KEYS.has(path))
+            return undefined;
+        return obj[path];
+    }
+    let segments = pathCache.get(path);
+    if (!segments) {
+        segments = path.split(".");
+        pathCache.set(path, segments);
+    }
+    let current = obj;
+    for (let i = 0; i < segments.length; i++) {
+        // Block prototype pollution attempts
+        if (BLOCKED_KEYS.has(segments[i]))
+            return undefined;
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[segments[i]];
+    }
+    return current;
+}
+/**
+ * Checks if a value is a plain object (not an array, Date, etc.)
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Checks if a value is a class instance (not a plain object)
+ */
+function isClassInstance(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto !== Object.prototype && proto !== null;
+}
+/**
+ * Creates a shallow clone of an object with only specified keys
+ */
+function pickKeys(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (key in obj) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+/**
+ * Creates a shallow clone of an object without specified keys
+ */
+function omitKeys(obj, keys) {
+    const keySet = new Set(keys);
+    const result = {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key) && !keySet.has(key)) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+/**
+ * Gets all property keys including inherited ones
+ */
+function getAllPropertyKeys(target) {
+    const keys = new Set();
+    let current = target;
+    while (current && current !== Object.prototype) {
+        for (const key of Object.getOwnPropertyNames(current)) {
+            if (key !== "constructor") {
+                keys.add(key);
+            }
+        }
+        current = Object.getPrototypeOf(current);
+    }
+    return Array.from(keys);
+}
+/**
+ * Deep clones an object (for handling circular references)
+ */
+function deepClone(obj, visited = new WeakMap()) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    const objAsObject = obj;
+    if (visited.has(objAsObject))
+        return visited.get(objAsObject);
+    if (Array.isArray(obj)) {
+        const arrClone = [];
+        visited.set(objAsObject, arrClone);
+        for (let i = 0; i < obj.length; i++) {
+            arrClone[i] = deepClone(obj[i], visited);
+        }
+        return arrClone;
+    }
+    if (obj instanceof Date)
+        return new Date(obj.getTime());
+    if (obj instanceof RegExp)
+        return new RegExp(obj.source, obj.flags);
+    const clone = Object.create(Object.getPrototypeOf(obj));
+    visited.set(objAsObject, clone);
+    for (const key of Object.keys(obj)) {
+        clone[key] = deepClone(obj[key], visited);
+    }
+    return clone;
+}

package/dist/esm/decorators.js

@@ -0,0 +1,274 @@
+/**
+ * @sevirial/nest-mapper - Decorators
+ * Property decorators for defining mapping configurations
+ */
+import "reflect-metadata";
+import { METADATA_KEYS, } from "./types";
+/**
+ * Maps a property from a source path or using a transform function.
+ *
+ * @example
+ * // Direct property mapping
+ * class UserDto {
+ *   @MapFrom('firstName')
+ *   name: string;
+ * }
+ *
+ * @example
+ * // Nested path mapping
+ * class UserDto {
+ *   @MapFrom('profile.avatar')
+ *   avatarUrl: string;
+ * }
+ *
+ * @example
+ * // Transform function with typed source
+ * class UserDto {
+ *   @MapFrom<User>((src) => src.age >= 18)  // ← IntelliSense for src!
+ *   isAdult: boolean;
+ * }
+ */
+export function MapFrom(sourcePathOrTransform) {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, target.constructor) || new Map();
+        const existingConfig = existingMappings.get(key) || createDefaultConfig(key);
+        if (typeof sourcePathOrTransform === "function") {
+            existingConfig.source = sourcePathOrTransform;
+            existingConfig.isTransform = true;
+        }
+        else {
+            existingConfig.source = sourcePathOrTransform;
+            existingConfig.isTransform = false;
+        }
+        existingMappings.set(key, existingConfig);
+        Reflect.defineMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+    };
+}
+/**
+ * Creates a type-safe mapping configuration with full IntelliSense support.
+ * Use this builder pattern when you need autocomplete for source paths.
+ *
+ * @example
+ * interface User {
+ *   username: string;
+ *   profile: { avatar: string; bio: string };
+ * }
+ *
+ * // Option 1: Define mappings with full autocomplete
+ * const toUserDto = createMapping<User, UserDto>({
+ *   avatar: 'profile.avatar',        // ✨ Autocomplete for paths!
+ *   bio: src => src.profile.bio,     // ✨ Autocomplete for transforms!
+ * });
+ *
+ * // Usage
+ * const dto = toUserDto(userEntity);
+ *
+ * @example
+ * // Option 2: Use with Mapper
+ * const dto = Mapper.mapWith(user, toUserDto);
+ */
+export function createMapping(mappings) {
+    return (source) => {
+        const result = {};
+        for (const [targetKey, sourcePathOrFn] of Object.entries(mappings)) {
+            if (typeof sourcePathOrFn === "function") {
+                result[targetKey] = sourcePathOrFn(source);
+            }
+            else {
+                result[targetKey] = getNestedValueTyped(source, sourcePathOrFn);
+            }
+        }
+        return result;
+    };
+}
+/**
+ * Helper to get nested value with type safety
+ */
+function getNestedValueTyped(obj, path) {
+    if (obj == null)
+        return undefined;
+    const segments = path.split(".");
+    let current = obj;
+    for (const segment of segments) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Automatically maps a property with the same name from source.
+ *
+ * @example
+ * class UserDto {
+ *   @AutoMap()
+ *   username: string;  // Maps from source.username
+ * }
+ */
+export function AutoMap() {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, target.constructor) || new Map();
+        const existingConfig = existingMappings.get(key) || createDefaultConfig(key);
+        existingConfig.source = key; // Same name mapping
+        existingConfig.isTransform = false;
+        existingMappings.set(key, existingConfig);
+        Reflect.defineMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+        Reflect.defineMetadata(METADATA_KEYS.AUTO_MAP, true, target.constructor, key);
+    };
+}
+/**
+ * Assigns a property to one or more field groups for runtime projection.
+ *
+ * @example
+ * // Basic usage with strings
+ * class UserDto {
+ *   @FieldGroup('minimal', 'public')
+ *   @AutoMap()
+ *   username: string;
+ * }
+ *
+ * @example
+ * // Type-safe usage with const object (recommended for autocomplete!)
+ * const Groups = createFieldGroups('minimal', 'public', 'full');
+ *
+ * class UserDto {
+ *   @FieldGroup(Groups.minimal, Groups.public)  // ✨ Autocomplete!
+ *   @AutoMap()
+ *   username: string;
+ * }
+ */
+export function FieldGroup(...groups) {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, target.constructor) || new Map();
+        const existingConfig = existingMappings.get(key) || createDefaultConfig(key);
+        existingConfig.groups = [...new Set([...existingConfig.groups, ...groups])];
+        existingMappings.set(key, existingConfig);
+        Reflect.defineMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+        // Also store in field groups map for quick lookup
+        const fieldGroups = Reflect.getMetadata(METADATA_KEYS.FIELD_GROUPS, target.constructor) || new Map();
+        for (const group of groups) {
+            const groupSet = fieldGroups.get(group) || new Set();
+            groupSet.add(key);
+            fieldGroups.set(group, groupSet);
+        }
+        Reflect.defineMetadata(METADATA_KEYS.FIELD_GROUPS, fieldGroups, target.constructor);
+    };
+}
+/**
+ * Creates a type-safe field groups object with autocomplete support.
+ * Use this to define your groups once and get IntelliSense everywhere!
+ *
+ * @example
+ * // Define groups once
+ * export const UserGroups = createFieldGroups('minimal', 'public', 'full');
+ *
+ * class UserDto {
+ *   @FieldGroup(UserGroups.minimal, UserGroups.public)  // ✨ Autocomplete!
+ *   @AutoMap()
+ *   username: string;
+ *
+ *   @FieldGroup(UserGroups.full)
+ *   @AutoMap()
+ *   email: string;
+ * }
+ *
+ * // Usage with type-safety
+ * Mapper.map(user, UserDto, { group: UserGroups.minimal });  // ✨ Autocomplete!
+ */
+export function createFieldGroups(...groups) {
+    const result = {};
+    for (const group of groups) {
+        result[group] = group;
+    }
+    return Object.freeze(result);
+}
+/**
+ * Built-in field groups with autocomplete - use these directly!
+ * No need to define your own groups for common use cases.
+ *
+ * @example
+ * class UserDto {
+ *   @FieldGroup(Groups.MINIMAL, Groups.PUBLIC)  // ✨ Autocomplete!
+ *   @AutoMap()
+ *   username: string;
+ *
+ *   @FieldGroup(Groups.DETAILED)
+ *   @AutoMap()
+ *   email: string;
+ * }
+ *
+ * // Usage
+ * Mapper.map(user, UserDto, { group: Groups.MINIMAL });  // ✨ Autocomplete!
+ */
+export const Groups = Object.freeze({
+    /** Minimal fields - just the essentials (e.g., id, name) */
+    MINIMAL: "minimal",
+    /** Summary fields - brief overview */
+    SUMMARY: "summary",
+    /** Public fields - safe to expose publicly */
+    PUBLIC: "public",
+    /** Private fields - internal use only */
+    PRIVATE: "private",
+    /** Detailed fields - comprehensive info */
+    DETAILED: "detailed",
+    /** Full fields - everything */
+    FULL: "full",
+    /** List view fields - for table/list displays */
+    LIST: "list",
+    /** Detail view fields - for detail pages */
+    DETAIL: "detail",
+    /** Admin fields - administrative data */
+    ADMIN: "admin",
+    /** API response fields */
+    API: "api",
+});
+/**
+ * Ignores a property during mapping.
+ *
+ * @example
+ * class UserDto {
+ *   @Ignore()
+ *   internalId: string;  // Will not be mapped
+ * }
+ */
+export function Ignore() {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, target.constructor) || new Map();
+        const existingConfig = existingMappings.get(key) || createDefaultConfig(key);
+        existingConfig.ignore = true;
+        existingMappings.set(key, existingConfig);
+        Reflect.defineMetadata(METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+        Reflect.defineMetadata(METADATA_KEYS.IGNORE, true, target.constructor, key);
+    };
+}
+/**
+ * Specifies the type for nested object mapping.
+ *
+ * @example
+ * class UserDto {
+ *   @NestedType(() => AddressDto)
+ *   @MapFrom('address')
+ *   address: AddressDto;
+ * }
+ */
+export function NestedType(typeFactory) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.NESTED_TYPE, typeFactory, target.constructor, String(propertyKey));
+    };
+}
+/**
+ * Creates a default property mapping config
+ */
+function createDefaultConfig(targetKey) {
+    return {
+        targetKey,
+        source: targetKey,
+        isTransform: false,
+        groups: [],
+        ignore: false,
+    };
+}

package/dist/esm/index.js

@@ -0,0 +1,51 @@
+/**
+ * typemold
+ * A lightweight, high-performance object mapper for TypeScript and Node.js
+ *
+ * @author Chetan Joshi
+ * @license MIT
+ *
+ * @example
+ * // Basic mapping
+ * import { Mapper, MapFrom, AutoMap } from 'typemold';
+ *
+ * class UserDto {
+ *   @AutoMap()
+ *   username: string;
+ *
+ *   @MapFrom('profile.avatar')
+ *   avatar: string;
+ *
+ *   @MapFrom((src) => src.age >= 18)
+ *   isAdult: boolean;
+ * }
+ *
+ * const userDto = Mapper.map(userEntity, UserDto);
+ *
+ * @example
+ * // Runtime field projection
+ * const minimal = Mapper.map(user, UserDto, { pick: ['username', 'avatar'] });
+ * const safe = Mapper.map(user, UserDto, { omit: ['email', 'password'] });
+ * const public = Mapper.map(user, UserDto, { group: 'public' });
+ *
+ * @example
+ * // NestJS integration (optional)
+ * import { MapperModule, MapperService } from 'typemold';
+ *
+ * @Module({
+ *   imports: [MapperModule.forRoot()],
+ * })
+ * export class AppModule {}
+ */
+// Core Mapper
+export { Mapper } from "./mapper";
+// Decorators
+export { MapFrom, createMapping, AutoMap, FieldGroup, createFieldGroups, Groups, Ignore, NestedType, } from "./decorators";
+// Types
+export { METADATA_KEYS, } from "./types";
+// Registry (for advanced usage)
+export { MappingRegistry, MapperFactory } from "./registry";
+// Utilities
+export { getNestedValue, pickKeys, omitKeys, isPlainObject, isClassInstance, } from "./utils";
+// NestJS Integration
+export { MapperModule, MapperService, MAPPER_OPTIONS, } from "./nestjs";

package/dist/esm/mapper.js

@@ -0,0 +1,149 @@
+/**
+ * @sevirial/nest-mapper - Core Mapper
+ * Main mapper class with static methods for easy usage
+ */
+import "reflect-metadata";
+import { MapperFactory, MappingRegistry } from "./registry";
+/**
+ * Main Mapper class - provides static methods for object mapping
+ *
+ * @example
+ * // Basic usage
+ * const userDto = Mapper.map(userEntity, UserDto);
+ *
+ * @example
+ * // With field projection
+ * const minimalUser = Mapper.map(userEntity, UserDto, { pick: ['username', 'avatar'] });
+ *
+ * @example
+ * // With field groups
+ * const publicUser = Mapper.map(userEntity, UserDto, { group: 'public' });
+ *
+ * @example
+ * // Array mapping
+ * const userDtos = Mapper.mapArray(users, UserDto);
+ */
+export class Mapper {
+    /**
+     * Maps a source object to a target DTO class
+     *
+     * @param source - Source object to map from
+     * @param targetType - Target DTO class constructor
+     * @param options - Optional mapping options for field projection
+     * @returns Mapped target object
+     */
+    static map(source, targetType, options) {
+        if (source == null) {
+            return null;
+        }
+        const mapper = MapperFactory.createMapper(targetType, options);
+        const context = {
+            ...this.globalContext,
+            extras: options?.extras,
+            depth: 0,
+            visited: new WeakMap(),
+        };
+        return mapper(source, context);
+    }
+    /**
+     * Maps an array of source objects to target DTOs
+     *
+     * @param sources - Array of source objects
+     * @param targetType - Target DTO class constructor
+     * @param options - Optional mapping options for field projection
+     * @returns Array of mapped target objects
+     */
+    static mapArray(sources, targetType, options) {
+        if (!sources || !Array.isArray(sources)) {
+            return [];
+        }
+        const mapper = MapperFactory.createMapper(targetType, options);
+        const context = {
+            ...this.globalContext,
+            extras: options?.extras,
+            depth: 0,
+            visited: new WeakMap(),
+        };
+        const result = new Array(sources.length);
+        for (let i = 0; i < sources.length; i++) {
+            result[i] =
+                sources[i] != null
+                    ? mapper(sources[i], context)
+                    : null;
+        }
+        return result;
+    }
+    /**
+     * Maps source to target and returns only specified fields (shorthand)
+     *
+     * @example
+     * const result = Mapper.pick(user, UserDto, ['username', 'avatar']);
+     */
+    static pick(source, targetType, fields) {
+        return this.map(source, targetType, {
+            pick: fields,
+        });
+    }
+    /**
+     * Maps source to target excluding specified fields (shorthand)
+     *
+     * @example
+     * const result = Mapper.omit(user, UserDto, ['password', 'email']);
+     */
+    static omit(source, targetType, fields) {
+        return this.map(source, targetType, {
+            omit: fields,
+        });
+    }
+    /**
+     * Maps source using a predefined field group (shorthand)
+     *
+     * @example
+     * const result = Mapper.group(user, UserDto, 'minimal');
+     */
+    static group(source, targetType, groupName) {
+        return this.map(source, targetType, { group: groupName });
+    }
+    /**
+     * Creates a reusable mapper function for better performance in loops
+     *
+     * @example
+     * const mapToUserDto = Mapper.createMapper(UserDto);
+     * const users = entities.map(mapToUserDto);
+     */
+    static createMapper(targetType, options) {
+        const compiledMapper = MapperFactory.createMapper(targetType, options);
+        const context = {
+            ...this.globalContext,
+            extras: options?.extras,
+        };
+        return (source) => compiledMapper(source, context);
+    }
+    /**
+     * Registers a type converter for automatic type transformations
+     */
+    static registerConverter(converter) {
+        this.typeConverters.push(converter);
+    }
+    /**
+     * Sets global context that will be available to all transform functions
+     */
+    static setGlobalContext(context) {
+        this.globalContext = { ...this.globalContext, ...context };
+    }
+    /**
+     * Clears all cached mappers (useful for testing or hot-reload scenarios)
+     */
+    static clearCache() {
+        MappingRegistry.clearCache();
+    }
+    /**
+     * Gets the compiled mapper for inspection (useful for debugging)
+     */
+    static getCompiledMapper(targetType, options) {
+        const optionsKey = MappingRegistry.getOptionsKey(options);
+        return MappingRegistry.getCompiledMapper(targetType, optionsKey);
+    }
+}
+Mapper.typeConverters = [];
+Mapper.globalContext = {};

package/dist/esm/nestjs/index.js

@@ -0,0 +1,6 @@
+/**
+ * @sevirial/nest-mapper - NestJS Integration
+ * Re-exports for NestJS-specific functionality
+ */
+export { MapperModule, } from "./mapper.module";
+export { MapperService, MAPPER_OPTIONS, } from "./mapper.service";