Document 6 — Understanding the Function The 4 Inputs

The traversal engine knows where it is in the source.
The function receives that information and decides what to do with it.

1. The External Function Signature

The traversal engine does not need to know what the function actually does. The application supplies the function:

function inspect(value, path, source, instruction) {
  console.log("Value:", value);
  console.log("Path:", path);
  console.log("Source:", source);
  console.log("Instruction:", instruction);
}

The central question is: what does each argument represent?

2. Architecture Diagram: The Four Inputs

CURRENT FUNCTION
                        │
        ┌───────────────┼────────────────┐
        │               │                │
      value            path          root/source
        │               │                │
        ▼               ▼                ▼
   What did we    Where are we?    What is the complete
   find here?                      source we're working on?
                        
                        +
               instruction/context
                        │
                        ▼
                 Why are we here?

3. Input 1: value — What Did We Find?

value is the actual data found at the current location in the source:

{
  "customer": {
    "name": "Keshav"
  }
}

If the current location is customer.name, then:

value === "Keshav"

4. Input 2: path — Where Are We?

path tells the function where the current value was found in the tree:

path === "customer.name"

The value tells us what we found; the path tells us where we found it.

5. Input 3: source — What is the Context?

source represents the complete root data structure being traversed:

{
  "customer": {
    "name": "Keshav",
    "email": "keshav@example.com"
  },
  "order": {
    "id": "ORD-101"
  }
}

Even though the function is operating on customer.name, it can access the complete source whenever cross-referencing context (such as looking up order.id) is required.

6. Input 4: instruction — Why Are We Here?

instruction represents the recipe directive that caused the function to be invoked at this location:

{
  "transform": "inspect"
}

The function knows not only the data and its location, but also why it was called.

7. Putting It Together: The Complete Mental Model

SOURCE
   ↓
TRAVERSAL
   ↓
Current Node
   ↓
┌─────────────────────────────┐
│ value                       │  → What did we find here?
│ path                        │  → Where are we in the tree?
│ source                      │  → What is the complete source?
│ instruction                 │  → Why are we here?
└─────────────────────────────┘
   ↓
FUNCTION
   ↓
Application behavior executed

8. The Production Transformation Function: The in / local Pipeline

In production systems, this leaf-function mental model evolves into the modular Transformation Function pipeline:

• Strict Input Envelope: All transformation functions accept a single named object with in-prefixed keys (e.g. { inValue, inDirective }).
• Immutable Local Scope: The top line unrolls inputs into local... constants to eliminate parameter reassignment bugs.
• Composed Responsibility: Instead of writing monolithic transformation blobs, each step is its own micro-function:
  1. resolveKey — computes output property names (alterKey).
  2. applyTransform — traverses nested recipes recursively.
  3. normalizeValueType — ensures singleton objects become arrays (valueType: "array") when downstream consumers require list semantics.
  4. extractValueKey — strips XML wrappers (valueKey).