*ActivityOptions: make either timeout required

[ikonst]

What was changed

*ActivityOptions types

Why?

We do this check in runtime: https://github.com/temporalio/sdk-typescript/blob/6990b1908f7d1d42ff131dbe361e9f90ea8aafa8/packages/workflow/src/workflow.ts#L134-L138

It can be easily expressed in TypeScript.

Checklist

• How was this tested: Type checks pass

[ikonst]

@mjameswh can take a look?

[bergundy]

FTR I considered defining the types this way initially but decided against it because it's harder to understand and doesn't render well in the generated documentation.

[ikonst]

I can't trigger Build Docs, but trusting that's still the case we can close this PR.

[mjameswh]

FTR I considered defining the types this way initially but decided against it because it's harder to understand and doesn't render well in the generated documentation.

Yeah, that was my concern too, though I feel the build-time error would be highly desirable. Even I regularly make that error when writing samples/test code.

And yes, that's still a problem; we already have several such things in our doc, like this one:

[mjameswh]

Let's keep this PR open for now.

This "stricter type definition vs generated API docs readability" thing is already a problem, and will continue to grows over time. Both are important for DX. I would really want to look at how we can get the former without compromising too much on the latter.

One possibility might be to look at more readable ways to express the same type constraints. For example, in the specific case highlighted by @ikonst, a definition such as RequireEither<ActivityOptions, 'scheduleToCloseTimeout' | startToCloseTimeout> would probably result in more readable documentation.

Also, TypeDoc is actively working on various optimizations to how complex types get displayed in generated documentation. Some of these optimizations are automatic, but most must be turned on explicitly, e.g. by adding some doc annotation to the type. The TypeDoc 0.27 Beta just introduced several new such optimizations. We should really explore these optimizations.

[Sushisource]

My 2c is the build time error is way more important than marginally prettier docs. One of them stops you from making a mistake without you having to think, and the other is maybe slightly... distracting?

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

:white_check_mark: mjameswh
:x: Ilya Priven

---

Ilya Priven seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}