🧬 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: '[email protected]'
}

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

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