or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

custom-tags.mdhtml-templates.mdindex.mdlist-formatting.mdstring-processing.md
tile.json

tessl/npm-common-tags

A set of well-tested template literal tag functions for ES2015+ that solve common string manipulation and formatting problems.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/common-tags@1.8.x

To install, run

npx @tessl/cli install tessl/npm-common-tags@1.8.0

index.mddocs/

Common Tags

Common Tags is a comprehensive set of well-tested template literal tag functions for ES2015+ that solve common string manipulation and formatting problems in JavaScript development. It offers specialized tags for stripping indentation, converting multiline strings to single lines, safely rendering HTML with XSS protection, and formatting arrays as lists with various delimiters and conjunctions.

Package Information

  • Package Name: common-tags
  • Package Type: npm
  • Language: JavaScript (ES2015+)
  • Installation: npm install common-tags

Core Imports

import { stripIndent, html, oneLine, commaLists } from "common-tags";

For CommonJS:

const { stripIndent, html, oneLine, commaLists } = require("common-tags");

Direct module imports (for tree-shaking):

import stripIndent from "common-tags/lib/stripIndent";
import html from "common-tags/lib/html";

Basic Usage

import { stripIndent, html, commaLists } from "common-tags";

// Strip indentation while preserving relative indents
const code = stripIndent`
  function hello() {
    console.log("Hello World");
  }
`;

// Render HTML with proper indentation
const items = ['apple', 'banana', 'cherry'];
const htmlOutput = html`
  <ul>
    ${items.map(item => `<li>${item}</li>`)}
  </ul>
`;

// Format arrays as comma-separated lists
const message = commaLists`
  I like ${['apples', 'bananas', 'watermelons']}
  They're delicious!
`;
// "I like apples, bananas, watermelons\nThey're delicious!"

Architecture

Common Tags is built on a flexible TemplateTag class architecture that supports transformer plugins and composable pipelines:

  • Core Foundation: TemplateTag class that processes template literals through transformer plugins
  • Pre-built Tags: 16 ready-to-use template tags for common use cases
  • Transformer System: 8 built-in transformers for creating custom tags
  • Plugin Pipeline: Composable architecture allowing multiple transformers per tag
  • Tail Processing: Advanced composition pattern for chaining template tags

Capabilities

String Processing Tags

Core template tags for manipulating string formatting and indentation. Perfect for code generation, template rendering, and text processing.

// Strip indentation while preserving relative structure
function stripIndent(strings, ...expressions): string;

// Strip all indentation from every line
function stripIndents(strings, ...expressions): string;

// Convert multiline strings to single line
function oneLine(strings, ...expressions): string;

// Convert to single line and trim whitespace
function oneLineTrim(strings, ...expressions): string;

String Processing

HTML Template Tags

HTML-focused template tags with indentation handling and XSS protection for safe HTML rendering.

// Render HTML with proper array and newline indentation
function html(strings, ...expressions): string;

// HTML-safe rendering with XSS protection
function safeHtml(strings, ...expressions): string;

HTML Templates

List Formatting Tags

Template tags specialized for formatting arrays as readable lists with various separators and conjunctions.

// Render arrays as space-separated lists
function inlineLists(strings, ...expressions): string;

// Render arrays as comma-separated lists  
function commaLists(strings, ...expressions): string;

// Comma-separated with "and" conjunction
function commaListsAnd(strings, ...expressions): string;

// Comma-separated with "or" conjunction
function commaListsOr(strings, ...expressions): string;

List Formatting

Custom Tag Creation

Powerful TemplateTag class and transformer system for building custom template tags with composable functionality.

// Core class for creating custom template tags
class TemplateTag {
  constructor(...transformers);
  tag(strings, ...expressions): string | Function;
}

// Built-in transformers for common operations
function trimResultTransformer(side?: string): Transformer;
function stripIndentTransformer(type?: string): Transformer; 
function inlineArrayTransformer(opts?: ArrayOptions): Transformer;
function replaceResultTransformer(replaceWhat: string | RegExp, replaceWith: string): Transformer;

Custom Tag Creation

Type Definitions

interface Transformer {
  onString?(str: string): string;
  onSubstitution?(substitution: any, resultSoFar: string): any;
  onEndResult?(endResult: string): string;
}

interface ArrayOptions {
  separator?: string;    // Default: ''
  conjunction?: string;  // Default: ''  
  serial?: boolean;     // Default: false
}

Advanced Features

Tail Processing

All template tags support tail processing by accepting a function as the first argument:

import { oneLine } from "common-tags";

// Instead of nested template tags
oneLine`${String.raw`foo\nbar`}`;

// Use tail processing for cleaner composition
oneLine(String.raw)`foo\nbar`;

Function Call Usage

Template tags can be called as regular functions on strings:

import { stripIndent } from "common-tags";

// Use as template tag
const result1 = stripIndent`
  indented text
`;

// Use as function
const result2 = stripIndent("  indented text\\n    more text");