mark-3 0.0.4 → 0.0.6

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

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { encodeSuperscript } from "..";
+
+describe("encodeSuperscript", () =>
+{
+	it("converts full match to superscript", () =>
+	{
+		expect(encodeSuperscript("h2o")).toBe("ʰ²ᵒ");
+		expect(encodeSuperscript("123")).toBe("¹²³");
+		expect(encodeSuperscript("abc")).toBe("ᵃᵇᶜ");
+	});
+
+	it("returns original string if any character mismatches and rollbackWhenMismatch is true", () =>
+	{
+		expect(encodeSuperscript("H2O")).toBe("H2O"); // 'H' and 'O' not in map
+		expect(encodeSuperscript("x+2")).toBe("x+2"); // '+' not in map
+	});
+
+	it("fallbacks partially when rollbackWhenMismatch is false", () =>
+	{
+		expect(encodeSuperscript("x+2", false)).toBe("ˣ+²");
+		expect(encodeSuperscript("H2O", false)).toBe("H²O");
+	});
+
+	it("returns non-string inputs as-is", () =>
+	{
+		expect(encodeSuperscript(null)).toBe(null);
+		expect(encodeSuperscript(undefined)).toBe(undefined);
+		expect(encodeSuperscript(123)).toBe(123);
+		expect(encodeSuperscript({})).toEqual({});
+	});
+
+	it("handles empty string correctly", () =>
+	{
+		expect(encodeSuperscript("")).toBe("");
+	});
+
+	it("works with a full string of superscriptable characters", () =>
+	{
+		expect(encodeSuperscript("abcdefghijklmnopqrstuvwxyz", false)).toBe("ᵃᵇᶜᵈᵉᶠᵍʰⁱʲᵏˡᵐⁿᵒᵖqʳˢᵗᵘᵛʷˣʸᶻ");
+	});
+});

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.6",
   "workspaces": [
     "src/*/*"
   ],
@@ -25,5 +25,8 @@
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "vue": "^3.5.18"
   }
 }

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\*"
-```

package/helpers/string/trim/README.md

@@ -1,66 +0,0 @@
-# trim
-A small utility function to trim specific characters from both ends of a string.
-
-Unlike the native `String.prototype.trim()` which only removes whitespace, this function lets you specify exactly which characters to trim — including special characters or a list of them.
-
----
-
-## Features
-- Trim custom characters from the **start and end** of a string
-- Accepts either a **single character string** or an **array of characters**
-- Automatically escapes special regex characters
-- Ignores non-string input safely
-
----
-
-## Usage
-```js
-import { trim } from "mark-3/helpers/string";
-
-// Default whitespace trim
-trim("   Hello world   "); 
-// => "Hello world"
-
-// Trim specific character
-trim("---Hello---", "-"); 
-// => "Hello"
-
-// Trim multiple characters
-trim("..//Hello//..", [".", "/"]); 
-// => "Hello"
-
-// No trim if input is not a string
-trim(42, "-"); 
-// => 42
-
-// Empty trim characters (returns input as-is)
-trim("text", ""); 
-// => "text"
-
-// trim characters as a pattern
-trim(":::text:::_", ":::" ); 
-// => "text:::_"
-```
-
----
-
-## Parameters
-```ts
-trim(input: string, chars?: string | string[]): string
-```
-
-| Name  | Type                 | Default | Description                             |
-| ----- | -------------------- | ------- | --------------------------------------- |
-| input | `string`             | —       | The string to be trimmed                |
-| chars | `string \| string[]` | `" "`   | The character(s) to trim from both ends |
-
-If chars is a string of multiple characters, each character will be treated individually and removed if present at the start or end.
-
-**Behavior Details**
-If chars is an array: All characters in the array will be treated as individual characters to trim.
-
-If chars is a string:
-* A single-character string: trimmed directly like a single items array.
-* A multi-character string: each character as a whole.
-
-All special characters like ., *, +, ^ are automatically escaped — no need to handle them manually.

package/helpers/types/get-type-name/README.md

@@ -1,11 +0,0 @@
-# getTypeName
-Returns the name of a variable's type.
-
----
-
-## Usage
-```js
-import { getTypeName } from "mark-3/helpers/types";
-
-getTypeName({}); // 'Object'
-```

package/helpers/types/is-array/README.md

@@ -1,11 +0,0 @@
-# isArray
-Checks if a value is an array.
-
----
-
-## Usage
-```js
-import { isArray } from "mark-3/helpers/types";
-
-isArray([ 1, 2, 3 ]); // true
-```