@heliosgraphics/utils 6.0.0-alpha.10

package/sanitize.ts

@@ -0,0 +1,219 @@
+const ALLOWED_TAGS = new Set([
+	"b",
+	"i",
+	"u",
+	"em",
+	"strong",
+	"span",
+	"p",
+	"br",
+	"div",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"ul",
+	"ol",
+	"li",
+	"blockquote",
+	"code",
+	"pre",
+])
+
+const ALLOWED_ATTRIBUTES = new Set(["class", "id", "title"])
+
+const SAFE_PROTOCOLS = /^(https?|mailto|tel|ftp):/i
+
+const DANGEROUS_FUNCTIONS: Array<RegExp> = [
+	/alert(?=\s*\()/gi,
+	/eval(?=\s*\()/gi,
+	/document\./gi,
+	/window\./gi,
+	/location\./gi,
+	/navigator\./gi,
+	/history\./gi,
+	/frames?\./gi,
+	/parent\./gi,
+	/top\./gi,
+	/self\./gi,
+	/globalThis\./gi,
+	/this\./gi,
+	/global\./gi,
+	/Function(?=\s*\()/gi,
+	/setTimeout(?=\s*\()/gi,
+	/setInterval(?=\s*\()/gi,
+	/requestAnimationFrame(?=\s*\()/gi,
+	/XMLHttpRequest(?=\s*\()/gi,
+	/fetch(?=\s*\()/gi,
+	/import(?=\s*\()/gi,
+	/require(?=\s*\()/gi,
+	/process\./gi,
+	/Buffer\./gi,
+	/\w+\[\s*["']constructor["']\s*\]/gi,
+	/\w+\[\s*["']prototype["']\s*\]/gi,
+	/`[\s\S]*?\$\{[\s\S]*?\}[\s\S]*?`/gi,
+	/fromCharCode(?=\s*\()/gi,
+	/String\s*\./gi,
+	/unescape(?=\s*\()/gi,
+	/decodeURI(?=\s*\()/gi,
+	/decodeURIComponent(?=\s*\()/gi,
+	/atob(?=\s*\()/gi,
+	/btoa(?=\s*\()/gi,
+	/WebAssembly\./gi,
+	/SharedArrayBuffer(?=\s*\()/gi,
+	/Worker(?=\s*\()/gi,
+	/ServiceWorker(?=\s*\()/gi,
+	/innerHTML\s*=/gi,
+	/outerHTML\s*=/gi,
+	/insertAdjacentHTML(?=\s*\()/gi,
+	/document\.write(?=\s*\()/gi,
+	/document\.writeln(?=\s*\()/gi,
+	/CustomEvent(?=\s*\()/gi,
+	/dispatchEvent(?=\s*\()/gi,
+	/createEvent(?=\s*\()/gi,
+	/constructor\s*\./gi,
+	/__proto__\s*\./gi,
+	/prototype\s*\./gi,
+	/jsonp(?=\s*\()/gi,
+	/loadScript(?=\s*\()/gi,
+	/createElement\s*\(\s*["']script["']\s*\)/gi,
+]
+
+export const sanitizeText = (input: string = ""): string => {
+	if (!input) return ""
+
+	// First remove dangerous patterns before decoding
+	let sanitized = input
+		.replace(/<!--[\s\S]*?-->/g, "")
+		.replace(/\\[0-9a-f]{1,6}\s*/gi, "")
+		.replace(/<img[^>]*src\s*=\s*["']data:[^"']*["'][^>]*>/gi, "")
+		.replace(/data\s*:[^"'\s>)]*/gi, "")
+
+	// Then decode entities
+	sanitized = sanitized
+		.replace(/&#x0*([0-9a-f]+);/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+		.replace(/&#0*(\d+);/g, (_, dec) => String.fromCharCode(parseInt(dec, 10)))
+		.replace(/\\u([0-9a-f]{4})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+		.replace(/\\x([0-9a-f]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
+		.replace(/\\([0-7]{1,3})/g, (_, octal) => String.fromCharCode(parseInt(octal, 8)))
+		.replace(/%3c/gi, "<")
+		.replace(/%3e/gi, ">")
+		.replace(/%22/gi, '"')
+		.replace(/%27/gi, "'")
+		.replace(/%2f/gi, "/")
+		.replace(/%20/gi, " ")
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&#39;/g, "'")
+		.replace(/&apos;/g, "'")
+		.replace(/&sol;/g, "/")
+		.replace(/&amp;/g, "&")
+		.replace(/&NewLine;/g, "\n")
+		.replace(/&Tab;/g, "\t")
+		.replace(/&lpar;/g, "(")
+		.replace(/&rpar;/g, ")")
+		.replace(/&comma;/g, ",")
+		.replace(/&period;/g, ".")
+		.replace(/&colon;/g, ":")
+		.replace(/&semi;/g, ";")
+		.replace(/&equals;/g, "=")
+		.replace(/&plus;/g, "+")
+		.replace(/&ast;/g, "*")
+		.replace(/&dollar;/g, "$")
+		.replace(/&num;/g, "#")
+		.replace(/&percnt;/g, "%")
+		.replace(/\\\\[\w\s]+\\/gi, "")
+		.replace(/\{\{[^}]*\}\}/g, "")
+		.replace(/\$\{[^}]*\}/g, "")
+
+	if (typeof sanitized.normalize === "function") {
+		sanitized = sanitized.normalize("NFKC")
+	}
+
+	sanitized = sanitized
+		.replace(/[\u200B-\u200D\uFEFF]/g, "")
+		// eslint-disable-next-line no-control-regex
+		.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, "")
+		.replace(/[\u202A-\u202E]/g, "")
+		.replace(/[\u2066-\u2069]/g, "")
+
+	sanitized = sanitized.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, "")
+	sanitized = sanitized.replace(/<script\b[^>]*>[\s\S]*$/gi, "")
+	sanitized = sanitized.replace(/<script\b[^>]*$/gi, "")
+
+	sanitized = sanitized.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, "")
+	sanitized = sanitized.replace(/<style\b[^>]*>[\s\S]*$/gi, "")
+
+	sanitized = sanitized.replace(
+		/(\w+(?:[\s\u00A0]*\w)*)\s*(?:&#58;|&#x3a;|&colon;|%3a|%3A|\\:|:)/gi,
+		(_: string, protocol: string) => {
+			const cleanProtocol = protocol.replace(/[\s\u00A0]/g, "").toLowerCase()
+			const testString = cleanProtocol + ":"
+			return SAFE_PROTOCOLS.test(testString) ? testString : ""
+		},
+	)
+
+	// Handle both closed and unclosed tags
+	sanitized = sanitized.replace(
+		/<(\/?)([\w-]+)([^>]*?)(?:>|$)/gi,
+		(_fullMatch: string, closing: string, tagName: string, attributes: string) => {
+			const tag = tagName.toLowerCase()
+
+			if (!ALLOWED_TAGS.has(tag)) {
+				return ""
+			}
+
+			if (attributes && attributes.trim()) {
+				let cleanAttributes = ""
+
+				const attrMatches = attributes.match(/\s*([a-z-]+)\s*=\s*(?:["']([^"']*)["']|`([^`]*)`|([^\s>=]+))/gi)
+
+				if (attrMatches) {
+					attrMatches.forEach((attrMatch) => {
+						const attrParsed = attrMatch.match(/\s*([a-z-]+)\s*=\s*(?:["']([^"']*)["']|`([^`]*)`|([^\s>=]+))/i)
+						if (attrParsed) {
+							const attrName = attrParsed[1]?.toLowerCase().trim()
+							const attrValue = (attrParsed[2] || attrParsed[3] || attrParsed[4] || "").trim()
+
+							if (!attrName) {
+								return
+							}
+
+							if (ALLOWED_ATTRIBUTES.has(attrName)) {
+								let cleanValue = attrValue
+
+								cleanValue = cleanValue.replace(/expression\s*\(/gi, "")
+								cleanValue = cleanValue.replace(/-moz-binding/gi, "")
+								cleanValue = cleanValue.replace(/behavior\s*:/gi, "")
+								cleanValue = cleanValue.replace(/script/gi, "")
+								cleanValue = cleanValue.replace(/alert/gi, "")
+
+								cleanAttributes += ` ${attrName}="${cleanValue}"`
+							}
+						}
+					})
+				}
+
+				return `<${closing}${tag}${cleanAttributes}>`
+			}
+
+			return `<${closing}${tag}>`
+		},
+	)
+
+	DANGEROUS_FUNCTIONS.forEach((pattern) => {
+		sanitized = sanitized.replace(pattern, "")
+	})
+
+	// Additional targeted cleanup for specific dangerous contexts
+	sanitized = sanitized.replace(/\balert\s*(?=[,\)])/gi, "")
+	sanitized = sanitized.replace(/\bjavascript\s*(?=:)/gi, "")
+
+	// Remove any remaining backticks
+	sanitized = sanitized.replace(/`/g, "")
+
+	return sanitized.trim()
+}

package/sleep.spec.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest"
+import { sleep } from "./sleep"
+
+describe("sleep", () => {
+	it("returns a Promise", () => {
+		const result = sleep(1)
+		expect(result).toBeInstanceOf(Promise)
+	})
+
+	it("resolves with undefined", async () => {
+		const result = await sleep(1)
+		expect(result).toBeUndefined()
+	})
+
+	it("accepts number parameter", () => {
+		expect(() => sleep(100)).not.toThrow()
+		expect(() => sleep(0)).not.toThrow()
+		expect(() => sleep(1.5)).not.toThrow()
+	})
+
+	it("resolves after minimal delay", async () => {
+		const start = Date.now()
+		await sleep(1)
+		const elapsed = Date.now() - start
+		expect(elapsed).toBeGreaterThanOrEqual(0)
+	})
+
+	it("handles zero milliseconds", async () => {
+		const start = Date.now()
+		await sleep(0)
+		const elapsed = Date.now() - start
+		expect(elapsed).toBeGreaterThanOrEqual(0)
+	})
+
+	it("handles fractional milliseconds", async () => {
+		const start = Date.now()
+		await sleep(0.5)
+		const elapsed = Date.now() - start
+		expect(elapsed).toBeGreaterThanOrEqual(0)
+	})
+
+	it("handles negative values", async () => {
+		const start = Date.now()
+		await sleep(-1)
+		const elapsed = Date.now() - start
+		expect(elapsed).toBeGreaterThanOrEqual(0)
+	})
+
+	it("can be used with Promise.all", async () => {
+		const promises = [sleep(1), sleep(2), sleep(3)]
+		const results = await Promise.all(promises)
+		expect(results).toEqual([undefined, undefined, undefined])
+	})
+
+	it("maintains proper typing", () => {
+		const promise: Promise<void> = sleep(1)
+		expect(promise).toBeInstanceOf(Promise)
+	})
+})

package/sleep.ts

@@ -0,0 +1 @@
+export const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))

package/slug.spec.ts

@@ -0,0 +1,15 @@
+import { it, describe, expect } from "vitest"
+import { getSlug } from "./slug"
+
+describe("slug", () => {
+	describe("getSlug", () => {
+		it("returns valid from string with dashes", () => expect(getSlug("--B—uRn--")).toEqual("-burn-"))
+		it("returns valid from special string", () => expect(getSlug("#$%^B#uR#n-")).toEqual("burn-"))
+		it("returns valid from parens string", () =>
+			expect(getSlug("Gaussian Blur [1](2){3}")).toEqual("gaussian-blur-123"))
+		it("replaces àáäâèéëêìíïîòóöôùúüûñç", () =>
+			expect(getSlug("àáäâèéëêìíïîòóöôùúüûñç")).toEqual("aaaaeeeeiiiioooouuuunc"))
+		it("fails silently from undefined", () => expect(getSlug(undefined)).toEqual(""))
+		it("fails silently from null", () => expect(getSlug(null as unknown as string)).toEqual(""))
+	})
+})

package/slug.ts

@@ -0,0 +1,14 @@
+export const getSlug = (text?: string): string => {
+	const isValid = Boolean(text && typeof text == "string")
+
+	if (!isValid || !text) return ""
+
+	return text
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9 -]/g, "")
+		.replace(/\s+/g, "-")
+		.replace(/-+/g, "-")
+}

package/strings.spec.ts

@@ -0,0 +1,77 @@
+import { it, describe, expect } from "vitest"
+import { removeMarkdown, removeNewlines, ellipsis } from "./strings"
+
+describe("strings", () => {
+	describe("removeMarkdown", () => {
+		it("removes a bold format", () => expect(removeMarkdown("a **bold** text")).toEqual("a bold text"))
+		it("removes a link but keeps the name", () =>
+			expect(removeMarkdown("a [link](https://x.com) hello")).toEqual("a link hello"))
+		it("removes a bold link", () =>
+			expect(removeMarkdown("a [bold **link**](https://x.com) hello")).toEqual("a bold link hello"))
+	})
+
+	describe("removeNewlines", () => {
+		it("removes no newline", () => expect(removeNewlines("first line same line")).toEqual("first line same line"))
+		it("removes newline", () =>
+			expect(removeNewlines("first line\n\n\nsecond line\n")).toEqual("first line second line"))
+		it("removes r newline", () =>
+			expect(removeNewlines("first line\r\n\nsecond line\n")).toEqual("first line second line"))
+		it("removes t newline", () => expect(removeNewlines("first line\tsecond line\n")).toEqual("first line second line"))
+		it("removes only a newline", () => expect(removeNewlines("\r")).toEqual(""))
+		it("removes nothing without newline", () => expect(removeNewlines("hey", undefined)).toEqual("hey"))
+		it("cuts string at the right position", () => expect(removeNewlines("ellipsis", 5)).toEqual("ellip"))
+		it("skips cutting if unnecessary", () => expect(removeNewlines("ellipsis", 20)).toEqual("ellipsis"))
+		it("returns empty string for null", () => expect(removeNewlines(null, 10)).toEqual(""))
+		it("returns empty string for undefined", () => expect(removeNewlines(undefined)).toEqual(""))
+		it("returns empty string for empty string", () => expect(removeNewlines("", 10)).toEqual(""))
+	})
+
+	describe("ellipsis", () => {
+		describe("end position (default)", () => {
+			it("truncates text at end with ellipsis", () => expect(ellipsis("Hello World", 8)).toEqual("Hello..."))
+			it("truncates longer text at end", () =>
+				expect(ellipsis("Lorem ipsum dolor sit amet", 15)).toEqual("Lorem ipsum ..."))
+			it("returns original text if shorter than max length", () => expect(ellipsis("Short", 10)).toEqual("Short"))
+			it("returns original text if equal to max length", () => expect(ellipsis("Exactly10!", 10)).toEqual("Exactly10!"))
+			it("handles single character with end position", () => expect(ellipsis("A", 5)).toEqual("A"))
+		})
+
+		describe("middle position", () => {
+			it("truncates text in middle with ellipsis", () =>
+				expect(ellipsis("Hello World", 8, "middle")).toEqual("He...rld"))
+			it("truncates longer text in middle", () =>
+				expect(ellipsis("Lorem ipsum dolor sit amet", 15, "middle")).toEqual("Lorem ...t amet"))
+			it("returns original text if shorter than max length", () =>
+				expect(ellipsis("Short", 10, "middle")).toEqual("Short"))
+			it("returns original text if equal to max length", () =>
+				expect(ellipsis("Exactly10!", 10, "middle")).toEqual("Exactly10!"))
+			it("handles odd length correctly", () => expect(ellipsis("Hello World", 7, "middle")).toEqual("He...ld"))
+			it("handles even length correctly", () => expect(ellipsis("Hello World", 8, "middle")).toEqual("He...rld"))
+		})
+
+		describe("edge cases", () => {
+			it("returns empty string for empty input", () => expect(ellipsis("", 5)).toEqual(""))
+			it("returns empty string for null input", () => expect(ellipsis(null as unknown as string, 5)).toEqual(""))
+			it("returns empty string for undefined input", () =>
+				expect(ellipsis(undefined as unknown as string, 5)).toEqual(""))
+			it("handles very small max length with end position", () => expect(ellipsis("Hello", 3)).toEqual(""))
+			it("handles very small max length with middle position", () => expect(ellipsis("Hello", 3, "middle")).toEqual(""))
+			it("handles max length of 4 with end position", () => expect(ellipsis("Hello", 4)).toEqual("H..."))
+			it("handles max length of 4 with middle position", () => expect(ellipsis("Hello", 4, "middle")).toEqual("...o"))
+		})
+
+		describe("emoji handling", () => {
+			it("truncates text with emojis at end", () => expect(ellipsis("Hello 👋 World 🌍", 12)).toEqual("Hello 👋 ..."))
+			it("truncates text with emojis in middle", () =>
+				expect(ellipsis("Hello 👋 World 🌍", 12, "middle")).toEqual("Hell...ld 🌍"))
+			it("preserves emojis when text is shorter than max length", () => expect(ellipsis("Hi 👋", 10)).toEqual("Hi 👋"))
+			it("handles text with basic emojis", () => expect(ellipsis("Hello world 😊", 10)).toEqual("Hello w..."))
+			it("demonstrates emoji splitting limitation", () => {
+				// Note: This function works with UTF-16 code units, not visual characters
+				// Complex emojis may be split incorrectly at boundaries
+				const result = ellipsis("👨‍💻 Work", 8)
+				expect(result.length).toBeLessThanOrEqual(8)
+			})
+		})
+	})
+})

package/strings.ts

@@ -0,0 +1,46 @@
+export const removeMarkdown = (markdownText: string): string => {
+	const patternsToRemove: Array<{ pattern: RegExp; replacement: string }> = [
+		{ pattern: /!\[.*?\]\(.*?\)|\[(.*?)\]\(.*?\)/g, replacement: "$1" },
+		{
+			pattern: /#{1,6}\s|(\*\*|__|\*|_)(.*?)\1|~~(.*?)~~|>/g,
+			replacement: "$2$3",
+		},
+		{ pattern: /-{3,}|`{3}[\s\S]*?`{3}/g, replacement: "" },
+		{ pattern: /`{1,2}(.*?)`{1,2}/g, replacement: "$1" },
+	]
+
+	let cleanText = markdownText
+
+	for (const { pattern, replacement } of patternsToRemove) {
+		cleanText = cleanText.replace(pattern, replacement)
+	}
+
+	return cleanText
+}
+
+export const removeNewlines = (text?: string | null, limit?: number): string => {
+	if (!text || typeof text !== "string") return ""
+
+	const limitEnd: number = limit ?? text.length ?? 0
+	const cleanString: string = text
+		.replace(/(?:\r\n|\r|\n|\t)+/g, " ")
+		.substring(0, limitEnd)
+		.trim()
+
+	return cleanString
+}
+
+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 (position === "middle") {
+		const halfLength = Math.floor((maxLength - 3) / 2)
+		const remainingLength = maxLength - 3 - halfLength
+
+		return text.substring(0, halfLength) + "..." + text.substring(text.length - remainingLength)
+	}
+
+	return text.substring(0, maxLength - 3) + "..."
+}

package/throttle.spec.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi } from "vitest"
+import { throttle } from "./throttle"
+import { sleep } from "./sleep"
+
+describe("throttle", () => {
+	it("executes callback once within throttle window", async () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		throttled()
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		await sleep(60)
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(2)
+	})
+
+	it("executes immediately on first call", () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(1)
+	})
+
+	it("preserves function arguments on first call", () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		throttled("arg1", "arg2", 123)
+		expect(fn).toHaveBeenCalledWith("arg1", "arg2", 123)
+	})
+
+	it("ignores subsequent calls within throttle window", () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		throttled("first")
+		expect(fn).toHaveBeenCalledWith("first")
+
+		throttled("second")
+		throttled("third")
+		expect(fn).toHaveBeenCalledTimes(1)
+		expect(fn).toHaveBeenCalledWith("first")
+	})
+
+	it("allows execution after throttle window expires", async () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		throttled("first")
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		await sleep(60)
+
+		throttled("second")
+		expect(fn).toHaveBeenCalledTimes(2)
+		expect(fn).toHaveBeenLastCalledWith("second")
+	})
+
+	it("works with functions that have specific parameter types", () => {
+		const fn = vi.fn((str: string, num: number) => str + num)
+		const throttled = throttle(fn, 50)
+
+		throttled("test", 42)
+		expect(fn).toHaveBeenCalledWith("test", 42)
+	})
+
+	it("works with functions that return values", () => {
+		const fn = vi.fn((x: number) => x * 2)
+		const throttled = throttle(fn, 50)
+
+		throttled(5)
+		expect(fn).toHaveBeenCalledWith(5)
+	})
+
+	it("handles rapid successive calls correctly", () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		for (let i = 0; i < 10; i++) {
+			throttled(i)
+		}
+
+		expect(fn).toHaveBeenCalledTimes(1)
+		expect(fn).toHaveBeenCalledWith(0)
+	})
+
+	it("works with zero delay", async () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 0)
+
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		await sleep(1)
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(2)
+	})
+
+	it("maintains separate throttle windows for different throttled functions", () => {
+		const fn1 = vi.fn()
+		const fn2 = vi.fn()
+		const throttled1 = throttle(fn1, 50)
+		const throttled2 = throttle(fn2, 50)
+
+		throttled1()
+		throttled2()
+
+		expect(fn1).toHaveBeenCalledTimes(1)
+		expect(fn2).toHaveBeenCalledTimes(1)
+
+		throttled1()
+		throttled2()
+
+		expect(fn1).toHaveBeenCalledTimes(1)
+		expect(fn2).toHaveBeenCalledTimes(1)
+	})
+
+	it("resets throttle window correctly", async () => {
+		const fn = vi.fn()
+		const throttled = throttle(fn, 50)
+
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		await sleep(25)
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(1)
+
+		await sleep(30)
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(2)
+
+		throttled()
+		expect(fn).toHaveBeenCalledTimes(2)
+	})
+})

package/throttle.ts

@@ -0,0 +1,17 @@
+// 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) => {
+	let timeoutId: ReturnType<typeof setTimeout> | null = null
+
+	return (...args: Parameters<T>): void => {
+		if (!timeoutId) {
+			fn(...args)
+
+			timeoutId = setTimeout(() => {
+				timeoutId = null
+			}, delay)
+		}
+	}
+}

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+	"compilerOptions": {
+		"allowJs": false,
+		"baseUrl": ".",
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"incremental": true,
+		"isolatedModules": true,
+		"jsx": "preserve",
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"noEmit": true,
+		"noFallthroughCasesInSwitch": true,
+		"noImplicitAny": true,
+		"noImplicitOverride": true,
+		"noImplicitReturns": true,
+		"noImplicitThis": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"noUncheckedIndexedAccess": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"exactOptionalPropertyTypes": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"strictBindCallApply": true,
+		"strictFunctionTypes": true,
+		"strictNullChecks": true,
+		"strictPropertyInitialization": true,
+		"target": "ES2022",
+		"useDefineForClassFields": true,
+		"verbatimModuleSyntax": false,
+		"types": ["node"]
+	},
+	"typeRoots": ["./node_modules/@types", "./types"],
+	"include": ["next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
+	"exclude": ["node_modules"]
+}

package/uuid.spec.ts

@@ -0,0 +1,32 @@
+import { it, describe, expect } from "vitest"
+import { getUUID, isUUID } from "./uuid"
+
+describe("validations", () => {
+	describe("getUUID", () => {
+		const UUID_1 = getUUID()
+		const UUID_1_IS_VALID = isUUID(UUID_1)
+		const UUID_2_STRING = "any-string"
+		const UUID_2 = getUUID(UUID_2_STRING)
+		const UUID_3 = getUUID()
+		const UUID_4 = getUUID()
+
+		it("returns a valid uuid", () => expect(UUID_1_IS_VALID).toEqual(true))
+		it("returns passed through", () => expect(UUID_2).toEqual(UUID_2_STRING))
+		it("returns different uuids on separate calls", () => expect(UUID_3).not.toEqual(UUID_4))
+	})
+
+	describe("isUUID", () => {
+		const UUID_3 = getUUID()
+		const UUID_3_IS_VALID = isUUID(UUID_3)
+		const UUID_4_IS_VALID = isUUID("101bfe56-8c16-4f94-9b45-759ea5e67cea")
+
+		it("validates a random uuid", () => expect(UUID_3_IS_VALID).toEqual(true))
+		it("validates a static uuid", () => expect(UUID_4_IS_VALID).toEqual(true))
+
+		const UUID_5_IS_VALID = isUUID("")
+		const UUID_6_IS_VALID = isUUID(undefined)
+
+		it("catches empty string", () => expect(UUID_5_IS_VALID).toEqual(false))
+		it("catches undefined", () => expect(UUID_6_IS_VALID).toEqual(false))
+	})
+})

package/uuid.ts

@@ -0,0 +1,14 @@
+export const getUUID = (id?: unknown): string => {
+	if (id) return id as string
+
+	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"
+
+	if (!isValid) return false
+
+	return uuidRegex.test(uuid)
+}