mark-3 0.0.3 → 0.0.5

package/helpers/number/tests/clamp.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { clamp } from "..";
+
+describe("clamp()", () =>
+{
+	it("returns the same value if it is within the min and max range", () =>
+	{
+		expect(clamp(5, 0, 10)).toBe(5);
+		expect(clamp(0, -10, 10)).toBe(0);
+		expect(clamp(9.5, 0, 10)).toBe(9.5);
+	});
+
+	it("clamps the value to the min if it is less than min", () =>
+	{
+		expect(clamp(-5, 0, 10)).toBe(0);
+		expect(clamp(-100, -10, 10)).toBe(-10);
+	});
+
+	it("clamps the value to the max if it is greater than max", () =>
+	{
+		expect(clamp(15, 0, 10)).toBe(10);
+		expect(clamp(99, -10, 10)).toBe(10);
+	});
+
+	it("returns the only possible value if min and max are equal", () =>
+	{
+		expect(clamp(5, 7, 7)).toBe(7);
+		expect(clamp(10, 10, 10)).toBe(10);
+		expect(clamp(-5, -3, -3)).toBe(-3);
+	});
+
+	it("swaps min and max if needed", () =>
+	{
+		expect(clamp(5, 10, 0)).toBe(5);
+		expect(clamp(-5, 3, -3)).toBe(-3);
+	});
+});

package/helpers/number/tests/random.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { random } from "..";
+
+describe("random", () =>
+{
+	it("should return a number between 0 and 1 by default", () =>
+	{
+		const result = random();
+		expect(result).toBeGreaterThanOrEqual(0);
+		expect(result).toBeLessThanOrEqual(1);
+		expect(Number.isInteger(result)).toBe(true);
+	});
+
+	it("should return float if shouldFloat is true", () =>
+	{
+		const result = random(0, 1, true);
+		expect(result).toBeGreaterThanOrEqual(0);
+		expect(result).toBeLessThanOrEqual(1);
+		expect(Number.isInteger(result)).toBe(false);
+	});
+
+	it("should respect min and max range with integers", () =>
+	{
+		const result = random(5, 10);
+		expect(result).toBeGreaterThanOrEqual(5);
+		expect(result).toBeLessThanOrEqual(10);
+		expect(Number.isInteger(result)).toBe(true);
+	});
+
+	it("should respect min and max range with floats", () =>
+	{
+		const result = random(5, 10, true);
+		expect(result).toBeGreaterThanOrEqual(5);
+		expect(result).toBeLessThanOrEqual(10);
+	});
+
+	it("should always return at least the min value", () =>
+	{
+		for (let i = 0; i < 100; i++)
+		{
+			const result = random(10, 20);
+			expect(result).toBeGreaterThanOrEqual(10);
+		}
+	});
+
+	it("should return exactly min if min and max are both 0", () =>
+	{
+		const result = random(0, 0);
+		expect(result).toBe(0);
+	});
+});

package/helpers/string/{camel-to-dash/index.js → camel-to-dash.js}

@@ -1,5 +1,5 @@
-import { trim } from "..";
-import { isString } from "../../types";
+import { trim } from ".";
+import { isString } from "../types";
 
 /**
  * Converts a camelCase string to dash-case.

package/helpers/string/encode-subscript.js

@@ -0,0 +1,45 @@
+const map =
+{ 
+	0: "₀", 1: "₁", 2: "₂", 3: "₃", 4: "₄", 5: "₅", 6: "₆", 7: "₇", 8: "₈", 9: "₉",
+	a: "ₐ", e: "ₑ", h: "ₕ", k: "ₖ", l: "ₗ", m: "ₘ", n: "ₙ", o: "ₒ", p: "ₚ", s: "ₛ",
+	t: "ₜ", "+": "₊", "-": "₋", "=": "₌", "(": "₍", ")": "₎",
+}
+
+/**
+ * Converts a given string into its subscript equivalent, if available.
+ *
+ * @param {string} str - The string to be converted.
+ * @param {boolean} [rollbackWhenMismatch=true] If true, returns the original string
+ *  a character is not in the map.
+ * @returns {string} The subscript representation of the string if it exists in the
+ * map, otherwise the original string.
+ */
+export default function encodeSubscript( str, rollbackWhenMismatch = true )
+{
+	if( typeof str !== "string" )
+	{
+		return str;
+	}
+
+	if( rollbackWhenMismatch )
+	{
+		let stack = "";
+
+		for( let char of str )
+		{
+			if( ! ( char in map ))
+			{
+				return str;
+			}
+
+			stack += map[ char ];
+		}
+
+		return stack;
+	}
+	
+	return str
+		.split( "" )
+		.map( char => map[ char ] || char )
+		.join( "" );
+}

