mark-3 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.4](https://github.com/ismailceylan/mark-3/compare/v0.0.3...v0.0.4) (2025-08-02)
+
+
+### Features
+
+* **composables:** add new use-responsiveness composable ([3b6ebe4](https://github.com/ismailceylan/mark-3/commit/3b6ebe4f0c50668453071cf4146b3dc459a25f24))
+* **helpers:** add new types/is-map method ([fdcda02](https://github.com/ismailceylan/mark-3/commit/fdcda0239aab54951df1c708dee7e74989801c79))
+* **helpers:** add new types/is-set method ([618abbe](https://github.com/ismailceylan/mark-3/commit/618abbeb6f068774dfa4c6158302fd7ac5f7fccc))
+
+
+### Bug Fixes
+
+* **helpers:** ensures that the default argument value is used for chars on string/trim method ([645f41e](https://github.com/ismailceylan/mark-3/commit/645f41e883b8777a16e4773ed520411e9953a45b))
+
+### [0.0.3](https://github.com/ismailceylan/mark-3/compare/v0.0.2...v0.0.3) (2025-08-02)
+
+
+### Features
+
+* **composables:** add new use-event-listener composable ([58bee94](https://github.com/ismailceylan/mark-3/commit/58bee94286d6736fee813f2286a3bd33031d58b2))
+* **composables:** add new use-media-query composable ([b76da8a](https://github.com/ismailceylan/mark-3/commit/b76da8a083e13e60c967c90f8116aaa3c735c74f))
+* **helpers:** add new escape-regex helper ([78ba818](https://github.com/ismailceylan/mark-3/commit/78ba818542c8325809d72ec7920f2aa14cd053d0))
+* **helpers:** add new get-type-name helper ([12cc26c](https://github.com/ismailceylan/mark-3/commit/12cc26c83335f96af408d90b5accab3aaa5f6d32))
+* **helpers:** add new is-array helper ([b8b95f6](https://github.com/ismailceylan/mark-3/commit/b8b95f652677f6dc6079b34cd97bcb64671db75c))
+* **helpers:** add new string/camel-to-dash helper ([fbbbcf0](https://github.com/ismailceylan/mark-3/commit/fbbbcf0570b38ccabbd44044ca9054d3dccdaafd))
+* **helpers:** add new string/trim helper ([cfd40a3](https://github.com/ismailceylan/mark-3/commit/cfd40a3a4741bb0ffe8bcc184f623cb6c6f39c6c))
+* **helpers:** add new types/is-empty helper ([151a547](https://github.com/ismailceylan/mark-3/commit/151a547d2ab89e47b5d9f85bad080af82d4e02a4))
+* **helpers:** add new types/is-plain-object method ([98a7804](https://github.com/ismailceylan/mark-3/commit/98a780415f4d1b086075be042b8467509fb2815d))
+* **helpers:** add new types/is-string helper ([2ee5197](https://github.com/ismailceylan/mark-3/commit/2ee51979235a674d63a3d8c9381f37ccc84ecfd7))
+
 ### [0.0.2](https://github.com/ismailceylan/mark-3/compare/v0.0.1...v0.0.2) (2025-08-01)
 
 

package/composables/index.js

@@ -0,0 +1,3 @@
+export { default as useMediaQuery } from "./use-media-query.js";
+export { default as useEventListener } from "./use-event-listener.js";
+export { default as useResponsiveness } from "./use-responsiveness.js";

package/composables/use-event-listener.js

@@ -0,0 +1,40 @@
+import { onMounted, onUnmounted, getCurrentInstance } from "vue";
+
+/**
+ * A composition function that adds a DOM event listener to the given target with the
+ * given event name and callback. The options object is optional. If the composition
+ * function is called from within a component, then the event listener is added when
+ * the component is mounted and removed when the component is unmounted. If the
+ * composition function is called outside of a component, then the event listener is
+ * added immediately and must be removed manually by calling the returned function.
+ *
+ * @param {Element} target - The target element to add the event listener to.
+ * @param {string} eventName - The name of the event to add a listener for.
+ * @param {function} callBack - The callback function to call when the event happens.
+ * @param {object} [options] - The options object to pass to addEventListener.
+ * @returns {function} - A function that can be called to remove the event listener.
+ */
+export default function useEventListener( target, eventName, callBack, options )
+{
+	if( getCurrentInstance())
+	{
+		onMounted( listen );
+		onUnmounted( stop );
+	}
+	else
+	{
+		listen();
+	}
+
+	function listen()
+	{
+		target.addEventListener( eventName, callBack, options );
+	}
+
+	function stop()
+	{
+		target.removeEventListener( eventName, callBack );
+	}
+
+	return stop;
+}

package/composables/use-media-query.js

@@ -0,0 +1,34 @@
+import { ref } from "vue";
+import { useEventListener } from ".";
+
+/**
+ * Creates a reactive reference that tracks whether the given media query matches the current viewport.
+ *
+ * @typedef {import('vue').Ref} Ref
+ * @param {string} query - A valid media query string.
+ * @param {function(boolean)} [watcher] - A function that will be called whenever the match status changes.
+ * The function will receive the current match status as a boolean argument.
+ * @returns {Ref<boolean>} A reactive reference to the match status.
+ * @example
+ * const isMobileRef = useMediaQuery( "(max-width: 767px)", matches =>
+ *    console.log( matches )
+ * );
+ */
+export default function useMediaQuery( query, watcher )
+{
+	const match = matchMedia( query );
+	const matches = ref( match.matches );
+
+	triggerWatcher();
+
+	useEventListener( match, "change", e =>
+		triggerWatcher( matches.value = e.matches )
+	);
+
+	function triggerWatcher()
+	{
+		watcher && watcher( matches.value );
+	}
+
+	return matches;
+}

package/composables/use-responsiveness.js

@@ -0,0 +1,61 @@
+import { reactive, toRefs } from "vue";
+import { camelToDash } from "../helpers/string";
+import { useMediaQuery } from ".";
+
+/**
+ * Reactive media query states for multiple breakpoints at once using
+ *   useMediaQuery composable under the hood and returns an object of
+ *   reactive media query states.
+ * 
+ * The object keys are the same as the keys of the rules object.
+ * 
+ * If the media queries you pass to the useResponsiveness composable
+ *   are min- prefixed, the relevant props of returned object will be
+ *   true if the screen is at least or more in that breakpoint. But if
+ *   the queries are min- and max- prefixed, the relevant props of the
+ *   reactive object that returned will be true if the screen is exactly
+ *   in that breakpoint.
+ * 
+ * You can pass any valid media query to the useResponsiveness composable
+ *   like color schemes, display modes, and more.
+ * 
+ * @typedef {import('vue').Ref} Ref
+ * @typedef {import('vue').Reactive} Reactive
+ * @param {Object} rules Object of media queries
+ * @returns {Reactive<{}>|Ref<boolean>} Object of reactive media query states
+ * @example
+ * const breakpoints = useResponsiveness({
+ *     mobile: "(max-width: 767px)",
+ *     tablet: "(min-width: 768px) and (max-width: 1023px)",
+ *     desktop: "(min-width: 1024px)",
+ * });
+ * // { mobile: false, tablet: false, desktop: true}
+ * // every property tells the screen is exactly in that breakpoint
+ * @example
+ * const breakpoints = useResponsiveness({
+ *     mobile: "(min-width: 300px)",
+ *     tablet: "(min-width: 768px)",
+ *     desktop: "(min-width: 1024px)",
+ * });
+ * // { mobile: true, tablet: true, desktop: false}
+ * // every property tells the screen is at least or more in that breakpoint
+ */
+export default function useResponsiveness( rules = {})
+{
+	const breakpoints = reactive({});
+	const keys = Object.keys( rules );
+
+	for( const name in rules )
+	{
+		useMediaQuery( rules[ name ], isActive =>
+			breakpoints[ camelToDash( name )] = isActive
+		);
+	}
+
+	if( keys.length === 1 )
+	{
+		return toRefs( breakpoints )[ keys[ 0 ]];
+	}
+
+	return breakpoints;
+}

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

@@ -0,0 +1,24 @@
+# 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/camel-to-dash/index.js

@@ -0,0 +1,23 @@
+import { trim } from "..";
+import { isString } from "../../types";
+
+/**
+ * Converts a camelCase string to dash-case.
+ *
+ * @param {string} source - The camelCase string to convert.
+ * @returns {string} The converted dash-case string. If the input is not a string, returns the input as is.
+ */
+export default function camelToDash( source )
+{
+	if( ! isString( source ))
+	{
+		return source;
+	}
+
+	source = source.replace(
+		/([A-Z])/g,
+		upper => "-" + upper.toLowerCase()
+	);
+
+	return trim( source, "-" );
+}

package/helpers/string/camel-to-dash/index.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import camelToDash from ".";
+
+describe( "camelToDash", () =>
+{
+	it( "converts camelCase to dash-case", () =>
+	{
+		expect( camelToDash( "helloWorld" )).toBe( "hello-world" );
+		expect( camelToDash( "mySuperVariable" )).toBe( "my-super-variable" );
+		expect( camelToDash( "alreadyDashCase" )).toBe( "already-dash-case" );
+	});
+
+	it( "handles strings with multiple uppercase letters in a row", () =>
+	{
+		expect( camelToDash( "PDFLoader" )).toBe( "p-d-f-loader" );
+		expect( camelToDash( "loadXMLDocument" )).toBe( "load-x-m-l-document" );
+	});
+
+	it( "trims dashes from the beginning and end", () =>
+	{
+		expect( camelToDash( "CamelCase" )).toBe( "camel-case" );
+		expect( camelToDash( "AB" )).toBe( "a-b" );
+		expect( camelToDash( "A" )).toBe( "a" );
+	});
+
+	it( "returns empty string when input is empty", () =>
+	{
+		expect( camelToDash( "" )).toBe( "" );
+	});
+
+	it( "returns non-string inputs unchanged", () =>
+	{
+		expect( camelToDash( null )).toBe( null );
+		expect( camelToDash( undefined )).toBe( undefined );
+		expect( camelToDash( 123 )).toBe( 123 );
+		expect( camelToDash({})).toEqual({});
+		expect( camelToDash([ "camelCase" ])).toEqual([ "camelCase" ]);
+	});
+});

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

@@ -0,0 +1,12 @@
+# 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/escape-regex/index.js

@@ -0,0 +1,20 @@
+import { isString } from "../../types";
+
+/**
+ * Escapes special characters in a string to be used in a regular expression.
+ *
+ * @param {string} str - The input string containing characters to be escaped.
+ * @returns {string} The modified string with special characters escaped.
+ */
+export default function escapeRegex( str )
+{
+	if( ! isString( str ))
+	{
+		return "";
+	}
+
+	return str.replace(
+		/[.*+?^${}()|[\]\\]/g,
+		"\\$&"
+	);
+}

package/helpers/string/escape-regex/index.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import escapeRegex from ".";
+
+describe( "escapeRegex", () =>
+{
+	it( "should escape all special regex characters", () =>
+	{
+		const input = ".*+?^${}()|[]\\";
+		const expected = "\\.\\*\\+\\?\\^\\$\\{\\}\\(\\)\\|\\[\\]\\\\";
+	
+		expect( escapeRegex( input )).toBe( expected );
+	});
+	
+	it( "should return the same string if there are no special characters", () =>
+	{
+		expect( escapeRegex( "abc123" )).toBe( "abc123" );
+	});
+
+	it( "should handle mixed characters", () =>
+	{
+		expect( escapeRegex( "file(name).js" )).toBe( "file\\(name\\)\\.js" );
+	});
+
+	it( "should return an empty string when input is an empty string", () =>
+	{
+		expect( escapeRegex( "" )).toBe( "" );
+	});
+
+	it( "should return an empty string when input is null", () =>
+	{
+		expect( escapeRegex( null )).toBe( "" );
+	});
+
+	it( "should return an empty string when input is undefined", () =>
+	{
+		expect( escapeRegex( undefined )).toBe( "" );
+	});
+
+	it( "should return an empty string when input is a number", () =>
+	{
+		expect( escapeRegex( 12345 )).toBe( "" );
+	});
+
+	it( "should return an empty string when input is an object", () =>
+	{
+		expect( escapeRegex({})).toBe( "" );
+	});
+
+	it( "should return an empty string when input is an array", () =>
+	{
+		expect( escapeRegex([])).toBe( "" );
+	});
+	
+	it( "should return an empty string when input is a function", () =>
+	{
+		expect( escapeRegex(() => {})).toBe( "" );
+	});
+});

package/helpers/string/index.js

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

package/helpers/string/trim/README.md

@@ -0,0 +1,66 @@
+# 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/string/trim/index.js

@@ -0,0 +1,33 @@
+import { escapeRegex } from "..";
+import { isEmpty, isArray, isString } from "../../types";
+
+/**
+ * Trims the specified characters from the beginning and end of a string.
+ *
+ * @param {string} input - The string to trim.
+ * @param {string|string[]} [chars=" "] - The character(s) to trim. Can be a single
+ * character or array of characters.
+ * @returns {string} The trimmed string.
+ */
+export default function trim( input, chars = " " )
+{
+	if( ! isString( input ) || ( chars !== " " && isEmpty( chars )))
+	{
+		return input;
+	}
+
+	const patternStr = isArray( chars )
+		? makePattern( chars.map( escapeRegex ).join( "" ), "b" )
+		: makePattern( escapeRegex( chars ));
+
+	const pattern = new RegExp( patternStr, "g" );
+
+	function makePattern( escaped, type )
+	{
+		return type == "b"
+			? `^[${escaped}]+|[${escaped}]+$`
+			: `^${escaped}+|${escaped}+$`;
+	}
+
+	return input.replace( pattern, "" );
+}

package/helpers/string/trim/index.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import trim from ".";
+
+describe( "trim", () =>
+{
+	it( "should trim spaces by default", () =>
+	{
+		expect( trim( "  hello  " )).toBe( "hello" );
+	});
+
+	it( "should trim custom character from both ends (single char)", () =>
+	{
+		expect( trim( "--hello--", "-" )).toBe( "hello" );
+	});
+
+	it( "should trim multiple characters (array)", () =>
+	{
+		expect( trim( "-_=hello=_-", [ "-", "_", "=" ])).toBe( "hello" );
+	});
+
+	it( "should not trim characters in the middle", () =>
+	{
+		expect( trim( "--he--llo--", "-" )).toBe( "he--llo" );
+	});
+
+	it( "should return input unchanged if it is not a string", () =>
+	{
+		expect( trim( 12345, "-" )).toBe( 12345 );
+		expect( trim( null, "-" )).toBe( null );
+		expect( trim( undefined, "-" )).toBe( undefined );
+	});
+
+	it( "should return the same string if chars is empty string", () =>
+	{
+		expect( trim( "abc", "" )).toBe( "abc" );
+	});
+
+	it( "should return the same string if chars is an empty array", () =>
+	{
+		expect( trim( "abc", [])).toBe( "abc" );
+	});
+
+	it( "should return empty string if input is empty", () =>
+	{
+		expect( trim( "" )).toBe( "" );
+	});
+
+	it( "should trim regex special characters properly", () =>
+	{
+		expect( trim( ".*hello.*", [ ".", "*" ])).toBe( "hello" );
+	});
+
+	it( "should trim only from start and end, not inside", () =>
+	{
+		expect( trim( "***abc***xyz***", "*" )).toBe( "abc***xyz" );
+	});
+
+	it( "should trim multiple different characters in mixed order", () =>
+	{
+		expect( trim( "-_-abc-_--", [ "-", "_" ])).toBe( "abc" );
+	});
+});

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

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

package/helpers/types/get-type-name/index.js

@@ -0,0 +1,13 @@
+/**
+ * Returns the type name of a given variable.
+ *
+ * @param {any} variable - The variable whose type name is to be determined.
+ * @return {string} The type name of the variable.
+ */
+export default function getTypeName( variable ) 
+{
+	return Object.prototype
+		.toString
+		.call( variable )
+		.match( /\[object (.*)\]/ )[ 1 ];
+}

package/helpers/types/get-type-name/index.test.js

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import getTypeName from ".";
+
+describe( "type", () =>
+{
+	it( 'should return "String" for a string', () =>
+	{
+		expect( getTypeName( "hello" )).toBe( "String" );
+	});
+
+	it( 'should return "Number" for a number', () =>
+	{
+		expect( getTypeName( 123 )).toBe( "Number" );
+	});
+
+	it( 'should return "Boolean" for a boolean', () =>
+	{
+		expect( getTypeName( true )).toBe( "Boolean" );
+		expect( getTypeName( false )).toBe("Boolean" );
+	});
+
+	it( 'should return "Object" for an object', () =>
+	{
+		expect( getTypeName({})).toBe( "Object" );
+	});
+
+	it( 'should return "Array" for an array', () =>
+	{
+		expect( getTypeName([])).toBe( "Array" );
+	});
+
+	it( 'should return "Null" for null', () =>
+	{
+		expect( getTypeName( null )).toBe( "Null" );
+	});
+
+	it( 'should return "Undefined" for undefined', () =>
+	{
+		expect( getTypeName( undefined )).toBe( "Undefined" );
+	});
+	
+	it( 'should return "Function" for a function', () =>
+	{
+		expect( getTypeName(() => {})).toBe( "Function" );
+	});
+
+	it( 'should return "RegExp" for a regular expression', () =>
+	{
+		expect( getTypeName( /abc/ )).toBe( 'RegExp' );
+	});
+
+	it( 'should return "Date" for a Date object', () =>
+	{
+		expect( getTypeName( new Date())).toBe( "Date" );
+	});
+
+	it( 'should return "Error" for an Error object', () =>
+	{
+		expect( getTypeName( new Error( "Something went wrong" ))).toBe( 'Error' );
+	});
+
+	it( 'should return "Symbol" for a Symbol', () =>
+	{
+		expect( getTypeName( Symbol( "foo" ))).toBe( "Symbol" );
+	});
+
+	it( 'should return "BigInt" for a BigInt', () =>
+	{
+		expect( getTypeName( 123n )).toBe( "BigInt" );
+	});
+});

package/helpers/types/index.js

@@ -0,0 +1,7 @@
+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 getTypeName } from "./get-type-name";
+export { default as isPlainObject } from "./is-plain-object";

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

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

package/helpers/types/is-array/index.js

@@ -0,0 +1,10 @@
+/**
+ * Checks if a value is an array.
+ * 
+ * @param {*} value
+ * @return {boolean}
+ */
+export default function isArray( value )
+{
+	return Array.isArray( value );
+}

package/helpers/types/is-array/index.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import isArray from ".";
+
+describe( "isArray", () =>
+{
+	it( "should return true for an empty array", () =>
+	{
+    	expect( isArray([])).toBe( true );
+	});
+
+	it( "should return true for a non-empty array", () =>
+	{
+		expect( isArray([ 1, 2, 3 ])).toBe( true );
+	});
+
+	it( "should return false for a string", () =>
+	{
+		expect( isArray( "hello" )).toBe( false );
+	});
+	
+	it( "should return false for a number", () =>
+	{
+		expect( isArray( 123 )).toBe( false );
+	});
+
+	it( "should return false for null", () =>
+	{
+		expect( isArray( null )).toBe( false );
+	});
+
+	it( "should return false for undefined", () =>
+	{
+		expect( isArray( undefined )).toBe( false );
+	});
+
+	it( "should return false for an object", () =>
+	{
+		expect( isArray({ a: 1 })).toBe( false );
+	});
+	
+	it( "should return false for a function", () =>
+	{
+		expect( isArray(() => {})).toBe( false );
+	});
+	
+	it( "should return false for a Set", () =>
+	{
+		expect( isArray( new Set([ 1, 2, 3 ]))).toBe( false );
+	});
+	
+	it( "should return false for an Array-like object", () =>
+	{
+    	const arrayLike = { 0: "a", 1: "b", length: 2 };
+		expect( isArray( arrayLike )).toBe( false );
+	});
+});

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

@@ -0,0 +1,35 @@
+# isEmpty
+Checks if the given variable is empty.
+
+If the variable is an object, it is considered empty if it has no keys.
+If the variable is an array, it is considered empty if it has no elements.
+If the variable is a map or a set, it is considered empty if it has no size.
+If the variable is a string, it is considered empty if it is trimmed to be an empty string.
+If the variable is undefined or null, it is considered empty.
+
+Otherwise, it is not considered empty.
+
+---
+
+## Usage
+
+```js
+import { isEmpty } from 'mark-3/helpers/types/isEmpty';
+
+isEmpty( '' ); // true
+isEmpty( '     ' ); // true
+isEmpty([]); // true
+isEmpty({}); // true
+isEmpty( new Map()); // true
+isEmpty( new Set()); // true
+isEmpty( null ); // true
+isEmpty( undefined ); // true
+
+isEmpty( 'foo' ); // false
+isEmpty([ 'foo' ]); // false
+isEmpty({ foo: 'bar' }); // false
+isEmpty( new Map([ 'foo', 'bar' ])); // false
+isEmpty( new Set([ 'foo' ])); // false
+isEmpty({ foo: 'bar' }); // false
+isEmpty(() => {}); // false
+```

package/helpers/types/is-empty/index.js

@@ -0,0 +1,45 @@
+import { isString, isArray, isMap, isSet, isPlainObject } from "..";
+
+/**
+ * Checks if the given variable is empty.
+ *
+ * If the variable is an object, it is considered empty if it has no keys.
+ * If the variable is an array, it is considered empty if it has no elements.
+ * If the variable is a map or a set, it is considered empty if it has no size.
+ * If the variable is a string, it is considered empty if it is trimmed to be an empty string.
+ * If the variable is undefined or null, it is considered empty.
+ *
+ * Otherwise, it is not considered empty.
+ *
+ * @param {*} variable the variable to check
+ * @return {Boolean} true if the variable is empty, false otherwise
+ */
+export default function isEmpty( variable )
+{
+	if( isPlainObject( variable ))
+	{
+		return Object.keys( variable ).length === 0;
+	}
+
+	if( isArray( variable ))
+	{
+		return variable.length === 0;
+	}
+
+	if( isMap( variable ) || isSet( variable ))
+	{
+		return variable.size === 0;
+	}
+
+	if( isString( variable ))
+	{
+		return variable.trim() === "";
+	}
+
+	if( variable === undefined || variable === null )
+	{
+		return true;
+	}
+
+	return false;
+}

package/helpers/types/is-empty/index.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import isEmpty from ".";
+
+describe( "isEmpty", () =>
+{
+	// Null & undefined
+	it( "should return true for null and undefined", () =>
+	{
+		expect( isEmpty( null )).toBe( true );
+		expect( isEmpty( undefined )).toBe( true );
+	});
+
+	// Strings
+	it( "should return true for empty and whitespace-only strings", () =>
+	{
+		expect( isEmpty( "" )).toBe( true );
+		expect( isEmpty( "   " )).toBe( true );
+	});
+
+	it( "should return false for non-empty strings", () =>
+	{
+		expect( isEmpty( "hello" )).toBe( false );
+		expect( isEmpty( "  test  " )).toBe( false );
+	});
+
+	// Arrays
+	it( "should return true for empty arrays", () =>
+	{
+		expect( isEmpty([] )).toBe( true );
+	});
+
+	it( "should return false for non-empty arrays", () =>
+	{
+		expect( isEmpty([1] )).toBe( false );
+	});
+
+	// Plain objects
+	it( "should return true for empty plain objects", () =>
+	{
+		expect( isEmpty({} )).toBe( true );
+	});
+
+	it( "should return false for non-empty plain objects", () =>
+	{
+		expect( isEmpty({ a: 1 } )).toBe( false );
+	});
+
+	// Map
+	it( "should return true for empty Map", () =>
+	{
+		expect( isEmpty(new Map( ))).toBe( true );
+	});
+
+	it( "should return false for non-empty Map", () =>
+	{
+		const map = new Map();
+		map.set( "key", "value");
+		expect( isEmpty(map )).toBe( false );
+	});
+
+	// Set
+	it( "should return true for empty Set", () =>
+	{
+		expect( isEmpty(new Set( ))).toBe( true );
+	});
+	
+	it( "should return false for non-empty Set", () =>
+	{
+		const set = new Set();
+		set.add(1);
+		expect( isEmpty(set )).toBe( false );
+	});
+
+	// Other types
+	it( "should return false for other types", () =>
+	{
+		expect( isEmpty(0 )).toBe( false );
+		expect( isEmpty(false )).toBe( false );
+		expect( isEmpty(NaN )).toBe( false );
+		expect( isEmpty(Symbol( ))).toBe( false );
+		expect( isEmpty(() => {} )).toBe( false );
+		expect( isEmpty(new Date( ))).toBe( false );
+	});
+});

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

@@ -0,0 +1,15 @@
+# isMap
+Utility function to check if a value is a native `Map` object in JavaScript.
+
+---
+
+## Usage
+```js
+import { isMap } from "@mark-3/helpers/types";
+
+isMap(new Map());     // true
+isMap(new WeakMap()); // false
+isMap({});            // false
+isMap([]);            // false
+isMap(null);          // false
+```

package/helpers/types/is-map/index.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-map/index.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/is-plain-object/README.md

@@ -0,0 +1,17 @@
+# isPlainObject
+A utility function to check if a value is a plain object.
+
+## Usage
+```js
+import { isPlainObject } from "mark-3/helpers/types";
+
+isPlainObject({});                       // true
+isPlainObject({ a: 1 });                 // true
+isPlainObject(Object.create(null));      // true
+isPlainObject([]);                       // false
+isPlainObject(null);                     // false
+isPlainObject(new Date());               // false
+isPlainObject(function(){});             // false
+isPlainObject(new Map());                // false
+isPlainObject(new ( class MyClass{})()); // false
+```

package/helpers/types/is-plain-object/index.js

@@ -0,0 +1,17 @@
+/**
+ * Checks if the given value is a plain object.
+ *
+ * @param {any} value - The value to be checked.
+ * @return {boolean} true if the value is a plain object, false otherwise.
+ */
+export default function isPlainObject( value )
+{
+	if( typeof value !== "object" || value === null )
+	{
+		return false;
+	}
+
+	const proto = Object.getPrototypeOf( value );
+	
+	return proto === Object.prototype || proto === null;
+}

package/helpers/types/is-plain-object/index.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import isPlainObject from ".";
+
+describe("isPlainObject", () =>
+{
+	it("returns true for plain object literals", () =>
+	{
+		expect(isPlainObject({})).toBe(true);
+		expect(isPlainObject({ a: 1, b: 2 })).toBe(true);
+	});
+
+	it("returns true for Object created with constructor", () =>
+	{
+		expect(isPlainObject(new Object())).toBe(true);
+	});
+
+	it("returns true for Object.create(null)", () =>
+	{
+		expect(isPlainObject(Object.create(null))).toBe(true);
+	});
+
+	it("returns false for arrays", () =>
+	{
+		expect(isPlainObject([])).toBe(false);
+		expect(isPlainObject([1, 2, 3])).toBe(false);
+	});
+
+	it("returns false for null", () =>
+	{
+		expect(isPlainObject(null)).toBe(false);
+	});
+
+	it("returns false for functions", () =>
+	{
+		expect(isPlainObject(function () {})).toBe(false);
+		expect(isPlainObject(() => {})).toBe(false);
+	});
+
+	it("returns false for primitive values", () =>
+	{
+		expect(isPlainObject(123)).toBe(false);
+		expect(isPlainObject("string")).toBe(false);
+		expect(isPlainObject(true)).toBe(false);
+		expect(isPlainObject(undefined)).toBe(false);
+		expect(isPlainObject(Symbol("sym"))).toBe(false);
+	});
+
+	it("returns false for built-in objects like Date, RegExp, Map, Set", () =>
+	{
+		expect(isPlainObject(new Date())).toBe(false);
+		expect(isPlainObject(/regex/)).toBe(false);
+		expect(isPlainObject(new Map())).toBe(false);
+		expect(isPlainObject(new Set())).toBe(false);
+	});
+
+	it("returns false for class instances", () =>
+	{
+		class MyClass {}
+		expect(isPlainObject(new MyClass())).toBe(false);
+	});
+});

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

@@ -0,0 +1,15 @@
+# isSet
+Utility function to check if a value is a native `Set` object in JavaScript.
+
+---
+
+## Usage
+```js
+import { isSet } from "mark-3/helpers/types";
+
+isSet(new Set());     // true
+isSet(new WeakSet()); // false
+isSet({});            // false
+isSet([]);            // false
+isSet(null);          // false
+```

package/helpers/types/is-set/index.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/is-set/index.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/is-string/README.md

@@ -0,0 +1,12 @@
+# isString
+Checks if a value is a string.
+
+---
+
+## Usage
+```js
+import { isString } from "mark-3/helpers/types";
+
+isString( "foo" ); // true
+isString(1); // false
+```

package/helpers/types/is-string/index.js

@@ -0,0 +1,10 @@
+/**
+ * Checks if a value is a string.
+ * 
+ * @param {*} value
+ * @return {boolean}
+ */
+export default function isString( value )
+{
+	return typeof value === "string";
+}

package/helpers/types/is-string/index.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.2",
+  "version": "0.0.4",
   "workspaces": [
     "src/*/*"
   ],

package/vitest.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      enabled: true,
+      reporter: ["text", "json", "html"],
+      include: ["*/*/*/"],
+    },
+    environment: "node",
+  },
+});

package/helpers/date/is-on-same-year/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "@mark-3/helpers-date-is-on-same-year",
-  "type": "module",
-  "version": "0.0.3",
-  "description": "Checks if two Date objects fall within the same year.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "release": "standard-version",
-    "publish-package": "npm publish --access=public"
-  },
-  "standard-version": {
-    "tagPrefix": "@mark-3/helpers/date/is-on-same-year@"
-  },
-  "keywords": [
-    "date",
-    "helper",
-    "year",
-    "compare",
-    "utility"
-  ],
-  "author": "Ismail Ceylan",
-  "license": "MIT"
-}

package/vitest.config.ts

@@ -1,12 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    coverage: {
-      enabled: true,
-      reporter: ['text', 'json', 'html'],
-      include: ['*/*/*/'],
-    },
-    environment: 'node',
-  },
-});