Merge pull request #3 from vpaschenkov/master

#1 :: Add docs and examples

README.md

@@ -5,5 +5,56 @@ RemoteData is an ADT (algebraic data type) described in [this article](https://m
 ### Installation
 `npm i --save @devexperts/remote-data-ts` 
 
+### How to lift (wrap) your data in RemoteData:
+As you remember RemoteData is an union of few types: `RemoteInitial`, `RemotePending`, `RemoteFailure` and `RemoteSuccess`.
+
+While your data in **initial** or **pending** state just use `initial` or `pending` constant, because you don't have any **real** values in this case.
+
+```
+import { initial, pending } from 'remote-data-ts';
+ 
+const customers = initial;
+// or
+const customers = pending;
+```
+
+When you receive data from server, use `failure` or `success` function, it depends on what you received:
+```
+import { failure, success } from 'remote-data-ts';
+import { apiClient } from 'apiClient'; 
+import { TCustomer } from './MyModel';
+ 
+const getCustomers = (): RemoteData<TCustomer[]> => {
+   const rawData: TCustomer[] = apiClient.get('/customers');
+   
+   try {
+        const length = rawData.length;
+
+        return success(rawData);
+   }
+   catch(err) {
+        return failure(new Error('parse error'));
+   }
+}
+``` 
+
+### How to fold (unwrap) your data from RemoteData:
+Finally you pass data to the component and want to render values, so now it's time to get our values back from RemoteData wrapper:
+```
+import { NoData, Pending, Failure } from './MyPlaceholders';
+import { TCustomer } from './MyModel';
+ 
+type TCustomersList = {
+    entities: RemoteData<TCustomer[]>;
+};
+ 
+const CustomersList: SFC<TCustomersList> = ({ entities }) => entities.fold(
+    () => <NoData />,
+    () => <Pending />,
+    err => <Failure error={err} />,
+    data => <ul>{data.map(item => <li>{item.name}</li>)}</ul>),
+)
+``` 
+
 ### Docs & Examples
 Coming soon (check the [source](src/remote-data.ts))