import { EntityEncoder, EntityDecoder, ALL_ENTITIES } from '@nodable/entities';

// Encode: plain text → entity references
// v3 requires an explicit entity set when encoding named (non‑ASCII) characters
const enc = new EntityEncoder({ namedEntities: ALL_ENTITIES });
enc.encode('Hello © 2024 & <stuff>');
// → 'Hello &copy; 2024 &amp; &lt;stuff&gt;'

// Decode: entity references → plain text
const dec = new EntityDecoder({ namedEntities: ALL_ENTITIES });
dec.decode('Hello &copy; 2024 &amp; &lt;stuff&gt;');
// → 'Hello © 2024 & <stuff>'

If you only need to encode XML‑unsafe characters (&, <, >, ", '), you can disable named‑entity encoding entirely and avoid importing any entity set:

const enc = new EntityEncoder({ encodeAllNamed: false });
enc.encode('© <stuff>'); // → '© &lt;stuff&gt;'  (copyright stays literal)

To encode only a specific subset of characters (e.g. common HTML entities), pass a custom map:

import { EntityEncoder, COMMON_HTML, CURRENCY } from '@nodable/entities';

const enc = new EntityEncoder({ namedEntities: { ...COMMON_HTML, ...CURRENCY } });
enc.encode('Price: 10 © 2024'); // only COMMON_HTML/CURRENCY entities are recognized

Migration from v2 to v3

Breaking change:
In v2, new EntityEncoder() automatically used the full built‑in entity set to encode non‑ASCII characters (like © → ©). This caused poor tree‑shaking: every consumer paid the cost of the entire entity table, even if they never used it.

In v3, EntityEncoder no longer includes a default entity set.
If you pass no options and encodeAllNamed is true (the default), the constructor will throw an error:

const enc = new EntityEncoder(); // throws: "encodeAllNamed is true but no `namedEntities` was provided"

How to update

What you need	v2 code	v3 code
Full built‑in set (same as v2)	`new EntityEncoder()`	`import { ALL_ENTITIES } from '@nodable/entities';` `new EntityEncoder({ namedEntities: ALL_ENTITIES })`
Only XML‑unsafe chars (no named entities)	`new EntityEncoder({ encodeAllNamed: false })`	Same – no change
Custom subset	`new EntityEncoder({ namedEntities: myMap })`	Same – but now your map is required for named‑entity encoding

This change allows bundlers to tree‑shake unused entity categories – you only pay for the characters you actually encode.

Upgrading step‑by‑step

Update to @nodable/entities@3.0.0.
Find all new EntityEncoder() calls in your project.
Decide:
- If you need the full set: import ALL_ENTITIES and pass it as namedEntities.
- If you only need XML‑unsafe escaping: add { encodeAllNamed: false }.
- If you used a custom set: keep it as‑is – it already worked.
Run your tests – the encoder should now behave as before, but with better bundle size.