fromNullable, documentation

README.md

@@ -19,8 +19,12 @@ as a guide, making sure your own implementation behaves as expected.
 - [Container types](#container-types)
     - [Box](#box)
     - [LazyBox](#lazybox)
+    - [Right](#right)
+    - [Left](#left)
     - [Either](#either)
+    - [fromNullable](#fromnullable)
 - [Functionality](#functionality)
+    - [range](#range)
 
 ## Function composition
 - [composeRight](#composeright)
@@ -44,7 +48,10 @@ Composes multiple functions from left to right into one new function. This new f
 ## Container types
 - [Box](#box)
 - [LazyBox](#lazybox)
+- [Right](#right)
+- [Left](#left)
 - [Either](#either)
+- [fromNullable](#fromnullable)
 
 ### Box
 A Box takes a value and boxes it up. On the box you'll be able to use a minimal, Box-specific API 
@@ -85,20 +92,47 @@ const LazyBox = g => ({
 });
 ```
 
-### Either
-Branches your code to either a Right or a Left based on the value it was given. If the value is 
-truthy it will branch to a Right, otherwise it will branch to a Left. 
+### Right
+Right is like a Box. The map method on Right does the same as the one in Box. 
+Fold takes two functions, an error-handler and a success-handler. It applies the success-handler 
+to the contained value.
+```javascript
+const Right = value => ({
+  map: func => Right(func(value)),
+  fold: (errorhandler, successhandler) => successhandler(value),
+  inspect: () => `Right(${value})`
+});
+```
 
-The map method on Right does the same as the one in Box. Fold takes two functions, an error-handler 
-and a success-handler. It applies the success-handler to the contained value.
+### Left
+Left is like a Box, it has a map, fold and inspect method. The map method on Left does not apply 
+the function to the contained value. Fold takes two functions, an error-handler and a success-handler. 
+It applies the error-handler to the contained value.
 
-Mapping over a Left returns the value in a new Left without applying the function to the value.
-Folding a Left also takes an error-handler and a success-handler but applies the error-handler to the underlying value.
+```javascript
+const Left = value => ({
+  map: func => Left(value),
+  fold: (errorhandler, successhandler) => errorhandler(value),
+  inspect: () => `Left(${value})`
+});
+```
+
+### Either
+Branches your code to a Right or a Left based on the value it was given. If the value is 
+truthy it will branch to a Right, otherwise it will branch to a Left.
 
 ```javascript
 const Either = value => value ? Right(value) : Left(value);
 ```
 
+### fromNullable
+Branches your code to a Right or a Left based on the value it was given. If the value is 
+null or undefined it will branch to a Left passing in null, otherwise it will branch to a Right. 
+
+```javascript
+const fromNullable = (value) => value == null ? Left(null) : Right(value);
+```
+
 ## Functionality
 - [range](#range)
 

dist/cjs/subterfuge.js

@@ -1,4 +1,4 @@
-/*  Subterfuge v0.7.1
+/*  Subterfuge v0.8.0
  *  https://github.com/phixid/subterfuge
  *  (c) 2017-2017 Kristof Hermans <@phixid>
  *  Subterfuge may be freely distributed under the MIT license.
@@ -74,6 +74,8 @@ const Right = value => ({
 
 const Either = value => (value ? Right(value) : Left(value));
 
+const fromNullable = value => (value == null ? Left(null) : Right(value));
+
 // prettier-ignore
 
 /**
@@ -105,6 +107,7 @@ exports.composeRight = composeRight;
 exports.pipeLeft = pipeLeft;
 exports.pipeRight = pipeRight;
 exports.Either = Either;
+exports.fromNullable = fromNullable;
 exports.Left = Left;
 exports.Right = Right;
 exports.range = range;

dist/es/subterfuge.js

@@ -1,4 +1,4 @@
-/*  Subterfuge v0.7.1
+/*  Subterfuge v0.8.0
  *  https://github.com/phixid/subterfuge
  *  (c) 2017-2017 Kristof Hermans <@phixid>
  *  Subterfuge may be freely distributed under the MIT license.
@@ -70,6 +70,8 @@ const Right = value => ({
 
 const Either = value => (value ? Right(value) : Left(value));
 
+const fromNullable = value => (value == null ? Left(null) : Right(value));
+
 // prettier-ignore
 
 /**
@@ -94,4 +96,4 @@ const range = (start, end = 0) => Array
 				: index
 		);
 
-export { Box, LazyBox, composeLeft, composeRight, pipeLeft, pipeRight, Either, Left, Right, range };
+export { Box, LazyBox, composeLeft, composeRight, pipeLeft, pipeRight, Either, fromNullable, Left, Right, range };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "subterfuge",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Simple functional Javascript",
   "keywords": ["functional", "javascript"],
   "author": "Kristof Hermans <@phixid>",

src/containers/either.js → src/containers/code-branching.js

@@ -11,3 +11,5 @@ export const Right = value => ({
 });
 
 export const Either = value => (value ? Right(value) : Left(value));
+
+export const fromNullable = value => (value == null ? Left(null) : Right(value));

src/containers/either.spec.js → src/containers/code-branching.spec.js

@@ -1,4 +1,4 @@
-import { Either, Left, Right } from './either';
+import { Either, fromNullable, Left, Right } from './code-branching';
 import { isFunction, resemblesBox } from '../../__tests__/testUtilities';
 import { addOne, randomNumberBetween1And10 } from '../../__tests__/utilities';
 
@@ -161,3 +161,22 @@ describe('Either container type: code branching', () => {
     });
   });
 });
+
+describe('fromNullable', () => {
+  it('is a function', () => {
+    isFunction(fromNullable);
+  });
+
+  it('takes one parameter', () => {
+    expect(fromNullable.length).toEqual(1);
+  });
+
+  it('returns a Left containing null when the parameter is null or undefined', () => {
+    expect(fromNullable(null).inspect()).toEqual('Left(null)');
+    expect(fromNullable(undefined).inspect()).toEqual('Left(null)');
+  });
+
+  it('returns a Right containing the passed value when not null or undefined', () => {
+    expect(fromNullable(5).inspect()).toEqual('Right(5)');
+  });
+});

src/index.js

@@ -2,5 +2,5 @@ export { Box } from './containers/box';
 export { LazyBox } from './containers/lazybox';
 export { composeLeft, composeRight } from './composition/compose';
 export { pipeLeft, pipeRight } from './composition/pipe';
-export { Either, Left, Right } from './containers/either';
+export { Either, fromNullable, Left, Right } from './containers/code-branching';
 export { range } from './functions/range';