tellegram 1.1.6 → 1.1.8

package/README.md

@@ -86,6 +86,11 @@ You can also add unsupported tags strategy as a second argument, which can be on
 - `remove` - remove unsupported tags
 - `keep` - ignore unsupported tags
 
+`convert` also accepts a third argument for feature options:
+
+- `table: 'list'` - convert GFM tables into MarkdownV2-safe hierarchical lists (default)
+- `table: 'unsupported'` - treat tables as unsupported and apply the second-argument strategy
+
 ```js
 import { convert } from 'tellegram';
 const markdown = `
@@ -111,4 +116,43 @@ convert(markdown, 'remove');
  */
 ```
 
+### Convert tables to list
+
+Telegram does not support Markdown tables. By default, teLLegraM converts a
+table into a vertical hierarchical list. In this mode, list markers and
+placeholder `-` are escaped to stay safe for Telegram MarkdownV2.
+
+```js
+import { convert } from 'tellegram';
+
+const markdown = `
+| Name  | Role  | Score |
+| ----- | ----- | ----- |
+| Alice | Admin | 95    |
+| Bob   | User  | 88    |
+`;
+
+convert(markdown, 'escape');
+/*
+\- Name: Alice
+  \- Role: Admin
+  \- Score: 95
+
+\- Name: Bob
+  \- Role: User
+  \- Score: 88
+*/
+```
+
+If you want the previous behavior (table treated as unsupported), use
+`table: 'unsupported'` with the strategy you need:
+
+```js
+convert(markdown, 'escape', { table: 'unsupported' });
+// => table is kept as escaped Markdown table text
+
+convert(markdown, 'remove', { table: 'unsupported' });
+// => ''
+```
+
 [MIT Licence](LICENSE)

package/lib/convert.mjs

@@ -7,10 +7,14 @@ import unified from 'unified';
 import { collectDefinitions, removeDefinitions } from './definitions.mjs';
 import createTellegramOptions from './tellegram.mjs';
 
-export default (markdown, unsupportedTagsStrategy = 'escape') => {
+export default (markdown, unsupportedTagsStrategy = 'escape', options = {}) => {
     const definitions = {};
 
-    const tellegramOptions = createTellegramOptions(definitions, unsupportedTagsStrategy);
+    const tellegramOptions = createTellegramOptions(
+        definitions,
+        unsupportedTagsStrategy,
+        options,
+    );
 
     return unified()
         .use(parse)

package/lib/table-to-list.mjs

@@ -0,0 +1,66 @@
+import phrasing from 'mdast-util-to-markdown/lib/util/container-phrasing.js';
+
+import { escapeSymbols } from './utils.mjs';
+
+const EMPTY_VALUE = escapeSymbols('-');
+const FALLBACK_HEADER = escapeSymbols('-');
+
+const normalizeCell = (node, context) => {
+    if (!node) {
+        return '';
+    }
+
+    const value = phrasing(node, context, { before: '', after: '' });
+    return value.replace(/\n/g, ' ').trim();
+};
+
+const normalizeHeader = (cell, index, context) => {
+    const value = normalizeCell(cell, context);
+    return value || `${FALLBACK_HEADER}`;
+};
+
+const normalizeValue = (cell, context) => {
+    const value = normalizeCell(cell, context);
+    return value || EMPTY_VALUE;
+};
+
+const pairToLine = (pair, isNested) => {
+    const prefix = isNested ? '  \\- ' : '\\- ';
+    return `${prefix}${pair.header}: ${pair.value}`;
+};
+
+export default (node, context) => {
+    if (!node.children.length) {
+        return '';
+    }
+
+    const [headerRow, ...rows] = node.children;
+    if (!headerRow || !rows.length) {
+        return '';
+    }
+
+    const headers = headerRow.children.map((cell, index) =>
+        normalizeHeader(cell, index, context));
+
+    const listRows = rows
+        .map((row, rowIndex) => {
+            const columnCount = Math.max(headers.length, row.children.length);
+            const pairs = Array.from({ length: columnCount }, (_, index) => {
+                const header = headers[index] || FALLBACK_HEADER;
+                const value = normalizeValue(row.children[index], context);
+                return { header, value };
+            });
+
+            if (!pairs.length) {
+                return `\\- Item ${rowIndex + 1}: ${EMPTY_VALUE}`;
+            }
+
+            const [first, ...rest] = pairs;
+            return [
+                pairToLine(first, false),
+                ...rest.map(pair => pairToLine(pair, true)),
+            ].join('\n');
+        });
+
+    return listRows.join('\n\n');
+};

package/lib/tellegram.mjs

@@ -3,6 +3,7 @@ import phrasing from 'mdast-util-to-markdown/lib/util/container-phrasing.js';
 import { toMarkdown as gfmTableToMarkdown } from 'mdast-util-gfm-table';
 
 import { wrap, isURL, escapeSymbols, processUnsupportedTags } from './utils.mjs';
+import tableToList from './table-to-list.mjs';
 
 /**
  * Creates custom `mdast-util-to-markdown` handlers that tailor the output for
@@ -13,7 +14,7 @@ import { wrap, isURL, escapeSymbols, processUnsupportedTags } from './utils.mjs'
  *
  * @returns {import('mdast-util-to-markdown').Handlers}
  */
-const createHandlers = (definitions, unsupportedTagsStrategy) => ({
+const createHandlers = (definitions, unsupportedTagsStrategy, options) => ({
     heading: (node, _parent, context) => {
         // make headers to be just *strong*
         const marker = '*';
@@ -134,8 +135,18 @@ const createHandlers = (definitions, unsupportedTagsStrategy) => ({
         processUnsupportedTags(defaultHandlers.blockquote(node, _parent, context), unsupportedTagsStrategy),
     html: (node, _parent, context) =>
         processUnsupportedTags(defaultHandlers.html(node, _parent, context), unsupportedTagsStrategy),
-    table: (node, _parent, context) =>
-        processUnsupportedTags(gfmTableToMarkdown().handlers.table(node, _parent, context), unsupportedTagsStrategy),
+    table: (node, _parent, context) => {
+        const tableMode = options.table || 'list';
+
+        if (tableMode === 'list') {
+            return tableToList(node, context);
+        }
+
+        return processUnsupportedTags(
+            gfmTableToMarkdown().handlers.table(node, _parent, context),
+            unsupportedTagsStrategy,
+        );
+    },
     thematicBreak: () =>
         processUnsupportedTags('---', unsupportedTagsStrategy),
 });
@@ -149,10 +160,10 @@ const createHandlers = (definitions, unsupportedTagsStrategy) => ({
  *
  * @returns {import('remark-stringify').RemarkStringifyOptions}
  */
-const createOptions = (definitions, unsupportedTagsStrategy) => ({
+const createOptions = (definitions, unsupportedTagsStrategy, options = {}) => ({
     bullet: '*',
     tightDefinitions: true,
-    handlers: createHandlers(definitions, unsupportedTagsStrategy),
+    handlers: createHandlers(definitions, unsupportedTagsStrategy, options),
 });
 
 export default createOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tellegram",
-    "version": "1.1.6",
+    "version": "1.1.8",
     "description": "Convert LLM-generated markdown into Telegram-specific markdown (MarkdownV2)",
     "type": "module",
     "main": "index.mjs",

package/types/index.d.ts

@@ -1,12 +1,23 @@
 type UnsupportedTagsStrategy = 'escape' | 'remove' | 'keep'
+type TableStrategy = 'list' | 'unsupported'
+
+interface ConvertOptions {
+  /** Table conversion mode. Default: 'list' */
+  table?: TableStrategy
+}
 
 declare module 'tellegram' {
   /**
    * Converts markdown to Telegram's format.
    * @param markdown The markdown to convert.
    * @param unsupportedTagsStrategy The strategy to use for unsupported tags.
+   * @param options Additional conversion options.
    */
-  export function convert(markdown: string, unsupportedTagsStrategy?: UnsupportedTagsStrategy): string;
+  export function convert(
+    markdown: string,
+    unsupportedTagsStrategy?: UnsupportedTagsStrategy,
+    options?: ConvertOptions
+  ): string;
 
   /**
    * Paginates text (placeholder).
@@ -16,4 +27,4 @@ declare module 'tellegram' {
 
   const defaultExport: typeof convert;
   export default defaultExport;
-}
+}