Skip to content

Formatter ​

tyrus fmt formats .tyr source files from the project root. The formatter reads tyrus-fmt.json when it exists; every key is optional and omitted keys use the built-in default.

Commands ​

shell
tyrus fmt
tyrus fmt --check
tyrus fmt --stdout src/main.tyr
tyrus fmt --init
tyrus fmt --default

tyrus fmt rewrites project files in place. --check verifies formatting without writing files and is the CI-friendly mode. --stdout prints formatted output for explicit paths. --init creates or updates tyrus-fmt.json by adding missing options while preserving existing values. --default resets tyrus-fmt.json to the full default configuration.

Example Configuration ​

json
{
  "array_expand": "simple",
  "blank_lines": "collapse",
  "blank_lines_around_blocks": true,
  "blank_lines_around_decorations": true,
  "brace_spacing": true,
  "brace_style": "same-line",
  "final_newline": true,
  "indent_style": "spaces",
  "indent_width": 4,
  "imports_sort": true,
  "line_width": 80,
  "object_expand": "simple",
  "pipeline_chain_layout": "line-by-line",
  "prefer_arrow_function": false,
  "quote_style": "double",
  "remove_unused_imports": true,
  "trailing_comma": "es5"
}

Options ​

OptionDefaultValuesPurpose
array_expand"simple""simple", "expand-all", "off"Controls when array literals expand to multiple lines.
blank_lines"collapse""collapse", "off"Controls blank lines between imports, declarations, statements, and control-flow blocks.
blank_lines_around_blockstruetrue, falseAdds blank lines before and after block statements and function declarations.
blank_lines_around_decorationstruetrue, falseAdds separation around decorated interface/type fields.
brace_spacingtruetrue, falsePrints object literals as { x: 1 } or {x: 1}.
brace_style"same-line""same-line", "next-line", "off"Controls opening braces for function bodies and control-flow blocks.
final_newlinetruetrue, falseEnsures the file ends with a trailing newline.
indent_style"spaces""spaces", "tab"Selects spaces or tabs for indentation.
indent_width4integer >= 0Number of spaces per indentation level when indent_style is "spaces".
imports_sorttruetrue, falseSorts imports by module path and keeps tyrus:* module imports first.
line_width90integer >= 0Expands arrays, objects, call arguments, and ternaries that exceed the configured width.
object_expand"simple""simple", "expand-all", "off"Controls when object literals expand to multiple lines.
pipeline_chain_layout"line-by-line""line-by-line", "inline", "off"Controls layout for chains that use more than one `
prefer_arrow_functionfalsetrue, falseForces every top-level function declaration to the arrow form (true), or leaves each one in whichever form it was written, mixing function and arrow freely (false).
quote_style"double""double", "single", "off"Selects preferred string literal quotes or preserves each literal's original quotes and escapes.
remove_unused_importstruetrue, falseRemoves unused import specifiers or entire unused import declarations.
trailing_commatruetrue, falseControls trailing commas in multi-line arrays and objects.

array_expand ​

Controls when array literals expand to multiple lines.

json
{ "array_expand": "simple" }
tyrus
const simple = ["a", "b", "c"];
const complex = [foo(1), bar(2)];

With "simple", the first array stays inline because all elements are literals, while the second expands because it contains function calls.

json
{ "array_expand": "expand-all" }
tyrus
const simple = [
    "a",
    "b",
    "c",
];

With "expand-all", every multi-element array expands regardless of complexity.

json
{ "array_expand": "off" }
tyrus
const values = [firstValue, secondValue];

With "off", arrays remain inline even when they exceed line_width.

blank_lines ​

Controls blank lines between imports, declarations, statements, and control-flow blocks.

json
{ "blank_lines": "collapse" }
tyrus
import { readFileSync } from "tyrus:fs";

import { add } from "./math";

function main(): void {
    const x = 1;

    if (x > 0) {
        print("positive");
    }

    const y = 2;
}

With "collapse", blank lines separate imports, declarations, and control-flow blocks.

json
{ "blank_lines": "off" }
tyrus
import { readFileSync } from "tyrus:fs";
import { add } from "./math";
function main(): void {
    const x = 1;
    if (x > 0) {
        print("positive");
    }
    const y = 2;
}

With "off", the formatter does not add blank lines, and repeated blank lines are collapsed.

blank_lines_around_blocks ​

Adds blank lines before and after block statements and function declarations.

json
{ "blank_lines_around_blocks": true }
tyrus
function main(): void {
    const x = 1;

    if (x > 0) {
        print("positive");
    }

    for (let i = 0; i < x; i++) {
        print(i);
    }
}

With true, blank lines surround block statements and function declarations.

json
{ "blank_lines_around_blocks": false }
tyrus
function main(): void {
    const x = 1;
    if (x > 0) {
        print("positive");
    }
    for (let i = 0; i < x; i++) {
        print(i);
    }
}

With false, blocks sit directly adjacent to surrounding statements.

blank_lines_around_decorations ​

blank_lines_around_decorations keeps validator-heavy interfaces readable.

tyrus
interface ProductFilter {
    @notEmpty()
    query: string;

    @min(5)
    pageSize: i32;
}

brace_spacing ​

Controls whether a space is printed between curly braces and their content.

json
{ "brace_spacing": true }
tyrus
const config = { host: "localhost", port: 8080 };

With true, a space separates the braces from their content: { host: "localhost" }.

json
{ "brace_spacing": false }
tyrus
const config = {host: "localhost", port: 8080};

With false, no space is printed: {host: "localhost"}.

brace_style ​

Controls placement of the opening brace for function bodies and control-flow blocks.

json
{ "brace_style": "same-line" }
tyrus
if (cond) {
    foo();
} else {
    bar();
}

With "same-line", the opening brace stays on the header line.

json
{ "brace_style": "next-line" }
tyrus
if (cond)
{
    foo();
}
else
{
    bar();
}

With "next-line", the opening brace drops to its own line, and else starts a new line too.

json
{ "brace_style": "off" }

With "off", each code block and continuation keyword keeps its original same-line or next-line layout.

final_newline ​

Controls whether a trailing newline is added at the end of the file.

json
{ "final_newline": true }

The formatter ensures every file ends with a trailing newline character.

json
{ "final_newline": false }

The formatter omits the trailing newline at the end of the file.

indent_style ​

Controls indentation style (spaces or tabs).

json
{ "indent_style": "spaces", "indent_width": 4 }
tyrus
function main(): void {
    const x = 1;
}
json
{ "indent_style": "tab" }
tyrus
function main(): void {
	const x = 1;
}

With "tab", a single tab character is used per indentation level.

indent_width ​

Controls the number of spaces per indentation level.

json
{ "indent_width": 2 }
tyrus
function main(): void {
  const x = 1;
  if (x > 0) {
    print("positive");
  }
}
json
{ "indent_width": 4 }
tyrus
function main(): void {
    const x = 1;
    if (x > 0) {
        print("positive");
    }
}

The number of spaces per level changes from 2 to 4.

imports_sort ​

Controls whether import declarations are sorted alphabetically and grouped by source type.

json
{ "imports_sort": true }
tyrus
import { readFileSync } from "tyrus:fs";

import { add } from "./math";
import { formatDate } from "./utils";

With true, tyrus:* imports come first, followed by code imports sorted alphabetically.

json
{ "imports_sort": false }
tyrus
import { add } from "./math";
import { readFileSync } from "tyrus:fs";
import { formatDate } from "./utils";

With false, the original import order from the source file is preserved.

line_width ​

Maximum line length. Arrays, objects, call arguments, and ternaries that exceed this limit expand to multi-line.

json
{ "line_width": 80 }
tyrus
const user = { name: "Alice", age: 30, email: "[email protected]" };

If the line exceeds 80 characters, the formatter expands it:

tyrus
const user = {
    name: "Alice",
    age: 30,
    email: "[email protected]",
};

The same expansion applies to arrays, function-call arguments, and ternary expressions.

object_expand ​

Controls when object literals expand to multiple lines.

json
{ "object_expand": "simple" }
tyrus
const simple = { x: 1, y: 2 };
const complex = { x: foo(1), y: bar(2) };

With "simple", the first object stays inline because values are literals, while the second expands because values are function calls.

json
{ "object_expand": "expand-all" }
tyrus
const simple = {
    x: 1,
    y: 2,
};

With "expand-all", every multi-field object expands regardless of value complexity.

json
{ "object_expand": "off" }
tyrus
const options = { first: firstValue, second: secondValue };

With "off", objects remain inline even when they exceed line_width.

prefer_arrow_function ​

Forces every top-level function declaration to the arrow form or preserves the original form.

json
{ "prefer_arrow_function": false }
tyrus
function main(): void {
    hello();
}

const hello = (): void => {
    print("hello");
};

With false, the formatter preserves each declaration in its original form, so function and arrow styles can coexist.

json
{ "prefer_arrow_function": true }
tyrus
const main = (): void => {
    hello();
};

const hello = (): void => {
    print("hello");
};

With true, every top-level function declaration is forced to the arrow form.

quote_style ​

Selects preferred string literal quotes. With "off", the formatter preserves the original quotes and escapes of every string literal.

json
{ "quote_style": "double" }
tyrus
const name = "Alice";
json
{ "quote_style": "single" }
tyrus
const name = 'Alice';
json
{ "quote_style": "off" }
tyrus
const name = 'Alice';
const greeting = "Hello";

remove_unused_imports ​

Removes unused import specifiers or entire unused import declarations.

json
{ "remove_unused_imports": true }
tyrus
import { add, subtract } from "./math";

const result = add(1, 2);

With true, the unused subtract specifier is removed.

json
{ "remove_unused_imports": false }
tyrus
import { add, subtract } from "./math";

const result = add(1, 2);

With false, unused imports are kept, only their layout is formatted.

trailing_comma ​

Controls trailing commas in multi-line arrays and objects.

json
{ "trailing_comma": true }
tyrus
const items = [
    "a",
    "b",
    "c",
];

const config = {
    host: "localhost",
    port: 8080,
};
json
{ "trailing_comma": false }
tyrus
const items = [
    "a",
    "b",
    "c"
];

const config = {
    host: "localhost",
    port: 8080
};

With true, trailing commas are added in multi-line arrays and objects. With false, no trailing commas are added.

Before and After ​

tyrus
import { readFileSync, type FsError } from "tyrus:fs";
const add = (left: i32, right: i32): i32 => left + right;
interface FormatResult { value:i32;source:Result<string,FsError>; }
const main = (): void => {
    const result: FormatResult = { value:add(1,2),source:readFileSync("README.md") };
};
tyrus
import { readFileSync, type FsError } from "tyrus:fs";

const add = (left: i32, right: i32): i32 => left + right;

interface FormatResult {
    value: i32;
    source: Result<string, FsError>;
}

const main = (): void => {
    const result: FormatResult = {
        value: add(1, 2),
        source: readFileSync("README.md"),
    };
};

Use --check in CI

tyrus fmt --check verifies formatting without writing files, which makes it the right command for pull requests and release pipelines.

pipeline_chain_layout ​

pipeline_chain_layout is useful for functional transformations because each step stays easy to scan.

tyrus
const result = value
    |> normalize
    |> validate(%)
    |> save(%);

Set it to "inline" when the project prefers compact short chains.

Set it to "off" to preserve whether each chain was written inline or across multiple lines.

tyrus
const result = value |> normalize |> validate(%) |> save(%);