Completed Initial Source for 2.0.0

Author: Elitezen

CHANGELOG.md

@@ -1,4 +1,13 @@
 # Changelog
 
+# 2.0.0 
+- The library received a massive rework through many quality of life changes. 
+
+- 'Static' and 'Pretty' category names are no more, developers will no longer have to worry about converting through these formats. 
+
+- All QuestionOption option types now have respective enums to work with.
+
+- `Category` is now just a class with various static methods for working with categories.
+
 ## 1.0.2
 - Switched from https module to Node Fetch API

README.md

@@ -0,0 +1,147 @@
+![OpenTriviaDB](https://i.imgur.com/QBhF5aY.png)
+
+![version](https://img.shields.io/npm/v/open-trivia-db)
+![downloads](https://img.shields.io/npm/dm/open-trivia-db)
+![minisize](https://img.shields.io/bundlephobia/min/open-trivia-db)
+![types](https://img.shields.io/npm/types/open-trivia-db)
+
+`open-trivia-db` is a small and simple library for interacting with the [OpenTDB](https://opentdb.com/) API.
+
+Live Demo: https://replit.com/@Elitezenv/open-trivia-db-DEMO?v=1
+
+## Updates (2.0.0)
+- The library received a massive rework through many quality of life changes. 
+
+- 'Static' and 'Pretty' category names are no more, developers will no longer have to worry about converting through these formats. 
+
+- All QuestionOption option types now have respective enums to work with.
+
+- `Category` is now just a class with various static methods for working with categories.
+
+
+## Example Code
+```js
+import { getQuestions, CategoryNames } from "open-trivia-db";
+
+const questions = await getQuestions({
+  amount: 10,
+  category: CategoryNames.Animals,
+  difficulty: QuestionDifficulties.Easy,
+})
+```
+
+## Result
+```js
+[
+  {
+    value: 'How many teeth does an adult rabbit have?',
+    category: { id: 27, name: 'Animals', getData: [Function: getData] },
+    type: 'multiple',
+    difficulty: 'easy',
+    correctAnswer: '28',
+    incorrectAnswers: [ '30', '26', '24' ],
+    allAnswers: [ '24', '28', '30', '26' ],
+    checkAnswer: [Function: checkAnswer]
+  }
+  ...
+]
+```
+
+# Guide
+## Getting Questions
+
+Questions can be fetched via the `getQuestions()` function by supplying options such as `amount`, `category`, `difficulty`, `type`, `session` and `encode`.
+
+`type`: The kind of questions, such as multiple choice (`"multiple"`) or true/false (`"boolean"`).
+
+`session`: A session instance or session token. [Learn about sessions](#sessions)
+
+`encode`: The encoding of the questions such as `base64`, `urlLegacy`, `url3968` or `none` which is the default.
+
+You can apply options via their respective enums.
+
+The result will be an array of questions.
+
+```js
+import { 
+  CategoryNames, 
+  QuestionDifficulties, 
+  QuestionTypes, 
+  QuestionEncodings 
+} from "open-trivia-db";
+
+getQuestions({
+  amount: 50,
+  category: CategoryNames["Entertainment: Japanese Anime & Manga"],
+  difficulty: QuestionDifficulties.Hard,
+  type: QuestionTypes.Multiple,
+  encode: QuestionEncodings.None
+})
+```
+
+## Getting Categories and Category Data
+<hr>
+
+A category resolvable can either be a category name or id. Category id's range from 9-32 inclusive, for there are 23 categories.
+
+To jump between resolvables, use `Category.idByName()` and `Category.nameById()`.
+
+```js
+import { Category, CategoryNames } from "open-trivia-db";
+
+Category.idByName('Art'); // 25
+Category.nameById(25); // 'Art'
+```
+
+### Getting a Category's Data
+Use `Category.getCategory()` to get a category's data such as name, id, and question counts.
+
+```js
+import { Category, CategoryNames } from "open-trivia-db"
+
+Category.getCategory(CategoryNames.Geography)
+  .then(console.log)
+```
+
+```js
+{
+  id: 22,
+  name: 'Geography',
+  questionCount: { 
+    total: 275, 
+    easy: 80, medium: 139, hard: 56 
+  }
+}
+```
+
+You can also complete a category's data through a question via `Question.category.getData()`
+
+```js
+const targetQuestion = questions[0] // from getQuestions()
+
+targetQuestion.category.getData()
+  .then(console.log)
+```
+
+## Sessions
+A session ensures you are not supplied a question more than once throughout it's lifetime.
+
+Initialize a session and supply the instance into `getQuestions()`. Make sure to await or resolve `Session.start()`.
+```js
+import { Session } from "open-trivia-db"
+
+const mySession = new Session();
+await mySession.start();
+
+getQuestions({
+  session: mySession
+})
+```
+
+`getQuestions()` will return an error once your session has served every single question in OpenTDB. Don't worry, theres thousands of questions! You will likely never come accross a session's end. However, if you wish to reset your session, use `Session.reset()`.
+
+```js
+await mySession.reset();
+```
+
+<hr>

dist/index.d.ts

@@ -1 +1,11 @@
-export {};
+import Category from "./src/classes/Category";
+import Constructor from "./src/classes/Constructor";
+import OpenTDBError from "./src/classes/OpenTDBError";
+import Session from "./src/classes/Session";
+import Util from "./src/classes/Util";
+import getCategory from "./src/functions/getCategory";
+import getQuestions from "./src/functions/getQuestions";
+import { CategoryNames, QuestionDifficulties, QuestionEncodings, QuestionTypes, Routes } from "./src/typings/enums";
+import type { CategoryData, ErrorResponse, MinifiedCategoryData, Question, QuestionOptions, RawQuestion, RawCategoryResponse, RawQuestionResponse, RawSessionStartResponse } from "./src/typings/interfaces";
+import type { CategoryNameType, CategoryResolvable, Dictionary, ErrorCode, QuestionDifficultyType, QuestionEncodingType, QuestionTypeType, ResponseCode, SimpleDictionary, ExtendedDictionary } from "./src/typings/types";
+export { Category, Constructor, OpenTDBError, Session, Util, getCategory, getQuestions, CategoryNames, QuestionDifficulties, QuestionEncodings, QuestionTypes, Routes, CategoryData, ErrorResponse, MinifiedCategoryData, Question, QuestionOptions, RawQuestion, RawCategoryResponse, RawQuestionResponse, RawSessionStartResponse, CategoryNameType, CategoryResolvable, Dictionary, ErrorCode, QuestionDifficultyType, QuestionEncodingType, QuestionTypeType, ResponseCode, SimpleDictionary, ExtendedDictionary };

dist/index.js

@@ -1,12 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Routes = exports.QuestionTypes = exports.QuestionEncodings = exports.QuestionDifficulties = exports.CategoryNames = exports.getQuestions = exports.getCategory = exports.Util = exports.Session = exports.OpenTDBError = exports.Constructor = exports.Category = void 0;
 const Category_1 = require("./src/classes/Category");
-async function test() {
-    try {
-        await Category_1.default.getCategory(8);
-    }
-    catch (err) {
-        throw err;
-    }
-}
-test();
+exports.Category = Category_1.default;
+const Constructor_1 = require("./src/classes/Constructor");
+exports.Constructor = Constructor_1.default;
+const OpenTDBError_1 = require("./src/classes/OpenTDBError");
+exports.OpenTDBError = OpenTDBError_1.default;
+const Session_1 = require("./src/classes/Session");
+exports.Session = Session_1.default;
+const Util_1 = require("./src/classes/Util");
+exports.Util = Util_1.default;
+const getCategory_1 = require("./src/functions/getCategory");
+exports.getCategory = getCategory_1.default;
+const getQuestions_1 = require("./src/functions/getQuestions");
+exports.getQuestions = getQuestions_1.default;
+const enums_1 = require("./src/typings/enums");
+Object.defineProperty(exports, "CategoryNames", { enumerable: true, get: function () { return enums_1.CategoryNames; } });
+Object.defineProperty(exports, "QuestionDifficulties", { enumerable: true, get: function () { return enums_1.QuestionDifficulties; } });
+Object.defineProperty(exports, "QuestionEncodings", { enumerable: true, get: function () { return enums_1.QuestionEncodings; } });
+Object.defineProperty(exports, "QuestionTypes", { enumerable: true, get: function () { return enums_1.QuestionTypes; } });
+Object.defineProperty(exports, "Routes", { enumerable: true, get: function () { return enums_1.Routes; } });

index.ts

@@ -1,11 +1,25 @@
 import Category from "./src/classes/Category";
+import Constructor from "./src/classes/Constructor";
+import OpenTDBError from "./src/classes/OpenTDBError";
+import Session from "./src/classes/Session";
+import Util from "./src/classes/Util";
 
-async function test() {
-  try {
-    await Category.getCategory(8)
-  } catch (err) {
-    throw err;
-  }
-}
+import getCategory from "./src/functions/getCategory";
+import getQuestions from "./src/functions/getQuestions";
 
-test();
+import { CategoryNames, QuestionDifficulties, QuestionEncodings, QuestionTypes, Routes } from "./src/typings/enums";
+import type { CategoryData, ErrorResponse, MinifiedCategoryData, Question, QuestionOptions, RawQuestion, RawCategoryResponse, RawQuestionResponse, RawSessionStartResponse } from "./src/typings/interfaces";
+import type { CategoryNameType, CategoryResolvable, Dictionary, ErrorCode, QuestionDifficultyType, QuestionEncodingType, QuestionTypeType, ResponseCode, SimpleDictionary, ExtendedDictionary } from "./src/typings/types";
+
+export {
+  Category,
+  Constructor,
+  OpenTDBError,
+  Session,
+  Util,
+  getCategory,
+  getQuestions,
+  CategoryNames, QuestionDifficulties, QuestionEncodings, QuestionTypes, Routes,
+  CategoryData, ErrorResponse, MinifiedCategoryData, Question, QuestionOptions, RawQuestion, RawCategoryResponse, RawQuestionResponse, RawSessionStartResponse,
+  CategoryNameType, CategoryResolvable, Dictionary, ErrorCode, QuestionDifficultyType, QuestionEncodingType, QuestionTypeType, ResponseCode, SimpleDictionary, ExtendedDictionary
+}

src/Classes/Category.ts

@@ -3,28 +3,72 @@ import type { CategoryNameType } from "../typings/types";
 import getCategory from "../functions/getCategory";
 import Util from "./Util";
 
+/**
+ * @class Class for anything trivia category related.
+ */
 export default class Category {
-  static allNames = Object.keys(CategoryNames).filter((key) => isNaN(+key));
+  /**
+   * An array of all category names. Use `Category.random()` for a random pick.
+   */
+  static allNames: CategoryNameType[] = Object.keys(CategoryNames).filter(
+    (key) => isNaN(+key)
+  ) as CategoryNameType[];
 
+  /**
+   * Decodes a URLLegacy, URL3968 or Base64 category name.
+   * @param {string} str string to decode.
+   * @returns {string} The decoded category name.
+   */
+  static decodeEncodedCategoryName(str: string): CategoryNameType | null {
+    return (
+      [
+        Util.decodeBase64<CategoryNameType>(str),
+        Util.decodeUrl3968<CategoryNameType>(str),
+        Util.decodeUrlLegacy<CategoryNameType>(str),
+      ].find((str) => Category.allNames.includes(str)) || null
+    );
+  }
+
+  /**
+   * Fetches a trivia category's data. Duplicate of `getCategory()`.
+   * @param {CategoryResolvable} arg An argument resolving to a trivia category.
+   * @returns {Promise<CategoryData>} The data of the category.
+   */
   static getCategory = getCategory;
 
-  static idByName(name: string) {
+  /**
+   * Returns a category id when given it's name.
+   * @param {CategoryNameType} name The name of the category.
+   * @returns {number | null} The id if resolvable.
+   */
+  static idByName(name: CategoryNameType): number | null {
     const id = Category.allNames.indexOf(name);
     return id > -1 ? id + 9 : null;
   }
 
+  /**
+   * Returns a category name when given it's id.
+   * @param {number} id The id of the category.
+   * @returns {CategoryNameType | null} The name if resolvable.
+   */
   static nameById(id: number): CategoryNameType | null {
     const name = Category.allNames[id - 9];
     return name !== undefined ? (name as CategoryNameType) : null;
   }
 
-  static decodeEncodedCategoryName(str: string): CategoryNameType | null {
-    return (
-      [
-        Util.decodeBase64<CategoryNameType>(str),
-        Util.decodeUrl3968<CategoryNameType>(str),
-        Util.decodeUrlLegacy<CategoryNameType>(str),
-      ].find((str) => Category.allNames.includes(str)) || null
-    );
+  /**
+   * Picks a random category name or id.
+   * @param {'name' | 'id'} resolvableType The kind of resolvable to return (default `'name'`).
+   * @returns {CategoryNameType | number} A random category id or name.
+   */
+  static random(resolvableType: "name"): CategoryNameType;
+  static random(resolvableType: "id"): number;
+  static random(resolvableType?: "name" | "id"): CategoryNameType | number {
+    if (resolvableType === undefined) resolvableType = "name";
+
+    const name =
+      Category.allNames[Math.floor(Math.random() * Category.allNames.length)];
+    if (resolvableType === "id") return Category.idByName(name)!;
+    return name;
   }
-}
+}

src/Classes/Constructor.ts

@@ -3,10 +3,14 @@ import type {
   Question,
   RawCategoryResponse,
   RawQuestion,
-} from "../typings/interface";
+} from "../typings/interfaces";
 import Category from "./Category";
 import Util from "./Util";
 
+/**
+ * @class Class for transforming raw API data to developer friendly data.
+ * @private
+ */
 export default class Constructor {
   static category(rawCategoryData: RawCategoryResponse): CategoryData {
     return {

src/Classes/OpenTDBError.ts

@@ -1,8 +1,11 @@
-import type { ErrorResponse } from "../typings/interface";
+import type { ErrorResponse } from "../typings/interfaces";
 
+/**
+ * @class OpenTDB error constructor
+ * @private
+ */
 export default class OpenTDBError extends TypeError {
   constructor(error: ErrorResponse) {
-    console.log(error);
     super(error.text);
     this.name = `OpenTDBError [${error.header}]`;
   }