The debug package was not included anymore in the dev bundle since the
migration from webpack to rollup ([1]) in version 6.0.0.
[1]: 27de300de4
See also: 4683a954d4
This commit adds the ability to provide a list of transport
implementations to use when connecting to an Engine.IO server.
This can be used to use HTTP long-polling based on `fetch()`, instead
of the default implementation based on the `XMLHttpRequest` object.
```
import { Socket, Fetch, WebSocket } from "engine.io-client";
const socket = new Socket({
transports: [Fetch, WebSocket]
});
```
This is useful in some environments that do not provide a
`XMLHttpRequest` object, like Chrome extension background scripts.
> XMLHttpRequest() can't be called from a service worker, extension or
otherwise. Replace calls from your background script to
XMLHttpRequest() with calls to global fetch().
Source: https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers#replace-xmlhttprequest
Related:
- https://github.com/socketio/engine.io-client/issues/716
- https://github.com/socketio/socket.io/issues/4980
This is also useful when running the client with Deno or Bun, as it
allows to use the built-in `fetch()` method and `WebSocket` object,
instead of using the `xmlhttprequest-ssl` and `ws` Node.js packages.
Related: https://github.com/socketio/socket.io-deno/issues/12
This feature also comes with the ability to exclude the code related to
unused transports (a.k.a. "tree-shaking"):
```js
import { SocketWithoutUpgrade, WebSocket } from "engine.io-client";
const socket = new SocketWithoutUpgrade({
transports: [WebSocket]
});
```
In that case, the code related to HTTP long-polling and WebTransport
will be excluded from the final bundle.
Related: https://github.com/socketio/socket.io/discussions/4393
WebTransport being a stream-based protocol, the chunking boundaries are
not necessarily preserved. That's why we need a header indicating the
type of the payload (plain text or binary) and its length.
See also: a306db09e8
This major bump creates a lot of noise, but it is necessary for
prettier to be able to parse new syntax such as:
- typed imports: `import { type xxx } from ...`
- private attributes: `class A { #b; #c() {} }`
This commit allows to:
- provide an ESM version of those modules ([1])
- reduce the attack surface in case of supply chain attacks
- reduce the size of the bundle with tree-shaking
As a downside, we won't receive security updates for those modules
anymore.
[1]: https://github.com/socketio/socket.io-client/issues/1536
The server will now include a "maxPayload" field in the handshake
details, allowing the clients to decide how many packets they have to
send to stay under the maxHttpBufferSize value.
Related:
- https://github.com/socketio/socket.io-client/issues/1531
- 088dcb4dff
This restores the possibility to import the bundle directly, without
getting the following error:
> [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './dist/engine.io.min.js' is not defined by "exports"
Some bundlers (like vite) do not support having a "browser" field in a
nested package.json.
Note: the previous commit ([1]) fixed the resolution of the "browser"
field in the dev bundle, but the production bundle still failed.
Related: https://github.com/socketio/socket.io-client/issues/1504
[1]: 49719142f6
Removing the debug library and the debug calls from the final bundle is
unexpectedly quite hard.
Actually, there are several solutions, each with its own pro and cons:
> use webpack-remove-debug (our previous solution)
Pro: works well, even with ESM imports with a little hack
```js
import debugModule from "debug"; // debug()
const debug = debugModule("my-library"); // debug()
debug("hello world");
```
Cons: only for webpack
See also: https://github.com/johngodley/webpack-remove-debug
> NODE_ENV variable
```js
import debugModule from "debug";
let debug = () => {}
if (process.env.NODE_ENV !== "production") {
debug = debugModule("my-library");
}
```
Pro: the `debug()` calls are properly removed when bundling for
production
Cons: some bundlers leave the debug library in the bundle, even if it
is not called (for example, rollup needs an additional
"moduleSideEffects: true")
Reference: https://rollupjs.org/guide/en/#treeshake
> dynamic import
```js
let debug = () => {}
if (process.env.NODE_ENV !== "production") {
import("debug").then(debugModule => {
debug = debugModule.default("my-library");
});
}
```
Pro: the sanest solution, which allows to use debug in development
Cons: will likely break some bundlers due to the dynamic import (for
example, not supported for UMD bundles)
> browser field
```json
{
"browser": {
"debug": "./noop.js"
}
}
```
Pro: the safest solution from a compatibility point of view
Cons: some bundlers leave the noop debug calls, even after minification
> remove debug from the source code
We could also remove the debug calls, but the ability to turn them with
a single env variable on is quite appealing (at least in a Node.js
environment):
```
DEBUG=* node index.js
```
> dual packaging (our selected solution)
We provide two ESM builds, one with debug and one without.
Pros:
- no tricky configuration for bundlers
- debug logs are still available in Node.js
Cons:
- no more debug logs in the browser
We will go with the latest solution for now, until there is a better
alternative.
This change allows us to:
- reduce the size of the bundle
- provide an ESM bundle (for usage in <script type="module">)
BREAKING CHANGE: due to how default export works with ES modules, we
have removed the default export of the library, which means the
following code:
```js
require("engine.io-client")(...);
```
will not work anymore. The named export must be used instead:
```js
const { Socket } = require("engine.io-client);
// or import { Socket } from "engine.io-client";
const socket = new Socket(...);
```
Note: the UMD build still exposes a function though:
```html
<script src="/path/to/engine.io.js"></script>
<script>
const socket = eio(...);
</script>
```
Note: webpack is still used with zuul because of the custom builder
(zuul-builder-webpack)
This allows to control the behavior of mocked timers (@sinonjs/fake-timers),
depending on the value of the "useNativeTimers" option:
- true: use native setTimeout function
- false (default): use classic timers, that may be mocked
The "installTimerFunctions" method will also be used in the
`socket.io-client` package:
```
import { installTimerFunctions } from "engine.io-client/lib/util";
```
Note: we could also have put the method in its own library, but that
sounded a bit overkill
Related: https://github.com/socketio/socket.io-client/pull/1479