package/helpers/string/{escape-regex/index.js → escape-regex.js}

@@ -1,4 +1,4 @@
-import { isString } from "../../types";
+import { isString } from "../types";
 
 /**
  * Escapes special characters in a string to be used in a regular expression.

package/helpers/string/index.js

@@ -1,3 +1,4 @@
 export { default as trim } from "./trim";
 export { default as escapeRegex } from "./escape-regex";
 export { default as camelToDash } from "./camel-to-dash";
+export { default as encodeSubscript } from "./encode-subscript";

package/helpers/string/{camel-to-dash/index.test.js → tests/camel-to-dash.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import camelToDash from ".";
+import { camelToDash } from "..";
 
 describe( "camelToDash", () =>
 {

package/helpers/string/tests/encode-subscript.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { encodeSubscript } from "..";
+
+describe("encodeSubscript", () =>
+{
+	it("converts full match to subscript", () =>
+	{
+		expect(encodeSubscript("h2o")).toBe("ₕ₂ₒ");
+		expect(encodeSubscript("123")).toBe("₁₂₃");
+	});
+
+	it("returns original string if any character mismatches and rollbackWhenMismatch is true", () =>
+	{
+		expect(encodeSubscript("H2O")).toBe("H2O"); // 'H' and 'O' not in map
+		expect(encodeSubscript("x+2")).toBe("x+2"); // 'x' not in map
+	});
+
+	it("fallbacks partially when rollbackWhenMismatch is false", () =>
+	{
+		expect(encodeSubscript("x+2", false)).toBe("x₊₂");
+		expect(encodeSubscript("H2O", false)).toBe("H₂O");
+	});
+
+	it("returns non-string inputs as-is", () =>
+	{
+		expect(encodeSubscript(null)).toBe(null);
+		expect(encodeSubscript(undefined)).toBe(undefined);
+		expect(encodeSubscript(123)).toBe(123);
+		expect(encodeSubscript({})).toEqual({});
+	});
+
+	it("handles empty string correctly", () =>
+	{
+		expect(encodeSubscript("")).toBe("");
+	});
+
+	it("works with symbols like + - ( )", () =>
+	{
+		expect(encodeSubscript("2+(3-1)", false)).toBe("₂₊₍₃₋₁₎");
+	});
+});

package/helpers/string/{escape-regex/index.test.js → tests/escape-regex.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import escapeRegex from "./escapeRegex";
+import { escapeRegex } from "..";
 
 describe( "escapeRegex", () =>
 {

package/helpers/string/{trim/index.test.js → tests/trim.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import trim from ".";
+import { trim } from "..";
 
 describe( "trim", () =>
 {

package/helpers/string/{trim/index.js → trim.js}

@@ -1,5 +1,5 @@
-import { escapeRegex } from "..";
-import { isEmpty, isArray, isString } from "../../types";
+import { escapeRegex } from ".";
+import { isEmpty, isArray, isString } from "../types";
 
 /**
  * Trims the specified characters from the beginning and end of a string.
@@ -11,7 +11,7 @@ import { isEmpty, isArray, isString } from "../../types";
  */
 export default function trim( input, chars = " " )
 {
-	if( ! isString( input ) || isEmpty( chars ))
+	if( ! isString( input ) || ( chars !== " " && isEmpty( chars )))
 	{
 		return input;
 	}

package/helpers/time/debounce.js

@@ -0,0 +1,29 @@
+/**
+ * Debounce a function call to prevent it from being called too often.
+ * 
+ * This is useful for functions that are called on every
+ *   frame, such as onScroll. This will ensure that the function
+ *   is only called at most once every `delay` milliseconds. 
+ * 
+ * @example
+ * const debounced = debounce(() =>
+ *    console.log( "Hello" ),
+ *    1000
+ * );
+ * 
+ * window.addEventListener( "scroll", debounced );
+ * 
+ * @param {function} callback The function to debounce.
+ * @param {number} delay The delay in milliseconds.
+ * @returns {function}
+ */
+export default function debounce( callback, delay = 200 )
+{
+	let timer;
+
+	return function debounceWrapper( ...args )
+	{
+		clearTimeout( timer );
+		timer = setTimeout( callback.bind( this, ...args ), delay );
+	}
+}

package/helpers/time/index.js

@@ -0,0 +1 @@
+export { default as debounce } from "./debounce";

package/helpers/time/tests/debounce.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi } from "vitest";
+import { debounce } from "..";
+
+describe("debounce", () =>
+{
+	it("should call the callback after the delay", async () =>
+	{
+		const callback = vi.fn();
+		const delay = 100;
+		const debouncedFn = debounce(callback, delay);
+
+		debouncedFn();
+		expect(callback).not.toHaveBeenCalled();
+
+		// wait delay + 20ms
+		await new Promise((r) => setTimeout(r, delay + 20));
+
+		expect(callback).toHaveBeenCalledTimes(1);
+	});
+
+	it("should call the callback only once if called multiple times quickly", async () =>
+	{
+		const callback = vi.fn();
+		const delay = 100;
+		const debouncedFn = debounce(callback, delay);
+
+		debouncedFn();
+		debouncedFn();
+		debouncedFn();
+
+		expect(callback).not.toHaveBeenCalled();
+
+		await new Promise((r) => setTimeout(r, delay + 20));
+
+		expect(callback).toHaveBeenCalledTimes(1);
+	});
+
+	it("should pass arguments and context correctly", async () =>
+	{
+		const callback = vi.fn(function (a, b)
+	{
+			// 'this' should be the wrapper's this context
+			expect(this).toEqual({ foo: "bar" });
+			expect(a).toBe(1);
+			expect(b).toBe(2);
+		});
+
+		const delay = 50;
+		const debouncedFn = debounce(callback, delay);
+
+		// call with context and arguments
+		debouncedFn.call({ foo: "bar" }, 1, 2);
+
+		await new Promise((r) => setTimeout(r, delay + 20));
+
+		expect(callback).toHaveBeenCalledTimes(1);
+	});
+});

