@quadratz/do-not-use-this-package

Telegram Abstract Syntax Tree for Telegram message entities.

tgast provides a way to represent Telegram message entities as a structured format called an Abstract Syntax Tree (AST). It's built using the unist specification, making it easy to work with and extend.

For released versions, see releases.

Contents

• Introduction
  • Where this specification fits
• Installation
• Nodes
  • Blockquote
  • Bold
  • BotCommand
  • Cashtag
  • Code
  • CustomEmoji
  • Email
  • ExpandableBlockquote
  • Hashtag
  • Italic
  • Mention
  • PhoneNumber
  • Pre
  • Spoiler
  • Strikethrough
  • Text
  • TextLink
  • TextMention
  • Underline
  • Url
• Glossary
• References
• Related

Introduction

tgast is a specification for representing Telegram message entities as an Abstract Syntax Tree (AST). It was initially created for the regram project.

Where this specification fits

tgast leverages the unist format for syntax trees, allowing you to benefit from its extensive ecosystem of utilities.

tgast is used within the regram and unified projects for processing Telegram message content.

Installation

If you are using TypeScript, you can use the tgast types by installing them with jsr or npm:

# deno
deno add -D jsr:@qz/tgast

# bun
bunx jsr add -D @qz/tgast

# pnpm
pnpm dlx jsr add -D @qz/tgast

# yarn
yarn dlx jsr add -D @qz/tgast

# npm jsr
npx jsr add -D @qz/tgast

# npm
npm add -D tgast

Nodes

Blockquote

interface Blockquote extends Parent {
  type: "blockquote";
  data?: BlockquoteData;
  position?: Position;
  children: PhrasingContent[];
}

Blockquote (type reference): Telegram block quotation. Represents blockquote entities in Telegram messages.

Example:

{
  "text": "This is a blockquote.",
  "entities": [
    {
      "offset": 0,
      "length": 21,
      "type": "blockquote"
    }
  ]
}

Yields:

{
  type: "blockquote",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 22,
      offset: 21
    }
  },
  children: [
    { 
      type: "text",
      value: "This is a blockquote.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 1,
          column: 22,
          offset: 21
        }
      }
    }
  ],
}

Bold

interface Bold extends Parent {
  type: "bold";
  data?: BoldData;
  position?: Position;
  children: PhrasingContent[];
}

Bold (type reference): Telegram bold text. Represents bold entities in Telegram messages.

Example:

{
  "text": "This is a bold text.",
  "entities": [
    {
      "offset": 0,
      "length": 20,
      "type": "bold"
    }
  ]
}

Yields:

{
  type: "bold",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 21,
      offset: 20
    }
  },
  children: [
    { 
      type: "text",
      value: "This is a bold text.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 1,
          column: 21,
          offset: 20
        }
      }
    }
  ]
}

BotCommand

interface BotCommand extends Literal {
  type: "bot_command";
  value: string;
  data?: BotCommandData;
  position?: Position;
}

BotCommand (type reference): Telegram bot command. Represents bot_command entities in Telegram messages.

Example:

{
  "text": "/start@entityparser_qz_bot",
  "entities": [
    {
      "offset": 0,
      "length": 26,
      "type": "bot_command"
    }
  ]
}

Yields:

{
  type: "bot_command",
  value: "/start@entityparser_qz_bot",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 27,
      offset: 26
    }
  }
}

Cashtag

interface Cashtag extends Literal {
  type: "cashtag";
  value: string;
  data?: CashtagData;
  position?: Position;
}

Cashtag (type reference): Telegram cashtag. Represents cashtag entities in Telegram messages.

Example:

{
  "text": "$IDR",
  "entities": [
    {
      "offset": 0,
      "length": 4,
      "type": "cashtag"
    }
  ]
}

Yields:

{
  type: "cashtag",
  value: "$IDR",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 5,
      offset: 4
    }
  }
}

Code

interface Code extends Literal {
  type: "code";
  value: string;
  data?: CodeData;
  position?: Position;
}

Code (type reference): Telegram monowidth string. Represents code entities in Telegram messages.

Example:

{
  "text": "This is a monowidth string.",
  "entities": [
    {
      "offset": 0,
      "length": 27,
      "type": "code"
    }
  ]
}

Yields:

{
  type: "code",
  value: "This is a monowidth string.",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 28,
      offset: 27
    }
  }
}

CustomEmoji

interface CustomEmoji extends Literal {
  type: "custom_emoji";
  emojiId: string;
  value: string;
  data?: CustomEmojiData;
  position?: Position;
}

CustomEmoji (type reference): Telegram custom emoji. Represents custom_emoji entities in Telegram messages.

