Merge pull request #5 from tguzik/master

Export the newestSpace function

README.md

@@ -368,7 +368,7 @@ Parameter: A space
 
 Returns: The root space associated with the given space.
 
-**Note**: Returns the latest root space of the passed in space. This means you can safely do `rootOf(space)` anywhere in a custom action, and always get the latest version.
+**Note**: This function goes all the way up in the chain of parent spaces, returning the latest root space of the parameter. This means you can safely do `rootOf(space)` anywhere in a custom action, and always get the latest version.
 
 ```js
 import { createSpace, rootOf } from 'spaceace';
@@ -383,6 +383,22 @@ space.user(({ merge, space }, name) => {
 })('Sam');
 ```
 
+### newestSpace
+
+Parameter: A space
+
+Returns: The newest copy of the space, at the same level.
+
+```js
+import { createSpace, newestSpace } from 'spaceace';
+
+const space = createSpace({ user: { name: 'Frodo' } });
+const latestSnapshot = space.user({ name: 'Sam' });
+
+latestSnapshot.name === 'Sam'; // true
+newestSpace(space.user).name === 'Sam'; // true
+```
+
 ## toJSON
 
 Returns: The contents of a space as an object literal.

lib/Space.d.ts

@@ -46,6 +46,7 @@ interface Subscriber {
 }
 
 export function rootOf(space: Space): Space;
+export function newestSpace(space: Space): Space;
 export function isSpace(space: Space | any): boolean;
 export function subscribe(subscriber: Subscriber): boolean;
 export function createSpace(initialState: object): Space;

lib/Space.js

@@ -262,6 +262,7 @@
   Space.isSpace = isSpace;
   Space.rootOf = rootOf;
   Space.createSpace = createSpace;
+  Space.newestSpace = newestSpace;
 
   /* Instance methods */
 

test/main.js

@@ -2,7 +2,13 @@
 'use strict';
 
 const assert = require('assert');
-const { createSpace, subscribe, isSpace, rootOf } = require('../lib/Space');
+const {
+  createSpace,
+  subscribe,
+  isSpace,
+  rootOf,
+  newestSpace,
+} = require('../lib/Space');
 
 describe('Space', function() {
   beforeEach(function() {
@@ -109,13 +115,35 @@ describe('Space', function() {
         assert.strictEqual(rootOf(this.space.characters[0]), this.space);
       });
 
+      it('goes all the way up the chain of parent spaces', function() {
+        assert.strictEqual(rootOf(this.space.userInfo.location), this.space);
+      });
+
+      it('returns the newest copy of the root space', function() {
+        this.space.userInfo.location({ city: 'San Diego' });
+        assert.strictEqual(rootOf(this.space.userInfo.location), this.newSpace);
+      });
+
       it('throws when given non-space', function() {
         assert.throws(() => {
           rootOf({});
         });
       });
     });
 
+    describe('.newestSpace', function() {
+      it('returns the same object if no updates were made', function() {
+        const capture = this.space.userInfo;
+        assert.strictEqual(newestSpace(capture), capture);
+      });
+
+      it('returns newest copy of current space', function() {
+        const capture = this.space.userInfo.location;
+        const newerSpace = capture({ city: 'San Diego' });
+        assert.strictEqual(newestSpace(capture), newerSpace);
+      });
+    });
+
     describe('.toJSON', function() {
       it('works', function() {
         assert.deepEqual(this.space.toJSON(), this.initialState);