@grey-ts/types 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -206,6 +206,12 @@ declare namespace GreyHack {
          * If the provided path cannot be resolved, meaning that no file or folder exists, this method will return null.
          *
          * Providing an empty string for the path will result in an error, interrupting the script execution.
+         * @example
+         * const computer = getShell().hostComputer;
+         * const passwd = computer.file("/etc/passwd");
+         * if (passwd) {
+         * 	print(`Content of passwd file\n${passwd.getContent()}`)
+         * }
          */
         file: (path: string) => FileType | null;
     }
@@ -318,21 +324,17 @@ declare namespace GreyHack {
          *
          * Certain limitations apply to file creation: the file name must be alphanumeric and below 128 characters. Creation will fail if there is already a file in place or if permissions are lacking. Additionally, there is a file limit of about 250 in each folder and 3125 files in the computer overall.
          *
-         *
-         *
          * Using this method in an SSH encryption process will cause an error to be thrown, preventing any further script execution.
          */
         touch: (destFolder: string, fileName: string) => true | string;
         /**
-         * Returns a list of the Wi-Fi networks that are available for the provided interface.
+         * Returns an array of the Wi-Fi networks that are available for the provided interface.
          *
-         * Each item in the list is a string containing information on the BSSID, PWR, and ESSID.
+         * Each item in the array is a string containing information on the BSSID, PWR, and ESSID.
          *
          * If the active network card is not a Wi-Fi card, an error will be thrown, preventing any further script execution.
          *
-         * @returns true on success
-         * @returns string with details on failure
-         * @returns null if no matching netDevice can be found
+         * @returns null if no matching netDevice can be found, otherwise the available networks
          */
         wifiNetworks: (netDevice: netDevice) => string[] | null;
     }
@@ -761,12 +763,18 @@ declare namespace GreyHack {
      * }
      */
     function isType<T extends keyof GameTypeMap>(value: any, type: T): value is GameTypeMap[T];
