Custom Tag Creation

/**
 * Creates a custom template tag with composable transformer pipeline
 * @param transformers - Array or arguments list of transformer objects/functions
 * @returns Template tag function (constructor returns this.tag, not the instance)
 */
class TemplateTag {
  constructor(...transformers): Function;
  
  /**
   * Main template tag method that processes template literals
   * @param strings - Template string parts or function for tail processing
   * @param expressions - Template substitution values
   * @returns Processed string or intermediary function for composition
   */
  tag(strings, ...expressions): string | Function;
}

import { TemplateTag, trimResultTransformer, replaceResultTransformer } from "common-tags";

// Create a simple custom tag
const upperCase = new TemplateTag({
  onEndResult(result) {
    return result.toUpperCase();
  }
});

const greeting = upperCase`Hello ${name}!`;
// Result: "HELLO JOHN!"

// Create tag with multiple transformers
const cleanCode = new TemplateTag(
  trimResultTransformer(),
  replaceResultTransformer(/\s+/g, ' '),  // Normalize whitespace
  {
    onEndResult(result) {
      return result.replace(/;/g, ';\n');  // Add newlines after semicolons
    }
  }
);

const code = cleanCode`
  const a = 1; const b = 2; console.log(a + b);
`;
// Result: "const a = 1;\n const b = 2;\n console.log(a + b);"

/**
 * Trims whitespace from the end result
 * @param side - Optional side to trim: 'start'/'left', 'end'/'right', or '' for both
 * @returns Transformer object with onEndResult method
 */
function trimResultTransformer(side?: string): Transformer;

import { TemplateTag, trimResultTransformer } from "common-tags";

// Trim both sides (default)
const trimBoth = new TemplateTag(trimResultTransformer());

// Trim only start
const trimStart = new TemplateTag(trimResultTransformer('start'));

// Trim only end  
const trimEnd = new TemplateTag(trimResultTransformer('end'));

const text = trimBoth`
  Some text with whitespace  
`;
// Result: "Some text with whitespace"

/**
 * Replaces patterns in the final result
 * @param replaceWhat - String or RegExp pattern to replace
 * @param replaceWith - Replacement string
 * @returns Transformer object with onEndResult method
 */
function replaceResultTransformer(replaceWhat: string | RegExp, replaceWith: string): Transformer;

import { TemplateTag, replaceResultTransformer } from "common-tags";

// Replace specific strings
const normalize = new TemplateTag(
  replaceResultTransformer('TODO', 'FIXME'),
  replaceResultTransformer(/\s+/g, ' ')  // Normalize whitespace
);

const note = normalize`TODO:   Fix   this   later`;
// Result: "FIXME: Fix this later"

/**
 * Strips indentation from lines
 * @param type - 'initial' removes shortest indent, 'all' removes all indentation
 * @returns Transformer object with onEndResult method
 */
function stripIndentTransformer(type?: string): Transformer;

import { TemplateTag, stripIndentTransformer } from "common-tags";

// Remove initial indent (default)
const stripInitial = new TemplateTag(stripIndentTransformer());

// Remove all indentation
const stripAll = new TemplateTag(stripIndentTransformer('all'));

const code = stripInitial`
  function hello() {
    console.log("Hello");
  }
`;
// Result: "function hello() {\n  console.log(\"Hello\");\n}"

/**
 * Replaces patterns in all substitution values
 * @param replaceWhat - String or RegExp pattern to replace
 * @param replaceWith - Replacement string
 * @returns Transformer object with onSubstitution method
 */
function replaceSubstitutionTransformer(replaceWhat: string | RegExp, replaceWith: string): Transformer;

import { TemplateTag, replaceSubstitutionTransformer } from "common-tags";

// Sanitize user input
const sanitize = new TemplateTag(
  replaceSubstitutionTransformer('<', '&lt;'),
  replaceSubstitutionTransformer('>', '&gt;')
);

