e621-client 1.1.3 → 1.2.0

package/demo.ts

@@ -0,0 +1,12 @@
+import { E621ApiClient } from "./src/client/E621ApiClient";
+
+async function demo() {
+  const client = new E621ApiClient({
+    isBrowser: false,
+    client: "EstoBox (by Tommus621 on e621)",
+  });
+  const favs = await client.getFavorites({ userId: "964986", page: "2" });
+  console.log(favs.length);
+}
+
+demo().finally();

package/dist/client/E621ApiClient.d.ts

@@ -1,10 +1,35 @@
 import { E621Post } from "../types/e621/E621Post";
 import { E621User } from "../types/e621/E621User";
 import { E621ApiHeaders } from "./E621ApiHeaders";
+import { GetAllFavoritesOptions, GetFavoritesOptions, GetPostsOptions, GetUsersOptions, Params } from "./options";
+/**
+ * The option object used to initialize the API client.
+ */
 export interface E621ApiOptions {
+    /**
+     *
+     */
     client: string;
+    /**
+     * Required to set the client in an appropriate way for the environment.
+     *
+     * Browsers must send it through query parameters, other environments can set the `User-Agent` header.
+     */
     isBrowser: boolean;
+    /**
+     * Username and API of a user if they are known at constructor call.
+     *
+     * Can be added or removed later with `setCredentials`.
+     */
     credentials?: Credentials;
+    /**
+     * Whether to show more detailed logs for fancier requests (e.g. `getAllFavorites`).
+     */
+    debugLogs?: boolean;
+    /**
+     * The time between two requests when a single method does multiple (e.g. `getAllFavorites`).
+     */
+    batchRateLimit?: number;
 }
 export type GetOptions = {
     route: Route;
@@ -17,35 +42,20 @@ export interface Credentials {
 }
 export type EntityId = string | number;
 export type Route = string | number | (string | number)[];
-export type Params = Record<string, string>;
-export type Pagination = {
-    limit?: string;
-    page?: string;
-};
-export type GetUsersOptions = {
-    nameMatches?: string;
-} & Params & Pagination;
-export type GetPostsOptions = {
-    tags?: string;
-} & Pagination;
-export type GetFavoritesOptions = {
-    userId?: string;
-} & Pagination;
-export type GetAllFavoritesOptions = {
-    userId?: string;
-};
 export declare class E621ApiClient {
     protected static readonly BASE_URL = "https://e621.net/";
     private readonly client;
     private readonly isBrowser;
+    private readonly batchRateLimit;
     private credentials;
+    debugLogs: boolean;
     constructor(options: E621ApiOptions);
     getUsers(options?: GetUsersOptions): Promise<E621User[]>;
     getUserById(id: EntityId): Promise<E621User | null>;
     getPosts(options?: GetPostsOptions): Promise<E621Post[]>;
     getPostById(id: EntityId): Promise<E621Post | null>;
     getFavorites(options?: GetFavoritesOptions): Promise<E621Post[]>;
-    getAllFavorites(options?: GetAllFavoritesOptions, debugLogs?: boolean): Promise<E621Post[]>;
+    getAllFavorites(options?: GetAllFavoritesOptions): Promise<E621Post[]>;
     setCredentials(credentials: Credentials | null): E621ApiClient;
     checkCredentials(credentials?: Credentials): Promise<boolean>;
     get<E>({ route, params, headers, }: GetOptions): Promise<E | null>;

package/dist/client/E621ApiClient.js

@@ -14,21 +14,22 @@ const E621Post_1 = require("../types/e621/E621Post");
 const E621User_1 = require("../types/e621/E621User");
 const utils_1 = require("../utils");
 const E621ApiHeaders_1 = require("./E621ApiHeaders");
+const options_1 = require("./options");
 class E621ApiClient {
     constructor(options) {
         this.credentials = null;
+        this.debugLogs = false;
         this.client = options.client;
         this.isBrowser = options.isBrowser;
         this.credentials = options.credentials || null;
+        this.batchRateLimit = options.batchRateLimit || 0;
     }
     // Users
     getUsers() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
             const users = yield this.get({
                 route: "users",
-                params: (0, utils_1.translateOptions)(options, {
-                    nameMatches: "search[name_matches]",
-                }),
+                params: (0, options_1.translateGetUserOptions)(options),
             });
             return (users === null || users === void 0 ? void 0 : users.map(E621User_1.parseUser)) || [];
         });
@@ -61,20 +62,20 @@ class E621ApiClient {
             var _a;
             const response = yield this.get({
                 route: "favorites",
-                params: (0, utils_1.translateOptions)(options, { userId: "user_id" }),
+                params: (0, options_1.translateGetFavoritesOptions)(options),
             });
             return ((_a = response === null || response === void 0 ? void 0 : response.posts) === null || _a === void 0 ? void 0 : _a.map(E621Post_1.parsePost)) || [];
         });
     }
     getAllFavorites() {
-        return __awaiter(this, arguments, void 0, function* (options = {}, debugLogs = false) {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
             var _a, _b;
             // max page size on e621 api
             const favorites = [];
             const limit = 300;
             let page = 1;
             while (true) {
-                if (debugLogs) {
+                if (this.debugLogs) {
                     const user = (_a = options.userId) !== null && _a !== void 0 ? _a : (_b = this.credentials) === null || _b === void 0 ? void 0 : _b.username;
                     console.info(`page ${page} for user ${user}`);
                 }
@@ -82,6 +83,7 @@ class E621ApiClient {
                 if (posts.length === 0)
                     break;
                 favorites.push(...posts);
+                yield (0, utils_1.delay)(this.batchRateLimit);
             }
             return favorites;
         });
@@ -96,14 +98,8 @@ class E621ApiClient {
             if (credentials) {
                 this.setCredentials(credentials);
             }
-            const headers = new E621ApiHeaders_1.E621ApiHeaders();
-            if (!this.isBrowser) {
-                headers.addUserAgent(this.client);
-            }
-            return yield fetch(this.buildUrl("favorites"), {
-                headers: headers.addAuthorization(this.credentials).build(),
-            })
-                .then((res) => res.ok)
+            return yield this.get({ route: "favorites" })
+                .then(() => true)
                 .catch(() => false);
         });
     }
@@ -112,16 +108,20 @@ class E621ApiClient {
             if (!this.isBrowser) {
                 headers.addUserAgent(this.client);
             }
-            const response = yield fetch(this.buildUrl(route, params), {
+            const url = this.buildUrl(route, params);
+            const response = yield fetch(url, {
                 method: "GET",
                 headers: headers.addAuthorization(this.credentials).build(),
             });
             if (response.ok) {
-                return response.json().catch(utils_1.logErrorAndReturnNull);
+                return response.json();
             }
-            else {
+            else if (response.status === 404) {
                 return null;
             }
+            else {
+                throw new Error(`Request to ${route} failed with status code ${response.status}`);
+            }
         });
     }
     buildUrl(route, params = {}) {

package/dist/client/options.d.ts

@@ -0,0 +1,25 @@
+export type Params = Record<string, string>;
+export type Pagination = {
+    limit?: string;
+    page?: string;
+};
+export type GetUsersOptions = {
+    nameMatches?: string;
+} & Params & Pagination;
+export type GetUserApiOptions = {
+    "search[name_matches]"?: string;
+} & Pagination;
+export type GetPostsOptions = {
+    tags?: string;
+} & Pagination;
+export type GetFavoritesOptions = {
+    userId?: string;
+} & Pagination;
+export type GetFavoritesApiOptions = {
+    user_id?: string;
+} & Pagination;
+export type GetAllFavoritesOptions = {
+    userId?: string;
+};
+export declare function translateGetUserOptions(options: GetUsersOptions): GetUserApiOptions;
+export declare function translateGetFavoritesOptions(options: GetFavoritesOptions): GetFavoritesApiOptions;

package/dist/client/options.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translateGetFavoritesOptions = exports.translateGetUserOptions = void 0;
+const utils_1 = require("../utils");
+function translateGetUserOptions(options) {
+    return (0, utils_1.translateOptions)(options, {
+        nameMatches: "search[name_matches]",
+    });
+}
+exports.translateGetUserOptions = translateGetUserOptions;
+function translateGetFavoritesOptions(options) {
+    return (0, utils_1.translateOptions)(options, {
+        userId: "user_id",
+    });
+}
+exports.translateGetFavoritesOptions = translateGetFavoritesOptions;

package/dist/utils.d.ts

@@ -1,3 +1,3 @@
 export declare function ensureArray<T>(value: T | T[]): T[];
-export declare function translateOptions<Options extends Record<string, string>>(options: Options, table: Partial<Options>): Record<string, string>;
-export declare function logErrorAndReturnNull(error: unknown): null;
+export declare function delay(ms: number): Promise<void>;
+export declare function translateOptions(options: Record<string, string | undefined>, table: Record<string, string | undefined>): Record<string, string>;

package/dist/utils.js

@@ -1,6 +1,15 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logErrorAndReturnNull = exports.translateOptions = exports.ensureArray = void 0;
+exports.translateOptions = exports.delay = exports.ensureArray = void 0;
 function ensureArray(value) {
     if (Array.isArray(value)) {
         return value;
@@ -8,17 +17,22 @@ function ensureArray(value) {
     return [value];
 }
 exports.ensureArray = ensureArray;
+function delay(ms) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (ms <= 0)
+            return;
+        return new Promise((res) => setTimeout(res, ms));
+    });
+}
+exports.delay = delay;
 function translateOptions(options, table) {
     var _a;
     const params = {};
     for (const [key, value] of Object.entries(options)) {
-        params[(_a = table[key]) !== null && _a !== void 0 ? _a : key] = value;
+        if (value !== undefined) {
+            params[(_a = table[key]) !== null && _a !== void 0 ? _a : key] = value;
+        }
     }
     return params;
 }
 exports.translateOptions = translateOptions;
-function logErrorAndReturnNull(error) {
-    console.error(error);
-    return null;
-}
-exports.logErrorAndReturnNull = logErrorAndReturnNull;

package/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/?(*.)+(spec|test).[tj]s?(x)"],
+  testPathIgnorePatterns: ["/dist/"],
+};

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "e621-client",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
+    "test": "jest",
     "build": "tsc",
     "prepublishOnly": "tsc"
   },
