support named states, and only storing / restoring certain attributes

[mxriverlynn]

add support for named states, or named stacks of states. from Dan Switzer via the Backbone mailing list:

---

For me, I think the best way for it to work would be this:

store([cid]) - always returns the cid. If no cid is provided as an
argument, one is created.

restore([cid]) - If no cid is supplied, restores previous state. If a
cid is specified, rolls all the back to the named state.

This would allow you to do:

1. Rollback to any given point and time:
   transactionId = this.store(); // this returns transactionId
   this.restore(transactionId);

2. Rollback to a specific point in time:
   this.store("init");
   this.restore("init");

NOTE: It might be handy to be able to have multiple transaction points
with the same name, that way you could easily create "undo" points. So,
calling this.restore("undo") would rollback to the first named "undo"
transaction. Calling this.restore("undo") would rollback to the next,
etc. That might be pretty powerful.

3. Rollback just like you do now:
   this.store();
   this.restore();

The reason named transaction are important for me, is I have some code
currently in production that can make a series of triggered model
changes. This code currently isn't using backbone and one of the
problems I'm facing is a proper "undo". The problem is the sequence of
triggered events might make multiple "undo" points, so I need to be able
to roll back to the correct undo point.

[mxriverlynn]

I've been thinking about this a bit and there's a few issues with the suggestions, but they are easily corrected.

Specifically, if we're returning some form of token to identify a serialized state, then we need to ensure that we always have that token's state around. this would likely mean that we need to store the serialized states not only in the stack that let's us push / pop in order, but also in an arbitrarily accessible object that lets us use a key / value pair.

While this isn't technically difficult, i wonder about potential issues with the 'restart' method as an example. what happens if we 'restart' a model and rewind it all the way back to the first state? should we keep the tokenized states around, and only rewind the stack? or ??? what happens if you only needed 1 or 2 of states out of 15 or 20 that have been stored, to be retrievable via some token or name? why should we keep a copy around for everything, if you only need one or two?

I'm wondering: should the code return the serialized state of the object instead of a token?

Look at this example:

var token = myModel.store();

Do you know or care whether or not token really is a token, or is the full serialized state of the model? I don't ... and I think this will simplify things quite a bit. by returning the state from the store method, you can keep as many of them around forever, as you want. then when you're ready to restore to a given state, you should be able to pass the current state back in to your model. soemthing like this maybe:

var myState = myModel.store();

myModel.restore({
  state: myState
});

This would restore the model to that state.

The big question, then, is what do we do with the stack of stored states that were used in the push / pop scenario? do we wipe out the stack? do we try to find the state in the stack and move the currently state to that? or ???

My initial thought is that we try to find the state in the stack, and reset the stack to that state, if we found it. If we didn't find it, we wipe the stack out and re-start it.

/cc @dswitzer

[dswitzer]

@derickbailey:

Sorry for the delay in responding, but I had to wait until I had time to read it and digest it.

I think you're right in that we can probably just return an object representing the state of the object. I my original stream of thought proposal, I was just modelling things off of setTimeout/clearTimeout and thought a text string would work well.

I like the idea that with an object, we could ensure we return to a state even if it's no longer in the stack.

However, I would make a few changes, which I think could help to solve some of your issues. I'd have the store() method return a custom object that could be passed directly to the restore() method:

var myState = myModel.store();

myModel.restore(myState);

The reason I'd do this, is then maybe we can pass other options to the "store" method which are stored with the serialized state. So, the "myState" object might look like:

{
  // the id of the state--for easy searching of the stack
  id: 0 // this would be a unique number for easy referencing stored states
  // this would be the data memento
  , state: {} 
  // indicate whether or not to attempt to rollback to the object (if set to false, a new restore point is pushed to the stack)
  , rollback: true/false // defaults to true
  // indicate if the stack should be completely purged
  , flush: true/false // defaults to false
}

If we pass back an object with some rules, it would allow you to do things like:

var init = myModel.store({rollback: false});

// restore model, but rollback stack would be preserved and a new point created
// this would allow you to "undo" the restore to the stored state
myModel.restore(init);

// restores state, but overwrites the stored rollback state and rolls back the stack
myModel.restore(init, {rollback: true});

// restores model, but flush the stack so it's clear
myModel.restore(init, {flush: true});

By storing an "id" referencing the state in the stack, it should give you an easy way to find if the state still existing in the stack. If it doesn't, you'd treat it like rollback was false (meaning a new state would be stored.) If someone wanted to ensure the stack was flushed, they could just specify the flush option.

I kind of like the idea of being able to specify whether or not to rollback the stack on a restore. I could see where maybe you'd have some situations where you might want to allow undo'ing a restore(). For example, let's say you wired up a "reset" method on a form, you might want users to be able to undo that.

What do you think of that?