@typesugar/prettier-plugin weekly downloads statistics

@typesugar/prettier-plugin

Prettier plugin for typesugar custom syntax (|>, ::, F<_>).

Installation

npm install --save-dev @typesugar/prettier-plugin

Quick Start

Add the plugin to your Prettier configuration:

{
  "plugins": ["@typesugar/prettier-plugin"]
}

That's it — Prettier will now handle typesugar files without crashing on custom syntax.

Two Layers of Formatting

Layer 1: Plugin (Don't Crash)

The Prettier plugin preprocesses custom syntax before Prettier parses it. This prevents parse errors on |>, ::, and F<_> syntax. The formatted output is valid TypeScript but contains preprocessor artifacts (__binop__, Kind<F, A>).

Use this when you just need Prettier to work — e.g., in CI format checks or editor integration.

{
  "plugins": ["@typesugar/prettier-plugin"]
}

Layer 2: Full Round-Trip Format (Preserve Custom Syntax)

The format() function does a complete round-trip: custom syntax is preprocessed, Prettier formats the valid TypeScript, then custom syntax is restored.

import { format } from "@typesugar/prettier-plugin";

const source = `const x = data |> filter(pred) |> map(fn);`;
const formatted = await format(source, { filepath: "example.ts" });
// formatted: `const x = data |> filter(pred) |> map(fn);` (properly formatted)

The pipeline:

1. preFormat — Converts |> to __binop__(), F<_> to Kind<F, A>, etc.
2. prettier.format — Formats the valid TypeScript
3. postFormat — Restores __binop__() back to |>, Kind<F, A> back to F<A>, etc.

CLI

A standalone formatter CLI is included:

# Format files in place
typesugar-fmt src/**/*.ts

# Check formatting (CI mode — exits 1 if any file needs formatting)
typesugar-fmt --check src/**/*.ts

CLI Options

Option	Description
--write	Write formatted output to files (default)
--check	Check if files are formatted
--help	Show help message

Supported extensions: .ts, .tsx, .mts, .cts

Plugin Options

The plugin adds one custom option to Prettier:

Option	Type	Default	Description
typesugarSkip	boolean	false	Skip typesugar preprocessing

{
  "plugins": ["@typesugar/prettier-plugin"],
  "typesugarSkip": false
}

Programmatic API

format(source, options?)

Full round-trip formatting with custom syntax preservation.

import { format } from "@typesugar/prettier-plugin";

const formatted = await format(source, {
  filepath: "example.ts",
  prettierOptions: { printWidth: 100 },
});

check(source, options?)

Check if a file would change when formatted. Returns true if formatting is needed.

import { check } from "@typesugar/prettier-plugin";

const needsFormat = await check(source, { filepath: "example.ts" });

preFormat(source, options?)

Convert custom syntax to valid TypeScript (step 1 only). Returns the processed code and metadata needed by postFormat.

import { preFormat } from "@typesugar/prettier-plugin";

const { code, changed, metadata } = preFormat(source, { fileName: "example.ts" });

postFormat(formatted, metadata)

Restore custom syntax from preprocessed TypeScript (step 3 only). Requires the metadata from preFormat.

import { postFormat } from "@typesugar/prettier-plugin";

const restored = postFormat(formattedCode, metadata);

getFormatMetadata(source, options?)

Get format metadata without actually formatting. Useful for debugging.

import { getFormatMetadata } from "@typesugar/prettier-plugin";

const metadata = getFormatMetadata(source, { filepath: "example.ts" });

Integration with Other Packages

• @typesugar/preprocessor — The plugin uses the preprocessor internally for syntax transformations
• @typesugar/eslint-plugin — The ESLint plugin handles linting; this plugin handles formatting
• @typesugar/vscode — The VS Code extension integrates both formatting and linting

How It Works

typesugar introduces syntax that isn't valid TypeScript (|>, ::, F<_>). Prettier's TypeScript parser chokes on these. This plugin intercepts parsing via a custom parser that preprocesses the source first.

The custom parser (typesugar-ts) extends Prettier's built-in TypeScript parser with a preprocess step that runs the typesugar preprocessor. Prettier sees valid TypeScript and formats it normally.

For the full round-trip format() function, a third step reverses the preprocessing using AST analysis to find __binop__() calls and Kind<F, A> type references, then replaces them with the original custom syntax.

API Quick Reference

Export	Type	Description
plugin	Plugin	Prettier plugin (default export)
format	Function	Full round-trip format
check	Function	Check if formatting needed
preFormat	Function	Custom syntax → valid TS
postFormat	Function	Valid TS → custom syntax
getFormatMetadata	Function	Inspect transformations without formatting
FormatOptions	Type	Options for format/check
PreFormatOptions	Type	Options for preFormat
FormatMetadata	Type	Metadata from preFormat
HKTParamInfo	Type	HKT parameter scope info

License

MIT