*ActivityOptions: make either timeout required

[ikonst]

What was changed

*ActivityOptions types

Why?

We do this check in runtime:

sdk-typescript/packages/workflow/src/workflow.ts

Lines 134 to 138 in 6990b19

	function validateActivityOptions(options: ActivityOptions): void {
	if (options.scheduleToCloseTimeout === undefined && options.startToCloseTimeout === undefined) {
	throw new TypeError('Required either scheduleToCloseTimeout or startToCloseTimeout');
	}
	}

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?