@pretto/places 0.40.0 → 0.41.0

package/README.md

@@ -5,6 +5,8 @@
 Allows you to search for an address, a postcode or a French department.
 You can also search a country.
 
+The library is typed but you can retrieve the types in the `dist/types` folder if needed
+
 ## FAQ
 
 ### How to implement the library?
@@ -16,28 +18,32 @@ yarn add @pretto/places
 For municipality and zipcode
 
 ```jsx
-import { municipalitySearch } from '@pretto/places'
+import { searchPlaces } from '@pretto/places';
+import { MunicipalitySearchResult } from '@pretto/places/dist/types';
 
-const result = await municipalitySearch.get("paris", { limit: 21 })
+const result = await searchPlaces("paris", { limit: 21 })
 
-// expected result : Paris (75001), Paris (75002), Paris (75003), ..., Paris (75020)
 // result object format :
 [
     {
-        "label": "Paris (75001)",
-        "value": {
-            "city": "Paris",
-            "country": "fr",
-            "zipcode": "75001"
-        }
+        label: "Paris 1er Arrondissement 75001",
+        value: {
+            center: [2.3359, 48.862],
+            city: "Paris 1er Arrondissement",
+            country: "fr",
+            outline: [[{"latitude": 48.870688, "longitude": 2.347918},...]],
+            zipcode: "75001",
+        },
     },
     {
-        "label": "Paris (75002)",
-        "value": {
-            "city": "Paris",
-            "country": "fr",
-            "zipcode": "75002"
-        }
+        label: "Paris 2e Arrondissement 75002",
+        value: {
+            center: [2.3411, 48.8677],
+            city: "Paris 2e Arrondissement",
+            country: "fr",
+            outline: [Array],
+            zipcode: "75002",
+        },
     },
     ...
 ]
@@ -46,28 +52,36 @@ const result = await municipalitySearch.get("paris", { limit: 21 })
 For department only
 
 ```jsx
-import { municipalitySearch } from '@pretto/places'
+import { searchDepartment } from '@pretto/places'
+import { DepartmentSearchResult } from '@pretto/places/dist/types';
 
-const result = await municipalitySearch.get("paris", { departmentOnly: true, limit: 21 })
+const result = await searchDepartment("pa", { limit: 21 })
 
-// expected result : Paris (75), Parisot(81), Parisot (82), Cormeilles-en-Parisis (95), ...
 // result object format :
 [
     {
-        "label": "Paris (75)",
-        "value": {
-            "city": "Paris",
-            "country": "fr",
-            "zipcode": "75"
-        }
+        label: "Paris (75)",
+        value: {
+            code: "75",
+            codeRegion: "11",
+            country: "fr",
+            region: {
+                code: "11",
+                nom: "Île-de-France"
+            }
+        },
     },
     {
-        "label": "Parisot (81)",
-        "value": {
-            "city": "Parisot",
-            "country": "fr",
-            "zipcode": "81"
-        }
+        label: "Pas-de-Calais (62)",
+        value: {
+            code: "62",
+            codeRegion: "32",
+            country: "fr",
+            region: {
+                code: "32",
+                nom: "Hauts-de-France"
+            }
+        },
     },
     ...
 ]
@@ -77,30 +91,30 @@ For Address (France only)
 
 ```jsx
 import { addressSearch } from '@pretto/places'
+import { AddressSearchResult } from '@pretto/places/dist/types';
 
 const result = await addressSearch.get("55 rue de paradis", { limit: 10 })
 
-// expected result : 55 Rue de Paradis 75010 Paris (75010), 55 Rue de Paradis 51160 Hautvillers (51160)...
 // result object format :
 [
-    {
-        "label": "55 Rue de Paradis 75010 Paris (75010)",
-        "value": {
-            "city": "Paris",
-            "country": "fr",
-            "street": "55 Rue de Paradis",
-            "zipcode": "75010"
-        }
+  {
+    label: "42 Rue de Paradis 75010, Paris",
+    value: {
+      city: "Paris",
+      country: "fr",
+      street: "42 Rue de Paradis",
+      zipcode: "75010",
     },
-    {
-        "label": "55 Rue de Paradis 51160 Hautvillers (51160)",
-        "value": {
-            "city": "Hautvillers",
-            "country": "fr",
-            "street": "55 Rue de Paradis",
-            "zipcode": "51160"
-        }
+  },
+  {
+    label: "42 Rue de Paradis 95100, Argenteuil",
+    value: {
+      city: "Argenteuil",
+      country: "fr",
+      street: "42 Rue de Paradis",
+      zipcode: "95100",
     },
+  },
     ...
 ]
 ```
