Add types for public API

[pittst3r]

So that BigTest can be used in TS projects. The tsconfig.json is for IntelliSense which aids in the creation/maintenance of the type declaration files.

This exports the IStats interface and Assertion and SideEffect function types from the index.d.ts file since those are public APIs. SideEffect is the type signature for the callback passed to Convergence#do() and I thought it was odd that #do(), although intended for side-effects, can perform side-effects and passes on the return value in the new Convergence it returns—unless I misinterpreted what's going on. I would have expected it to only perform side effects and for anything returned from its callback to be swallowed. If both behaviors are desired maybe that indicates an additional method like #map()?

[Robdel12]

This awesome! 🎉 Thanks for the PR.

I would have expected it to only perform side effects and for anything returned from its callback to be swallowed. If both behaviors are desired maybe that indicates an additional method like #map()?

I think that sounds right to me. I'm going to wait for a @cowboyd or @wwilsman review to figure out what we should do going forward. I don't think it has to hold this PR up either. But we should figure out what our follow up is

[pittst3r]

Confirm, not a blocker.

[cowboyd]

and I thought it was odd that #do(), although intended for side-effects, can perform side-effects and passes on the return value in the new Convergence

It's mildly Monadic in so far as it allows you to change both the value and the context, similar to promise.then, so it seems natural that you would not throw away the value?

do is about sequencing side-effects that don't actually run until all antecedent assertions have been met. So, for example, you could model your entire beforeEach chain for your nested contexts as a single convergence, each chained off the previous one.

when w
always x
do first thing
when y
never z
do second thing

The idea is to capture this sequence, so that it can be run again and again and again. But you're right. There are probably both map and flatMap in there somewhere, and I'd be very curious to see what that api would look like.

[wwilsman]

I'll clarify what's going on with flattening the return value inside of #do:

A feature of convergences is currying the return value from a previous function in the stack to the next function in the stack. You can use convergences without returning anything, so it's an optional feature that other libraries like @bigtest/interactor utilize a lot.

Support for flattening promise and convergence values inside of #do was only added because we need to wait for those side effects to finish before continuing on to the next function in the stack.

[pittst3r]

Thanks y'all. I will ponder this some more and open an issue to track this discussion.

[Robdel12]

Awesome, I'm going to merge this. 🎉

[pittst3r]

Noice 🙌