Merge pull request #48 from Sv443-Network/version/1.17

SvCoreLib.d.ts

@@ -18,6 +18,8 @@ import { Connection, QueryOptions } from "mysql";
 import { SelectionMenuSettings, SelectionMenuResult, SelectionMenuLocale, SelectionMenuOption } from "./src/types/SelectionMenu";
 
 
+//#MARKER types
+
 /**
  * Describes an object that is JSON-compatible, aka doesn't contain self- / circular references or non-primitive JS properties  
  * [Source](https://github.com/microsoft/TypeScript/issues/1897#issuecomment-338650717)
@@ -26,13 +28,16 @@ export type JSONCompatible =  boolean | number | string | null | JSONArray | JSO
 interface JSONMap { [key: string]: JSONCompatible; }
 interface JSONArray extends Array<JSONCompatible> {}
 
-/**
- * Describes a value that has a `.toString()` method, meaning it can be converted to a string
- */
-export interface Stringifiable {
+/** Describes a value that either is a string itself or has a `.toString()` method, meaning it can be converted to a string */
+export type Stringifiable = string | {
     toString(): string;
 }
 
+/** Describes any class reference that is constructable/newable */
+export type Newable<T> = { new(...args: any[]): T; };
+/** Describes any value that is a constructable/newable class reference or a function (ES5 classes and abstract ES6 classes) */
+export type AnyClass<T> = Newable<T> | (Function & { prototype: T });
+
 /**
  * ![icon](https://sv443.net/resources/images/svcorelib_tiny.png)  
  * 
@@ -47,15 +52,13 @@ export interface Stringifiable {
  *   
  * If you like this library please consider [supporting me ❤](https://github.com/sponsors/Sv443)
  * @author [Sv443](https://github.com/Sv443)
- * @version 1.15.0 [(changelog)](https://github.com/Sv443-Network/SvCoreLib/blob/master/changelog.md#readme)
- * @license [MIT](https://sv443.net/LICENSE)
  * @copyright © 2020 Sv443 Network
+ * @license [MIT](https://sv443.net/LICENSE)
  * @module svcorelib
  */
 declare module "svcorelib" {
-    //#MARKER functions
-
 
+    //#MARKER functions
 
     //#SECTION Miscellaneous
 
@@ -81,6 +84,13 @@ declare module "svcorelib" {
      */
     function isArrayEmpty<T>(array: T[]): boolean | number;
 
+    /**
+     * 🔹 Checks if the passed value is a reference to a class 🔹
+     * @param val Value to check
+     * @since 1.17.0
+     */
+    function isClass<T>(val: any): val is AnyClass<T>;
+
     /**
      * 🔹 Sends a red console message and optionally exits the process with an optional status code. 🔹
      * @param cause The cause of the error
@@ -117,9 +127,19 @@ declare module "svcorelib" {
      */
     function allOfType<T>(array: T[], type: JSPrimitiveTypeName): boolean;
 
+    /**
+     * 🔹 Checks if each item of an array is an instance of the passed class reference. 🔹
+     * @param array Array that should be checked
+     * @param Class Reference to the class to be checked. Don't pass an actual instance of that class!
+     * @returns Returns true if all items are an instance of `Class`, else returns false
+     * @throws Throws a TypeError if the parameters are invalid
+     * @since 1.17.0
+     */
+    function allInstanceOf<T>(array: T[], Class: AnyClass<T>): boolean;
+
     /**
      * 🔹 Reserializes a JSON-compatible object. This means it copies the value of an object and loses the internal reference to it.  
-     * Using an object that contains special JavaScript classes or a circular structure will result in unexpected behavior. 🔹
+     * Using an object that contains special JavaScript classes or circular objects will throw an error. 🔹
      * @param obj The object you want to reserialize - if this is not of type `object`, you will just get the original value back
      * @param immutable Set this to `true` if you want to make the returned object immutable (its properties can't be modified anymore)
      * @returns Returns the reserialized object or the unmodified original value if it is not of type `object`
@@ -196,6 +216,30 @@ declare module "svcorelib" {
      */
     function byteLength(str: string): number;
 
+    /**
+     * 🔹 Returns both halves of an array as a tuple. 🔹
+     * @param array An array of any size, with any values contained inside
+     * @returns Returns a tuple with two array entries, being the first and second half of the array
+     * @since 1.15.0
+     * @example ```js
+     * const [first, second] = halves([ 1, 2, 3, 4, 5 ]);
+     * 
+     * console.log(first);  // [ 1, 2, 3 ]
+     * console.log(second); // [ 4, 5 ]
+     * ```
+     */
+    function halves<T>(array: T[]): [first: T[], second: T[]];
+
+    /**
+     * 🔹 Inserts values into a percent-formatted string.  
+     * If there are no insertion marks, this function returns the unmodified input string. 🔹
+     * @param str A string containing numbered insertion marks (%1, %2, ..., %10, %11, ...)
+     * @param values [Rest parameter] The values to insert into the string - All values that are not of type `string` will be attempted to be converted using their method `.toString()`
+     * @throws Throws a "TypeError" if the parameter `str` is not a string or if one of the values could not be converted to a string
+     * @since 1.12.0
+     */
+    function insertValues(str: string, ...values: (string | Stringifiable)[]): string;
+
     //#SECTION randomization
 
     /**
@@ -243,41 +287,33 @@ declare module "svcorelib" {
     /**
      * 🔹 Chooses a random item in an array and returns it 🔹
      * @param array An array of any size, with any values contained inside
-     * @returns Returns a random item of the provided array
+     * @returns Returns a random item of the provided array. Returns undefined if the array is empty.
      * @since 1.9.4
      */
-    function randomItem<T>(array: T[]): T;
+    function randomItem<T>(array: T[]): T | undefined;
 
     /**
-     * 🔹 Removes duplicate items in an array 🔹
-     * @param array An array with any values
-     * @since 1.9.0
+     * 🔹 Chooses a random item in an array and returns it, along with its index in the array. 🔹
+     * @param array An array of any size, with any values contained inside
+     * @returns Returns a tuple array with two entries. First entry is the randomly chosen item, second entry is the index of the random item. Returns undefined if the array is empty.
+     * @since 1.17.0
      */
-    function removeDuplicates<T>(array: T[]): T[];
+    function randomItemIndex<T>(array: T[]): [item?: T, index?: number];
 
     /**
-     * 🔹 Returns both halves of an array as a tuple. 🔹
+     * 🔹 Chooses a random item in an array and returns it. Mutates the original array so the chosen item is no longer contained! 🔹
      * @param array An array of any size, with any values contained inside
-     * @returns Returns a tuple with two array entries, being the first and second half of the array
-     * @since 1.15.0
-     * @example ```js
-     * const [first, second] = halves([ 1, 2, 3, 4, 5 ]);
-     * 
-     * console.log(first);  // [ 1, 2, 3 ]
-     * console.log(second); // [ 4, 5 ]
-     * ```
+     * @returns Returns the randomly chosen item. Returns undefined if the array is empty.
+     * @since 1.17.0
      */
-    function halves<T>(array: T[]): [first: T[], second: T[]];
+    function takeRandomItem<T>(array: T[]): T | undefined;
 
     /**
-     * 🔹 Inserts values into a percent-formatted string.  
-     * If there are no insertion marks, this function returns the unmodified input string. 🔹
-     * @param str A string containing numbered insertion marks (%1, %2, ..., %10, %11, ...)
-     * @param values [Rest parameter] The values to insert into the string - All values that are not of type `string` will be attempted to be converted using their method `.toString()`
-     * @throws Throws a "TypeError" if the parameter `str` is not a string or if one of the values could not be converted to a string
-     * @since 1.12.0
+     * 🔹 Removes duplicate items in an array 🔹
+     * @param array An array with any values
+     * @since 1.9.0
      */
-    function insertValues(str: string, ...values: (string | Stringifiable)[]): string;
+    function removeDuplicates<T>(array: T[]): T[];
 
     /**
      * 🔸 Offers a few functions to generate seeded random numbers.  
@@ -593,7 +629,7 @@ declare module "svcorelib" {
     //#SECTION SQL
 
     /**
-     * 🔸 Offers a few functions to interface with a SQL database 🔸
+     * 🔸 Offers functions to interface with a SQL database 🔸
      */
     namespace sql {
         /**
@@ -687,8 +723,6 @@ declare module "svcorelib" {
 
     //#MARKER classes
 
-
-
     //#SECTION ProgressBar
 
     /**
@@ -1045,7 +1079,7 @@ declare module "svcorelib" {
 
     //#SECTION StatePromise
 
-    type PromiseState = "initialized" | "pending" | "fulfilled" | "rejected";
+    type PromiseState = "initialized" | "pending" | "resolved" | "rejected";
 
     /**
      * 🔹 This class is a wrapper for the Promise API.  
@@ -1083,7 +1117,7 @@ declare module "svcorelib" {
          * | :-- | :-- |
          * | `initialized` | The StatePromise instance was created but the `exec()` method wasn't called yet |
          * | `pending` | The promise execution was started but it hasn't been resolved or rejected yet |
-         * | `fulfilled` | Execution was finished and the promise was resolved |
+         * | `resolved` | Execution was finished and the promise was resolved |
          * | `rejected` | Execution was finished but the promise was rejected |
          * @since 1.14.0
          */
@@ -1123,7 +1157,7 @@ declare module "svcorelib" {
         class PatternInvalidError extends SCLError {}
 
         /**
-         * 🔹 This error gets thrown when the terminal that the process runs in doesn't provide an stdin channel 🔹
+         * 🔹 This error gets thrown when the terminal that the process runs in doesn't provide a stdin channel 🔹
          * @since 1.12.0
          */
         class NoStdinError extends SCLError {}
@@ -1135,7 +1169,7 @@ declare module "svcorelib" {
         class InvalidMimeTypeError extends SCLError {}
 
         /**
-         * 🔹 This error gets thrown when a provided SQL connection was not established or errored out 🔹
+         * 🔹 This error gets thrown when a provided SQL connection was not established yet or has ended 🔹
          * @since 1.12.0
          */
         class SqlConnectionNotEstablishedError extends SCLError {}
@@ -1165,7 +1199,7 @@ declare module "svcorelib" {
         /** The name of the author of SvCoreLib */
         let author: string;
         /** People that contributed to SvCoreLib - this is the raw object from package.json */
-        let contributors: object;
+        let contributors: Record<"name" | "url", string>[];
         /** The license of SvCoreLib */
         let license: string;
         /** The URL to SvCoreLib's documentation */
@@ -1178,15 +1212,16 @@ declare module "svcorelib" {
      * 🔹 Use this to add color to your console output 🔹
      * @since 1.8.0
      * @version 1.10.0 Added `rst` to the `fg` and `bg` objects
+     * @version 1.17.0 Removed brightness from `bg` and `fg`, added it to `bgb` and `fgb` instead and renamed `fat` to `bright`
      */
     namespace colors
     {
         /** Resets the color to default */
         let rst: string;
-        let fat: string;
+        let bright: string;
         let blink: string;
 
-        /** Sets the foreground (text) color */
+        /** Sets a dim foreground (text) color */
         namespace fg {
             let black: string;
             let red: string;
@@ -1200,7 +1235,7 @@ declare module "svcorelib" {
             let rst: string;
         }
 
-        /** Sets the background/backdrop color */
+        /** Sets a dim background color */
         namespace bg {
             let black: string;
             let red: string;
@@ -1213,5 +1248,33 @@ declare module "svcorelib" {
             /** Resets the color to default */
             let rst: string;
         }
+
+        /** Sets a bright foreground (text) color */
+        namespace fgb {
+            let black: string;
+            let red: string;
+            let green: string;
+            let yellow: string;
+            let blue: string;
+            let magenta: string;
+            let cyan: string;
+            let white: string;
+            /** Resets the color to default */
+            let rst: string;
+        }
+
+        /** Sets a bright background color */
+        namespace bgb {
+            let black: string;
+            let red: string;
+            let green: string;
+            let yellow: string;
+            let blue: string;
+            let magenta: string;
+            let cyan: string;
+            let white: string;
+            /** Resets the color to default */
+            let rst: string;
+        }
     }
 }

SvCoreLib.js

@@ -13,9 +13,11 @@ module.exports = {
 
     isEmpty:          imp("functions/isEmpty"),
     isArrayEmpty:     imp("functions/isArrayEmpty"),
+    isClass:          imp("functions/isClass"),
     error:            imp("functions/error"),
     allEqual:         imp("functions/allEqual"),
     allOfType:        imp("functions/allOfType"),
+    allInstanceOf:    imp("functions/allInstanceOf"),
     reserialize:      imp("functions/reserialize"),
     readableArray:    imp("functions/readableArray"),
     mapRange:         imp("functions/mapRange"),
@@ -26,6 +28,8 @@ module.exports = {
     clamp:            imp("functions/clamp"),
     randomizeArray:   imp("functions/randomizeArray"),
     randomItem:       imp("functions/randomItem"),
+    randomItemIndex:  imp("functions/randomItemIndex"),
+    takeRandomItem:   imp("functions/takeRandomItem"),
     removeDuplicates: imp("functions/removeDuplicates"),
     halves:           imp("functions/halves"),
     insertValues:     imp("functions/insertValues"),

changelog.md

@@ -1,5 +1,5 @@
 ## SvCoreLib - Changelog
-### Latest version: [1.16.0](#1160)
+### Latest version: [1.17.0](#1170)
 
 
 <br>
@@ -9,6 +9,7 @@
 <br>
 
 > **SvCoreLib**
+> - [1.17.0](#1170)
 > - [1.16.0](#1160)
 > - [1.15.0](#1150)
 > - [1.14.0](#1140)
@@ -44,6 +45,26 @@
 
 <br><br>
 
+## 1.17.0
+- Additions
+    - Added function `allInstanceOf()` to check if all items in an array are an instance of a class
+    - Added function `isClass()` to check if a value is a reference to a class
+    - Added function `randomItemIndex()` to get a random item and its index from an array
+    - Added function `takeRandomItem()` to delete a random item from an array and return it
+    - colors
+        - Added `colors.fgb` and `colors.bgb` for bright colors
+        - Added `dim`, `underscore`, `reverse` and `hidden`
+- Breaking changes
+    - Changed state `fulfilled` to `resolved` in StatePromise
+    - colors
+        - Removed brightness modifier from `colors.fg` and `colors.bg`
+        - Renamed `colors.fat` to `colors.bright`
+- Fixes
+    - Added missing documentation for `allOfType()`
+    - Fixed docs in various places
+
+<br>
+
 ## 1.16.0
 
 - Additions