Next generation route manipulation

[wheresrhys]

#460 is about improving the api for naming routes in order to facilitate clearer inspection APIs (#523 #527 #545), with knock on benefits, due to the ease of referencing a route, for manipulating a particular route after creation (#565)

However, the real need is to improve the ability to reference a route. Can we do that without the concept of a name to identify a route by, and rather use an actual reference to the route itself. (Inspired in part by this issue https://github.com/wheresrhys/fetch-mock-jest/issues/17)

Requirements:

1. Ability to ask both 'did this route handle this call' and 'does this matcher match this call'... subtlely different things
2. Ability to alter/replace/remove a specific route
3. Editable sticky routes i.e. generic sticky routes set up once, but can be modified for the duration of a test
4. Remove difficult to explain (and therefore bad) APIs around how inspecting works and how and when to turn on/off overwrite routes
5. Simplify fetchHandler by making it a little dumber - it should be a machine for running a bunch of routes and is less about managing when it is/isn't using some sensible routes

Some thoughts:

1. Define a new Route class that encapsulates all properties of a route
2. Provide some way of getting a reference to the instances of Route while still allowing chainability. First draft non-breaking POC might be FetchMock.router.mock|get|post|... return the route while the top level methods are still chainable.
3. Longer term might want to make all the mocking methods return routes, but these proxy through to the parent fetchMock instance for chaining (but feels difficult as how do we deal with the this references with child sandboxed instances)
4. overwrite routes goes
5. Calls have the route that handled them assigned to a handledBy property. this can also have the values fetch or catch
6. If an inspection method is passed an instance of Route it filters by that. Otherwise filters by running the matcher
7. routes have an edit method or similar which edits the route (but reverting to the underlying sticky route when reset)
8. also a remove method (or maybe ot's fetchMock.remove()
9. These routes can be created completely independently and passed around. mock() can be passed one or more of them

[wheresrhys]

@trixn86 this is partly inspired by your issue on fetch-mock-jest. I'm interested on feedback

[wheresrhys]

• [x] Define a new Route class that encapsulates all properties of a route
• [ ] Provide some way of getting a reference to the instances of Route while still allowing chainability. First draft non-breaking POC
• [ ] might be FetchMock.router.mock|get|post|... return the route while the top level methods are still chainable.
• [ ] Longer term might want to make all the mocking methods return routes, but these proxy through to the parent fetchMock instance for
• [ ] chaining (but feels difficult as how do we deal with the this references with child sandboxed instances)
• [ ] overwrite routes goes
• [ ] Calls have the route that handled them assigned to a handledBy property. this can also have the values fetch or catch
• [ ] If an inspection method is passed an instance of Route it filters by that. Otherwise filters by running the matcher
• [ ] routes have an edit method or similar which edits the route (but reverting to the underlying sticky route when reset)
• [ ] also a remove method (or maybe ot's fetchMock.remove()
• [ ] These routes can be created completely independently and passed around. mock() can be passed one or more of them- [ ]
• [ ] Tests that methods behave basically the same as existing methods
• [ ] Test that inspection based on passing in routes basically works
• [ ] Deprecate (with warning) use of route name
• [ ] Document in the midst of existing docs
• [ ] New docs page outlining the new approach