package/helpers/types/index.js

@@ -1,5 +1,8 @@
+export { default as isMap } from "./is-map";
+export { default as isSet } from "./is-set";
 export { default as isArray } from "./is-array";
 export { default as isEmpty } from "./is-empty";
 export { default as isString } from "./is-string";
+export { default as isNumeric } from "./is-numeric";
 export { default as getTypeName } from "./get-type-name";
 export { default as isPlainObject } from "./is-plain-object";

package/helpers/types/{is-empty/index.js → is-empty.js}

@@ -1,4 +1,4 @@
-import { isString, isArray, isMap, isSet, isPlainObject } from "..";
+import { isString, isArray, isMap, isSet, isPlainObject } from ".";
 
 /**
  * Checks if the given variable is empty.

package/helpers/types/is-map.js

@@ -0,0 +1,12 @@
+import { getTypeName } from ".";
+
+/**
+ * Checks if a given value is a Map.
+ *
+ * @param {any} value - The value to be checked.
+ * @returns {boolean} true if the value is a Map, false otherwise.
+ */
+export default function isMap( value )
+{
+	return getTypeName( value ) === "Map";
+}

package/helpers/types/is-numeric.js

@@ -0,0 +1,22 @@
+/**
+ * Checks if a value is numeric or can be converted to a number.
+ * 
+ * @param {any} value - The value to be checked.
+ * @returns {boolean} true if the value is numeric, false otherwise.
+ */
+export default function isNumeric( value )
+{
+	if( typeof value === "number" )
+	{
+    	return ! isNaN( value ) && isFinite( value );
+	}
+
+	if( typeof value === "string" )
+	{
+		return value.trim() !== "" &&
+		       ! isNaN( Number( value )) &&
+			   isFinite( Number( value ));
+	}
+
+	return false;
+}

