emberjs/data — pull request #1339 by tstirrat (2013-09-22 03:12:40+00:00)
Title: Allow an underscore to force secondary loading when secondary type is same as primary

This allows you to normalize your payload when you have embedded records of the same type as the primary query type (a tree/node structure).

If you were to use the standard normalization procedure and append to the primary array, your query comes back with unexpected results.

```javascript
var App.Category = DS.Model.extend({
name: DS.attr('string'),
root: DS.attr('boolean'),
children: DS.hasMany('category')
});

// payload: store.find('category', { root: true });
{
"categories": [{
"id": 1,
"name": "Main Category",
"root": true,
"children": [{ id: 2, ... }, { id: 3, ... }]
}]
}

// normalizePayload cannot be done without modifying the primary array
{
"categories": [{
"id": 1,
"name": "Main Category",
"root": true,
"children": [2, 3]
},
{ id: 2, ... },
{ id: 3, ... }
],
}
```

We cannot move those embedded records into `payload.categories` or the recordArray will be populated with 3 categories inside it.

However, after this patch, if we move those children into `payload._categories` it will load the sub categories into the store while keeping the primary array unaltered.

```javascript
{
// primary array
"categories": [{
"id": 1,
"name": "Main Category",
"root": true,
"children": [2, 3]
}],
// loaded into store for relationships
"_categories": [{ id: 2, ...}, { id: 3, ...}]
}
```

Apologies if the documentation update is not clear enough. I'm happy to write something more in the ember guides if we decide to go ahead and merge this.