ForgeJSON

Better and new $json and $array functions for ForgeScript. Discord IDs never lose digits, and leaderboards, pages and lists take a single function.

---

Contents

1. Installation
2. Functions
3. What it fixes in ForgeScript

Installation

---

1. Install the package.

   From npm - the stable release:

   npm i forge.json

   From GitHub:

   npm i github:Daaisukidayo/ForgeJSON#main

   It needs ForgeScript 2.4.0 and Node.js 22 or newer.

2. Here's an example of how your main file should look:

   const { ForgeClient } = require("@tryforge/forgescript")
   const { ForgeJSON } = require("forge.json")
   
   const client = new ForgeClient({
       ...options, // Change that to the options you currently have
       extensions: [
           new ForgeJSON(),
           // Add other extensions you installed here
       ]
   })
   
   client.login("YourToken")

ForgeJSON replaces 37 of ForgeScript's functions. Existing calls keep working, and the differences are under Changed in functions.md.

⚠️ Warning
Lists saved before ForgeJSON hold their numbers as text. Search them with $arrayIndexOf[list;"10"], not $arrayIndexOf[list;10].

Functions

---

Every function is in functions.md, along with the Basics they share and Examples of whole commands.

Group	Functions	What for
JSON functions	14	Reading, writing and checking any value.
Object functions	5	Building objects and working with their keys.
Array functions	51	Adding and removing, pages, random picks, sorting, sums, formatting and loops.

What it fixes in ForgeScript

---

Checked on @tryforge/forgescript 2.7.0 and 2.7.1:

In ForgeScript	With ForgeJSON
$jsonLoad, $jsonSet, $arrayMap, $arrayPushJSON, $arrayUnshiftJSON and $arrayFill round long numbers, so the ID 123456789012345678 is stored as 123456789012345680.	IDs stay exact.
Since 2.7.1, $arrayIncludes misses a long ID or a code like 007 that the list holds.	Both are found.
$jsonLoad stores JSON that doesn't parse as plain text. When a ] cuts it short, the rest of it ends up in the message.	An object or array that doesn't parse is an error naming the likely cause.
$arrayPush, $arrayUnshift, $arraySplice and $arrayLoad store numbers and booleans as text, so since 2.7.1 $arrayIncludes[list;5] misses the 5 they added.	Numbers and booleans are stored as such.
$arrayIndexOf[list;5] and $arrayLastIndexOf[list;5] don't find the number in [5]. Neither did $arrayIncludes[list;5] before 2.7.1, and since then it disagrees with them.	All three compare by type.
$arrayPush, $arrayUnshift, $arrayPushJSON, $arrayUnshiftJSON and $arraySplice silently do nothing when the variable holds something other than an array, or nothing yet.	A missing array is created, anything else is an error.
$arrayJoin writes objects as [object Object].	Objects are written as JSON.
$jsonHas answers nothing, rather than false, for a missing variable.	It answers false.
$jsonDelete on an array answers with the removed element, rather than true or false.	It answers true or false.
The array loops leave their variables set once they end, overwriting any variable of the same name.	They are restored.
$arrayEvery doesn't read its code as a condition, so $arrayEvery[list;x;$env[x]>0] gives false for any list that isn't empty.	The condition is read as in $if.
$arrayReduce without a default value starts from null, not the 0 it promises, so adding up [1,2,3] with $math gives 5.	It starts from 0.
$arrayShuffle makes some orders likelier than others.	Every order is equally likely.
$arraySort sorts asc from the largest and desc from the smallest. Without a sort type it sorts numbers as text, so [10,9,1] becomes [1,10,9].	asc and desc are the right way round, and numbers sort as numbers.
$arrayFill puts one and the same object in every element, so changing one element changes them all.	Every element gets its own copy.
$arrayRandomIndex gives 0 for an empty array.	It gives nothing.
$arrayReverse[a;b] and $arraySort[a;b] change a as well, and make b the very same array.	b gets its own copy, and a stays as it is.