@sovgut/allocate

Features

• 🔄 Key Remapping: Transform object keys based on a simple schema
• 🎯 Deep Path Support: Navigate and transform deeply nested properties using dot notation
• 📦 Array Handling: Process arrays of objects with special [] notation
• 🌳 Nested Transformations: Handle complex nested structures with ease
• 🚀 Zero Dependencies: Lightweight and fast

Installation

npm install @sovgut/allocate

yarn add @sovgut/allocate

pnpm add @sovgut/allocate

Table of Contents

• Quick Start
• Usage
  • Basic Example
  • Working with Nested Objects
  • Array Transformations
  • Complex Nested Arrays
  • Root-Level Arrays
• API Reference
• Important Notes
• Contributing
• License

Quick Start

Get started with @sovgut/allocate in seconds:

import { allocate } from '@sovgut/allocate';

// Transform a simple object
const user = { firstName: 'John', lastName: 'Doe' };
const result = allocate(user, {
  firstName: 'name.first',
  lastName: 'name.last'
});
// Output: { name: { first: 'John', last: 'Doe' } }

// Transform an array of objects
const users = [{ id: 1, email: '[email protected]' }];
const transformed = allocate(users, {
  '[].id': '[].userId',
  '[].email': '[].contact.email'
});
// Output: [{ userId: 1, contact: { email: '[email protected]' } }]

Usage

Basic Example

import { allocate } from '@sovgut/allocate';

const user = {
  firstName: 'John',
  lastName: 'Doe'
};

const schema = {
  firstName: 'name.first',
  lastName: 'name.last'
};

const result = allocate(user, schema);
// Result: { name: { first: 'John', last: 'Doe' } }

Working with Nested Objects

Use dot notation to access and transform nested properties:

const data = {
  user: {
    details: {
      email: '[email protected]',
      phone: '123-456-7890'
    }
  }
};

const schema = {
  'user.details.email': 'contact.email',
  'user.details.phone': 'contact.phone'
};

const result = allocate(data, schema);
// Result: { 
//   contact: { email: '[email protected]', phone: '123-456-7890' },
//   user: { details: {} }
// }

Array Transformations

Transform arrays of objects using the [] notation:

const data = {
  users: [
    { id: 1, name: 'John' },
    { id: 2, name: 'Jane' }
  ]
};

const schema = {
  'users[].id': 'people[].userId',
  'users[].name': 'people[].fullName'
};

const result = allocate(data, schema);
// Result: {
//   people: [
//     { userId: 1, fullName: 'John' },
//     { userId: 2, fullName: 'Jane' }
//   ],
//   users: [{}, {}]
// }

Complex Nested Arrays

Handle deeply nested array structures:

const data = {
  departments: [
    {
      name: 'Engineering',
      teams: [
        { id: 1, lead: 'Alice' },
        { id: 2, lead: 'Bob' }
      ]
    }
  ]
};

const schema = {
  'departments[].teams[].lead': 'departments[].teams[].manager'
};

const result = allocate(data, schema);
// Result: {
//   departments: [{
//     name: 'Engineering',
//     teams: [
//       { id: 1, manager: 'Alice' },
//       { id: 2, manager: 'Bob' }
//     ]
//   }]
// }

Root-Level Arrays

Transform arrays at the root level:

const users = [
  { firstName: 'John', age: 30 },
  { firstName: 'Jane', age: 25 }
];

const schema = {
  '[].firstName': '[].name',
  '[].age': '[].years'
};

const result = allocate(users, schema);
// Result: [
//   { name: 'John', years: 30 },
//   { name: 'Jane', years: 25 }
// ]

API Reference

allocate(source, schema)

Transforms an object or array structure according to the provided schema.

Parameters

• source: T - The source object or array to transform. Can be:

  • A plain object
  • An array of objects
  • null or undefined (returns as-is)

• schema: Record<string, string> - A mapping of source paths to destination paths

Returns

Returns the transformed object/array with keys remapped according to the schema. The original source remains unchanged.

Path Syntax

• Dot notation: Access nested properties (e.g., 'user.profile.name')
• Array notation: Use [] to indicate array iteration (e.g., 'users[].name')
• Combined: Mix both notations (e.g., 'data[].items[].value')

Important Notes

1. Original Structure: The function preserves parts of the original structure that aren't explicitly transformed
2. Empty Objects: After moving properties, empty parent objects remain in the result
3. Type Preservation: All value types are preserved during transformation
4. Non-existent Paths: Accessing non-existent paths results in undefined values
5. Self-referencing: Mapping a path to itself keeps the value in place

🤝 Contributing

If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request on GitHub.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.