typemold 1.0.0

package/dist/cjs/mapper.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - Core Mapper
+ * Main mapper class with static methods for easy usage
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mapper = void 0;
+require("reflect-metadata");
+const registry_1 = require("./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);
+ */
+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 = registry_1.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 = registry_1.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 = registry_1.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() {
+        registry_1.MappingRegistry.clearCache();
+    }
+    /**
+     * Gets the compiled mapper for inspection (useful for debugging)
+     */
+    static getCompiledMapper(targetType, options) {
+        const optionsKey = registry_1.MappingRegistry.getOptionsKey(options);
+        return registry_1.MappingRegistry.getCompiledMapper(targetType, optionsKey);
+    }
+}
+exports.Mapper = Mapper;
+Mapper.typeConverters = [];
+Mapper.globalContext = {};

package/dist/cjs/nestjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - NestJS Integration
+ * Re-exports for NestJS-specific functionality
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAPPER_OPTIONS = exports.MapperService = exports.MapperModule = void 0;
+var mapper_module_1 = require("./mapper.module");
+Object.defineProperty(exports, "MapperModule", { enumerable: true, get: function () { return mapper_module_1.MapperModule; } });
+var mapper_service_1 = require("./mapper.service");
+Object.defineProperty(exports, "MapperService", { enumerable: true, get: function () { return mapper_service_1.MapperService; } });
+Object.defineProperty(exports, "MAPPER_OPTIONS", { enumerable: true, get: function () { return mapper_service_1.MAPPER_OPTIONS; } });

package/dist/cjs/nestjs/mapper.module.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - NestJS MapperModule
+ * Dynamic module for NestJS integration
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var MapperModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapperModule = void 0;
+const common_1 = require("@nestjs/common");
+const mapper_service_1 = require("./mapper.service");
+/**
+ * NestJS Module for @sevirial/nest-mapper
+ *
+ * @example
+ * // Basic usage (global by default)
+ * @Module({
+ *   imports: [MapperModule.forRoot()],
+ * })
+ * export class AppModule {}
+ *
+ * @example
+ * // With options
+ * @Module({
+ *   imports: [
+ *     MapperModule.forRoot({
+ *       enableValidation: true,
+ *       converters: [myDateConverter],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * @example
+ * // Async configuration
+ * @Module({
+ *   imports: [
+ *     MapperModule.forRootAsync({
+ *       imports: [ConfigModule],
+ *       useFactory: (config: ConfigService) => ({
+ *         enableValidation: config.get('ENABLE_VALIDATION'),
+ *       }),
+ *       inject: [ConfigService],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ */
+let MapperModule = MapperModule_1 = class MapperModule {
+    /**
+     * Configure the mapper module with static options
+     */
+    static forRoot(options) {
+        const isGlobal = options?.isGlobal ?? true;
+        const optionsProvider = {
+            provide: mapper_service_1.MAPPER_OPTIONS,
+            useValue: options || {},
+        };
+        return {
+            module: MapperModule_1,
+            global: isGlobal,
+            providers: [optionsProvider, mapper_service_1.MapperService],
+            exports: [mapper_service_1.MapperService],
+        };
+    }
+    /**
+     * Configure the mapper module with async options (factory pattern)
+     */
+    static forRootAsync(options) {
+        const isGlobal = options.isGlobal ?? true;
+        const asyncOptionsProvider = {
+            provide: mapper_service_1.MAPPER_OPTIONS,
+            useFactory: options.useFactory,
+            inject: options.inject || [],
+        };
+        return {
+            module: MapperModule_1,
+            global: isGlobal,
+            imports: options.imports || [],
+            providers: [asyncOptionsProvider, mapper_service_1.MapperService],
+            exports: [mapper_service_1.MapperService],
+        };
+    }
+    /**
+     * For feature modules that need the mapper (when not using isGlobal)
+     */
+    static forFeature() {
+        return {
+            module: MapperModule_1,
+            providers: [mapper_service_1.MapperService],
+            exports: [mapper_service_1.MapperService],
+        };
+    }
+};
+exports.MapperModule = MapperModule;
+exports.MapperModule = MapperModule = MapperModule_1 = __decorate([
+    (0, common_1.Module)({})
+], MapperModule);

