@sunafterrainwm/telegram-entities-builder 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, sunafterrainwm <sunafterrainwm@gmail.com>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/index.d.mts

@@ -0,0 +1,240 @@
+import * as TT from '@grammyjs/types';
+
+type Telegram = TT.ApiMethods<never>;
+type ApiParameters<T extends keyof Telegram> = Parameters<Telegram[T]>[0];
+/**
+ * Represents a Telegram MessageEntity without the offset and length properties.
+ */
+type PartialEntity<E extends TT.MessageEntity = TT.MessageEntity> = Omit<E, 'offset' | 'length'>;
+/**
+ * Represents any draft entity that can be used before calculating the final offset and length.
+ */
+type AnyDraftEntity = PartialEntity<TT.MessageEntity.CommonMessageEntity> | PartialEntity<TT.MessageEntity.CustomEmojiMessageEntity> | PartialEntity<TT.MessageEntity.PreMessageEntity> | PartialEntity<TT.MessageEntity.TextLinkMessageEntity> | PartialEntity<TT.MessageEntity.TextMentionMessageEntity>;
+/**
+ * Represents a segment of text which may contain one or multiple entities.
+ */
+type TextSegment = TextSegment.SingleTextSegment | TextSegment.MultiTextSegment;
+/**
+ * Namespace for TextSegment types.
+ */
+declare namespace TextSegment {
+    interface SingleTextSegment {
+        text: string;
+        entity?: AnyDraftEntity;
+        entities?: never;
+    }
+    interface MultiTextSegment {
+        text: string;
+        entity?: never;
+        entities: AnyDraftEntity[];
+    }
+}
+type PartialRequired<T, REQUIRED extends keyof T, OPTIONAL extends keyof T> = Required<Pick<T, REQUIRED>> & Pick<T, OPTIONAL>;
+/**
+ * Base interface for entity builders, providing fundamental operations for appending text and managing builder state.
+ */
+interface IEntityBuilderBase {
+    /**
+     * Appends plain text.
+     */
+    addText(text: string): this;
+    /**
+     * Appends text with a single entity.
+     */
+    addTextEntity(text: string, entity: AnyDraftEntity): this;
+    /**
+     * Appends text with multiple entities.
+     */
+    addTextEntities(text: string, entities: AnyDraftEntity[]): this;
+    /**
+     * Appends a list of text segments.
+     */
+    addTextSegmentList(segments: TextSegment[]): this;
+    /**
+     * Creates a deep clone of this builder.
+     */
+    clone(): IEntityBuilderBase;
+    /**
+     * Creates a child builder that forks from this instance.
+     */
+    fork(): IEntityBuilderBase;
+    /**
+     * Merges a forked builder back into its parent.
+     */
+    merge(wrapperEntities?: AnyDraftEntity[]): void;
+}
+/**
+ * Advanced entity builder interface supporting string manipulation, entity sorting, and payload generation.
+ */
+interface IEntityBuilder extends IEntityBuilderBase {
+    /**
+     * Trims or slices the string in-place, and automatically recalculates, filters, or truncates the affected entities.
+     */
+    sliceInplace(start?: number, end?: number): this;
+    /**
+     * Returns a new sliced instance.
+     */
+    slice(start?: number, end?: number): IEntityBuilder;
+    /**
+     * Removes leading whitespace in-place.
+     */
+    trimStart(): this;
+    /**
+     * Removes trailing whitespace in-place.
+     */
+    trimEnd(): this;
+    /**
+     * Removes leading and trailing whitespace in-place.
+     */
+    trim(): this;
+    /**
+     * Sorts the entities based on their offset and length.
+     */
+    sortEntities(): this;
+    /**
+     * Builds the payload for sending a text message.
+     */
+    buildTextPayload(): PartialRequired<ApiParameters<'sendMessage'>, 'text', 'entities' | 'link_preview_options'>;
+    /**
+     * Builds the payload for sending a document with a caption.
+     */
+    buildCaptionPayload(): PartialRequired<ApiParameters<'sendDocument'>, 'caption', 'caption_entities'>;
+    /**
+     * Builds the payload for inline query results.
+     */
+    buildInlinePayload(): PartialRequired<TT.InputTextMessageContent, 'message_text', 'entities' | 'link_preview_options'>;
+    clone(): IEntityBuilder;
+    fork(): IEntityBuilder;
+}
+/**
+ * Main implementation of IEntityBuilder that eagerly evaluates and stores entities.
+ */
+declare class EntityBuilder implements IEntityBuilder {
+    #private;
+    addText(text: string): this;
+    addTextEntity(text: string, entity: AnyDraftEntity): this;
+    addTextEntities(text: string, entities: AnyDraftEntity[]): this;
+    addTextSegmentList(segments: TextSegment[]): this;
+    buildTextPayload(): {
+        text: string;
+        entities: TT.MessageEntity[];
+    };
+    buildCaptionPayload(): {
+        caption: string;
+        caption_entities: TT.MessageEntity[];
+    };
+    buildInlinePayload(): {
+        message_text: string;
+        entities: TT.MessageEntity[];
+    };
+    sortEntities(): this;
+    sliceInplace(start?: number, end?: number): this;
+    slice(start?: number, end?: number): EntityBuilder;
+    trimStart(): this;
+    trimEnd(): this;
+    trim(): this;
+    clone(): EntityBuilder;
+    fork(): EntityBuilder;
+    /**
+     * Merges a payload text and its entities into this builder, optionally wrapping them with additional entities.
+     */
+    mergePayload(text: string, entities: TT.MessageEntity[], wrappers?: AnyDraftEntity[]): void;
+    merge(wrapperEntities?: AnyDraftEntity[]): void;
+}
+/**
+ * A lazy implementation of IEntityBuilderBase that stores segments and flattens them into an EntityBuilder only when needed.
+ */
+declare class LazyEntityBuilder implements IEntityBuilderBase {
+    #private;
+    /**
+     * Flattens the lazy segments into a new EntityBuilder instance.
+     */
+    flatten(): EntityBuilder;
+    addText(text: string): this;
+    addTextEntity(text: string, entity: AnyDraftEntity): this;
+    addTextEntities(text: string, entities: AnyDraftEntity[]): this;
+    addTextSegmentList(segments: TextSegment[]): this;
+    clone(): LazyEntityBuilder;
+    fork(): LazyEntityBuilder;
+    merge(wrapperEntities?: AnyDraftEntity[]): void;
+}
+/**
+ * Abstract proxy class that delegates all IEntityBuilder operations to an underlying builder instance.
+ */
+declare abstract class EntityBuilderProxy<THIS extends IEntityBuilder = IEntityBuilder> implements IEntityBuilder {
+    protected _entities: IEntityBuilder;
+    protected constructor(_entities: IEntityBuilder);
+    get entities(): IEntityBuilder;
+    addText(...args: Parameters<IEntityBuilder['addText']>): this;
+    addTextEntity(...args: Parameters<IEntityBuilder['addTextEntity']>): this;
+    addTextEntities(...args: Parameters<IEntityBuilder['addTextEntities']>): this;
+    addTextSegmentList(...args: Parameters<IEntityBuilder['addTextSegmentList']>): this;
+    sliceInplace(...args: Parameters<IEntityBuilder['sliceInplace']>): this;
+    slice(...args: Parameters<IEntityBuilder['slice']>): THIS;
+    trim(): this;
+    trimStart(): this;
+    trimEnd(): this;
+    sortEntities(): this;
+    clone(): THIS;
+    fork(): IEntityBuilder;
+    merge(...args: Parameters<IEntityBuilder['merge']>): void;
+    buildTextPayload(): PartialRequired<{
+        business_connection_id?: string;
+        chat_id: number | string;
+        message_thread_id?: number;
+        text: string;
+        parse_mode?: TT.ParseMode;
+        entities?: TT.MessageEntity[];
+        link_preview_options?: TT.LinkPreviewOptions;
+        disable_notification?: boolean;
+        protect_content?: boolean;
+        allow_paid_broadcast?: boolean;
+        message_effect_id?: string;
+        reply_parameters?: TT.ReplyParameters;
+        reply_markup?: TT.InlineKeyboardMarkup | TT.ReplyKeyboardMarkup | TT.ReplyKeyboardRemove | TT.ForceReply;
+        reply_to_message_id?: number;
+    }, "text", "entities" | "link_preview_options">;
+    buildCaptionPayload(): {
+        caption: string;
+        caption_entities: TT.MessageEntity[] | undefined;
+    };
+    buildInlinePayload(): {
+        message_text: string;
+        entities: TT.MessageEntity[] | undefined;
+        link_preview_options: TT.LinkPreviewOptions | undefined;
+    };
+}
+/**
+ * Escapes a string to be used as a valid tag by removing or replacing invalid characters.
+ */
+declare function escapeTag(input: string): string;
+declare const SymbolMessageComposer: unique symbol;
+/**
+ * A high-level composer that wraps an IEntityBuilder and provides additional features like tags and link preview options.
+ */
+declare class MessageComposer extends EntityBuilderProxy<MessageComposer> {
+    #private;
+    protected [SymbolMessageComposer]: true;
+    /**
+     * Options for link preview generation.
+     */
+    linkPreviewOptions?: TT.LinkPreviewOptions;
+    constructor(entities?: IEntityBuilder & {
+        [SymbolMessageComposer]?: never;
+    });
+    /**
+     * Gets the current list of tags.
+     */
+    get tags(): string[];
+    /**
+     * Adds one or more tags, escaping them and avoiding duplicates.
+     */
+    addTags(...tags: string[]): this;
+    buildTextPayload(): {
+        link_preview_options: TT.LinkPreviewOptions | undefined;
+        text: string;
+        entities?: TT.MessageEntity[] | undefined;
+    };
+}
+
+export { type AnyDraftEntity, EntityBuilder, EntityBuilderProxy, type IEntityBuilder, type IEntityBuilderBase, LazyEntityBuilder, MessageComposer, type PartialEntity, TextSegment, escapeTag };

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import * as TT from '@grammyjs/types';
+
+type Telegram = TT.ApiMethods<never>;
+type ApiParameters<T extends keyof Telegram> = Parameters<Telegram[T]>[0];
+/**
+ * Represents a Telegram MessageEntity without the offset and length properties.
+ */
+type PartialEntity<E extends TT.MessageEntity = TT.MessageEntity> = Omit<E, 'offset' | 'length'>;
+/**
+ * Represents any draft entity that can be used before calculating the final offset and length.
+ */
+type AnyDraftEntity = PartialEntity<TT.MessageEntity.CommonMessageEntity> | PartialEntity<TT.MessageEntity.CustomEmojiMessageEntity> | PartialEntity<TT.MessageEntity.PreMessageEntity> | PartialEntity<TT.MessageEntity.TextLinkMessageEntity> | PartialEntity<TT.MessageEntity.TextMentionMessageEntity>;
+/**
+ * Represents a segment of text which may contain one or multiple entities.
+ */
+type TextSegment = TextSegment.SingleTextSegment | TextSegment.MultiTextSegment;
+/**
+ * Namespace for TextSegment types.
+ */
+declare namespace TextSegment {
+    interface SingleTextSegment {
+        text: string;
+        entity?: AnyDraftEntity;
+        entities?: never;
+    }
+    interface MultiTextSegment {
+        text: string;
+        entity?: never;
+        entities: AnyDraftEntity[];
+    }
+}
+type PartialRequired<T, REQUIRED extends keyof T, OPTIONAL extends keyof T> = Required<Pick<T, REQUIRED>> & Pick<T, OPTIONAL>;
+/**
+ * Base interface for entity builders, providing fundamental operations for appending text and managing builder state.
+ */
+interface IEntityBuilderBase {
+    /**
+     * Appends plain text.
+     */
+    addText(text: string): this;
+    /**
+     * Appends text with a single entity.
+     */
+    addTextEntity(text: string, entity: AnyDraftEntity): this;
+    /**
+     * Appends text with multiple entities.
+     */
+    addTextEntities(text: string, entities: AnyDraftEntity[]): this;
+    /**
+     * Appends a list of text segments.
+     */
+    addTextSegmentList(segments: TextSegment[]): this;
+    /**
+     * Creates a deep clone of this builder.
+     */
+    clone(): IEntityBuilderBase;
+    /**
+     * Creates a child builder that forks from this instance.
+     */
+    fork(): IEntityBuilderBase;
+    /**
+     * Merges a forked builder back into its parent.
+     */
+    merge(wrapperEntities?: AnyDraftEntity[]): void;
+}
+/**
+ * Advanced entity builder interface supporting string manipulation, entity sorting, and payload generation.
+ */
+interface IEntityBuilder extends IEntityBuilderBase {
+    /**
+     * Trims or slices the string in-place, and automatically recalculates, filters, or truncates the affected entities.
+     */
+    sliceInplace(start?: number, end?: number): this;
+    /**
+     * Returns a new sliced instance.
+     */
+    slice(start?: number, end?: number): IEntityBuilder;
+    /**
+     * Removes leading whitespace in-place.
+     */
+    trimStart(): this;
+    /**
+     * Removes trailing whitespace in-place.
+     */
+    trimEnd(): this;
+    /**
+     * Removes leading and trailing whitespace in-place.
+     */
+    trim(): this;
+    /**
+     * Sorts the entities based on their offset and length.
+     */
+    sortEntities(): this;
+    /**
+     * Builds the payload for sending a text message.
+     */
+    buildTextPayload(): PartialRequired<ApiParameters<'sendMessage'>, 'text', 'entities' | 'link_preview_options'>;
+    /**
+     * Builds the payload for sending a document with a caption.
+     */
+    buildCaptionPayload(): PartialRequired<ApiParameters<'sendDocument'>, 'caption', 'caption_entities'>;
+    /**
+     * Builds the payload for inline query results.
+     */
+    buildInlinePayload(): PartialRequired<TT.InputTextMessageContent, 'message_text', 'entities' | 'link_preview_options'>;
+    clone(): IEntityBuilder;
+    fork(): IEntityBuilder;
+}
+/**
+ * Main implementation of IEntityBuilder that eagerly evaluates and stores entities.
+ */
+declare class EntityBuilder implements IEntityBuilder {
+    #private;
+    addText(text: string): this;
+    addTextEntity(text: string, entity: AnyDraftEntity): this;
+    addTextEntities(text: string, entities: AnyDraftEntity[]): this;
+    addTextSegmentList(segments: TextSegment[]): this;
+    buildTextPayload(): {
+        text: string;
+        entities: TT.MessageEntity[];
+    };
+    buildCaptionPayload(): {
+        caption: string;
+        caption_entities: TT.MessageEntity[];
+    };
+    buildInlinePayload(): {
+        message_text: string;
+        entities: TT.MessageEntity[];
+    };
+    sortEntities(): this;
+    sliceInplace(start?: number, end?: number): this;
+    slice(start?: number, end?: number): EntityBuilder;
+    trimStart(): this;
+    trimEnd(): this;
+    trim(): this;
+    clone(): EntityBuilder;
+    fork(): EntityBuilder;
+    /**
+     * Merges a payload text and its entities into this builder, optionally wrapping them with additional entities.
+     */
+    mergePayload(text: string, entities: TT.MessageEntity[], wrappers?: AnyDraftEntity[]): void;
+    merge(wrapperEntities?: AnyDraftEntity[]): void;
+}
+/**
+ * A lazy implementation of IEntityBuilderBase that stores segments and flattens them into an EntityBuilder only when needed.
+ */
+declare class LazyEntityBuilder implements IEntityBuilderBase {
+    #private;
+    /**
+     * Flattens the lazy segments into a new EntityBuilder instance.
+     */
+    flatten(): EntityBuilder;
+    addText(text: string): this;
+    addTextEntity(text: string, entity: AnyDraftEntity): this;
+    addTextEntities(text: string, entities: AnyDraftEntity[]): this;
+    addTextSegmentList(segments: TextSegment[]): this;
+    clone(): LazyEntityBuilder;
+    fork(): LazyEntityBuilder;
+    merge(wrapperEntities?: AnyDraftEntity[]): void;
+}
+/**
+ * Abstract proxy class that delegates all IEntityBuilder operations to an underlying builder instance.
+ */
+declare abstract class EntityBuilderProxy<THIS extends IEntityBuilder = IEntityBuilder> implements IEntityBuilder {
+    protected _entities: IEntityBuilder;
+    protected constructor(_entities: IEntityBuilder);
+    get entities(): IEntityBuilder;
+    addText(...args: Parameters<IEntityBuilder['addText']>): this;
+    addTextEntity(...args: Parameters<IEntityBuilder['addTextEntity']>): this;
+    addTextEntities(...args: Parameters<IEntityBuilder['addTextEntities']>): this;
+    addTextSegmentList(...args: Parameters<IEntityBuilder['addTextSegmentList']>): this;
+    sliceInplace(...args: Parameters<IEntityBuilder['sliceInplace']>): this;
+    slice(...args: Parameters<IEntityBuilder['slice']>): THIS;
+    trim(): this;
+    trimStart(): this;
+    trimEnd(): this;
+    sortEntities(): this;
+    clone(): THIS;
+    fork(): IEntityBuilder;
+    merge(...args: Parameters<IEntityBuilder['merge']>): void;
+    buildTextPayload(): PartialRequired<{
+        business_connection_id?: string;
+        chat_id: number | string;
+        message_thread_id?: number;
+        text: string;
+        parse_mode?: TT.ParseMode;
+        entities?: TT.MessageEntity[];
+        link_preview_options?: TT.LinkPreviewOptions;
+        disable_notification?: boolean;
+        protect_content?: boolean;
+        allow_paid_broadcast?: boolean;
+        message_effect_id?: string;
+        reply_parameters?: TT.ReplyParameters;
+        reply_markup?: TT.InlineKeyboardMarkup | TT.ReplyKeyboardMarkup | TT.ReplyKeyboardRemove | TT.ForceReply;
+        reply_to_message_id?: number;
+    }, "text", "entities" | "link_preview_options">;
+    buildCaptionPayload(): {
+        caption: string;
+        caption_entities: TT.MessageEntity[] | undefined;
+    };
+    buildInlinePayload(): {
+        message_text: string;
+        entities: TT.MessageEntity[] | undefined;
+        link_preview_options: TT.LinkPreviewOptions | undefined;
+    };
+}
+/**
+ * Escapes a string to be used as a valid tag by removing or replacing invalid characters.
+ */
+declare function escapeTag(input: string): string;
+declare const SymbolMessageComposer: unique symbol;
+/**
+ * A high-level composer that wraps an IEntityBuilder and provides additional features like tags and link preview options.
+ */
+declare class MessageComposer extends EntityBuilderProxy<MessageComposer> {
+    #private;
+    protected [SymbolMessageComposer]: true;
+    /**
+     * Options for link preview generation.
+     */
+    linkPreviewOptions?: TT.LinkPreviewOptions;
+    constructor(entities?: IEntityBuilder & {
+        [SymbolMessageComposer]?: never;
+    });
+    /**
+     * Gets the current list of tags.
+     */
+    get tags(): string[];
+    /**
+     * Adds one or more tags, escaping them and avoiding duplicates.
+     */
+    addTags(...tags: string[]): this;
+    buildTextPayload(): {
+        link_preview_options: TT.LinkPreviewOptions | undefined;
+        text: string;
+        entities?: TT.MessageEntity[] | undefined;
+    };
+}
+
+export { type AnyDraftEntity, EntityBuilder, EntityBuilderProxy, type IEntityBuilder, type IEntityBuilderBase, LazyEntityBuilder, MessageComposer, type PartialEntity, TextSegment, escapeTag };