@ethanblaisalarms/utils 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export type TRecord<T = unknown> = Record<string, T>;
+export type TNumRecord<T = unknown> = Record<number, T>;
+export type TCondition = (iteration?: number) => boolean;
+export declare function merge<T extends object>(target: T, ...sources: object[]): T;
+export declare function decommentJSON(data: string): string;
+export declare function checkPlain(data: unknown): data is TRecord;
+export declare function pull<T>(target: T[], ...elements: T[]): T[];
+export declare function pullAll<T>(target: T[], ...elements: T[]): T[];
+export declare function replace<T>(target: T[], element: T, ...replace: T[]): T[];
+export declare function replaceAll<T>(target: T[], element: T, ...replace: T[]): T[];
+export declare function objectify<T>(source: T[]): TNumRecord<T>;
+export declare function stringify(data: unknown): string;
+export declare function stringifyArray(data: unknown[]): string[];
+export declare function stringifyJSON(data: object, separator?: string, ignore?: string[]): string;
+export declare function rand(base?: number, maxInput?: number): number;
+export declare function rand<T>(base: T[]): T | null;
+export declare function rand(base: TRecord): string | null;
+export declare function randString(len?: number, charset?: string | string[]): string;
+export declare function sleep(ms: number): Promise<void>;
+export declare function until(condition: TCondition, interval?: number, attempts?: number | null): Promise<number>;

package/dist/index.js