package/dist/cjs/nestjs/mapper.service.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - NestJS MapperService
+ * Injectable service for NestJS dependency injection
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapperService = exports.MAPPER_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const mapper_1 = require("../mapper");
+/**
+ * Injection token for MapperModule options
+ */
+exports.MAPPER_OPTIONS = Symbol("MAPPER_OPTIONS");
+/**
+ * Injectable mapper service for NestJS
+ *
+ * @example
+ * @Injectable()
+ * export class UserService {
+ *   constructor(private readonly mapper: MapperService) {}
+ *
+ *   async getUser(id: string): Promise<UserDto> {
+ *     const user = await this.userRepo.findOne(id);
+ *     return this.mapper.map(user, UserDto);
+ *   }
+ * }
+ */
+let MapperService = class MapperService {
+    constructor(options) {
+        this.validator = null;
+        this.options = options || {};
+        // Register custom converters if provided
+        if (this.options.converters) {
+            for (const converter of this.options.converters) {
+                mapper_1.Mapper.registerConverter(converter);
+            }
+        }
+        // Set global context if extras provided
+        if (this.options.globalExtras) {
+            mapper_1.Mapper.setGlobalContext({ extras: this.options.globalExtras });
+        }
+        // Try to load class-validator if validation is enabled
+        if (this.options.enableValidation) {
+            this.initializeValidator();
+        }
+    }
+    /**
+     * Lazily loads class-validator for hybrid integration
+     */
+    async initializeValidator() {
+        try {
+            this.validator = await Promise.resolve().then(() => __importStar(require("class-validator")));
+        }
+        catch {
+            console.warn("[@sevirial/nest-mapper] class-validator not found. Validation will be skipped.");
+        }
+    }
+    /**
+     * Maps a source object to a target DTO
+     */
+    map(source, targetType, options) {
+        return mapper_1.Mapper.map(source, targetType, options);
+    }
+    /**
+     * Maps an array of source objects to target DTOs
+     */
+    mapArray(sources, targetType, options) {
+        return mapper_1.Mapper.mapArray(sources, targetType, options);
+    }
+    /**
+     * Maps and validates the result using class-validator (if enabled)
+     *
+     * @throws ValidationError[] if validation fails
+     */
+    async mapAndValidate(source, targetType, options) {
+        const result = this.map(source, targetType, options);
+        if (this.validator && this.options.enableValidation) {
+            const errors = await this.validator.validate(result);
+            if (errors.length > 0) {
+                throw errors;
+            }
+        }
+        return result;
+    }
+    /**
+     * Pick specific fields (shorthand)
+     */
+    pick(source, targetType, fields) {
+        return mapper_1.Mapper.pick(source, targetType, fields);
+    }
+    /**
+     * Omit specific fields (shorthand)
+     */
+    omit(source, targetType, fields) {
+        return mapper_1.Mapper.omit(source, targetType, fields);
+    }
+    /**
+     * Use a field group (shorthand)
+     */
+    group(source, targetType, groupName) {
+        return mapper_1.Mapper.group(source, targetType, groupName);
+    }
+    /**
+     * Creates a reusable mapper function
+     */
+    createMapper(targetType, options) {
+        return mapper_1.Mapper.createMapper(targetType, options);
+    }
+};
+exports.MapperService = MapperService;
+exports.MapperService = MapperService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(exports.MAPPER_OPTIONS)),
+    __metadata("design:paramtypes", [Object])
+], MapperService);

