@qnighy/dedent: JS multi-line literal done right

1import { dedent } from "@qnighy/dedent";
2
3const mdDoc = dedent`\
4  ## Hello!
5
6  - Plants
7    - Apples
8    - Oranges
9  - Animals
10    - Dogs
11    - Cats
12`;

Simple, yet expressive

The dedent function does only one thing: it removes indentation as it appears in the source code in a template literal.

Therefore the result is easily predictable. Additionally, you can express any text using the dedent function.

1import { dedent } from "@qnighy/dedent";
2
3// End-of-line at the end
4const eol = dedent`\
5  foo
6  bar
7`;
8// No end-of-line at the end
9const noEol = dedent`\
10  foo
11  bar`;
12
13// With all lines indented
14const withIndent = dedent`\
15  \
16    This line is the 1st line. It has 2 spaces of indentation.
17    This line is the 2nd line. It has 2 spaces of indentation.
18`;

Tagged literal

Tagged literals are also supported. You can write

1import { dedent } from "@qnighy/dedent";
2
3const text = dedent(myTag)`\
4  foo
5  ${bar}
6`;

for

1const text = myTag`\
2foo
3${bar}
4`;

which is often equivalent to:

1const text = myTag`foo
2${bar}
3`;

With or without code transformation

You do not need to configure Babel or SWC or whatever to use @qnighy/dedent. Simply import the function and you are ready to use it.

Though you can use @qnighy/babel-plugin-dedent or @qnighy/swc-plugin-dedent if you need optimization.

Installation

(NOTE: not released yet)

yarn add -D @qnighy/dedent
# OR:
npm install -D @qnighy/dedent

Detailed rules

Indenting some lines in the indented text

Indentation is determined based on the longest common indentation among lines. Therefore, you can have some lines indented among other lines.

1const text = dedent`\
2  non-indented line
3    indented line
4`;

The first line

It does not remove indentation of the first line, as it is always preceded by a backtick `. Remember that the library removes indentation as it appears in the source code.

1const text = dedent`  indented line
2  non-indented line
3`;

That is why we recommend putting a backslash \ immediately after the backtick `, like this:

1const text = dedent`\
2  the above backslash (\\)
3  tells JS to join the lines.
4`;

Counting

Spaces and tabs are counted equally. The result would be unpredictable should you mix spaces and tabs.

Lines containing only spaces and tabs

Lines containing only spaces and tabs are considered to have infinity number of indentation.

If they are shorter than the inferred indentation, they become empty. Otherwise, there remain some spaces or tabs.

1const text = dedent`\
2  1st line
3
4  3rd line. The above line is empty.
5`;

The closing backtick ` is not accounted for in this rule. Therefore, in the example above, last line is considered to be empty.

Escapes and interpolations

This library removes indentation as it appears in the source code. Therefore, escapes and interpolations are both considered to be non-space elements.

1const text = dedent`\
2  \x20 <- This is a non-space element
3  ${" "} <- This is a non-space element too
4`;

However, indentation within interpolated expressions are excluded from this rule, as we cannot reliably know the indentation there.

1// prettier-ignore
2const text = dedent`\
3  ${
4"Indentation is still removed"
5  }
6`;

This is the only exception to the aforementioned rule.

Newline characters

There are three types of newline in JS:

• LF (\n)
• LS (\u2028)
• PS (\u2029)

They all start new lines. Note that CR (\r) and CRLF (\r\n) in the source text are automatically converted to LF (\n) before parsing, thus the library cannot distinguish between LF, CR, and CRLF.

License

MIT