Merge pull request #17 from ladda-js/next

Ladda - Next release

README.md

@@ -1,7 +1,7 @@
 ![Ladda](https://smallimprovementstech.files.wordpress.com/2017/03/laddalogo-horiz-color-21.png)
 
-![Build status](https://api.travis-ci.org/petercrona/ladda.svg?branch=master)
-[![Coverage Status](https://coveralls.io/repos/github/petercrona/ladda/badge.svg?branch=master&cache=1)](https://coveralls.io/github/petercrona/ladda?branch=master)
+![Build status](https://api.travis-ci.org/ladda-js/ladda.svg?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/ladda-js/ladda/badge.svg?branch=master&cache=1)](https://coveralls.io/github/ladda-cache/ladda?branch=master)
 
 Ladda is a library that helps you with caching, invalidation of caches and to handle different representations of the same data in a **performant** and **memory efficient** way. It is written in **JavaScript** (ES2015) and designed to be used by **single-page applications**. It is framework agnostic, so it works equally well with React, Vue, Angular or just vanilla JavaScript.
 

docs/README.md

@@ -12,7 +12,11 @@
 * [Advanced](/docs/advanced/README.md)
   * [Invalidation](/docs/advanced/Invalidation.md)
   * [Views](/docs/advanced/ViewOf.md)
+  * [Deduplication](/docs/advanced/Deduplication.md)
   * [Custom ID](/docs/advanced/CustomId.md)
+  * [Plugins](/docs/advanced/Plugins.md)
+    * [Cheat Sheet](/docs/advanced/Plugins-CheatSheet.md)
+    * [Known Plugins](/docs/advanced/Plugins-KnownPlugins.md)
 * [Recipes](/docs/Recipes.md)
   * [Separate API Folder](/docs/recipes/SeparateApiFolder.md)
   * [Polling](/docs/recipes/Polling.md)

docs/advanced/ChangeListener.md

@@ -0,0 +1,37 @@
+# Change Listener
+
+The returned api object of Ladda's `build` function exposes a registration function to be notified every time entities inside Ladda's cache change. The field is called `__addChangeListener`.
+
+```javascript
+import { build } from 'ladda-cache';
+
+const config = { /* your configuration here */ };
+const api = build(config);
+
+api.__addChangeListener((change) => /* act on change */)
+```
+
+`__addChangeListener` returns an unsubscribe function to stop listening
+for changes.
+
+```javascript
+const unsubscribe = api.__addChangeListener((change) => /* act on change */)
+unsubscribe();
+```
+
+The signature of the change object is as follows:
+```javascript
+{
+  type: 'UPDATE' | 'REMOVE',
+  entity: EntityName,
+  entities: EntityValue[]
+}
+```
+
+At this point in time there is no difference made between adding new
+EntityValues and updating already present ones: Both events lead to a
+change of the type `UPDATE`.
+The `entities` field is guaranteed to be a list of EntityValues, even if
+a change only affects a single entity.
+
+

docs/advanced/Deduplication.md

@@ -0,0 +1,30 @@
+# Deduplication
+
+Ladda tries to optimize "READ" operations by deduplicating identical
+simultaneous requests and therefore reduce the load both on server and
+client.
+
+*Identical* means calling the same function with identical arguments.
+<br>
+*Simultaneous* means that another call has been made before the first
+call has been resolved or rejected.
+
+Given the following code, where `getUsers` is a "READ" operation:
+
+```javascript
+// Component 1
+api.user.getUsers();
+
+// Component 2
+api.user.getUsers();
+
+// Component 3
+api.user.getUsers();
+```
+
+Ladda will only make a single call to `getUsers` and distribute its
+result to all callers.
+
+
+This feature can be disabled on a global, an entity and a function
+level. Check the [Configuration Reference](/docs/basics/Configuration.md) for details.

docs/advanced/Plugins-CheatSheet.md

@@ -0,0 +1,54 @@
+# Plugins Cheat Sheet
+
+## Signature
+
+```javascript
+({ entityConfigs, config, addChangeListener }) => ({ entity, fn }) => ApiFn
+```
+
+<br/>
+
+It is a good practice to allow your users to pass in an additional
+plugin configuration object, thus reaching a final shape like this:
+
+```javascript
+export const yourPlugin = (pluginConfig = {}) => {
+  return ({ entityConfigs, config, addChangeListener }) => {
+    // Use this space to setup additional data structures and helpers,
+    // that act across entities.
+    return ({ entity, fn }) => {
+      // Use this space to setup additional data structures and helpers,
+      // that act on a single entity.
+      return (...args) => {
+        // Do your magic here!
+        // Invoke the original fn with its arguments or a variation of it.
+        return fn(...args);
+      };
+    };
+  };
+};
+```
+
+We commonly refer to this process as __create => setup => decorate__
+steps, with the final goal of producing a decorated __ApiFunction__.
+
+## Apply a plugin
+
+Pass plugins in a list of plugins as an optional second argument to
+Ladda's `build` function.
+
+```javascript
+import { build } from 'ladda-cache';
+import { logger } from 'ladda-logger';
+import { observable } from 'ladda-observable';
+
+const config = { /* your ladda configuration */ };
+
+export default build(config, [
+  observable(),
+  logger()
+]);
+```
+
+Plugins are evaluated from left to right.
+

docs/advanced/Plugins-KnownPlugins.md

@@ -0,0 +1,31 @@
+# Known Plugins
+
+<div style="padding: 20px; margin-bottom: 20px; background-color: #fff6d4;">
+  <div>
+    <strong>Just created your own Ladda plugin?</strong>
+  </div>
+  <div>
+    Feel free to add it to this list and share it with the community!
+  </div>
+</div>
+
+- [ladda-logger](https://github.com/ladda-js/ladda-logger)
+
+A more sophisticated version of the plugin we just build. Logs on every
+change to the Ladda cache and gives you timings on how long your API
+calls take.
+
+- [ladda-observable](https://github.com/ladda-js/ladda-observable)
+
+Adds an observable interface to all `READ` operations. Allows you to be
+notified whenever something related to your API call has changed, e.g.
+you can observe a list of entities and get notified once one of this
+changes is updated.
+
+- [ladda-denormalizer](https://github.com/ladda-js/ladda-denormalizer)
+
+Allows to define denormalization schemas and strategies, so that your
+server can send plain ids instead of full entity objects. The plugin
+will resolve these ids for you in an optimized fashion, so that your
+client-side code can stay simple an operate on full entities.
+