From ef629f5efd05569a0ef3a2eb1b981e01aab29574 Mon Sep 17 00:00:00 2001 From: Brian Cavalier Date: Wed, 11 Jan 2017 21:07:23 -0500 Subject: [PATCH] Deprecate aliased functions, update docs (#380) --- docs/api.md | 51 +++++++++++++++++++++++------------------- src/index.js | 50 ++++++++++++++++++++++++++++++++--------- src/source/periodic.js | 6 ++--- 3 files changed, 71 insertions(+), 36 deletions(-) diff --git a/docs/api.md b/docs/api.md index 5fc7a75e..d5bd6b94 100644 --- a/docs/api.md +++ b/docs/api.md @@ -7,7 +7,7 @@ most.js API 1. API Notes * [Draft ES Observable interop](#draft-es-observable-interop) 1. Creating streams - * [most.of](#mostof), alias [most.just](#mostof) + * [most.just](#mostjust), alias [most.of](#mostjust) * [most.fromPromise](#mostfrompromise) * [most.from](#mostfrom) * [most.periodic](#mostperiodic) @@ -69,7 +69,7 @@ most.js API * [join](#join) * [mergeConcurrently](#mergeconcurrently) 1. Awaiting promises - * [await](#await) + * [awaitPromises](#awaitPromises), alias [await](#awaitPromises) 1. Rate limiting streams * [debounce](#debounce) * [throttle](#throttle) @@ -182,12 +182,12 @@ most.combineArray(combineFunction, arrayOfObservables.map(from)) ## Creating streams -### most.of +### most.just -ES6 import-friendly alias: `most.just` +Alias: `most.of` -####`most.of(x) -> Stream` ####`most.just(x) -> Stream` +####`most.of(x) -> Stream` ``` most.of(x): x| @@ -269,14 +269,17 @@ stream.take(100) ### most.periodic -####`most.periodic(period, x) -> Stream` +####`most.periodic(period) -> Stream` +####`most.periodic(period, x) -> Stream` (deprecated) + +**Note:** periodic's second argument (`x`) is deprecated. To create a periodic stream with a specific value use `constant(x, periodic(period))` ``` -most.periodic(2, x): x-x-x-x-x-x-> -most.periodic(5, x): x----x----x-> +most.periodic(2): x-x-x-x-x-x-> (x === undefined) +most.periodic(5, a): a----a----a-> ``` -Create an infinite stream containing events that arrive every `period` milliseconds, and whose value is `x`. +Create an infinite stream containing events that arrive every `period` milliseconds, and whose value is `undefined`. ### most.empty @@ -1418,19 +1421,21 @@ To control concurrency, `mergeConcurrently` must maintain an internal queue of n ## Awaiting promises -### await +### awaitPromises + +Deprecated alias: `await` -####`stream.await() -> Stream` -####`most.await(stream) -> Stream` +####`stream.awaitPromises() -> Stream` +####`most.awaitPromises(stream) -> Stream` Given a stream of promises, ie Stream<Promise<X>>, return a new stream containing the fulfillment values, ie Stream<X>. ``` -promise p: ---1 -promise q: ------2 -promise r: -3 -stream: -p---q---r-> -stream.await(): ---1--2--3-> +promise p: ---1 +promise q: ------2 +promise r: -3 +stream: -p---q---r-> +stream.awaitPromises(): ---1--2--3-> ``` Event *times* may be delayed. However, event *order* is always preserved, regardless of promise fulfillment order. @@ -1444,17 +1449,17 @@ promise q: --------2 promise r: ------3 stream: -p-q-r-----> stream.chain(most.fromPromise): --1---3-2--> -stream.await(): --1-----23-> +stream.awaitPromises(): --1-----23-> ``` If a promise rejects, the stream will be in an error state with the rejected promise's reason as its error. See [recoverWith](#recoverwith) for error recovery. For example: ``` -promise p: ---1 -promise q: ------X -promise r: -3 -stream: -p---q---r-> -stream.await(): ---1--X +promise p: ---1 +promise q: ------X +promise r: -3 +stream: -p---q---r-> +stream.awaitPromises(): ---1--X ``` ```es6 diff --git a/src/index.js b/src/index.js index f867189f..fa82d08f 100644 --- a/src/index.js +++ b/src/index.js @@ -237,6 +237,7 @@ Stream.prototype.transduce = function (transducer) { import { flatMap, join } from './combinator/flatMap' +// @deprecated flatMap, use chain instead export { flatMap, flatMap as chain, join } /** @@ -245,11 +246,14 @@ export { flatMap, flatMap as chain, join } * @param {function(x:*):Stream} f chaining function, must return a Stream * @returns {Stream} new stream containing all events from each stream returned by f */ -Stream.prototype.flatMap = Stream.prototype.chain = function (f) { +Stream.prototype.chain = function (f) { return flatMap(f, this) } -/** +// @deprecated use chain instead +Stream.prototype.flatMap = Stream.prototype.chain + + /** * Monadic join. Flatten a Stream> to Stream by merging inner * streams to the outer. Event arrival times are preserved. * @returns {Stream} new stream containing all events of all inner streams @@ -260,6 +264,7 @@ Stream.prototype.join = function () { import { continueWith } from './combinator/continueWith' +// @deprecated flatMapEnd, use continueWith instead export { continueWith, continueWith as flatMapEnd } /** @@ -269,10 +274,13 @@ export { continueWith, continueWith as flatMapEnd } * @returns {Stream} new stream that emits all events from the original stream, * followed by all events from the stream returned by f. */ -Stream.prototype.continueWith = Stream.prototype.flatMapEnd = function (f) { +Stream.prototype.continueWith = function (f) { return continueWith(f, this) } +// @deprecated use continueWith instead +Stream.prototype.flatMapEnd = Stream.prototype.continueWith + import { concatMap } from './combinator/concatMap' export { concatMap } @@ -385,6 +393,7 @@ Stream.prototype.zip = function (f /*, ...streams*/) { import { switchLatest } from './combinator/switch' +// @deprecated switch, use switchLatest instead export { switchLatest, switchLatest as switch } /** @@ -392,15 +401,20 @@ export { switchLatest, switchLatest as switch } * of the most recent inner stream. * @returns {Stream} switching stream */ -Stream.prototype.switch = Stream.prototype.switchLatest = function () { +Stream.prototype.switchLatest = function () { return switchLatest(this) } +// @deprecated use switchLatest instead +Stream.prototype.switch = Stream.prototype.switchLatest + // ----------------------------------------------------------------------- // Filtering import { filter, skipRepeats, skipRepeatsWith } from './combinator/filter' +// @deprecated distinct, use skipRepeats instead +// @deprecated distinctBy, use skipRepeatsWith instead export { filter, skipRepeats, skipRepeats as distinct, skipRepeatsWith, skipRepeatsWith as distinctBy } /** @@ -499,6 +513,8 @@ Stream.prototype.skipWhile = function (p) { import { takeUntil, skipUntil, during } from './combinator/timeslice' +// @deprecated takeUntil, use until instead +// @deprecated skipUntil, use since instead export { takeUntil, takeUntil as until, skipUntil, skipUntil as since, during } /** @@ -510,11 +526,14 @@ export { takeUntil, takeUntil as until, skipUntil, skipUntil as since, during } * @returns {Stream} new stream containing only events that occur before * the first event in signal. */ -Stream.prototype.until = Stream.prototype.takeUntil = function (signal) { +Stream.prototype.until = function (signal) { return takeUntil(signal, this) } -/** +// @deprecated use until instead +Stream.prototype.takeUntil = Stream.prototype.until + + /** * stream: -a-b-c-d-e-f-g-> * signal: -------x * takeUntil(signal, stream): -------d-e-f-g-> @@ -523,11 +542,14 @@ Stream.prototype.until = Stream.prototype.takeUntil = function (signal) { * @returns {Stream} new stream containing only events that occur after * the first event in signal. */ -Stream.prototype.since = Stream.prototype.skipUntil = function (signal) { +Stream.prototype.since = function (signal) { return skipUntil(signal, this) } -/** +// @deprecated use since instead +Stream.prototype.skipUntil = Stream.prototype.since + + /** * stream: -a-b-c-d-e-f-g-> * timeWindow: -----s * s: -----t @@ -606,6 +628,7 @@ Stream.prototype.debounce = function (period) { import { fromPromise, awaitPromises } from './combinator/promises' +// @deprecated await, use awaitPromises instead export { fromPromise, awaitPromises, awaitPromises as await } /** @@ -613,15 +636,19 @@ export { fromPromise, awaitPromises, awaitPromises as await } * event order, but timeshifts events based on promise resolution time. * @returns {Stream} stream containing non-promise values */ -Stream.prototype.await = function () { +Stream.prototype.awaitPromises = function () { return awaitPromises(this) } +// @deprecated use awaitPromises instead +Stream.prototype.await = Stream.prototype.awaitPromises + // ----------------------------------------------------------------------- // Error handling import { recoverWith, flatMapError, throwError } from './combinator/errors' +// @deprecated flatMapError, use recoverWith instead export { recoverWith, flatMapError, throwError } /** @@ -633,10 +660,13 @@ export { recoverWith, flatMapError, throwError } * @param {function(error:*):Stream} f function which returns a new stream * @returns {Stream} new stream which will recover from an error by calling f */ -Stream.prototype.recoverWith = Stream.prototype.flatMapError = function (f) { +Stream.prototype.recoverWith = function (f) { return flatMapError(f, this) } +// @deprecated use recoverWith instead +Stream.prototype.flatMapError = Stream.prototype.recoverWith + // ----------------------------------------------------------------------- // Multicasting diff --git a/src/source/periodic.js b/src/source/periodic.js index 1a36f0c2..93b7c445 100644 --- a/src/source/periodic.js +++ b/src/source/periodic.js @@ -8,11 +8,11 @@ import PropagateTask from '../scheduler/PropagateTask' /** * Create a stream that emits the current time periodically * @param {Number} period periodicity of events in millis - * @param {*} value value to emit each period + * @param {*} deprecatedValue @deprecated value to emit each period * @returns {Stream} new stream that emits the current time every period */ -export function periodic (period, value) { - return new Stream(new Periodic(period, value)) +export function periodic (period, deprecatedValue) { + return new Stream(new Periodic(period, deprecatedValue)) } function Periodic (period, value) {