@heliosgraphics/utils 6.0.0-alpha.10 → 6.0.0-alpha.12

package/classnames.ts

@@ -2,7 +2,7 @@ export const getClasses = (...args: Array<unknown>): string => {
 	const classNames: Set<string> = new Set()
 
 	for (const item of args) {
-		const itemType = typeof item
+		const itemType: string = typeof item
 		const isValidString: boolean = itemType === "string" && (item as string).length > 0
 		const isValidObject: boolean = itemType === "object" && item !== null
 
@@ -17,5 +17,5 @@ export const getClasses = (...args: Array<unknown>): string => {
 		}
 	}
 
-	return Array.from(classNames).join(" ")
+	return [...classNames].join(" ")
 }

package/clipboard.ts

@@ -1,10 +1,14 @@
-export const copyValue = (text: string): void => {
+export const copyValue = async (text: string): Promise<void> => {
+	if (navigator?.clipboard?.writeText) {
+		await navigator.clipboard.writeText(text)
+		return
+	}
+
 	const input: HTMLTextAreaElement = document.createElement("textarea")
 
 	document.body.appendChild(input)
 	input.value = text
 	input.select()
 	document.execCommand("copy", false)
-
-	return input.remove()
+	input.remove()
 }

package/colors.ts

@@ -1,15 +1,20 @@
 type TypeRGB = [number, number, number]
 
-export const DEFAULT_PROFILE_RGB: TypeRGB = [199, 201, 209] as const
-
-export const hexToRgb = (hex?: string | null): TypeRGB => {
+export const hexToRgb = (hex?: string | null): TypeRGB | null => {
 	const isValid: boolean = !!hex && typeof hex === "string"
 
-	if (!isValid || !hex) return DEFAULT_PROFILE_RGB
+	if (!isValid || !hex) return null
 
 	hex = hex.replace(/^#/, "")
 
-	const bigint = parseInt(hex, 16)
+	if (hex.length === 3) {
+		hex = hex
+			.split("")
+			.map((c: string) => c + c)
+			.join("")
+	}
+
+	const bigint: number = parseInt(hex, 16)
 	const r: number = (bigint >> 16) & 255
 	const g: number = (bigint >> 8) & 255
 	const b: number = bigint & 255
@@ -19,12 +24,14 @@ export const hexToRgb = (hex?: string | null): TypeRGB => {
 
 export const rgbToHex = (r: number | string = 255, g: number | string = 255, b: number | string = 255): string => {
 	const _toHex = (c: unknown): string => {
-		const value: number = Number(c)
+		if (c === null || c === undefined) return "ff"
+
+		const value: number = Math.round(Number(c))
 		const isInvalid: boolean = isNaN(value) || value < 0 || value > 255
 
 		if (isInvalid) return "ff"
 
-		const hex = value.toString(16)
+		const hex: string = value.toString(16)
 
 		return hex.length === 1 ? `0${hex}` : hex
 	}

package/debounce.ts

@@ -1,15 +1,29 @@
+interface DebouncedFunction<T extends (...args: Array<unknown>) => unknown> {
+	(...args: Parameters<T>): void
+	cancel: () => void
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const debounce = <T extends (...args: Array<any>) => any>(
-	callback: T,
-	wait: number,
-): ((...args: Parameters<T>) => void) => {
-	let timeoutId: ReturnType<typeof setTimeout>
+export const debounce = <T extends (...args: Array<any>) => any>(callback: T, wait: number): DebouncedFunction<T> => {
+	let timeoutId: ReturnType<typeof setTimeout> | null = null
 
-	return (...args: Parameters<T>): void => {
-		globalThis.clearTimeout(timeoutId)
+	const debounced: DebouncedFunction<T> = (...args: Parameters<T>): void => {
+		if (timeoutId !== null) {
+			globalThis.clearTimeout(timeoutId)
+		}
 
 		timeoutId = globalThis.setTimeout(() => {
 			callback.apply(null, args)
+			timeoutId = null
 		}, wait)
 	}
+
+	debounced.cancel = (): void => {
+		if (timeoutId !== null) {
+			globalThis.clearTimeout(timeoutId)
+			timeoutId = null
+		}
+	}
+
+	return debounced
 }

package/equals.ts

@@ -1,19 +1,15 @@
 type FracturesPrimitive = string | number | boolean | null | undefined | bigint | symbol
 type FracturesComparable = FracturesPrimitive | object | Array<unknown> | Set<unknown> | Map<unknown, unknown>
 
-export const _getAreMapsEqual = <K, V>(
-	mapA: Map<K, V>,
-	mapB: Map<K, V>,
-	seen = new WeakMap<object, object>(),
-): boolean => {
+const _getAreMapsEqual = <K, V>(mapA: Map<K, V>, mapB: Map<K, V>, seen = new WeakMap<object, object>()): boolean => {
 	if (mapA.size !== mapB.size) return false
 	if (mapA === mapB) return true
 
-	const entriesA = Array.from(mapA.entries())
-	const entriesB = new Map(mapB)
+	const entriesA: Array<[K, V]> = Array.from(mapA.entries())
+	const entriesB: Map<K, V> = new Map(mapB)
 
 	return entriesA.every(
-		([key, value]) =>
+		([key, value]: [K, V]) =>
 			entriesB.has(key) && _getIsEqual(value as FracturesComparable, entriesB.get(key) as FracturesComparable, seen),
 	)
 }
@@ -22,21 +18,21 @@ export const getAreDatesEqual = (a: Date, b: Date): boolean => a.getTime() === b
 export const getAreRegExpsEqual = (a: RegExp, b: RegExp): boolean => a.toString() === b.toString()
 export const getAreErrorsEqual = (a: Error, b: Error): boolean =>
 	a.message === b.message && a.name === b.name && a.stack === b.stack
-export const getAreBuffersEqual = (a: Buffer, b: Buffer): boolean => a.length === b.length && Buffer.compare(a, b) === 0
+export const getAreBuffersEqual = (a: Buffer, b: Buffer): boolean => Buffer.compare(a, b) === 0
 
 export const getAreSetsEqual = <T>(setA: Set<T>, setB: Set<T>): boolean => {
 	if (setA.size !== setB.size) return false
 	if (setA === setB) return true
 	if (setA.size === 0) return true
 
-	const arrA = Array.from(setA)
-	const arrB = Array.from(setB)
-	const matched = new Array(arrB.length).fill(false)
+	const arrA: Array<T> = Array.from(setA)
+	const arrB: Array<T> = Array.from(setB)
+	const matched: Array<boolean> = new Array(arrB.length).fill(false)
 
-	for (let i = 0; i < arrA.length; i++) {
-		let foundMatch = false
+	for (let i: number = 0; i < arrA.length; i++) {
+		let foundMatch: boolean = false
 
-		for (let j = 0; j < arrB.length; j++) {
+		for (let j: number = 0; j < arrB.length; j++) {
 			if (!matched[j] && _getIsEqual(arrA[i] as FracturesComparable, arrB[j] as FracturesComparable)) {
 				matched[j] = true
 				foundMatch = true
@@ -50,31 +46,15 @@ export const getAreSetsEqual = <T>(setA: Set<T>, setB: Set<T>): boolean => {
 	return true
 }
 
-export const _getIsEqual = <T extends FracturesComparable>(
-	a: T,
-	b: T,
-	seen = new WeakMap<object, object>(),
-): boolean => {
+const _getIsEqual = <T extends FracturesComparable>(a: T, b: T, seen = new WeakMap<object, object>()): boolean => {
 	if (a === b) return true
-	if (a === null || b === null) return a === b
+	if (a === null || b === null) return false
 
-	if (typeof a !== "object" && typeof b !== "object") {
-		return a === b
-	}
-
-	if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) {
-		return false
-	}
-
-	if (Object.is(a, b)) return true
-
-	const typeA = typeof a
-	const typeB = typeof b
+	if (typeof a !== "object" || typeof b !== "object") return false
 
-	if (typeA !== typeB) return false
-	if (typeA !== "object") return false
+	if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false
 
-	const seenA = seen.get(a as object)
+	const seenA: object | undefined = seen.get(a as object)
 	if (seenA) return seenA === b
 
 	seen.set(a as object, b as object)
@@ -82,7 +62,7 @@ export const _getIsEqual = <T extends FracturesComparable>(
 	if (Array.isArray(a) && Array.isArray(b)) {
 		if (a.length !== b.length) return false
 
-		for (let i = 0; i < a.length; i++) {
+		for (let i: number = 0; i < a.length; i++) {
 			if (!_getIsEqual(a[i], b[i], seen)) return false
 		}
 		return true
@@ -95,13 +75,13 @@ export const _getIsEqual = <T extends FracturesComparable>(
 	if (a instanceof RegExp && b instanceof RegExp) return getAreRegExpsEqual(a, b)
 	if (Buffer.isBuffer(a) && Buffer.isBuffer(b)) return getAreBuffersEqual(a, b)
 
-	const keysA = [...Object.keys(a as object), ...Object.getOwnPropertySymbols(a as object)]
-	const keysB = [...Object.keys(b as object), ...Object.getOwnPropertySymbols(b as object)]
+	const keysA: Array<string | symbol> = [...Object.keys(a as object), ...Object.getOwnPropertySymbols(a as object)]
+	const keysB: Array<string | symbol> = [...Object.keys(b as object), ...Object.getOwnPropertySymbols(b as object)]
 
 	if (keysA.length !== keysB.length) return false
 
 	return keysA.every(
-		(key) =>
+		(key: string | symbol) =>
 			Object.prototype.hasOwnProperty.call(b, key) &&
 			_getIsEqual(
 				(a as Record<string | symbol, unknown>)[key] as FracturesComparable,
@@ -115,6 +95,6 @@ export const getIsEqual = <T extends FracturesComparable>(a: T, b: T): boolean =
 	return _getIsEqual(a, b)
 }
 
-export const getAreMapsEqual = <T extends FracturesComparable>(a: T, b: T): boolean => {
-	return _getAreMapsEqual(a as Map<unknown, unknown>, b as Map<unknown, unknown>)
+export const getAreMapsEqual = <K, V>(a: Map<K, V>, b: Map<K, V>): boolean => {
+	return _getAreMapsEqual(a, b)
 }

package/index.ts

@@ -17,4 +17,4 @@ export { removeMarkdown, removeNewlines, ellipsis } from "./strings"
 export { sanitizeText } from "./sanitize"
 export { throttle } from "./throttle"
 export { isUUID, getUUID } from "./uuid"
-export { validateUrl, validateEmail } from "./validations"
+export { validateHttpsUrl, validateEmail } from "./validations"

package/package.json

@@ -1,14 +1,32 @@
 {
 	"name": "@heliosgraphics/utils",
-	"version": "6.0.0-alpha.10",
+	"version": "6.0.0-alpha.12",
 	"type": "module",
+	"sideEffects": false,
 	"author": "Chris Puska <chris@puska.org>",
 	"license": "MIT",
 	"private": false,
 	"description": "Helios Utils",
 	"main": "index.ts",
-	"dependencies": {
-		"@types/node": "^24"
+	"types": "index.ts",
+	"exports": {
+		".": "./index.ts",
+		"./*": "./*.ts"
 	},
-	"devDependencies": {}
+	"files": [
+		"*.ts",
+		"!*.spec.ts"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/heliosgraphics/helios-ui.git",
+		"directory": "packages/utils"
+	},
+	"homepage": "https://github.com/heliosgraphics/helios-ui/tree/main/packages/utils",
+	"bugs": {
+		"url": "https://github.com/heliosgraphics/helios-ui/issues"
+	},
+	"devDependencies": {
+		"@types/node": "^25"
+	}
 }

package/sanitize.ts

@@ -209,7 +209,7 @@ export const sanitizeText = (input: string = ""): string => {
 	})
 
 	// Additional targeted cleanup for specific dangerous contexts
-	sanitized = sanitized.replace(/\balert\s*(?=[,\)])/gi, "")
+	sanitized = sanitized.replace(/\balert\s*(?=[,)])/gi, "")
 	sanitized = sanitized.replace(/\bjavascript\s*(?=:)/gi, "")
 
 	// Remove any remaining backticks

package/strings.ts

@@ -33,7 +33,7 @@ export const removeNewlines = (text?: string | null, limit?: number): string =>
 export const ellipsis = (text: string, maxLength: number, position: "end" | "middle" = "end"): string => {
 	if (!text || typeof text !== "string") return ""
 	if (text.length <= maxLength) return text
-	if (maxLength < 4) return ""
+	if (maxLength < 4) return text
 
 	if (position === "middle") {
 		const halfLength = Math.floor((maxLength - 3) / 2)

package/throttle.ts

@@ -1,11 +1,13 @@
+interface ThrottledFunction<T extends (...args: Array<unknown>) => unknown> {
+	(...args: Parameters<T>): void
+	cancel: () => void
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export const throttle = <T extends (...args: Array<any>) => any>(
-	fn: T,
-	delay: number,
-): ((...args: Parameters<T>) => void) => {
+export const throttle = <T extends (...args: Array<any>) => any>(fn: T, delay: number): ThrottledFunction<T> => {
 	let timeoutId: ReturnType<typeof setTimeout> | null = null
 
-	return (...args: Parameters<T>): void => {
+	const throttled: ThrottledFunction<T> = (...args: Parameters<T>): void => {
 		if (!timeoutId) {
 			fn(...args)
 
@@ -14,4 +16,13 @@ export const throttle = <T extends (...args: Array<any>) => any>(
 			}, delay)
 		}
 	}
+
+	throttled.cancel = (): void => {
+		if (timeoutId !== null) {
+			clearTimeout(timeoutId)
+			timeoutId = null
+		}
+	}
+
+	return throttled
 }

package/uuid.ts

@@ -1,14 +1,13 @@
-export const getUUID = (id?: unknown): string => {
-	if (id) return id as string
+export const getUUID = (id?: string): string => {
+	if (id !== undefined) return id
 
 	return crypto.randomUUID()
 }
 
-export const isUUID = (uuid?: unknown): boolean => {
-	const uuidRegex = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
-	const isValid = typeof uuid === "string"
+const UUID_REGEX: RegExp = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/
 
-	if (!isValid) return false
+export const isUUID = (uuid?: unknown): uuid is string => {
+	if (typeof uuid !== "string") return false
 
-	return uuidRegex.test(uuid)
+	return UUID_REGEX.test(uuid)
 }

package/validations.ts

@@ -1,4 +1,4 @@
-export const validateUrl = (text?: string | null): boolean => {
+export const validateHttpsUrl = (text?: string | null): boolean => {
 	let url: URL
 
 	try {

package/classnames.spec.ts

@@ -1,17 +0,0 @@
-import { it, describe, expect } from "vitest"
-import { getClasses } from "./classnames"
-
-describe("classnames", () => {
-	describe("getClasses", () => {
-		it("returns valid with string", () => expect(getClasses("burn")).toEqual("burn"))
-		it("returns conditional object", () =>
-			expect(getClasses("burn", { "burn--alternative": true })).toEqual("burn burn--alternative"))
-		it("returns valid with invalid", () =>
-			expect(
-				getClasses("burn", null, "burn", undefined, {
-					"burn--active": false,
-					"burn--loading": true,
-				}),
-			).toEqual("burn burn--loading"))
-	})
-})

package/clipboard.spec.ts

@@ -1,40 +0,0 @@
-import { describe, it, expect, vi } from "vitest"
-import { copyValue } from "./clipboard"
-
-const mockDocument = {
-	createElement: vi.fn(),
-	execCommand: vi.fn(),
-	body: {
-		appendChild: vi.fn(),
-	},
-} as unknown as Document
-
-global.document = mockDocument
-
-describe("copyValue", () => {
-	const TEXT_STRING = "Test text" as const
-
-	it("copies text to the clipboard", () => {
-		const textAreaMock: {
-			value: string
-			select: () => void
-			remove: () => void
-		} = {
-			value: "",
-			select: vi.fn(),
-			remove: vi.fn(),
-		}
-
-		document.createElement = vi.fn().mockReturnValue(textAreaMock)
-		document.body.appendChild = vi.fn().mockReturnValue(textAreaMock)
-
-		copyValue(TEXT_STRING)
-
-		expect(document.createElement).toHaveBeenCalledWith("textarea")
-		expect(document.body.appendChild).toHaveBeenCalled()
-		expect(document.execCommand).toHaveBeenCalledWith("copy", false)
-		expect(textAreaMock.value).toBe(TEXT_STRING)
-		expect(textAreaMock.select).toHaveBeenCalled()
-		expect(textAreaMock.remove).toHaveBeenCalled()
-	})
-})

package/colors.spec.ts

@@ -1,40 +0,0 @@
-import { it, describe, expect } from "vitest"
-import { rgbToHex, hexToRgb, DEFAULT_PROFILE_RGB } from "./colors"
-
-describe("colors", () => {
-	describe("hexToRgb", () => {
-		it("converts hex to rgb", () => expect(hexToRgb("#0c2c78")).toEqual([12, 44, 120]))
-		it("converts hex without #", () => expect(hexToRgb("0c2c78")).toEqual([12, 44, 120]))
-		it("converts uppercase hex", () => expect(hexToRgb("#0C2C78")).toEqual([12, 44, 120]))
-		it("converts short hex", () => expect(hexToRgb("#fff")).toEqual([0, 15, 255]))
-		it("converts black", () => expect(hexToRgb("#000000")).toEqual([0, 0, 0]))
-		it("converts white", () => expect(hexToRgb("#ffffff")).toEqual([255, 255, 255]))
-		it("returns default for 0", () => expect(hexToRgb(0 as unknown as string)).toEqual(DEFAULT_PROFILE_RGB))
-		it("returns default for undefined", () => expect(hexToRgb(undefined)).toEqual(DEFAULT_PROFILE_RGB))
-		it("returns default for null", () => expect(hexToRgb(null)).toEqual(DEFAULT_PROFILE_RGB))
-		it("returns default for empty string", () => expect(hexToRgb("")).toEqual(DEFAULT_PROFILE_RGB))
-		it("returns default for invalid hex", () => expect(hexToRgb("gggggg")).toEqual([0, 0, 0]))
-		it("returns default for non-string", () => expect(hexToRgb(123 as unknown as string)).toEqual(DEFAULT_PROFILE_RGB))
-	})
-
-	describe("rgbToHex", () => {
-		it("converts rgb to hex", () => expect(rgbToHex(12, 44, 120)).toEqual("#0c2c78"))
-		it("converts string to hex", () =>
-			expect(rgbToHex("12" as unknown as number, "44" as unknown as number, "120" as unknown as number)).toEqual(
-				"#0c2c78",
-			))
-		it("converts null to hex", () => expect(rgbToHex(null as unknown as number, 44, 120)).toEqual("#002c78"))
-		it("returns undefined to hex", () => expect(rgbToHex(12, undefined as unknown as number, 120)).toEqual("#0cff78"))
-		it("returns FF for negative", () => expect(rgbToHex(-1, -12, 120)).toEqual("#ffff78"))
-		it("converts zero values", () => expect(rgbToHex(0, 0, 0)).toEqual("#000000"))
-		it("converts max values", () => expect(rgbToHex(255, 255, 255)).toEqual("#ffffff"))
-		it("returns FF for over 255", () => expect(rgbToHex(300, 256, 120)).toEqual("#ffff78"))
-		it("returns FF for invalid string", () => expect(rgbToHex("abc" as unknown as number, 44, 120)).toEqual("#ff2c78"))
-		it("handles fractional numbers", () =>
-			expect(rgbToHex(12.9, 44.1, 120.5)).toEqual("#c.e6666666666682c.19999999999a78.8"))
-		it("uses defaults when no params", () => expect(rgbToHex()).toEqual("#ffffff"))
-		it("handles mixed valid/invalid", () =>
-			expect(rgbToHex(12, "invalid" as unknown as number, 120)).toEqual("#0cff78"))
-		it("converts single digit to padded hex", () => expect(rgbToHex(1, 2, 3)).toEqual("#010203"))
-	})
-})

package/debounce.spec.ts

@@ -1,101 +0,0 @@
-import { describe, it, expect, vi } from "vitest"
-import { debounce } from "./debounce"
-import { sleep } from "./sleep"
-
-describe("debounce", () => {
-	it("calls the callback after the specified time", async () => {
-		const callback = vi.fn()
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction()
-
-		await sleep(25)
-		expect(callback).not.toHaveBeenCalled()
-
-		await sleep(30)
-		expect(callback).toHaveBeenCalledTimes(1)
-	})
-
-	it("does not call the callback if the function is called again within the wait time", async () => {
-		const callback = vi.fn()
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction()
-		await sleep(25)
-
-		debouncedFunction()
-		await sleep(25)
-
-		expect(callback).not.toHaveBeenCalled()
-
-		await sleep(30)
-		expect(callback).toHaveBeenCalledTimes(1)
-	})
-
-	it("preserves function arguments", async () => {
-		const callback = vi.fn()
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction("arg1", "arg2", 123)
-
-		await sleep(60)
-		expect(callback).toHaveBeenCalledWith("arg1", "arg2", 123)
-	})
-
-	it("uses the latest arguments when called multiple times", async () => {
-		const callback = vi.fn()
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction("first")
-		await sleep(25)
-
-		debouncedFunction("second")
-		await sleep(60)
-
-		expect(callback).toHaveBeenCalledTimes(1)
-		expect(callback).toHaveBeenCalledWith("second")
-	})
-
-	it("works with functions that have specific parameter types", async () => {
-		const callback = vi.fn((str: string, num: number) => str + num)
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction("test", 42)
-
-		await sleep(60)
-		expect(callback).toHaveBeenCalledWith("test", 42)
-	})
-
-	it("works with functions that return values", async () => {
-		const callback = vi.fn((x: number) => x * 2)
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction(5)
-
-		await sleep(60)
-		expect(callback).toHaveBeenCalledWith(5)
-	})
-
-	it("works with zero wait time", async () => {
-		const callback = vi.fn()
-		const debouncedFunction = debounce(callback, 0)
-
-		debouncedFunction()
-
-		await sleep(1)
-		expect(callback).toHaveBeenCalledTimes(1)
-	})
-
-	it("can be called after completion", async () => {
-		const callback = vi.fn()
-		const debouncedFunction = debounce(callback, 50)
-
-		debouncedFunction()
-		await sleep(60)
-		expect(callback).toHaveBeenCalledTimes(1)
-
-		debouncedFunction()
-		await sleep(60)
-		expect(callback).toHaveBeenCalledTimes(2)
-	})
-})