@mkmonkeycat/dom-utils 0.1.0

package/src/dom/style.ts

@@ -0,0 +1,23 @@
+/**
+ * Injects a <style> tag with the provided CSS into the document.
+ * @param css - The CSS text to inject.
+ * @param options - Optional configuration such as `id`, `nonce`, and target container.
+ * @returns An object containing the created style element and a `remove` function.
+ */
+export const injectStyle = (
+  css: string,
+  options: { id?: string; nonce?: string; target?: HTMLElement } = {},
+): { style: HTMLStyleElement; remove: () => void } => {
+  const { id, nonce, target = document.head } = options;
+  const style = document.createElement('style');
+  if (id) style.id = id;
+  if (nonce) style.setAttribute('nonce', nonce);
+  style.textContent = css;
+  target.appendChild(style);
+
+  const remove = () => {
+    style.parentNode?.removeChild(style);
+  };
+
+  return { style, remove };
+};

package/src/dom/tag-internal.ts

@@ -0,0 +1,19 @@
+import { isMarkedAs, markFunc, type TaggedFunction } from '../utils/tag';
+
+/**
+ * Marks a function as an mk utils internal event handler.
+ * @param func - The function to mark.
+ * @returns The marked function.
+ */
+export const markAsEventFunc = <F extends CallableFunction>(
+  func: F,
+): TaggedFunction<F, '__mkEvent'> => markFunc(func, '__mkEvent');
+
+/**
+ * Checks if a function is marked as an mk utils internal event handler.
+ * @param func - The function to check.
+ * @returns True if the function is marked as an event handler, false otherwise.
+ */
+export const isEventFunc = <F extends CallableFunction>(
+  func: F,
+): func is TaggedFunction<F, '__mkEvent'> => isMarkedAs(func, '__mkEvent');

package/src/dom/win.ts

@@ -0,0 +1,21 @@
+export const globalWin: Win = typeof unsafeWindow !== 'undefined' ? unsafeWindow : window;
+export const globalDoc: Document = globalWin.document;
+
+export function getWin(): Win;
+export function getWin(
+  target: Node | Event | ShadowRoot | Document | Window | null | undefined,
+): Win | null;
+export function getWin(target?: Node | Event | ShadowRoot | Document | Window | null): Win | null {
+  if (!target) return globalWin;
+
+  if (target instanceof Window) return target as Win;
+  if (target instanceof UIEvent && target.view) return target.view as Win;
+  if (target instanceof Document) return target.defaultView;
+  if (target instanceof ShadowRoot) return target.host.ownerDocument?.defaultView ?? null;
+  if (target instanceof Node) return target.ownerDocument?.defaultView ?? null;
+
+  return null;
+}
+
+export type Win = Window & typeof globalThis;
+declare const unsafeWindow: Win | undefined;

package/src/index.ts

@@ -0,0 +1,4 @@
+export const VERSION = '0.0.1';
+
+export * from './dom';
+export * from './utils';

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './string';
+export * from './tag';
+export * from './timing';
+export * from './types';

package/src/utils/string.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a camelCase string to kebab-case.
+ * @param str - The camelCase string to convert.
+ * @returns The kebab-case string.
+ */
+export const camelToKebab = (str: string): string => {
+  return str.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, '$1-$2').toLowerCase();
+};
+
+/**
+ * Converts a PascalCase string to kebab-case.
+ * @param str - The PascalCase string to convert.
+ * @returns The kebab-case string.
+ */
+export const pascalToKebab = (str: string): string => {
+  return str.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, '$1-$2').toLowerCase();
+};

package/src/utils/tag.ts

@@ -0,0 +1,31 @@
+/**
+ * Type representing a function tagged with a specific string.
+ */
+export type TaggedFunction<F extends CallableFunction, T extends string> = F & {
+  readonly [K in T]?: true;
+};
+
+/**
+ * Marks a function with a specific tag.
+ * @param func - The function to mark.
+ * @param tag - The tag to assign.
+ * @returns The marked function.
+ */
+export const markFunc = <F extends CallableFunction, T extends string>(
+  func: F,
+  tag: T,
+): TaggedFunction<F, T> => {
+  Object.defineProperty(func, tag, { value: true });
+  return func as TaggedFunction<F, T>;
+};
+
+/**
+ * Checks if a function is marked with a specific tag.
+ * @param func - The function to check.
+ * @param tag - The tag to look for.
+ * @returns True if the function is marked with the tag, false otherwise.
+ */
+export const isMarkedAs = <F extends CallableFunction, T extends string>(
+  func: F,
+  tag: T,
+): func is TaggedFunction<F, T> => !!(func as Record<string, unknown>)[tag];

package/src/utils/timing.ts

