Skip to content
JavaScript bindings for Derpibooru API
JavaScript
Branch: master
Clone or download
Latest commit 7935b4c Sep 3, 2019

readme.md

dinky.js

JavaScript bindings for Derpibooru API

Build Status Code Coverage dependencies Status devDependencies Status

Installation

You can install this package from npm:

npm install dinky.js

Or with yarn:

yarn add dinky.js

Native ESM support

Dinky expose .mjs entry point, so you can use ESM natively in Node.js context using the --experimental-modules flag.

Usage

Dinky implements chainable API to build each request and all requests will return a Promise that resolves data taken from Derpibooru API.

  1. The minimal example that will return an image by known ID:
import dinky from "dinky.js"

// The following request will return the 1th uploaded image from Derpibooru.
// Equivalent to https://derpibooru.org/images/0.json request
dinky().images().id(0).then(console.log)
  1. Search for images by their tags using the .search() method:
import dinky from "dinky.js"

// You can specify tags right in the .search() method
// The following example is equivalent of these requests:
// https://derpibooru.org/search.json?q=artist:rainbow,safe&random_image=true
// ...and then this one:
// https://derpibooru.org/images/<received image id>.json
dinky().search(["artist:rainbow", "safe"]).random()
  .then(console.log)
  1. Since .search() method returns Search instance you can store it into variable for the further usage:
import dinky from "dinky.js"

(async function() {
  const search = dinky()
    .search(["scootaloo", "princess luna", "safe", "sleepless in ponyville"])
    .minScore(200)

  // Will search for random image with parameters from above
  await search.random()

  // ...and once more
  await search.random()
}()).catch(console.error)
  1. Walking through the search results:
import dinky from "dinky.js"

(async function() {
  const search = dinky().search(["twilight sparkle"]).minScore(200)

  // Search class is thenable, so you don't have to call `.exec()` method
  // in async functions context.
  // This request will return search results from the first page
  await search

  await search.page(2)

  // Same thing for Images class:
  const images = dinky().images()

  await images.page(2)
}()).catch(console.error)
  1. You can set a filter to use for requests:
import dinky from "dinky.js"

dinky({filter: 37430}).search(["dinky", "derpy hooves"]).then(console.log)

// You can also set per-request filter from .exec() method
dinky({filter: 37430}).search(["dinky", "derpy hooves"]).exec({filter: 100073})
  .then(console.log)
  1. Search for "my:faves" images using a key taken from account page:
import dinky from "dinky.js"

dinky({key: "<your key here>"}).search(["trixie", "safe"]).faves()
  .then(console.log)

API

class Dinky

constructor([options]) -> {Dinky}

Creates a new instance of the Derpibooru API client

  • {object} [options = {}] – client options
  • {string} [options.key = undefined] – your personal API key taken from your account settings
  • {number} [options.filter = undefined] – ID of a filter. The ID can be found on filters page

Instance methods

images() -> {Images}

Creates a request handler for /images.json

search([tags]) -> {Search}

Creates a request handler for /search.json. This method takes a list of tags

  • {string | string[]} [tags = []] – a tag or a list of tags and returns Search instance

class Images > Request

constructor() -> {Images}

Creates a request handler for /images.json

Instance methods

id(id) -> {Promise<object>}

Returns an image with given ID

class Search > Request

constructor() -> {Search}

Creates a request handler for /search.json.

Instance methods

tags([list]) -> {Search}

Appends a tag or a list of tags to the current search request. This method will not apply the q= parameter to the request for query when no tags has been set.

  • {string | string[]} [list = []] – a tag or a list of tags you want to append
faves() -> {Seatch}

Sets my:faves param to the search request.

Note that this method requires user's key.

watched() -> {Search}

Sets my:watched param to the search request.

Note that this method requires user's key.

upvotes() -> {Search}

Sets my:upvotes param to the search request.

Note that this method requires user's key.

downvotes() -> {Search}

Sets my:downvotes param to the search request.

Note that this method requires user's key.

uploads() -> {Search}

Sets my:uploads param to the search request.

Note that this method requires user's key.

favedBy(user) -> {Search}

Search for images faved by given user.

  • {string} user – name of the user on Derpibooru
uploadedBy(user) -> {Search}

Search for images uploaded by given user.

  • {string} user – name of the user on Derpibooru
limit(value) -> {Search}

Specifies how many images per page should API return

  • {number} value – an amount of images you want to take. The value must be in range of 1 and 50.
minScore(value) -> {Search}

Sets the minimal score of requested images.

  • {number} value – a value of minimal socre
maxScore(value) -> {Search}

Sets the maximal score of requested images

  • {number} value – a value of maximal socre
random() -> {Promise<object>}

If been called, the API will return random image

class Lists > Request

constructor() -> {Lists}

Creates a new Lists instance to give you ability to send requests to /lists.json and bunch of shortcuts to search for specific images categories on /search.json

last(period) -> {Lists}

Creates a request that gets 3 images lists (top scoring, all time top scoring, top commented) for given period.

  • {string} period – Sampling period, specified in weeks, days, or hours
topScoring() -> {Search}

Creates a Search request that gets top scoring images of last 3 days. The most rated images will be at the top of the list.

topScoringAllTime() -> {Search}

Creates a Search request that gets top scoring images of the all time. The most rated images will be at the top of the list.

topCommented() -> {Search}

Creates a Search request that gets top commented images of last 3 days. The most commented images will be at the top of the list.

class Request

constructor() -> {Request}

Creates a new request handler.

Instance methods

Sets images ordering to descending

page(offset) -> {Request}

Sets the page offset

  • {number} [offset = 1] – The page offset.
exec([options]) -> {Promise<object>}

Executes current request.

  • {object} options – a set of options to use in request. They are have priority over the constructor options.
  • {string} [options.key = undefined] – your personal API key taken from your account settings
  • {number} [options.filter = undefined] – ID of a filter. The ID can be found on filters page
then(onFulfilled, onRejected) -> {Promise<object>}

This method takes up to two arguments: callback functions for the success and failure cases of the Promise. See Promise#then() documentation for more info.

catch(onRejected) -> {Promise<any>}

This method returns a Promise and deals with rejected cases only. See Promise#catch() documentation for more info.

class NetworkError > Error

constructor() -> {NetworkError}

This class can be used to check if network error was thrown.

Instance properties

response -> {Response}

Returns a Response object.

url -> {string}

Contains the URL of the response.

status -> {number}

Contains the status code of the response (e.g., 200 for a success).

statusText -> {string}

Contains the status message corresponding to the status code (e.g., OK for 200).

Related

Another API bindings:

You can’t perform that action at this time.