@sandlada/symbol-align

Vertically align code symbols such as =, :, =>, //, # — via CLI or API.

---

Install

npm install -D @sandlada/symbol-align

Usage

CLI

Pipe code through the CLI or pass a file directly:

# Align = signs (default) — pipe mode
cat file.ts | npx symbol-align

# Align = signs — file mode
npx symbol-align --file input.ts

# Align : and = signs
npx symbol-align --file input.ts --symbols =,:

# Align => arrows
cat file.ts | npx symbol-align --symbols =>

Any symbol can be aligned — just list it with --symbols.

Use --file / -f for direct file input, or pipe via stdin for streaming use. Use --output / -o to write to a file instead of stdout.

API

import { align } from '@sandlada/symbol-align';

const result = align(
  [
    'const backgroundColor = tokens.color.surface;',
    'const textColor       = tokens.color.text.primary;',
    'const borderColor     = tokens.color.border.default;',
  ].join('\n'),
);

console.log(result.code);
// Already aligned — no changes needed
console.log(result.changes); // 0

Multi-symbol alignment:

const code = [
  'const x: Type = 1;',
  'const yy: AnotherType = 22;',
].join('\n');

const { code: aligned } = align(code, { symbols: [':', '='] });
// → const x : Type        = 1;
// → const yy: AnotherType = 22;

Options

AlignOptions

Option	Type	Default	Description
symbols	string[]	['=']	Symbols to align (e.g. ['=', ':', '=>', '//', '#'])

AlignResult

Field	Type	Description
code	string	The aligned code
changes	number	Number of lines modified

Rules

• Symbols inside strings (', ", `) are ignored
• Symbols inside comments (//, /* */) are ignored
• Lines that don't contain the symbol are left unchanged
• Multi-symbol alignment processes symbols in order of first appearance
• Only adds spaces — never removes existing spacing

Examples

Align = assignments

symbols: =

Before	After
const a = 1; const bb = 2; const ccc = 3;	const a = 1; const bb = 2; const ccc = 3;

Align // comments

symbols: //

Before	After
const a = 1; // short const bb = 22; // longer	const a = 1; // short const bb = 22; // longer

Align : type annotations

symbols: :

Before	After
const x: string; const yy: number;	const x : string; const yy: number;

CLI Reference

Usage: symbol-align [options] [< file]
       symbol-align [options] --file <path>

Vertically align symbols in code. Reads from stdin or a file, writes to stdout.

Options:
  -f, --file <path>    Read from file instead of stdin
  -o, --output <path>  Write to file instead of stdout
  -s, --symbols <list> Comma-separated symbols to align (default: "=")
  --help               Show this help

Examples:
  echo "a = 1\nbb = 2" | symbol-align
  cat file.ts | symbol-align --symbols =,:
  symbol-align --file input.ts
  symbol-align -f input.ts --symbols =,:
  symbol-align --file input.ts -o output.ts

Limitations

• Does not detect regex /.../ — symbols inside regex may be aligned
• Single-pass alignment per symbol group

License

MIT — see LICENSE.