Git Product home page Git Product logo

dinky's Introduction

dinky.js

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

ESLint CI Code Coverage

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)
  1. 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)
  1. 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"])
  1. 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"])
  1. 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
  1. 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)
  1. 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})
  1. 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

Another API bindings:

dinky's People

Contributors

dependabot[bot] avatar jozsefsallai avatar octet-stream avatar veetaha avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

dinky's Issues

Search random image without specifying tags throws invalid json error.

When you run

await dinky().search().random()

it throws

FetchError: invalid json response body at 
https://derpibooru.org/search.json?random_image=true reason: 
Unexpected end of JSON input

Its because this request results in an empty body.

https://derpibooru.org/search.json?random_image=true

You should set q=* parameter when there are no tags specified in order to resolve the issue.

Types are not published on npm

Hello!

I noticed that the repo contains type declarations, however, they are not published on npm yet (they were created after March, when the latest release was published). This makes it a bit cumbersome to work with dinky.js in a TypeScript environment (right now I'm using patch-package to add the missing types or I just pull the package from Github).

Is there any reason why the latest changes weren't published since March? And when do you think you could make the type declarations available in the package too?

No rush, just a question :)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.