Example:

{
  "text": "👀",
  "entities": [
    {
      "offset": 0,
      "length": 2,
      "type": "custom_emoji",
      "custom_emoji_id": "5269436882302811645"
    }
  ]
}

Yields:

{
  type: "custom_emoji",
  emojiId: "5269436882302811645",
  value: "👀",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 3,
      offset: 2
    }
  }
}

Email

interface Email extends Literal {
  type: "email";
  value: string;
  data?: EmailData;
  position?: Position;
}

Email (type reference): Telegram email address. Represents email entities in Telegram messages.

Example:

{
  "text": "[e-mail]",
  "entities": [
    {
      "offset": 0,
      "length": 18,
      "type": "email"
    }
  ]
}

Yields:

{
  type: "email",
  value: "[e-mail]",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 19,
      offset: 18
    }
  }
}

ExpandableBlockquote

interface ExpandableBlockquote extends Parent {
  type: "expandable_blockquote";
  data?: ExpandableBlockquoteData;
  position?: Position;
  children: PhrasingContent[];
}

ExpandableBlockquote (type reference): Telegram expandable blockquote. Represents expandable_blockquote entities in Telegram messages.

Example:

{
  "text": "This\nis\nan\nexpandable\nblockquote.",
  "entities": [
    {
      "offset": 0,
      "length": 33,
      "type": "expandable_blockquote"
    }
  ]
}

Yields:

{
  type: "expandable_blockquote",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 5,
      column: 12,
      offset: 33
    }
  },
  children: [
    { 
      type: "text",
      value: "This\nis\nan\nexpandable\nblockquote.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 5,
          column: 12,
          offset: 33
        }
      }
    }
  ]
}

Hashtag

interface Hashtag extends Literal {
  type: "hashtag";
  value: string;
  data?: HashtagData;
  position?: Position;
}

Hashtag (type reference): Telegram hashtag. Represents hashtag entities in Telegram messages.

Example:

{
  "text": "#DontBeEvil",
  "entities": [
    {
      "offset": 0,
      "length": 11,
      "type": "hashtag"
    }
  ]
}

Yields:

{
  type: "hashtag",
  value: "#DontBeEvil",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 12,
      offset: 11
    }
  }
}

Italic

interface Italic extends Parent {
  type: "italic";
  data?: ItalicData;
  position?: Position;
  children: PhrasingContent[];
}

Italic (type reference): Telegram italic text. Represents italic entities in Telegram messages.

Example:

{
  "text": "This is an italic text.",
  "entities": [
    {
      "offset": 0,
      "length": 23,
      "type": "italic"
    }
  ]
}

Yields:

{
  type: "italic",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 24,
      offset: 23
    }
  },
  children: [
    { 
      type: "text",
      value: "This is an italic text.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 1,
          column: 24,
          offset: 23
        }
      }
    }
  ]
}

Mention

interface Mention extends Literal {
  type: "mention";
  value: string;
  data?: MentionData;
  position?: Position;
}

Mention (type reference): Telegram mention. Represents mention entities in Telegram messages.

Example:

{
  "text": "@quadratz",
  "entities": [
    {
      "offset": 0,
      "length": 9,
      "type": "mention"
    }
  ]
}

Yields:

{
  type: "mention",
  value: "@quadratz",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 10,
      offset: 9
    }
  }
}

PhoneNumber

interface PhoneNumber extends Literal {
  type: "phone_number";
  value: string;
  data?: PhoneNumberData;
  position?: Position;
}

PhoneNumber (type reference): Telegram phone number. Represents phone_number entities in Telegram messages.

Example:

{
  "text": "[phone]",
  "entities": [
    {
      "offset": 0,
      "length": 15,
      "type": "phone_number"
    }
  ]
}

Yields:

{
  type: "phone_number",
  value: "[phone]",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 16,
      offset: 15
    }
  }
}

Pre

interface Pre extends Literal {
  type: "pre";
  value: string;
  language?: string;
  data?: PreData;
  position?: Position;
}

Pre (type reference): Telegram monowidth block. Represents pre entities in Telegram messages.

Example:

{
  "text": "console.log(\"This is a monowidth block.\");",
  "entities": [
    {
      "offset": 0,
      "length": 42,
      "type": "pre",
      "language": "JavaScript"
    }
  ]
}

Yields:

{
  type: "pre",
  value: "console.log(\"This is a monowidth block.\");",
  language: "JavaScript",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 43,
      offset: 42
    }
  }
}

Spoiler

interface Spoiler extends Parent {
  type: "spoiler";
  data?: SpoilerData;
  position?: Position;
  children: PhrasingContent[];
}

