Skip to content

Latest commit

 

History

History
190 lines (151 loc) · 8.61 KB

README.md

File metadata and controls

190 lines (151 loc) · 8.61 KB
Raw

Eiyuu Testing Maintainability

Contributing • Documentation • Report Issues

The problem

TL;DR use arbitrary query to consume imageboard API, each websites could using direct wildcards with asterisk symbols like ?tags=<SomeQuery>*. The whole booru api does not have wildcard endpoint, that mean You cannot using arbitrary query to interact with. This library bringing the wildcard usage on JS/TS environment.

The solution

A query completion Booru imageboards module that uses wildcard for It's query resolver.


💻 What browser looks like
🚀 This library also

The completion works like a Search, It's uses wildcard but Pure scraping, and does not hit the API just works like a plugins will immediately resolve the arbitrary query. It's can be used in any JS Third-party libraries.

Features

  • Support 11 different boorus (check base.ts)
  • Pure scraping, does not hit the API endpoint
  • Documented and tested
  • Easy to use, check your intelisense

Eiyuu vs. the Competition

Some tests result with the imageboards

Site Status Query resolver Additions
Danbooru Yes Stable
Gelbooru Yes Stable
Hypnohub Yes Stable
Konachan Yes Stable
Lolibooru Yes Partial
Rule34 Yes Captcha Enabled
Realbooru Yes Stable
Safebooru Yes Stable
Tbib Yes Stable
Xbooru Yes Partial
Yandere Yes Stable

Getting Started

npm install eiyuu / yarn add eiyuu

Prerequisites

NOTE: NodeJS 14.x or higher

Quick Example

Use the arbitrary query for jeanne_d'arc_(fate)

import { Eiyuu } from "eiyuu";

const search = new Eiyuu();
search.danbooru("janne").then(res => {
    console.log(res); // Get the res[0] for the best match
});

commonjs: const { Eiyuu } = require('eiyuu');

You can passing optional useragent and follow redirects options.
constructor(useragent?: string, followRedirects?: boolean)

const search = new Eiyuu('eiyuu/version (eiyuu.js.org);', false);

Combine Eiyuu with another libraries

Example combine eiyuu with JS Booru package @AtoraSuunva/booru

const Booru = require('booru');
const { Eiyuu } = require('eiyuu');
const resolve = new Eiyuu();

async function Danbooru() {
    const query = await resolve.danbooru("jeanne"); // arbitrary request
    const dan = Booru.forSite('danbooru');
    dan.search(query[0], { limit: 10 }).then(posts => {
        console.log(posts);
    })
}

Danbooru();

Combine Eiyuu with the Rest

Example use this module with direct request to the api

const axios = require("axios");
const { Eiyuu } = require('eiyuu');
const resolve = new Eiyuu();

async function Danbooru() {
    const query = await resolve.danbooru("jeanne"); // arbitrary request
    const res = await axios.get(`https://danbooru.donmai.us/posts.json?limit=10&tags=${query[0]}`);
    console.log(res.data);
}

Danbooru();

Use Eiyuu as error handler

Instead hanging when no results are found, You can tells the proper queries with parseString()

const axios = require("axios"); // or any http client
const { Eiyuu, parseString } = require('eiyuu'); // import the wildcard
const resolve = new Eiyuu(); // default constructor
const q = "jeanne"; // assuming this is the query

async function Danbooru() {
    const res = await axios.get(`https://danbooru.donmai.us/posts.json?limit=10&tags=${q}`);

    // throw when error and tells the proper queries
    if (!res.data || res.data.length === 0) return resolve.danbooru(q).then(r => {
        console.log("No results found. Did you mean:", parseString(r));
    })

    // return when found
    console.log(res.data);

}

Danbooru();

The search returns

The query resolved returned as array

[
  "jeanne_d'arc_alter_(fate)",
  "jeanne_d'arc_(fate)",
  "jeanne_d'arc_alter_(avenger)_(fate)",
  "jeanne_d'arc_(ruler)_(fate)",
  "jeanne_d'arc_alter_(swimsuit_berserker)_(fate)",
  "jeanne_d'arc_alter_santa_lily_(fate)",
  "jeanne_d'arc_(swimsuit_archer)_(fate)"
] // and so on..

Testing

Check workflows and the whole build script on package.json

Documentation

The documentation can be found https://sinkaroid.github.io/eiyuu

Webpack

TBA

Limitations

Depends on your request, Some sites has CF or captcha enabled. Rule34 for example, If they marked your IP for being spam Eiyuu's scraper will not work. Make sure your stuff run on good environments.

Pronunciation

ja_JP • /ei-yū/ Eiyuu / eiyū / 英雄 — hero; heroine; leads to the spirit hero probably; (?)

Legal

This tool can be freely copied, modified, altered, distributed without any attribution whatsoever. However, if you feel like this tool deserves an attribution, mention it. It won't hurt anybody.

Licence: WTF.