CommonFormats

Overview

CommonFormats is a collection of pre-configured FormatDefinition objects that provide standard definitions for common file formats. These definitions reduce boilerplate when creating format handlers and ensure consistency across the codebase.

Import

import CommonFormats from "src/CommonFormats.ts";
import { Category } from "src/CommonFormats.ts";

FormatDefinition Class

Each entry in CommonFormats is an instance of the FormatDefinition class, which contains metadata about a file format.

Constructor

new FormatDefinition(
  name: string,
  format: string,
  extension: string,
  mime: string,
  category?: string[] | string
)

name

string

required

Long, descriptive name of the format (e.g., “Portable Network Graphics”)

format

string

required

Short, formal name used for identification (e.g., “png”)

extension

string

required

File extension without the dot (e.g., “png”)

mime

string

required

MIME type (e.g., “image/png”)

Builder Pattern

The FormatDefinition class provides a fluent builder API to create FileFormat objects for use in handlers.

CommonFormats.PNG.builder("png")
  .allowFrom()
  .allowTo()
  .markLossless()

Builder Methods

builder(ref)

function

Creates a builder with the specified internal reference identifier

allowFrom(value?)

function

Marks format as supporting conversion FROM this format. Defaults to true

allowTo(value?)

function

Marks format as supporting conversion TO this format. Defaults to true

markLossless(value?)

function

Marks the format as lossless in this context. Defaults to true

named(name)

function

Override the format name

withFormat(format)

function

Override the format identifier

withExt(ext)

function

Override the file extension

withMime(mimetype)

function

Override the MIME type

withCategory(category)

function

Replace the format category

override(values)

function

Apply multiple overrides at once using a partial object

Alternative: supported() Method

For simple cases, use the supported() method instead of the builder:

CommonFormats.PNG.supported(
  "png",    // internal reference
  true,     // allow from
  true,     // allow to
  true,     // lossless
  {}        // optional overrides
)

Available Formats

Image Formats

PNG

FormatDefinition

Portable Network Graphics

Format: png
Extension: .png
MIME: image/png
Category: IMAGE

JPEG

FormatDefinition

Joint Photographic Experts Group JFIF

Format: jpeg
Extension: .jpg
MIME: image/jpeg
Category: IMAGE

WEBP

FormatDefinition

WebP

Format: webp
Extension: .webp
MIME: image/webp
Category: IMAGE

TIFF

FormatDefinition

Tagged Image File Format

Format: tiff
Extension: .tiff
MIME: image/tiff
Category: IMAGE

BMP

FormatDefinition

Microsoft Windows bitmap image

Format: bmp
Extension: .bmp
MIME: image/bmp
Category: IMAGE

GIF

FormatDefinition

CompuServe Graphics Interchange Format (GIF)

Format: gif
Extension: .gif
MIME: image/gif
Categories: IMAGE, VIDEO

SVG

FormatDefinition

Scalable Vector Graphics

Format: svg
Extension: .svg
MIME: image/svg+xml
Categories: IMAGE, VECTOR, DOCUMENT

Data Formats

JSON

FormatDefinition

JavaScript Object Notation

Format: json
Extension: .json
MIME: application/json
Category: DATA

XML

FormatDefinition

Extensible Markup Language

Format: xml
Extension: .xml
MIME: application/xml
Category: DATA

YML

FormatDefinition

YAML Ain’t Markup Language

Format: yaml
Extension: .yml
MIME: application/yaml
Category: DATA

CSV

FormatDefinition

Comma Separated Values

Format: csv
Extension: .csv
MIME: text/csv
Category: DATA

Text & Document Formats

TEXT

FormatDefinition

Plain Text

Format: text
Extension: .txt
MIME: text/plain
Category: TEXT

HTML

FormatDefinition

Hypertext Markup Language

Format: html
Extension: .html
MIME: text/html
Categories: DOCUMENT, TEXT

FormatDefinition

Markdown Document

Format: markdown
Extension: .markdown
MIME: text/markdown
Categories: DOCUMENT, TEXT

PDF

FormatDefinition

Portable Document Format

Format: pdf
Extension: .pdf
MIME: application/pdf
Category: DOCUMENT

Code Formats

BATCH

FormatDefinition

Windows Batch file

Format: batch
Extension: .bat
MIME: text/windows-batch
Category: TEXT

PYTHON

FormatDefinition

Python Script

Format: py
Extension: .py
MIME: text/x-python
Category: CODE

FormatDefinition

Shell Script

Format: sh
Extension: .sh
MIME: application/x-sh
Category: TEXT

EXE

FormatDefinition

Windows Portable Executable

Format: exe
Extension: .exe
MIME: application/vnd.microsoft.portable-executable
Category: CODE

Audio Formats

MP3

FormatDefinition

MP3 Audio

Format: mp3
Extension: .mp3
MIME: audio/mpeg
Category: AUDIO

WAV

FormatDefinition

Waveform Audio File Format

Format: wav
Extension: .wav
MIME: audio/wav
Category: AUDIO

OGG

FormatDefinition

Ogg Audio

Format: ogg
Extension: .ogg
MIME: audio/ogg
Category: AUDIO

FLAC

FormatDefinition

Free Lossless Audio Codec

Format: flac
Extension: .flac
MIME: audio/flac
Category: AUDIO

Video Formats

MP4

FormatDefinition

MPEG-4 Part 14

Format: mp4
Extension: .mp4
MIME: video/mp4
Category: VIDEO

Archive Formats

ZIP

FormatDefinition

ZIP Archive

Format: zip
Extension: .zip
MIME: application/zip
Category: ARCHIVE

