Deprecate aliased functions, update docs (#380)

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

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<Stream<X>> to Stream<X> by merging inner
  * streams to the outer. Event arrival times are preserved.
  * @returns {Stream<X>} 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,22 +393,28 @@ Stream.prototype.zip = function (f /*, ...streams*/) {
 
 import { switchLatest } from './combinator/switch'
 
+// @deprecated switch, use switchLatest instead
 export { switchLatest, switchLatest as switch }
 
 /**
  * Given a stream of streams, return a new stream that adopts the behavior
  * 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,22 +628,27 @@ Stream.prototype.debounce = function (period) {
 
 import { fromPromise, awaitPromises } from './combinator/promises'
 
+// @deprecated await, use awaitPromises instead
 export { fromPromise, awaitPromises, awaitPromises as await }
 
 /**
  * Await promises, turning a Stream<Promise<X>> into Stream<X>.  Preserves
  * event order, but timeshifts events based on promise resolution time.
  * @returns {Stream<X>} 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
 

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) {