feat(timeout): One timeout to rule them all

- Adds configuration argument pattern
- Fixes issue where `timeout` and `timeoutWith` would always timeout when provided a Date as a due time, even if the source emitted a value before then.
- Adds ability to configure timeout to have a different `first` timeout check and subsequent `each` timeout checks
- Adds ability to timeout if _just_ the first value does not arrive after a specified number of milliseconds
- Adds additional information to `TimeoutError`s thrown by bare `timeout` calls.
- Adds `with` parameter to `timeout` operator's configuration, such that now `timeout` can be used in exactly the same ways as `timeoutWith` and more. The `with` parameter is a function that provides information about the timeout and expects an `ObservableInput` to switch to in response to a timeout.
- Deprecates `timeoutWith`.
- Updates tests to use run mode.
- Adds additional tests to `timeout` to cover more aspects of the configuration possiblities.
- Improves type signatures for `timeout` and `timeoutWith`.

api_guard/dist/types/index.d.ts

@@ -571,7 +571,8 @@ export interface TimeInterval<T> {
     value: T;
 }
 
-export interface TimeoutError extends Error {
+export interface TimeoutError<T = unknown, M = unknown> extends Error {
+    info: TimeoutInfo<T, M> | null;
 }
 
 export declare const TimeoutError: TimeoutErrorCtor;

api_guard/dist/types/operators/index.d.ts

@@ -318,9 +318,15 @@ export declare function throwIfEmpty<T>(errorFactory?: (() => any)): MonoTypeOpe
 
 export declare function timeInterval<T>(scheduler?: SchedulerLike): OperatorFunction<T, TimeInterval<T>>;
 
-export declare function timeout<T>(due: number | Date, scheduler?: SchedulerLike): MonoTypeOperatorFunction<T>;
-
-export declare function timeoutWith<T, R>(due: number | Date, withObservable: ObservableInput<R>, scheduler?: SchedulerLike): OperatorFunction<T, T | R>;
+export declare function timeout<T, R, M = unknown>(config: TimeoutConfig<T, R, M> & {
+    with: (info: TimeoutInfo<T, M>) => ObservableInput<R>;
+}): OperatorFunction<T, T | R>;
+export declare function timeout<T, M = unknown>(config: Omit<TimeoutConfig<T, any, M>, 'with'>): OperatorFunction<T, T>;
+export declare function timeout<T>(first: Date, scheduler?: SchedulerLike): MonoTypeOperatorFunction<T>;
+export declare function timeout<T>(each: number, scheduler?: SchedulerLike): MonoTypeOperatorFunction<T>;
+
+export declare function timeoutWith<T, R>(dueBy: Date, switchTo: ObservableInput<R>, scheduler?: SchedulerLike): OperatorFunction<T, T | R>;
+export declare function timeoutWith<T, R>(waitFor: number, switchTo: ObservableInput<R>, scheduler?: SchedulerLike): OperatorFunction<T, T | R>;
 
 export declare function timestamp<T>(timestampProvider?: TimestampProvider): OperatorFunction<T, Timestamp<T>>;
 

spec-dtslint/operators/timeout-spec.ts

@@ -1,5 +1,6 @@
 import { of, asyncScheduler } from 'rxjs';
 import { timeout } from 'rxjs/operators';
+import { A } from '../helpers';
 
 it('should infer correctly', () => {
   const o = of('a', 'b', 'c').pipe(timeout(10)); // $ExpectType Observable<string>
@@ -25,3 +26,30 @@ it('should enforce types of due', () => {
 it('should enforce types of scheduler', () => {
   const o = of('a', 'b', 'c').pipe(timeout(5, 'foo')); // $ExpectError
 });
+
+it('Check info argument to factory', () => {
+  const o = of('a').pipe( // $ExpectType Observable<string | number>
+    timeout({
+      meta: new A(),
+      with: (info) => {
+        const i = info; // $ExpectType TimeoutInfo<string, A>
+        const m = info.meta; // $ExpectType A
+        const s = info.seen; // $ExpectType number
+        const l = info.lastValue; // $ExpectType string | null
+        // These should be readonly
+        info.meta = new A(); // $ExpectError
+        info.seen = 12; // $ExpectError
+        info.lastValue = 'blah'; // $ExpectError
+        return of(123);
+      }
+    })
+  );
+});
+
+it('Check config arguments', () => {
+  const o = of('a').pipe( // $ExpectType Observable<string>
+    timeout({
+      first: 1000
+    })
+  );
+});