# Understanding the lossless Property in FormatHandler for Data Integrity

> Learn how the lossless property in FormatHandler ensures perfect data integrity during conversion. Prioritize quality preserving routes with this key feature.

- Repository: [p2r3/convert](https://github.com/p2r3/convert)
- Tags: internals
- Published: 2026-02-19

---

**The `lossless` property tells the conversion engine whether a format preserves data perfectly during transformation, influencing pathfinding algorithms to prioritize quality-preserving conversion routes.**

In the `p2r3/convert` repository, the `lossless` property serves as a critical flag for determining data fidelity during file format conversions. This boolean indicator, defined within the `FileFormat` interface in [`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts), enables the conversion graph algorithm to distinguish between formats that preserve information perfectly and those that degrade data.

## What Is the lossless Property?

The `lossless` property is a boolean flag defined on the `FileFormat` interface at lines 25-27 of [`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts), defaulting to `false` when not explicitly specified. When registering a format, developers can mark it as lossless through the `supported()` method or the fluent builder's `markLossless()` method to indicate that conversions to this format introduce no data degradation.

### Defining Lossless Formats in Source Code

Handlers register lossless formats using either the imperative `supported()` method (lines 64-72) or the declarative builder pattern (lines 90-94). Both approaches set this flag to `true`, signaling that the format supports perfect round-trip conversion without information loss.

## Algorithmic Impact on Conversion Pathfinding

The `lossless` property directly influences the conversion graph's pathfinding algorithm implemented in [`src/TraversionGraph.ts`](https://github.com/p2r3/convert/blob/main/src/TraversionGraph.ts). When calculating edge costs between formats, the system applies a `LOSSY_COST_MULTIPLIER` of `1.4` (defined at lines 26-27) whenever a conversion target lacks the lossless flag, effectively penalizing potentially degrading transformations.

### Cost Multiplier Implementation

At lines 238-239 of [`src/TraversionGraph.ts`](https://github.com/p2r3/convert/blob/main/src/TraversionGraph.ts), the algorithm checks `to.format.lossless` before applying the multiplier:

```typescript
const cost = to.format.lossless 
  ? baseCost 
  : baseCost * LOSSY_COST_MULTIPLIER; // 1.4x penalty for lossy formats

```

This mathematical preference ensures that when multiple conversion paths exist between source and target formats, the engine selects routes that minimize data degradation unless explicitly configured otherwise.

## Configuring the lossless Flag in Practice

Developers register formats as lossless using two primary approaches within [`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts). The builder pattern offers a readable fluent interface, while the `supported()` method provides concise registration for simple format definitions.

### Using the Fluent Builder

The builder pattern exposes a `markLossless()` method that chains with other configuration calls:

```typescript
import { FormatDefinition } from "./src/FormatHandler";

const txtFormat = new FormatDefinition(
  "Plain Text (UTF-8)", "UTF-8", "txt", "text/plain; charset=UTF-8"
).builder("utf8")
  .allowFrom(true)
  .allowTo(true)
  .markLossless()  // Explicitly marks as lossless
  .build();

```

### Using the supported() Method

Alternatively, the `supported()` helper accepts the lossless flag as its fourth boolean argument:

```typescript
const pngDef = new FormatDefinition(
  "Portable Network Graphics", "PNG", "png", "image/png"
);

// Parameters: format ID, allowFrom, allowTo, lossless
const pngFormat = pngDef.supported("png", true, true, true);

```

## Consequences of Misconfiguring lossless

Incorrectly setting the `lossless` property produces significant consequences for conversion quality and system reliability. A format mistakenly marked as lossless when it actually compresses or discards data causes the pathfinder to treat destructive conversions as zero-cost operations, potentially corrupting user files through "perfect" pathways that silently degrade content.

Conversely, marking truly lossless formats like PNG, UTF-8 text, or LZH archives as `lossless: false` forces the algorithm to apply the 1.4x cost penalty unnecessarily. This artificial inflation may cause the engine to select convoluted multi-step conversion chains through intermediate formats when direct conversion would preserve data perfectly.

## Summary

- The `lossless` property in [`src/FormatHandler.ts`](https://github.com/p2r3/convert/blob/main/src/FormatHandler.ts) defaults to `false` and indicates whether a format supports perfect data preservation during conversion.
- [`src/TraversionGraph.ts`](https://github.com/p2r3/convert/blob/main/src/TraversionGraph.ts) applies a `LOSSY_COST_MULTIPLIER` of `1.4` to non-lossless formats, making the pathfinding algorithm prefer data-preserving routes.
- Developers set this flag via `markLossless()` in the builder pattern or the fourth parameter of `supported()`.
- Misconfiguration risks include silent data corruption (when lossy formats claim lossless status) or suboptimal conversion paths (when lossless formats are undervalued).

## Frequently Asked Questions

### What happens if I accidentally mark a lossy format as lossless?

The conversion engine will treat JPEG, MP3, or other compressed formats as zero-cost nodes in the traversal graph. This causes the pathfinder to potentially route conversions through these formats even when intermediate steps discard data, resulting in accumulated quality loss that the system cannot detect or prevent.

### How does the lossless property affect conversion performance?

While the property itself introduces negligible computational overhead, it significantly impacts path calculation in [`src/TraversionGraph.ts`](https://github.com/p2r3/convert/blob/main/src/TraversionGraph.ts). The algorithm evaluates edge costs using the `LOSSY_COST_MULTIPLIER` constant during graph construction, leaving runtime conversion performance unaffected while ensuring higher-quality output selection.

### Can I adjust the cost penalty for lossy conversions?

The `LOSSY_COST_MULTIPLIER` is currently defined as a constant (`1.4`) at lines 26-27 of [`src/TraversionGraph.ts`](https://github.com/p2r3/convert/blob/main/src/TraversionGraph.ts). To modify the penalty weighting, you must edit this constant in the source code, as the repository does not expose runtime configuration for the cost multiplier through the public API.

### Which file formats should typically be marked as lossless?

Lossless formats include uncompressed or perfectly reversible encodings such as PNG images, FLAC audio, UTF-8 text files, gzip archives, and LZH compressed data. Formats employing perceptual compression like JPEG, MP3, or lossy WebP should never carry the `lossless: true` flag, as they intentionally discard data to achieve smaller file sizes.