@@ -0,0 +1,179 @@
+/**
+ * Debounce function that delays the execution of a callback until after a specified wait time has elapsed.
+ * @param callback - The function to debounce.
+ * @param wait - The delay in milliseconds.
+ * @returns A debounced function with cancel and flush methods.
+ */
+export const debounce = <T extends (...args: unknown[]) => unknown>(
+  callback: T,
+  wait: number,
+): ((...args: Parameters<T>) => void) & { cancel: () => void; flush: () => void } => {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let lastArgs: Parameters<T> | null = null;
+
+  const debounced = (...args: Parameters<T>) => {
+    lastArgs = args;
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      callback(...lastArgs!);
+      timeoutId = null;
+      lastArgs = null;
+    }, wait);
+  };
+
+  debounced.cancel = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = null;
+    lastArgs = null;
+  };
+
+  debounced.flush = () => {
+    if (timeoutId) {
+      callback(...lastArgs!);
+      clearTimeout(timeoutId);
+      timeoutId = null;
+      lastArgs = null;
+    }
+  };
+
+  return debounced;
+};
+
+/**
+ * Throttle function that executes a callback at most once every specified wait time.
+ * @param callback - The function to throttle.
+ * @param wait - The minimum interval in milliseconds between executions.
+ * @returns A throttled function with cancel and flush methods.
+ */
+export const throttle = <T extends (...args: unknown[]) => unknown>(
+  callback: T,
+  wait: number,
+): ((...args: Parameters<T>) => void) & { cancel: () => void; flush: () => void } => {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let lastArgs: Parameters<T> | null = null;
+  let lastCallTime = 0;
+
+  const cleanup = () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  const throttled = (...args: Parameters<T>) => {
+    const now = Date.now();
+    lastArgs = args;
+
+    if (lastCallTime === 0) {
+      callback(...args);
+      lastCallTime = now;
+    } else {
+      const elapsed = now - lastCallTime;
+      if (elapsed >= wait) {
+        callback(...args);
+        lastCallTime = now;
+        cleanup();
+      } else {
+        cleanup();
+        timeoutId = setTimeout(() => {
+          callback(...lastArgs!);
+          lastCallTime = Date.now();
+          timeoutId = null;
+        }, wait - elapsed);
+      }
+    }
+  };
+
+  throttled.cancel = () => {
+    cleanup();
+    lastCallTime = 0;
+    lastArgs = null;
+  };
+
+  throttled.flush = () => {
+    if (lastCallTime > 0 && lastArgs !== null) {
+      callback(...lastArgs);
+    }
+    cleanup();
+    lastCallTime = 0;
+    lastArgs = null;
+  };
+
+  return throttled;
+};
+
+/**
+ * Creates a promise that resolves after a specified delay.
+ * @param ms - The delay in milliseconds.
+ * @returns A promise that resolves after the delay.
+ */
+export const delay = (ms: number): Promise<void> => {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+};
+
+/**
+ * Pauses execution for a specified duration in async contexts.
+ * @param ms - The duration to sleep in milliseconds.
+ * @returns A promise that resolves after the sleep duration.
+ */
+export const sleep = (ms: number): Promise<void> => delay(ms);
+
+/**
+ * Creates a promise that rejects if the given promise doesn't resolve within the specified timeout.
+ * @param promise - The promise to apply a timeout to.
+ * @param ms - The timeout duration in milliseconds.
+ * @param message - Optional error message for the timeout error.
+ * @returns A promise that resolves with the original promise's value or rejects on timeout.
+ */
+export const timeout = <T>(
+  promise: Promise<T>,
+  ms: number,
+  message = `Operation timed out after ${ms}ms`,
+): Promise<T> => {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => setTimeout(() => reject(new Error(message)), ms)),
+  ]);
+};
+
+/**
+ * A no-operation function that does nothing when called.
+ */
+export const noop = (): void => {};
+
+/**
+ * Retries a function until it succeeds or reaches the maximum number of attempts.
+ * @param fn - The async function to retry.
+ * @param options - Configuration options for retry behavior.
+ * @returns A promise that resolves with the function result or rejects if all attempts fail.
+ */
+export const retry = async <T>(
+  fn: () => Promise<T>,
+  options: {
+    /** Maximum number of attempts. Default: 3 */
+    maxAttempts?: number;
+    /** Delay in milliseconds between attempts. Default: 1000 */
+    delay?: number;
+    /** Whether to use exponential backoff. Default: false */
+    exponential?: boolean;
+  } = {},
+): Promise<T> => {
+  const { maxAttempts = 3, delay = 1000, exponential = false } = options;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt < maxAttempts) {
+        const waitTime = exponential ? delay * Math.pow(2, attempt - 1) : delay;
+        await new Promise((resolve) => setTimeout(resolve, waitTime));
+      }
+    }
+  }
+
+  throw lastError || new Error('Retry failed');
+};

package/src/utils/types.ts

@@ -0,0 +1,14 @@
+/**
+ * A type that represents a value that can be either a single instance of type T or an array of type T.
+ */
+export type SingleOrArray<T> = T | T[];
+
+/**
+ * A type that represents a value that can be either a direct value of type T or a Promise that resolves to type T.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * A type that represents a value that can be null or undefined.
+ */
+export type Nullable<T> = T | null | undefined;

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,21 @@
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+
+const name = 'MKDomUtils';
+const fileName = name.toLowerCase();
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+export default defineConfig({
+  build: {
+    lib: {
+      name,
+      entry: resolve(__dirname, 'src/index.ts'),
+      formats: ['es', 'cjs', 'umd', 'iife'],
+      fileName: (format) => `${fileName}${format.includes('es') ? '' : `.${format}`}.js`,
+    },
+    rollupOptions: { output: { assetFileNames: () => `${fileName}[extname]` } },
+  },
+  plugins: [dts()],
+});

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'jsdom',
+    setupFiles: ['./tests/setup.ts'],
+    coverage: {
+      provider: 'v8',
+    },
+  },
+});