object-morpher

object-morpher is an advanced transformation utility designed to work with single-level object structures, such as command-line arguments. It serves as an extension and rewrite of the previous library, alias-mapper, with enhanced capabilities to handle complex data transformations while maintaining a focus on single-level initial objects.

Features

1. Extended Functionality: Building upon the foundation of my previous library (alias-mapper), object-morpher introduces additional features like dynamic compute functions and value mappings, offering more power and flexibility in data shaping.

2. Single-Level Object Focus: Despite its advanced features, object-morpher remains targeted at processing single-level initial objects, ensuring simplicity and ease of use where complex nested structures are not required.

3. Value Parsing: It is recommended to use a parsing library such as zod for handling value parsing and type safety, which complements object-morpher's transformation capabilities.

4. TypeScript Support: Fully typed to enable IntelliSense in your favorite IDE.

By leveraging object-morpher, developers can easily manipulate data structures to fit their application's needs, streamlining the process of data handling and transformation.

It's primarily used with Bun, so use:

bun add github:ristosha/object-morpher

or just npm:

npm install object-morpher

Usage

First, import the library:

import { transformObject } from 'object-morpher';

Define your schema:

const schema = {
  age: {
    _compute: (val: number) => val + 1,
    _aliases: ['profileAge'],
    _values: {
      "60": "old",
      "30": "middle",
      "12": "young"
    }
  },
  // ... other schema definitions
};

Transform your object:

const user = {
  profileAge: "young",
  // ... other user properties
};

const transformedUser = transformObject(user, schema);

Some examples from tests:

const obj = { name: 'John', age: 30 }

const schema: Schema<typeof obj> = {
    name: { _compute: (val: string) => val.toUpperCase() },
    age: { _compute: (val: number) => val + 1 }
}

// transformObject(obj, schema)

const expected = { name: 'JOHN', age: 31 }

const obj = { fullName: 'Alice Wonderland' }

const schema: Schema = {
    __composite: {
      fullName: {
        _compute: (val: string) => {
          const [firstName, lastName] = val.split(' ')
          return { firstName, lastName }
        }
      }
    }
}

// transformObject(obj, schema)

const expected = { firstName: 'Alice', lastName: 'Wonderland' }

⚠️ Caution

For frequent use cases, it is highly recommended to pre-generate the alias map using generateAliasMap(schema). This practice improves performance by avoiding the overhead of recalculating the map for each transformation, especially when dealing with large schemas or processing numerous objects.

API Reference

transformObject(obj, schema, aliasMap?)

Transforms an object based on the provided schema and optional alias map.

• obj: The object to transform.
• schema: The schema definition for the transformation.
• aliasMap: Optional map of aliases to property paths.

Schema Definition

A schema is defined as an object where each key corresponds to a property in the source object. Each key's value is an object that can have the following properties:

• _compute: A function that takes the property's value and returns a new value.
• _values: An object mapping possible values to their aliases. (don't work with _compute)
• _aliases: An array of strings representing aliases for the property.

License

object-morpher is MIT licensed.