Skip to content

Commit 9af409a

Browse files
committed
doc: clarify encoding bundle versions
1 parent 3bddbfa commit 9af409a

File tree

1 file changed

+27
-12
lines changed

1 file changed

+27
-12
lines changed

README.md

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -100,29 +100,44 @@ _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+
```js
111+
import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-lite.js'
112+
import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-lite.js' // Requires Streams
113+
```
112114

115+
Reduces the bundle size 9x, while still keeping `utf-8`, `utf-16le`, `utf-16be` and all single-byte encodings specified by the spec.
116+
The only difference is support for legacy multi-byte encodings.
117+
118+
See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels).
119+
120+
This can be useful for example in React Native global TextDecoder polyfill,
121+
if you are sure that you don't need legacy multi-byte encodings support.
122+
123+
124+
Bundle size comparison:
113125
| import | size |
114126
| - | - |
115127
| `@exodus/bytes/encoding-browser.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding-browser.js?style=flat-square)</sub> |
116128
| `@exodus/bytes/encoding-lite.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding-lite.js?style=flat-square)</sub> |
117129
| `@exodus/bytes/encoding.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding.js?style=flat-square)</sub> |
118130
| `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> |
131+
| `iconv-lite` | <sub>![](https://img.shields.io/bundlejs/size/iconv-lite/lib/index.js?style=flat-square)</sub> |
120132
| `whatwg-encoding` | <sub>![](https://img.shields.io/bundlejs/size/whatwg-encoding?style=flat-square)</sub> |
121133
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.
134+
In general:
135+
136+
1. Libraries are advised to use single-purpose hardened `@exodus/bytes/utf8.js` / `@exodus/bytes/utf16.js` APIs for Unicode or
137+
global `TextDecoder` for the remaining WHATWG encodings
124138
125-
See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels).
139+
2. Applications (including React Native apps) are advised to load either `@exodus/bytes/encoding-lite.js` or `@exodus/bytes/encoding.js`
140+
(depending on whether legacy multi-byte support is needed) and use that a a global polyfill.
126141
127142
## API
128143

0 commit comments

Comments
 (0)