fix(socket.io): improve close() function

[fantua]

The kind of change this PR does introduce

• a bug fix
• a new feature
• an update to the documentation
• a code change that improves performance
• other

Current behavior

After #4971 the usage of the close() function has become confusing and sometimes misleading.

Since close() now returns a Promise, I would expect the httpServer to close when the promise is resolved. However, this is not the case.

await io.close();
// httpServer not closed yet

Also, in order to catch all possible errors, I need to use a mixed style of async/await and callbacks:

io.close(error => {
  if (error) {
    // error here
  }
}).catch(error => {
  // another error here
});

New behavior

await io.close();
// httpServer closed

io.close().catch(error => {
  // all errors here
});

[fantua]

related to 72d61da

[fantua]

@darrachequesne could you please take a look? Thanks

[piotr-cz]

I think it's good moment to deprecate the error argument here:

socket.io/packages/socket.io/lib/index.ts

Line 807 in 91e1c8b

public async close(fn?: (err?: Error) => void): Promise<void> {

[darrachequesne]

Merged as bb0b480, and included in [email protected]. Thanks!

@piotr-cz we will do this in the next major release

Related: #4546

[piotr-cz]

@darrachequesne

How about deprecating the callback (docblock, docs) in minor/ patch version and removing in major version?