Skip to main content
File format types define the metadata and capabilities of supported formats in the conversion system.

​
FileFormat Interface

Extends IFormatDefinition with conversion capabilities: 
export interface FileFormat extends IFormatDefinition {
  /** Whether conversion **from** this format is supported. */
  from: boolean;
  /** Whether conversion **to** this format is supported. */
  to: boolean;
  /** Format identifier for the handler's internal reference. */
  internal: string;
  /** (Optional) Whether the format is lossless in this context. Defaults to `false`. */
  lossless?: boolean;
}
​
from
boolean
required
Whether conversion from this format is supported.Set to true if this handler can read and convert files in this format.
​
to
boolean
required
Whether conversion to this format is supported.Set to true if this handler can produce output files in this format.
​
internal
string
required
Format identifier for the handler’s internal reference.Used to identify the format within the handler’s conversion logic. This can be different from the format field for disambiguation.
​
lossless
boolean
default:false
Whether the format is lossless in this context.This affects pathfinding cost calculations. Lossy conversions receive a cost multiplier of 1.4x.

​
IFormatDefinition Interface

Base interface containing format metadata: 
export interface IFormatDefinition {
  /** Format description (long name) for displaying to the user. */
  name: string;
  /** Short, "formal" name for displaying to the user, and for
   * differentiating between files of identical MIME types.
   * If your file is different from others of the same MIME type,
   * then this string should be used to differentiate it. */
  format: string;
  /** File extension. */
  extension: string;
  /** MIME type. */
  mime: string;
  /** Category for grouping formats. */
  category?: Array<string> | string;
}
​
name
string
required
Format description (long name) for displaying to the user.Example: "Minecraft Schematic", "MPEG-4 Audio"
​
format
string
required
Short, “formal” name for displaying to the user, and for differentiating between files of identical MIME types.If your file is different from others of the same MIME type, this string should be used to differentiate it.Example: "schematic", "mp4", "litematic"
​
extension
string
required
File extension without the leading dot.Example: "schematic", "mp4", "png"
​
mime
string
required
MIME type of the format.Example: "application/x-minecraft-schematic", "video/mp4", "image/png"
​
category
string | string[]
Category for grouping formats.Can be a single category or an array of categories. Used by the pathfinding algorithm to apply category change costs.Common categories: "image", "video", "audio", "text", "document", "data"

​
FormatDefinition Class

Utility class for creating FileFormat objects with a fluent builder API: 
export class FormatDefinition implements IFormatDefinition {
  public readonly name: string;
  public readonly format: string;
  public readonly extension: string;
  public readonly mime: string;
  public readonly category?: string[] | string;

  constructor(
    name: string,
    format: string,
    extension: string,
    mime: string,
    category?: string[] | string
  )
}

​
Methods

​
supported
(ref: string, from: boolean, to: boolean, lossless?: boolean, override?: Partial<IFormatDefinition>) => FileFormat
Returns a FileFormat object that uses this format definition and specified options.Example:
const pngFormat = new FormatDefinition(
  "Portable Network Graphics",
  "png",
  "png",
  "image/png",
  "image"
);

const fileFormat = pngFormat.supported("png", true, true, true);
​
builder
(ref: string) => FileFormat & Builder
Returns a builder to fluently create FileFormat.Example:
const pngFormat = new FormatDefinition(
  "Portable Network Graphics",
  "png",
  "png",
  "image/png",
  "image"
);

const fileFormat = pngFormat.builder("png")
  .allowFrom()
  .allowTo()
  .markLossless();

​
Usage Examples

​
Creating FileFormat Objects

const format: FileFormat = {
  name: "Minecraft Schematic",
  format: "schematic",
  extension: "schematic",
  mime: "application/x-minecraft-schematic",
  from: true,
  to: true,
  internal: "schematic",
  category: "data",
  lossless: true
};

​
Handler Implementation

class MyHandler implements FormatHandler {
  public name = "MyHandler";
  public supportedFormats?: FileFormat[];
  public ready = false;

  async init() {
    const pngDef = new FormatDefinition(
      "Portable Network Graphics",
      "png",
      "png",
      "image/png",
      "image"
    );
    
    const jpegDef = new FormatDefinition(
      "JPEG Image",
      "jpeg",
      "jpg",
      "image/jpeg",
      "image"
    );

    this.supportedFormats = [
      pngDef.builder("png").allowFrom().allowTo().markLossless(),
      jpegDef.builder("jpeg").allowFrom().allowTo()
    ];
    
    this.ready = true;
  }

  async doConvert(
    inputFiles: FileData[],
    inputFormat: FileFormat,
    outputFormat: FileFormat
  ): Promise<FileData[]> {
    // Conversion logic using inputFormat.internal and outputFormat.internal
    return [];
  }
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us