{"id":18318253,"url":"https://github.com/sinkaroid/eiyuu","last_synced_at":"2025-04-05T21:32:37.365Z","repository":{"id":57749488,"uuid":"524800174","full_name":"sinkaroid/eiyuu","owner":"sinkaroid","description":"Search tags and query completion for booru imageboards","archived":false,"fork":false,"pushed_at":"2023-11-09T04:11:44.000Z","size":138,"stargazers_count":14,"open_issues_count":3,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-31T17:30:31.644Z","etag":null,"topics":["booru","imageboard","resolver"],"latest_commit_sha":null,"homepage":"https://eiyuu.js.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sinkaroid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null},"funding":{"github":"sinkaroid","custom":"https://paypal.me/sinkaroid"}},"created_at":"2022-08-14T23:12:12.000Z","updated_at":"2024-10-16T16:23:53.000Z","dependencies_parsed_at":"2022-08-27T00:11:17.343Z","dependency_job_id":null,"html_url":"https://github.com/sinkaroid/eiyuu","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinkaroid%2Feiyuu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinkaroid%2Feiyuu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinkaroid%2Feiyuu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sinkaroid%2Feiyuu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sinkaroid","download_url":"https://codeload.github.com/sinkaroid/eiyuu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223221269,"owners_count":17108514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["booru","imageboard","resolver"],"created_at":"2024-11-05T18:08:58.333Z","updated_at":"2024-11-05T18:08:59.285Z","avatar_url":"https://github.com/sinkaroid.png","language":"TypeScript","funding_links":["https://github.com/sponsors/sinkaroid","https://paypal.me/sinkaroid"],"categories":[],"sub_categories":[],"readme":"# Eiyuu [![Testing](https://github.com/sinkaroid/eiyuu/workflows/Typedata%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/mocha.yml) [![Maintainability](https://api.codeclimate.com/v1/badges/cc5309f61f1336368fd2/maintainability)](https://codeclimate.com/github/sinkaroid/eiyuu/maintainability)\n\n\u003ca href=\"https://github.com/sinkaroid/eiyuu/blob/master/CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e •\n\u003ca href=\"https://eiyuu.js.org/\"\u003eDocumentation\u003c/a\u003e •\n\u003ca href=\"https://github.com/sinkaroid/eiyuu/issues/new/choose\"\u003eReport Issues\u003c/a\u003e\n\n\u003ca href=\"https://www.npmjs.com/package/eiyuu\"\u003e\u003cimg align=\"right\" src=\"https://cdn.discordapp.com/attachments/952117487166705747/1008503920651407470/eiyuu_.png\" width=\"300\"\u003e\u003c/a\u003e\n\n- [Eiyuu](#)\n  - [The problem](#the-problem)\n  - [The solution](#the-solution)\n  - [Features](#features)\n    - [Eiyuu vs. the Competition](#eiyuu-vs-the-competition)\n  - [Installation](#getting-started)\n    - [Prerequisites](#prerequisites)\n  - [Documentation](#documentation)\n    - [Quick example](#quick-example)\n    - [Combine with another libs](#combine-eiyuu-with-another-libraries)\n    - [Combine with the Rest](#Combine-eiyuu-with-the-Rest)\n    - [Use as error handler](#Use-eiyuu-as-error-handler)\n    - [The search returns](#the-search-returns)\n    - [Running the tests](#testing)\n  - [Webpack](#webpack)\n  - [Limitations](#limitations)\n  - [Pronunciation](#Pronunciation)\n  - [Acknowledgements](./CLOSING_REMARKS.md)\n  - [Legal](#legal)\n\n\n## The problem\nTL;DR use arbitrary query to consume imageboard API, each websites could using direct wildcards with asterisk symbols like `?tags=\u003cSomeQuery\u003e*`. 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. \n\n## The solution\nA query completion Booru imageboards module that uses wildcard for It's query resolver.\n\u003ccenter\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.discordapp.com/attachments/952117487166705747/1008355693255983144/rounded_corners_6.png\" width=\"360px;\" alt=\"\"/\u003e\u003cbr /\u003e💻 What browser looks like\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"https://cdn.discordapp.com/attachments/952117487166705747/1008355692782030868/rounded_corners_7.png\" width=\"360px;\" alt=\"\"/\u003e\u003cbr /\u003e🚀 This library also\u003c/td\u003e\n\n\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/center\u003e\u003cbr\u003e\nThe 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.\n\n## Features\n\n- Support 11 different boorus (check [base.ts](./src/base.ts))\n- Pure scraping, does not hit the API endpoint\n- Documented and tested\n- Easy to use, check your intelisense\n\n## Eiyuu vs. the Competition\nSome tests result with the imageboards\n\n| Site            | Status                                                                                                                                                                            | Query resolver | Additions |\n| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | --- |\n| `Danbooru`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Danbooru%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/danbooru.yml) | `Yes` | Stable |\n| `Gelbooru`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Gelbooru%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/gelbooru.yml) | `Yes` | Stable |\n| `Hypnohub`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Hypnohub%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/hypnohub.yml) | `Yes` | Stable |\n| `Konachan`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Konachan%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/konachan.yml) | `Yes` | Stable |\n| `Lolibooru`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Lolibooru%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/lolibooru.yml) | `Yes` | Partial |\n| `Rule34`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Rule34%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/rule34.yml) | `Yes` | Captcha Enabled |\n| `Realbooru`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Realbooru%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/realbooru.yml) | `Yes` | Stable |\n| `Safebooru`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Safebooru%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/safebooru.yml) | `Yes` | Stable |\n| `Tbib`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Tbib%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/tbib.yml) | `Yes` | Stable |\n| `Xbooru`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Xbooru%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/xbooru.yml) | `Yes` | Partial |\n| `Yandere`       | [![](https://github.com/sinkaroid/eiyuu/workflows/Yandere%20test/badge.svg)](https://github.com/sinkaroid/eiyuu/actions/workflows/yandere.yml) | `Yes` | Stable |\n\n## Getting Started\n`npm install eiyuu` / `yarn add eiyuu`\n\n## Prerequisites\n\u003ctable\u003e\n\t\u003ctd\u003e\u003cb\u003eNOTE:\u003c/b\u003e NodeJS 14.x or higher\u003c/td\u003e\n\u003c/table\u003e\n\n## Quick Example\nUse the arbitrary query for `jeanne_d'arc_(fate)`\n```js\nimport { Eiyuu } from \"eiyuu\";\n\nconst search = new Eiyuu();\nsearch.danbooru(\"janne\").then(res =\u003e {\n    console.log(res); // Get the res[0] for the best match\n});\n```\ncommonjs: `const { Eiyuu } = require('eiyuu');`\n\nYou can passing optional useragent and follow redirects options.  \n`constructor(useragent?: string, followRedirects?: boolean)`\n```js\nconst search = new Eiyuu('eiyuu/version (eiyuu.js.org);', false);\n```\n\n## Combine Eiyuu with another libraries\nExample combine eiyuu with JS Booru package [@AtoraSuunva/booru](https://www.npmjs.com/package/booru)\n```js\nconst Booru = require('booru');\nconst { Eiyuu } = require('eiyuu');\nconst resolve = new Eiyuu();\n\nasync function Danbooru() {\n    const query = await resolve.danbooru(\"jeanne\"); // arbitrary request\n    const dan = Booru.forSite('danbooru');\n    dan.search(query[0], { limit: 10 }).then(posts =\u003e {\n        console.log(posts);\n    })\n}\n\nDanbooru();\n```\n\n## Combine Eiyuu with the Rest\nExample use this module with direct request to the api\n```js\nconst axios = require(\"axios\");\nconst { Eiyuu } = require('eiyuu');\nconst resolve = new Eiyuu();\n\nasync function Danbooru() {\n    const query = await resolve.danbooru(\"jeanne\"); // arbitrary request\n    const res = await axios.get(`https://danbooru.donmai.us/posts.json?limit=10\u0026tags=${query[0]}`);\n    console.log(res.data);\n}\n\nDanbooru();\n```\n\n## Use Eiyuu as error handler\nInstead hanging when no results are found, You can tells the proper queries with `parseString()`\n```js\nconst axios = require(\"axios\"); // or any http client\nconst { Eiyuu, parseString } = require('eiyuu'); // import the wildcard\nconst resolve = new Eiyuu(); // default constructor\nconst q = \"jeanne\"; // assuming this is the query\n\nasync function Danbooru() {\n    const res = await axios.get(`https://danbooru.donmai.us/posts.json?limit=10\u0026tags=${q}`);\n\n    // throw when error and tells the proper queries\n    if (!res.data || res.data.length === 0) return resolve.danbooru(q).then(r =\u003e {\n        console.log(\"No results found. Did you mean:\", parseString(r));\n    })\n\n    // return when found\n    console.log(res.data);\n\n}\n\nDanbooru();\n```\n\n## The search returns\nThe query resolved returned as array\n\n```js\n[\n  \"jeanne_d'arc_alter_(fate)\",\n  \"jeanne_d'arc_(fate)\",\n  \"jeanne_d'arc_alter_(avenger)_(fate)\",\n  \"jeanne_d'arc_(ruler)_(fate)\",\n  \"jeanne_d'arc_alter_(swimsuit_berserker)_(fate)\",\n  \"jeanne_d'arc_alter_santa_lily_(fate)\",\n  \"jeanne_d'arc_(swimsuit_archer)_(fate)\"\n] // and so on..\n```\n\n## Testing\nCheck workflows and the whole build script on [package.json](./package.json)\n\n## Documentation\nThe documentation can be found https://sinkaroid.github.io/eiyuu\n\n## Webpack\nTBA\n\n## Limitations\nDepends 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.\n\n\n## Pronunciation\n[`ja_JP`](https://www.localeplanet.com/java/ja-JP/index.html) • **/ei-yū/** Eiyuu / eiyū / 英雄 — hero; heroine; leads to the spirit hero probably; _(?)_\n\n\n## Legal\nThis tool can be freely copied, modified, altered, distributed without any attribution whatsoever. However, if you feel\nlike this tool deserves an attribution, mention it. It won't hurt anybody.\n\u003e Licence: WTF.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinkaroid%2Feiyuu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsinkaroid%2Feiyuu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsinkaroid%2Feiyuu/lists"}