chore: deprecate error ctors (#6277)

* chore: add deprecations to error ctors

* test: add test for error ctor deprecations

* chore: remove old dtslint comment - TS 2.8 lol

Author: cartant

spec-dtslint/errors-spec.ts

@@ -0,0 +1,35 @@
+import { AjaxError, AjaxTimeoutError } from 'rxjs/ajax';
+import {
+  ArgumentOutOfRangeError,
+  EmptyError,
+  NotFoundError,
+  ObjectUnsubscribedError,
+  SequenceError,
+  TimeoutError,
+  UnsubscriptionError
+} from 'rxjs';
+
+it('should deprecate error construction', () => {
+  let error: Error;
+  error = new AjaxError('message', null!, null!); // $ExpectDeprecation
+  error = new ArgumentOutOfRangeError(); // $ExpectDeprecation
+  error = new EmptyError(); // $ExpectDeprecation
+  error = new NotFoundError('message'); // $ExpectDeprecation
+  error = new ObjectUnsubscribedError(); // $ExpectDeprecation
+  error = new SequenceError('message'); // $ExpectDeprecation
+  error = new TimeoutError(); // $ExpectDeprecation
+  error = new UnsubscriptionError([]); // $ExpectDeprecation
+});
+
+it('should not deprecate instanceof use', () => {
+  const error = new Error('message');
+  let b: boolean;
+  b = error instanceof AjaxError; // $ExpectNoDeprecation
+  b = error instanceof ArgumentOutOfRangeError; // $ExpectNoDeprecation
+  b = error instanceof EmptyError; // $ExpectNoDeprecation
+  b = error instanceof NotFoundError; // $ExpectNoDeprecation
+  b = error instanceof ObjectUnsubscribedError; // $ExpectNoDeprecation
+  b = error instanceof SequenceError; // $ExpectNoDeprecation
+  b = error instanceof TimeoutError; // $ExpectNoDeprecation
+  b = error instanceof UnsubscriptionError; // $ExpectNoDeprecation
+});

spec-dtslint/index.d.ts

@@ -1 +0,0 @@
-// TypeScript Version: 2.8

src/internal/ajax/errors.ts

@@ -39,7 +39,8 @@ export interface AjaxError extends Error {
 
 export interface AjaxErrorCtor {
   /**
-   * Internal use only. Do not manually create instances of this type.
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
    */
   new (message: string, xhr: XMLHttpRequest, request: AjaxRequest): AjaxError;
 }
@@ -78,7 +79,8 @@ export interface AjaxTimeoutError extends AjaxError {}
 
 export interface AjaxTimeoutErrorCtor {
   /**
-   * Internal use only. Do not manually create instances of this type.
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
    */
   new (xhr: XMLHttpRequest, request: AjaxRequest): AjaxTimeoutError;
 }

src/internal/operators/timeout.ts

@@ -67,8 +67,8 @@ export interface TimeoutError<T = unknown, M = unknown> extends Error {
 
 export interface TimeoutErrorCtor {
   /**
-   * Internal use only. DO NOT create new instances of TimeoutError directly.
-   * This type is exported for the purpose of `instanceof` checks.
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
    */
   new <T = unknown, M = unknown>(info?: TimeoutInfo<T, M>): TimeoutError<T, M>;
 }

src/internal/util/ArgumentOutOfRangeError.ts

@@ -3,6 +3,10 @@ import { createErrorClass } from './createErrorClass';
 export interface ArgumentOutOfRangeError extends Error {}
 
 export interface ArgumentOutOfRangeErrorCtor {
+  /**
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
+   */
   new (): ArgumentOutOfRangeError;
 }
 

src/internal/util/EmptyError.ts

@@ -1,10 +1,13 @@
 import { createErrorClass } from './createErrorClass';
 
-export interface EmptyError extends Error {
-}
+export interface EmptyError extends Error {}
 
 export interface EmptyErrorCtor {
-  new(): EmptyError;
+  /**
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
+   */
+  new (): EmptyError;
 }
 
 /**
@@ -17,8 +20,11 @@ export interface EmptyErrorCtor {
  *
  * @class EmptyError
  */
-export const EmptyError: EmptyErrorCtor = createErrorClass((_super) => function EmptyErrorImpl(this: any) {
-  _super(this);
-  this.name = 'EmptyError';
-  this.message = 'no elements in sequence';
-});
+export const EmptyError: EmptyErrorCtor = createErrorClass(
+  (_super) =>
+    function EmptyErrorImpl(this: any) {
+      _super(this);
+      this.name = 'EmptyError';
+      this.message = 'no elements in sequence';
+    }
+);

src/internal/util/NotFoundError.ts

@@ -3,6 +3,10 @@ import { createErrorClass } from './createErrorClass';
 export interface NotFoundError extends Error {}
 
 export interface NotFoundErrorCtor {
+  /**
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
+   */
   new (message: string): NotFoundError;
 }
 

src/internal/util/ObjectUnsubscribedError.ts

@@ -3,6 +3,10 @@ import { createErrorClass } from './createErrorClass';
 export interface ObjectUnsubscribedError extends Error {}
 
 export interface ObjectUnsubscribedErrorCtor {
+  /**
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
+   */
   new (): ObjectUnsubscribedError;
 }
 

src/internal/util/SequenceError.ts

@@ -3,6 +3,10 @@ import { createErrorClass } from './createErrorClass';
 export interface SequenceError extends Error {}
 
 export interface SequenceErrorCtor {
+  /**
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
+   */
   new (message: string): SequenceError;
 }
 

src/internal/util/UnsubscriptionError.ts

@@ -5,6 +5,10 @@ export interface UnsubscriptionError extends Error {
 }
 
 export interface UnsubscriptionErrorCtor {
+  /**
+   * @deprecated Internal implementation detail. Do not construct error instances.
+   * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
+   */
   new (errors: any[]): UnsubscriptionError;
 }