fix(NODE-4788)!: use implementer Writable methods for GridFSBucketWriteStream

[nbbeeken]

Description

What is changing?

• Remove overrides of stream methods
• Add overrides of _X stream methods that control the underlying implmentations
• Remove manual event emitting
• Ensure callback is always invoked asynchronously (nextTick)

Is there new documentation needed for these changes?

• TBD

What is the motivation for this change?

Node.js Streams are supposed to be implemented with the _X methods, the write & end functions are maintained by Node.js, the _ methods define the implementation of a stream.

Release Highlight

Corrected GridFSBucketWriteStream's Writable method overrides and event emission

Our implementation of a writeable stream for GridFSBucketWriteStream mistakenly overrode the write() and end() methods, as well as, manually emitted 'close', 'drain', 'finish' events. Per Node.js documentation, these methods and events are intended for the Node.js stream implementation to provide, and an author of a stream implementation is supposed to override _write, _final, and allow Node.js to manage event emitting.

Since the API is still a Writable stream most usages will continue to work with no changes, the .write() and .end() methods are still available and take the same arguments. The breaking change relates to the improper manually emitted event listeners that are now handled by Node.js. The 'finish' and 'drain' events will no longer receive the GridFSFile document as an argument (this is the document inserted to the bucket's files collection after all chunks have been inserted). Instead, it will be available on the stream itself as a property: gridFSFile.

// If our event handler is declared as a `function` "this" is bound to the stream.
fs.createReadStream('./file.txt')
  .pipe(bucket.openUploadStream('file.txt'))
  .on('finish', function () {
    console.log(this.gridFSFile)
  })

// If our event handler is declared using big arrow notation,
// the property is accessible on a scoped variable
const uploadStream = bucket.openUploadStream('file.txt')
fs.createReadStream('./file.txt')
  .pipe(uploadStream)
  .on('finish', () => console.log(uploadStream.gridFSFile))

Since the class no longer emits its own events: static constants GridFSBucketWriteStream.ERROR, GridFSBucketWriteStream.FINISH, GridFSBucketWriteStream.CLOSE have been removed to avoid confusion about the source of the events and the arguments their listeners accept.

Fix manually emitted events from GridFSBucketReadStream

The GridFSBucketReadStream internals have also been corrected to no longer emit events that are handled by Node's stream logic. Since the class no longer emits its own events: static constants GridFSBucketReadStream.ERROR, GridFSBucketReadStream.DATA, GridFSBucketReadStream.CLOSE, and GridFSBucketReadStream.END have been removed to avoid confusion about the source of the events and the arguments their listeners accept.

Double check the following

• Ran npm run check:lint script
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket