mark-3 0.0.4 → 0.0.5

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 ".";
+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.

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

@@ -3,5 +3,6 @@ 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/index.js → is-map.js}

@@ -1,4 +1,4 @@
-import { getTypeName } from "..";
+import { getTypeName } from ".";
 
 /**
  * Checks if a given value is a 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-set/index.js → is-set.js}

@@ -1,4 +1,4 @@
-import { getTypeName } from "..";
+import { getTypeName } from ".";
 
 /**
  * Checks if a given value is a 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 ".";
+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 ".";
+import { isEmpty } from "../index";
 
 describe( "isEmpty", () =>
 {

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

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

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 ".";
+import { isPlainObject } from "..";
 
 describe("isPlainObject", () =>
 {

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

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

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import isString from ".";
+import { isString } from "..";
 
 describe("isString", () => {
   it("should return true for a normal string", () => {

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.4",
+  "version": "0.0.5",
   "workspaces": [
     "src/*/*"
   ],

package/helpers/date/format/README.md

@@ -1,33 +0,0 @@
-# format
-A lightweight and flexible date formatting utility for JavaScript and TypeScript. This helper formats Date objects using PHP-style tokens like Y, m, d, H, i, and more. It supports both short and long month names with locale-aware formatting via Intl.DateTimeFormat.
-
-Built with simplicity and clarity in mind — no external dependencies, easy to use, fully typed.
-
----
-
-## Usage
-```ts
-import { format } from '@mark-3/helpers/date';
-
-format( new Date, "Y-m-d H:i:s" );
-// 2022-01-01 22:00:00 (mysql datetime format)
-
-format( new Date, "j MM, H:i", "tr" );
-// 1 Temmuz, 22:00
-```
-
----
-
-## 💡 Supported Tokens
-`d`: 01-31 (zero-padded day)
-`j`:  1-31 (non-padded day)
-`m`: 01-12 (zero-padded month)
-`n`:  1-12 (non-padded month)
-`M`: Jan–Dec (short month name, localized)
-`MM`: January–December (long month name, localized)
-`y`: 00-99 (two-digit year)
-`Y`: 0000-9999 (full year)
-`H`: 00-23 (zero-padded hour, 24h)
-`G`:  0-23 (hour, 24h)
-`i`: 00-59 (minutes)
-`s`: 00-59 (seconds)

package/helpers/date/format/index.test.js

@@ -1,97 +0,0 @@
-import { describe, it, expect } from "vitest";
-import formatDate from "./index";
-
-describe( "formatDate", () =>
-{
-	const date = new Date( "2025-12-21T22:10:05" );
-
-	it( "formats full year (Y)", () =>
-	{
-		expect( formatDate( date, "Y" )).toBe( "2025" );
-	});
-	
-	it( "formats short year (y)", () =>
-	{
-		expect( formatDate( date, "y" )).toBe( "25" );
-	});
-	
-	it( "formats zero-padded month (m)", () =>
-	{
-		expect( formatDate( date, "m" )).toBe( "12" );
-	});
-	
-	it( "formats non-padded month (n)", () =>
-	{
-		expect( formatDate( date, "n" )).toBe( "12" );
-	});
-	
-	it( "formats short month name (M)", () =>
-	{
-		expect( formatDate( date, "M" )).toBe( "Dec" );
-	});
-	
-	it( "formats full month name (MM)", () =>
-	{
-		expect( formatDate( date, "MM" )).toBe( "December" );
-	});
-	
-	it( "formats day padded (d)", () =>
-	{
-		expect( formatDate( date, "d" )).toBe( "21" );
-	});
-	
-	it( "formats day non-padded (j)", () =>
-	{
-		expect( formatDate( date, "j" )).toBe( "21" );
-	});
-	
-	it( "formats zero-padded hour (H)", () =>
-	{
-		expect( formatDate( date, "H" )).toBe( "22" );
-	});
-	
-	it( "formats non-padded hour (G)", () =>
-	{
-		expect( formatDate( date, "G" )).toBe( "22" );
-	});
-	
-	it( "formats minutes (i)", () =>
-	{
-		expect( formatDate( date, "i" )).toBe( "10" );
-	});
-	
-	it( "formats seconds (s)", () =>
-	{
-		expect( formatDate( date, "s" )).toBe( "05" );
-	});
-	
-	it( "formats a custom pattern", () =>
-	{
-		expect( formatDate( date, "d.m.Y H:i" )).toBe( "21.12.2025 22:10" );
-	});
-	
-	it( "supports localized short month (M) in TR", () =>
-	{
-		expect( formatDate( date, "M", "tr" )).toBe( "Ara" ); // Aralık
-	});
-	
-	it( "supports localized long month (MM) in TR", () =>
-	{
-		expect( formatDate( date, "MM", "tr" )).toBe( "Aralık" );
-	});
-	
-	it( "returns empty string for empty pattern", () =>
-	{
-		expect( formatDate( date, "" )).toBe( "" );
-	});
-	
-	it( "leaves unknown tokens as-is", () =>
-	{
-		expect( formatDate( date, "[foo] Y" )).toBe( "[foo] 2025" );
-	});
-	
-	it( "mixes plain text and tokens", () =>
-	{
-		expect( formatDate( date, "d MM Y, H:i" )).toBe( "21 December 2025, 22:10" );
-	});
-});

