@ethanblaisalarms/utils 1.0.0

package/src/index.ts

@@ -0,0 +1,286 @@
+//=======================================\\
+//  EBA UTILITIES  1.0.0                 \\
+//  index.ts                             \\
+//  Copyright (c) EthanBlaisAlarms 2026  \\
+//=======================================\\
+
+
+//========================
+//  TYPES and INTERFACES
+//========================
+export type TRecord<T = unknown> = Record<string, T>;
+export type TNumRecord<T = unknown> = Record<number, T>;
+export type TCondition = (iteration?:number)=>boolean;
+
+
+//====================
+//  OBJECT UTILITIES
+//====================
+export function merge<T extends object>(
+	target:T,
+	...sources:object[]
+):T {
+	// Ignored node names.
+	// Prevents accidentally overwriting prototypes and constructors.
+	const blocklist = new Set(["__proto__", "prototype", "constructor"]);
+	const seen = new WeakSet();
+
+	const innerMerge = function(
+		target:TRecord,
+		source:TRecord,
+	):void {
+		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 as TRecord, source as TRecord);
+	return target;
+}
+export function decommentJSON(data:string):string {
+	const linebreaks:string[] = ["\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:string = data[i];
+		const nextChar:string = data[i+1] ?? "";
+		const nextChars:string = 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:unknown):data is TRecord {
+	return Object.prototype.toString.call(data) === "[object Object]";
+}
+
+
+//===================
+//  ARRAY UTILITIES
+//===================
+export function pull<T>(
+	target:T[],
+	...elements:T[]
+):T[] {
+	for (const element of elements) {
+		const i:number = target.indexOf(element);
+		if (i >= 0) target.splice(i, 1);
+	}
+	return target;
+}
+export function pullAll<T>(
+	target:T[],
+	...elements:T[]
+):T[] {
+	for (const element of elements) {
+		let i;
+		while ((i = target.indexOf(element)) !== -1) target.splice(i, 1);
+	}
+	return target;
+}
+export function replace<T>(
+	target:T[],
+	element:T,
+	...replace:T[]
+):T[] {
+	const i:number = target.indexOf(element);
+	if (i >= 0) target.splice(i, 1, ...replace);
+	return target;
+}
+export function replaceAll<T>(
+	target:T[],
+	element:T,
+	...replace:T[]
+):T[] {
+	let i;
+	while ((i = target.indexOf(element)) !== -1) target.splice(i, 1, ...replace);
+	return target;
+}
+export function objectify<T>(source:T[]):TNumRecord<T> {
+	const output:TNumRecord<T> = {};
+	for (const i of source.keys()) output[i] = source[i];
+	return output;
+}
+
+
+//=============
+//  STRINGIFY
+//=============
+export function stringify(data:unknown):string {
+	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:unknown[]):string[] {
+	return data.map(stringify);
+}
+export function stringifyJSON(
+	data:object,
+	separator:string = " ",
+	ignore:string[] = [],
+):string {
+	const seen:WeakSet<object> = new WeakSet();
+	const paths:WeakMap<object, string> = new WeakMap();
+	const ignoreSet = new Set(ignore);
+
+	const replacer = function(this:any, key:string, value:unknown):unknown {
+		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);
+}
+
+
+//=================
+//  RANDOMIZATION
+//=================
+export function rand(
+	base?:number,
+	maxInput?:number,
+):number;
+export function rand<T>(
+	base:T[],
+):T|null;
+export function rand(
+	base:TRecord,
+):string|null;
+export function rand(
+	base?:number|unknown[]|TRecord,
+	max?:number,
+):unknown {
+	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:string|string[]="0123456789ABCDEF",
+):string {
+	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:number):Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+export async function until(
+	condition:TCondition,
+	interval=100,
+	attempts:number|null=null,
+):Promise<number> {
+	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/src/test.ts

@@ -0,0 +1,366 @@
+//=======================================\\
+//  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,
+	TRecord,
+} 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: ():true => {
+		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: ():string => {
+			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:TRecord = {
+	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/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"declaration": true,
+		"outDir": "dist",
+		"rootDir": "src",
+		"moduleResolution": "node",
+		"types": ["node"],
+		"strict": true
+	},
+	"include": ["src"]
+}