docs: update README to enhance clarity and structure, adding new features and examples

Author: Sovgut

README.md

@@ -1,118 +1,253 @@
 # @sovgut/allocate
 
-A powerful utility for transforming the keys of objects or arrays of objects according to a specified schema. This package allows you to replace keys in deeply nested structures with ease.
+<p align="center">
+  <b>A lightweight TypeScript utility for transforming object and array structures by remapping keys according to a schema. Perfect for API response transformation, data migration, and object restructuring.</b>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@sovgut/allocate" alt="npm version" />
+  <img src="https://img.shields.io/npm/dm/@sovgut/allocate" alt="npm downloads" />
+  <img src="https://img.shields.io/github/license/sovgut/allocate" alt="license" />
+</p>
 
 ## Features
 
-- **Key Replacement:** Easily replace keys in objects or arrays based on a schema.
-- **Nested Structures:** Supports nested objects and arrays, even with complex paths.
-- **Array Handling:** Seamlessly process arrays of objects, applying key replacement to each item.
+- 🔄 **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
 
-Install the package via npm:
-
 ```bash
 npm install @sovgut/allocate
 ```
 
-Or via yarn:
-
 ```bash
 yarn add @sovgut/allocate
 ```
 
-## Usage
+```bash
+pnpm add @sovgut/allocate
+```
 
-### Basic Key Replacement
+## Table of Contents
 
-Replace keys in a simple object:
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+  - [Working with Nested Objects](#working-with-nested-objects)
+  - [Array Transformations](#array-transformations)
+  - [Complex Nested Arrays](#complex-nested-arrays)
+  - [Root-Level Arrays](#root-level-arrays)
+- [API Reference](#api-reference)
+- [Important Notes](#important-notes)
+- [Contributing](#-contributing)
+- [License](#-license)
 
-```typescript
-import { Allocate } from '@sovgut/allocate'
+## Quick Start
 
-const source = { foo: true, qux: false }
-const schema = { foo: 'bar' }
+Get started with `@sovgut/allocate` in seconds:
 
-allocate(source, schema) // { bar: true }
+```typescript
+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: 'john@example.com' }];
+const transformed = allocate(users, {
+  '[].id': '[].userId',
+  '[].email': '[].contact.email'
+});
+// Output: [{ userId: 1, contact: { email: 'john@example.com' } }]
 ```
 
-### Nested Key Replacement
+## Usage
 
-Handle nested structures with dot notation:
+### Basic Example
 
 ```typescript
-import { Allocate } from '@sovgut/allocate'
+import { allocate } from '@sovgut/allocate';
+
+const user = {
+  firstName: 'John',
+  lastName: 'Doe'
+};
 
-const source = { foo: { bar: true, baz: false } }
-const schema = { 'foo.baz': 'bar.qux' }
+const schema = {
+  firstName: 'name.first',
+  lastName: 'name.last'
+};
 
-allocate(source, schema) // { bar: { qux: false } }
+const result = allocate(user, schema);
+// Result: { name: { first: 'John', last: 'Doe' } }
 ```
 
-### Array of Objects
+### Working with Nested Objects
 
-Apply key replacement to each object in an array:
+Use dot notation to access and transform nested properties:
 
 ```typescript
-import { Allocate } from '@sovgut/allocate'
-
-const source = [{ foo: true }, { foo: true, bar: 123 }]
-const schema = { '[].foo': '[].bar' }
-
-allocate(source, schema) // [{ bar: true }, { bar: true }]
+const data = {
+  user: {
+    details: {
+      email: 'john@example.com',
+      phone: '123-456-7890'
+    }
+  }
+};
+
+const schema = {
+  'user.details.email': 'contact.email',
+  'user.details.phone': 'contact.phone'
+};
+
+const result = allocate(data, schema);
+// Result: { 
+//   contact: { email: 'john@example.com', phone: '123-456-7890' },
+//   user: { details: {} }
+// }
 ```
 
-### Complex Nested Structures
+### Array Transformations
 
-Work with deeply nested arrays and objects:
+Transform arrays of objects using the `[]` notation:
 
 ```typescript
-import { allocate } from '@sovgut/allocate'
+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
 
-const source = { foo: { bar: [{ baz: true }, { baz: true }] } }
-const schema = { 'foo.bar[].baz': 'foo.bar[].qux' }
+Handle deeply nested array structures:
 
-allocate(source, schema) // { foo: { bar: [{ qux: true }, { qux: true }] } }
+```typescript
+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' }
+//     ]
+//   }]
+// }
 ```
 
-## API
+### Root-Level Arrays
+
+Transform arrays at the root level:
 
 ```typescript
-/**
- * Transforms the keys of an object or an array of objects according to a specified schema.
- *
- * The `allocate` function takes a source object (or array of objects) and a schema that defines
- * how the keys in the source should be transformed. It returns a new object (or array) with
- * the keys replaced as specified by the schema.
- *
- * @template TResult - The type of the resulting object or array after key allocation.
- * @param {NonNullable<object | object[]>} source - The source object or array to be transformed. It must be a non-null object or array of objects.
- * @param {AllocateSchema} schema - An object where each key-value pair defines the mapping from the old key to the new key.
- * @returns {TResult} - The transformed object or array with the keys replaced according to the schema.
- *
- * @throws {TypeError} Throws an error if the schema is not an object or if the source is not an object or an array.
- */
-export declare function allocate<TResult>(source: NonNullable<object | object[]>, schema: AllocateSchema): TResult
-
-/**
- * A map of key-value pairs that define how to replace keys in the source.
- *
- * The keys of this record represent the current keys in the source object,
- * and the values represent the required keys that will replace them in the allocated object.
- *
- * @type {Record<string, string>}
- */
-export declare type AllocateSchema = Record<string, string>
+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 }
+// ]
 ```
 
-#### Parameters:
-- `source`: The source object or array of objects to be transformed.
-- `schema`: An object defining the mapping between old keys and new keys. Use dot notation for nested keys and `*` to indicate array elements.
+## 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](https://github.com/sovgut/allocate).
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-#### Returns:
-- A new object or array with keys replaced according to the schema.
+---
 
-## License
+<p align="center">
+  Made with ❤️ by <a href="https://github.com/sovgut">sovgut</a>
+</p>
 
-This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
+<p align="center">
+  <a href="https://github.com/sovgut/allocate">GitHub</a> •
+  <a href="https://www.npmjs.com/package/@sovgut/allocate">npm</a> •
+  <a href="#-api-reference">Documentation</a>
+</p>