Home Manual Reference Source Test Repository

es6/MiscJSDoc.js

import { Observable } from './Observable';
import './observable/dom/MiscJSDoc';
/**
 * We need this JSDoc comment for affecting ESDoc.
 * @extends {Ignored}
 * @hide true
 */
export class ObservableDoc {
    /**
     * 创建一个新的 Observable ,当观察者( {@link Observer} )订阅该 Observable 时,它会执行指定的函数。
     *
     * <span class="informal">创建自定义的 Observable ,它可以做任何你想做的事情</span>
     *
     * <img src="./img/create.png" width="100%">
     *
     * `create` 将 `onSubscription` 函数转化为一个实际的 Observable 。每当有人订阅该 Observable 的
     * 时候,`onSubscription`函数会接收 {@link Observer} 实例作为唯一参数执行。`onSubscription` 应该
     * 调用观察者对象的 `next`, `error` 和 `complete` 方法。
     *
     * 带值调用 `next` 会将该值发出给观察者。调用 complete 意味着该 Observable 结束了发出并且不会做任何事情了。
     * 调用 `error` 意味着出现了错误,传给 `error` 的参数应该提供详细的错误信息。
     *
     * 一个格式良好的 Observable 可以通过 `next` 方法发出任意多个值,但是 `complete` 和 `error` 方法只能被调用
     * 一次,并且调用之后不会再调用任何方法。 如果你试图在 Observable 已经完成或者发生错误之后调用`next`、 `complete`
     * 或 `error` 方法,这些调用将会被忽略,以保护所谓的 Observable 合同。注意,你并不需要一定要在某个时刻
     * 调用 `complete` 方法,创建一个不会被终止的 Observable 也是完全可以的,一切取决于你的需求。
     *
     * `onSubscription` 可以选择性的返回一个函数或者一个拥有 `unsubscribe` 方法的对象。 当要取消对 Observable
     * 的订阅时,函数或者方法将会被调用,清理所有的资源。比如说,如果你在自己的 Observable 里面使用了
     * `setTimeout`, 当有人要取消订阅的时候, 你可以清理定时器, 这样就可以减少不必要的触发,并且浏览
     * 器(或者其他宿主环境)也不用将计算能力浪费在这种无人监听的定时事件上。
     *
     * 绝大多数情况下你不需要使用 `create`,因为现有的操作符创建出来的 Observable 能满足绝大多数使用场景。这也就意味着,
     * `create` 是允许你创建任何 Observable 的底层机制,如果你有非常特殊的需求的话,可以使用它。
     *
     * **TypeScript 签名问题**
     *
     * 因为 Observable 继承的类已经定义了静态 `create` 方法,但是签名不同, 不可能给 `Observable.create` 合适的签名。
     * 正因为如此,给 `create` 传递的函数将不会进行类型检查,除非你明确指定了特定的签名。
     *
     * 当使用 TypeScript 时,我们建议将传递给 create 的函数签名声明为`(observer: Observer) => TeardownLogic`,
     * 其中{@link Observer} 和 {@link TeardownLogic} 是库提供的接口。
     *
     * @example <caption>发出三个数字,然后完成。</caption>
     * var observable = Rx.Observable.create(function (observer) {
     *   observer.next(1);
     *   observer.next(2);
     *   observer.next(3);
     *   observer.complete();
     * });
     * observable.subscribe(
     *   value => console.log(value),
     *   err => {},
     *   () => console.log('this is the end')
     * );
     *
     * // 日志:
     * // 1
     * // 2
     * // 3
     * // "this is the end"
     *
     *
     * @example <caption>发出一个错误</caption>
     * const observable = Rx.Observable.create((observer) => {
     *   observer.error('something went really wrong...');
     * });
     *
     * observable.subscribe(
     *   value => console.log(value), // 永远不会被调用
     *   err => console.log(err),
     *   () => console.log('complete') // 永远不会被调用
     * );
     *
     * // 日志:
     * // "something went really wrong..."
     *
     *
     * @example <caption>返回取消订阅函数</caption>
     *
     * const observable = Rx.Observable.create(observer => {
     *   const id = setTimeout(() => observer.next('...'), 5000); // 5s后发出数据
     *
     *   return () => { clearTimeout(id); console.log('cleared!'); };
     * });
     *
     * const subscription = observable.subscribe(value => console.log(value));
     *
     * setTimeout(() => subscription.unsubscribe(), 3000); // 3s后取消订阅
     *
     * // 日志:
     * // "cleared!" after 3s
     *
     * // Never logs "..."
     *
     *
     * @see {@link empty}
     * @see {@link never}
     * @see {@link of}
     * @see {@link throw}
     *
     * @param {function(observer: Observer): TeardownLogic} onSubscription 该函数接受一个观察者,
     * 然后在适当的时机调用观察者的 `next` 、`error` 或者 `complete` 方法,也可以返回一些清理资源的逻辑。
     * @return {Observable} Observable, 当该 Observable 被订阅的时候将会执行特定函数。
     * @static true
     * @name create
     * @owner Observable
     */
    static create(onSubscription) {
        return new Observable(onSubscription);
    }
    ;
}
/**
 * 消费者接口,消费者接收由 {@link Observable} 推送的通知。
 *
 * ```ts
 * interface Observer<T> {
 *   closed?: boolean;
 *   next: (value: T) => void;
 *   error: (err: any) => void;
 *   complete: () => void;
 * }
 * ```
 *
 * 符合观察者接口规范的对象,通常用来传给 `observable.subscribe(observer)` 方法,同时
 * Observable 会调用观察者的 `next(value)` 提供通知。定义良好的 Observable 会确切的调用
 * 观察者的 `complete()` 或者 `error(err)` 方法一次,作为最后的通知。
 *
 * @interface
 * @name Observer
 * @noimport true
 */
