@mdxld/types

Shared TypeScript type definitions for all MDXLD format packages. Provides a consistent interface pattern across JSON, YAML, CSV, XLSX, PDF, Markdown, and HTML converters.

Installation

pnpm add @mdxld/types

Usage

import type {
  Format,
  BiDirectionalFormat,
  TextFormat,
  BinaryFormat,
  ReadOnlyFormat,
  TabularFormat,
  DocumentFormat
} from '@mdxld/types'

Core Interfaces

Format

Base interface that all format converters implement:

interface Format<T = unknown, ParseOptions = unknown, StringifyOptions = unknown> {
  parse(input: string | ArrayBuffer, options?: ParseOptions): T
  stringify?(data: T, options?: StringifyOptions): string | ArrayBuffer
  fetch(url: string, options?: FormatFetchOptions & ParseOptions): Promise<T>

  readonly name: string
  readonly mimeTypes: readonly string[]
  readonly extensions: readonly string[]
}

BiDirectionalFormat

Formats that support both parse and stringify (JSON, YAML, CSV, XLSX):

interface BiDirectionalFormat<T, ParseOptions, StringifyOptions>
  extends Format<T, ParseOptions, StringifyOptions> {
  stringify(data: T, options?: StringifyOptions): string | ArrayBuffer
}

TextFormat

Text-based formats where input and output are always strings (JSON, YAML, CSV, Markdown):

interface TextFormat<T, ParseOptions, StringifyOptions>
  extends BiDirectionalFormat<T, ParseOptions, StringifyOptions, string, string> {
  stringify(data: T, options?: StringifyOptions): string
}

BinaryFormat

Binary formats where output is ArrayBuffer (XLSX):

interface BinaryFormat<T, ParseOptions, StringifyOptions>
  extends BiDirectionalFormat<T, ParseOptions, StringifyOptions, string | ArrayBuffer, ArrayBuffer> {
  stringify(data: T, options?: StringifyOptions): ArrayBuffer
}

ReadOnlyFormat

Formats that only support reading (PDF):

interface ReadOnlyFormat<T, ParseOptions>
  extends Omit<Format<T, ParseOptions, never>, 'stringify'> {
  readonly readonly: true
}

TabularFormat

Formats for tabular text data (CSV, TSV):

interface TabularFormat<T = Record<string, unknown>[], ParseOptions, StringifyOptions>
  extends TextFormat<T, ParseOptions, StringifyOptions> {
  getHeaders(data: T): string[]
}

TabularBinaryFormat

Formats for tabular binary data (XLSX):

interface TabularBinaryFormat<T = Record<string, unknown>[], ParseOptions, StringifyOptions>
  extends BinaryFormat<T, ParseOptions, StringifyOptions> {
  getHeaders(data: T): string[]
}

Type Guards

import { isBiDirectional, isReadOnly, isTabular } from '@mdxld/types'

if (isBiDirectional(format)) {
  // format.stringify is available
}

if (isReadOnly(format)) {
  // format.readonly === true, no stringify
}

if (isTabular(format)) {
  // format.getHeaders is available
}

Example Implementation

import type { TextFormat } from '@mdxld/types'

const MyFormat: TextFormat<MyData, MyParseOptions, MyStringifyOptions> = {
  name: 'myformat',
  mimeTypes: ['application/x-myformat'],
  extensions: ['myf'],

  parse(input: string, options?: MyParseOptions): MyData {
    // Implementation
  },

  stringify(data: MyData, options?: MyStringifyOptions): string {
    // Implementation
  },

  async fetch(url: string, options?: FormatFetchOptions & MyParseOptions): Promise<MyData> {
    const response = await fetch(url)
    const text = await response.text()
    return this.parse(text, options)
  }
}

Packages Using These Types

• @mdxld/json - JSON and JSON-LD
• @mdxld/yaml - YAML and YAML-LD
• @mdxld/csv - CSV and TSV
• @mdxld/xlsx - Excel spreadsheets
• @mdxld/pdf - PDF documents
• @mdxld/markdown - Markdown
• @mdxld/html - HTML
• @mdxld/formats - Unified access to all formats