@@ -0,0 +1,231 @@
+//=======================================\\
+//  EBA UTILITIES  1.0.0                 \\
+//  index.ts                             \\
+//  Copyright (c) EthanBlaisAlarms 2026  \\
+//=======================================\\
+//====================
+//  OBJECT UTILITIES
+//====================
+export function merge(target, ...sources) {
+    // Ignored node names.
+    // Prevents accidentally overwriting prototypes and constructors.
+    const blocklist = new Set(["__proto__", "prototype", "constructor"]);
+    const seen = new WeakSet();
+    const innerMerge = function (target, source) {
+        if (seen.has(source))
+            return;
+        seen.add(source);
+        for (const i of Object.keys(source)) {
+            // Skip ignored node names.
+            // Skip functions.
+            if (blocklist.has(i))
+                continue;
+            if (typeof source[i] === "function")
+                continue;
+            // Merge Arrays
+            if (Array.isArray(source[i]) && Array.isArray(target[i])) {
+                target[i] = target[i].concat(source[i]);
+                continue;
+            }
+            // Merge Non-Recursive
+            if (!checkPlain(target[i]) || !checkPlain(source[i])) {
+                target[i] = source[i];
+                continue;
+            }
+            // Merge Recursive
+            innerMerge(target[i], source[i]);
+        }
+        seen.delete(source);
+    };
+    for (const source of sources)
+        innerMerge(target, source);
+    return target;
+}
+export function decommentJSON(data) {
+    const linebreaks = ["\n", "\r"];
+    let inside = false;
+    let escape = false;
+    let single = false;
+    let multi = false;
+    let result = "";
+    for (let i = 0; i < data.length; i++) {
+        const char = data[i];
+        const nextChar = data[i + 1] ?? "";
+        const nextChars = char + nextChar;
+        if (inside) {
+            if (escape)
+                escape = false;
+            else if (char == "\\")
+                escape = true;
+            else if (char == "\"")
+                inside = false;
+        }
+        else if (single) {
+            if (linebreaks.includes(char))
+                single = false;
+            else
+                continue;
+        }
+        else if (multi) {
+            if (nextChars == "*/") {
+                multi = false;
+                i++;
+            }
+            continue;
+        }
+        else if (nextChars == "//") {
+            single = true;
+            i++;
+            continue;
+        }
+        else if (nextChars == "/*") {
+            multi = true;
+            i++;
+            continue;
+        }
+        else if (char == "\"")
+            inside = true;
+        result += char;
+    }
+    return result;
+}
+export function checkPlain(data) {
+    return Object.prototype.toString.call(data) === "[object Object]";
+}
+//===================
+//  ARRAY UTILITIES
+//===================
+export function pull(target, ...elements) {
+    for (const element of elements) {
+        const i = target.indexOf(element);
+        if (i >= 0)
+            target.splice(i, 1);
+    }
+    return target;
+}
+export function pullAll(target, ...elements) {
+    for (const element of elements) {
+        let i;
+        while ((i = target.indexOf(element)) !== -1)
+            target.splice(i, 1);
+    }
+    return target;
+}
+export function replace(target, element, ...replace) {
+    const i = target.indexOf(element);
+    if (i >= 0)
+        target.splice(i, 1, ...replace);
+    return target;
+}
+export function replaceAll(target, element, ...replace) {
+    let i;
+    while ((i = target.indexOf(element)) !== -1)
+        target.splice(i, 1, ...replace);
+    return target;
+}
+export function objectify(source) {
+    const output = {};
+    for (const i of source.keys())
+        output[i] = source[i];
+    return output;
+}
+//=============
+//  STRINGIFY
+//=============
+export function stringify(data) {
+    if (typeof data === "bigint")
+        return `${data}n`;
+    if (typeof data !== "object")
+        return String(data);
+    if (data === null)
+        return "null";
+    if (data instanceof Set)
+        return stringify(Array.from(data));
+    if (data instanceof Map)
+        return stringify(Array.from(data.entries()));
+    if (Array.isArray(data))
+        return stringifyJSON(data);
+    if (data.toString !== Object.prototype.toString
+        && typeof data.toString === "function")
+        return data.toString();
+    return stringifyJSON({ ...data });
+}
+export function stringifyArray(data) {
+    return data.map(stringify);
+}
+export function stringifyJSON(data, separator = " ", ignore = []) {
+    const seen = new WeakSet();
+    const paths = new WeakMap();
+    const ignoreSet = new Set(ignore);
+    const replacer = function (key, value) {
+        const parent = paths.get(this) ?? "";
+        const current = key
+            ? (parent ? parent + "." : "") + key
+            : "";
+        if (ignoreSet.has(current))
+            return undefined;
+        if (typeof value == "bigint")
+            return `${value}n`;
+        if (typeof value == "object" && value) {
+            if (seen.has(value))
+                return `[Circular: ${paths.get(value) || "~"}]`;
+            seen.add(value);
+            if (current != "")
+                paths.set(value, current);
+        }
+        if (value instanceof Set)
+            return Array.from(value);
+        if (value instanceof Map)
+            return Array.from(value.entries());
+        return value;
+    };
+    paths.set(data, "");
+    return JSON.stringify(data, replacer, separator);
+}
+export function rand(base, max) {
+    if (typeof base == "number") {
+        const hasMax = typeof max == "number";
+        const setBase = hasMax ? Math.min(base, max) : 0;
+        const setMax = hasMax ? Math.max(base, max) : base;
+        return Math.floor(Math.random() * (setMax - setBase + 1)) + setBase;
+    }
+    if (!base)
+        return Math.random();
+    if (Array.isArray(base)) {
+        if (base.length < 1)
+            return null;
+        return base[rand(base.length - 1)];
+    }
+    const keys = Object.keys(base);
+    if (keys.length < 1)
+        return null;
+    return rand(keys);
+}
+export function randString(len = 16, charset = "0123456789ABCDEF") {
+    if (typeof charset === "string")
+        charset = charset.split("");
+    if (charset.length < 1)
+        return "";
+    let output = "";
+    while (len > 0) {
+        output += rand(charset);
+        len--;
+    }
+    return output;
+}
+//===================
+//  ASYNC UTILITIES
+//===================
+export async function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+export async function until(condition, interval = 100, attempts = null) {
+    for (let i = 0; (i < (attempts ?? i + 1)); i++) {
+        if (condition(i + 1))
+            return i + 1;
+        await sleep(interval);
+    }
+    throw new RangeError("Maximum number of attempts reached.");
+}

package/dist/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.js

