@azlib/formatter

Universal, extensible text formatting library for TypeScript and JavaScript. Zero external dependencies, modular language formatters, syntax highlighters, and @azlib/schema-powered options validation.

Features

• Unified Dispatcher (format): Format any text by language name or alias (sql, json, xml, html, css, env, query-string, markdown).
• Extensible Registry: Register custom formatters and aliases via registerFormatter.
• SQL Formatter & Highlighter: Full SQL query formatter with clause-level indentation, dialect support, casing normalization, and HTML syntax highlighting.
• JSON Pretty-Printer: Relaxed parser handling comments (//, /* */), trailing commas, unquoted keys, recursive key sorting, compact inlining, and @azlib/schema runtime validation.
• XML & HTML Formatter: Clean tag indentation, HTML5 void element recognition, attribute wrapping (auto / always / never), attribute sorting, and <tag></tag> to <tag /> collapsing.
• CSS Formatter: Declaration block indentation, at-rule nesting (@media, @supports), alphabetical property sorting, and concise single-line rule mode.
• ENV / Properties Formatter: Equal sign (=) alignment across consecutive keys, section preservation, key sorting, and quote normalization.
• Query String / URL Formatter: Sort query parameters, multiline layout for clean inspection, and URI decoding/encoding.
• Markdown Formatter: Neatly padded and aligned Markdown tables, ATX heading normalization, and code block preservation.
• Text Utilities: indentString, dedent, alignColumns, and wrapText.

Installation

pnpm add @azlib/formatter

Quick Start

Unified format()

import { format } from "@azlib/formatter";

// SQL
const sql = format("select id, name from users where active = true;", "sql");

// JSON with key sorting
const json = format("{ b: 2, a: 1 }", { language: "json", sortKeys: true });

// HTML
const html = format("<div><h1>Hello</h1><p>World</p></div>", "html");

Dedicated Formatters

SQL Formatter & Syntax Highlighter

import { formatSql, highlightSql } from "@azlib/formatter";

const query = `
  SELECT u.id, u.name, count(o.id) as order_count
  FROM users u
  LEFT JOIN orders o ON o.user_id = u.id
  WHERE u.status = 'active'
  GROUP BY u.id, u.name
  ORDER BY order_count DESC;
`;

const formatted = formatSql(query, {
  keywordCase: "upper",
  indent: 2,
});

const html = highlightSql(query, {
  theme: "dark",
  wrap: "pre",
});

JSON Formatter

import { formatJson } from "@azlib/formatter";
import { s } from "@azlib/schema";

const dirtyJson = `
  {
    // Profile configuration
    name: 'Alice',
    age: 30,
    roles: ['admin', 'developer',],
  }
`;

const clean = formatJson(dirtyJson, {
  sortKeys: true,
  inlineThreshold: 30,
  schema: s.object({
    name: s.string(),
    age: s.number(),
    roles: s.array(s.string()),
  }),
});

ENV Formatter

import { formatEnv } from "@azlib/formatter";

const env = `
PORT=3000
DATABASE_URL=postgresql://localhost:5432/db
DEBUG=true
`;

const aligned = formatEnv(env, { alignValues: true });
// PORT         = 3000
// DATABASE_URL = postgresql://localhost:5432/db
// DEBUG        = true

Markdown Formatter

import { formatMarkdown } from "@azlib/formatter";

const table = `
| Name | Age | Status |
| :--- | ---: | :---: |
| Alice | 30 | Active |
| Bob | 5 | Inactive |
`;

const formattedTable = formatMarkdown(table, { formatTables: true });

Options Validation

@azlib/formatter exports schemas built on @azlib/schema:

• sqlFormatOptionsSchema
• jsonFormatOptionsSchema
• xmlFormatOptionsSchema
• cssFormatOptionsSchema
• envFormatOptionsSchema
• queryStringFormatOptionsSchema
• markdownFormatOptionsSchema
• formatterOptionsSchema

License

MIT