Merge pull request #24 from movableink/mn/allow-for-additional-options

allow for additional options to be passed such as corsCacheTime

README.md

@@ -3,9 +3,11 @@
 Data Source is a JS library meant to help developers access Movable Ink Data Sources and the raw responses associated with that Data Source.
 
 ## Installation
+
 Add data sources to your package.json file. In `dependencies` include the following:
+
 ```
-"data-source.js": "https://github.com/movableink/data-source.js.git#v0.2.0"
+"data-source.js": "https://github.com/movableink/data-source.js.git#v0.2.1"
 ```
 
 ## Usage
@@ -15,21 +17,26 @@ Add data sources to your package.json file. In `dependencies` include the follow
 The client is meant to be ran in a browser-like environment. The package itself is meant to be imported through ES6 modules.
 
 ```javascript
-import DataSource from "data-source.js"
+import DataSource from 'data-source.js';
 ```
 
 ### Fetching data
 
 ```javascript
-const key = "unique_datasource_key";  // pulled from the data sources application
+const key = 'unique_datasource_key'; // pulled from the data sources application
 const targetingKeys = {
-targeting_1: CD.param('targeting_1'),
-targeting_2: CD.param('targeting_2')
+  targeting_1: CD.param('targeting_1'),
+  targeting_2: CD.param('targeting_2')
 }; // optional params that will get passed to sorcerer
 
+// optional header options to pass to sorcerer
+const options = {
+  cacheTime: 100000
+};
+
 const source = new DataSource(key);
 
-const { data } = await source.getRawData(targetingKeys);
+const { data } = await source.getRawData(targetingKeys, options);
 //do something with your data
 ```
 
@@ -42,14 +49,19 @@ To fetch multiple rows you can call `getAllRows(targetingKeys)` which will retur
 
 ```javascript
 const targetingKeys = { category: 'food' };
-const rows = await source.getAllRows(targetingKeys)
+
+// optional header options to pass to sorcerer
+const options = {
+  cacheTime: 100000
+};
+const rows = await source.getAllRows(targetingKeys, options);
 // [["food", "apple", "banana"], ["food", "cake", "rice"], ["food", "fish", "pasta"]]
 ```
 
-
 #### Example
 
 Assuming a CSV file that looks like this (where `category` is the targeting segment, `item1` and `item2` are content fields)
+
 ```csv
 category, item1, item2
 food, apple, banana
@@ -62,17 +74,28 @@ toys, gun, doll
 The returned value will be an array of arrays containing entire rows that match specified targeting keys. The csv header names are not included.
 
 ```json
-[["food", "apple", "banana"], ["food", "cake", "rice"], ["food", "fish", "pasta"]]
+[
+  ["food", "apple", "banana"],
+  ["food", "cake", "rice"],
+  ["food", "fish", "pasta"]
+]
 ```
 
 ### Including Headers
+
 You can include a `headers` option to merge the original headers associated with the CSV as part of the response for `getAllRows`.
 
 #### Example
 
 ```javascript
 const targetingKeys = { category: 'food' };
-const rows = await source.getAllRows(targetingKeys, { headers: true })
+
+// optional header options to pass to sorcerer
+const options = {
+  headers: true,
+  cacheTime: 100000
+};
+const rows = await source.getAllRows(targetingKeys, options);
 // [
 //   { category: "food", item1: "apple", item:2 "banana" },
 //   { category: "food", item1: "cake", item2: "rice" },
@@ -83,15 +106,19 @@ const rows = await source.getAllRows(targetingKeys, { headers: true })
 The response will be an array of objects, where the keys are the headers and the values are the row's values.
 
 ### Geolocation
+
 You can also retrieve rows through our GIS capabilities by providing latitude and longitude coordinates while using `getAllRows`.
 
 #### Example
 
 This is assuming a CSV Data Source was created with columns `gap_latitude` and `gap_longitude` specified to be targeted using `latitude` and `longitude` respectively.
 
 ```javascript
-const targetingKeys = { mi_lat: CD.param('mi_lat'), mi_lon: CD.param('mi_lon') };
-const rows = await source.getAllRows(targetingKeys)
+const targetingKeys = {
+  mi_lat: CD.param('mi_lat'),
+  mi_lon: CD.param('mi_lon')
+};
+const rows = await source.getAllRows(targetingKeys);
 // assuming `mi_lat` and `mi_lon` were 40, -70 respectively
 // [
 //   ["The Gap Bryant Park", 40, -70],
@@ -103,8 +130,11 @@ const rows = await source.getAllRows(targetingKeys)
 `headers` also works:
 
 ```javascript
