Skip to main content
The FormatHandler interface establishes a common contract for converting between file formats. Format handlers are typically wrappers around existing conversion tools.

​
Interface Definition

export interface FormatHandler {
  name: string;
  supportedFormats?: FileFormat[];
  supportAnyInput?: boolean;
  ready: boolean;
  init: () => Promise<void>;
  doConvert: (
    inputFiles: FileData[],
    inputFormat: FileFormat,
    outputFormat: FileFormat,
    args?: string[]
  ) => Promise<FileData[]>;
}

​
Properties

​
name
string
required
Name of the tool being wrapped (e.g. “FFmpeg”, “ImageMagick”, “mcSchematic”).
​
supportedFormats
FileFormat[]
List of supported input/output file formats. Each format in this array defines conversion capabilities through the from and to properties.See FileFormat for the complete type definition.
​
supportAnyInput
boolean
default:false
Whether the handler supports input of any type. When true, conversion using this handler will only be performed if no other direct conversion is found.This is useful for universal handlers that can attempt conversions for any format.
​
ready
boolean
required
Whether the handler is ready for use. Should be set to true in the init() method.If true, the doConvert() method is expected to work properly.

​
Methods

​
init
() => Promise<void>
required
Initializes the handler if necessary. This method should:
  • Load any required resources or dependencies
  • Populate the supportedFormats array
  • Set ready to true when initialization is complete
Example:
async init() {
  this.supportedFormats = [
    {
      name: "Minecraft Schematic",
      format: "schematic",
      extension: "schematic",
      mime: "application/x-minecraft-schematic",
      from: true,
      to: true,
      internal: "schematic",
      category: "data",
      lossless: true
    }
  ];
  this.ready = true;
}
​
doConvert
(inputFiles: FileData[], inputFormat: FileFormat, outputFormat: FileFormat, args?: string[]) => Promise<FileData[]>
required
Performs the actual file conversion.

​
FileData Type

export interface FileData {
  /** File name with extension. */
  name: string;
  /**
   * File contents in bytes.
   *
   * **Please note:** Handlers are responsible for ensuring the lifetime
   * and consistency of this buffer. If you're not sure that your handler
   * won't modify it, wrap it in `new Uint8Array()`.
   */
  readonly bytes: Uint8Array;
}
​
name
string
required
File name with extension.
​
bytes
Uint8Array
required
File contents in bytes.
Handlers are responsible for ensuring the lifetime and consistency of this buffer. If you’re not sure that your handler won’t modify it, wrap it in new Uint8Array().

​
Usage Example

Here’s a complete example of a format handler implementation: 
import type { FileData, FileFormat, FormatHandler } from "src/FormatHandler";

class MyCustomHandler implements FormatHandler {
  public name: string = "MyCustom";
  public supportedFormats?: FileFormat[];
  public ready: boolean = false;

  async init() {
    this.supportedFormats = [
      {
        name: "Custom Format A",
        format: "custom-a",
        extension: "ca",
        mime: "application/x-custom-a",
        from: true,
        to: false,
        internal: "custom-a",
        lossless: true
      },
      {
        name: "Custom Format B",
        format: "custom-b",
        extension: "cb",
        mime: "application/x-custom-b",
        from: false,
        to: true,
        internal: "custom-b",
        lossless: false
      }
    ];
    this.ready = true;
  }

  async doConvert(
    inputFiles: FileData[],
    inputFormat: FileFormat,
    outputFormat: FileFormat,
    args?: string[]
  ): Promise<FileData[]> {
    const outputFiles: FileData[] = [];

    for (const file of inputFiles) {
      // Perform conversion logic here
      const convertedBytes = this.performConversion(file.bytes);
      
      outputFiles.push({
        name: file.name.split(".")[0] + "." + outputFormat.extension,
        bytes: convertedBytes
      });
    }

    return outputFiles;
  }

  private performConversion(input: Uint8Array): Uint8Array {
    // Your conversion logic
    return new Uint8Array(input);
  }
}

export default MyCustomHandler;

​
ConvertPathNode

Used internally for pathfinding and conversion routing: 
export class ConvertPathNode {
  public handler: FormatHandler;
  public format: FileFormat;
  
  constructor(handler: FormatHandler, format: FileFormat) {
    this.handler = handler;
    this.format = format;
  }
}
​
handler
FormatHandler
required
The format handler to use for this conversion step.
​
format
FileFormat
required
The file format at this conversion step.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us