@mkody/twitch-emoticons 3.0.0-beta.1 → 3.0.0-beta.2

package/README.md

@@ -2,10 +2,15 @@
 
 Gets Twitch, BTTV, FFZ and 7TV emotes as well as parsing text to emotes!
 
+> [!IMPORTANT]  
+> This branch is for the **currently pre-released** 3.0 version.  
+> If you want to see the latest stable version (as of this commit),
+> [switch to the `version/2.9` branch](https://github.com/mkody/twitch-emoticons/tree/version/2.9).
+
 
 ## Migrate to 3.x
 
-**This release introduces some breaking changes!**
+**This release introduces breaking changes!**
 
 <details>
 <summary>Click here to toggle for details</summary>
@@ -86,9 +91,9 @@ console.log(parser.parse('Hello CoolCat!')) // <- Doesn't require :colons: and r
 </details>
 
 
-## Pre-requisites
+## Prerequisites
 
-To fetch Twitch emotes you need to [create an app here](https://dev.twitch.tv/console/apps/create), it's free.  
+To fetch "native" Twitch emotes, you need to [create an app here](https://dev.twitch.tv/console/apps/create), it's free.  
 If you are only using BetterTTV, FrankerFaceZ and 7TV you don't need to provide Twitch app keys.
 
 You must use a Twitch user ID instead of the username to fetch users' emotes.  
@@ -97,21 +102,155 @@ You can use [this page to manually convert them](https://s.kdy.ch/twitchid/).
 
 ## Install
 
+From [npm] ([browse on npmx]; use the `@next` tag):
+
 ```sh
-npm install @mkody/twitch-emoticons
+npm install @mkody/twitch-emoticons@next
+# or
+pnpm add @mkody/twitch-emoticons@next
+# or
+yarn add @mkody/twitch-emoticons@next
 # or
-pnpm add @mkody/twitch-emoticons
+deno add npm:@mkody/twitch-emoticons@next
+```
+
+From [jsr]:
+
+```sh
+npx jsr add @mkody/twitch-emoticons
 # or
-yarn add @mkody/twitch-emoticons
+pnpm add jsr:@mkody/twitch-emoticons
 # or
-deno add npm:@mkody/twitch-emoticons
+yarn add jsr:@mkody/twitch-emoticons
+# or (version has to be specified while it's a pre-release)
+deno add jsr:@mkody/twitch-emoticons@3.0.0-beta.1
+```
+
+[npm]: https://www.npmjs.com/package/@mkody/twitch-emoticons/v/3.0.0-beta.1
+[browse on npmx]: https://npmx.dev/package/@mkody/twitch-emoticons/v/3.0.0-beta.1
+[jsr]: https://jsr.io/@mkody/twitch-emoticons@3.0.0-beta.1
+
+
+## Quick docs
+
+<details>
+<summary>Click here to toggle the docs</summary>
+
+Here's some quick documentation to explain our two classes, the principal methods, and the settings.
+
+> **NOTE:**  
+> If you want a more complete documentation, see: https://mkody.github.io/twitch-emoticons/
+
+
+### Grab emotes with `EmoteFetcher`
+
+First, you need to load a list of emotes, and for that you create a new `EmoteFetcher` object:
+
+```js
+const fetcher = new EmoteFetcher({
+  // If you want to use emotes from twitch.tv, you'll need to be authenticated to use their API. You have two options:
+  // Option 1: Provide your app ID and secret here (get them at https://dev.twitch.tv/console/apps).
+  twitchAppID,      // <string>
+  twitchAppSecret,  // <string>
+  // Option 2: If you need a different way to auth or already use `@twurple/api`, you can provide your ApiClient object here.
+  apiClient, // <ApiClient>
+
+  // Force emotes to be static (non-animated).
+  forceStatic, // <boolean> - Default: false
+
+  // Theme mode (background color) preference for Twitch emotes.
+  twitchThemeMode // <'dark' | 'light'> - Default: 'dark'
+})
+```
+
+And then you need to make the calls to load what you want.
+
+There is one method per platform; all of them return Promises (so you can use `await` or callback chains):
+
+- `fetcher.fetchTwitchEmotes()`
+- `fetcher.fetchBTTVEmotes()`
+- `fetcher.fetchFFZEmotes()`
+- `fetcher.fetchSevenTVEmotes()`
+
+The first parameter is the Twitch user ID of the channel you want to load emotes from.  
+If not provided or it's `null`/falsy, it loads what we call "global emotes", which are available to all users of the platform.
+
+Do note that `fetchSevenTVEmotes()` accepts a second parameter with an object:
+
+- `format`: Set the image type used, either `webp` or `avif`. Default: `webp`
+
+So if you want to load all global emotes, you can do it that way:
+
+```js
+await fetcher.fetchTwitchEmotes()
+await fetcher.fetchBTTVEmotes()
+await fetcher.fetchFFZEmotes()
+await fetcher.fetchSevenTVEmotes(null, { format: 'avif' }) // Example of loading images in AVIF here
+```
+
+
+### Parse strings to include emotes with `EmoteParser`
+
+And now that we have our list of emotes that we can expect to find, let's use it!  
+Let's create our `EmoteParser` object:
+
+```js
+const parser = new EmoteParser(
+  // The first parameter is our EmoteFetcher, the object that holds the list of fetched emotes.
+  fetcher, // <EmoteFetcher>
+
+  // The second parameter is an *optional* object with settings.
+  {
+    // What output should be used when you parse messages? There are two ways to set that up:
+    // Option 1: Use one of the provided templates:
+    // - `html`: `<img alt="{name}" title="{name}" class="twitch-emote" src="{link}">`
+    // - `markdown`: `![{name}]({link} "{name}")`
+    // - `bbcode`: `[img]{link}[/img]`
+    // - `plain`: `{link}`
+    type, // <'html' | 'markdown' | 'bbcode' | 'plain'> - Default: 'html'
+    // Option 2: Make your own template; it has priority over option 1. You can use those: `{link}`, `{name}`, `{size}`, `{creator}`.
+    template, // <string> - Default: ''
+
+    // You can customize the regular expression used to find possible emotes.
+    match, // <RegExp>
+  },
+) 
+```
+
+Now that you have an EmoteParser object, you can do two things with it:
+look up an `Emote` or parse text and get the output as set by `type` or `template`.
+
+To grab a specific emote, you can do `fetcher.emotes.get('...')`, with the case-sensitive name of the emote in place of the ellipsis.  
+From there, you can read properties like `.code`, `.animated`, `.imageType`, or `.type`,
+but you can also use the `.toLink()` method to… get a link!
+
+To parse text, you use the `parser.parse()` method.  
+The first parameter is the input text. There's also an optional second parameter
+where you can provide a few settings (which can overwrite the same ones set in the `EmoteFetcher`).
+
+```js
+const parsed = parser.parse(
+  // The text to parse.
+  text, // <string>
+
+  // The second parameter is an *optional* object with the settings.
+  {
+    // Size (scale) for emotes. It varies by provider, and not all share the same resolution in pixels. Play with this value if you'd like, but no guarantees!
+    size, // <number>
+
+    // Force emotes to be static (non-animated).
+    forceStatic, // <boolean> - Default: what's in EmoteFetcher or false
+
+    // Theme mode (background color) preference for Twitch emotes.
+    twitchThemeMode // <'dark' | 'light'> - Default: what's in EmoteFetcher or 'dark'
+  },
+)
 ```
 
-See this package on [npm] ([npmx]) or [jsr].
+And that's it for the essentials!  
+You can go through the examples below if you need to see more complete code and direct usage.
 
-[npm]: https://www.npmjs.com/package/@mkody/twitch-emoticons
-[npmx]: https://npmx.dev/package/@mkody/twitch-emoticons
-[jsr]: https://jsr.io/@mkody/twitch-emoticons
+</details>
 
 
 ## Examples
@@ -152,13 +291,20 @@ console.log(parsed)
 
 ### 2. Bring your own `@twurple/api`
 
-If you already use [Twurple](https://twurple.js.org/) in your project and manage authentification
-(i.e. with user tokens), you can reuse it in this project by setting `apiClient` with your
+If you already use [Twurple](https://twurple.js.org/) in your project and manage authentication
+(i.e., with user tokens), you can reuse it in this project by setting `apiClient` with your
 [ApiClient](https://twurple.js.org/reference/api/classes/ApiClient.html) object.
 
 ```js
+import { ApiClient } from '@twurple/api'
+import { StaticAuthProvider } from '@twurple/auth'
+import { EmoteFetcher } from '@mkody/twitch-emoticons'
+
+const authProvider = new StaticAuthProvider('<your app ID>', '<access token>')
+const myCustomApiClient = new ApiClient({ authProvider })
+
 const fetcher = new EmoteFetcher({
-  apiClient: yourOwnTwurpleApiClientHere,
+  apiClient: myCustomApiClient,
 })
 ```
 
@@ -186,6 +332,7 @@ const parser = new EmoteParser(fetcher, {
   match: /([a-zA-Z0-9_\-]+)/g,
 })
 
+// Fetch all emotes at once and wait for all of them to complete
 Promise.all([
   // Twitch global
   fetcher.fetchTwitchEmotes(),
@@ -203,18 +350,20 @@ Promise.all([
   fetcher.fetchFFZEmotes(),
   // FFZ channel
   fetcher.fetchFFZEmotes(channelId),
-]).then(() => {
-  const globalEmotes = parser.parse('EZ Clap way too easy LUL now for the last boss monkaS LaterSooner')
-  console.log(globalEmotes)
-  // <img class="emote" alt="EZ" src="https://cdn.7tv.app/emote/63071b80942ffb69e13d700f/1x.webp"> <img class="emote" alt="Clap" src="https://cdn.7tv.app/emote/62fc0a0c4a75fd54bd3520a9/1x.webp"> way too easy <img class="emote" alt="LUL" src="https://static-cdn.jtvnw.net/emoticons/v2/425618/default/dark/1.0"> now for the last boss <img class="emote" alt="monkaS" src="https://cdn.betterttv.net/emote/56e9f494fff3cc5c35e5287e/1x.webp"> <img class="emote" alt="LaterSooner" src="https://cdn.frankerfacez.com/emote/149346/1">
-
-  const channelEmotes = parser.parse('KEKW that was 3Head TeriPoint')
-  console.log(channelEmotes)
-  // <img class="emote" alt="KEKW" src="https://cdn.betterttv.net/emote/5e9c6c187e090362f8b0b9e8/1x.webp"> that was <img class="emote" alt="3Head" src="https://cdn.frankerfacez.com/emote/274406/1"> <img class="emote" alt="TeriPoint" src="https://cdn.7tv.app/emote/61dc299b600369a98b38ebef/1x.webp">
-}).catch((err) => {
-  console.error('Error loading emotes...')
-  console.error(err)
-})
+])
+  .then(() => {
+    const globalEmotes = parser.parse('EZ Clap way too easy LUL now for the last boss monkaS LaterSooner')
+    console.log(globalEmotes)
+    // <img class="emote" alt="EZ" src="https://cdn.7tv.app/emote/63071b80942ffb69e13d700f/1x.webp"> <img class="emote" alt="Clap" src="https://cdn.7tv.app/emote/62fc0a0c4a75fd54bd3520a9/1x.webp"> way too easy <img class="emote" alt="LUL" src="https://static-cdn.jtvnw.net/emoticons/v2/425618/default/dark/1.0"> now for the last boss <img class="emote" alt="monkaS" src="https://cdn.betterttv.net/emote/56e9f494fff3cc5c35e5287e/1x.webp"> <img class="emote" alt="LaterSooner" src="https://cdn.frankerfacez.com/emote/149346/1">
+
+    const channelEmotes = parser.parse('KEKW that was 3Head TeriPoint')
+    console.log(channelEmotes)
+    // <img class="emote" alt="KEKW" src="https://cdn.betterttv.net/emote/5e9c6c187e090362f8b0b9e8/1x.webp"> that was <img class="emote" alt="3Head" src="https://cdn.frankerfacez.com/emote/274406/1"> <img class="emote" alt="TeriPoint" src="https://cdn.7tv.app/emote/61dc299b600369a98b38ebef/1x.webp">
+  })
+  .catch((err) => {
+    console.error('Error loading emotes...')
+    console.error(err)
+  })
 ```
 
 
@@ -226,6 +375,8 @@ By default, we allow animated emotes to be used,
 but you can override this at the `EmoteFetcher` level:
 
 ```js
+import { EmoteFetcher } from '@mkody/twitch-emoticons'
+
 const fetcher = new EmoteFetcher({
   twitchAppID: '<your app ID>',
   twitchAppSecret: '<your app secret>',
@@ -271,6 +422,8 @@ By default, emotes are fetched for dark backgrounds,
 but you can specify a preference at the `EmoteFetcher` level:
 
 ```js
+import { EmoteFetcher } from '@mkody/twitch-emoticons'
+
 // For dark backgrounds (default)
 const fetcherDark = new EmoteFetcher({
   twitchAppID: '<your app ID>',
@@ -316,9 +469,13 @@ console.log(kappa)
 
 7TV v3 delivers emotes in either WEBP or AVIF.
 
-By default we'll return WEBP emotes but you can override this.
+By default we'll return WEBP emotes, but you can override this.
 
 ```js
+// (setup)
+import { EmoteFetcher } from '@mkody/twitch-emoticons'
+const fetcher = new EmoteFetcher()
+
 // Fetch global emotes in AVIF (channel id has to be `null` for global)
 await fetcher.fetchSevenTVEmotes(null, { format: 'avif' })
 
@@ -338,6 +495,10 @@ await fetcher.fetchSevenTVEmotes(24377667, { format: 'avif' })
 This can be useful to save the emotes in a cache or for offline content.
 
 ```js
+// (setup)
+import { EmoteFetcher } from '@mkody/twitch-emoticons'
+const fetcher = new EmoteFetcher()
+
 // First fetch some emotes
 await fetcher.fetchSevenTVEmotes(null, { format: 'avif' })
 
@@ -362,6 +523,7 @@ fetcher.fromObject(emotes)
 - [Changelog](https://github.com/mkody/twitch-emoticons/releases)
 
 This library uses the following:
+
 - [Twurple](https://twurple.js.org/) and the [Twitch API](https://dev.twitch.tv/)
 - [BetterTTV API](https://betterttv.com/developers/api)
 - [FrankerFaceZ API](https://api.frankerfacez.com/docs/)

package/dist/TwitchEmoticons.cjs

@@ -160,11 +160,12 @@ var BTTVEmote = class _BTTVEmote extends Emote_default {
    * @returns {object} - Object representation of the BTTVEmote.
    */
   toObject() {
-    return Object.assign({}, super.toObject(), {
+    return {
+      ...super.toObject(),
       animated: this.animated,
       ownerName: this.ownerName,
       type: this.type
-    });
+    };
   }
   /**
    * Converts an emote Object into a BTTVEmote
@@ -199,16 +200,22 @@ var Collection = class extends Map {
    */
   find(propOrFunc, value) {
     if (typeof propOrFunc === "string") {
-      if (typeof value === "undefined") return null;
+      if (value === void 0) {
+        return null;
+      }
       for (const item of this.values()) {
-        if (item[propOrFunc] === value) return item;
+        if (item[propOrFunc] === value) {
+          return item;
+        }
       }
       return null;
     }
     if (typeof propOrFunc === "function") {
       let i = 0;
       for (const item of this.values()) {
-        if (propOrFunc(item, i, this)) return item;
+        if (propOrFunc(item, i, this)) {
+          return item;
+        }
         i++;
       }
       return null;
@@ -223,11 +230,15 @@ var Collection = class extends Map {
    * @returns {Collection} - A new collection with the filtered items.
    */
   filter(func, thisArg) {
-    if (thisArg) func = func.bind(thisArg);
+    if (thisArg) {
+      func = func.bind(thisArg);
+    }
     const results = new this.constructor();
     let i = 0;
     for (const [key, item] of this) {
-      if (func(item, i, this)) results.set(key, item);
+      if (func(item, i, this)) {
+        results.set(key, item);
+      }
       i++;
     }
     return results;
@@ -240,7 +251,9 @@ var Collection = class extends Map {
    * @returns {any[]} - An array with the mapped items.
    */
   map(func, thisArg) {
-    if (thisArg) func = func.bind(thisArg);
+    if (thisArg) {
+      func = func.bind(thisArg);
+    }
     const array = new Array(this.size);
     let i = 0;
     for (const item of this.values()) {
@@ -334,13 +347,14 @@ var FFZEmote = class _FFZEmote extends Emote_default {
    * @returns {object} - Object representation of the FFZEmote.
    */
   toObject() {
-    return Object.assign({}, super.toObject(), {
+    return {
+      ...super.toObject(),
       animated: this.animated,
       sizes: this.sizes,
       ownerName: this.ownerName,
       type: this.type,
       modifier: this.modifier
-    });
+    };
   }
   /**
    * Converts an emote Object into a FFZEmote
@@ -411,13 +425,14 @@ var SevenTVEmote = class _SevenTVEmote extends Emote_default {
    * @returns {object} - Object representation of the SevenTVEmote.
    */
   toObject() {
-    return Object.assign({}, super.toObject(), {
+    return {
+      ...super.toObject(),
       animated: this.animated,
       sizes: this.sizes,
       ownerName: this.ownerName,
       type: this.type,
       imageType: this.imageType
-    });
+    };
   }
   /**
    * Converts an emote Object into a SevenTVEmote
@@ -490,11 +505,12 @@ var TwitchEmote = class _TwitchEmote extends Emote_default {
    * @returns {object} - Object representation of the TwitchEmote.
    */
   toObject() {
-    return Object.assign({}, super.toObject(), {
+    return {
+      ...super.toObject(),
       animated: this.animated,
       set: this.set,
       type: this.type
-    });
+    };
   }
   /**
    * Converts an emote Object into a TwitchEmote
@@ -607,11 +623,14 @@ var EmoteFetcher = class {
    * @returns {Promise<object[]>} - A promise that resolves to an array of raw BTTV emote data.
    */
   _getRawBTTVEmotes(id) {
-    const endpoint = !id ? Constants_default.BTTV.Global : Constants_default.BTTV.Channel(id);
+    const endpoint = id ? Constants_default.BTTV.Channel(id) : Constants_default.BTTV.Global;
     return fetch(endpoint).then((response) => response.json()).then((data) => {
-      if (data instanceof Array) return data;
-      if (data && data.channelEmotes && data.sharedEmotes) {
-        return [...data.channelEmotes, ...data.sharedEmotes];
+      if (Array.isArray(data)) return data;
+      if (data?.channelEmotes && data?.sharedEmotes) {
+        return [
+          ...data.channelEmotes,
+          ...data.sharedEmotes
+        ];
       }
       return data || [];
     });
@@ -682,7 +701,7 @@ var EmoteFetcher = class {
    * @returns {Promise<object[]>} - A promise that resolves to an array of raw 7TV emote data.
    */
   _getRawSevenTVEmotes(id) {
-    const endpoint = !id ? Constants_default.SevenTV.Global : Constants_default.SevenTV.Channel(id);
+    const endpoint = id ? Constants_default.SevenTV.Channel(id) : Constants_default.SevenTV.Global;
     return fetch(endpoint).then((response) => response.json());
   }
   /**
@@ -774,7 +793,7 @@ var EmoteFetcher = class {
       format = "webp"
     } = options || {};
     return this._getRawSevenTVEmotes(channel).then((rawEmotes) => {
-      if ("emotes" in rawEmotes) {
+      if (Object.hasOwn(rawEmotes, "emotes")) {
         for (const data of rawEmotes.emotes) {
           this._cacheSevenTVEmote(channel, data, format);
         }
@@ -828,7 +847,7 @@ var EmoteParser = class {
    * - `{name}` The name of the emote.
    * - `{size}` The size index of the image.
    * - `{creator}` The channel/owner name of the emote.
-   * @param {string} [options.type='html'] - The type of the parser.
+   * @param {'html' | 'markdown' | 'bbcode' | 'plain'} [options.type='html'] - The type of the parser.
    * Can be one of `html`, `markdown`, `bbcode`, or `plain`.
    * If the `template` option is provided, this is ignored.
    * @param {RegExp} [options.match=/(\w+)/g] - The regular expression that matches an emote.
@@ -836,14 +855,12 @@ var EmoteParser = class {
    */
   constructor(fetcher, options = {}) {
     this.fetcher = fetcher;
-    this.options = Object.assign(
-      {
-        template: "",
-        type: "html",
-        match: /(\w+)/g
-      },
-      options
-    );
+    this.options = {
+      template: "",
+      type: "html",
+      match: /(\w+)/g,
+      ...options
+    };
     this._validateOptions(this.options);
   }
   /**
@@ -856,8 +873,8 @@ var EmoteParser = class {
    * - `{name}` The name of the emote.
    * - `{size}` The size of the image.
    * - `{creator}` The channel/owner name of the emote.
-   * @param {string} [options.type] - The type of the parser.
-   * Can be one of  `html`, `markdown`,`bbcode`, or `plain`.
+   * @param {'html' | 'markdown' | 'bbcode' | 'plain'} [options.type] - The type of the parser.
+   * Can be one of `html`, `markdown`, `bbcode`, or `plain`.
    * If the `template` option is provided, this is ignored.
    * @param {RegExp} [options.match] - The regular expression that matches an emote.
    * Must be a global regex, with one capture group for the emote code.
@@ -897,7 +914,7 @@ var EmoteParser = class {
       if (emote.modifier) return "";
       const template = this.options.template || Constants_default.Templates[this.options.type];
       const link = emote.toLink({ size, forceStatic, themeMode });
-      const res = template.replace(/{link}/g, link).replace(/{name}/g, emote.code).replace(/{size}/g, size).replace(/{creator}/g, emote.ownerName || "global");
+      const res = template.replaceAll("{link}", link).replaceAll("{name}", emote.code).replaceAll("{size}", size).replaceAll("{creator}", emote.ownerName || "global");
       return res;
     });
     return parsed;