Spoiler (type reference) Telegram spoiler message. Represents spoiler entities in Telegram messages.

Example:

{
  "text": "This is a spoiler text.",
  "entities": [
    {
      "offset": 0,
      "length": 23,
      "type": "spoiler"
    }
  ]
}

Yields:

{
  type: "spoiler",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 24,
      offset: 23
    }
  },
  children: [
    { 
      type: "text",
      value: "This is a spoiler text.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 1,
          column: 24,
          offset: 23
        }
      }
    }
  ]
}

Strikethrough

interface Strikethrough extends Parent {
  type: "strikethrough";
  data?: StrikethroughData;
  position?: Position;
  children: PhrasingContent[];
}

Strikethrough (type reference): Telegram strikethrough text. Represents strikethrough entities in Telegram messages.

Example:

{
  "text": "This is a strikethrough text.",
  "entities": [
    {
      "offset": 0,
      "length": 29,
      "type": "strikethrough"
    }
  ]
}

Yields:

{
  type: "strikethrough",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 30,
      offset: 29
    }
  },
  children: [
    { 
      type: "text",
      value: "This is a strikethrough text.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 1,
          column: 30,
          offset: 29
        }
      }
    }
  ]
}

Text

interface Text extends Literal {
  type: "text";
  value: string;
  data?: TextData;
}

Text (type reference): Telegram plain text. Represents plain text content in Telegram messages.

Example:

{
  "text": "This is a plain text."
}

Yields:

{
  type: "text",
  value: "This is a plain text.",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 22,
      offset: 21
    }
  }
}

TextLink

interface TextLink extends Literal {
  type: "text_link";
  value: string;
  url: string;
  data?: TextLinkData;
  position?: Position;
}

TextLink (type reference): Telegram clickable text URL. Represents text_link entities in Telegram messages.

Example:

{
  "text": "Click me!",
  "entities": [
    {
      "offset": 0,
      "length": 9,
      "type": "text_link",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  ]
}

Yields:

{
  type: "text_link",
  value: "Click me!",
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 10,
      offset: 9
    }
  }
}

TextMention

interface TextMention extends Literal {
  type: "text_mention";
  value: string;
  user: User;
  data?: TextMentionData;
  position?: Position;
}

TextMention (type reference): Telegram mentions for users without usernames. Represents text_mention entities in Telegram messages.

Example:

{
  "text": "Qz",
  "entities": [
    {
      "offset": 0,
      "length": 2,
      "type": "text_mention",
      "user": {
        "id": 423623658,
        "is_bot": false,
        "first_name": "Qz",
        "language_code": "en"
      }
    }
  ]
}

Yields:

{
  type: "text_mention",
  value: "Qz",
  user: {
    id: 423623658,
    is_bot: false,
    first_name: "Qz",
    language_code: "en"
  },
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 3,
      offset: 2
    }
  }
}

Underline

interface Underline extends Parent {
  type: "underline";
  data?: UnderlineData;
  position?: Position;
  children: PhrasingContent[];
}

Underline (type reference): Telegram underline text. Represents underline entities in Telegram messages.

Example:

{
  "text": "This is an underlined text.",
  "entities": [
    {
      "offset": 0,
      "length": 27,
      "type": "underline"
    }
  ]
}

Yields:

{
  type: "underline",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 28,
      offset: 27
    }
  },
  children: [
    { 
      type: "text",
      value: "This is an underlined text.",
      position: {
        start: {
          line: 1,
          column: 1,
          offset: 0
        },
        end: {
          line: 1,
          column: 28,
          offset: 27
        }
      }
    }
  ]
}

Url

interface Url extends Literal {
  type: "url";
  value: string;
  data?: UrlData;
  position?: Position;
}

Url (type reference): Telegram URL. Represents url entities in Telegram messages.

Example:

{
  "text": "https://t.me/quadratz",
  "entities": [
    {
      "offset": 0,
      "length": 21,
      "type": "url"
    }
  ]
}

Yields:

{
  type: "url",
  value: "https://t.me/quadratz",
  position: {
    start: {
      line: 1,
      column: 1,
      offset: 0
    },
    end: {
      line: 1,
      column: 22,
      offset: 21
    }
  }
}

Glossary

See § Glossary in syntax-tree/unist.

References

• regram: regram. Quadratz.
• unist: Universal Syntax Tree. T. Wormer; et al.
• Telegram Bot API: Telegram Message Entity. Telegram.

Related

• mdast — Markdown Abstract Syntax Tree format
• hast — HTML Abstract Syntax Tree format
• nlcst — Natural Language Concrete Syntax Tree format
• xast — Extensible Abstract Syntax Tree