package/helpers/date/from-timestamp/README.md

@@ -1,14 +0,0 @@
-# fromTimestamp
-This function handles both seconds and milliseconds timestamps by checking the length of the number.
-
-If the `timestamp` is less than `1e11`, it's assumed to be in seconds and is converted to milliseconds. If the conversion results in an invalid `Date` object, the function returns the provided `defaultValue`
-or `undefined` if no default is specified.
-
----
-
-## Usage
-```ts
-import fromTimestamp from '@mark-3/helpers-date-from-timestamp';
-
-const result = fromTimestamp( 1753634780845 );
-```

package/helpers/date/is-on-same-day/README.md

@@ -1,12 +0,0 @@
-# isOnSameDay
-A lightweight utility to check whether two JavaScript `Date` objects are in the same calendar day.
-
----
-
-## Usage
-```ts
-import isOnSameDay from '@mark-3/helpers-date-is-on-same-day';
-
-const result = isOnSameDay( new Date( '2022-01-01' ), new Date( '2022-12-31' ));
-// false
-```

package/helpers/date/is-on-same-year/README.md

@@ -1,13 +0,0 @@
-# isOnSameYear
-A lightweight utility to check whether two JavaScript `Date` objects are in the same calendar year.
-
----
-
-## Usage
-
-```ts
-import isOnSameYear from '@mark-3/helpers-date-is-on-same-year';
-
-const result = isOnSameYear( new Date( '2022-01-01' ), new Date( '2022-12-31' ));
-// true
-```

package/helpers/string/camel-to-dash/README.md

@@ -1,24 +0,0 @@
-# camelToDash
-Converts a camelCase string to dash-case.
-
-* replaces uppercase letters with a dash followed by the lowercase equivalent
-* removes leading and trailing dashes
-* if the input is not a string, returns it unchanged
-
----
-
-## Usage
-```js
-import { camelToDash } from "mark-3/helpers/string";
-
-camelToDash("helloWorld");       // "hello-world"
-camelToDash("backgroundColor");  // "background-color"
-camelToDash("already-dashed");   // "already-dashed"
-camelToDash("already---dashed"); // "already---dashed"
-camelToDash("MyComponent");      // "my-component"
-camelToDash("XMLHttpRequest");   // "x-m-l-http-request"
-camelToDash("someValue123");     // "some-value123"
-camelToDash("---EdgeCase---");   // "edge-case"
-camelToDash(42);                 // 42
-camelToDash(null);               // null
-```

package/helpers/string/escape-regex/README.md

@@ -1,12 +0,0 @@
-# escapeRegex
-Escapes special characters in a string to be used in a regular expression.
-
----
-
-## Usage
-```js
-import { escapeRegex } from "mark-3/helpers/string";
-
-escapeRegex( "foo" );  // => "foo"
-escapeRegex( "foo*" ); // => "foo\*"
-```