JSON Shape Converter Yolabs 🔄

The ultimate tool for surgical data transformation. json-shape-converter-yolabs allows you to redefine, flatten, and restructure complex JSON objects using a simple, declarative schema.

🏗️ Core Concept

The engine follows a Source + Schema = Result pattern. It is built to handle:

• Deep Nesting: Resolve values from multi-level objects using dot-notation.
• Complex Lists: Automatically iterate and reshape arrays of objects.
• Calculated Values: Create new data points using custom functions.
• Data Safety: Fallback to default values when source data is missing.

📦 Installation

npm install json-shape-converter-yolabs

🛠 Usage & Scenarios

1. Simple Array Transformation (Renaming & Flattening)

Automatically process a list of objects to standardize keys.

Input:

[
  { "pk": 101, "attributes": { "title": "Apple" } },
  { "pk": 102, "attributes": { "title": "Banana" } },
  { "pk": 103, "attributes": { "title": "Cherry" } }
]

Implementation:

import { reshape } from 'json-shape-converter-yolabs';

const schema = {
  id: 'pk',
  name: 'attributes.title' // Flatten deep values
};

const result = reshape(input, schema);
// Result: [{ "id": 101, "name": "Apple" }, ...]

2. Complex Nested Input (The "API Normalizer")

Transform a complex, multi-level object into a clean, specific structure.

Input:

[
  {
    "UUID": "USR-1",
    "personal": { "name": { "first": "John", "last": "Doe" }, "age": 28 },
    "access": { "roles": ["admin", "editor"] }
  },
  {
    "UUID": "USR-2",
    "personal": { "name": { "first": "Jane", "last": "Smith" }, "age": 34 },
    "access": { "roles": ["viewer"] }
  },
  {
    "UUID": "USR-3",
    "personal": { "name": { "first": "Alex", "last": "Vane" } },
    "access": { "roles": [] }
  }
]

Implementation:

const schema = {
  uid: "UUID",
  // Nested Output Creation
  profile: {
    fullName: (src) => `${src.personal.name.first} ${src.personal.name.last}`,
    // Default value with a calculation
    isSenior: {
      path: "personal.age",
      default: 0,
      transform: (age) => age > 30
    }
  },
  // Deep Array Access
  primaryRole: {
    path: "access.roles.0",
    default: "guest"
  }
};

const result = reshape(input, schema);

Output:

[
  {
    "uid": "USR-1",
    "profile": { "fullName": "John Doe", "isSenior": false },
    "primaryRole": "admin"
  },
  {
    "uid": "USR-2",
    "profile": { "fullName": "Jane Smith", "isSenior": true },
    "primaryRole": "viewer"
  },
  {
    "uid": "USR-3",
    "profile": { "fullName": "Alex Vane", "isSenior": false },
    "primaryRole": "guest"
  }
]

3. Data Transformation with Logic

Perform math or logic while reshaping.

Input:

[
  { "item": "A", "stats": { "qty": 10, "price": 5 } },
  { "item": "B", "stats": { "qty": 2, "price": 50 } },
  { "item": "C", "stats": { "qty": 5, "price": 20 } }
]

Implementation:

const schema = {
  product: "item",
  inventory: {
    // Custom logic using the source object
    totalValue: (src) => src.stats.qty * src.stats.price,
    inStock: {
      path: "stats.qty",
      transform: (q) => q > 0
    }
  }
};

const result = reshape(input, schema);

⚙️ API Reference

reshape(data, schema)

| Rule Type | Syntax Example | Description | | --- | --- | --- | | String | 'user.id' | Maps target key to source path (dot notation supported). | | Function | (src) => src.id | Returns a value based on the entire source object. | | Config Object | { path, default, transform } | Advanced control: path lookup, fallback, and value mutation. | | Nested Object | { sub: { ... } } | Creates a nested object in the result. |

⚛️ Framework Usage

1. Next.js (App Router / Server Components)

Reshape your data on the Server before it even reaches the client. This reduces the payload size and keeps your UI logic clean.

app/users/page.tsx

import { reshape } from 'json-shape-converter-yolabs';

const schema = {
  uid: 'id',
  displayName: 'username',
  location: 'address.city',
  // Create a clean URL from raw data
  profileUrl: (src) => `https://myapp.com/user/${src.id}`
};

export default async function Page() {
  // Fetching a list of 10 users (Array of Objects)
  const res = await fetch('https://jsonplaceholder.typicode.com/users');
  const rawData = await res.json();

  // Transform the entire array instantly
  const users = reshape(rawData, schema);

  return (
    <ul>
      {users.map(user => (
        <li key={user.uid}>{user.displayName} from {user.location}</li>
      ))}
    </ul>
  );
}

2. React (Client-Side State)

Perfect for normalizing data from various sources before saving it to your state or store.

components/UserList.tsx

import React, { useEffect, useState } from 'react';
import { reshape } from 'json-shape-converter-yolabs';

export const UserList = () => {
  const [items, setItems] = useState([]);

  useEffect(() => {
    const rawApiData = [
      { id: 1, info: { title: "Item A" }, active: true },
      { id: 2, info: { title: "Item B" }, active: false },
      { id: 3, info: { title: "Item C" }, active: true }
    ];

    const mySchema = {
      key: 'id',
      label: 'info.title',
      status: {
        path: 'active',
        transform: (v) => v ? '✅ Online' : '❌ Offline'
      }
    };

    // Transform before setting state
    setItems(reshape(rawApiData, mySchema));
  }, []);

  return (
    <div>
      {items.map(item => (
        <div key={item.key}>{item.label}: {item.status}</div>
      ))}
    </div>
  );
};

⚙️ Why use Yolabs Converter?

| Problem | Yolabs Solution | | --- | --- | | Deep Nesting | Use simple dot-notation strings like "meta.user.name". | | Missing Data | Use the default key to provide fallbacks automatically. | | Messy Logic | Use transform functions to keep UI components pure. | | Large Bundles | Ultra-lightweight with zero dependencies. |

📜 License

Yolabs <+251930327375>