transmutant

🧬 Transmutant 🧬

A powerful, type-safe TypeScript library for transmuting objects through flexible schema definitions.

Features

• 🔒 Type-safe: Full TypeScript support with strong type inference
• 🎯 Flexible mapping: Direct property mapping or custom transmuter functions
• ⚡ High performance: Minimal overhead and zero dependencies
• 🔄 Extensible: Support for custom transmutation logic and external data
• 📦 Lightweight: Zero dependencies, small bundle size
• 🛠️ Predictable: Transparent handling of undefined values

Installation

npm install transmutant

Quick Start

import { Schema, transmute } from 'transmutant'

// Source type
interface User {
  firstName: string;
  lastName: string;
  email: string;
}

// Target type
interface UserDTO {
  fullName: string;
  contactEmail: string;
}

// Define transmutation schema
const schema: Schema<User, UserDTO>[] = [
  {
    to: 'fullName',
    from: ({ source }) => `${source.firstName} ${source.lastName}`
  },
  {
    to: 'contactEmail',
    from: 'email'
  }
]

// Transmute the object
const user: User = {
  firstName: 'John',
  lastName: 'Doe',
  email: '[e-mail]'
}

const userDTO = transmute(schema, user)
// Result: { fullName: 'John Doe', contactEmail: '[e-mail]' }

Core Concepts

Schema Definition

A schema is an array of transmutation rules that define how properties should be mapped from the source to the target type. Each rule specifies:

• The target property key (to)
• Either a source property key for direct mapping or a transmuter function (from)

type Schema<Source, Target, Extra> = {
  to: keyof Target,
  from: keyof Source | Transmuter<Source, Target, Extra>
}

Transmutation Types

1. Direct Property Mapping

Map a property directly from source to target when types are compatible:

interface Source {
  email: string;
}

interface Target {
  contactEmail: string;
}

const schema: Schema<Source, Target>[] = [
  { to: 'contactEmail', from: 'email' }
]

2. Custom Transmuter Functions

Transmute properties using custom logic with full type safety:

interface Source {
  age: number;
}

interface Target {
  isAdult: boolean;
}

const schema: Schema<Source, Target>[] = [
  {
    to: 'isAdult',
    from: ({ source }) => source.age >= 18
  }
];

3. External Data Transmutations

Include additional context in transmutations through the extra parameter:

interface Source {
  city: string;
  country: string;
}

interface Target {
  location: string;
}

interface ExtraData {
  separator: string;
}

const schema: Schema<Source, Target, ExtraData>[] = [
  {
    to: 'location',
    from: ({ source, extra }) =>
      `${source.city}${extra.separator}${source.country}`
  }
];

const result = transmute(schema,
  { city: 'New York', country: 'USA' },
  { separator: ', ' }
);
// Result: { location: 'New York, USA' }

API Reference

Types

// Arguments passed to a mutation function
type TransmuterArgs<Source, Extra> = { source: Source, extra?: Extra }

// Function that performs a custom transmutation
type Transmuter<Source, Target, Extra> = (args: TransmuterArgs<Source, Extra>) => Target[keyof Target]

// Defines how a property should be transmuted
type Schema<Source, Target, Extra> = {
  to: keyof Target,
  from: keyof Source | Transmuter<Source, Target, Extra>
}

transmute()

Main function for performing object transmutations.

function transmute<Source, Target, Extra>(
  schema: Schema<Source, Target, Extra>[],
  source: Source,
  extra?: Extra
): Target;

Parameters

Parameter	Type	Description
schema	Schema<Source, Target, Extra>[]	Array of transmutation rules
source	Source	Source object to transmute
extra	Extra (optional)	Additional data for transmutations

Returns

Returns an object of type Target with all specified transmutations applied.

Type Safety Examples

The library provides strong type checking for both direct mappings and custom transmutations:

interface Source {
  firstName: string;
  lastName: string;
  age: number;
}

interface Target {
  fullName: string;
  isAdult: boolean;
}

// Correct usage - types match
const validSchema: Schema<Source, Target>[] = [
  {
    to: 'fullName',
    from: ({ source }) => `${source.firstName} ${source.lastName}`  // Returns string
  },
  {
    to: 'isAdult',
    from: ({ source }) => source.age >= 18  // Returns boolean
  }
];

// Type error - incorrect return type
const invalidSchema: Schema<Source, Target>[] = [
  {
    to: 'isAdult',
    from: ({ source }) => source.age  // Error: number not assignable to boolean
  }
];

Contributing

Contributions are welcome! Feel free to submit a Pull Request.

License

MIT © Antoni Oriol

---

_{Built with ❤️ by Antoni Oriol}

Changelog

4.0.0 (2024-11-01)

⚠ BREAKING CHANGES

• types: Changed Extra type parameter default from unknown to undefined for better type inference and runtime behavior alignment.

Code Refactoring

• types: switch Extra type parameter default to undefined (83c5a56)