@@ -12,8 +13,11 @@
   "license": "ISC",
   "description": "A simple client for the e621 API",
   "devDependencies": {
+    "@types/jest": "^29.5.12",
     "@types/node": "^20.14.2",
+    "jest": "^29.7.0",
     "prettier": "^3.3.1",
+    "ts-jest": "^29.2.3",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.5"
   }

package/src/client/E621ApiClient.spec.ts

@@ -0,0 +1,305 @@
+import { E621ApiClient } from "./E621ApiClient";
+import { MockedFetch, mockFetch } from "../test-utils/mockFetch";
+import { createClient } from "../test-utils/createClient";
+import { createApiUser, createUser } from "../test-utils/createUser";
+import { createApiPost, createPost } from "../test-utils/createPost";
+import {
+  GetFavoritesResponse,
+  GetPostResponse,
+  GetPostsResponse,
+} from "../types/responses";
+import { delay } from "../utils";
+
+describe("E621ApiClient", () => {
+  beforeEach(() => {
+    jest.resetAllMocks();
+  });
+
+  describe("generic get endpoint", () => {
+    let fetchMock: MockedFetch;
+
+    beforeEach(() => {
+      fetchMock = mockFetch();
+    });
+
+    it("should build the url correctly", async () => {
+      const client = createClient();
+
+      await client.get({ route: "favorites" });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/favorites.json",
+        expect.anything(),
+      );
+
+      await client.get({ route: 1234 });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/1234.json",
+        expect.anything(),
+      );
+
+      await client.get({ route: ["users", "tommus"] });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/users/tommus.json",
+        expect.anything(),
+      );
+
+      await client.get({ route: ["users", 1234] });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/users/1234.json",
+        expect.anything(),
+      );
+    });
+
+    it("should pass the client in query params when in browser mode", async () => {
+      const client = createClient({
+        client: "jest",
+        isBrowser: true,
+      });
+
+      await client.get({ route: "test" });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/test.json?_client=jest",
+        expect.anything(),
+      );
+    });
+
+    it("should pass the client in headers when not in browser mode", async () => {
+      const client = createClient({
+        client: "jest",
+        isBrowser: false,
+      });
+
+      await client.get({ route: "test" });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/test.json",
+        expect.objectContaining({
+          headers: { "User-Agent": "jest" },
+        }),
+      );
+    });
+
+    it("should add the query parameters properly", async () => {
+      const client = createClient({ isBrowser: false });
+
+      await client.get({
+        route: "test",
+        params: {
+          param1: "abc",
+          param2: "def",
+        },
+      });
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://e621.net/test.json?param1=abc&param2=def",
+        expect.anything(),
+      );
+    });
+  });
+
+  describe("specific endpoints", () => {
+    let client: E621ApiClient;
+    let getMock: jest.SpyInstance;
+
+    beforeEach(() => {
+      client = createClient();
+      getMock = jest.spyOn(client, "get").mockResolvedValue(null);
+    });
+
+    describe("getUsers", () => {
+      it("should use the correct default values", async () => {
+        await client.getUsers();
+        expect(getMock).toHaveBeenCalledWith({ route: "users", params: {} });
+      });
+
+      it("should return empty array if get returns null", async () => {
+        getMock.mockResolvedValue(null);
+        const users = await client.getUsers();
+        expect(users).toEqual([]);
+      });
+
+      it("should translate options into query params", async () => {
+        await client.getUsers({
+          page: "1",
+          limit: "20",
+          nameMatches: "Tommus",
+        });
+        expect(getMock).toHaveBeenCalledWith(
+          expect.objectContaining({
+            params: {
+              page: "1",
+              limit: "20",
+              "search[name_matches]": "Tommus",
+            },
+          }),
+        );
+      });
+
+      it("should transform the API users to client users", async () => {
+        const usersResponse = [
+          createApiUser({ id: 1, name: "Zackary911" }),
+          createApiUser({ id: 2, name: "Braeburned" }),
+          createApiUser({ id: 3, name: "LetoDoesArt" }),
+        ];
+        getMock.mockResolvedValue(usersResponse);
+
+        const users = await client.getUsers();
+        expect(users).toEqual([
+          createUser({ id: 1, name: "Zackary911" }),
+          createUser({ id: 2, name: "Braeburned" }),
+          createUser({ id: 3, name: "LetoDoesArt" }),
+        ]);
+      });
+    });
+
+    describe("getUserById", () => {
+      it("should use the correct default values", async () => {
+        await client.getUserById(123);
+        expect(getMock).toHaveBeenCalledWith({ route: ["users", 123] });
+      });
+
+      it("should return null if no user is found", async () => {
+        getMock.mockResolvedValue(null);
+        const user = await client.getUserById(123);
+        expect(user).toBeNull();
+      });
+
+      it("should transform the API user to client user", async () => {
+        const userResponse = createApiUser({ id: 123 });
+        getMock.mockResolvedValue(userResponse);
+
+        const user = await client.getUserById(123);
+        expect(user).toEqual(createUser({ id: 123 }));
+      });
+    });
+
+    describe("getPosts", () => {
+      it("should use the correct default values", async () => {
+        await client.getPosts();
+        expect(getMock).toHaveBeenCalledWith({ route: "posts", params: {} });
+      });
+
+      it("should return empty array if get returns null", async () => {
+        getMock.mockResolvedValue(null);
+        const posts = await client.getPosts();
+        expect(posts).toEqual([]);
+      });
+
+      it("should transform the API posts to client posts", async () => {
+        const postsResponse: GetPostsResponse = {
+          posts: [
+            createApiPost({ id: 1 }),
+            createApiPost({ id: 2 }),
+            createApiPost({ id: 3 }),
+          ],
+        };
+        getMock.mockResolvedValue(postsResponse);
+
+        const posts = await client.getPosts();
+        expect(posts).toEqual([
+          createPost({ id: 1 }),
+          createPost({ id: 2 }),
+          createPost({ id: 3 }),
+        ]);
+      });
+    });
+
+    describe("getPostById", () => {
+      it("should use the correct default values", async () => {
+        await client.getPostById(123);
+        expect(getMock).toHaveBeenCalledWith({ route: ["posts", 123] });
+      });
+
+      it("should return null if no post is found", async () => {
+        getMock.mockResolvedValue(null);
+        const post = await client.getPostById(123);
+        expect(post).toBeNull();
+      });
+
+      it("should transform the API post to client post", async () => {
+        const postsResponse: GetPostResponse = {
+          post: createApiPost({ id: 123 }),
+        };
+        getMock.mockResolvedValue(postsResponse);
+
+        const post = await client.getPostById(123);
+        expect(post).toEqual(createPost({ id: 123 }));
+      });
+    });
+
+    describe("getFavorites", () => {
+      it("should use the correct default values", async () => {
+        await client.getFavorites();
+        expect(getMock).toHaveBeenCalledWith({
+          route: "favorites",
+          params: {},
+        });
+      });
+
+      it("should return empty array if get returns null", async () => {
+        getMock.mockResolvedValue(null);
+        const posts = await client.getFavorites();
+        expect(posts).toEqual([]);
+      });
+
+      it("should transform the API posts to client posts", async () => {
+        const postsResponse: GetFavoritesResponse = {
+          posts: [
+            createApiPost({ id: 1 }),
+            createApiPost({ id: 2 }),
+            createApiPost({ id: 3 }),
+          ],
+        };
+        getMock.mockResolvedValue(postsResponse);
+
+        const posts = await client.getFavorites();
+        expect(posts).toEqual([
+          createPost({ id: 1 }),
+          createPost({ id: 2 }),
+          createPost({ id: 3 }),
+        ]);
+      });
+    });
+
+    describe("getAllFavorites", () => {
+      it("should call getFavorites until final page", async () => {
+        let page = 0;
+        const lastPage = 3;
+
+        const apiClient = createClient();
+        const getFavoritesMock = jest
+          .spyOn(apiClient, "getFavorites")
+          .mockImplementation(() => {
+            return page++ === lastPage
+              ? Promise.resolve([])
+              : Promise.resolve([createPost()]);
+          });
+
+        const favorites = await apiClient.getAllFavorites();
+        expect(favorites).toEqual([createPost(), createPost(), createPost()]);
+        expect(getFavoritesMock).toHaveBeenCalledTimes(lastPage + 1);
+      });
+
+      it("wait between getFavorite calls with the given rate limit", async () => {
+        let page = 0;
+        const lastPage = 5;
+
+        const apiClient = createClient({ batchRateLimit: 100 });
+        const getFavoritesMock = jest
+          .spyOn(apiClient, "getFavorites")
+          .mockImplementation(() => {
+            return page++ === lastPage
+              ? Promise.resolve([])
+              : Promise.resolve([createPost()]);
+          });
+
+        await new Promise(async (res) => {
+          apiClient.getAllFavorites().then(res);
+
+          // wait until 4 calls have been made (1 on start, and 1 each 100 after that) - 50ms grace period for timeout
+          delay(350).then(() => {
+            expect(getFavoritesMock).toHaveBeenCalledTimes(4);
+          });
+        });
+      });
+    });
+  });
+});