const userInput = '<script>alert("xss")</script>';
const output = sanitize`User said: ${userInput}`;
// Result: "User said: &lt;script&gt;alert(\"xss\")&lt;/script&gt;"

/**
 * Converts array substitutions to formatted string lists
 * @param opts - Configuration object for list formatting
 * @returns Transformer object with onSubstitution method
 */
function inlineArrayTransformer(opts?: ArrayOptions): Transformer;

interface ArrayOptions {
  separator?: string;    // Character separating items (default: '')
  conjunction?: string;  // Word before last item (default: '')
  serial?: boolean;     // Include separator before conjunction (default: false)
}

import { TemplateTag, inlineArrayTransformer, trimResultTransformer } from "common-tags";

// Create custom list formatter
const customList = new TemplateTag(
  inlineArrayTransformer({
    separator: ' | ',
    conjunction: 'or',
    serial: false
  }),
  trimResultTransformer()
);

const options = ['red', 'green', 'blue', 'yellow'];
const message = customList`Choose: ${options}`;
// Result: "Choose: red | green | blue or yellow"

// Oxford comma style
const oxfordList = new TemplateTag(
  inlineArrayTransformer({
    separator: ',',
    conjunction: 'and', 
    serial: true
  }),
  trimResultTransformer()
);

const items = ['apples', 'oranges', 'bananas'];
const grocery = oxfordList`Buy: ${items}`;
// Result: "Buy: apples, oranges, and bananas"

/**
 * Replaces patterns in template string parts
 * @param replaceWhat - String or RegExp pattern to replace
 * @param replaceWith - Replacement string
 * @returns Transformer object with onString method
 */
function replaceStringTransformer(replaceWhat: string | RegExp, replaceWith: string): Transformer;

/**
 * Splits string substitutions into arrays by delimiter
 * @param splitBy - Substring to split by
 * @returns Transformer object with onSubstitution method
 */
function splitStringTransformer(splitBy: string): Transformer;

/**
 * Removes non-printing values from substitutions
 * @returns Transformer object with onSubstitution method
 */
const removeNonPrintingValuesTransformer: Transformer;

interface Transformer {
  /**
   * Called for each template string part (content outside ${})
   * @param str - The current string part
   * @returns Transformed string
   */
  onString?(str: string): string;
  
  /**
   * Called for each substitution value (content inside ${})
   * @param substitution - The current substitution value
   * @param resultSoFar - The accumulated result up to this point
   * @returns Transformed substitution value
   */
  onSubstitution?(substitution: any, resultSoFar: string): any;
  
  /**
   * Called once on the final template result
   * @param endResult - The complete processed template
   * @returns Final transformed result
   */
  onEndResult?(endResult: string): string;
}

import { TemplateTag } from "common-tags";

// Parameterized transformer function
const wrapTransformer = (tagName) => ({
  onEndResult(result) {
    return `<${tagName}>${result}</${tagName}>`;
  }
});

// Use with different parameters
const h1 = new TemplateTag(wrapTransformer('h1'));
const p = new TemplateTag(wrapTransformer('p'));

const title = h1`Welcome`;        // "<h1>Welcome</h1>"
const content = p`Hello world`;   // "<p>Hello world</p>"

import { TemplateTag } from "common-tags";

const counterTransformer = {
  onSubstitution(substitution, resultSoFar) {
    this.count = (this.count || 0) + 1;
    return `${substitution} (#${this.count})`;
  },
  onEndResult(result) {
    return `${result}\nTotal substitutions: ${this.count || 0}`;
  }
};

const numbered = new TemplateTag(counterTransformer);

const result = numbered`Hello ${name}, you are ${age} years old`;
// Result: "Hello John (#1), you are 25 (#2) years old\nTotal substitutions: 2"

import { TemplateTag, trimResultTransformer } from "common-tags";

const customTag = new TemplateTag(trimResultTransformer());

// Tail processing with String.raw
const result = customTag(String.raw)`
  Some text with\nnewlines
`;
// Result: "Some text with\\nnewlines"