Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #449 from jprichardson/read-write-obj
BREAKING: fs.read() & fs.write() should return objects
- Loading branch information
Showing
5 changed files
with
237 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
# About `fs.read()` & `fs.write()` | ||
|
||
[`fs.read()`](https://nodejs.org/api/fs.html#fs_fs_read_fd_buffer_offset_length_position_callback) & [`fs.write()`](https://nodejs.org/api/fs.html#fs_fs_write_fd_buffer_offset_length_position_callback) are different from other `fs` methods in that their callbacks are called with 3 arguments instead of the usual 2 arguments. | ||
|
||
If you're using them with callbacks, they will behave as usual. However, their promise usage is a little different. `fs-extra` promisifies these methods like [`util.promisify()`](https://nodejs.org/api/util.html#util_util_promisify_original) (only availible in Node 8+) does. | ||
|
||
Here's the example promise usage: | ||
|
||
## `fs.read()` | ||
|
||
```js | ||
// Basic promises | ||
fs.read(fd, buffer, offset, length, position) | ||
.then(results => { | ||
console.log(results) | ||
// { bytesRead: 20, buffer: <Buffer 0f 34 5d ...> } | ||
}) | ||
|
||
// Async/await usage: | ||
async function example () { | ||
const { bytesRead, buffer } = await fs.read(fd, buffer, offset, length, position) | ||
} | ||
``` | ||
|
||
## `fs.write()` | ||
|
||
```js | ||
// Basic promises | ||
fs.write(fd, buffer, offset, length, position) | ||
.then(results => { | ||
console.log(results) | ||
// { bytesWritten: 20, buffer: <Buffer 0f 34 5d ...> } | ||
}) | ||
|
||
// Async/await usage: | ||
async function example () { | ||
const { bytesWritten, buffer } = await fs.write(fd, buffer, offset, length, position) | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,154 @@ | ||
'use strict' | ||
/* eslint-env mocha */ | ||
const assert = require('assert') | ||
const path = require('path') | ||
const crypto = require('crypto') | ||
const os = require('os') | ||
const semver = require('semver') | ||
const fs = require('../..') | ||
|
||
const SIZE = 1000 | ||
|
||
// Used for tests on Node 7.2.0+ only | ||
const onNode7it = semver.gte(process.version, '7.2.0') ? it : it.skip | ||
|
||
describe('fs.read()', () => { | ||
let TEST_FILE | ||
let TEST_DATA | ||
let TEST_FD | ||
|
||
beforeEach(() => { | ||
TEST_FILE = path.join(os.tmpdir(), 'fs-extra', 'read-test-file') | ||
TEST_DATA = crypto.randomBytes(SIZE) | ||
fs.writeFileSync(TEST_FILE, TEST_DATA) | ||
TEST_FD = fs.openSync(TEST_FILE, 'r') | ||
}) | ||
|
||
afterEach(() => { | ||
return fs.close(TEST_FD) | ||
.then(() => fs.remove(TEST_FILE)) | ||
}) | ||
|
||
describe('with promises', () => { | ||
it('returns an object', () => { | ||
return fs.read(TEST_FD, Buffer.alloc(SIZE), 0, SIZE, 0) | ||
.then(results => { | ||
const bytesRead = results.bytesRead | ||
const buffer = results.buffer | ||
assert.equal(bytesRead, SIZE, 'bytesRead is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
}) | ||
}) | ||
|
||
it('returns an object when position is not set', () => { | ||
return fs.read(TEST_FD, Buffer.alloc(SIZE), 0, SIZE) | ||
.then(results => { | ||
const bytesRead = results.bytesRead | ||
const buffer = results.buffer | ||
assert.equal(bytesRead, SIZE, 'bytesRead is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
}) | ||
}) | ||
}) | ||
|
||
describe('with callbacks', () => { | ||
it('works', done => { | ||
fs.read(TEST_FD, Buffer.alloc(SIZE), 0, SIZE, 0, (err, bytesRead, buffer) => { | ||
assert.ifError(err) | ||
assert.equal(bytesRead, SIZE, 'bytesRead is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
done() | ||
}) | ||
}) | ||
|
||
it('works when position is null', done => { | ||
fs.read(TEST_FD, Buffer.alloc(SIZE), 0, SIZE, null, (err, bytesRead, buffer) => { | ||
assert.ifError(err) | ||
assert.equal(bytesRead, SIZE, 'bytesRead is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
done() | ||
}) | ||
}) | ||
}) | ||
}) | ||
|
||
describe('fs.write()', () => { | ||
let TEST_FILE | ||
let TEST_DATA | ||
let TEST_FD | ||
|
||
beforeEach(() => { | ||
TEST_FILE = path.join(os.tmpdir(), 'fs-extra', 'write-test-file') | ||
TEST_DATA = crypto.randomBytes(SIZE) | ||
fs.ensureDirSync(path.dirname(TEST_FILE)) | ||
TEST_FD = fs.openSync(TEST_FILE, 'w') | ||
}) | ||
|
||
afterEach(() => { | ||
return fs.close(TEST_FD) | ||
.then(() => fs.remove(TEST_FILE)) | ||
}) | ||
|
||
describe('with promises', () => { | ||
it('returns an object', () => { | ||
return fs.write(TEST_FD, TEST_DATA, 0, SIZE, 0) | ||
.then(results => { | ||
const bytesWritten = results.bytesWritten | ||
const buffer = results.buffer | ||
assert.equal(bytesWritten, SIZE, 'bytesWritten is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
}) | ||
}) | ||
|
||
onNode7it('returns an object when minimal arguments are passed', () => { | ||
return fs.write(TEST_FD, TEST_DATA) | ||
.then(results => { | ||
const bytesWritten = results.bytesWritten | ||
const buffer = results.buffer | ||
assert.equal(bytesWritten, SIZE, 'bytesWritten is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
}) | ||
}) | ||
|
||
it('returns an object when writing a string', () => { | ||
const message = 'Hello World!' | ||
return fs.write(TEST_FD, message) | ||
.then(results => { | ||
const bytesWritten = results.bytesWritten | ||
const buffer = results.buffer | ||
assert.equal(bytesWritten, message.length, 'bytesWritten is correct') | ||
assert.equal(buffer, message, 'data is correct') | ||
}) | ||
}) | ||
}) | ||
|
||
describe('with callbacks', () => { | ||
it('works', done => { | ||
fs.write(TEST_FD, TEST_DATA, 0, SIZE, 0, (err, bytesWritten, buffer) => { | ||
assert.ifError(err) | ||
assert.equal(bytesWritten, SIZE, 'bytesWritten is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
done() | ||
}) | ||
}) | ||
|
||
onNode7it('works when minimal arguments are passed', done => { | ||
fs.write(TEST_FD, TEST_DATA, (err, bytesWritten, buffer) => { | ||
assert.ifError(err) | ||
assert.equal(bytesWritten, SIZE, 'bytesWritten is correct') | ||
assert(buffer.equals(TEST_DATA), 'data is correct') | ||
done() | ||
}) | ||
}) | ||
|
||
it('works when writing a string', done => { | ||
const message = 'Hello World!' | ||
return fs.write(TEST_FD, message, (err, bytesWritten, buffer) => { | ||
assert.ifError(err) | ||
assert.equal(bytesWritten, message.length, 'bytesWritten is correct') | ||
assert.equal(buffer, message, 'data is correct') | ||
done() | ||
}) | ||
}) | ||
}) | ||
}) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters