[Pkg-javascript-commits] [node-read-only-stream] 05/22: docs

[Bastien Roucariès]

This is an automated email from the git hooks/post-receive script.

rouca pushed a commit to branch master
in repository node-read-only-stream.

commit d6b7b8384e123694344f2249dd163d7c25f6da19
Author: James Halliday <mail at substack.net>
Date:   Mon Sep 8 11:22:04 2014 +0100

    docs
---
 readme.markdown | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/readme.markdown b/readme.markdown
new file mode 100644
index 0000000..4b1932c
--- /dev/null
+++ b/readme.markdown
@@ -0,0 +1,58 @@
+# read-only-stream
+
+wrap a readable/writable stream to be read-only
+to prevent mucking up the input side
+
+# example
+
+Suppose you have a module that uses a readable/writable stream internally but
+want to expose just the readable part of that internal stream. This is common if
+you use the writable side internally and expose the readable side as the
+interface.
+
+Now we can write some code like this with a `through` stream internally for
+convenience:
+
+``` js
+var through = require('through2');
+var readonly = require('read-only-stream');
+
+module.exports = function () {
+    var stream = through();
+    stream.end('wooooo\n');
+    return readonly(stream);
+};
+```
+
+but consumers won't be able to write to the input side and break the api:
+
+``` js
+var wrap = require('./wrap.js');
+var ro = wrap(); // can't write to `ro` and muck up internal state
+ro.pipe(process.stdout);
+```
+
+# methods
+
+``` js
+var readonly = require('read-only-stream')
+```
+
+## var ro = readonly(stream)
+
+Return a readable stream `ro` that wraps the readable/writable `stream` argument
+given to only expose the readable side.
+
+`stream` can be a streams1 or streams2 stream.
+
+# install
+
+With [npm](https://npmjs.org) do:
+
+```
+npm install read-only-stream
+```
+
+# license
+
+MIT

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-read-only-stream.git