Add fs utility to write data to a file

Author: kgryte

lib/node_modules/@stdlib/fs/write-file/README.md

@@ -0,0 +1,205 @@
+# Write File
+
+> Write data to a file.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var writeFile = require( '@stdlib/fs/write-file' );
+```
+
+#### writeFile( file, data, \[options,] clbk )
+
+Asynchronously write `data` to a `file`.
+
+```javascript
+var join = require( 'path' ).join;
+
+var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
+
+writeFile( fpath, 'beep boop\n', onWrite );
+
+function onWrite( error, data ) {
+    if ( error ) {
+        throw error;
+    }
+}
+```
+
+The `data` argument may be either a `string` or a [`Buffer`][@stdlib/buffer/ctor].
+
+```javascript
+var join = require( 'path' ).join;
+var string2buffer = require( '@stdlib/buffer/from-string' );
+
+var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
+
+writeFile( fpath, string2buffer( 'beep boop\n' ), onWrite );
+
+function onWrite( error, data ) {
+    if ( error ) {
+        throw error;
+    }
+}
+```
+
+The function accepts the same `options` and has the same defaults as [`fs.writeFile()`][node-fs].
+
+#### writeFile.sync( file, data\[, options] )
+
+Synchronously writes `data` to a `file`.
+
+```javascript
+var join = require( 'path' ).join;
+
+var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
+
+var err = writeFile.sync( fpath, 'beep boop\n' );
+if ( err instanceof Error ) {
+    throw err;
+}
+```
+
+The function accepts the same `options` and has the same defaults as [`fs.writeFileSync()`][node-fs].
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The difference between this `writeFile.sync` and [`fs.writeFileSync()`][node-fs] is that [`fs.writeFileSync()`][node-fs] will throw if an `error` is encountered (e.g., if given a non-existent directory path) and this API will return an `error`. Hence, the following anti-pattern
+
+    <!-- run-disable -->
+
+    ```javascript
+    var fs = require( 'fs' );
+
+    // Check for directory path existence to prevent an error being thrown...
+    if ( fs.existsSync( '/path/to' ) ) {
+        fs.writeFileSync( '/path/to/file.txt', 'beep boop\n' );
+    }
+    ```
+
+    can be replaced by an approach which addresses existence via `error` handling.
+
+    <!-- run-disable -->
+
+    ```javascript
+    var writeFile = require( '@stdlib/fs/write-file' );
+
+    // Explicitly handle the error...
+    var err = writeFile.sync( '/path/to/file.txt', 'beep boop\n' );
+    if ( err instanceof Error ) {
+        // You choose what to do...
+        throw err;
+    }
+    ```
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var join = require( 'path' ).join;
+var writeFile = require( '@stdlib/fs/write-file' );
+
+var fpath = join( __dirname, 'examples', 'fixtures', 'file.txt' );
+
+// Synchronously write data to a file:
+var err = writeFile.sync( fpath, 'beep boop\n', 'utf8' );
+// returns null
+
+console.log( err instanceof Error );
+// => false
+
+// Asynchronously write data to a file:
+writeFile( fpath, 'beep boop\n', onWrite );
+
+function onWrite( error ) {
+    if ( error ) {
+        console.error( 'Error: %s', error.message );
+    }
+    console.log( 'Success!' );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+* * *
+
+<section class="cli">
+
+## CLI
+
+<section class="usage">
+
+### Usage
+
+```text
+Usage: writefile [options] <filepath>
+
+Options:
+
+  -h,    --help                Print this message.
+  -V,    --version             Print the package version.
+  --enc, --encoding encoding   Encoding. Default: 'utf8'.
+         --flag flag           Flag. Default: 'r'.
+         --mode mode           Mode. Default: 0o666.
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+### Notes
+
+-   Relative output file paths are resolved relative to the current working directory.
+-   Errors are written to `stderr`.
+-   File contents should be provided over `stdin` as part of a [standard stream][standard-stream] pipeline.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+### Examples
+
+```bash
+$ printf 'beep boop\n' | writefile ./examples/fixtures/file.txt
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.cli -->
+
+<section class="links">
+
+[node-fs]: https://nodejs.org/api/fs.html
+
+[@stdlib/buffer/ctor]: https://github.com/stdlib-js/stdlib
+
+[standard-stream]: http://en.wikipedia.org/wiki/Pipeline_%28Unix%29
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/fs/write-file/benchmark/benchmark.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// MODULES //
+
+var join = require( 'path' ).join;
+var bench = require( '@stdlib/bench' );
+var readFile = require( '@stdlib/fs/read-file' ).sync;
+var pkg = require( './../package.json' ).name;
+var writeFile = require( './../lib' );
+
+
+// FIXTURES //
+
+var FILE = join( __dirname, 'fixtures', 'file.txt' );
+var DATA = readFile( FILE );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var i;
+
+	i = 0;
+	b.tic();
+
+	return next();
+
+	function next() {
+		i += 1;
+		if ( i <= b.iterations ) {
+			return writeFile( FILE, DATA, done );
+		}
+		b.toc();
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+
+	function done( error ) {
+		if ( error ) {
+			b.fail( error.message );
+		}
+		next();
+	}
+});
+
+bench( pkg+':sync', function benchmark( b ) {
+	var out;
+	var i;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		out = writeFile.sync( FILE, DATA );
+		if ( out instanceof Error ) {
+			b.fail( out.message );
+		}
+	}
+	b.toc();
+	if ( out instanceof Error ) {
+		b.fail( out.message );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/fs/write-file/benchmark/fixtures/file.txt

@@ -0,0 +1 @@
+beep boop

lib/node_modules/@stdlib/fs/write-file/bin/cli

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+'use strict';
+
+// MODULES //
+
+var resolve = require( 'path' ).resolve;
+var readFileSync = require( '@stdlib/fs/read-file' ).sync;
+var CLI = require( '@stdlib/tools/cli' );
+var stdin = require( '@stdlib/utils/read-stdin' );
+var cwd = require( '@stdlib/utils/cwd' );
+var writeFile = require( './../lib' );
+
+
+// FUNCTIONS //
+
+/**
+* Callback invoked upon writing a file.
+*
+* @private
+* @param {Error} [error] - error object
+* @returns {void}
+*/
+function onWrite( error ) {
+	if ( error ) {
+		process.exitCode = 1;
+		return console.error( 'Error: %s', error.message ); // eslint-disable-line no-console
+	}
+} // end FUNCTION onWrite()
+
+
+// MAIN //
+
+/**
+* Main execution sequence.
+*
+* @private
+* @returns {void}
+*/
+function main() {
+	var flags;
+	var fpath;
+	var args;
+	var opts;
+	var cli;
+
+	// Create a command-line interface:
+	cli = new CLI({
+		'pkg': require( './../package.json' ),
+		'options': require( './../etc/cli_opts.json' ),
+		'help': readFileSync( resolve( __dirname, '..', 'docs', 'usage.txt' ), {
+			'encoding': 'utf8'
+		})
+	});
+
+	// Get any provided command-line arguments:
+	args = cli.args();
+
+	// Get any provided command-line flags:
+	flags = cli.flags();
+
+	opts = {};
+	if ( flags.encoding ) {
+		opts.encoding = flags.encoding;
+	}
+	if ( flags.flag ) {
+		opts.flag = flags.flag;
+	}
+	if ( flags.mode ) {
+		opts.mode = parseInt( flags.mode, 8 );
+	}
+	fpath = resolve( cwd(), args[ 0 ] );
+
+	// Gather data from `stdin`...
+	return stdin( onRead );
+
+	/**
+	* Callback invoked upon reading from `stdin`.
+	*
+	* @private
+	* @param {(Error|null)} error - error object
+	* @param {Buffer} data - data
+	* @returns {void}
+	*/
+	function onRead( error, data ) {
+		if ( error ) {
+			process.exitCode = 1;
+			return console.error( 'Error: %s', error.message ); // eslint-disable-line no-console
+		}
+		writeFile( fpath, data, opts, onWrite );
+	} // end FUNCTION onRead()
+} // end FUNCTION main()
+
+main();