@@ -108,11 +122,10 @@ const result = await addressSearch.get("55 rue de paradis", { limit: 10 })
 For country
 
 ```jsx
-import { countrySearch } from '@pretto/places'
+import { searchCountry } from '@pretto/places'
 
-const countriesApi = countrySearch.init(ALGOLIA_COUNTRIES_APP_ID, ALGOLIA_COUNTRIES_API_KEY)
+const countriesApi = searchCountry.init(ALGOLIA_COUNTRIES_APP_ID, ALGOLIA_COUNTRIES_API_KEY)
 const results = await countriesApi.get('al', { limit: 10 })[
-  // expected result : Allemagne (99109), Albanie (99125), Algerie (99352)
   // result object format :
   ({
     label: 'Allemagne (99109)',
@@ -129,44 +142,61 @@ const results = await countriesApi.get('al', { limit: 10 })[
 ]
 ```
 
-For geolocalisation
+For reverse geolocalisation
 
 ```typescript
-import { geolocSearch } from '@pretto/places'
+import { searchByCoordinates } from '@pretto/places'
+import { MunicipalitySearchResult } from '@pretto/places/dist/types';
+
+const results = await searchByCoordinates({ latitude: 48.87571729159758, longitude: 2.3503000982950883 })
 
-const results = await geolocSearch.get('75010')
 // result object format :
-// [{
-//      city: 'Paris'
-//      code: '75010',
-//      coordinates: [2.347, 48.8589],
-// }]
+[
+  {
+    label: "Paris 10e Arrondissement 75010",
+    value: {
+      center: [Object],
+      city: "Paris 10e Arrondissement",
+      country: "fr",
+      outline: [Array],
+      zipcode: "75010",
+    },
+  },
+];
 ```
 
-For reverse geolocalisation
+### Options
 
-```typescript
-import { reverseGeolocSearch } from '@pretto/places'
+You can pass options to the search function.
 
-const results = await reverseGeolocSearch.get({ latitude: 48.8932244326416, longitude: 2.289395548568507 })
-// result object format :
-// [{
-//      center: {latitude: 48.8946, longitude: 2.2874}
-//      city: 'Levallois-Perret'
-//      code: '92044',
-//      coordinates: [2.2874, 48.8946],
-//      zipcode: 92300,
-// }]
-```
+| Option       | Type        | Default Value   |
+| ------------ | ----------- | --------------- |
+| debouncetime | number      | 300             |
+| limit        | number      | 10              |
+| signal       | AbortSignal | AbortController |
 
-### Debounce
+```jsx
+const debounceValue = 1000 // --- 1000 = 1s
+const results = await searchPlaces('paris', { debouncetime: debounceValue, limit: 100 })
+```
 
-`addressSearch`, `municipalitySearch` and `geolocSearch` have defaut debounce value fixed to **300ms**\
-You can override this value by passing debounce value as last argument
+The signal allows you to abort a request if you no longer want to wait for the response. If it's not defined in the options, the library will use a locally managed AbortController(). If you need to manage your own abort, you can do it like this:
 
 ```jsx
-const debounceValue = 1000 // --- 1000 = 1s
-const results = await countriesApi.get('al', { limit: 10 }, debounceValue)
+let controller = null
+...
+if(!search) {
+   controller.abort()
+   setResults([])
+   return
+}
+
+if(controller) {
+  controller.abort()
+}
+
+controller = new AbortController()
+const places = await searchPlaces(search, {signal: controller.signal})
 ```
 
 ### How to publish a new version?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretto/places",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",