{"id":18600807,"url":"https://github.com/octet-stream/dinky","last_synced_at":"2025-04-10T18:31:35.997Z","repository":{"id":53520850,"uuid":"167169093","full_name":"octet-stream/dinky","owner":"octet-stream","description":"JavaScript bindings for Philomena JSON API. Supports sites such as Derpibooru and Furbooru.","archived":false,"fork":false,"pushed_at":"2023-10-22T00:59:21.000Z","size":979,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-25T03:01:35.444Z","etag":null,"topics":["api-bindings","api-client","derpibooru","furbooru","javascript","javascript-library","mylittlepony","philomena"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/dinky.js","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/octet-stream.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-23T11:06:51.000Z","updated_at":"2022-10-26T17:55:15.000Z","dependencies_parsed_at":"2022-09-03T12:00:29.906Z","dependency_job_id":null,"html_url":"https://github.com/octet-stream/dinky","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octet-stream%2Fdinky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octet-stream%2Fdinky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octet-stream%2Fdinky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/octet-stream%2Fdinky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/octet-stream","download_url":"https://codeload.github.com/octet-stream/dinky/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085322,"owners_count":21045139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-bindings","api-client","derpibooru","furbooru","javascript","javascript-library","mylittlepony","philomena"],"created_at":"2024-11-07T02:05:43.098Z","updated_at":"2025-04-10T18:31:35.348Z","avatar_url":"https://github.com/octet-stream.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dinky.js\n\nJavaScript bindings for [Philomena](https://github.com/philomena-dev/philomena) JSON API. Supports sites such as [Derpibooru](https://derpibooru.org) and [Furbooru](https://furbooru.org).\n\n[![ESLint](https://github.com/octet-stream/dinky/workflows/ESLint/badge.svg)](https://github.com/octet-stream/dinky/actions/workflows/eslint.yml)\n[![CI](https://github.com/octet-stream/dinky/workflows/CI/badge.svg)](https://github.com/octet-stream/dinky/actions/workflows/ci.yml)\n[![Code Coverage](https://codecov.io/github/octet-stream/dinky/coverage.svg?branch=master)](https://codecov.io/github/octet-stream/dinky?branch=master)\n\n## Installation\n\nYou can install this package from npm:\n\n```\nnpm install dinky.js\n```\n\nOr with yarn:\n\n```\nyarn add dinky.js\n```\n\nOr via pnpm:\n\n```\npnpm add dinky.js\n```\n\n## Usage\n\nDinky 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.\n\n1. The minimal example that will return an image by known ID:\n\n```js\nimport {Images} from \"dinky.js\"\n\nconst images = new Images()\n\n// The following request will return the 1th uploaded image from Derpibooru.\n// Equivalent to https://derpibooru.org/api/v1/json/images/0 request\nawait images.getById(0)\n```\n\n2. Search for images by their tags using the `Search` class:\n\n```js\nimport {Search} from \"dinky.js\"\n\nconst search = new Search()\n\n// You can specify tags right in the .query() method\n// The following example is equivalent of this requests:\n// https://derpibooru.org/api/v1/json/search/images?q=artist:rainbow,safe\u0026sf=random\u0026per_page=1\nawait search.query([\"artist:rainbow\", \"safe\"]).random().limit(1)\n```\n\n3. Every dinky.js class constructor allows to set a custom base URL, allowing you to use it with any Philomena compatible APIs.\n\n```js\nimport {Search} from \"dinky.js\"\n\nconst search = new Search({url: \"https://furbooru.org\"})\n\nawait search.query([\"safe\", \"loona\"])\n```\n\n4. Dinky has shortcuts for both `entites` and `search` interfaces, so you can build request in similar to v1 manner:\n\n```js\nimport {images, search} from \"dinky.js\"\n\nawait images().getById(0) // Same as new Images().getById(0)\nawait search.reverse(\"https://derpicdn.net/img/2019/12/24/2228439/full.jpg\") // Same as new SearchImages().reverse()\nawait search.images().query([\"pinke pie\", \"safe\"])\n```\n\n5. Every class keeps its state between request, which means you can re-use same object to perform multiple requests.\n\n```js\nimport {Search} from \"dinky.js\"\n\nconst search = new Search()\n\nsearch\n  .query([\"scootaloo\", \"princess luna\", \"safe\", \"sleepless in ponyville\"])\n  .minScore(200)\n  .random()\n  .limit(1)\n\n// Will search for random image with parameters from above\nawait search\n\n// ...and once more\nawait search\n```\n\n7. You can navigate through search results with `.page()` method. Note that after each `.page()` call you have to send a new request to API:\n\n```js\nimport {Search} from \"dinky.js\"\n\nconst search = new Search()\n\nserch.query([\"twilight sparkle\"]).minScore(200)\n\n// Search class is thenable, so you don't have to call `.exec()`,`.then()` and `.catch()` methods to commit a request.\n// By default, will API will return results from the first page\nawait search\n\n// Results for 2nd page\nawait search.page(2)\n```\n\n8. You can set a filter to use for requests:\n\n```js\nimport {Search} from \"dinky.js\"\n\nconst search = new Search({filter: 37430})\n\nsearch.query([\"dinky\", \"derpy hooves\"])\n\nawait search.exec()\n\n// You can also set per-request filter from .exec() method\nawait search.exec({filter: 100073})\n```\n\n9. Search for \"my:faves\" images using a key taken from account page:\n\n```js\nimport {Search} from \"dinky.js\"\n\nconst search = new Search({key: \"\u003cyour key here\u003e\"})\n\n// You can search for `my:faves` images with specific tags\nawait search.query([\"trixie\", \"safe\"]).faves()\n```\n\n## API\n\nFull documentation can be found in [`/docs`](https://github.com/octet-stream/dinky/tree/master/docs) directory.\n\n## Related\n\n* Derpibooru API documentation can be found here: [derpibooru.org/pages/api](https://derpibooru.org/pages/api)\n\n## Another API bindings:\n* [derpiboorust](https://github.com/mxseev/derpiboorust) – Rust\n* [DerPyBooru](https://github.com/joshua-stone/DerPyBooru) – Python\n* [derpigo](https://github.com/Xe/derpigo) – Go\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctet-stream%2Fdinky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foctet-stream%2Fdinky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foctet-stream%2Fdinky/lists"}