7.api-reference.md

API Reference

Complete API documentation for Docen.

Core API

Convert Function

Main conversion function:

async function convert(
  input: string | Buffer,
  output: string,
  options?: ConversionOptions,
): Promise<void>;

Parameters

• input: Source file path or buffer
• output: Destination file path
• options: Conversion options

Options Interface

interface ConversionOptions {
  // Format options
  sourceFormat?: string;
  targetFormat?: string;

  // Processing options
  quality?: "low" | "medium" | "high";
  preserveMetadata?: boolean;

  // Resource limits
  timeout?: number;
  maxMemory?: number;

  // Processor specific
  [key: string]: any;
}

Registry API

Manage document processors:

class Registry {
  // Register new processor
  register(processor: Processor): void;

  // Get processor for format
  getProcessor(format: string): Processor;

  // List registered processors
  listProcessors(): Processor[];
}

Document Model

Core document representation:

interface Document {
  // Content structure
  content: DocumentContent;

  // Document metadata
  metadata: Metadata;

  // Embedded resources
  assets: Asset[];
}

interface DocumentContent {
  type: ContentType;
  value: any;
  children?: DocumentContent[];
}

interface Metadata {
  title?: string;
  author?: string;
  created?: Date;
  modified?: Date;
  [key: string]: any;
}

interface Asset {
  id: string;
  type: AssetType;
  data: Buffer;
}

Processor API

Base Processor

Abstract base class for processors:

abstract class BaseProcessor implements Processor {
  abstract name: string;
  abstract supportedFormats: string[];

  abstract read(input: Buffer): Promise<Document>;
  abstract write(document: Document): Promise<Buffer>;

  validate(document: Document): boolean;
  cleanup(): Promise<void>;
}

Processor Interface

Required interface for all processors:

interface Processor {
  // Processor identity
  readonly name: string;
  readonly supportedFormats: string[];

  // Core operations
  read(input: Buffer): Promise<Document>;
  write(document: Document): Promise<Buffer>;

  // Optional operations
  validate?(document: Document): boolean;
  cleanup?(): Promise<void>;
}

Utility Functions

Format Detection

function detectFormat(input: string | Buffer): Promise<string>;

function isFormatSupported(format: string): boolean;

Error Handling

Custom error types:

class DocenError extends Error {
  code: string;
  details?: any;
}

class UnsupportedFormatError extends DocenError {
  constructor(format: string);
}

class ProcessingError extends DocenError {
  constructor(message: string, details?: any);
}

Stream Support

Stream-based processing:

function createConversionStream(options: StreamOptions): Transform;

interface StreamOptions extends ConversionOptions {
  highWaterMark?: number;
  encoding?: string;
}

Events

Event system for monitoring:

interface ConversionEvents {
  on(event: "start", listener: () => void): this;
  on(event: "progress", listener: (progress: number) => void): this;
  on(event: "complete", listener: () => void): this;
  on(event: "error", listener: (error: Error) => void): this;
}

Configuration

Global configuration:

interface Config {
  // Default options
  defaults: ConversionOptions;

  // System settings
  tempDir: string;
  maxMemory: number;
  timeout: number;

  // Logging
  logLevel: LogLevel;
  logger: Logger;
}

Next Steps

• Review CLI Usage
• Check Core Concepts
• Read Contributing Guide