@alloc/formatly v0.1.2

!NOTE This is a fork of formatly with no dependencies. It also searches parent directories for formatter-specific config files, rather than only the current directory.

Usage

formatly can automatically detect and format with:

• Biome
• deno fmt
• dprint
• Prettier

See Formatter Detection for details on how they are detected.

CLI

npx formatly <files>

formatly takes in any number of glob patterns. It will then:

1. Detect which supported formatter is configured in the repository
2. Pass those glob patterns directly to the formatter

For example, to match all directories and folders in the current directory:

npx formatly *

To match only .ts files in src/:

npx formatly "src/**/*.ts"

Node.js API

npm i formatly

The formatly package exports the functions used by the formatly CLI.

formatly

Runs formatting on any number of glob pattern strings.

import { formatly } from "@alloc/formatly";

await formatly(["*"]);

Parameters:

1. patterns: string[] (required): any number of glob patterns
2. options: FormatlyOptions (optional):
   • cwd: string (optional): working directory, if not "."

Resolves with a FormatlyReport, which is either:

• FormatlyReportError if a formatter could not be determined, which an object containing:
  • ran: false
• FormatlyReportResult if a formatter could be determined, which is an object containing:
  • formatter: Formatter: as resolved by resolveFormatter
  • ran: true
  • result: Result, the Result from running the formatter with execa

For example, to run formatting on TypeScript source files in a child directory and check the result:

import { formatly } from "@alloc/formatly";

const report = await formatly(["src/**/*.ts"], { cwd: "path/to/project" });

if (!report.ran) {
	console.error("Could not determine formatter.");
	return;
}

const { formatter, result } = report;

if (result.code) {
	console.error(`Error running ${formatter.runner}:`, result.stderr);
} else {
	console.log(`Formatted with ${formatter.name}! 🧼`);
}

resolveFormatter

Detects which of the supported formatters to use for a directory. Parent directories are searched if necessary. The search ends when a directory with .git folder is encountered.

import { resolveFormatter } from "@alloc/formatly";

const formatter = await resolveFormatter();

// {
//   name: "Prettier",
//   runner: "npx prettier --write",
//   testers: { ... }
// }
console.log(formatter);

Parameters:

1. cwd: string (optional): working directory, if not "."

Resolves with either:

• undefined if a formatter could not be detected
• Formatter if one can be found, which is an object containing:
  • name: string: English name of the formatter
  • runner: string: the shell command used to run the formatter
  • testers: object: strings and regular expressions used to test for the formatter

Formatter Detection

Formatters are detected based on the first match from, in order:

1. Existence of the formatter's default supported config file name
2. The formatter's name in a package.json fmt or format script
3. Well-known root-level package.json key

Supported Formatters

Want support for a formatter not mentioned here? Great! Please file a feature request GitHub issue. 🙏

Why?

Formatly is a tool for any developer tool that creates files for users. If your tool creates, say, a config file that users are meant to check into their repository, you probably want that file to be formatted per the user's preference. But there are several popular formatters in use today: it's not enough to just call to prettier.format.

Formatly takes away the burden of

• Detecting which formatter -if any- a userland project is using
• Calling to that formatter's API(s) to format the file

Does Formatly replace Prettier, etc.?

No. Formatly is a detection + wrapping layer around formatters such as Prettier. Userland projects still need to configure a formatter themselves.

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 💖

Contributors

💝 This package was templated with create-typescript-app using the create engine.