mark-3 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+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.2](https://github.com/ismailceylan/mark-3/compare/v0.0.1...v0.0.2) (2025-08-01)
+
+
+### Features
+
+* **helpers:** add new date/format helper ([9d2eb12](https://github.com/ismailceylan/mark-3/commit/9d2eb12c8595785d0b40ec740612ecdc407e4fe2))
+* **helpers:** add new date/from-timestamp helper ([812163f](https://github.com/ismailceylan/mark-3/commit/812163f84a11e53f77b7f291ccad8f1b3bd88631))
+* **helpers:** add new date/is-on-same-day helper ([8fe86fc](https://github.com/ismailceylan/mark-3/commit/8fe86fcff57d51803307f12f7e78310999f0acb2))
+* **helpers:** add new date/is-on-same-year helper ([f29123a](https://github.com/ismailceylan/mark-3/commit/f29123a2997e294c2672bb450124e0b571b6d730))
+
+### 0.0.1 (2025-08-01)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 İsmail Ceylan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# mark-3
+Modular collection of reusable JavaScript helpers, utilities, and Vue components. Built for maintainability, performance, and clarity.

package/helpers/date/format/README.md

@@ -0,0 +1,33 @@
+# 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.js

@@ -0,0 +1,60 @@
+/**
+ * Format a date according to a given pattern.
+ *
+ * @param {Date} date The date to format.
+ * @param {string} pattern The pattern to use for formatting the date.
+ * @param {string} [lang="en"] The language to use for month names.
+ * @returns {string} The formatted date string.
+ *
+ * Supported patterns:
+ *
+ * - d: 01-31 (zero-padded day of the month)
+ * - j:  1-31 (day of the month)
+ * - m: 01-12 (zero-padded month)
+ * - n:  1-12 (month)
+ * - M: January-December (month name, localized for the given language)
+ * - y: 00-99 (2-digit year)
+ * - Y: 0000-9999 (4-digit year)
+ * - H: 00-23 (zero-padded hour in 24-hour format)
+ * - G:  0-23 (hour in 24-hour format)
+ * - i: 00-59 (zero-padded minute)
+ * - s: 00-59 (zero-padded second)
+ */
+export default function formatDate( date, pattern, lang = "en" )
+{
+	function pad( n, len = 2 )
+	{
+		return n.toString().padStart( len, "0" );
+	}
+
+	const replacements =
+	{
+		// Day
+		d: pad( date.getDate()),	   // 01-31
+		j: date.getDate().toString(),  //  1-31
+
+		// Month
+		m: pad( date.getMonth() + 1 ),         // 01-12
+		n: ( date.getMonth() + 1 ).toString(), //  1-12
+		M:  new Intl.DateTimeFormat( lang, { month: "short" }).format( date ),
+		MM: new Intl.DateTimeFormat( lang, { month: "long"  }).format( date ),
+
+		// Year
+		y: date.getFullYear().toString().slice( -2 ), // 2 digit year
+		Y: date.getFullYear().toString(),             // 4 digit year
+
+		// Hour
+		H: pad( date.getHours()),	   // 00-23
+		G: date.getHours().toString(), //  0-23
+
+		// Minute
+		i: pad( date.getMinutes()),	 // 00-59
+
+		// Second
+		s: pad( date.getSeconds()),	// 00-59
+	}
+
+	return pattern.replace( /d|j|m|n|MM|M|y|Y|H|G|i|s/g, match =>
+		replacements[ match ]
+	);
+}

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

@@ -0,0 +1,97 @@
+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

@@ -0,0 +1,14 @@
+# 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/from-timestamp/index.js

@@ -0,0 +1,34 @@
+/**
+ * Converts a Unix timestamp to a JavaScript Date object.
+ * 
+ * @template T
+ * @param {number|string} timestamp - The Unix timestamp in seconds or milliseconds, or a string that can be converted to a number.
+ * @param {T} [defaultValue] - The value to return if timestamp is invalid or results in an invalid Date.
+ * @returns {Date|T|undefined} A Date object representing the timestamp, or the defaultValue if the timestamp is invalid.
+ * 
+ * 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.
+ */
+export default function fromTimestamp( timestamp, defaultValue )
+{
+	const ts = typeof timestamp === "string"
+		? Number( timestamp )
+		: timestamp;
+
+	if( Number.isNaN( ts ))
+	{
+		return defaultValue;
+	}
+
+	const time = ts < 1e11
+		? ts * 1000
+		: ts;
+
+	const date = new Date( time );
+
+	return isNaN( date.getTime())
+  		? defaultValue
+		: date;
+}

package/helpers/date/from-timestamp/index.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import fromTimestamp from "./index";
+
+describe( "fromTimestamp", () =>
+{
+	it( "should parse milliseconds timestamp correctly", () =>
+	{
+		const now = Date.now();
+		const result = fromTimestamp( now );
+
+		expect( result ).toBeInstanceOf( Date );
+		expect( result?.getTime()).toBe( now );
+	});
+
+	it( "should parse seconds timestamp correctly", () =>
+	{
+		const now = Math.floor( Date.now() / 1000 );
+		const result = fromTimestamp( now );
+
+		expect( result ).toBeInstanceOf( Date );
+		expect( Math.floor( result?.getTime() / 1000 )).toBe( now );
+	});
+
+	it( "should return defaultValue for non-number input", () =>
+	{
+		const result = fromTimestamp( "not-a-number", "default" );
+		expect( result ).toBe( "default" );
+	});
+
+	it( "should return defaultValue for NaN date", () =>
+	{
+    	const result = fromTimestamp( NaN, "fallback" );
+		expect( result ).toBe( "fallback" );
+	});
+
+	it( "should return undefined for invalid input without default", () =>
+	{
+		expect( fromTimestamp( NaN )).toBeUndefined();
+	});
+
+	it( "should support boolean as default value", () =>
+	{
+    	const result = fromTimestamp( NaN, false );
+		expect( result ).toBe( false );
+	});
+
+	it( "should support object as default value", () =>
+	{
+    	const fallback = { error: true }
+    	const result = fromTimestamp( NaN, fallback );
+    
+		expect( result ).toBe( fallback );
+	});
+
+	it( "should return defaultValue for Infinity", () =>
+	{
+		expect( fromTimestamp( Infinity, "fallback" )).toBe( "fallback" );
+	});
+
+	it( "should return undefined for Infinity without defaultValue", () =>
+	{
+		expect( fromTimestamp( Infinity )).toBe( undefined );
+	});
+});

package/helpers/date/index.js

@@ -0,0 +1,4 @@
+export { default as format } from "./format";
+export { default as isOnSameDay } from "./is-on-same-day";
+export { default as fromTimestamp } from "./from-timestamp";
+export { default as isOnSameYear } from "./is-on-same-year";

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

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

@@ -0,0 +1,13 @@
+/**
+ * Checks if two Date objects fall within the same day of the year.
+ *
+ * @param {Date} dateA The first date.
+ * @param {Date} dateB The second date.
+ * @returns {boolean} True if both dates fall within the same day of the year, otherwise false.
+ */
+export default function isOnSameYear( dateA, dateB )
+{
+	return dateA.getUTCDate() === dateB.getUTCDate() &&
+	       dateA.getUTCMonth() === dateB.getUTCMonth() &&
+	       dateA.getUTCFullYear() === dateB.getUTCFullYear();
+}

package/helpers/date/is-on-same-day/index.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import isOnSameDay from "./index";
+
+describe( "isOnSameDay", () =>
+{
+	it( "returns true for same year, month and day", () =>
+	{
+		const d1 = new Date( "2023-07-27T10:00:00" );
+		const d2 = new Date( "2023-07-27T23:59:59" );
+
+		expect( isOnSameDay( d1, d2 )).toBe( true );
+	});
+
+	it( "returns false for same month and day but different year", () =>
+	{
+		const d1 = new Date( "2022-07-27" );
+		const d2 = new Date( "2023-07-27" );
+		
+		expect( isOnSameDay( d1, d2 )).toBe( false );
+	});
+
+	it( "returns false for same year and day but different month", () =>
+	{
+		const d1 = new Date( "2023-06-27" );
+		const d2 = new Date( "2023-07-27" );
+
+		expect( isOnSameDay( d1, d2 )).toBe( false );
+	});
+
+	it( "returns false for same year and month but different day", () =>
+	{
+		const d1 = new Date( "2023-07-26" );
+		const d2 = new Date( "2023-07-27" );
+
+		expect( isOnSameDay( d1, d2 )).toBe( false );
+	});
+
+	it( "returns true for exact same date object", () =>
+	{
+		const d1 = new Date( "2023-07-27T12:34:56" );
+		expect( isOnSameDay( d1, d1 )).toBe( true );
+	});
+
+	it( "works correctly across timezones if both dates are created equally", () =>
+	{
+		const d1 = new Date( Date.UTC( 2023, 6, 27, 0, 0, 0 )); // UTC
+		const d2 = new Date( Date.UTC( 2023, 6, 27, 23, 59, 59 ));
+	
+		expect( isOnSameDay( d1, d2 )).toBe( true );
+	});
+
+	it( "returns false for completely different dates", () =>
+	{
+		const d1 = new Date( "1999-01-01" );
+		const d2 = new Date( "2025-12-31" );
+
+		expect( isOnSameDay( d1, d2 )).toBe( false );
+	});
+});

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

@@ -0,0 +1,13 @@
+# 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/date/is-on-same-year/index.js

@@ -0,0 +1,11 @@
+/**
+ * Checks if two Date objects fall within the same year.
+ *
+ * @param {Date} dateA The first date.
+ * @param {Date} dateB The second date.
+ * @returns {boolean} True if both dates fall within the same year, otherwise false.
+ */
+export default function isOnSameYear( dateA, dateB )
+{
+	return dateA.getFullYear() === dateB.getFullYear();
+}

package/helpers/date/is-on-same-year/index.test.js

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import isOnSameYear from "./index";
+
+describe( "isOnSameYear", () =>
+{
+	it( "returns true if both dates are in the same year", () =>
+	{
+		const date1 = new Date( "2023-01-01" );
+		const date2 = new Date( "2023-12-31" );
+		
+		expect( isOnSameYear( date1, date2 )).toBe( true );
+	});
+
+	it( "returns false if years differ", () =>
+	{
+		const date1 = new Date( "2022-12-31" );
+		const date2 = new Date( "2023-01-01" );
+		
+		expect( isOnSameYear( date1, date2 )).toBe( false );
+	});
+});

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

@@ -0,0 +1,25 @@
+{
+  "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/package.json

@@ -0,0 +1,29 @@
+{
+  "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",
+  "workspaces": [
+    "src/*/*"
+  ],
+  "scripts": {
+    "release": "standard-version",
+    "test": "npx vitest --ui --coverage",
+    "publish-package": "npm publish --access=public"
+  },
+  "standard-version": {},
+  "author": {
+    "name": "Ismail Ceylan",
+    "email": "ismaillceylan@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ismailceylan/mark-3.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "vitest": "^3.2.4"
+  }
+}

package/vitest.config.ts

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