Emoji type

Author: dahlia

CHANGES.md

@@ -19,8 +19,11 @@ To be released.
      -  Added `CustomEmojiFromUrl` interface.
      -  Added `CustomEmojiFromFile` interface.
      -  Added `CustomEmoji` type.
-     -  Added `DeferredEmoji` type.
-     -  Added `Emoji` class.
+     -  Added `DeferredCustomEmoji` type.
+
+ -  Added `Emoji` type.
+
+ -  Added `isEmoji()` predicate function.
 
  -  Added `SessionGetOutboxOptions` interface.
 

src/bot-impl.ts

@@ -57,7 +57,7 @@ import { getLogger } from "@logtape/logtape";
 import { extension } from "@std/media-types/extension";
 import metadata from "../deno.json" with { type: "json" };
 import type { Bot, CreateBotOptions, PagesOptions } from "./bot.ts";
-import type { CustomEmoji, DeferredEmoji } from "./emoji.ts";
+import type { CustomEmoji, DeferredCustomEmoji } from "./emoji.ts";
 import type {
   AcceptEventHandler,
   FollowEventHandler,
@@ -879,7 +879,7 @@ export class BotImpl<TContextData> implements Bot<TContextData> {
   addCustomEmoji<TEmojiName extends string>(
     name: TEmojiName,
     data: CustomEmoji,
-  ): DeferredEmoji<TContextData> {
+  ): DeferredCustomEmoji<TContextData> {
     if (!name.match(/^[a-z0-9-_]+$/i)) {
       throw new TypeError(
         `Invalid custom emoji name: ${name}. It must match /^[a-z0-9-_]+$/i.`,
@@ -900,8 +900,11 @@ export class BotImpl<TContextData> implements Bot<TContextData> {
 
   addCustomEmojis<TEmojiName extends string>(
     emojis: Readonly<Record<TEmojiName, CustomEmoji>>,
-  ): Readonly<Record<TEmojiName, DeferredEmoji<TContextData>>> {
-    const emojiMap = {} as Record<TEmojiName, DeferredEmoji<TContextData>>;
+  ): Readonly<Record<TEmojiName, DeferredCustomEmoji<TContextData>>> {
+    const emojiMap = {} as Record<
+      TEmojiName,
+      DeferredCustomEmoji<TContextData>
+    >;
     for (const name in emojis) {
       emojiMap[name] = this.addCustomEmoji(name, emojis[name]);
     }

src/bot.ts

@@ -22,7 +22,7 @@ import type {
 import type { Software } from "@fedify/fedify/nodeinfo";
 import type { Application, Image, Service } from "@fedify/fedify/vocab";
 import { BotImpl } from "./bot-impl.ts";
-import type { CustomEmoji, DeferredEmoji } from "./emoji.ts";
+import type { CustomEmoji, DeferredCustomEmoji } from "./emoji.ts";
 import type {
   AcceptEventHandler,
   FollowEventHandler,
@@ -103,7 +103,7 @@ export interface Bot<TContextData> {
    */
   addCustomEmojis<TEmojiName extends string>(
     emojis: Readonly<Record<TEmojiName, CustomEmoji>>,
-  ): Readonly<Record<TEmojiName, DeferredEmoji<TContextData>>>;
+  ): Readonly<Record<TEmojiName, DeferredCustomEmoji<TContextData>>>;
 
   /**
    * An event handler for a follow request to the bot.
@@ -372,7 +372,7 @@ export function createBot<TContextData = void>(
     },
     addCustomEmojis<TEmojiName extends string>(
       emojis: Readonly<Record<TEmojiName, CustomEmoji>>,
-    ): Readonly<Record<TEmojiName, DeferredEmoji<TContextData>>> {
+    ): Readonly<Record<TEmojiName, DeferredCustomEmoji<TContextData>>> {
       return bot.addCustomEmojis(emojis);
     },
     get onFollow() {

src/emoji.test.ts

@@ -0,0 +1,114 @@
+// BotKit by Fedify: A framework for creating ActivityPub bots
+// Copyright (C) 2025 Hong Minhee <https://hongminhee.org/>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+import { assert } from "@std/assert/assert";
+import { assertFalse } from "@std/assert/false";
+import { isEmoji } from "./emoji.ts";
+
+Deno.test("isEmoji() with valid emojis", () => {
+  const validEmojis = [
+    "😀", // simple emoji
+    "👍", // thumbs up
+    "🚀", // rocket
+    "🏳️‍🌈", // pride flag (complex emoji with ZWJ sequence)
+    "👨‍👩‍👧‍👦", // family (complex emoji with multiple ZWJ sequences)
+    "👩🏽‍🔬", // woman scientist with medium skin tone
+    "🧘🏻‍♀️", // woman in lotus position with light skin tone
+    "🤦‍♂️", // man facepalming
+    "🇯🇵", // flag
+  ];
+
+  for (const emoji of validEmojis) {
+    assert(
+      isEmoji(emoji),
+      `Expected '${emoji}' to be recognized as an emoji`,
+    );
+  }
+});
+
+Deno.test("isEmoji() with invalid inputs", () => {
+  const invalidInputs = [
+    // Multiple emojis
+    "😀😀",
+    "👍🏻👎🏻",
+    // Regular text
+    "hello",
+    "a",
+    // Mixed content
+    "hi😀",
+    "👍awesome",
+    // Empty string
+    "",
+    // Non-string values
+    42,
+    null,
+    undefined,
+    true,
+    false,
+    {},
+    [],
+    new Date(),
+  ];
+
+  for (const input of invalidInputs) {
+    assertFalse(
+      isEmoji(input),
+      `Expected '${input}' not to be recognized as an emoji`,
+    );
+  }
+});
+
+Deno.test("isEmoji() with additional edge cases", () => {
+  const edgeCaseEmojis = [
+    "5️⃣", // key cap sequence
+    "❤️", // emoji with presentation variation selector
+    "☺️", // older emoji with variation selector
+    "👩‍🦰", // woman with red hair (hair modifier)
+    "🏊‍♀️", // woman swimming (gender modifier)
+    "🧙‍♂️", // man mage (gender modifier)
+    "🔢", // input numbers symbol (legacy input emoji)
+    "↔️", // arrow with variation selector
+    "📧", // e-mail symbol
+    "📱", // mobile phone
+  ];
+
+  for (const emoji of edgeCaseEmojis) {
+    assert(
+      isEmoji(emoji),
+      `Expected '${emoji}' to be recognized as an emoji`,
+    );
+  }
+});
+
+Deno.test("isEmoji() with tricky invalid inputs", () => {
+  const trickyInvalidInputs = [
+    " 😀", // emoji with leading space
+    "😀 ", // emoji with trailing space
+    "\u200B😀", // emoji with zero-width space
+    // Note: Single regional indicators like "🇺" are technically valid emojis
+    // even though they're usually paired to form flags
+    "\u{1F3F4}\uE0067\uE0062", // incomplete tag sequence
+    "\uFE0F", // variation selector alone
+    "\u200D", // zero width joiner alone
+    "♀️♂️", // gender symbols together (should be two separate graphemes)
+  ];
+
+  for (const input of trickyInvalidInputs) {
+    assertFalse(
+      isEmoji(input),
+      `Expected '${input}' not to be recognized as an emoji`,
+    );
+  }
+});

src/emoji.ts

@@ -13,9 +13,38 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
-import type { Emoji } from "@fedify/fedify/vocab";
+import type { Emoji as EmojiObject } from "@fedify/fedify/vocab";
 import type { Session } from "./session.ts";
-export { Emoji } from "@fedify/fedify/vocab";
+
+/**
+ * A branded type for a single emoji character (more exactly, a single
+ * Unicode grapheme cluster of emoji).  This is used to represent a single emoji
+ * in a string format.  It is not a full-fledged emoji object, but rather a
+ * string that is guaranteed to be a single emoji.
+ *
+ * You can narrow a string to an {@link Emoji} type using the {@link isEmoji}
+ * predicate function.
+ * @since 0.2.0
+ */
+export type Emoji = string & { readonly __emoji: unique symbol };
+
+/**
+ * A type guard that checks if a value is a single emoji character.
+ * @param value The value to check.
+ * @returns `true` if the value is a single emoji character, `false` otherwise.
+ * @since 0.2.0
+ */
+export function isEmoji(value: unknown): value is Emoji {
+  if (typeof value !== "string") return false;
+
+  // First check if we have exactly one grapheme cluster
+  const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
+  const segments = [...segmenter.segment(value)];
+  if (segments.length !== 1) return false;
+
+  // Then check if this grapheme cluster has the emoji property
+  return /\p{Emoji}/u.test(segments[0].segment);
+}
 
 /**
  * The common interface for defining custom emojis.
@@ -58,13 +87,13 @@ export interface CustomEmojiFromFile extends CustomEmojiBase {
 export type CustomEmoji = CustomEmojiFromUrl | CustomEmojiFromFile;
 
 /**
- * A deferred {@link Emoji}, which is a function that takes a {@link Session}
- * and returns an {@link Emoji}.  This is useful for creating emojis that
- * depend on the session data.
+ * A deferred `Emoji` (provided by Fedify), which is a function that
+ * takes a {@link Session} and returns an `Emoji`.  This is useful for
+ * creating emojis that depend on the session data.
  * @since 0.2.0
  * @param TContextData The type of the context data.
- * @return The {@link Emoji} object.
+ * @return The `Emoji` object.
  */
-export type DeferredEmoji<TContextData> = (
+export type DeferredCustomEmoji<TContextData> = (
   session: Session<TContextData>,
-) => Emoji;
+) => EmojiObject;

src/mod.ts

@@ -32,7 +32,12 @@ export {
   Service,
   type Software,
 } from "./bot.ts";
-export { type CustomEmoji, Emoji } from "./emoji.ts";
+export {
+  type CustomEmoji,
+  type DeferredCustomEmoji,
+  type Emoji,
+  isEmoji,
+} from "./emoji.ts";
 export type * from "./events.ts";
 export type { FollowRequest } from "./follow.ts";
 export {

src/text.test.ts

@@ -29,7 +29,7 @@ import {
 } from "@std/assert";
 import { BotImpl } from "./bot-impl.ts";
 import type { BotWithVoidContextData } from "./bot.ts";
-import type { CustomEmoji, DeferredEmoji } from "./emoji.ts";
+import type { CustomEmoji, DeferredCustomEmoji } from "./emoji.ts";
 import type { Session } from "./session.ts";
 import {
   code,
@@ -156,8 +156,8 @@ const bot: BotWithVoidContextData = {
   },
   addCustomEmojis<TEmojiName extends string>(
     _emojis: Record<TEmojiName, CustomEmoji>,
-  ): Record<TEmojiName, DeferredEmoji<void>> {
-    return {} as Record<TEmojiName, DeferredEmoji<void>>;
+  ): Record<TEmojiName, DeferredCustomEmoji<void>> {
+    return {} as Record<TEmojiName, DeferredCustomEmoji<void>>;
   },
 };
 

src/text.ts

@@ -30,7 +30,7 @@ import {
 } from "@fedify/markdown-it-mention";
 import { escape } from "@std/html/entities";
 import MarkdownIt from "markdown-it";
-import type { DeferredEmoji } from "./emoji.ts";
+import type { DeferredCustomEmoji } from "./emoji.ts";
 import type { Session } from "./session.ts";
 
 /**
@@ -723,13 +723,13 @@ export function code<TContextData>(
 export class CustomEmojiText<TContextData>
   implements Text<"inline", TContextData> {
   readonly type = "inline";
-  readonly #emoji: Emoji | DeferredEmoji<TContextData>;
+  readonly #emoji: Emoji | DeferredCustomEmoji<TContextData>;
 
   /**
    * Creates a {@link CustomEmojiText} tree with a custom emoji.
    * @param emoji The custom emoji to render.
    */
-  constructor(emoji: Emoji | DeferredEmoji<TContextData>) {
+  constructor(emoji: Emoji | DeferredCustomEmoji<TContextData>) {
     this.#emoji = emoji;
   }
 
@@ -772,7 +772,7 @@ export class CustomEmojiText<TContextData>
  * @since 0.2.0
  */
 export function customEmoji<TContextData>(
-  emoji: Emoji | DeferredEmoji<TContextData>,
+  emoji: Emoji | DeferredCustomEmoji<TContextData>,
 ): Text<"inline", TContextData> {
   return new CustomEmojiText(emoji);
 }