Skip to content

Commit 46605a1

Browse files
committed
doc: clarify encoding bundle versions
1 parent 3bddbfa commit 46605a1

File tree

1 file changed

+20
-14
lines changed

1 file changed

+20
-14
lines changed

README.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -100,30 +100,36 @@ _These are only provided as a compatibility layer, prefer hardened APIs instead
100100

101101
### Lite version
102102

103-
If you don't need support for legacy multi-byte encodings, you can use the lite import:
104-
```js
105-
import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-lite.js'
106-
import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-lite.js' // Requires Streams
107-
```
103+
Alternate exports exist that can help reduce bundle size:
104+
105+
* `@exodus/bytes/encoding-browser.js` - resolves to a tiny import in browser bundles, preferring native `TextDecoder` / `TextEncoder`.
106+
For non-browsers (Node.js, React Native), loads a full implementation.
107+
108+
* `@exodus/bytes/encoding-lite.js` - if you don't need support for legacy multi-byte encodings.
108109

109-
This reduces the bundle size 9x:\
110-
from 94 KiB gzipped for `@exodus/bytes/encoding.js` to 10 KiB gzipped for `@exodus/bytes/encoding-lite.js`.\
111-
(For comparison, `text-encoding` and `iconv-lite` are each over 195 KiB gzipped):
110+
Reduces the bundle size 9x, while still keeping `utf-8`, `utf-16le`, `utf-16be` and all single-byte encodings specified by the spec.
111+
The only difference is support for legacy multi-byte encodings.
112112

113+
See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels).
114+
115+
This can be useful for example in React Native global TextDecoder polyfill,
116+
if you are sure that you don't need legacy multi-byte encodings support.
117+
118+
Libraries are advised to use single-purpose hardened `@exodus/bytes/utf8.js` / `@exodus/bytes/utf16.js` APIs for Unicode.
119+
120+
Applications (including React Native apps) are advised to load either `@exodus/bytes/encoding-lite.js` or `@exodus/bytes/encoding.js`
121+
(depending on whether legacy multi-byte support is needed) and use that as a global polyfill.
122+
123+
Bundle size comparison:
113124
| import | size |
114125
| - | - |
115126
| `@exodus/bytes/encoding-browser.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding-browser.js?style=flat-square)</sub> |
116127
| `@exodus/bytes/encoding-lite.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding-lite.js?style=flat-square)</sub> |
117128
| `@exodus/bytes/encoding.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding.js?style=flat-square)</sub> |
118129
| `text-encoding` | <sub>![](https://img.shields.io/bundlejs/size/text-encoding?style=flat-square)</sub> |
119-
| `iconv-lite` | <sub>![](https://img.shields.io/bundlejs/size/iconv-lite?style=flat-square)</sub> |
130+
| `iconv-lite` | <sub>![](https://img.shields.io/bundlejs/size/iconv-lite/lib/index.js?style=flat-square)</sub> |
120131
| `whatwg-encoding` | <sub>![](https://img.shields.io/bundlejs/size/whatwg-encoding?style=flat-square)</sub> |
121132

122-
It still supports `utf-8`, `utf-16le`, `utf-16be` and all single-byte encodings specified by the spec,
123-
the only difference is support for legacy multi-byte encodings.
124-
125-
See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels).
126-
127133
## API
128134

129135
### @exodus/bytes/utf8.js <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/utf8.js?style=flat-square)<sub>

0 commit comments

Comments
 (0)