Update api and introduction docs

docs/api/README.md

@@ -54,7 +54,8 @@ of data in redux state. This section documents the complete redux-io API.
 
 ### Importing
 
-Every function described above is a top-level export, except `rio` that has default export. You can import any of them like this:
+Every function described above is a top-level export, except `rio` that has default export. You can import any of them
+like this:
 
 #### ES6
 

docs/api/collection.md

@@ -0,0 +1,47 @@
+### `collection(schema, tag = '', settings = {}, initialState = [])`
+Collection is generic reducer that enables creating typed and named collection reducers that are handling
+`REFERENCE_*` type actions with defined `schema` and `tag`. Reducer holds array of object `ids`, where
+index defines order of objects. Every collection is defined with `schema` and `tag`. Use it for normalized state
+to keep references to object instances (for which you use [storage](collection.md) reducer). With `tag` you can define
+multiple and various references on same data schema.
+
+```javascript
+pinnedTodos: [3, 1],
+allTodos: [1, 2, 3, 4, 5, ...],
+users: [ 1002, 1005],
+...
+```
+
+###### Arguments
+`schema` (String): Type of data that is stored in the map. Based on schema and tag `collection` will be held responsible
+for handling dispatched actions from `redux-io`.
+
+`tag` (String): Defines along `schema` reducer's responsibility to process `redux-io` actiona. Tag enable to have
+multiple collections for same schema. It's important if you want to have normalized state and instances in one place,
+but different collections of data. By default it's empty string `''` and mostly use in cases when we want to hold all
+keys of object in state.
+
+`settings` (Object): optional status data used to define behaviour of reducer.
+``` { expirationTime: seconds } ```
+
+`initialState` (Object): If you are passing custom initial state, you should create an array with object `id`.
+
+###### Returns
+(*Function*): A reducer that invokes on action with equal `schema` and `tag`.
+
+###### Example
+
+```javascript
+import { combineReducers } from 'redux';
+import { collection } from '@shoutem/redux-io';
+
+const todoSchema = 'data.todos'
+const userSchema = 'data.users'
+
+export default combineReducers({
+  pinnedTodos: collection(todoSchema, 'pinned');
+  allTodos: collection(todoSchema);
+  users: collection(userSchema);
+});
+
+```

docs/api/one.md

@@ -0,0 +1,45 @@
+### `one(schema, tag = '', settings = {}, initialValue = '')`
+One is generic reducer that enables creating typed and named one reducers that are handling
+`REFERENCE_*` type actions with defined `schema` and `tag`. Reducer holds single value referencing single object in state.
+One is defined with `schema` and `tag`. Use it for normalized state to keep single reference to object instance
+(for which you use [storage](collection.md) reducer). With `tag` you can define multiple and various references on same
+data schema.
+
+```javascript
+selectedTodo: "1",
+activeUser: "1002",
+...
+```
+
+###### Arguments
+`schema` (String): Type of data that is stored in the map. Based on schema and tag `one` will be held responsible
+for handling dispatched actions from `redux-io`.
+
+`tag` (String): Defines along `schema` reducer's responsibility to process `redux-io` actiona. Tag enable to have
+multiple collections for same schema. It's important if you want to have normalized state and instances in one place,
+but different collections of data. By default it's empty string `''` and mostly use in cases when we want to hold all
+keys of object in state.
+
+`settings` (Object): optional status data used to define behaviour of reducer.
+``` { expirationTime: seconds } ```
+
+`initialValue` (String|Number|Object): Reference to single object in state. Corresponds to object `id`.
+
+###### Returns
+(*Function*): A reducer that invokes on action with equal `schema` and `tag`.
+
+###### Example
+
+```javascript
+import { combineReducers } from 'redux';
+import { one } from '@shoutem/redux-io';
+
+const todoSchema = 'data.todos'
+const userSchema = 'data.users'
+
+export default combineReducers({
+  selectedTodo: one(todoSchema, 'selected');
+  activeUser: one(userSchema, 'active');  
+});
+
+```

docs/api/storage.md

@@ -1,14 +1,33 @@
 ### `storage(schema, initialState={})`
-Storage is generic storage reducer that enables the creation of typed storage reducers that are handling specific
-OBJECT_ type actions. Holds map of objects, where `key` is object id and `value` instance of an object. You should hold
-all objects of one schema in one storage. On fetch and create storage will always merge new object into existing map,
-overwriting possible existing object.
+Storage is generic storage reducer that enables creation of typed storage reducers that are handling specific
+`OBJECT_*` type actions. It holds map of objects, where `key` is object id and `value` instance of an object. You should
+hold all objects of one `schema` in one storage. On `find` and `create` actions storage will always merge new object into
+existing map, overwriting possible existing object.
+
+```javascript
+todos : {
+  1: {
+    id: 1,
+    type: "data.todos",
+    title: "Buy new shoes",
+    author:"1003"
+  },
+  2: {
+    id: 2,
+    type: "data.todos",
+    title: "Run 5K",
+    author:"1004"
+  },
+  3: { ... },
+  ...
+}
+```
 
 ###### Arguments
 `schema` (String): Type of data that is stored in the map. Based on schema `storage` will be held responsible for
-handling dispatched actions from `redux-api-state`.
+handling dispatched actions from `redux-io`.
 
-`initialState` (Object): If you are passing custom initial state, you should create a map where `key` is object id
+`initialState` (Object): If you are passing custom initial state, you should create a map where `key` is object `id`
 and `value` instance of an object.
 
 ###### Returns

docs/recipes/README.md

@@ -0,0 +1,9 @@
+# Receipes
+
+This topics cover most use cases during development of apps.
+
+* normalized data
+* usage of selectors
+* organizing state
+...
+

src/reducers/collection.js

@@ -101,7 +101,7 @@ export default function collection(schema, tag = '', settings = {}, initialState
   }
   // eslint-disable-next-line no-param-reassign
   setStatus(initialState, createDefaultStatus(schema, tag, settings));
-  // TODO-vedran: refactor status into context={status, config}
+  // TODO: refactor status into context={status, config}
   return (state = initialState, action) => {
     if (!isValidAction(action, schema, tag)) {
       return state;