typemold 1.0.0

package/LICENSE

@@ -0,0 +1,43 @@
+MIT License
+
+Copyright (c) 2026 Chetan Prakash Joshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+MIT License
+
+Copyright (c) 2026 Chetan Joshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# typemold
+
+A **lightweight**, **high-performance** object mapper for NestJS with runtime field projection.
+
+[![npm version](https://badge.fury.io/js/%40sevirial%2Fnest-mapper.svg)](https://www.npmjs.com/package/typemold)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ⚡ **High Performance** - Compiled mappers cached after first use (no runtime reflection)
+- 🎯 **Runtime Field Projection** - Pick/omit fields without creating multiple DTOs
+- 📦 **Lightweight** - < 5KB bundle, zero production dependencies
+- 🏷️ **Field Groups** - Define reusable field sets with decorators
+- 🔧 **NestJS Integration** - Full module support with DI
+- ✅ **TypeScript First** - Full strict mode support
+- 🔄 **Hybrid Validation** - Optional class-validator integration
+
+## Installation
+
+```bash
+npm install typemold
+
+# Peer dependency (already in NestJS projects)
+npm install reflect-metadata
+```
+
+## Quick Start
+
+### 1. Define Your DTO
+
+```typescript
+import { AutoMap, MapFrom, FieldGroup } from "typemold";
+
+class UserDto {
+  @AutoMap()
+  username: string;
+
+  @MapFrom("profile.avatar")
+  avatarUrl: string;
+
+  @MapFrom((src) => src.age >= 18)
+  isAdult: boolean;
+
+  @AutoMap()
+  email: string;
+}
+```
+
+### 2. Map Objects
+
+```typescript
+import { Mapper } from "typemold";
+
+// Basic mapping
+const userDto = Mapper.map(userEntity, UserDto);
+
+// Array mapping
+const userDtos = Mapper.mapArray(users, UserDto);
+```
+
+## Runtime Field Projection ⭐
+
+**The killer feature** - reuse a single DTO across multiple endpoints:
+
+```typescript
+// Full user profile
+Mapper.map(user, UserDto);
+// Result: { username, avatarUrl, isAdult, email }
+
+// Only username and avatar (shorthand)
+Mapper.pick(user, UserDto, ["username", "avatarUrl"]);
+// Result: { username, avatarUrl }
+
+// Exclude sensitive fields
+Mapper.omit(user, UserDto, ["email"]);
+// Result: { username, avatarUrl, isAdult }
+
+// Using options object
+Mapper.map(user, UserDto, { pick: ["username", "avatarUrl"] });
+Mapper.map(user, UserDto, { omit: ["email"] });
+```
+
+## Field Groups
+
+Define reusable field sets:
+
+```typescript
+class UserDto {
+  @FieldGroup("minimal", "public")
+  @AutoMap()
+  username: string;
+
+  @FieldGroup("minimal", "public")
+  @MapFrom("profile.avatar")
+  avatar: string;
+
+  @FieldGroup("public", "full")
+  @AutoMap()
+  bio: string;
+
+  @FieldGroup("full")
+  @AutoMap()
+  email: string;
+}
+
+// Use field groups
+Mapper.group(user, UserDto, "minimal"); // { username, avatar }
+Mapper.group(user, UserDto, "public"); // { username, avatar, bio }
+Mapper.group(user, UserDto, "full"); // { bio, email }
+
+// Or via options
+Mapper.map(user, UserDto, { group: "minimal" });
+```
+
+## Decorators
+
+| Decorator                 | Description                  | Example                                          |
+| ------------------------- | ---------------------------- | ------------------------------------------------ |
+| `@AutoMap()`              | Maps property with same name | `@AutoMap() name: string`                        |
+| `@MapFrom(path)`          | Maps from nested path        | `@MapFrom('profile.avatar') avatar: string`      |
+| `@MapFrom(fn)`            | Custom transform             | `@MapFrom(src => src.age > 18) isAdult: boolean` |
+| `@FieldGroup(...groups)`  | Assigns to field groups      | `@FieldGroup('minimal', 'public')`               |
+| `@Ignore()`               | Skips property               | `@Ignore() internalId: string`                   |
+| `@NestedType(() => Type)` | Nested object mapping        | `@NestedType(() => AddressDto)`                  |
+
+## NestJS Integration
+
+### Basic Setup
+
+```typescript
+import { Module } from "@nestjs/common";
+import { MapperModule } from "typemold";
+
+@Module({
+  imports: [MapperModule.forRoot()], // Global by default
+})
+export class AppModule {}
+```
+
+### With Validation
+
+```typescript
+@Module({
+  imports: [
+    MapperModule.forRoot({
+      enableValidation: true, // Uses class-validator if installed
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async Configuration
+
+```typescript
+@Module({
+  imports: [
+    MapperModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: (config: ConfigService) => ({
+        enableValidation: config.get("ENABLE_VALIDATION"),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Using MapperService
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { MapperService } from "typemold";
+
+@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);
+  }
+
+  async getUserMinimal(id: string): Promise<Partial<UserDto>> {
+    const user = await this.userRepo.findOne(id);
+    return this.mapper.group(user, UserDto, "minimal");
+  }
+
+  async getPostAuthor(
+    postId: string
+  ): Promise<Pick<UserDto, "username" | "avatar">> {
+    const user = await this.getPostUser(postId);
+    return this.mapper.pick(user, UserDto, ["username", "avatar"]);
+  }
+}
+```
+
+## Performance
+
+Thanks to compiled & cached mappers, performance is near-identical to hand-written mapping code:
+
+| Operation    | typemold | @automapper/nestjs | Manual   |
+| ------------ | --------------------- | ------------------ | -------- |
+| Single map   | ~0.002ms              | ~0.05ms            | ~0.001ms |
+| Array (1000) | ~1.5ms                | ~40ms              | ~1ms     |
+| Memory       | O(1) cache            | O(n) profiles      | None     |
+
+## API Reference
+
+### Mapper (Static)
+
+```typescript
+Mapper.map(source, TargetDto, options?)
+Mapper.mapArray(sources, TargetDto, options?)
+Mapper.pick(source, TargetDto, ['field1', 'field2'])
+Mapper.omit(source, TargetDto, ['field1'])
+Mapper.group(source, TargetDto, 'groupName')
+Mapper.createMapper(TargetDto, options?) // Returns reusable function
+```
+
+### MapOptions
+
+```typescript
+interface MapOptions<T> {
+  pick?: (keyof T)[]; // Include only these fields
+  omit?: (keyof T)[]; // Exclude these fields
+  group?: string; // Use predefined field group
+  extras?: Record<string, unknown>; // Extra context for transforms
+}
+```
+
+## License
+
+MIT © [Sevirial](https://sevirial.com)

package/dist/cjs/decorators.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * @sevirial/nest-mapper - Decorators
+ * Property decorators for defining mapping configurations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Groups = void 0;
+exports.MapFrom = MapFrom;
+exports.createMapping = createMapping;
+exports.AutoMap = AutoMap;
+exports.FieldGroup = FieldGroup;
+exports.createFieldGroups = createFieldGroups;
+exports.Ignore = Ignore;
+exports.NestedType = NestedType;
+require("reflect-metadata");
+const types_1 = require("./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;
+ * }
+ */
+function MapFrom(sourcePathOrTransform) {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(types_1.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(types_1.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);
+ */
+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
+ * }
+ */
+function AutoMap() {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(types_1.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(types_1.METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+        Reflect.defineMetadata(types_1.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;
+ * }
+ */
+function FieldGroup(...groups) {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(types_1.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(types_1.METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+        // Also store in field groups map for quick lookup
+        const fieldGroups = Reflect.getMetadata(types_1.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(types_1.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!
+ */
+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!
+ */
+exports.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
+ * }
+ */
+function Ignore() {
+    return (target, propertyKey) => {
+        const key = String(propertyKey);
+        const existingMappings = Reflect.getMetadata(types_1.METADATA_KEYS.PROPERTY_MAPPINGS, target.constructor) || new Map();
+        const existingConfig = existingMappings.get(key) || createDefaultConfig(key);
+        existingConfig.ignore = true;
+        existingMappings.set(key, existingConfig);
+        Reflect.defineMetadata(types_1.METADATA_KEYS.PROPERTY_MAPPINGS, existingMappings, target.constructor);
+        Reflect.defineMetadata(types_1.METADATA_KEYS.IGNORE, true, target.constructor, key);
+    };
+}
+/**
+ * Specifies the type for nested object mapping.
+ *
+ * @example
+ * class UserDto {
+ *   @NestedType(() => AddressDto)
+ *   @MapFrom('address')
+ *   address: AddressDto;
+ * }
+ */
+function NestedType(typeFactory) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(types_1.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/cjs/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * 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 {}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAPPER_OPTIONS = exports.MapperService = exports.MapperModule = exports.isClassInstance = exports.isPlainObject = exports.omitKeys = exports.pickKeys = exports.getNestedValue = exports.MapperFactory = exports.MappingRegistry = exports.METADATA_KEYS = exports.NestedType = exports.Ignore = exports.Groups = exports.createFieldGroups = exports.FieldGroup = exports.AutoMap = exports.createMapping = exports.MapFrom = exports.Mapper = void 0;
+// Core Mapper
+var mapper_1 = require("./mapper");
+Object.defineProperty(exports, "Mapper", { enumerable: true, get: function () { return mapper_1.Mapper; } });
+// Decorators
+var decorators_1 = require("./decorators");
+Object.defineProperty(exports, "MapFrom", { enumerable: true, get: function () { return decorators_1.MapFrom; } });
+Object.defineProperty(exports, "createMapping", { enumerable: true, get: function () { return decorators_1.createMapping; } });
+Object.defineProperty(exports, "AutoMap", { enumerable: true, get: function () { return decorators_1.AutoMap; } });
+Object.defineProperty(exports, "FieldGroup", { enumerable: true, get: function () { return decorators_1.FieldGroup; } });
+Object.defineProperty(exports, "createFieldGroups", { enumerable: true, get: function () { return decorators_1.createFieldGroups; } });
+Object.defineProperty(exports, "Groups", { enumerable: true, get: function () { return decorators_1.Groups; } });
+Object.defineProperty(exports, "Ignore", { enumerable: true, get: function () { return decorators_1.Ignore; } });
+Object.defineProperty(exports, "NestedType", { enumerable: true, get: function () { return decorators_1.NestedType; } });
+// Types
+var types_1 = require("./types");
+Object.defineProperty(exports, "METADATA_KEYS", { enumerable: true, get: function () { return types_1.METADATA_KEYS; } });
+// Registry (for advanced usage)
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "MappingRegistry", { enumerable: true, get: function () { return registry_1.MappingRegistry; } });
+Object.defineProperty(exports, "MapperFactory", { enumerable: true, get: function () { return registry_1.MapperFactory; } });
+// Utilities
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "getNestedValue", { enumerable: true, get: function () { return utils_1.getNestedValue; } });
+Object.defineProperty(exports, "pickKeys", { enumerable: true, get: function () { return utils_1.pickKeys; } });
+Object.defineProperty(exports, "omitKeys", { enumerable: true, get: function () { return utils_1.omitKeys; } });
+Object.defineProperty(exports, "isPlainObject", { enumerable: true, get: function () { return utils_1.isPlainObject; } });
+Object.defineProperty(exports, "isClassInstance", { enumerable: true, get: function () { return utils_1.isClassInstance; } });
+// NestJS Integration
+var nestjs_1 = require("./nestjs");
+Object.defineProperty(exports, "MapperModule", { enumerable: true, get: function () { return nestjs_1.MapperModule; } });
+Object.defineProperty(exports, "MapperService", { enumerable: true, get: function () { return nestjs_1.MapperService; } });
+Object.defineProperty(exports, "MAPPER_OPTIONS", { enumerable: true, get: function () { return nestjs_1.MAPPER_OPTIONS; } });