rename getEmojis -> filterEmojis

README.md

@@ -1 +1,113 @@
-# emoji-util
+# unicode-emoji-utils
+
+A collection of utilities for emojis and raw data for Unicode Emojis
+
+- Support CommonJS and ES Module
+
+- Full list of `Unicode Emoji, Version 15.0` from [Unicode](https://home.unicode.org/emoji/about-emoji/).
+
+## 🔌 Installation
+
+Using `npm`
+
+```shell
+npm install unicode-emoji-utils
+```
+
+Or `yarn`
+
+```shell
+yarn add unicode-emoji-utils
+```
+
+## Usage
+
+```javascript
+import { type Emoji, getAllEmojis, hasEmoji, compareVersion, stripEmojies, filterEmojis, getAllComponents, extractEmojis, getEmojisByGroup } from 'unicode-emoji-utils';
+```
+
+### Check whether a text has emojis
+
+```javascript
+hasEmoji('a'); // false
+hasEmoji('a 🫶'); // true
+```
+
+### Strip emojis from a given text
+
+```javascript
+stripEmoji('a 🫶'); // 'a '
+```
+
+### Extract Emojis
+
+```javascript
+extractEmoji('👋🏼adfsadfs safdsaf dsafds 🫶'); // ['👋🏼', '🫶']
+```
+
+### Get All Emojis
+
+```javascript
+getAllEmojis(); // ['🫶', '👋🏼', '🙏🏿', '👨🏻‍🤝‍👨🏼', '👬', ...]
+
+const emojis = [{emoji: '🫶', version: '14.0' }];
+getAllEmojis(emojis); // ['🫶']
+```
+
+### Filter Emoijs by the Unicode Version
+
+```javascript
+filterEmojis('14.0'); // Filter Emojis from version 14.0 and below
+
+filterEmojis('14.0', true); // Only returns emoji with version 14.0
+
+const emojis = [{emoji: '🫶', version: '14.0' }];
+filterEmojis('14.0', true, emojis); // [{emoji: '🫶', version: '14.0' }]
+filterEmojis('14.0', false, emojis); // [{emoji: '🫶', version: '14.0' }]
+filterEmojis('1.0', false, emojis); // []
+```
+
+### Retrieve Unicode components
+
+```javascript
+getAllComponents();
+```
+
+```javascript
+{
+  "skin-tone": [
+    {
+      "emoji": "🏻",
+      "description": "light skin tone",
+      "version": "1.0"
+    },
+    {
+      "emoji": "🏼",
+      "description": "medium-light skin tone",
+      "version": "1.0"
+    },
+    // ...
+  ],
+  "hair-style": [
+    {
+      "emoji": "🦰",
+      "description": "red hair",
+      "version": "11.0"
+    },
+    {
+      "emoji": "🦱",
+      "description": "curly hair",
+      "version": "11.0"
+    },
+    // ...
+  ]
+}
+```
+
+### Get Emojis by group, subgroup or category
+
+```javascript
+getEmojisByGroup('group');
+getEmojisByGroup('subgroup');
+getEmojisByGroup('category');
+```

package.json

@@ -17,7 +17,7 @@
   },
   "name": "unicode-emoji-utils",
   "description": "A collection of utilities for emojis",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "sideEffects": false,
   "main": "dist/index.js",
   "module": "dist/index.mjs",

src/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { type Emoji, getAllEmojis, hasEmoji, compareVersion, stripEmojies, getEmojis, getAllComponents, extractEmojis, getEmojisByGroup } from '../';
+import { type Emoji, getAllEmojis, hasEmoji, compareVersion, stripEmojies, filterEmojis, getAllComponents, extractEmojis, getEmojisByGroup } from '../';
 import unicodeEmojis from '../unicode-emojis';
 
 const ztring = 'adfsadfs safdsaf dsafds ';
@@ -33,13 +33,13 @@ test('getAllEmojis', () => {
     }
 });
 
