chore: add ts_api_guardian (#5494)

.circleci/config.yml

@@ -58,6 +58,12 @@ jobs:
       - attach_workspace: *attach_options
       - run: npm run dtslint
 
+  api_guardian:
+    <<: *defaults
+    steps:
+      - attach_workspace: *attach_options
+      - run: npm run api_guardian
+
   typescript3:
     <<: *defaults
     steps:

.gitignore

@@ -8,11 +8,11 @@
 
 # Installed libs
 node_modules/
-typings/
+/typings/
 
 # Generated
-dist/
-dist-compat/
+/dist/
+/dist-compat/
 tmp/
 coverage/
 img/

api_guard/dist/typings/ajax/index.d.ts

@@ -0,0 +1,44 @@
+export declare const ajax: AjaxCreationMethod;
+
+export interface AjaxError extends Error {
+    request: AjaxRequest;
+    response: any;
+    responseType: string;
+    status: number;
+    xhr: XMLHttpRequest;
+}
+
+export declare const AjaxError: AjaxErrorCtor;
+
+export interface AjaxRequest {
+    async?: boolean;
+    body?: any;
+    createXHR?: () => XMLHttpRequest;
+    crossDomain?: boolean;
+    hasContent?: boolean;
+    headers?: Object;
+    method?: string;
+    password?: string;
+    progressSubscriber?: Subscriber<any>;
+    responseType?: string;
+    timeout?: number;
+    url?: string;
+    user?: string;
+    withCredentials?: boolean;
+}
+
+export declare class AjaxResponse {
+    originalEvent: Event;
+    request: AjaxRequest;
+    response: any;
+    responseText: string;
+    responseType: string;
+    status: number;
+    xhr: XMLHttpRequest;
+    constructor(originalEvent: Event, xhr: XMLHttpRequest, request: AjaxRequest);
+}
+
+export interface AjaxTimeoutError extends AjaxError {
+}
+
+export declare const AjaxTimeoutError: AjaxTimeoutErrorCtor;

api_guard/dist/typings/fetch/index.d.ts

@@ -0,0 +1,4 @@
+export declare function fromFetch<T>(input: string | Request, init: RequestInit & {
+    selector: (response: Response) => ObservableInput<T>;
+}): Observable<T>;
+export declare function fromFetch(input: string | Request, init?: RequestInit): Observable<Response>;

api_guard/dist/typings/testing/index.d.ts

@@ -0,0 +1,23 @@
+export declare class TestScheduler extends VirtualTimeScheduler {
+    assertDeepEqual: (actual: any, expected: any) => boolean | void;
+    readonly coldObservables: ColdObservable<any>[];
+    readonly hotObservables: HotObservable<any>[];
+    constructor(assertDeepEqual: (actual: any, expected: any) => boolean | void);
+    createColdObservable<T = string>(marbles: string, values?: {
+        [marble: string]: T;
+    },                               error?: any): ColdObservable<T>;
+    createHotObservable<T = string>(marbles: string, values?: {
+        [marble: string]: T;
+    },                              error?: any): HotObservable<T>;
+    createTime(marbles: string): number;
+    expectObservable(observable: Observable<any>, subscriptionMarbles?: string): ({
+        toBe: observableToBeFn;
+    });
+    expectSubscriptions(actualSubscriptionLogs: SubscriptionLog[]): ({
+        toBe: subscriptionLogsToBeFn;
+    });
+    flush(): void;
+    run<T>(callback: (helpers: RunHelpers) => T): T;
+    static parseMarbles(marbles: string, values?: any, errorValue?: any, materializeInnerObservables?: boolean, runMode?: boolean): TestMessage[];
+    static parseMarblesAsSubscriptions(marbles: string, runMode?: boolean): SubscriptionLog;
+}

api_guard/dist/typings/webSocket/index.d.ts

@@ -0,0 +1,25 @@
+export declare function webSocket<T>(urlConfigOrSource: string | WebSocketSubjectConfig<T>): WebSocketSubject<T>;
+
+export declare class WebSocketSubject<T> extends AnonymousSubject<T> {
+    _output: Subject<T>;
+    constructor(urlConfigOrSource: string | WebSocketSubjectConfig<T> | Observable<T>, destination?: Observer<T>);
+    _subscribe(subscriber: Subscriber<T>): Subscription;
+    lift<R>(operator: Operator<T, R>): WebSocketSubject<R>;
+    multiplex(subMsg: () => any, unsubMsg: () => any, messageFilter: (value: T) => boolean): Observable<any>;
+    unsubscribe(): void;
+}
+
+export interface WebSocketSubjectConfig<T> {
+    WebSocketCtor?: {
+        new (url: string, protocols?: string | string[]): WebSocket;
+    };
+    binaryType?: 'blob' | 'arraybuffer';
+    closeObserver?: NextObserver<CloseEvent>;
+    closingObserver?: NextObserver<void>;
+    deserializer?: (e: MessageEvent) => T;
+    openObserver?: NextObserver<Event>;
+    protocol?: string | Array<string>;
+    resultSelector?: (e: MessageEvent) => T;
+    serializer?: (value: T) => WebSocketMessage;
+    url: string;
+}

package.json

@@ -40,7 +40,8 @@
       ]
     },
     "ignore": [
-      "spec-dtslint/**/*.{js,ts}"
+      "spec-dtslint/**/*.{js,ts}",
+      "api_guard/**/*.{js,ts}"
     ]
   },
   "scripts": {
@@ -122,7 +123,9 @@
     "compat_compile_dist_esm5_for_rollup": "tsc -p ./tsconfig/compat/tsconfig.esm5.rollup.json",
     "compat_compile_dist_esm2015": "tsc -p ./tsconfig/compat/tsconfig.esm2015.json",
     "compat_copy_sources": "mkdirp dist-compat && shx cp -r ./compat/ ./dist-compat/",
-    "compat_generate_packages": "node .make-compat-package.js"
+    "compat_generate_packages": "node .make-compat-package.js",
+    "api_guardian:update": "ts-api-guardian --outDir api_guard dist/typings/index.d.ts dist/typings/ajax/index.d.ts dist/typings/fetch/index.d.ts dist/typings/operators/index.d.ts dist/typings/testing/index.d.ts dist/typings/webSocket/index.d.ts",
+    "api_guardian": "ts-api-guardian --verifyDir api_guard dist/typings/index.d.ts dist/typings/ajax/index.d.ts dist/typings/fetch/index.d.ts dist/typings/operators/index.d.ts dist/typings/testing/index.d.ts dist/types/webSocket/index.d.ts"
   },
   "repository": {
     "type": "git",
@@ -238,6 +241,7 @@
     "source-map-support": "0.5.3",
     "symbol-observable": "1.0.1",
     "systemjs": "^0.21.0",
+    "ts-api-guardian": "^0.5.0",
     "ts-node": "6.1.0",
     "tsconfig-paths": "3.2.0",
     "tslint": "5.9.1",

src/index.ts

@@ -12,10 +12,10 @@ export { ReplaySubject } from './internal/ReplaySubject';
 export { AsyncSubject } from './internal/AsyncSubject';
 
 /* Schedulers */
-export { asap as asapScheduler } from './internal/scheduler/asap';
-export { async as asyncScheduler } from './internal/scheduler/async';
-export { queue as queueScheduler } from './internal/scheduler/queue';
-export { animationFrame as animationFrameScheduler } from './internal/scheduler/animationFrame';
+export { asap, asapScheduler } from './internal/scheduler/asap';
+export { async, asyncScheduler } from './internal/scheduler/async';
+export { queue, queueScheduler } from './internal/scheduler/queue';
+export { animationFrame, animationFrameScheduler } from './internal/scheduler/animationFrame';
 export { VirtualTimeScheduler, VirtualAction } from './internal/scheduler/VirtualTimeScheduler';
 export { Scheduler } from './internal/Scheduler';
 

src/internal/operators/mergeMap.ts

@@ -70,8 +70,6 @@ export function mergeMap<T, R, O extends ObservableInput<any>>(project: (value:
  * projection function (and the optional deprecated `resultSelector`) to each item
  * emitted by the source Observable and merging the results of the Observables
  * obtained from this transformation.
- * @method mergeMap
- * @owner Observable
  */
 export function mergeMap<T, R, O extends ObservableInput<any>>(
   project: (value: T, index: number) => O,
@@ -179,3 +177,8 @@ export class MergeMapSubscriber<T, R> extends OuterSubscriber<T, R> {
     }
   }
 }
+
+/**
+ * @deprecated renamed. Use {@link mergeMap}
+ */
+export const flatMap = mergeMap;

src/internal/scheduler/animationFrame.ts

@@ -31,10 +31,10 @@ import { AnimationFrameScheduler } from './AnimationFrameScheduler';
  *
  * // You will see a div element growing in height
  * ```
- *
- * @static true
- * @name animationFrame
- * @owner Scheduler
  */
+export const animationFrameScheduler = new AnimationFrameScheduler(AnimationFrameAction);
 
-export const animationFrame = new AnimationFrameScheduler(AnimationFrameAction);
+/**
+ * @deprecated renamed. Use {@link animationFrameScheduler}
+ */
+export const animationFrame = animationFrameScheduler;

src/internal/scheduler/asap.ts

@@ -34,9 +34,10 @@ import { AsapScheduler } from './AsapScheduler';
  * // "async"
  * // ... but 'asap' goes first!
  * ```
- * @static true
- * @name asap
- * @owner Scheduler
  */
+export const asapScheduler = new AsapScheduler(AsapAction);
 
-export const asap = new AsapScheduler(AsapAction);
+/**
+ * @deprecated renamed. Use {@link asapScheduler}
+ */
+export const asap = asapScheduler;

src/internal/scheduler/async.ts

@@ -46,10 +46,10 @@ import { AsyncScheduler } from './AsyncScheduler';
  * // 2 after 5s
  * // 3 after 6s
  * ```
- *
- * @static true
- * @name async
- * @owner Scheduler
  */
+export const asyncScheduler = new AsyncScheduler(AsyncAction);
 
-export const async = new AsyncScheduler(AsyncAction);
+/**
+ * @deprecated renamed. Use {@link asyncScheduler}
+ */
+export const async = asyncScheduler;

src/internal/scheduler/queue.ts

@@ -62,10 +62,10 @@ import { QueueScheduler } from './QueueScheduler';
  * // "before", 1
  * // "after", 1
  * ```
- *
- * @static true
- * @name queue
- * @owner Scheduler
  */
+export const queueScheduler = new QueueScheduler(QueueAction);
 
-export const queue = new QueueScheduler(QueueAction);
+/**
+ * @deprecated renamed. Use {@link queueScheduler}
+ */
+export const queue = queueScheduler;

src/internal/util/subscribeToIterable.ts

@@ -10,7 +10,7 @@ export const subscribeToIterable = <T>(iterable: Iterable<T>) => (subscriber: Su
       item = iterator.next();
     } catch (err) {
       subscriber.error(err);
-      return;
+      return subscriber;
     }
     if (item.done) {
       subscriber.complete();

src/operators/index.ts

@@ -45,8 +45,7 @@ export { materialize } from '../internal/operators/materialize';
 export { max } from '../internal/operators/max';
 export { merge } from '../internal/operators/merge';
 export { mergeAll } from '../internal/operators/mergeAll';
-export { mergeMap } from '../internal/operators/mergeMap';
-export { mergeMap as flatMap } from '../internal/operators/mergeMap';
+export { mergeMap, flatMap } from '../internal/operators/mergeMap';
 export { mergeMapTo } from '../internal/operators/mergeMapTo';
 export { mergeScan } from '../internal/operators/mergeScan';
 export { min } from '../internal/operators/min';