export class ObserverDoc {
    constructor() {
        /**
         * 可选的标志位,用来表示该观察者作为订阅者时,是否已经对它观察的 Observable 取消了订阅。
         * @type {boolean}
         */
        this.closed = false;
    }
    /**
     * 该回调函数接收来自 Observable 的 `next` 类型(附带值)的通知。Observable 会调用这个方法0次或者多次。
     * @param {T} value  `next` 的值。
     * @return {void}
     */
    next(value) {
        return void 0;
    }
    /**
     * 该回调函数接收来自 Observable 的 `error` 类型(附带值)的通知,带着 {@link Error} 。通知观察者,
     * Observable 发生了错误。
     * @param {any} err `error` 异常。
     * @return {void}
     */
    error(err) {
        return void 0;
    }
    /**
     * 该回调函数接收来自于 Observable 的 `complete` 类型(附带值)的通知。通知观察者,Observable 已经
     * 完成了发送推送体系的通知。
     * @return {void}
     */
    complete() {
        return void 0;
    }
}
/**
 * `SubscribableOrPromise` 接口描述行为像 Observables 或者 Promises 的值。每个操作符
 * 接受被这个接口 annotate 过的参数,也可以使用不是 RxJS Observables 的参数。
 *
 * 下列类型的值可以传递给期望此接口的操作符:
 *
 * ## Observable
 *
 * RxJS {@link Observable} 实例。
 *
 * ## 类 Observable 对象 (Subscribable)
 *
 * 这可以是任何拥有 `Symbol.observable` 方法的对象。当这个方法被调用的时候,应该返回一个带有
 * `subscribe` 方法的对象,这个方法的行为应该和 RxJS 的 `Observable.subscribe` 一致。
 *
 * `Symbol.observable` 是 https://github.com/tc39/proposal-observable 提案的一部分。
 * 当实现一个自定义的类 Observable 对象,因为现在还没有被原生支持, 每个符号只和自己相等,你应该使用 https://github.com/blesh/symbol-observable 垫片。
 *
 * **TypeScript Subscribable 接口问题**
 *
 * 尽管 TypeScript 接口声明,可订阅对象是一个声明了 `subscribe` 方法的对象,但是传递定义了 `subscribe` 方法
 * 但是没有定义 `Symbol.observable` 方法的对象在运行时会失败。相反地,传递定义了 `Symbol.observable` 而没有
 * 定义 `subscribe` 的对象将会在编译时失败(如果你使用 TypeScript)。
 *
 * TypeScript 在支持定义了 symbol 属性方法的接口时是有问题的。为了绕过它,你应该直接实现
 * `subscribe` 方法,并且使 `Symbol.observable` 方法简单地返回 `this` 。这种方式能够
 * 起作用,编译器也不会报错。如果你真的不想添加 `subscribe` 方法,你可以在将其传递给操作符之前,
 * 将类型转化为 `any`。
 *
 * 当这个 issue 被解决了,可订阅的接口仅允许定义了 `Symbol.observable` 方法的类 Observable
 * 对象,无论该对象是否实现了 `subscribe` 方法。
 *
 * ## ES6 Promise
 *
 * Promise 可以被认为是 Observable,当 resolved 的时候,Observable 发出值并完成,
 * 当 rejected 的时候,Observable 发出错误。
 *
 * ## 类 Promise 对象 (可使用 then 方法的)
 *
 * 传递给操作符的 Promises 不需要是 ES6 原生的 Promises。可以直接使用流行库或垫片中的实现,甚至自己来实现。
 * 它只需要拥有 `then` 方法,并且该方法和 ES6 Promise 的 `then` 行为
 * 一致。
 *
 * @example <caption>用非 RxJS 的 observable 作为参数来使用 merge 和 map 操作符</caption>
 * const nonRxJSObservable = {
 *   subscribe(observer) {
 *     observer.next(1000);
 *     observer.complete();
 *   },
 *   [Symbol.observable]() {
 *     return this;
 *   }
 * };
 *
 * Rx.Observable.merge(nonRxJSObservable)
 * .map(value => "This value is " + value)
 * .subscribe(result => console.log(result)); // 输出 "This value is 1000"
 *
 *
 * @example <caption>用 ES6 的 Promise 来使用 combineLatest 操作符</caption>
 * Rx.Observable.combineLatest(Promise.resolve(5), Promise.resolve(10), Promise.resolve(15))
 * .subscribe(
 *   value => console.log(value),
 *   err => {},
 *   () => console.log('the end!')
 * );
 * // 输出:
 * // [5, 10, 15]
 * // "the end!"
 *
 *
 * @interface
 * @name SubscribableOrPromise
 * @noimport true
 */