Microsoft Office Formats

DOCX

FormatDefinition

WordprocessingML Document

Format: docx
Extension: .docx
MIME: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Category: DOCUMENT

XLSX

FormatDefinition

SpreadsheetML Workbook

Format: xlsx
Extension: .xlsx
MIME: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Categories: SPREADSHEET, DOCUMENT

PPTX

FormatDefinition

PresentationML Presentation

Format: pptx
Extension: .pptx
MIME: application/vnd.openxmlformats-officedocument.presentationml.presentation
Categories: PRESENTATION, DOCUMENT

Font Formats

TTF

FormatDefinition

TrueType Font

Format: ttf
Extension: .ttf
MIME: font/ttf
Category: FONT

OTF

FormatDefinition

OpenType Font

Format: otf
Extension: .otf
MIME: font/otf
Category: FONT

WOFF

FormatDefinition

Web Open Font Format

Format: woff
Extension: .woff
MIME: font/woff
Category: FONT

WOFF2

FormatDefinition

Web Open Font Format 2.0

Format: woff2
Extension: .woff2
MIME: font/woff2
Category: FONT

Music Notation Formats

MUSICXML

FormatDefinition

MusicXML

Format: musicxml
Extension: .musicxml
MIME: application/vnd.recordare.musicxml+xml
Category: DOCUMENT

MXL

FormatDefinition

MusicXML Compressed

Format: mxl
Extension: .mxl
MIME: application/vnd.recordare.musicxml
Category: DOCUMENT

Usage Examples

Basic Usage with Builder Pattern

import CommonFormats from "src/CommonFormats.ts";
import type { FormatHandler, FileFormat } from "src/FormatHandler.ts";

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

  async init() {
    this.supportedFormats = [
      CommonFormats.PNG.builder("png")
        .allowFrom()
        .allowTo()
        .markLossless(),
      
      CommonFormats.JPEG.builder("jpeg")
        .allowFrom()
        .allowTo(),
      
      CommonFormats.WEBP.builder("webp")
        .allowTo()
    ];
    this.ready = true;
  }

  async doConvert(/* ... */) {
    // Implementation
  }
}

Font Handler Example

Real-world example from the font handler (src/handlers/font.ts:232):

import CommonFormats from 'src/CommonFormats.ts';

class fontHandler implements FormatHandler {
  async init() {
    this.supportedFormats = [
      CommonFormats.TTF.builder("ttf").allowFrom().markLossless(),
      CommonFormats.OTF.builder("otf").allowFrom().allowTo().markLossless(),
      CommonFormats.WOFF.builder("woff").allowFrom().markLossless(),
      CommonFormats.WOFF2.builder("woff2").allowFrom().allowTo().markLossless(),
      CommonFormats.SVG.builder("svg").allowFrom().allowTo()
    ];
    this.ready = true;
  }
}

Using supported() Method

import CommonFormats from "src/CommonFormats.ts";

const formats = [
  CommonFormats.PNG.supported("png", true, true, true),
  CommonFormats.JPEG.supported("jpeg", true, true, false)
];

Overriding Format Properties

import CommonFormats from "src/CommonFormats.ts";

// Using builder
const customFormat = CommonFormats.PNG.builder("custom-png")
  .allowFrom()
  .withMime("image/x-custom-png")
  .named("Custom PNG Format");

// Using supported() with overrides
const customFormat2 = CommonFormats.PNG.supported(
  "custom-png",
  true,
  false,
  true,
  { mime: "image/x-custom-png", name: "Custom PNG Format" }
);

Working with Categories

import CommonFormats, { Category } from "src/CommonFormats.ts";

// Check if a format belongs to a category
const isSvgImage = CommonFormats.SVG.category?.includes(Category.IMAGE);
const isSvgVector = CommonFormats.SVG.category?.includes(Category.VECTOR);

// Create custom format with multiple categories
const customFormat = CommonFormats.TEXT.builder("custom")
  .withCategory([Category.TEXT, Category.DATA]);

Core Concepts

Major Handlers

Utilities

Overview

Import

FormatDefinition Class

Constructor

Categories

Builder Pattern

Builder Methods

Alternative: supported() Method

Available Formats

Image Formats

Data Formats

Text & Document Formats

Code Formats

Audio Formats

Video Formats

Archive Formats

Microsoft Office Formats

Font Formats

Music Notation Formats

Usage Examples

Basic Usage with Builder Pattern

Font Handler Example

Using supported() Method

Overriding Format Properties

Working with Categories

See Also

Build docs developers (and LLMs) love

Core Concepts

Major Handlers

Utilities

​Overview

​Import

​FormatDefinition Class

​Constructor

​Categories

​Builder Pattern

​Builder Methods

​Alternative: supported() Method

​Available Formats

​Image Formats

​Data Formats

​Text & Document Formats

​Code Formats

​Audio Formats

​Video Formats

​Archive Formats

​Microsoft Office Formats

​Font Formats

​Music Notation Formats

​Usage Examples

​Basic Usage with Builder Pattern

​Font Handler Example

​Using supported() Method

​Overriding Format Properties

​Working with Categories

​See Also

Build docs developers (and LLMs) love

Overview

Import

FormatDefinition Class

Constructor

Categories

Builder Pattern

Builder Methods

Alternative: supported() Method

Available Formats

Image Formats

Data Formats

Text & Document Formats

Code Formats

Audio Formats

Video Formats

Archive Formats

Microsoft Office Formats

Font Formats

Music Notation Formats

Usage Examples

Basic Usage with Builder Pattern

Font Handler Example

Using supported() Method

Overriding Format Properties

Working with Categories

See Also