package/dist/cjs/registry.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - Mapping Registry
+ * Singleton registry for storing and caching mapping configurations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapperFactory = exports.MappingRegistry = void 0;
+require("reflect-metadata");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+/**
+ * Global mapping registry - singleton pattern for performance
+ */
+class MappingRegistryClass {
+    constructor() {
+        this.registry = new Map();
+        this.compiledMappers = new WeakMap();
+    }
+    /**
+     * Gets or creates a registry entry for a target DTO class
+     */
+    getEntry(targetType) {
+        let entry = this.registry.get(targetType);
+        if (!entry) {
+            entry = this.createEntryFromMetadata(targetType);
+            this.registry.set(targetType, entry);
+        }
+        return entry;
+    }
+    /**
+     * Creates a mapping entry by reading decorator metadata
+     */
+    createEntryFromMetadata(targetType) {
+        const propertyMappings = Reflect.getMetadata(types_1.METADATA_KEYS.PROPERTY_MAPPINGS, targetType) ||
+            new Map();
+        const fieldGroups = Reflect.getMetadata(types_1.METADATA_KEYS.FIELD_GROUPS, targetType) || new Map();
+        return {
+            targetType,
+            propertyConfigs: propertyMappings,
+            fieldGroups,
+        };
+    }
+    /**
+     * Gets a compiled mapper for the given target type and options signature
+     */
+    getCompiledMapper(targetType, optionsKey = "default") {
+        const typeMappers = this.compiledMappers.get(targetType);
+        return typeMappers?.get(optionsKey);
+    }
+    /**
+     * Stores a compiled mapper for reuse
+     */
+    setCompiledMapper(targetType, optionsKey, mapper) {
+        let typeMappers = this.compiledMappers.get(targetType);
+        if (!typeMappers) {
+            typeMappers = new Map();
+            this.compiledMappers.set(targetType, typeMappers);
+        }
+        typeMappers.set(optionsKey, mapper);
+    }
+    /**
+     * Clears all cached mappers (useful for testing)
+     */
+    clearCache() {
+        this.registry.clear();
+    }
+    /**
+     * Generates a cache key for mapping options
+     */
+    getOptionsKey(options) {
+        if (!options)
+            return "default";
+        if (options.pick)
+            return `pick:${options.pick.sort().join(",")}`;
+        if (options.omit)
+            return `omit:${options.omit.sort().join(",")}`;
+        if (options.group)
+            return `group:${options.group}`;
+        return "default";
+    }
+}
+/**
+ * Singleton instance
+ */
+exports.MappingRegistry = new MappingRegistryClass();
+/**
+ * Mapper Factory - Creates optimized mapping functions
+ */
+class MapperFactory {
+    /**
+     * Creates a compiled mapper for the given target type with optional field projection
+     */
+    static createMapper(targetType, options) {
+        const entry = exports.MappingRegistry.getEntry(targetType);
+        const optionsKey = exports.MappingRegistry.getOptionsKey(options);
+        // Check cache first
+        let compiledMapper = exports.MappingRegistry.getCompiledMapper(targetType, optionsKey);
+        if (compiledMapper) {
+            return compiledMapper;
+        }
+        // Determine which properties to include
+        const propertiesToMap = this.getPropertiesToMap(entry, options);
+        // Build the compiled mapper
+        compiledMapper = this.buildMapper(targetType, entry, propertiesToMap);
+        // Cache for reuse
+        exports.MappingRegistry.setCompiledMapper(targetType, optionsKey, compiledMapper);
+        return compiledMapper;
+    }
+    /**
+     * Determines which properties to map based on options
+     */
+    static getPropertiesToMap(entry, options) {
+        const allConfigs = Array.from(entry.propertyConfigs.values()).filter((config) => !config.ignore);
+        if (!options) {
+            return allConfigs;
+        }
+        // Field group selection
+        if (options.group) {
+            const groupFields = entry.fieldGroups.get(options.group);
+            if (groupFields) {
+                return allConfigs.filter((config) => groupFields.has(config.targetKey));
+            }
+            return []; // Group not found, return empty
+        }
+        // Pick specific fields
+        if (options.pick && options.pick.length > 0) {
+            const pickSet = new Set(options.pick.map(String));
+            return allConfigs.filter((config) => pickSet.has(config.targetKey));
+        }
+        // Omit specific fields
+        if (options.omit && options.omit.length > 0) {
+            const omitSet = new Set(options.omit.map(String));
+            return allConfigs.filter((config) => !omitSet.has(config.targetKey));
+        }
+        return allConfigs;
+    }
+    /**
+     * Builds an optimized mapping function
+     */
+    static buildMapper(targetType, entry, properties) {
+        // Separate transform functions from path mappings for optimization
+        const pathMappings = [];
+        const transformMappings = [];
+        for (const prop of properties) {
+            if (prop.isTransform && typeof prop.source === "function") {
+                transformMappings.push({
+                    target: prop.targetKey,
+                    transform: prop.source,
+                });
+            }
+            else {
+                pathMappings.push({
+                    target: prop.targetKey,
+                    source: prop.source,
+                });
+            }
+        }
+        // Return optimized mapper function
+        return (source, context) => {
+            if (source == null) {
+                return null;
+            }
+            // Create new instance or plain object based on target type
+            const result = new targetType();
+            // Apply path mappings (optimized)
+            for (let i = 0; i < pathMappings.length; i++) {
+                const mapping = pathMappings[i];
+                result[mapping.target] = (0, utils_1.getNestedValue)(source, mapping.source);
+            }
+            // Apply transform mappings
+            for (let i = 0; i < transformMappings.length; i++) {
+                const mapping = transformMappings[i];
+                result[mapping.target] = mapping.transform(source, context);
+            }
+            return result;
+        };
+    }
+}
+exports.MapperFactory = MapperFactory;

package/dist/cjs/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - Type Definitions
+ * Core types for the high-performance object mapper
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METADATA_KEYS = void 0;
+/**
+ * Metadata key constants
+ */
+exports.METADATA_KEYS = {
+    PROPERTY_MAPPINGS: Symbol("sevirial:property-mappings"),
+    FIELD_GROUPS: Symbol("sevirial:field-groups"),
+    AUTO_MAP: Symbol("sevirial:auto-map"),
+    IGNORE: Symbol("sevirial:ignore"),
+    NESTED_TYPE: Symbol("sevirial:nested-type"),
+};