@qgisk/jokeapi-wrapper - npm Package Compare versions

Comparing version 1.0.8 to 2.0.0

index.js

@@ -1,1 +0,3 @@
-module.exports = require('./src/index');
+import JokeAPI from './src/index.js';
+
+export default JokeAPI;

package.json

 {
+  "type": "module",
   "name": "@qgisk/jokeapi-wrapper",
-  "version": "1.0.8",
+  "version": "2.0.0",
   "description": "Wrapper for Joke API",
-  "main": "index.js",
+  "exports": "./index.js",
   "files": [
+    "src",
+    "src/helpers",
     "index.js",
-    "src/index.js",
-    "src/helpers/constants.js",
-    "src/helpers/util.js"
+    "types"
   ],
@@ -17,7 +18,11 @@ "scripts": {
     "prettier": "prettier --check **/*.js",
-    "prettier:fix": "prettier --write **/*.js"
+    "prettier:fix": "prettier --write **/*.js",
+    "release": "standard-version",
+    "release:minor": "standard-version --release-as minor",
+    "release:patch": "standard-version --release-as patch",
+    "release:major": "standard-version --release-as major"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/QGIsK/JokeAPIWrapper-JS.git"
+    "url": "git+https://github.com/QGIsK/jokeapi-wrapper.git"
   },
@@ -38,17 +43,27 @@ "keywords": [
   "bugs": {
-    "url": "https://github.com/QGIsK/JokeAPIWrapper-JS/issues"
+    "url": "https://github.com/QGIsK/jokeapi-wrapper/issues"
   },
-  "homepage": "https://github.com/QGIsK/JokeAPIWrapper-JS#readme",
+  "homepage": "https://github.com/QGIsK/jokeapi-wrapper#readme",
   "devDependencies": {
+    "@ava/babel": "^2.0.0",
+    "@commitlint/cli": "^15.0.0",
+    "@commitlint/config-conventional": "^15.0.0",
+    "@typescript-eslint/parser": "^5.6.0",
     "ava": "^3.15.0",
-    "eslint": "^7.0.0",
-    "eslint-config-airbnb-base": "^14.0.0",
-    "eslint-config-prettier": "^8.1.0",
-    "eslint-plugin-prettier": "^3.1.1",
+    "eslint": ">=8.0.0",
+    "eslint-config-google": "^0.14.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
     "eslint-plugin-security": "^1.4.0",
-    "prettier": "^2.0.5"
+    "husky": "^7.0.4",
+    "prettier": "^2.0.5",
+    "standard-version": "^9.3.2",
+    "typescript": "^4.5.3"
   },
   "dependencies": {
-    "node-fetch": "^2.6.1"
+    "isomorphic-unfetch": "^3.1.0"
+  },
+  "ava": {
+    "babel": true
   }
 }

README.md

@@ -8,3 +8,3 @@ # Joke API Client for NodeJS
 
-A Node.js wrapper for the JokeAPI with only one dependency [node-fetch](https://www.npmjs.com/package/node-fetch).
+A Node.js wrapper for the JokeAPI with only one dependency [isomorphic-unfetch](https://www.npmjs.com/package/isomorphic-unfetch).
 
@@ -17,20 +17,11 @@ ## • Installation
 
-## • JokeAPI Documentation
+## • Example Project
 
-For complete API documentation, up-to-date parameters, responses and errors, please refer to [JokeAPI](https://jokeapi.dev).
+[Discord Bot](https://discord.com/oauth2/authorize?client_id=896816739336196208&permissions=0&scope=bot%20applications.commands) | [Source](https://github.com/QGIsK/JokeBot)
 
-## • Constants
+## • JokeAPI Documentation
 
-This module provides helper constants for use in calls.
+For the full wrapper documentation checkout [this](https://jokewrapper.docs.demiann.dev/)
 
-| Key               | Usage                     | Description                         |
-| ----------------- | ------------------------- | ----------------------------------- |
-| `BASE`            | `JokeAPI.BASE`            | Base url for api                    |
-| `HOST`            | `JokeAPI.HOST`            | Host url                            |
-| `API_VERSION`     | `JokeAPI.API_VERSION`     | Current api version                 |
-| `CATEGORIES`      | `JokeAPI.CATEGORIES`      | Lists all avaliable categories      |
-| `BLACKLIST_FLAGS` | `JokeAPI.BLACKLIST_FLAGS` | Lists all avaliable blacklist flags |
-| `FORMAT`          | `JokeAPI.FORMAT`          | Lists all avaliable formats         |
-| `TYPE`            | `JokeAPI.TYPE`            | Lists all avaliable types           |
-| `AMOUNT_MAX`      | `JokeAPI.AMOUNT_MAX`      | Max amount of jokes per request     |
+For complete API documentation, up-to-date parameters, responses and errors, please refer to [JokeAPI](https://jokeapi.dev).
 
@@ -41,3 +32,3 @@ ## • Quick Start Example
 // Import the wrapper library
-const JokeAPI = require('@qgisk/jokeapi-wrapper');
+import JokeAPI from '@qgisk/jokeapi-wrapper';
 
@@ -57,208 +48,2 @@ // Initiate the client
 
-## • With Options
-
-| Key              | Type           |
-| ---------------- | -------------- |
-| `apiKey`         | `string`       |
-| `safemode`       | `boolean`      |
-| `format`         | `string`       |
-| `blacklistFlags` | `string/array` |
-| `lang`           | `string`       |
-
-### • Example
-
-```javascript
-// NOTE:: Params take priority over options so when key is supplied in both, Params will be used.
-const JokeClient = new JokeAPI({ apiKey: 'exampleapikey', safemode: true, format: 'xml' blacklistflags: ['nsfw'], lang: 'de'});
-```
-
-## • Categories & BlacklistFlags
-
-can be given in an array or a string seperated by , + or -
-
-### • Example
-
-```javascript
-const JokeClient = new JokeAPI({ blacklistflags: ['nsfw', 'explicit'] });
-const joke = await JokeClient.getJoke({ categories: 'coding,dark' });
-const joke = await JokeClient.getJoke({ categories: 'coding+dark' });
-const joke = await JokeClient.getJoke({ categories: 'coding-dark' });
-```
-
-## • Get Joke
-
-| Key              | Type           |
-| ---------------- | -------------- |
-| `categories`     | `string/array` |
-| `format`         | `string`       |
-| `blacklistFlags` | `string/array` |
-| `lang`           | `string`       |
-| `idRange`        | `number`       |
-| `contains`       | `string`       |
-| `type`           | `string`       |
-| `amount`         | `number`       |
-
-### • Example
-
-```javascript
-const joke = await JokeClient.getJoke({ categories: ['Coding', 'dark'] });
-
-const joke = await JokeClient.getJoke({ categories: 'Coding,dark' });
-
-// If theres no categories provided it defaults to /any
-const joke = await JokeClient.getJoke();
-```
-
-## • Output example
-
-```json
-{
-  "error": false,
-  "category": "Programming",
-  "type": "twopart",
-  "setup": "Why does no one like SQLrillex?",
-  "delivery": "He keeps dropping the database.",
-  "flags": {
-    "nsfw": false,
-    "religious": false,
-    "political": false,
-    "racist": false,
-    "sexist": false,
-    "explicit": false
-  },
-  "id": 13,
-  "safe": true,
-  "lang": "en"
-}
-```
-
-## • Info
-
-| Key      | Type     |
-| -------- | -------- |
-| `format` | `string` |
-| `lang`   | `string` |
-
-### • Example
-
-```javascript
-const info = await JokeClient.info();
-
-const info = await JokeClient.info({ format: 'text', lang: 'en' });
-```
-
-## • Categories
-
-| Key      | Type     |
-| -------- | -------- |
-| `format` | `string` |
-| `lang`   | `string` |
-
-### • Example
-
-```javascript
-const categories = await JokeClient.categories();
-
-const categories = await JokeClient.categories({ format: 'text', lang: 'en' });
-```
-
-## • Langcode
-
-| Key        | Type     | required |
-| ---------- | -------- | -------- |
-| `format`   | `string` | `false`  |
-| `language` | `string` | `true`   |
-
-### • Example
-
-```javascript
-const langcode = await JokeClient.langcode({ format: 'text', language: 'english' });
-```
-
-## • Languages
-
-| Key      | Type     |
-| -------- | -------- |
-| `format` | `string` |
-
-### • Example
-
-```javascript
-const languages = await JokeClient.languages({ format: 'text' });
-```
-
-## • Flags
-
-| Key      | Type     |
-| -------- | -------- |
-| `format` | `string` |
-| `lang`   | `string` |
-
-### • Example
-
-```javascript
-const flags = await JokeClient.flags();
-
-const flags = await JokeClient.flags({ format: 'text', lang: 'en' });
-```
-
-## • Formats
-
-| Key      | Type     |
-| -------- | -------- |
-| `format` | `string` |
-| `lang`   | `string` |
-
-### • Example
-
-```javascript
-const formats = await JokeClient.formats();
-
-const formats = await JokeClient.formats({ format: 'text', lang: 'en' });
-```
-
-## • Ping
-
-| Key      | Type     |
-| -------- | -------- |
-| `format` | `string` |
-| `lang`   | `string` |
-
-### • Example
-
-```javascript
-const ping = await JokeClient.ping();
-
-const ping = await JokeClient.ping({ format: 'text', lang: 'en' });
-```
-
-## • Submitting
-
-For testing define dry-run as anything
-
-### • Example
-
-```javascript
-const submitSingle = await JokeClient.submit({
-  'dry-run': true,
-  formatVersion: 3,
-  category: 'Misc',
-  type: 'single',
-  joke: 'testing',
-  flags: { nsfw: true, religious: false, political: false, racist: false, sexist: false, explicit: true },
-  lang: 'en',
-});
-
-const submitDouble = await JokeClient.submit({
-  'dry-run': true,
-  formatVersion: 3,
-  category: 'misc',
-  type: 'twopart',
-  setup: 'Setup',
-  delivery: 'Delivering',
-  flags: { nsfw: true, religious: false, political: false, racist: false, sexist: false, explicit: true },
-  lang: 'en',
-});
-```
-
 ## • Inspiration
@@ -265,0 +50,0 @@

src/helpers/constants.js

 /**
+ * @kind constant
  * @description The base url for the Joke API
@@ -7,2 +8,3 @@ */
 /**
+ * @kind constant
  * @description The host of the Joke API
@@ -13,2 +15,3 @@ */
 /**
+ * @kind constant
  * @description The current version for the JokeAPI API
@@ -19,2 +22,3 @@ */
 /**
+ * @kind constant
  * @description The current categories avaliable
@@ -37,2 +41,3 @@ */
 /**
+ * @kind constant
  * @description The current blacklist flags avaliable
@@ -43,2 +48,3 @@ */
 /**
+ * @kind constant
  * @description The current formats avaliable
@@ -49,2 +55,3 @@ */
 /**
+ * @kind constant
  * @description The current joke outputs avaliable
@@ -55,2 +62,3 @@ */
 /**
+ * @kind constant
  * @description Current max amount of jokes
@@ -60,2 +68,2 @@ */
 
-module.exports = { BASE, HOST, API_VERSION, CATEGORIES, BLACKLIST_FLAGS, FORMAT, TYPE, AMOUNT_MAX };
+export default { BASE, HOST, API_VERSION, CATEGORIES, BLACKLIST_FLAGS, FORMAT, TYPE, AMOUNT_MAX };

src/helpers/util.js

 /**
- * @param {string|array} data
- * @returns {string}
+ * @typedef {import('../../types').Options} Options
+ * @typedef {import('../../types/params').ExtendedParams} ExtendedParams
+ * @typedef {import('../../types/params').JokeParams} JokeParams
+ * @typedef {import('../../types/params').SubmitJokeParams} SubmitJokeParams
+ * @typedef {import('../../types/params').LangCodeParams} LangCodeParams
  */
+
+/**
+ * @param {string | any[]} data
+ * @return {string}
+ */
 const parseArray = (data) => {
@@ -10,10 +18,13 @@ return Array.isArray(data) ? data.join(',') : data;
 /**
- * @param {object} params
- * @param {object} options
- * @returns {object}
+ * @param {ExtendedParams} params
+ * @param {Options} options
+ *
+ * @return {{parsedParams: ExtendedParams, wildcard: string}}
  */
 const parseParams = (params, options) => {
+  /** @type {ExtendedParams} */
   const parsedParams = {};
   let wildcard;
 
+  // @ts-ignore ignore all code paths must return value
   if (!params || !options) return;
@@ -24,7 +35,12 @@ Object.assign(parsedParams, params);
   if ('safe-mode' in options) parsedParams['safe-mode'] = 'safe-mode';
-  if ('safe-mode' in params)
-    params['safe-mode'] ? (parsedParams['safe-mode'] = 'safe-mode') : delete parsedParams['safe-mode'];
+  if ('safe-mode' in params) {
+    if (params['safe-mode']) parsedParams['safe-mode'] = 'safe-mode';
+    else delete parsedParams['safe-mode'];
+  }
 
   if ('format' in options) parsedParams.format = options.format;
-  if ('format' in params) params.format === 'json' ? delete parsedParams.format : (parsedParams.format = params.format);
+  if ('format' in params) {
+    if (params.format === 'json') delete parsedParams.format;
+    else parsedParams.format = params.format;
+  }
 
@@ -53,3 +69,2 @@ if ('blacklistFlags' in params || 'blacklistFlags' in options)
 };
-
-module.exports = { parseArray, parseParams };
+export default { parseArray, parseParams };

src/index.js

@@ -1,6 +0,16 @@
-const fetch = require('node-fetch');
+/**
+ * @typedef {import('../types').Options} Options
+ * @typedef {import('../types').RequestOptions} RequestOptions
+ * @typedef {import('../types/params').BaseParams} Params
+ * @typedef {import('../types/params').JokeParams} JokeParams
+ * @typedef {import('../types/params').SubmitJokeParams} SubmitJokeParams
+ * @typedef {import('../types/params').LangCodeParams} LangCodeParams
+ * @typedef {import('../types/params').ExtendedParams} ExtendedParams
+ */
 
-const Constants = require('./helpers/constants');
-const Util = require('./helpers/util');
+import fetch from 'isomorphic-unfetch';
 
+import Constants from './helpers/constants.js';
+import Util from './helpers/util.js';
+
 /**
@@ -19,8 +29,3 @@ * @class JokeAPI
   /**
-   * @param {object} options
-   * @param {string} options.apiKey OPTIONAL:: Authorization key
-   * @param {boolean} options.safemode Turn on safemode DEFAULT:: off
-   * @param {string} options.format Change global format DEFAULT:: JSON
-   * @param {string|array} options.blacklistFlags Globally blacklist certain flags, Check JokeClient.BLACKLIST_FLAGS or https://jokeapi.dev/ for flag names
-   * @param {string} options.lang Globally change language DEFAULT:: en
+   * @param {Options} options
    */
@@ -32,13 +37,8 @@ constructor(options = {}) {
   /**
-   * @description This endpoint is the one you want to call to get a joke.
-   * @function getJoke()
-   * @param {string|array} params.categories
-   * @param {string} params.format
-   * @param {string|array} params.blacklistFlags
-   * @param {string} params.lang
-   * @param {string} params.idRange i.e. 10-25
-   * @param {string} params.contains
-   * @param {string} params.type
-   * @param {number} params.amount i.e. 5 MAX:: 10
-   * @returns {ReturnObject}
+   * @function getJoke
+   * @description Returns a joke in supplied categories or any
+   *
+   * @param {JokeParams} params
+   *
+   * @return {Promise<Object>}
    */
@@ -54,7 +54,8 @@ getJoke(params = {}) {
   /**
+   * @function info
    * @description This endpoint provides a lot of information about JokeAPI and its jokes
-   * @function info()
-   * @param {string} params.format
-   * @param {string} params.lang
-   * @returns {ReturnObject}
+   *
+   * @param {Params} params
+   *
+   * @return {Object}
    */
@@ -67,8 +68,8 @@ info(params = {}) {
   /**
+   * @function categories
    * @description This endpoint returns a list / an array of all available joke categories,
    * all available category aliases and a 13-character UNIX timestamp.
-   * @function categories()
-   * @param {string} params.format
-   * @param {string} params.lang
-   * @returns {ReturnObject}
+   * @param {Params} params
+   *
+   * @return {Object}
    */
@@ -81,11 +82,12 @@ categories(params = {}) {
   /**
+   * @function langcode
    * @description This endpoint returns the ISO 639-1 language code of a provided language.
    * It is searched with a fuzzy search, so you just have to provide the approximate language name.
    * The resulting language code is to be used in fetching and submitting jokes in different languages.
-   * @function langcode()
-   * @param {string} params.format
-   * @param {string} params.language
-   * @returns {ReturnObject}
+   * 
+   * @param {LangCodeParams} params
+
+   * @return {Object}
    */
-  langcode(params = {}) {
+  langcode(params) {
     if (!params.language) return { error: true, message: 'You need to supply a language' };
@@ -98,8 +100,9 @@
   /**
+   * @function languages
    * @description This endpoint returns lists of supported languages in jokes and supported languages in system messages (error messages).
    * Also, it returns a list of possible ISO 639-1 language codes you can use to submit a joke or add a translation.
-   * @function languages()
-   * @param {string} params.format
-   * @param {string} params.lang
-   * @returns {ReturnObject}
+   *
+   * @param {Params} params
+   *
+   * @return {Object}
    */
@@ -112,7 +115,8 @@ languages(params = {}) {
   /**
+   * @function flags
    * @description This endpoint returns a list / an array of all available blacklist flags and a 13-character UNIX timestamp.
-   * @function flags()
-   * @param {string} params.format
-   * @param {string} params.lang
-   * @returns {ReturnObject}
+   *
+   * @param {Params} params
+   *
+   * @return {Object}
    */
@@ -125,7 +129,8 @@ flags(params = {}) {
   /**
+   * @function formats
    * @description This endpoint returns a list / an array of all available response formats and a 13-character UNIX timestamp.
-   * @function formats()
-   * @param {string} params.format
-   * @param {string} params.lang
-   * @returns {ReturnObject}
+   * 
+   * @param {Params} params
+
+   * @return {Object}
    */
@@ -138,8 +143,9 @@ formats(params = {}) {
   /**
+   * @function ping
    * @description This endpoint returns a parameter named "ping" that contains the word "Pong!"
    * and a 13-character UNIX timestamp. It is intended for external uptime monitoring
-   * @function ping()
-   * @param {string} params.format
-   * @param {string} params.lang
-   * @returns {ReturnObject}
+   * 
+   * @param {Params} params
+
+   * @return {Object}
    */
@@ -152,6 +158,8 @@ ping(params = {}) {
   /**
+   * @function endpoints
    * @description This endpoint returns a list / an array of all available endpoints, their usage (method, url and supported parameters) and a short description each.
-   * @function endpoints()
-   * @param {string} params.format
-   * @returns {ReturnObject}
+   * 
+   * @param {Params} params
+
+   * @return {Object}
    */
@@ -164,20 +172,12 @@ endpoints(params = {}) {
   /**
+   * @function endpoints
    * @description This endpoint returns a list / an array of all available endpoints, their usage (method, url and supported parameters) and a short description each.
-   * @function endpoints()
-   * @param {number} params.formatVersion
-   * @param {string} params.category
-   * @param {string} params.type
-   * @param {string} params.joke
-   * @param {object} params.flags
-   * @param {boolean} params.flags.nsfw
-   * @param {boolean} params.flags.religious
-   * @param {boolean} params.flags.political
-   * @param {boolean} params.flags.racist
-   * @param {boolean} params.flags.sexist
-   * @param {boolean} params.flags.explicit
-   * @param {lang} params.lang
-   * @returns {ReturnObject}
+   *
+   * @param {SubmitJokeParams} params
+   *
+   * @return {Object}
    */
-  submit(params = {}) {
+  submit(params) {
     const url = this._buildUrl('submit', undefined, params['dry-run']);
+
     // Remove dry run from body
@@ -189,16 +189,10 @@ delete params['dry-run'];
   /**
+   * @function _buildUrl
    * @description Builds the url.
-   * @function _buildUrl()
+   *
    * @param {string} endpoint
-   * @param {string|array} params.categories
-   * @param {string} params.format
-   * @param {string|array} params.blacklistFlags
-   * @param {string} params.lang
-   * @param {number} params.idRange
-   * @param {string} params.contains
-   * @param {string} params.type
-   * @param {number} params.amount
-   * @param {string} params.lang
-   * @param {string} method
-   * @returns {string}
+   * @param {ExtendedParams} params
+   * @param {Boolean } [testRun]
+   *
+   * @return {string}
    */
@@ -219,15 +213,9 @@ _buildUrl(endpoint, params, testRun) {
   /**
+   * @function _buildQuery
    * @description Formats object into http query
-   * @function _buildQuery()
+   *
    * @param {string} url
-   * @param {string|array} params.categories
-   * @param {string} params.format
-   * @param {string|array} params.blacklistFlags
-   * @param {string} params.lang
-   * @param {number} params.idRange
-   * @param {string} params.contains
-   * @param {string} params.type
-   * @param {number} params.amount
-   * @param {string} params.lang
-   * @returns {string}
+   * @param {ExtendedParams} query
+   *
+   * @return {string}
    */
@@ -237,3 +225,3 @@ _buildQuery(url, query) {
       .map((pair) => {
-        // On some queries there is no value i.e. safemode; so we jsut use the key name
+        // On some queries there is no value i.e. safemode; so we just use the key name
         return pair[0] === pair[1] ? pair[0] : pair.map(encodeURIComponent).join('=');
@@ -247,8 +235,9 @@ })
   /**
+   * @function _request
    * @description Sends request to api then returns output in requested format
-   * @function _request()
+   *
    * @param {string} url
-   * @param {object} options
-   * @param {string} options.method
-   * @returns {object}
+   * @param {RequestOptions} [options]
+   *
+   * @return {Promise<any>}
    */
@@ -263,3 +252,6 @@ async _request(url, options) {
 
+    // @ts-ignore TODO :: Fix this
     const formattedUrl = new URL(url);
+
+    // @ts-ignore TODO :: Fix this
     const urlSearchParams = new URLSearchParams(formattedUrl.search);
@@ -283,2 +275,2 @@ const format = urlSearchParams.get('format');
 
-module.exports = JokeAPI;
+export default JokeAPI;

No alert changes

Improved metrics

Number of package files

10

increased by42.86%

Lines of code

403

increased by22.87%

Is type module

Yes

Worsened metrics

Total package byte prevSize

17987

decreased by-13.81%

Dev dependency count

14

increased by100%

Number of lines in readme file

52

decreased by-80.52%

Dependency changes

• + Addedisomorphic-unfetch@^3.1.0

• + Addedisomorphic-unfetch@3.1.0(transitive)

• + Addedunfetch@4.2.0(transitive)

• - Removednode-fetch@^2.6.1