-const targetingKeys = { mi_lat: CD.param('mi_lat'), mi_lon: CD.param('mi_lon') };
-const rows = await source.getAllRows(targetingKeys, { headers: true })
+const targetingKeys = {
+  mi_lat: CD.param('mi_lat'),
+  mi_lon: CD.param('mi_lon')
+};
+const rows = await source.getAllRows(targetingKeys, { headers: true });
 // assuming `mi_lat` and `mi_lon` were 40, -70 respectively
 // {
 //   values: [
@@ -122,8 +152,8 @@ Note: including `headers: true`, only for geolocation, will change the response
 
 You will get back by default the three closest locations sorted by distance. We also support the following params:
 
-* `mi_limit`: by default this is `3`. You can pass an integer to specify how many locations you would like returned in the payload. The max is `20` and any values sent higher than that will default to `20`
-* `mi_radius`: by default this is not used. You can pass in an integer for `mi_radius` to further trim the results by distance (unit is miles).
+- `mi_limit`: by default this is `3`. You can pass an integer to specify how many locations you would like returned in the payload. The max is `20` and any values sent higher than that will default to `20`
+- `mi_radius`: by default this is not used. You can pass in an integer for `mi_radius` to further trim the results by distance (unit is miles).
 
 The first argument of `getAllRows` is typically a JS object. Internally that object is converted to URI query parameters and appended to the request on `sorcerer`. You can include any additional query parameters simply by including them into the object:
 
@@ -135,32 +165,42 @@ const rows = await source.getAllRows({ mi_lat: latitude, mi_lon: longitude, some
 
 When geolocating, if both targeting keys and geolocation columns are set, we will use the following priority to determine which parameters are used to retrieve rows:
 
-* IF both geolocation and targeting columns are set, AND the targeting conditions are fulfilled (read: required targeting keys are supplied)
-  * `sorcerer` will _only_ use targeting
-* IF both geolocation and targeting columns are set, AND the targeting conditions are not fulfilled
-  * `sorcerer` will fall back to geolocation
-* IF only geolocation columns are set, AND geolocation conditions are fulfilled (read: `mi_lat` and `mi_lon` are supplied)
-  * `sorcerer` will use geolocation
-* IF only targeting columns are set, AND targeting conditions are fulfilled
-  * `sorcerer` will use targeting
+- IF both geolocation and targeting columns are set, AND the targeting conditions are fulfilled (read: required targeting keys are supplied)
+  - `sorcerer` will _only_ use targeting
+- IF both geolocation and targeting columns are set, AND the targeting conditions are not fulfilled
+  - `sorcerer` will fall back to geolocation
+- IF only geolocation columns are set, AND geolocation conditions are fulfilled (read: `mi_lat` and `mi_lon` are supplied)
+  - `sorcerer` will use geolocation
+- IF only targeting columns are set, AND targeting conditions are fulfilled
+  - `sorcerer` will use targeting
 
 ## Changelog
 
+### 0.2.1
+
+- Add additional `headers` support to `getRawData` & `getAllRows`
+  - Pass additional params such as `{ headers: true, cacheTime: 100000 }` as the 2nd argument which will increase the cache time
+
 ### 0.2.0
-  * Add `headers` option support to `getAllRows`
-    * Pass `{ headers: true }` as an options argument which will return headers as part of each row's response.
+
+- Add `headers` option support to `getAllRows`
+  - Pass `{ headers: true }` as an options argument which will return headers as part of each row's response.
 
 ### 0.1.0
-  * Add getAllRows function
-    * Calling this function returns an array of all rows that match supplied targeting keys
+
+- Add getAllRows function
+  - Calling this function returns an array of all rows that match supplied targeting keys
 
 ### 0.0.3
-  * Remove `src/` as `.npmignore`-ed directory
-    * This was originally added to keep the `.ts` files out of the npm package, as people pulling from npm should just use the built `dist/` directory as the entrypoint to the library. Problem is, is that this then keeps `src/` out of the package when users install through the `git` paths. `tsc` fails due to not having any input directories.
-    * For now, we can remove this and keep the original `src/` in the package, as most users won't be pulling from `npm`.
+
+- Remove `src/` as `.npmignore`-ed directory
+  - This was originally added to keep the `.ts` files out of the npm package, as people pulling from npm should just use the built `dist/` directory as the entrypoint to the library. Problem is, is that this then keeps `src/` out of the package when users install through the `git` paths. `tsc` fails due to not having any input directories.
+  - For now, we can remove this and keep the original `src/` in the package, as most users won't be pulling from `npm`.
 
 ### 0.0.2
-  * Fix `No inputs were found in config file` by hardcoding `include` path
+
+- Fix `No inputs were found in config file` by hardcoding `include` path
 
 ### 0.0.1
-  * Initial release
+
+- Initial release