@@ -0,0 +1,312 @@
+//=======================================\\
+//  EBA UTILITIES  1.0.0                 \\
+//  test.ts                              \\
+//  Copyright (c) EthanBlaisAlarms 2026  \\
+//=======================================\\
+import * as Assert from "node:assert";
+import { checkPlain, decommentJSON, merge, objectify, pull, pullAll, replace, replaceAll, stringify, stringifyArray, stringifyJSON, } from "./index.js";
+console.log("Starting tests...");
+//====================
+//  OBJECT UTILITIES
+//====================
+console.log("\n\nCATEGORY: Object Utilities");
+//-----------------
+//  Merge objects
+//-----------------
+console.log("\nFUNCTION: merge()");
+console.log("TEST 1: General functionality and object mutation");
+const mrg11 = {
+    A: 1,
+    B: 2,
+    C: 3,
+};
+const mrg12 = {
+    A: 10,
+    D: 40,
+    E: 50,
+};
+const mrg13 = {
+    A: 100,
+    E: 500,
+    F: 600,
+};
+merge(mrg11, mrg12, mrg13);
+Assert.deepStrictEqual(mrg11, {
+    A: 100,
+    B: 2,
+    C: 3,
+    D: 40,
+    E: 500,
+    F: 600,
+});
+console.log("TEST 2: Exclusions and array concatenation");
+const mrg21 = {
+    A: 100,
+    B: new Date(-1000),
+    C: [0, 1, 2],
+    prototype: "I'm a prototype!",
+};
+const mrg22 = {
+    A: () => {
+        return true;
+    },
+    B: new Date(1000),
+    C: [3, 4, 5],
+    prototype: "I'm overwriting a prototype!",
+    [Symbol("Symbol")]: "I'm a symbol!",
+};
+merge(mrg21, mrg22);
+Assert.deepStrictEqual(mrg21, {
+    A: 100,
+    B: mrg22.B,
+    C: [0, 1, 2, 3, 4, 5],
+    prototype: "I'm a prototype!",
+});
+//-------------------
+//  De-Comment JSON
+//-------------------
+console.log("\nFUNCTION: decommentJSON()");
+console.log("TEST 1: Everything");
+const dcm1 = `{
+	// "A" holds the number of apples.
+	"A": 10,
+	/* "B" holds the number of bananas.
+	Must be greater than 0. */
+	"B": 20,
+	/*
+		"C" holds the number of carrots.
+		Must be:
+		- An even number
+		- Divisible by 3
+		- Not divisible by 60
+		- The digits must no add up to 6
+	*/
+	"C": 30,
+	"D": "//This is not a JSON comment"
+}`;
+const dcm2 = JSON.parse(decommentJSON(dcm1));
+Assert.deepStrictEqual(dcm2, {
+    A: 10,
+    B: 20,
+    C: 30,
+    D: "//This is not a JSON comment",
+});
+//---------------------------
+//  Check for plain objects
+//---------------------------
+console.log("\nFUNCTION: checkPlain()");
+console.log("TEST 1: Everything");
+const chk1 = [
+    checkPlain(new Date()),
+    checkPlain({}),
+];
+Assert.deepStrictEqual(chk1, [false, true]);
+//===================
+//  ARRAY UTILITIES
+//===================
+console.log("\n\nCATEGORY: Array Utilities");
+//-------------------
+//  Pull from array
+//-------------------
+console.log("\nFUNCTION: pull()");
+console.log("TEST 1: Everything");
+const pul1 = [10, 20, 30, 40, 50, 20];
+pull(pul1, 20, 50);
+Assert.deepStrictEqual(pul1, [10, 30, 40, 20]);
+//------------
+//  Pull all
+//------------
+console.log("\nFUNCTION: pullAll()");
+console.log("TEST 1: Everything");
+const pul2 = [10, 20, 30, 40, 50, 20];
+pullAll(pul2, 20, 50);
+Assert.deepStrictEqual(pul2, [10, 30, 40]);
+//--------------------
+//  Pull and replace
+//--------------------
+console.log("\nFUNCTION: replace()");
+console.log("TEST 1: Everything");
+const pul3 = [10, 20, 30, 40, 50, 20];
+replace(pul3, 20, 60, 70);
+Assert.deepStrictEqual(pul3, [10, 60, 70, 30, 40, 50, 20]);
+//------------------------
+//  Pull and replace all
+//------------------------
+console.log("\nFUNCTION: replaceAll()");
+console.log("TEST 1: Everything");
+const pul4 = [10, 20, 30, 40, 50, 20];
+replaceAll(pul4, 20, 60, 70);
+Assert.deepStrictEqual(pul4, [10, 60, 70, 30, 40, 50, 60, 70]);
+//--------------------
+//  Objectify arrays
+//--------------------
+console.log("\nFUNCTION: objectify()");
+console.log("TEST 1: Everything");
+const obj1 = ["zero", "one", "two", "three"];
+const obj2 = objectify(obj1);
+Assert.deepStrictEqual(obj2, {
+    0: "zero",
+    1: "one",
+    2: "two",
+    3: "three",
+});
+//====================
+//  STRINGIFY VALUES
+//====================
+console.log("\n\nCATEGORY: Stringify Values");
+//---------------------
+//  General stringify
+//---------------------
+console.log("\nFUNCTION: stringify()");
+console.log("TEST 1: General functionality with primitives");
+const str1 = [
+    stringify("hello"),
+    stringify(100),
+    stringify(500n),
+    stringify(false),
+    stringify(Symbol("str")),
+    stringify(null),
+    stringify(undefined),
+];
+Assert.deepStrictEqual(str1, [
+    "hello",
+    "100",
+    "500n",
+    "false",
+    "Symbol(str)",
+    "null",
+    "undefined",
+]);
+console.log("TEST 2: Plain objects");
+const str2 = [
+    stringify({}),
+    stringify({
+        A: 100,
+        B: {
+            C: 500,
+        },
+    }),
+    stringify({
+        A: 100,
+        toString: () => {
+            return "A is 100";
+        },
+    }),
+    stringify({
+        A: 100,
+        toString: "Not callable",
+    }),
+    stringify([1, 2, 3, 4, 5]),
+];
+const str3 = `{
+ "A": 100,
+ "B": {
+  "C": 500
+ }
+}`;
+const str4 = `{
+ "A": 100,
+ "toString": "Not callable"
+}`;
+const str5 = `[
+ 1,
+ 2,
+ 3,
+ 4,
+ 5
+]`;
+Assert.deepStrictEqual(str2, [
+    "{}",
+    str3,
+    "A is 100",
+    str4,
+    str5,
+]);
+console.log("TEST 3: Object instances");
+const str6 = new Date(0);
+const str7 = [
+    stringify(str6),
+    stringify(new Error("Something went wrong!")),
+    stringify((new Set()).add("One")),
+    stringify((new Map()).set("1", "One")),
+];
+const str8 = `[
+ "One"
+]`;
+const str9 = `[
+ [
+  "1",
+  "One"
+ ]
+]`;
+Assert.deepStrictEqual(str7, [
+    str6.toString(),
+    "Error: Something went wrong!",
+    str8,
+    str9,
+]);
+//------------------
+//  Stringify JSON
+//------------------
+console.log("\nFUNCTION: stringifyJSON()");
+console.log("TEST 1: Everything");
+const jsn1 = {
+    A: 1,
+    B: 2,
+    C: (new Set()).add("Ten"),
+};
+const jsn2 = {
+    A: 1,
+    B: 2,
+    C: {
+        A: 100n,
+        B: 2,
+    },
+};
+const jsn3 = {
+    D: jsn1,
+    E: jsn1,
+};
+jsn3.F = jsn3;
+const jsn4 = {
+    jsn1: stringifyJSON(jsn1),
+    jsn2: stringifyJSON(jsn2, ">", ["A", "C.B"]),
+    jsn3: stringifyJSON(jsn3),
+};
+const jsn5 = `{
+ "A": 1,
+ "B": 2,
+ "C": [
+  "Ten"
+ ]
+}`;
+const jsn6 = `{
+>"B": 2,
+>"C": {
+>>"A": "100n"
+>}
+}`;
+const jsn7 = `{
+ "D": {
+  "A": 1,
+  "B": 2,
+  "C": [
+   "Ten"
+  ]
+ },
+ "E": "[Circular: D]",
+ "F": "[Circular: ~]"
+}`;
+Assert.deepStrictEqual(jsn4, {
+    jsn1: jsn5,
+    jsn2: jsn6,
+    jsn3: jsn7,
+});
+//----------------------------
+//  Stringify array elements
+//----------------------------
+console.log("\nFUNCTION: stringifyArray()");
+console.log("TEST 1: Everything");
+const arr1 = [null, 20, {}];
+const arr2 = stringifyArray(arr1);
+Assert.deepStrictEqual(arr2, ["null", "20", "{}"]);

package/eba_utils.code-workspace

@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {}
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@ethanblaisalarms/utils",
+  "version": "1.0.0",
+  "description": "Lightweight helpers, primarily focused on array and object manipulation and improved stringification.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prestart": "tsc",
+    "start": "node .",
+    "test": "npm run build && node dist/test.js"
+  },
+  "author": "EthanBlaisAlarms <support@ethanblaisalarms.com>",
+  "license": "ISC",
+  "dependencies": {
+    "@types/node": "^25.3.5",
+    "typescript": "^5.9.3"
+  }
+}