package/helpers/types/{is-plain-object/index.js → is-plain-object.js}

@@ -1,5 +1,3 @@
-import { getTypeName } from "../type";
-
 /**
  * Checks if the given value is a plain object.
  *
@@ -8,5 +6,12 @@ import { getTypeName } from "../type";
  */
 export default function isPlainObject( value )
 {
-	return getTypeName( value ) === "Object";
+	if( typeof value !== "object" || value === null )
+	{
+		return false;
+	}
+
+	const proto = Object.getPrototypeOf( value );
+	
+	return proto === Object.prototype || proto === null;
 }

package/helpers/types/is-set.js

@@ -0,0 +1,12 @@
+import { getTypeName } from ".";
+
+/**
+ * Checks if a given value is a Set.
+ *
+ * @param {any} value - The value to be checked.
+ * @returns {boolean} true if the value is a Set, false otherwise.
+ */
+export default function isSet( value )
+{
+	return getTypeName( value ) === "Set";
+}

package/helpers/types/{get-type-name/index.test.js → tests/get-type-name.test.js}

@@ -1,7 +1,7 @@
 import { describe, it, expect } from "vitest";
-import getTypeName from "./type";
+import { getTypeName } from "..";
 
-describe( "type", () =>
+describe( "getTypeName", () =>
 {
 	it( 'should return "String" for a string', () =>
 	{

package/helpers/types/{is-array/index.test.js → tests/is-array.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import isArray from ".";
+import { isArray } from "..";
 
 describe( "isArray", () =>
 {

package/helpers/types/{is-empty/index.test.js → tests/is-empty.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import isEmpty from "../src/isEmpty";
+import { isEmpty } from "../index";
 
 describe( "isEmpty", () =>
 {

package/helpers/types/tests/is-map.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { isMap } from "..";
+
+describe("isMap", () =>
+{
+	it("should return true for Map instances", () =>
+	{
+		expect(isMap(new Map())).toBe(true);
+		const map = new Map();
+		map.set("key", "value");
+		expect(isMap(map)).toBe(true);
+	});
+
+	it("should return false for WeakMap", () =>
+	{
+		expect(isMap(new WeakMap())).toBe(false);
+	});
+
+	it("should return false for plain objects", () =>
+	{
+		expect(isMap({})).toBe(false);
+		expect(isMap({ a: 1 })).toBe(false);
+	});
+
+	it("should return false for arrays", () =>
+	{
+		expect(isMap([])).toBe(false);
+		expect(isMap([1, 2, 3])).toBe(false);
+	});
+
+	it("should return false for other types", () =>
+	{
+		expect(isMap(null)).toBe(false);
+		expect(isMap(undefined)).toBe(false);
+		expect(isMap(42)).toBe(false);
+		expect(isMap("string")).toBe(false);
+		expect(isMap(true)).toBe(false);
+		expect(isMap(Symbol("sym"))).toBe(false);
+		expect(isMap(function () {})).toBe(false);
+	});
+});

package/helpers/types/tests/is-numeric.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { isNumeric } from "..";
+
+describe("isNumeric function", () =>
+{
+	it("should return true for numeric numbers", () =>
+	{
+		expect(isNumeric(0)).toBe(true);
+		expect(isNumeric(123)).toBe(true);
+		expect(isNumeric(-456)).toBe(true);
+		expect(isNumeric(1e4)).toBe(true);
+		expect(isNumeric(3.14)).toBe(true);
+	});
+
+	it("should return false for NaN and Infinity numbers", () =>
+	{
+		expect(isNumeric(NaN)).toBe(false);
+		expect(isNumeric(Infinity)).toBe(false);
+		expect(isNumeric(-Infinity)).toBe(false);
+	});
+
+	it("should return true for numeric strings", () =>
+	{
+		expect(isNumeric("0")).toBe(true);
+		expect(isNumeric("123")).toBe(true);
+		expect(isNumeric("-456")).toBe(true);
+		expect(isNumeric("1e4")).toBe(true);
+		expect(isNumeric("3.14")).toBe(true);
+		expect(isNumeric("  42  ")).toBe(true);
+	});
+
+	it("should return false for non-numeric strings", () =>
+	{
+		expect(isNumeric("")).toBe(false);
+		expect(isNumeric(" ")).toBe(false);
+		expect(isNumeric("abc")).toBe(false);
+		expect(isNumeric("123abc")).toBe(false);
+		expect(isNumeric("Infinity")).toBe(false);
+	});
+
+	it("should return false for other data types", () =>
+	{
+		expect(isNumeric(null)).toBe(false);
+		expect(isNumeric(undefined)).toBe(false);
+		expect(isNumeric(true)).toBe(false);
+		expect(isNumeric(false)).toBe(false);
+		expect(isNumeric({})).toBe(false);
+		expect(isNumeric([])).toBe(false);
+		expect(isNumeric(() => {})).toBe(false);
+	});
+});

package/helpers/types/{is-plain-object/index.test.js → tests/is-plain-object.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import isPlainObject from "./isPlainObject";
+import { isPlainObject } from "..";
 
 describe("isPlainObject", () =>
 {

package/helpers/types/tests/is-set.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { isSet } from "..";
+
+describe("isSet", () =>
+{
+	it("should return true for Set instances", () =>
+	{
+		expect(isSet(new Set())).toBe(true);
+		const set = new Set();
+		set.add("key", "value");
+		expect(isSet(set)).toBe(true);
+	});
+
+	it("should return false for WeakSet", () =>
+	{
+		expect(isSet(new WeakSet())).toBe(false);
+	});
+
+	it("should return false for plain objects", () =>
+	{
+		expect(isSet({})).toBe(false);
+		expect(isSet({ a: 1 })).toBe(false);
+	});
+
+	it("should return false for arrays", () =>
+	{
+		expect(isSet([])).toBe(false);
+		expect(isSet([1, 2, 3])).toBe(false);
+	});
+
+	it("should return false for other types", () =>
+	{
+		expect(isSet(null)).toBe(false);
+		expect(isSet(undefined)).toBe(false);
+		expect(isSet(42)).toBe(false);
+		expect(isSet("string")).toBe(false);
+		expect(isSet(true)).toBe(false);
+		expect(isSet(Symbol("sym"))).toBe(false);
+		expect(isSet(function () {})).toBe(false);
+	});
+});

package/helpers/types/tests/is-string.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { isString } from "..";
+
+describe("isString", () => {
+  it("should return true for a normal string", () => {
+    expect(isString("hello")).toBe(true);
+  });
+
+  it("should return true for an empty string", () => {
+    expect(isString("")).toBe(true);
+  });
+
+  it("should return false for a String object", () => {
+    // typeof new String("abc") === "object"
+    expect(isString(new String("abc"))).toBe(false);
+  });
+
+  it("should return false for a number", () => {
+    expect(isString(123)).toBe(false);
+  });
+
+  it("should return false for null", () => {
+    expect(isString(null)).toBe(false);
+  });
+
+  it("should return false for undefined", () => {
+    expect(isString(undefined)).toBe(false);
+  });
+
+  it("should return false for an object", () => {
+    expect(isString({})).toBe(false);
+  });
+
+  it("should return false for an array", () => {
+    expect(isString(["a", "b"])).toBe(false);
+  });
+
+  it("should return false for a boolean", () => {
+    expect(isString(true)).toBe(false);
+    expect(isString(false)).toBe(false);
+  });
+
+  it("should return false for a function", () => {
+    expect(isString(() => {})).toBe(false);
+  });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "mark-3",
   "description": "Modular collection of reusable JavaScript helpers, utilities, and Vue components. Built for maintainability, performance, and clarity.",
   "private": false,
-  "version": "0.0.3",
+  "version": "0.0.5",
   "workspaces": [
     "src/*/*"
   ],