Constructor
Fcnew Datasource(dataFetcheropt, optionsopt)
In order to assure that caching works correctly, every data fetcher that accepts parameters, and returns different results depending on the values of those parameters must have an associated stream name generator, or, a stream name must be specified as an option each time data is fetched from the data source (the latter is very cumbersome and a poor apprach). If a custom stream name generator is not added to the data fetcher, the Datasource.defaultStreamNameGenerator() function is used. This will suffice in all cases except those where the passed parameter values can't be converted to JSON strings. In such rare edge cases, a custom stream name geneator must be specified or each call to the data fetcher will result in an error being thrown.
A custom stream name generator can be added by adding a callback as a
property of the fetcher function with the name streamNameGenerator.
Parameters:
| Name | Type | Attributes | Default | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
dataFetcher |
DataFetcher
|
<optional> |
{} |
the callback, or collection of callbacks, which the datasource will use to fetch data. |
|||||||||||||||
options |
PlainObject
|
<optional> |
a plain object defining options.
|
Throws:
-
a validation error is thrown if parameter validation fails.
- Type
-
external:validateParams.ValidationError
Examples
Single Data Fetcher without Parameters
const cjdb = require('@maynoothuniversity/caching-json-databridge');
let daysDS = new cjdb.Datasource(function(){
return ['mon', 'tues', 'wed', 'thurs', 'fri', 'sat', 'sun'];
});Multiple Data Fetchers without Parameters
const cjdb = require('@maynoothuniversity/caching-json-databridge');
let fancyDaysDS = new cjdb.Datasource({
lowerCase: function(){
return ['mon', 'tues', 'wed', 'thurs', 'fri', 'sat', 'sun'];
},
upperCase: function(){
return ['Mon', 'TUES', 'WED', 'THURS', 'FRI', 'SAT', 'SUN'];
}
});Custom Stream Name Generator
const cjdb = require('@maynoothuniversity/caching-json-databridge');
// define a data fetcher function which expects a Date object as the only param
let myDataFetcher = function(d){
return "Party like it's " + d.getFullYear();
}
// add a custom stream name generator
myDataFetcher.streamNameGenerator = function(fParams){
return "y_" + fParams[0].getFullYear();
}
// create the datasource
let partyDS = new cjdb.Datasource(myDataFetcher);Methods
F(static) defaultStreamNameGenerator(dataFetcherParams, fetchOptions) → {DatabridgeName}
The default stream name generator function. This function attempts to always ensure a unique stream name for all possible fetcher arguments.
If no arguments are present, main is returned.
If a single argument is present, and its string value would be valid as a
datasource name, then that value is returned (numbers get pre-fixed with
n_ to make them valid).
For all other values, an attempt is made to convert the fetcher arguments to a JSON string, which is then converted to a hexidecimal MD5 hash. Not all values can be converted to JSON, so this function could throw an error.
- See:
Parameters:
| Name | Type | Description |
|---|---|---|
dataFetcherParams |
Array
|
the parameters that will be passed to the datafetcher as an array. |
fetchOptions |
PlainObject
|
the options that were passed to the call to [.fetchResponse()]{Databridge#fetchResponse} on the data bridge to trigger the request this stream name is for. |
Throws:
-
An error is thrown if the function fails to convert the given fetcher parameters to a stream name.
- Type
-
Error
Returns:
- Type:
-
DatabridgeName
FdataFetcher(callbackPathopt) → {function|PlainObject}
A read-only accessor for fetcher callbacks. If there's only one callback associated with this source then it will be returned, regardless of the parameters passed. If there are multiple nested callbacks, then, depending on the parameters passed, either a callback or a plain object containing multiple callbacks will be returned.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
callbackPath |
DatabridgeName
|
Array.<DatabridgeName>
|
<optional> |
if paramters are passed, they will be interpreted as paths within the data fetchers data structure. |
Throws:
-
-
A type error is thrown if parameters are present, but not valid.
- Type
-
TypeError
-
-
-
An error is thrown if a non-existent data fetcher is requested.
- Type
-
Error
-
Returns:
- Type:
-
function|PlainObject
FfetchDataPromise(fetcherArgsopt, callbackPathopt) → {Promise}
A function to execute the dataFetcher callback and return a promise for
the data it will produce.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
fetcherArgs |
Array
|
<optional> |
[] |
the arguments to pass to the fetcher functions as an array. |
callbackPath |
Array.<DatabridgeName>
|
<optional> |
if this datasource has multiple data fetchers, this argument is required. |
Returns:
- Type:
-
Promise
FhasSingleDataFetcher() → {boolean}
A utility function to determine whether or not a given datasource has a
simple sigle data fetcher callback, or, supports multiple data fetchers.
I.e. true if .dataFetcher() returns a callback, and false if it
returns a plain object, even if that plain object only contains a single
callback.
Returns:
- Type:
-
boolean
Foption(optionName) → {*}
A read-only accessor for all the options.
Parameters:
| Name | Type | Description |
|---|---|---|
optionName |
string
|
the name of the option to get the value for |
Throws:
-
-
a validation error is thrown if parameter validation fails.
- Type
-
external:validateParams.ValidationError
-
-
-
an error if execution of the fetcher fails.
- Type
-
Error
-
Returns:
- Type:
-
*
the option's value, or undefined if the option is not
defined.