New decodeEntity() method to speed up entity decoding.

Author: mdevils

CHANGELOG.md

@@ -1,3 +1,8 @@
+2.2.0
+-----
+
+ * A fast `decodeEntity()` method to decode a single HTML entity.
+
 2.1.1
 -----
 

README.md

@@ -85,6 +85,32 @@ Options:
  * `attribute` emulates behavior of browser when parsing tag attributes: entities without semicolon are replaced when not followed by equality sign `=`.
  * `strict` ignores entities without semicolon.
 
+### decodeEntity(text, options)
+
+Decodes a single HTML entity. Unknown entitiy is left as is.
+
+```js
+import {decodeEntity} from 'html-entities';
+
+decodeEntity('<');
+// -> '<'
+
+decodeEntity('&copy;', {level: 'html5'});
+// -> '©'
+
+decodeEntity('&copy;', {level: 'xml'});
+// -> '&copy;'
+```
+
+Options:
+
+#### level
+
+ * `all` alias to `html5` (default).
+ * `html5` uses `HTML5` named references.
+ * `html4` uses `HTML4` named references.
+ * `xml` uses `XML` named references.
+
 Performance
 -----------
 

package.json

@@ -40,7 +40,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/mdevils/node-html-entities.git"
+    "url": "https://github.com/mdevils/html-entities.git"
   },
   "main": "./lib/index.js",
   "typings": "./lib/index.d.ts",

src/index.ts

@@ -118,6 +118,37 @@ const decodeRegExps: Record<Level, Record<DecodeScope, RegExp>> = {
 const fromCharCode = String.fromCharCode;
 const outOfBoundsChar = fromCharCode(65533);
 
+const defaultDecodeEntityOptions: CommonOptions = {
+    level: 'all'
+};
+
+export function decodeEntity(
+    entity: string | undefined | null,
+    {level = 'all'}: CommonOptions = defaultDecodeEntityOptions
+): string {
+    if (!entity) {
+        return '';
+    }
+
+    const references = allNamedReferences[level].entities;
+    const resultByReference = references[entity];
+    if (resultByReference) {
+        return resultByReference;
+    }
+    if (entity[0] === '&' && entity[1] === '#') {
+        const secondChar = entity[2];
+        const code =
+            secondChar == 'x' || secondChar == 'X' ? parseInt(entity.substr(3), 16) : parseInt(entity.substr(2));
+
+        return code >= 0x10ffff
+            ? outOfBoundsChar
+            : code > 65535
+            ? fromCodePoint(code)
+            : fromCharCode(numericUnicodeMap[code] || code);
+    }
+    return entity;
+}
+
 export function decode(
     text: string | undefined | null,
     {level = 'all', scope = level === 'xml' ? 'strict' : 'body'}: DecodeOptions = defaultDecodeOptions

test/index.test.ts

@@ -2,7 +2,7 @@ import {expect} from 'chai';
 import * as HE from '../src';
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
-const {encode, decode} = require(process.env.TEST_LIB ? '../lib' : '../src') as typeof HE;
+const {encode, decode, decodeEntity} = require(process.env.TEST_LIB ? '../lib' : '../src') as typeof HE;
 
 describe('encode()', () => {
     it('should handle undefined', () => {
@@ -104,3 +104,41 @@ describe('decode()', () => {
         });
     });
 });
+
+describe('decodeEntity()', () => {
+    it('should handle undefined', () => {
+        expect(decodeEntity(undefined)).to.equal('');
+    });
+    it('should handle null', () => {
+        expect(decodeEntity(null)).to.equal('');
+    });
+    it('should handle empty string', () => {
+        expect(decodeEntity('')).to.equal('');
+    });
+    it('should handle invalid numeric entities', () => {
+        expect(decodeEntity('�')).to.equal(String.fromCharCode(65533));
+    });
+    it('should decode numeric entities without semicolon', () => {
+        expect(decodeEntity('&#34')).to.equal('"');
+    });
+    it('should decode incomplete named entities', () => {
+        expect(decodeEntity('&uuml')).to.equal('ü');
+    });
+    it('should decode proper named entities', () => {
+        expect(decodeEntity('&')).to.equal('&');
+    });
+    it('should decode emoji', () => {
+        expect(decodeEntity('😂')).to.equal('😂');
+    });
+    describe('level', () => {
+        it('should decode according to the level', () => {
+            expect(decodeEntity('℞', {level: 'all'})).to.equal('℞');
+            expect(decodeEntity('℞', {level: 'html5'})).to.equal('℞');
+            expect(decodeEntity('℞', {level: 'html4'})).to.equal('℞');
+            expect(decodeEntity('©', {level: 'html4'})).to.equal('©');
+            expect(decodeEntity('℞', {level: 'xml'})).to.equal('℞');
+            expect(decodeEntity('©', {level: 'xml'})).to.equal('©');
+            expect(decodeEntity('&lt;', {level: 'xml'})).to.equal('<');
+        });
+    });
+});