from and of: Return read-only channels.

doc/API.md

@@ -9,10 +9,11 @@
   - [value()](#value)
 - [Array-like Properties](#array-like-properties)
   - [Channel](#channel)
-    - [Channel([bufferLength = 0]) -> Channel](#channelbufferlength--0---channel)
+    - [Channel([bufferLength]) -> Channel](#channelbufferlength---channel)
     - [Channel.isChannel(value) -> Boolean](#channelischannelvalue---boolean)
-    - [Channel.of(...values) -> Channel](#channelofvalues---channel)
-    - [Channel.from(callback | iterable | stream.Readable[, mapfn [, thisArg]]) -> Channel](#channelfromcallback--iterable--streamreadable-mapfn--thisarg---channel)
+    - [Channel.of(...values) -> read-only Channel](#channelofvalues---read-only-channel)
+    - [Channel.from(callback | iterable | stream.Readable[, mapfn [, thisArg]]) -> read-only Channel](#channelfromcallback--iterable--streamreadable-mapfn--thisarg---read-only-channel)
+      - [Examples](#examples-1)
   - [Channel Object](#channel-object)
     - [every(callbackfn[, thisArg]) -> async Boolean](#everycallbackfn-thisarg---async-boolean)
     - [filter(callbackfn[, thisArg]) -> Channel](#filtercallbackfn-thisarg---channel)
@@ -160,11 +161,11 @@ to push up to `bufferLength` values before blocking.
 
 Return `true` if `value` is a channel, `false` otherwise.
 
-### Channel.of(...values) -> Channel
+### Channel.of(...values) -> read-only Channel
 
 Push `values` into a new channel and then close it.
 
-### Channel.from(callback | iterable | stream.Readable[, mapfn [, thisArg]]) -> Channel
+### Channel.from(callback | iterable | stream.Readable[, mapfn [, thisArg]]) -> read-only Channel
 
 Create a new `Channel` from a callback function, an iterable, or a [Node.js
 readable stream](https://nodejs.org/api/stream.html#stream_readable_streams).
@@ -176,6 +177,29 @@ pushing into the channel.  Close the channel when the function returns
 If the optional `mapfn` argument is provided, call it (using the also optional
 `thisArg`) on each value before pushing it into the channel.
 
+#### Examples
+
+```JavaScript
+const randomValues = Channel.from(Math.random);
+
+const fromArray = Channel.from([0, 1, 2]);
+
+const generator = function*() {
+  let counter = 0;
+
+  for (;;) {
+    yield counter;
+    counter++;
+  }
+};
+
+const fromGenerator = Channel.from(generator());
+
+const fromStream = Channel.from(
+  fs.createReadStream(`Communicating Sequential Processes.pdf`)
+);
+```
+
 ## Channel Object
 
 ### every(callbackfn[, thisArg]) -> async Boolean

lib/index.js

@@ -349,7 +349,7 @@ Channel.from = (values, mapfn, thisArg) => {
     }
   })();
 
-  return mapfn ? channel.map(mapfn, thisArg) : channel;
+  return (mapfn ? channel.map(mapfn, thisArg) : channel).readOnly();
 };
 
 Channel.of = (...values) => Channel.from(values);

test/index.js

@@ -45,6 +45,7 @@ describe(`Channel`, function() {
   });
 
   describe(`from`, function() {
+    describe(`types`, function() {
       it(`callback`, async function() {
         let counter = 0;
         const callback = () => (counter < 3 ? counter++ : undefined);
@@ -55,7 +56,16 @@ describe(`Channel`, function() {
         assert.deepEqual(await Channel.from([0, 1, 2]).values(), [0, 1, 2]);
       });
 
-    it(`mapfn`, async function() {
+      it(`Node.js's stream.Readable`, async function() {
+        const readable = stream.PassThrough({ objectMode: true });
+        readable.write(0);
+        readable.write(1);
+        readable.end(2);
+        assert.deepEqual(await Channel.from(readable).values(), [0, 1, 2]);
+      });
+    });
+
+    it(`with mapfn`, async function() {
       assert.deepEqual(
         await Channel.from([`a`, `b`, `c`], value =>
           value.toUpperCase()
@@ -64,12 +74,8 @@ describe(`Channel`, function() {
       );
     });
 
-    it(`Node.js's stream.readOnly`, async function() {
-      const readOnly = stream.PassThrough({ objectMode: true });
-      readOnly.write(0);
-      readOnly.write(1);
-      readOnly.end(2);
-      assert.deepEqual(await Channel.from(readOnly).values(), [0, 1, 2]);
+    it(`returns a readOnly channel`, function() {
+      assert(!(`push` in Channel.from([0, 1, 2])));
     });
   });
 
@@ -81,7 +87,9 @@ describe(`Channel`, function() {
   });
 
   it(`of`, async function() {
-    assert.deepEqual(await Channel.of(0, 1, 2).values(), [0, 1, 2]);
+    const channel = Channel.of(0, 1, 2);
+    assert(!(`push` in channel));
+    assert.deepEqual(await channel.values(), [0, 1, 2]);
   });
 
   describe(`select`, function() {