add keepState option to .restore()

backbone.memento.js

@@ -31,7 +31,12 @@ Backbone.Memento = (function(Backbone, _){
     };
 
     this.restore = function(restoreConfig){
-      var previousState = mementoStack.pop();
+      var previousState;
+      if (restoreConfig.keepState) {
+        previousState = _.last(mementoStack);
+      } else {
+        previousState = mementoStack.pop();
+      }
       restoreState(previousState, restoreConfig);
     };
 
@@ -124,7 +129,7 @@ Backbone.Memento = (function(Backbone, _){
       restoreConfig = _.extend({}, config, restoreConfig);
       restoreState(previousState, restoreConfig);
     }
-      
+
   };
 
   // ----------------------------
@@ -140,7 +145,7 @@ Backbone.Memento = (function(Backbone, _){
     this.push = function(attrs){
       attributeStack.push(attrs);
     }
-    
+
     this.pop = function(restoreConfig){
       var oldAttrs = attributeStack.pop();
       return oldAttrs;

readme.md

@@ -12,7 +12,7 @@ any round trips.
 
 ## Getting Started
 
-It's easy to get up and running. You only need to have Backbone (including underscore.js - 
+It's easy to get up and running. You only need to have Backbone (including underscore.js -
 a requirement for Backbone) in your page before including the backbone.memento
 plugin.
 
@@ -26,7 +26,7 @@ Namely, it uses the `set` and `unset` methods of models and `reset` and `remove`
 
 ### Get The Memento Plugin
 
-Download the `backbone.memento.js` file from this github repository and copy it into 
+Download the `backbone.memento.js` file from this github repository and copy it into
 your javascripts folder. Add the needed `<script>` tag to bring the plugin into any page
 that wishes to use it. Be sure to include the modelbinding file _after_ the backbone.js file.
 
@@ -52,8 +52,8 @@ SomeModel = Backbone.Model.extend({
 
 #### Cherry-Picking Methods
 
-You can also configure a model by instantiating the memento with your model's 
-initializer and then providing access to the methods as needed, or by using the 
+You can also configure a model by instantiating the memento with your model's
+initializer and then providing access to the methods as needed, or by using the
 methods internally.
 
 ``` javascript
@@ -102,25 +102,27 @@ someCollection.restore();
 someCollection.at(0).get("something"); //=> "whatever"
 ```
 
-### 
+###
 
 ## Memento Methods
 
 There are several methods provided by Backbone.Memento, to allow you more control over
-how the memento object works, and when. 
+how the memento object works, and when.
 
 ### memento.store
 
 This method creates a copy of your structure's current state, as a memento, and stores it in
-a stack (first in, last out). 
+a stack (first in, last out).
 
 ### memento.restore
 
 This method takes the previously stored state, and restores your structure to this state. You
-can call this as many times as you have called `store`. Calling this method more times 
+can call this as many times as you have called `store`. Calling this method more times
 than you have called store will result in a no-operation and your structure will not be
 changed.
 
+Optionally, you can pass the `{ keepState: true }` option to the `restore` call to keep the previous state in the stack. You can call `restore({ keepState: true })` as many times as you want and the model will always be restored to the point where your last `store` is called.
+
 ### memento.restart (formerly reset)
 
 This method effectively rolls your structure back to the first store point, no matter how
@@ -192,7 +194,7 @@ ignore list.
 
 With this in place, you can push your model's state onto the memento stack by calling
 `store`, and pop the previously stored state back into the model (destroying the current
-state in the process) by calling `restore`. 
+state in the process) by calling `restore`.
 
 ``` javascript
 myModel = new SomeModel();

spec/javascripts/memento.spec.js

@@ -40,6 +40,21 @@ describe("memento", function(){
     });
   });
 
+  describe("when restoring with keepState option", function(){
+    beforeEach(function(){
+      this.model.set({foo: "first"});
+      this.model.store();
+      this.model.set({foo: "second"});
+      this.model.store();
+    });
+
+    it("should always restore to the state at the last .store call", function(){
+      this.model.restore({ keepState: true });
+      this.model.restore({ keepState: true });
+      expect(this.model.get("foo")).toBe("second");
+    });
+  });
+
   describe("when mementoing twice and rolling back once", function(){
     beforeEach(function(){
       this.model.set({foo: "bar"});
@@ -76,5 +91,5 @@ describe("memento", function(){
       expect(changed).toBeTruthy();
     });
   });
-  
+
 });