@joyboy-parser/core

Core SDK and runtime for the JoyBoy parser ecosystem.

Installation

npm install @joyboy-parser/core @joyboy-parser/types

Features

• 🔌 Dynamic parser loading (static, dynamic, remote)
• 🔍 Type-safe interfaces
• 🌐 Cross-platform (Node.js, Browser, React Native)
• 🔄 Built-in retry and error handling
• 💾 Optional caching layer
• 📦 Tree-shakeable ESM bundles

Quick Start

import { JoyBoy } from '@joyboy-parser/core';

// Load a parser
await JoyBoy.loadSource('@joyboy-parser/source-mangadex');

// Get the loaded source
const mangadex = JoyBoy.getSource('mangadex');

// Search for manga
const results = await mangadex.search('One Piece');

API Reference

JoyBoy Runtime

JoyBoy.loadSource(source)

Load a source parser dynamically.

// From package name
await JoyBoy.loadSource('@joyboy-parser/source-mangadex');

// From instance
import MangaDexSource from '@joyboy-parser/source-mangadex';
await JoyBoy.loadSource(new MangaDexSource());

// From lazy loader
await JoyBoy.loadSource(() => import('@joyboy-parser/source-mangadex'));

JoyBoy.getSource(id)

Get a loaded source by ID.

const mangadex = JoyBoy.getSource('mangadex');

JoyBoy.listSources()

Get all loaded sources.

const sources = JoyBoy.listSources();

JoyBoy.searchAll(query, sourceIds?)

Search across multiple sources.

const results = await JoyBoy.searchAll('One Piece');
// Returns Map<string, Manga[]>

BaseSource

Abstract base class for creating parsers.

import { BaseSource } from '@joyboy-parser/core';
import type { Manga, Chapter, Page } from '@joyboy-parser/types';

export default class MySource extends BaseSource {
  id = 'mysource';
  name = 'My Source';
  version = '1.0.0';
  baseUrl = 'https://example.com';

  async getMangaDetails(id: string): Promise<Manga> {
    // Implementation
  }

  async getChapters(mangaId: string): Promise<Chapter[]> {
    // Implementation
  }

  async getChapterPages(chapterId: string): Promise<Page[]> {
    // Implementation
  }
}

Utilities

RequestManager

protected async request<T>(url: string, options?: RequestOptions): Promise<T>
protected async fetchHtml(url: string, options?: RequestOptions): Promise<string>

Error Handling

import { isSourceError, formatError } from '@joyboy-parser/core';

try {
  await source.search('query');
} catch (error) {
  if (isSourceError(error)) {
    console.error(formatError(error));
  }
}

Creating a Custom Parser

See Creating Custom Parsers for detailed guide.

License

MIT