wat4beauty

Why wat4beauty?

Writing WebAssembly Text Format by hand is powerful, but maintaining readable code structure can be a nightmare. The Lisp-like syntax often leads to deeply nested parentheses, inconsistent indentation, and scattered definitions.

wat4beauty solves this by treating your code as a structured document. It doesn't just indent lines; it intelligently aligns parameters, locals, imports, and globals into clean columns. It keeps your logic on the left and pushes exports to the right, transforming messy .wat files into professional, maintainable codebases.

Key Features

• 🚀 Zero Dependencies: A lightweight, focused tool that does one thing perfectly.
• 🧠 Scope-Aware Formatting: Intelligently handles indentation depth, respecting nested blocks and parenthesis balance.
• 📐 Vertical Alignment: Automatically aligns types and names for imports, globals, tables, and memories.
• ✨ Smart Header Formatting: Aligns param, result, and local definitions within functions using a reverse-sort algorithm to handle complex scopes.
• 👉 Right-Aligned Exports: Automatically moves inline (export ...) statements to the far right (default column: 70), keeping the function signature clean.
• 🛡️ Safe Parsing: Smartly ignores comments (;;) and string contents to prevent formatting errors.
• 💻 Dual Mode: Use it as a robust CLI tool in your terminal or as a JavaScript library in your build scripts.

Quick Start

1. Installation

Install globally to use the CLI anywhere, or locally for your project.

# Global installation
npm install -g wat4beauty

# Local installation
npm install wat4beauty

2. Usage Example (CLI)

Format a file and save the output:

wat4beauty input.wat -o output.wat

Format with custom indentation (2 spaces) and export alignment (column 80):

wat4beauty input.wat -a "  " -e 80 -o output.wat

3. Usage Example (Library)

import { formatWatSmart } from "wat4beauty";

const uglyWat = `(module (func $add (param i32 i32) (result i32) (export "add") i32.add))`;

// Format with tabs (default) and align exports to column 70
const beautifulWat = formatWatSmart(uglyWat, "\t", 70);

console.log(beautifulWat);

Transformation Example

Before:

(module
(import "env" "log" (func $log (param i32)))
(global $g (mut i32) (i32.const 0))
(func $main (export "main") (result i32)
(local $temp i32)
...
)
)

After wat4beauty:

(module
    (import "env" "log" (func $log (param i32)))

    (global $g      (mut i32) (i32.const 0))

    (func $main     (result i32)                          (export "main")
        (local $temp i32)
        ...
    )
)

CLI Reference

You can pass flags to customize the output.

| Flag | Full Name | Description | | :--- | :--- | :--- | | -o | --output | The output file path. If omitted, prints to stdout. | | -a | --align-indents-with | Character(s) used for indentation (e.g., " "). Default: \t (Tab). | | -e | --export-pad-start | The column number to align inline exports. Default: 70. | | -p | --print-only | Force printing to console even if output file is specified (dry run). | | -h | --help | Show the help screen. |

API Reference

formatWatSmart(content, indentChar, exportPad)

The main function exported by the library.

• content (String): The raw .wat file content string.
• indentChar (String): The character string to use for indentation levels. Default: "\t".
• exportPad (Number): The minimum column index to start alignment of inline exports. Default: 70.
• Returns (String): The formatted and beautified WebAssembly text.

License

This project is licensed under the MIT License - see the LICENSE file for details.