Can't add custom formatter (Object literal may only specify known properties, and ''sub'' does not exist in type 'TagDefinitions'.)

[willismonroe]

The goal
I'm trying to add a subscript formatter to replace the numbers in the sub tag with their unicode equivalents.

This is in Vue3 with typescript, I've added the "@types/html-to-text" to my project, but when I add the custom formatter to the "tags" property I get a typescript error:

Failed to compile.
src/components/Editor.vue:42:15
TS2322: Type '{ sub: { format: string; options: { leadingLineBreaks: number; trailingLineBreaks: number; }; }; p: { options: { leadingLineBreaks: number; trailingLineBreaks: number; }; }; pre: { options: { leadingLineBreaks: number; trailingLineBreaks: number; }; }; }' is not assignable to type 'TagDefinitions'.
  Object literal may only specify known properties, and ''sub'' does not exist in type 'TagDefinitions'.
    40 |             },
    41 |             tags: {
  > 42 |               'sub': { format: 'subscriptFormatter', options: { leadingLineBreaks: 1, trailingLineBreaks: 1 }},
       |               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    43 |               'p': {options: {leadingLineBreaks: 1, trailingLineBreaks: 1}},
    44 |               'pre': {options: {leadingLineBreaks: 1, trailingLineBreaks: 1}}
    45 |             }

Here's the relevant segment of the code (the formatter is obviously unfinished i was just trying stuff out):

    const rawText = computed(() => {
      return htmlToText(editorContent.value ?? '',
          {
            formatters: {
              'subscriptFormatter': function(elem, walk, builder) {
                console.log(elem.children)
                walk(elem.children, builder)
              }
            },
            tags: {
              'sub': { format: 'subscriptFormatter', options: { leadingLineBreaks: 1, trailingLineBreaks: 1 }},
              'p': {options: {leadingLineBreaks: 1, trailingLineBreaks: 1}},
              'pre': {options: {leadingLineBreaks: 1, trailingLineBreaks: 1}}
            }
          })
    })

[KillyMXI]

I guess this is an issue with how TagDefinitions are defined in DefinitelyTyped repo.
I have no connection to those who maintain that.

It must be open for new keys in order to work properly.
Relevant SO question.

[willismonroe]

Got it, thanks for the prompt response.

So I guess I need to add something like:
[tag: string]: TagDefinition
to the interface? That will allow custom tags to be added I guess.

[KillyMXI]

Yep.

And I'm not sure why they decided to specify existing tags instead of just tags?: Record<string, TagDefinition>;.
Might be remains from old versions that didn't allow for custom tags... (I forgot I've introduced the tags field in v6)

That being said, @types/html-to-text is currently at v6 and doesn't contain the changes in the builder method arguments introduced in v7.

[willismonroe]

I noticed in the DefinitelyTyped repository they say that they only cover types not bundled in the repository itself. Is this something that html-to-text might want to do in the future? I have no experience with this type of development, but it seems like it might be easier than trying to maintain types in another project.

[KillyMXI]

At some point - yes, I think.

[webstech]

Not going to research but I think it was unclear if tags supported any element or only specific elements. The DT code assumes specific elements. The updates for v8 will allow any element (or selector under the new config). tags will not be changed.

[KillyMXI]

It looks to me that DT got the type for tags the way tsc --allowJs --emitDeclarationsOnly emits it.
Some attention to the docs required to see that it was actually a documented extension point in v6/v7.
Current documentation doesn't describe deprecated options.

[KillyMXI]

Thanks to @webstech effort, types for v8 are now available.
I consider this issue resolved - everyone are on the same page now.
Most importantly, I'm happy it happened now and gives a heads-up before v9 (where a big cleanup is planned).

Clarification on bundling types with html-to-text package itself:
It's always on the table. I'm quite dissatisfied with jsdoc limitations, but I also don't want to support two separate type definition systems.
I couldn't figure out before how to make d.ts work with intellisense. But as the code is getting more organized, I might as well convert it to TypeScript altogether. Not sure yet when exactly it will happen though.