add caching - make it optional from the config returned

add tests

add some examples



