How can I save a single entity with EntityManager's saveChanges() method?

Suppose I have the following data structure: a Customer entity that has a collection of Orders (1 to n relationship). So, Customer.Orders() returns an array of zero or more Orders.

Now, I create a new Customer newCustomer, and a new Orders entity array. This Orders entity array is assigned to the Customer. All entities have the "Added" entity state.

Then, I call saveChanges() as follows:

manager.saveChanges([newCustomer])

I used the saveChanges()'s [entities] parameter according to this documentation: http://www.breezejs.com/sites/all/apidocs/classes/EntityManager.html#method_saveChanges

I would expect that both the newCustomer and its Orders array would be saved in the server, but only the newCustomer was saved.

Is there any way to save the newCustomer and its Orders array? Maybe I could pass all entities in the [entities] parameter, but this would be verbose and a point of bugs. I know I could call only saveChanges() method to save all entities, but I want to save only a specific entity completely.

Thanks in advance,

Bernardo Pacheco

Solution

Update 8 Oct 2014

I'm sticking with my original advice to avoid cherry-picking changes.

But if you must, I am reminded by @utopik's comment that breeze labs has the getEntityGraph plugin which may make such scenarios considerably easier.

Install the getEntityGraph.js plugin script after breeze itself. Then you should be able to say:

// get flat array of cust and its orders
var graph = manager.getEntityGraph(newCustomer,'Orders'); 
manager.saveChanges(graph);

You do have to state explicitly which navigation paths should be included using the breeze "expand" clause syntax.

This approach will send both changed and unmodified graph entities to the server. You could filter out the unchanged ones:

var changes = manager
    .getEntityGraph(newCustomer,'Orders')
    .filter(function(entity){
        return !entity.entityAspect.entityState.isUnchanged();
    }); 

manager.saveChanges(changes)

getEntityGraph may make it into the core product someday. Until then, there is breeze labs.

Original Answer

Excellent question, BP. Your concern about omitting entities that should be saved is why we discourage calling saveChanges(array-of-entities). The routine, safe thing to do is simply call saveChanges(). This will save every entity with pending changes in a single transaction.

We offer the selective save overload (the one you tried) for the special case in which you need to cherry pick the entities that should be saved. You must be careful when you do this; you don't want to orphan related entities ... such as the new orders that you added to your new customer. It's really easy to make a mistake ... as you rightly point out.

I can see that you want Breeze to infer that it should include the child orders with the parent customer. But you're asking Breeze to guess what you really want to do. If Breeze followed the cookie trail from newCustomer down every branch of every navigation path, who knows what it would save ... or not save? We give you the option to cherry pick; now it's your responsibility to say precisely what you mean.

If you really needed to save the newCustomer and its orders, you could write:

var entitiesToSave = newCustomer.Orders().slice(); // Make sure it's a copy!
entitiesToSave.push(newCustomer); // add the newCustomer too.
manager.saveChanges(entitiesToSave); // save newCustomer and its orders.

But I beg you to avoid this approach. If you find yourself often in this position of needing to save subsets of entities-with-changes, I urge you to re-examine your workflow. Perhaps you need multiple managers ... as described here.