usefulTags

A tiny JavaScript library providing some useful template tag functions.

code size: < 10kb license: MIT release: 1.x.x codefactor: A+ code style: prettier

usefulTags is a compact JavaScript library that adds a handful of commonly used template tags. It aims to be small and simple by adding what I see to be the 4 most helpful.

By default, template strings preserve all newlines and indents, which can be irritating and make source code look awful. usefulTags' primary purpose is to resolve this issue in the vast majority of use cases, with 4 tags for managing newlines and indents.

import {stripIndent} from "usefultags";

stripIndent`
    Hello,
      World!`;
/*
Output (has no extra indents):
Hello,
  World!
*/

Table of Contents

Usage

The examples demonstrate this much better. Simply use the funtion as a template tag.

When used as a regular function, any type is accepted (has no effect on non-string and non-array inputs).

A string is always returned no matter what.

See available tags for usage examples.

Requirements

  • Any version of Node.js / iojs
  • Any version of Deno
  • Any other environment supporting ES5

usefulTags supports the vast majority of module loaders (CommonJS, ESModules, RequireJS, Script Tags, etc.) thanks to UMD.

usefulTags works with transpilers like TypeScript and Babel, so you can write template literals in modern ES2015 syntax and transform it to ES5.

Importing

See importable functions at available tags.

The default suggested namespace is usefulTags if you choose not to pollute the global namespace.

Node

Install with NPM (or whatever other package manager you use):

npm i usefultags
//CommonJS loader:
const {stripIndent} = require("usefultags");
//RequireJS loader (assuming it's already configured for Node):
requirejs(["usefultags"], (usefulTags) => {
    //...
});
//ESModule loader
import {stripIndent} from "usefultags";

Browsers

<!--If you have no module loader, use this script (ensure you replace @ver with a version tag)-->
<!--The namespace is "usefulTags" or "window.usefulTags"-->
<script src="https://unpkg.com/usefultags@ver"></script>
//RequireJS loader (ensure you replace @ver with a version tag)
requirejs(["https://unpkg.com/usefultags@ver"], (usefulTags) => {
    //...
});
//ESModule loader (again, ensure you replace @ver with a version tag)
//Remember that the ESModule version is located in the /dist/usefulTags.mjs path
import {stripIndent} from "https://unpkg.com/usefultags@ver/dist/usefulTags.mjs";

Deno

//Ensure you replace @ver with a version tag
//This will import the module with TypeScript type defenitions (v1.1.0 and later)
//For regular JavaScript you should do a more traditional import like Node.js
import * as usefulTags from "https://deno.land/x/usefultags@ver/usefulTags.mjs";
import * as _usefulTags from "https://deno.land/x/usefultags@ver/usefulTags.d.ts";
const {stripIndent} = usefulTags as typeof _usefulTags;

Available Tags:

These are all of the tags exposed by usefulTags.

stripIndent

Remove initial indentation from each line in a multi-line string, but keep intentionally larger indents. Useful in deep nesting to keep multi-line strings looking clean and operational.

Note that if you mix tabs and spaces, there will be horrible results using this.

const line = stripIndent`
        This
        is
        ${"a"}
        multi-line
        newline
         
            indented  
        string.
        Random number: ${Math.random()}.`;
console.log(line);

/*Output:
This
is
a
multi-line
newline
 
    indented  
string.
Random number: 0.xxxxxxxxxxxxxxxx.
*/

stripAllIndents

Remove all indentation from each line in a multi-line string. Useful in deep nesting to keep multi-line strings looking clean and operational.

const line = stripAllIndents`This
    is
         ${"a"}
      multi-line
        newline
         
            indented  
        string.
        Random number: ${Math.random()}.`;
console.log(line);

/*Output:
This
is
a
multi-line
newline

indented  
string.
Random number: 0.xxxxxxxxxxxxxxxx.
*/

oneLine

Merge a multi-line string onto one line. Useful for keeping long lines looking nice in source code.

const line = oneLine`
        This
        is
        ${"a"}
        multi-line
        newline
         
            indented  /
        string.
        Random number: ${Math.random()}.`;
console.log(line);

/*Output:
This is a multi-line newline indented  / string. Random number: 0.xxxxxxxxxxxxxxxx.
*/

oneLineConcatenate

Merge a multi-line string onto one line, without spaces. Useful for URLs constructed using template literals.

const line = oneLineConcatenate`
        This
        is
        ${"a"}
        multi-line
        newline
         
            indented  /
        string.
        Random number: ${Math.random()}.`;
console.log(line);

/*Output:
Thisisamulti-linenewlineindented  /string.Random number: 0.xxxxxxxxxxxxxxxx.
*/

Tags on Regular Strings

If needed, you can always use a template tag without an actual template string. Supply a string or array of strings as an argument to the function.

stripIndent("    Hello,\n     World!");
/*Output:
Hello,
 World!
*/

TypeScript Usage

usefulTags v1.1.0 and later ship with TypeScript type defenitions by default. They should automatically be loaded when used in Node.js. For Deno, the instructions in Importing/Deno detail how to import with type defenitions.

License

usefulTags is licensed under the MIT License.