So looking over the original polly source code, it looks like there's lots of complex C#-specific features that go into its implementation, including extension methods on the PolicyBuilder
type defined for each type of policy. This looks to be the main thing that drives the fluent api. We might be able to get really close to the fluent api that exists in the original, but for ease of contribution, it might be better to create distinct classes for each policy type and think about how to join them together/create a fluid api that encompasses all of them later on.
So my proposal for now is that we use an interface of some kind to unite them and start implementing them separately. Maybe something like the following:
type SyncOrAsyncFn = (() => Promise<void>) | (() => void));
interface Policy {
execute: (fn: SyncOrAsyncFn) => Promise<void>
// the original Polly has a very hard line between sync and async
// usages of the `execute` function, and whoever its friends are in the
// specific terminal policy that is built in a given usage, so we may likewise
// want to keep sync and async fenced off. This interface has
// them united into an async impl that handles sync cases.
}
Here's some pseudocode for RetryPolicy
to continue the example:
class RetryPolicy<TException> implements Policy {
or<T>(fn: ...) {
// ...
return this;
}
retry(numRetries: number) {
// ...
return this;
}
// etc.
async execute(fn: SyncOrAsyncFn): Promise<void> {
// ...
await fn();
}
}
Then we can create a module as our main export that at least gives us the impression of having a static Policy
object for initializing policies. I'm hoping this can keep API changes a bit less disruptive but I'm not 100% sure how that might play out.
// index.ts
// this is the `main` file in the `package.json`
export default {
handle: <TException>() => new RetryPolicy<TException>()
}
// elsewhere, in this library's calling code.
import Policy from 'pollyscript'
const retryPolicy = Policy.handle<MyCustomException>().or<WhateverException>().retry(3);
const fallibleFn = () => { ... };
retryPolicy.execute(fallibleFn);
NOTE: I'm completely spitballing the pseudo-implementation for retry policy. This version actually doesn't allow any meaningful usage outside of typescript, due to the use of generics as the driver for giving exception types in the main API, as an additional note.
@the-pat What do you think?