Select path (angular-redux#125)

* Select path

`.select` and `@select` will now accept a property path too.

* Added ability to select array indices

Author: SethDavenport

packages/store/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 3.0.6
+
+### Features
+
+Added a 'path' option to `ngRedux.select()` and `@select()`. Now you can
+do stuff like `@select(['foo', 'bar'])` to select `state.foo.bar` into
+an observable.
+
 # 3.0.0
 
 ### Features

packages/store/README.md

@@ -89,10 +89,15 @@ The `@select` decorator can be added to the property of any class or angular
 component/injectable. It will turn the property into an observable which observes
 the Redux Store value which is selected by the decorator's parameter.
 
-The decorator expects to receive a `string`, a `function` or no parameter at all. 
-
-- If a `string` is passed the `@select` decorator will attempt to observe a store property whose name matches the value represented by the `string`.
-- If a `function` is passed the `@select` decorator will attempt to use that function as a selector on the RxJs observable. 
+The decorator expects to receive a `string`, an array of `string`s, a `function` or no
+parameter at all. 
+
+- If a `string` is passed the `@select` decorator will attempt to observe a store
+property whose name matches the `string`.
+- If an array of strings is passed, the decorator will attempt to match that path
+through the store (similar to `immutableJS`'s `getIn`).
+- If a `function` is passed the `@select` decorator will attempt to use that function
+as a selector on the RxJs observable. 
 - If nothing is passed then the `@select` decorator will attempt to use the name of the class property to find a matching value in the Redux store. Note that a utility is in place here where any $ characters will be ignored from the class property's name.
 
 ```typescript
@@ -124,6 +129,10 @@ export class CounterValue {
     // this selects `counter` from the store and attaches it to this property
     @select('counter') counterSelectedWithString;
 
+    // this selects `pathDemo.foo.bar` from the store and attaches it to this
+    // property.
+    @select(['pathDemo', 'foo', 'bar']) pathSelection;
+
     // this selects `counter` from the store and attaches it to this property
     @select(state => state.counter) counterSelectedWithFunction;
 
@@ -473,7 +482,7 @@ this.counterSubscription = this.ngRedux
 this.counter$ = this.ngRedux.select('counter');  
 ```
 
-### @select(key | function)
+### @select(key | path | function)
 
 Property decorator.
 
@@ -482,6 +491,7 @@ Attaches an observable to the property which will reflect the latest value in th
 __Arguments:__
 
 * `key` \(*string*): A key within the state that you want to subscribe to.
+* `path` \(*string[]*): A path of nested keys within the state you want to subscribe to.
 * `selector` \(*Function*): A function that accepts the application state, and returns the slice you want to subscribe to for changes.
 
 e.g. see [the @select decorator](#the-select-decorator)

packages/store/examples/counter/components/Counter.ts

@@ -14,11 +14,18 @@ import { RandomNumberService } from '../services/random-number';
     <button (click)="actions.incrementIfOdd()">Increment if odd</button>
     <button (click)="actions.incrementAsync(2222)">Increment async</button>
     <button (click)="actions.randomize()">Set to random number</button>
+
+    <br>
+    foo$: {{ foo$ | async | json }}
+    <br>
+    bar$: {{ bar$ | async}}
   </p>
   `
 })
 export class Counter {
   @select('counter') counter$: any;
+  @select([ 'pathDemo', 'foo' ]) foo$;
+  @select([ 'pathDemo', 'foo', 'bar', 0 ]) bar$: number;
 
   constructor(private actions: CounterActions) {}
 }

packages/store/examples/counter/containers/App.ts

@@ -1,6 +1,6 @@
 import { Component } from '@angular/core';
 import { AsyncPipe } from '@angular/common';
-import { NgRedux, select } from 'ng2-redux';
+import { NgRedux } from 'ng2-redux';
 
 import { Counter } from '../components/Counter';
 import { CounterInfo } from '../components/CounterInfo';
@@ -25,7 +25,7 @@ export class App {
         // Do this once in the top-level app component.
         this.ngRedux.configureStore(
             reducer,
-            { counter: 0 },
+            {},
             [ createLogger() ],
             enhancers
         );

packages/store/examples/counter/reducers/index.ts

@@ -2,9 +2,11 @@ import * as Redux from 'redux';
 const { combineReducers } = Redux;
 import { RootState } from '../store';
 import counter from './counter';
+import pathDemo from './path-demo';
 
 const rootReducer = combineReducers<RootState>({
-  counter
+  counter,
+  pathDemo
 });
 
 export default rootReducer;

packages/store/examples/counter/reducers/path-demo.ts

@@ -0,0 +1,16 @@
+import { CounterActions } from '../actions/counter-actions';
+
+export default (state: any = {
+  foo: {
+    bar: [ 0 ]
+  }
+}, action:any) => {
+  switch (action.type) {
+    case CounterActions.INCREMENT_COUNTER:
+      return { foo: { bar: [ state.foo.bar[0] + 1 ] } };
+    case CounterActions.DECREMENT_COUNTER:
+      return { foo: { bar: [ state.foo.bar[0] - 1 ] } };
+    default:
+      return state;
+  }
+}

packages/store/examples/counter/store/index.ts

@@ -10,4 +10,5 @@ if (window.devToolsExtension) {
 
 export interface RootState {
   counter: number;
+  pathDemo: Object;
 }

packages/store/src/___tests___/utils/get-in.spec.ts

@@ -0,0 +1,95 @@
+import { getIn } from '../../utils/get-in';
+import { expect } from 'chai';
+
+describe('getIn', () => {
+
+  it('should select a first-level prop', () => {
+    const test = { foo: 1 };
+    expect(getIn(test, [ 'foo' ])).to.equal(1);
+  });
+
+  it('should select a second-level prop', () => {
+    const test = { foo: { bar: 2 } };
+    expect(getIn(test, [ 'foo', 'bar' ])).to.equal(2);
+  });
+
+  it('should select a third-level prop', () => {
+    const test = { foo: { bar: { quux: 3 } } };
+    expect(getIn(test, [ 'foo', 'bar', 'quux' ])).to.equal(3);
+  });
+
+  it('should select falsy values properly', () => {
+    const test = {
+      a: false,
+      b: 0,
+      c: '',
+      d: undefined
+    };
+    expect(getIn(test, [ 'a' ])).to.equal(false);
+    expect(getIn(test, [ 'b' ])).to.equal(0);
+    expect(getIn(test, [ 'c' ])).to.equal('');
+    expect(getIn(test, [ 'd' ])).to.equal(undefined);
+  });
+
+  it('should select nested falsy values properly', () => {
+    const test = {
+      foo: {
+        a: false,
+        b: 0,
+        c: '',
+        d: undefined
+      }
+    };
+    expect(getIn(test, [ 'foo', 'a' ])).to.equal(false);
+    expect(getIn(test, [ 'foo', 'b' ])).to.equal(0);
+    expect(getIn(test, [ 'foo', 'c' ])).to.equal('');
+    expect(getIn(test, [ 'foo', 'd' ])).to.equal(undefined);
+  });
+
+  it('should not freak if the object is null', () => {
+    expect(getIn(null, [ 'foo', 'd' ])).to.equal(null);
+  });
+
+  it('should not freak if the object is undefined', () => {
+    expect(getIn(undefined, [ 'foo', 'd' ])).to.equal(undefined);
+  });
+
+  it('should not freak if the object is a primitive', () => {
+    expect(getIn(42, [ 'foo', 'd' ])).to.equal(undefined);
+  });
+
+  it('should return undefined for a nonexistent prop', () => {
+    const test = { foo: 1 };
+    expect(getIn(test, [ 'bar' ])).to.be.undefined;
+  });
+
+  it('should return undefined for a nonexistent path', () => {
+    const test = { foo: 1 };
+    expect(getIn(test, [ 'bar', 'quux' ])).to.be.undefined;
+  });
+
+  it('should return undefined for a nested nonexistent prop', () => {
+    const test = { foo: 1 };
+    expect(getIn(test, [ 'foo', 'bar' ])).to.be.undefined;
+  });
+
+  it('should select array elements properly', () => {
+    const test = [ 'foo', 'bar' ];
+    expect(getIn(test, [0])).to.equal('foo');
+    expect(getIn(test, ['0'])).to.equal('foo');
+    expect(getIn(test, [1])).to.equal('bar');
+    expect(getIn(test, ['1'])).to.equal('bar');
+    expect(getIn(test, [2])).to.be.undefined;
+    expect(getIn(test, ['2'])).to.be.undefined;
+  });
+
+  it('should select nested array elements properly', () => {
+    const test = { 'quux': [ 'foo', 'bar' ] };
+    expect(getIn(test, ['quux', 0])).to.equal('foo');
+    expect(getIn(test, ['quux', '0'])).to.equal('foo');
+    expect(getIn(test, ['quux', 1])).to.equal('bar');
+    expect(getIn(test, ['quux', '1'])).to.equal('bar');
+    expect(getIn(test, ['quux', 2])).to.be.undefined;
+    expect(getIn(test, ['quux', '2'])).to.be.undefined;
+  });
+});

packages/store/src/components/ng-redux.ts

@@ -19,11 +19,13 @@ import wrapActionCreators from '../utils/wrapActionCreators';
 import { isObject, isFunction, isPlainObject} from '../utils/type-checks';
 import { omit } from '../utils/omit';
 import { invariant } from '../utils/invariant';
+import { getIn } from '../utils/get-in';
 
-const VALID_SELECTORS = ['string', 'number', 'symbol', 'function'];
+const VALID_SELECTORS = ['string', 'string[]', 'number', 'symbol', 'function'];
 const ERROR_MESSAGE = `Expected selector to be one of:
     ${VALID_SELECTORS.join(',')}. Instead recieved %s`;
-const checkSelector = (s) => VALID_SELECTORS.indexOf(typeof s, 0) >= 0;
+const checkSelector = (s) => VALID_SELECTORS.indexOf(typeof s, 0) >= 0 ||
+    Array.isArray(s);
 
 @Injectable()
 export class NgRedux<RootState> {
@@ -114,7 +116,11 @@ export class NgRedux<RootState> {
      * source Observable with distinct values.
      */
     select<S>(
-        selector: string | number | symbol | ((state: RootState) => S),
+        selector: string |
+            number |
+            symbol |
+            (string | number)[] |
+            ((s: RootState) => S),
         comparer?: (x: any, y: any) => boolean): Observable<S> {
 
         invariant(checkSelector(selector), ERROR_MESSAGE, selector);
@@ -126,6 +132,10 @@ export class NgRedux<RootState> {
             return this._store$
                 .map(state => state[selector])
                 .distinctUntilChanged(comparer);
+        } else if (Array.isArray(selector)) {
+            return this._store$
+                .map(state => getIn(state, selector))
+                .distinctUntilChanged(comparer);
         } else if (typeof selector === 'function') {
             return this._store$
                 .map(selector).distinctUntilChanged(comparer);

packages/store/src/decorators/select.ts

@@ -4,26 +4,28 @@ import { NgRedux } from '../components/ng-redux';
  * Selects an observable from the store, and attaches it to the decorated 
  * property.
  *
- * @param {string | function} stateKeyOrFunc
+ * @param {string | string[] | function} statePathOrFunc 
+ * An Rxjs selector function, property name string, or property name path
+ * (array of strings/array indices) that locates the store data to be 
+ * selected
+ *
  * @param {function} comparer function for this selector
- * An Rxjs selector function or a string indicating the name of the store
- * property to be selected.
- * */
+ */
 export const select = <T>(
-    stateKeyOrFunc?,
+    statePathOrFunc?: string |
+        (string | number)[] |
+        Function,
     comparer?: (x: any, y: any) => boolean) => (target, key) => {
 
-    let bindingKey = (key.lastIndexOf('$') === key.length - 1) ?
-        key.substring(0, key.length - 1) : key;
-
-    if (typeof stateKeyOrFunc === 'string') {
-        bindingKey = stateKeyOrFunc;
+    let bindingKey = statePathOrFunc;
+    if (!statePathOrFunc) {
+        bindingKey = (key.lastIndexOf('$') === key.length - 1) ?
+            key.substring(0, key.length - 1) :
+            key;
     }
-
+    
     function getter() {
-      const isFunction = typeof stateKeyOrFunc === 'function';
-        return NgRedux.instance
-            .select(isFunction ? stateKeyOrFunc : bindingKey, comparer);
+        return NgRedux.instance.select(bindingKey, comparer);
     }
 
     // Delete property.

packages/store/src/utils/get-in.ts

@@ -0,0 +1,22 @@
+/*
+ * Gets a deeply-nested property value from an object, given a 'path'
+ * of property names or array indices.
+ */
+export function getIn(
+  v: Object,
+  pathElems: (string | number)[]): any {
+    const [ firstElem, ...restElems] = pathElems;
+    if (!v) {
+      return v;
+    }
+
+    if (undefined === v[firstElem]) {
+      return undefined;
+    }
+
+    if (restElems.length === 0) {
+        return v[firstElem];
+    }
+
+    return getIn(v[firstElem], restElems);
+}