-test('getEmojis', () => {
-    expect(getEmojis('1.0', false, testEmojis)).toEqual(testEmojis);
-    expect(getEmojis('1.0', true, testEmojis)).toEqual(testEmojis);
-    expect(getAllEmojis(getEmojis('1.0', true)).includes('😂')).toBe(false); // v0.6
-    expect(getAllEmojis(getEmojis('1.0', true)).includes('👨🏻‍🤝‍👨🏽')).toBe(false); // v12.1
-    expect(getAllEmojis(getEmojis('1.0')).includes('😂')).toBe(true);
-    expect(getAllEmojis(getEmojis('1.0')).includes('👨🏻‍🤝‍👨🏽')).toBe(false);
+test('filterEmojis', () => {
+    expect(filterEmojis('1.0', false, testEmojis)).toEqual(testEmojis);
+    expect(filterEmojis('1.0', true, testEmojis)).toEqual(testEmojis);
+    expect(getAllEmojis(filterEmojis('1.0', true)).includes('😂')).toBe(false); // v0.6
+    expect(getAllEmojis(filterEmojis('1.0', true)).includes('👨🏻‍🤝‍👨🏽')).toBe(false); // v12.1
+    expect(getAllEmojis(filterEmojis('1.0')).includes('😂')).toBe(true);
+    expect(getAllEmojis(filterEmojis('1.0')).includes('👨🏻‍🤝‍👨🏽')).toBe(false);
 });
 
 test('getEmojisByGroup', () => {

src/index.ts

@@ -32,6 +32,11 @@ export type Emoji = {
 }
 type Group = 'category' | 'group' | 'subgroup';
 
+/**
+ * Get All Emojis as an array of emoji character
+ * @param emojis 
+ * @returns 
+ */
 export function getAllEmojis(emojis?: Array<Emoji>) {
     return (emojis ?? unicodeEmojis.emojis)
         .map(e => [e.emoji, ...(e.variations ?? []).map(v => v.emoji)])
@@ -43,13 +48,20 @@ export function compareVersion(a: EmojiVersion, b: EmojiVersion, exact?: boolean
     return parseFloat(a) <= parseFloat(b);
 }
 
-export function getEmojis(version: EmojiVersion, exact?: boolean, emoijs?: Array<Emoji>) {
+/**
+ * Filter Emoijs by the Unicode Version
+ * @param version 
+ * @param exact 
+ * @param emoijs 
+ * @returns 
+ */
+export function filterEmojis(version: EmojiVersion, exact?: boolean, emoijs?: Array<Emoji>) {
     const filteredEmojis: Array<Emoji> = [];
 
     for (const emoji of (emoijs ?? unicodeEmojis.emojis)) {
         if (compareVersion(emoji.version, version, exact)) {
             if (emoji.variations) {
-                emoji.variations = getEmojis(version, exact, emoji.variations)
+                emoji.variations = filterEmojis(version, exact, emoji.variations)
             }
             filteredEmojis.push(emoji);
         }
@@ -58,6 +70,12 @@ export function getEmojis(version: EmojiVersion, exact?: boolean, emoijs?: Array
     return filteredEmojis;
 }
 
+/**
+ * Get Emojis by group, category or subgroup
+ * @param group category | group | subgroup
+ * @param emojis 
+ * @returns 
+ */
 export function getEmojisByGroup(group: Group, emojis?: Array<Emoji>) {
     const map = new Map<string, Array<Emoji>>();
     for (const emoji of (emojis ?? unicodeEmojis.emojis)) {
@@ -71,26 +89,67 @@ export function getEmojisByGroup(group: Group, emojis?: Array<Emoji>) {
     return map;
 }
 
+/**
+ * Get Unicode Emoji Components
+ * @returns 
+ */
 export function getAllComponents() {
     return unicodeEmojis.components;
 }
 
+/**
+ * Emoji Regular Expression
+ * @returns Emoji Regex
+ */
 export function getEmojiRegex() {
     return emojiRegex();
 }
 
+/**
+ * Check whether a given text has emojis
+ * @param text 
+ * @returns text has emojis
+ */
 export function hasEmoji(text: string) {
     return getEmojiRegex().test(text);
 }
 
+/**
+ * Checks if `value` is classified as a `String` primitive or object.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is a string, else `false`.
+ * @example
+ *
+ * isString('abc')
+ * // => true
+ *
+ * isString(1)
+ * // => false
+ */
+function isString(value: any): value is string {
+    const type = typeof value
+    return type === 'string' || (type === 'object' && value != null && !Array.isArray(value) && Object.prototype.toString.call(value) === '[object String]')
+}
+
+/**
+ * Extract Emojis in a given text and preserve the order of appearance
+ * @param text 
+ * @returns 
+ */
 export function extractEmojis(text: string) {
     const emojis = getAllEmojis();
     return Array.from(text.matchAll(getEmojiRegex()))
         .map(match => match[0])
         .map(emojiStr => emojis.find(e => e === emojiStr))
-        .filter(Boolean);
+        .filter<string>(isString);
 }
 
+/**
+ * Strip / Remove Emojis in a given text
+ * @param text 
+ * @returns 
+ */
 export function stripEmojies(text: string) {
     return text.replace(getEmojiRegex(), '');
 }