export class SubscribableOrPromiseDoc {
}
/**
 * `ObservableInput` 接口描述了所有值是一个 {@link SubscribableOrPromise} 或者
 * 此类型的值可以转化为能发出值的 Observable 。
 * 每个操作符都可以接收被该接口 annotate 过的参数,而不一定需要是 RxJS 的 Observables。
 *
 * `ObservableInput` 继承了 {@link SubscribableOrPromise} ,拥有如下类型:
 *
 * ## 数组
 *
 * 数组可以被理解为,observables 会从左到右,一个接一个地发送数组的所有值,然后立即完成。
 *
 * ## 类数组
 *
 * 传递给操作符的数组也可以不是 JavaScript 内置的数组。它们还可以是其他的,例如,每个函数的 `arguments`
 * 属性,[DOM NodeList](https://developer.mozilla.org/pl/docs/Web/API/NodeList),或者实际上,
 * 拥有 `length` 属性(是个数字)的对象 并且存储了大于0个数。
 *
 * ## ES6 迭代器
 *
 * 操作符可以接收内置的和自定义的 ES6 迭代器,把它们当做 observables 通过顺序的发出迭代器的所有值,
 * 然后当迭代器完成的时候,触发完成。注意和数组的区别,迭代器不需要是有限的,应该创建一个永远不会完成
 * 的 Observables 使之成为可能。
 *
 * 注意,通过在 `Symbol.iterator` 方法中返回自身,你可以迭代迭代器实例。这意味着每个操作符接收可迭代对象,
 * 但是间接的,迭代器本身也可以。所有原生 ES6 的迭代器默认都是 Iterable 的实例,所以你不需要自己实现 `Symbol.iterator` 方法。
 *
 * **TypeScript Iterable 接口 issue **
 *
 * TypeScript `ObservableInput` 接口实际上缺乏 Iterables 的类型签名,
 * 由于一些项目造成的 issue (查看 [this issue](https://github.com/ReactiveX/rxjs/issues/2306)).
 * 如果你想给操作符传递 Iterable, 首先将它转化为 `any`。当然要铭记,因为类型转化,你需要确保传递的参数
 * 确实实现了此接口。
 *
 *
 * @example <caption>用数组使用 merge 操作符</caption>
 * Rx.Observable.merge([1, 2], [4], [5, 6])
 * .subscribe(
 *   value => console.log(value),
 *   err => {},
 *   () => console.log('ta dam!')
 * );
 *
 * // 日志:
 * // 1
 * // 2
 * // 3
 * // 4
 * // 5
 * // 6
 * // "ta dam!"
 *
 *
 * @example <caption>用类数组使用 merge 操作符</caption>
 * Rx.Observable.merge({0: 1, 1: 2, length: 2}, {0: 3, length: 1})
 * .subscribe(
 *   value => console.log(value),
 *   err => {},
 *   () => console.log('nice, huh?')
 * );
 *
 * // 日志:
 * // 1
 * // 2
 * // 3
 * // "nice, huh?"
 *
 * @example <caption>用 Iterable (Map) 使用 merge 操作符</caption>
 * const firstMap = new Map([[1, 'a'], [2, 'b']]);
 * const secondMap = new Map([[3, 'c'], [4, 'd']]);
 *
 * Rx.Observable.merge(
 *   firstMap,          // 传递 Iterable
 *   secondMap.values() // 传递 iterator, 它本身就是 Iterable
 * ).subscribe(
 *   value => console.log(value),
 *   err => {},
 *   () => console.log('yup!')
 * );
 *
 * // 日志:
 * // [1, "a"]
 * // [2, "b"]
 * // "c"
 * // "d"
 * // "yup!"
 *
 * @example <caption>用 generator(返回无限的 iterator)使用 from 操作符</caption>
 * // 无限的自增数列流
 * const infinite = function* () {
 *   let i = 0;
 *
 *   while (true) {
 *     yield i++;
 *   }
 * };
 *
 * Rx.Observable.from(infinite())
 * .take(3) // 因为是无限的,仅仅取前三个
 * .subscribe(
 *   value => console.log(value),
 *   err => {},
 *   () => console.log('ta dam!')
 * );
 *
 * // 日志:
 * // 0
 * // 1
 * // 2
 * // "ta dam!"
 *
 * @interface
 * @name ObservableInput
 * @noimport true
 */
export class ObservableInputDoc {
}
/**
 *
 * 这个接口描述了 Observable 构造函数和静态方法 {@link create} 接收的函数的返回对象。这个接口
 * 的值可以用来取消对当前 Observable 的订阅。
 *
 * `TeardownLogic` 可以是:
 *
 * ## 函数
 *
 * 该函数不接收参数。 当创建的 Observable 的消费者调用 `unsubscribe`时,该函数被调用。
 *
 * ## AnonymousSubscription
 *
 * `AnonymousSubscription` 是一个拥有 `unsubscribe` 方法的简单对象。 该方法和上面函数行为一致。
 *
 * ## void
 *
 * 如果创建的 Observable 不需要清理任何资源,该函数不需要返回任何值。
 *
 * @interface
 * @name TeardownLogic
 * @noimport true
 */
export class TeardownLogicDoc {
}
//# sourceMappingURL=MiscJSDoc.js.map