octet-stream / dinky

JavaScript bindings for Philomena JSON API. Supports sites such as Derpibooru and Furbooru.

dinky.js

JavaScript bindings for Philomena JSON API. Supports sites such as Derpibooru and Furbooru.

Installation

You can install this package from npm:

npm install dinky.js

Or with yarn:

yarn add dinky.js

Or via pnpm:

pnpm add dinky.js

Usage

Dinky implements individual class for each API resourse to build a request. Each class is request builder and will return Promise when you commit the request.

1. The minimal example that will return an image by known ID:

import {Images} from "dinky.js"

const images = new Images()

// The following request will return the 1th uploaded image from Derpibooru.
// Equivalent to https://derpibooru.org/api/v1/json/images/0 request
await images.getById(0)

2. Search for images by their tags using the Search class:

import {Search} from "dinky.js"

const search = new Search()

// You can specify tags right in the .query() method
// The following example is equivalent of this requests:
// https://derpibooru.org/api/v1/json/search/images?q=artist:rainbow,safe&sf=random&per_page=1
await search.query(["artist:rainbow", "safe"]).random().limit(1)

3. Every dinky.js class constructor allows to set a custom base URL, allowing you to use it with any Philomena compatible APIs.

import {Search} from "dinky.js"

const search = new Search({url: "https://furbooru.org"})

await search.query(["safe", "loona"])

4. Dinky has shortcuts for both entites and search interfaces, so you can build request in similar to v1 manner:

import {images, search} from "dinky.js"

await images().getById(0) // Same as new Images().getById(0)
await search.reverse("https://derpicdn.net/img/2019/12/24/2228439/full.jpg") // Same as new SearchImages().reverse()
await search.images().query(["pinke pie", "safe"])

5. Every class keeps its state between request, which means you can re-use same object to perform multiple requests.

import {Search} from "dinky.js"

const search = new Search()

search
  .query(["scootaloo", "princess luna", "safe", "sleepless in ponyville"])
  .minScore(200)
  .random()
  .limit(1)

// Will search for random image with parameters from above
await search

// ...and once more
await search

7. You can navigate through search results with .page() method. Note that after each .page() call you have to send a new request to API:

import {Search} from "dinky.js"

const search = new Search()

serch.query(["twilight sparkle"]).minScore(200)

// Search class is thenable, so you don't have to call `.exec()`,`.then()` and `.catch()` methods to commit a request.
// By default, will API will return results from the first page
await search

// Results for 2nd page
await search.page(2)

8. You can set a filter to use for requests:

import {Search} from "dinky.js"

const search = new Search({filter: 37430})

search.query(["dinky", "derpy hooves"])

await search.exec()

// You can also set per-request filter from .exec() method
await search.exec({filter: 100073})

9. Search for "my:faves" images using a key taken from account page:

import {Search} from "dinky.js"

const search = new Search({key: "<your key here>"})

// You can search for `my:faves` images with specific tags
await search.query(["trixie", "safe"]).faves()

API

Full documentation can be found in /docs directory.

Related

• Derpibooru API documentation can be found here: derpibooru.org/pages/api

Another API bindings:

• derpiboorust – Rust
• DerPyBooru – Python
• derpigo – Go