dinky.js
JavaScript bindings for Derpibooru API
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.
- The minimal example that will return an image by known ID:
import dinky from "dinky.js"
dinky().images().getById(0).then(console.log)
- Search for images by their tags using the
.search()
method:
import dinky from "dinky.js"
dinky().search(["artist:rainbow", "safe"]).random()
.then(console.log)
- Since
.search()
method returns Search
instance
you can store it into variable for the further usage:
import dinky from "dinky.js"
(async function() {
const random = dinky()
.search(["scootaloo", "princess luna", "safe", "sleepless in ponyville"])
.minScore(200)
.random()
.limit(1)
await random
await random
}()).catch(console.error)
- Walking through the search results:
import dinky from "dinky.js"
(async function() {
const search = dinky().search(["twilight sparkle"]).minScore(200)
await search
await search.page(2)
const images = dinky().images()
await images.page(2)
}()).catch(console.error)
- You can set a filter to use for requests:
import dinky from "dinky.js"
dinky({filter: 37430}).search(["dinky", "derpy hooves"]).then(console.log)
dinky({filter: 37430}).search(["dinky", "derpy hooves"]).exec({filter: 100073})
.then(console.log)
- 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 /api/v1/json/images
search([query]) -> {Search}
Creates a request handler for /api/v1/json/search/images
. This method takes a list of query params
- {string | string[]} [query = []] – a tag or a list of query params and returns Search instance
class Images > Entities
constructor() -> {Images}
Creates a request handler for /api/v1/json/images
Instance methods
search([query]) -> {Search}
Creates a new Search request that points to /api/v1/json/search/images
.
getById(id) -> {Promise<object>}
Returns an image with given ID
featured() -> {Promise<object>}
Returns featured image
Creates a request handler for /api/v1/json/comments
.
Instance methods
search([query]) -> {Search}
Creates a new Search request that points to /api/v1/json/search/comments
.
getById(id) -> {Promise<object>}
Returns a comment with given ID
class Tags > Entities
constructor() -> {Tags}
Creates a request handler for /api/v1/json/tags
.
Instance methods
search([query]) -> {Search}
Creates a new Search request that points to /api/v1/json/search/tags
.
getById(id) -> {Promise<object>}
Returns a tag with given ID
class Search > Request
constructor() -> {Search}
Creates a request handler for /api/v1/json/search
.
Instance methods
Sets Search type to "comments"
galleries() -> {Search}
Sets Search type to "galleries"
posts() -> {Search}
Sets Search type to "posts"
tags() -> {Search}
Sets Search type to "tags"
images() -> {Search}
Sets Search type to "images"
query([list]) -> {Search}
Appends list of query params to the current search request.
This method will not apply the q=
parameter to if called without arguments.
- {string | string[]} [list = []] – list of query params you want to append
faves() -> {Search}
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() -> {Search}
If been called, the API will return random image
class Lists > Request
constructor() -> {Lists}
Provides a bunch of shortcuts for Search
request
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.
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 Entities > Request
constructor() -> {Entities}
Creates an Entity providing a few common methods for Images
, Comments
and Tags
Instance methods
search([query]) -> {Search}
Creates a new Search request that points to /api/v1/json/search
.
getById(id) -> {Promise<object>}
Finds an entity by given ID
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: