The User Guide Recipe Author

1. The Big Story: From Source to Consumption

In modern enterprise architecture, data flows between three fundamentally distinct parties with contradictory incentives:

2. What Happens When We Transfer from Source to Consumption?

When transferring enterprise data to consumption, traditional developers write imperative scripts full of nested loops, mutation, and fragile condition checks. That shortcut is where systems fail:

• Cardinality Shock: XML parsers turn multiple items into an array, but a single item into a plain object. Imperative scripts throw TypeError: map is not a function.
• XML Clutter: Text nodes wrapped in #text and metadata attributes like @_TYPE="String" pollute your frontend stores.
• Silent Mutations: Modifying source objects in memory corrupts shared references and causes unpredictable memory leaks.

@keshavsoft/json-transformer provides a lossless, declarative bridge. It takes raw source data and a declarative recipe, compiling them into clean consumption JSON with zero side-effects.

3. Why Two Separate Files? The Immutability Principle

1. Client Data is Sacrosanct: Upstream data does not belong to you. Mutating incoming client payloads pollutes shared memory and breaks downstream consumers.
2. Preventing Infinite Loops: If a recursive engine mutates data while traversing it, self-referencing branches trigger infinite execution loops.
3. Independent Lifecycles: The Food changes on every API request. The Recipe changes only when your business contract evolves.

4. The Recipe is Knowledge, Not Duplication

Why does the recipe mirror the hierarchy of the source data? Because you cannot transform complex enterprise data without first proving you understand its hierarchy.

When an engineer writes a recipe matching the path down to the target field, they formally prove:

• Structural Proof: "I understand that STOCKITEM contains BATCHALLOCATIONS.LIST, which contains GODOWNNAME."
• Intentionality: Only paths that are explicitly acknowledged survive. All unrequested XML noise is pruned automatically.

5. Quickstart

npm install @keshavsoft/json-transformer

import transform from "@keshavsoft/json-transformer";

const source = {
  STOCKITEM: [
    {
      NAME: "Item A",
      BASEUNITS: { "#text": "kgs" }
    }
  ]
};

const recipe = {
  transform: {
    STOCKITEM: {
      alterKey: "Items",
      transform: {
        NAME: { alterKey: "name" },
        BASEUNITS: { alterKey: "units", valueKey: "#text" }
      }
    }
  }
};

const result = transform(source, recipe);
console.log(result);
// { Items: [ { name: "Item A", units: "kgs" } ] }