Update v1.1.0 (#10)

Features

- Add size to HawAPIOptions
- Add PageableBuilder
- Add setLanguage method

Changes

- Update typedoc config
- Update buildUrl to overwrite values
- Update filters value to be undefined or null
- Update param language from getOverview be undefined
- Replace null with undefined on RequestResult

Fixes

- Fix missing types export
- Fix value `cached` from ResultRequest always being true

Author: LucJosin

package.json

@@ -39,11 +39,12 @@
   "exports": {
     ".": [
       {
+        "types": "./dist/types/index.d.ts",
         "import": "./dist/index.min.mjs",
         "require": "./dist/index.min.cjs",
         "default": "./dist/index.min.js"
       },
-      "./dist/index.js"
+      "./dist/index.min.js"
     ]
   },
   "scripts": {
@@ -63,20 +64,20 @@
   "devDependencies": {
     "@mxssfd/typedoc-theme": "^1.1.2",
     "@rollup/plugin-terser": "^0.4.3",
-    "@types/eslint": "^8.4.10",
-    "@types/jest": "^29.2.4",
+    "@types/eslint": "^8.44.2",
+    "@types/jest": "^29.5.4",
     "@types/prettier": "^2.7.2",
     "@typescript-eslint/eslint-plugin": "^5.47.0",
     "@typescript-eslint/parser": "^5.47.0",
-    "eslint": "^8.30.0",
+    "eslint": "^8.48.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.2.1",
-    "jest": "^29.3.1",
+    "jest": "^29.6.4",
     "prettier": "^2.8.1",
     "rollup": "^2.79.1",
     "rollup-plugin-typescript2": "^0.34.1",
-    "ts-jest": "^29.0.3",
-    "ts-jest-resolver": "^2.0.0",
+    "ts-jest": "^29.1.1",
+    "ts-jest-resolver": "^2.0.1",
     "typedoc": "^0.24.8",
     "typescript": "^4.9.4"
   }

src/HawAPIClient.ts

@@ -1,7 +1,7 @@
 import HawAPIOptions from './HawAPIOptions';
 import { isValidTargetOrThrow } from './Utils';
 import { InMemoryCacheManager } from './cache';
-import { EndpointType, Endpoints } from './enums/EndpointType';
+import { EndpointType, Endpoints } from './enums';
 import { Filters, Pageable } from './filters';
 import {
   APIInfoModel,
@@ -71,7 +71,7 @@ export default class HawAPIClient {
 
   /**
    * Method to get all client options
-   * @returns
+   * @returns The current {@link HawAPIOptions} (without token)
    */
   public async getOptions(): Promise<HawAPIOptions> {
     return {
@@ -80,6 +80,13 @@ export default class HawAPIClient {
     };
   }
 
+  /**
+   * Method to define new language into client options
+   */
+  public async setLanguage(language: string): Promise<void> {
+    this.options.language = language;
+  }
+
   /**
    * Method to clear all cached data
    * @returns The count of all cleaned data
@@ -120,9 +127,9 @@ export default class HawAPIClient {
    * @returns An new {@link RequestResult} with overview
    */
   public async getOverview<OverviewModel>(
-    language: string
+    language?: string
   ): Promise<RequestResult<OverviewModel>> {
-    return this.service.fetch(`/overview`, { language }, null);
+    return this.service.fetch(`/overview`, { language: language }, null);
   }
 
   /**

src/HawAPIOptions.ts

@@ -1,4 +1,4 @@
-import { API_DEFAULT_LANG, API_URL, API_VERSION } from './Constants';
+import { API_URL, API_VERSION } from './Constants';
 
 /**
  * The HawAPI options configuration.
@@ -19,13 +19,22 @@ class HawAPIOptions {
   version: string = API_VERSION;
 
   /**
-   * The language of items in request
+   * The language of items for all requests
    *
    * **Note: This value can be overwritten later**
    *
    * @default 'en-US'
    */
-  language: string;
+  language?: string;
+
+  /**
+   * The size of items for all requests
+   *
+   * **Note: This value can be overwritten later**
+   *
+   * @default 10
+   */
+  size?: number;
 
   /**
    * The timeout of a response in milliseconds
@@ -52,7 +61,6 @@ class HawAPIOptions {
   constructor(config: Partial<HawAPIOptions> = {}) {
     this.endpoint = API_URL;
     this.version = API_VERSION;
-    this.language = API_DEFAULT_LANG;
     this.timeout = 10 * 1000;
     this.inMemoryCache = true;
 
@@ -62,6 +70,8 @@ class HawAPIOptions {
 
     if (config.language) this.language = config.language;
 
+    if (config.size) this.size = config.size;
+
     if (config.timeout) this.timeout = config.timeout;
 
     if (config.token) this.token = config.token;

src/Utils.ts

@@ -40,13 +40,13 @@ export function buildResult<T>(
   const language = headers.get(API_HEADER_CONTENT_LANGUAGE);
 
   return {
-    page: Number(page) || null,
-    page_size: Number(page_size) || null,
-    page_total: Number(page_total) || null,
-    item_size: Number(item_total) || null,
-    next_page: handlePagination(Number(page), true) || null,
-    prev_page: handlePagination(Number(page), false) || null,
-    language: language || null,
+    page: Number(page) || undefined,
+    page_size: Number(page_size) || undefined,
+    page_total: Number(page_total) || undefined,
+    item_size: Number(item_total) || undefined,
+    next_page: handlePagination(Number(page), true) || undefined,
+    prev_page: handlePagination(Number(page), false) || undefined,
+    language: language || undefined,
     status: status,
     data: body,
   };
@@ -89,33 +89,56 @@ export function buildUrl(
   filters?: Filters | null,
   pageable?: Pageable | null
 ) {
-  let params = '?';
+  let params: string[] = [];
+
+  if (options.language) params.push(`language=${options.language}`);
+  if (options.size) params.push(`size=${options.size}`);
 
   // Get all filters names and values
   if (filters) {
     for (const key in filters) {
       const value = filters[key];
       if (value !== undefined && value !== null) {
-        params += `${key}=${value}&`;
+        params = pushOrOverwrite(params, key, value);
       }
     }
   }
 
   // Define the page, sort and order
   if (pageable) {
-    if (pageable.page) params += `page=${pageable.page}&`;
-    if (pageable.size) params += `size=${pageable.size}&`;
+    if (pageable.page) params = pushOrOverwrite(params, 'page', pageable.page);
+    if (pageable.size) params = pushOrOverwrite(params, 'size', pageable.size);
 
     // 'Order' can only be applied when 'sort' is defined
     if (pageable.sort) {
       if (pageable.order) {
-        params += `sort=${pageable.sort},${pageable.order}&`;
+        params = pushOrOverwrite(
+          params,
+          'sort',
+          `${pageable.sort},${pageable.order}`
+        );
       } else {
-        params += `sort=${pageable.sort}&`;
+        params = pushOrOverwrite(params, 'sort', pageable.sort);
       }
     }
   }
 
-  params = params.slice(0, -1);
-  return options.endpoint + `/${options.version}${target}${params}`;
+  const stringOfParams = params.length !== 0 ? '?' + params.join('&') : '';
+  return options.endpoint + `/${options.version}${target}${stringOfParams}`;
+}
+
+/**
+ * Method to push new key/value or overwrite existing one
+ * @param params A array of strings
+ * @param key The param name
+ * @param value The param value
+ * @returns A array of strings with new key/value or overwritten value
+ */
+function pushOrOverwrite(params: string[], key: string, value: unknown) {
+  const param = params.find((e) => e.includes(key));
+
+  if (param !== undefined) params[params.indexOf(param)] = `${key}=${value}`;
+  else params.push(`${key}=${value}`);
+
+  return params;
 }

src/cache/InMemoryCacheManager.ts

@@ -37,11 +37,14 @@ export class InMemoryCacheManager {
    *
    * @param key The cache key
    * @param value The value to be cached
+   * @returns true if {@link useCache} is true and the cache was added or false if {@link useCache} is false
    */
-  async set(key: string, value: RequestResult<unknown>): Promise<void> {
+  async set(key: string, value: RequestResult<unknown>): Promise<boolean> {
     if (this.useCache) {
-      this.storage.set(key, value);
+      return this.storage.set(key, value) !== undefined;
     }
+
+    return false;
   }
 
   /**

src/filters/Filters.ts

@@ -5,5 +5,5 @@
  * See more: {@link https://hawapi.theproject.id/docs/guides/filters}
  */
 export type Filters = {
-  [key: string]: string;
+  [key: string]: string | undefined | null;
 };

src/filters/Pageable.ts

@@ -49,4 +49,39 @@ export class Pageable {
 
     if (pageable.order) this.order = pageable.order;
   }
+
+  /**
+   * A fluent builder for configuring Pageable
+   */
+  static Builder = class PageableBuilder {
+    private pageable: Pageable = new Pageable({});
+
+    page(value: number) {
+      this.pageable.page = value;
+      return this;
+    }
+
+    size(value: number) {
+      this.pageable.size = value;
+      return this;
+    }
+
+    order(value: OrderType) {
+      this.pageable.order = value;
+      return this;
+    }
+
+    sort(value: string) {
+      this.pageable.sort = value;
+      return this;
+    }
+
+    /**
+     * Converts the pageable builder into {@link Pageable}
+     * @returns A new {@link Pageable}
+     */
+    build(): Pageable {
+      return new Pageable(this.pageable);
+    }
+  };
 }

src/models/http/RequestResult.ts

@@ -5,44 +5,44 @@ export interface RequestResult<T> {
   /**
    * The current page index
    */
-  page?: number | null;
+  page?: number | undefined;
 
   /**
    * The item size of current page
    */
-  page_size?: number | null;
+  page_size?: number | undefined;
 
   /**
    * The total of pages
    */
-  page_total?: number | null;
+  page_total?: number | undefined;
 
   /**
    * The total of items in the database
    */
-  item_size?: number | null;
+  item_size?: number | undefined;
 
   /**
    * The next page index
    */
-  next_page?: number | null;
+  next_page?: number | undefined;
 
   /**
    * The previous page index
    */
-  prev_page?: number | null;
+  prev_page?: number | undefined;
 
   /**
    * The content language
    *
    * {@link HawAPIOptions}
    */
-  language?: string | null;
+  language?: string | undefined;
 
   /**
    * The request status code
    */
-  status?: number | null;
+  status: number;
 
   /**
    * Determine if data is from cache

src/service/Service.ts

@@ -34,7 +34,7 @@ export class Service {
     const url = buildUrl(baseUrl, this.options, filters, pageable);
 
     const cache = await this.cache.get<T>(url);
-    if (cache !== undefined) return { ...cache, cached: true };
+    if (cache !== undefined) return { cached: true, ...cache };
 
     // Setup timeout
     let timeout;
@@ -59,9 +59,8 @@ export class Service {
         response.status
       );
 
-      await this.cache.set(url, result);
-
-      return { ...result, cached: true };
+      const cached = await this.cache.set(url, result);
+      return { cached, ...result };
     } catch (err) {
       const isJson = response.headers.get('Content-Type') == 'application/json';
 

test/HawAPIClient.test.ts

@@ -13,7 +13,8 @@ test('it use default client options', async () => {
 
   expect(options.endpoint).toBe('https://hawapi.theproject.id/api');
   expect(options.version).toBe('v1');
-  expect(options.language).toBe('en-US');
+  expect(options.language).toBeUndefined();
+  expect(options.size).toBeUndefined();
   expect(options.timeout).toBe(10000);
   expect(options.token).toBe('');
   expect(options.inMemoryCache).toBe(true);