fix(limit): add limit and error events (#267)

fixes #265

docs/source/documentation.html.md.erb

@@ -384,6 +384,30 @@ and no suggestion is displayed nor selected.
 
 You can use this event when used with a map to reset the pins and the default center. See this behaviour
 live on the [map example](examples.html#link-to-a-map).
+</td>
+ </tr>
+ <tr>
+<td markdown="1">
+<div class="api-entry" id="api-events-limit"><code>limit</code></div>
+
+Event data: `undefined`
+
+</td>
+<td markdown="1">
+Fired when you reached your current [rate limit](#rate-limits).
+</td>
+ </tr>
+ <tr>
+<td markdown="1">
+ <div class="api-entry" id="api-events-error"><code>error</code></div>
+
+ Event data:
+
+ - *message* <br>Type: **string**
+
+</td>
+<td markdown="1">
+ Fired when we could not make the request to Algolia Places servers for any reason but reaching your rate limit.
 </td>
  </tr>
  </tbody>
@@ -753,6 +777,8 @@ The Algolia Places API enforces some rate limits.
 
 If you're calling the API from your backend, the rate-limits computation is then based on the source IP.
 
+If you are using the places.js library, you will receive a [`limit` event](#api-events-limit) on the places.js instance when you reach your current rate limit.
+
 ## License
 
 Algolia Places [is licensed](https:/algolia/places/blob/master/LICENSE) under [MIT](https://en.wikipedia.org/wiki/MIT_License).

src/createAutocompleteDataset.js

@@ -7,11 +7,13 @@ export default function createAutocompleteDataset(options) {
  ...options.templates
  };
 
+ const source = createAutocompleteSource({
+ ...options,
+ formatInputValue: templates.value
+ });
+
  return {
- source: createAutocompleteSource({
- ...options,
- formatInputValue: templates.value
- }),
+ source,
  templates,
  displayKey: 'value',
  name: 'places'

src/createAutocompleteSource.js

@@ -15,6 +15,8 @@ export default function createAutocompleteSource({
  useDeviceLocation = false,
  language = navigator.language.split('-')[0],
  onHits = () => {},
+ onError,
+ onRateLimitReached,
  type
 }) {
  const placesClient = algoliasearch.initPlaces(
@@ -75,5 +77,13 @@ export default function createAutocompleteSource({
  return hits;
  }
  )
- .then(cb);
+ .then(cb)
+ .catch(e => {
+ if (e.message === 'Too many requests') {
+ onRateLimitReached();
+ return;
+ }
+
+ onError(e);
+ });
 }

src/places.js

@@ -75,7 +75,25 @@ export default function places(options) {
  rawAnswer,
  query,
  suggestions: hits
- })
+ }),
+ onError: e => placesInstance.emit('error', e),
+ onRateLimitReached: () => {
+ const listeners = placesInstance.listenerCount('limit');
+ if (listeners === 0) {
+ console.log(
+`Algolia Places: Current rate limit reached.
+
+Sign up for a free 100,000 queries/month account at
+https://www.algolia.com/users/sign_up/places.
+
+Or upgrade your 100,000 queries/month plan by contacting us at
+https://community.algolia.com/places/contact.html.`
+);
+ return;
+ }
+
+ placesInstance.emit('limit');
+ }
  });
  const autocompleteInstance = autocomplete(container, autocompleteOptions, autocompleteDataset);
  const autocompleteContainer = container.parentNode;