Installation

npm install --save @papitaconpure/booru-client

bun add @papitaconpure/booru-client

deno add npm:@papitaconpure/booru-client

Basic Usage

Gelbooru:

import { BooruClient, Gelbooru } from '@papitaconpure/booru-client';

//Instance a Booru adapter
const gelbooru = new Gelbooru();

//Create a Booru client with the adapter and our credentials
const client = new BooruClient(gelbooru, {
	apiKey: 'your Gelbooru API key',
	userId: 'your Gelbooru user ID',
});

//Return 5 random posts containing the tag "megumin" and a "General" content rating
const posts = await client.search('megumin rating:general sort:random', { limit: 5 });

//Log the id, tags, url, and extra Gelbooru metadata of every obtained post
for (const post of posts) {
	console.log({
		id: post.id,
		tags: post.tags,
		url: post.url,
		extra: post.extra,
	});
}

Danbooru:

import { BooruClient, Danbooru } from '@papitaconpure/booru-client';

//Instance a Booru adapter
const danbooru = new Danbooru();

//Create a Booru client with the adapter and our credentials
const client = new BooruClient(danbooru, {
	apiKey: 'your Danbooru API key',
	login: 'your Danbooru user ID',
});

//Return the last 3 posts containing the tag "touhou" and a "Sensitive" content rating
const posts = await client.search('touhou rating:sensitive', { limit: 3 });

//Log the id, tags and url of every obtained post
for (const post of posts) {
	console.log({
		id: post.id,
		tags: post.tags,
		url: post.url,
	});
}

For more advanced usage, please check out all of the examples.

Smart Tag Resolution (Batching + Deduplication)

This client automatically tries to optimize tag resolution under the hood using:

• Smart request batching
• In-flight request deduplication
• Multi-layer caching

This means that multiple requests for overlapping tags may automatically merge into a single tag store lookup or API call, whichever comes first.

//Fetches the last 4 posts containing the tag 'megumin' from a booru.
const posts = await client.search('megumin', { limit: 4 });

//Fetches tags "in parallel", batching tag resolution requests across posts
//and avoiding duplicated requests within a reasonable time window.
await Promise.all(
	posts.map(async (post) => {
		const tags = await client.fetchPostTags(post);

		//Log each Post's ID and tags after fetching.
		console.log(post.id);
		console.dir(post.tags);
	}),
);

//These 24 tag requests are automatically reduced to only 1~8 API calls
//With default BooruClient settings, usually only 1 API call is required!
await Promise.all([
	client.fetchTagsByNames({ names: ['hakurei_reimu'] }),
	client.fetchTagsByNames({ names: ['hakurei_reimu', 'kirisame_marisa'] }),
	client.fetchTagsByNames({ names: ['hakurei_reimu', 'kirisame_marisa', 'alice_margatroid'] }),
	client.fetchTagsByNames({ names: ['kirisame_marisa', 'alice_margatroid', 'ibuki_suika'] }),
	client.fetchTagsByNames({ names: ['alice_margatroid', 'ibuki_suika', 'houraisan_kaguya'] }),
	client.fetchTagsByNames({ names: ['ibuki_suika', 'houraisan_kaguya', 'shameimaru_aya'] }),
	client.fetchTagsByNames({ names: ['houraisan_kaguya', 'shameimaru_aya', 'kochiya_sanae'] }),
	client.fetchTagsByNames({ names: ['shameimaru_aya', 'kochiya_sanae', 'hinanawi_tenshi'] }),
	client.fetchTagsByNames({ names: ['kochiya_sanae', 'hinanawi_tenshi'] }),
	client.fetchTagsByNames({ names: ['hinanawi_tenshi'] }),
]);

Keep in mind, Post requests are currently executed independently without caching, batching, or request deduplication. These optimizations are planned for future releases however.