allow getBy to receive options

- one use of the options is to override the result limit so that getBy
  can return multiple hits.
- the options has been introduced in a backwards compatible manner.
- all tests should still be passing.