-    /** FOR TRANSPILER ONLY
+    /**
+     * FOR TRANSPILER ONLY
      *
      * Includes the given source to this position. If the file was already transpiled then this does nothing
      *
      * Can be a folder if you want to include all the files inside
-     * @param file The absolute or relative path of the file */
+     *
+     * @param file The absolute or relative path of the file
+     *
+     * @example
+     * include("./commands");
+     */
     function include(file: string): void;
     type LibTypes = {
         "aptclient.so": GreyHack.AptClient;
@@ -1064,7 +1072,25 @@ declare namespace GreyHack {
          *
          * So in case a password does not exist in the game world, the decryption will fail.
          *
-         * On failure, this method will return null. Using this method in an SSH encryption process will cause an error to be thrown, aborting further script execution. */
+         * On failure, this method will return null. Using this method in an SSH encryption process will cause an error to be thrown, aborting further script execution.
+         * @example
+         * const crypto = includeLib("/lib/crypto.so");
+         * if (!isType(crypto, "cryptoLib")) exit("Failed to load crypto.so");
+         *
+         * const computer = getShell().hostComputer;
+         * const passwdFile = computer.file("/etc/passwd");
+         * if (!passwdFile) exit("Failed to get passwd file");
+         *
+         * const lines = passwdFile.getContent()!.split(char(10));
+         * for (const line of lines) {
+         * 	const parsed = line.split(":");
+         * 	const username = parsed[0];
+         * 	const passwordhash = parsed[1];
+         *
+         * 	const password = crypto.decipher(passwordhash);
+         * 	print(`Password for user '${username}' is: ${password}`);
+         * }
+         */
         decipher(hash: string): string | null;
         /** Decrypts the specified file using the provided key.
          *
@@ -1205,22 +1231,43 @@ declare namespace GreyHack {
     }
 }
 interface Math {
+    /** Returns the value of pi to the precision of 6 */
     readonly PI: number;
+    /** Returns the absolute value of number. */
     readonly abs: (value: number) => number;
+    /** Returns the inverse cosine (in radians) of a number. */
     readonly acos: (value: number) => number;
+    /** Returns the inverse sine (in radians) of a number. */
     readonly asin: (value: number) => number;
+    /** Returns the inverse tangent (in radians) of a number. */
     readonly atan: (y: number, x?: number | undefined) => number;
+    /** Returns number rounded up to the integer value of the provided number. */
     readonly ceil: (value: number) => number;
+    /** Returns number rounded down to the integer value of the provided number. */
     readonly floor: (value: number) => number;
+    /** Returns the cosine of a number in radians. */
     readonly cos: (value: number) => number;
+    /** Returns the sine of a number in radians. */
     readonly sin: (value: number) => number;
+    /** Returns the tangent of a number in radians. */
     readonly tan: (value: number) => number;
+    /** Returns the square root of a number. */
     readonly sqrt: (value: number) => number;
-    readonly sign: (value: number) => number;
+    /** Returns 1 or -1 indicating the sign of the value passed or 0 if the value is 0 */
+    readonly sign: (value: number) => -1 | 0 | 1;
+    /** Returns number rounded to the integer value of the provided number. */
     readonly round: (value: number, fixed?: number | undefined) => number;
+    /** Returns a random number between 0 and 1. Optionally a seed number can be provided. */
     readonly random: (seed?: number | undefined) => number;
+    /**
+     * Returns the natural logarithm of a number.
+     *
+     * By default, the base is 10. Optionally the base can be changed.
+     */
     readonly log: (value: number, base?: number | undefined) => number;
+    /** Returns the smallest number of the given values */
     readonly min: (...values: number[]) => number;
+    /** Returns the largest number of the given values */
     readonly max: (...values: number[]) => number;
 }
 declare var Math: Math;
@@ -1430,17 +1477,69 @@ interface String {
     indexOf(value: string, offset?: number): number | null;
     indexes(): number[];
     insert(index: number, value: string): string;
-    isMatch(pattern: string | RegExp, regexOptions?: string): number;
-    lastIndexOf(value: string): number;
-    lower(): string;
+    /**
+     * Uses regular expression to check if a string matches a certain pattern.
+     *
+     * If the pattern is empty, the provided {@link https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-options|regexOptions} are invalid, or if the regular expression times out, an error will be thrown, preventing further script execution.
+     */
+    isMatch(pattern: string | RegExp, regexOptions?: string): boolean;
+    /** Returns the last occurrence of a substring in the string. */
+    lastIndexOf(searchString: string): number;
+    /** Converts all the alphabetic characters in a string to lowercase. */
+    toLowerCase(): string;
+    /** Converts all the alphabetic characters in a string to uppercase. */
+    toUpperCase(): string;
+    /**
+     * Returns an object with all search results for the provided regular expression.
+     *
+     * Each key contains the index and the value contains the matching string.
+     *
+     * If the pattern is empty, the provided {@link https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-options|regexOptions} are invalid, or if the regular expression times out, an error will be thrown, preventing further script execution.
+     */
     matches(pattern: string | RegExp, regexOptions?: string): Record<number, string>;
+    /**
+     * Returns a new string with the provided value removed
+     * @example
+     * const myString = "I will not eat an ice cream!";
+     * const newString = myString.remove("not ");
+     * print(newString); // Prints "I will eat an ice cream!"
+     */
     remove(value: string): string;
+    /**
+     * Returns a string with the replaced content by using regular expressions.
+     *
+     * If the pattern is empty, the provided {@link https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-options|regexOptions} are invalid or if the regular expression times out, an error will be thrown, preventing further script execution.
+     *
+     * @example
+     * const myString = "I am now online";
+     * const newString = myString.replace("online", "offline");
+     * print(newString); // Prints "I am now offline"
+     */
     replace(pattern: string | RegExp, newValue: string, regexOptions?: string): string;
+    /**
+     * Returns an array where each item is a segment of the string, separated by the provided separator string.
+     *
+     * This method uses regular expressions for matching, so remember to escape special characters such as dots.
+     *
+     * In case the pattern is empty, the provided {@link https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-options|regexOptions} are invalid, or the regular expression times out, an error will be thrown, preventing further script execution.
+     *
+     * @example
+     * const csvString = "cat,turtle,dog,mouse";
+     * const animals = csvString.split(",");
+     * print(animals); // Prints ["cat", "turtle", "dog", "mouse"]
+     */
     split(pattern: string | RegExp, regexOptions?: string): string[];
+    /**
+     * Returns a number which is parsed from the string as an integer.
+     *
+     * In case the string is not numeric it will return the original string.
+     */
     toInt(): string | number;
+    /** Removes the leading and trailing white space and line terminator characters from a string. */
     trim(): string;
-    upper(): string;
+    /** Returns a number which is parsed from the string. In case the string is not numeric it will return a zero. */
     val(): number;
+    /** Returns an array where each item is a string representing all available characters in the string. Could be compared to using {@link String.split|split} but with empty separator. */
     values(): string[];
     /** Returns true if this string starts with the searchString. Otherwise returns false. */
     startsWith(searchString: string, position?: number): boolean;
@@ -1458,9 +1557,13 @@ interface String {
      * @param end The index to the end of the specified portion of string. The substring includes the characters up to, but not including, the character indicated by end. If this value is not specified, the substring continues to the end of string.
      */
     slice(start?: number, end?: number): string;
+    /** Returns a string representation of a string. */
+    toString(): string;
     readonly [index: number]: string;
 }
 interface Number {
+    /** Returns a string representation of a number. */
+    toString(): string;
 }
 type PropertyKey = number | string | symbol;
 interface Object {
@@ -1477,10 +1580,13 @@ interface Object {
     shuffle(): null;
     sum(): number;
     values(): any[];
+    /** Returns a string representation of an object. */
+    toString(): string;
 }
 interface ObjectConstructor {
     new (value?: any): Object;
     readonly prototype: Object;
+    /** Determines whether an object has a property with the specified name. */
     hasOwn<T extends PropertyKey, U = object>(o: U, key: T): o is (T extends keyof U ? U : U & {
         [K in T]: unknown;
     });
@@ -1489,14 +1595,26 @@ interface ObjectConstructor {
     assign<T extends {}, U, V>(target: T, source: U, source2: V): T & U & V;
     assign<T extends {}, U, V, W>(target: T, source: U, source2: V, source3: W): T & U & V & W;
     assign(target: object, ...sources: any[]): any;
+    /** Returns an array of keys of the object */
     keys<T extends Record<any, any>>(o: T): (Exclude<keyof T, symbol>)[];
+    /** Returns an array of values of the object */
+    values<T extends Record<any, any>>(o: T): (T[keyof T])[];
 }
 interface Array<T> {
     readonly length: number;
+    /** Returns a boolean indicating if the provided index exists in the array */
     hasIndex(index: number): boolean;
+    /** Returns the index of the first occurrence of a value in an array, or null if it is not present. */
     indexOf(value: T, offset?: number): number | null;
+    /** Returns an array containing the indexes of the array */
     indexes(): number[];
+    /** Inserts a value into the array at the provided index. This method mutates the array and returns a reference to the same array. */
     insert(index: number, value: T): T[];
+    /**
+     * Returns a concatenated string containing all stringified values inside the list. These values will be separated via the provided separator.
+     *
+     * In case the list exceeds `16777215L` items or the delimiter exceeds 128 characters, this method will throw an error, interrupting further script execution.
+     */
     join(delimiter: string): string;
     /** Removes the first element from an array and returns it. If the array is empty, null is returned. */
     shift(): T | null;
@@ -1506,11 +1624,33 @@ interface Array<T> {
     pop(): T | null;
     /** Appends new elements to the end of an array, and returns the new length of the array. */
     push(...items: T[]): number;
+    /**
+     * Removes an item from the list with the provided index. Due to the removal the list will get mutated.
+     */
     remove(index: number): null;
+    /**
+     * Changes every value of the array that matches `oldValue` into `newValue`
+     *
+     * This method mutates the array and returns a reference to the same array.
+     */
     replace(oldValue: T, newValue: T, maxCount?: number): T[];
-    reverse(): null;
+    /** Reverses the elements in an array in place. This method mutates the array and returns a reference to the same array. */
+    reverse(): T;
+    /** Shuffles all values in the array. This method mutates the array. */
     shuffle(): null;
-    sort(key: PropertyKey | null, ascending?: boolean): T[];
+    /**
+     * Sorts the values of an array alphanumerically.
+     *
+     * This operation mutates the original array. Optionally, a key can be provided, which is used if the items are objects or arrays. Finally, this method returns the updated array.
+     * @example
+     * const myArray = [{ key: 123 }, { key: 5 }, { key: 17 }];
+     * myArray.sort("key");
+     *
+     * const numbers = [1,2,3,4,5];
+     * numbers.sort()
+     */
+    sort(key?: PropertyKey | null, ascending?: boolean): T[];
+    /** Returns a sum of all values inside the array. Any non-numeric values will be considered a zero. */
     sum(): number;
     values(): T[];
     /** Combines two or more arrays. This method returns a new array without modifying any existing arrays.
@@ -1534,9 +1674,13 @@ interface Array<T> {
      * @param end The end index of the specified portion of the array. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the array.
      * */
     slice(start?: number, end?: number): T[];
+    /** Returns a string representation of an array. */
+    toString(): string;
     [n: number]: T;
 }
 interface Function {
+    /** Returns a string representation of a function. */
+    toString(): string;
 }
 declare var String: {
     new (value?: any): String;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@grey-ts/types",
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"description": "TypeScript definitions for GreyHack's functions and objects",
 	"license": "MIT",
 	"types": "dist/index.d.ts",