@wexample/js-helpers 0.0.26 → 0.0.34

package/README.md

@@ -1,137 +1,10 @@
 # @wexample/js-helpers
 
-Version: 0.0.26
+Version: 0.0.34
 
 Modern, type-safe helper utilities for Wexample projects.
 
 ## Table of Contents
 
-- [Api Reference](#api-reference)
-- [Code Quality](#code-quality)
-- [Versioning](#versioning)
-- [Changelog](#changelog)
-- [Migration Notes](#migration-notes)
-- [Security](#security)
-- [Privacy](#privacy)
-- [Support](#support)
-- [Contribution Guidelines](#contribution-guidelines)
-- [Maintainers](#maintainers)
-- [License](#license)
-- [Suite Integration](#suite-integration)
-- [Compatibility Matrix](#compatibility-matrix)
-- [Dependencies](#dependencies)
-- [Suite Signature](#suite-signature)
 
 
-## API Reference
-
-Full API documentation is available in the source code docstrings.
-
-Key modules and classes are documented with type hints for better IDE support.
-
-## Code Quality & Typing
-
-All the suite packages follow strict quality standards:
-
-- **Type hints**: Full type coverage with mypy validation
-- **Code formatting**: Enforced with black and isort
-- **Linting**: Comprehensive checks with custom scripts and tools
-- **Testing**: High test coverage requirements
-
-These standards ensure reliability and maintainability across the suite.
-
-## Versioning & Compatibility Policy
-
-Wexample packages follow **Semantic Versioning** (SemVer):
-
-- **MAJOR**: Breaking changes
-- **MINOR**: New features, backward compatible
-- **PATCH**: Bug fixes, backward compatible
-
-We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
-
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.
-
-Major changes are documented with migration guides when applicable.
-
-## Migration Notes
-
-When upgrading between major versions, refer to the migration guides in the documentation.
-
-Breaking changes are clearly documented with upgrade paths and examples.
-
-## Security Policy
-
-### Reporting Vulnerabilities
-
-If you discover a security vulnerability, please email contact@wexample.com.
-
-**Do not** open public issues for security vulnerabilities.
-
-We take security seriously and will respond promptly to verified reports.
-
-## Privacy & Telemetry
-
-This package does **not** collect any telemetry or usage data.
-
-Your privacy is respected — no data is transmitted to external services.
-
-## Support Channels
-
-- **GitHub Issues**: Bug reports and feature requests
-- **GitHub Discussions**: Questions and community support
-- **Documentation**: Comprehensive guides and API reference
-- **Email**: contact@wexample.com for general inquiries
-
-Community support is available through GitHub Discussions.
-
-## Contribution Guidelines
-
-We welcome contributions to the Wexample suite!
-
-### How to Contribute
-
-1. **Fork** the repository
-2. **Create** a feature branch
-3. **Make** your changes
-4. **Test** thoroughly
-5. **Submit** a pull request
-
-## Maintainers & Authors
-
-Maintained by the Wexample team and community contributors.
-
-See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the full list of contributors.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-Free to use in both personal and commercial projects.
-
-## Integration in the Suite
-
-This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
-
-### Related Packages
-
-The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
-
-Visit the [Wexample Suite documentation](https://docs.wexample.com) for the complete package ecosystem.
-
-## Compatibility Matrix
-
-This package is part of the Wexample suite and is compatible with other suite packages.
-
-Refer to each package's documentation for specific version compatibility requirements.
-
-# About us
-
-[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
-
-This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
-
-Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
-

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@wexample/js-helpers",
-  "version": "0.0.26",
+  "version": "0.0.34",
   "description": "Modern, type-safe helper utilities for Wexample projects.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "scripts": {
-    "clean": "rm -rf dist",
-    "build": "npm run clean && tsc",
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "lint": "npm run typecheck",
     "prepublishOnly": "npm run build"
   },
@@ -24,17 +24,25 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
   "repository": "https://github.com/wexample/js-helpers",
   "files": [
-    "dist"
+    "src"
   ],
   "exports": {
     "./*": {
-      "types": "./dist/*.d.ts",
-      "default": "./dist/*.js"
+      "types": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
     }
   }
 }

package/src/Common/AsyncConstructor.ts

@@ -0,0 +1,47 @@
+import { functionIsType } from '../Helper/Function.js';
+
+type AnyFn<TThis, TArgs extends unknown[]> = (this: TThis, ...args: TArgs) => void | Promise<void>;
+
+export default abstract class AsyncConstructor<TArgs extends unknown[] = unknown[]> {
+  private _isReady = false;
+  private _readyArgs: TArgs | null = null;
+  private readonly readyCallbacks: Array<AnyFn<this, TArgs>> = [];
+
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
+  protected defer(fn: () => void): void {
+    if (typeof queueMicrotask === 'function') queueMicrotask(fn);
+    else setTimeout(fn, 0);
+  }
+
+  ready(cb: AnyFn<this, TArgs>): void {
+    if (this._isReady) {
+      const args = this._readyArgs ?? ([] as unknown as TArgs);
+      this.defer(() => void cb.apply(this, args));
+      return;
+    }
+    this.readyCallbacks.push(cb);
+  }
+
+  protected async readyComplete(...args: TArgs): Promise<void> {
+    if (this._isReady) return;
+
+    this._isReady = true;
+    this._readyArgs = args;
+
+    const callbacks = this.readyCallbacks.splice(0);
+
+    for (const cb of callbacks) {
+      if (!functionIsType(cb)) {
+        throw new TypeError('Ready callback must be a function.');
+      }
+      await cb.apply(this, args);
+    }
+  }
+
+  protected seal(): void {
+    Object.seal(this);
+  }
+}

package/src/Common/RetryBackoffScheduler.ts

@@ -0,0 +1,64 @@
+import {
+  type ReconnectBackoffController,
+  type ReconnectBackoffOptions,
+  reconnectBackoffCreateController,
+} from '../Helper/Reconnect';
+
+export type RetryBackoffScheduleContext = {
+  attempt: number;
+  delayMs: number;
+};
+
+export default class RetryBackoffScheduler {
+  private readonly controller: ReconnectBackoffController;
+  private timeout: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(options: ReconnectBackoffOptions = {}) {
+    this.controller = reconnectBackoffCreateController(options);
+  }
+
+  get attempt(): number {
+    return this.controller.getAttempt();
+  }
+
+  get isScheduled(): boolean {
+    return this.timeout !== null;
+  }
+
+  canRetry(): boolean {
+    return this.controller.canRetry();
+  }
+
+  reset(): void {
+    this.cancel();
+    this.controller.reset();
+  }
+
+  cancel(): void {
+    if (!this.timeout) {
+      return;
+    }
+
+    clearTimeout(this.timeout);
+    this.timeout = null;
+  }
+
+  schedule(run: () => void): RetryBackoffScheduleContext | null {
+    if (this.timeout || !this.controller.canRetry()) {
+      return null;
+    }
+
+    const delayMs = this.controller.nextDelay();
+    const context: RetryBackoffScheduleContext = {
+      attempt: this.controller.getAttempt(),
+      delayMs,
+    };
+
+    this.timeout = setTimeout(() => {
+      this.timeout = null;
+      run();
+    }, delayMs);
+
+    return context;
+  }
+}

package/src/Helper/AbstractMixin.ts

@@ -0,0 +1,18 @@
+export default abstract class AbstractMixin {
+  protected static applyOnce(
+    instance: any,
+    apply: (instance: any) => void,
+    flag?: string
+  ): boolean {
+    const key = flag || `__mixin_${AbstractMixin.name}`;
+
+    if (instance[key]) {
+      return false;
+    }
+
+    instance[key] = true;
+    apply(instance);
+
+    return true;
+  }
+}

package/src/Helper/Animation.ts

@@ -0,0 +1,47 @@
+export const waitForAnimationEnd = (
+  el: HTMLElement | null,
+  softTimeoutMs = 220,
+  hardTimeoutMs = 10000
+): Promise<void> => {
+  if (!el) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    let started = false;
+    let resolved = false;
+
+    const clear = () => {
+      el.removeEventListener('animationstart', onStart);
+      el.removeEventListener('animationend', onEnd);
+    };
+
+    const finish = () => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      clear();
+      resolve();
+    };
+
+    const onStart = () => {
+      started = true;
+      window.setTimeout(finish, hardTimeoutMs);
+    };
+
+    const onEnd = () => {
+      finish();
+    };
+
+    el.addEventListener('animationstart', onStart, { once: true });
+    el.addEventListener('animationend', onEnd, { once: true });
+
+    // Soft timeout if no animation starts.
+    window.setTimeout(() => {
+      if (!started) {
+        finish();
+      }
+    }, softTimeoutMs);
+  });
+};

package/src/Helper/Array.ts

@@ -0,0 +1,30 @@
+export function arrayDeleteItem<T>(haystack: T[], needle: T): T[] {
+  return arrayDeleteByIndex(haystack, haystack.indexOf(needle));
+}
+
+export function arrayDeleteByIndex<T>(haystack: T[], index: number): T[] {
+  if (index !== -1) {
+    haystack.splice(index, 1);
+  }
+
+  return haystack;
+}
+
+/**
+ * Functions "arguments" object may be transformed to real array for extra manipulations.
+ */
+export function arrayFromArguments<T>(args: ArrayLike<T>): T[] {
+  return Array.prototype.slice.call(args);
+}
+
+export function arrayShallowCopy<T>(array: T[]): T[] {
+  return array.slice(0);
+}
+
+export function arrayUnique<T>(array: T[]): T[] {
+  return array.filter((value, index) => array.indexOf(value) === index);
+}
+
+export function arrayFindByIndex<T>(array: T[], position: number): T | undefined {
+  return array[position >= 0 ? position : array.length + position];
+}

package/src/Helper/Bytes.ts

@@ -0,0 +1,12 @@
+export function bytesFormatBytes(bytes: number, decimals = 2): string {
+  if (bytes === 0) {
+    return '0 Bytes';
+  }
+
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / k ** i).toFixed(dm))} ${sizes[i]}`;
+}

package/src/Helper/Dom.ts

@@ -0,0 +1,142 @@
+export const DOM_ATTRIBUTE = {
+  HREF: 'href',
+  ID: 'id',
+  REL: 'rel',
+  SRC: 'src',
+} as const;
+
+export const DOM_ATTRIBUTE_VALUE = {
+  STYLESHEET: 'stylesheet',
+} as const;
+
+export const DOM_INSERT_POSITION = {
+  BEFORE_END: 'beforeend' as InsertPosition,
+} as const;
+
+export const DOM_TAG_NAME = {
+  A: 'a',
+  DIV: 'div',
+  LINK: 'link',
+  SCRIPT: 'script',
+} as const;
+
+export type DomScrollToBottomOptions = {
+  container?: HTMLElement | null;
+  behavior?: ScrollBehavior;
+  retries?: number;
+  includeHidden?: boolean;
+};
+
+export function domAppendInnerHtml(el: HTMLElement, html: string): void {
+  el.insertAdjacentHTML(DOM_INSERT_POSITION.BEFORE_END, html);
+}
+
+export function domFindPreviousNode(el: HTMLElement): HTMLElement | null {
+  let current: ChildNode | null = el;
+
+  do {
+    current = current?.previousSibling ?? null;
+  } while (current && current.nodeType === Node.TEXT_NODE);
+
+  return current as HTMLElement | null;
+}
+
+/**
+ * Return first scrollable parent.
+ *
+ * @see https://stackoverflow.com/a/42543908/2057976
+ */
+export function domFindScrollParent(element: HTMLElement, includeHidden = false): HTMLElement {
+  const style = getComputedStyle(element);
+  const overflowRegex = includeHidden ? /(auto|scroll|hidden)/ : /(auto|scroll)/;
+  const excludeStaticParent = style.position === 'absolute';
+
+  if (style.position === 'fixed') {
+    return document.body;
+  }
+
+  let parent: HTMLElement | null = element.parentElement;
+  while (parent) {
+    const parentStyle = getComputedStyle(parent);
+
+    if (
+      (!excludeStaticParent || parentStyle.position !== 'static') &&
+      overflowRegex.test(parentStyle.overflow + parentStyle.overflowY + parentStyle.overflowX)
+    ) {
+      return parent;
+    }
+
+    parent = parent.parentElement;
+  }
+
+  return document.body;
+}
+
+export function domToggleMainOverlay(visible: boolean | null = null): void {
+  const overlay = document.getElementById('main-overlay');
+  if (!overlay) return;
+
+  const classList = overlay.classList;
+  const shouldShow = visible !== null ? visible : !classList.contains('visible');
+
+  classList[shouldShow ? 'add' : 'remove']('visible');
+}
+
+export function domCreateHtmlDocumentFromHtml(html: string): HTMLHtmlElement {
+  const root = document.createElement('html');
+  root.innerHTML = html;
+  return root;
+}
+
+export function domRemoveAllClasses(el: HTMLElement, classesToRemove: Iterable<string>): void {
+  for (const className of classesToRemove) {
+    el.classList.remove(className);
+  }
+}
+
+export function domReplaceByOneClass(
+  el: HTMLElement,
+  newState: string,
+  classesToRemove: Iterable<string>
+): void {
+  domRemoveAllClasses(el, classesToRemove);
+  el.classList.add(newState);
+}
+
+export function domScrollToBottom(
+  anchorElement: HTMLElement | null,
+  options: DomScrollToBottomOptions = {}
+): void {
+  if (!anchorElement) {
+    return;
+  }
+
+  const { container = null, behavior = 'auto', retries = 0, includeHidden = false } = options;
+
+  const scrollContainer = container ?? domFindScrollParent(anchorElement, includeHidden);
+  if (!scrollContainer) {
+    return;
+  }
+
+  const targetTop = scrollContainer.scrollHeight;
+
+  if (typeof scrollContainer.scrollTo === 'function') {
+    scrollContainer.scrollTo({
+      top: targetTop,
+      behavior,
+    });
+  } else {
+    scrollContainer.scrollTop = targetTop;
+  }
+
+  if (retries > 0) {
+    window.requestAnimationFrame(() => {
+      domScrollToBottom(anchorElement, {
+        container: scrollContainer,
+        behavior,
+        retries: retries - 1,
+        includeHidden,
+      });
+    });
+  }
+}

package/src/Helper/ElementSize.ts

@@ -0,0 +1,87 @@
+export const waitForElementSize = (
+  el: HTMLElement | null,
+  minHeight = 1,
+  timeoutMs = 500,
+  ready?: (el: HTMLElement) => boolean
+): Promise<void> => {
+  if (!el) {
+    return Promise.resolve();
+  }
+
+  const hasSize = () => (ready ? ready(el) : el.getBoundingClientRect().height >= minHeight);
+
+  if (hasSize()) {
+    return Promise.resolve();
+  }
+
+  const runRafProbe = () =>
+    new Promise<void>((resolve) => {
+      let attempts = 0;
+      const tick = () => {
+        if (hasSize() || attempts >= 8) {
+          resolve();
+          return;
+        }
+        attempts += 1;
+        requestAnimationFrame(tick);
+      };
+      requestAnimationFrame(tick);
+    });
+
+  const runResizeObserver = () =>
+    new Promise<void>((resolve) => {
+      if (typeof ResizeObserver === 'undefined') {
+        resolve();
+        return;
+      }
+
+      let done = false;
+      const observer = new ResizeObserver(() => {
+        if (done) {
+          return;
+        }
+        if (hasSize()) {
+          done = true;
+          observer.disconnect();
+          resolve();
+        }
+      });
+
+      observer.observe(el);
+
+      window.setTimeout(() => {
+        if (done) {
+          return;
+        }
+        done = true;
+        observer.disconnect();
+        resolve();
+      }, timeoutMs);
+    });
+
+  const runIntervalProbe = () =>
+    new Promise<void>((resolve) => {
+      let attempts = 0;
+      const maxAttempts = 6;
+      const intervalMs = 500;
+      const timer = window.setInterval(() => {
+        attempts += 1;
+        if (hasSize() || attempts >= maxAttempts) {
+          clearInterval(timer);
+          resolve();
+        }
+      }, intervalMs);
+    });
+
+  return runRafProbe().then(() => {
+    if (hasSize()) {
+      return;
+    }
+    return runResizeObserver().then(() => {
+      if (hasSize()) {
+        return;
+      }
+      return runIntervalProbe();
+    });
+  });
+};

package/src/Helper/Event.ts

@@ -0,0 +1,30 @@
+export const EVENT = {
+  CLICK: 'click',
+  DBLCLICK: 'dblclick',
+  CONTEXTMENU: 'contextmenu',
+  KEYDOWN: 'keydown',
+  KEYUP: 'keyup',
+  KEYPRESS: 'keypress',
+  INPUT: 'input',
+  CHANGE: 'change',
+  FOCUS: 'focus',
+  BLUR: 'blur',
+  SUBMIT: 'submit',
+  RESET: 'reset',
+  MOUSEUP: 'mouseup',
+  MOUSEDOWN: 'mousedown',
+  MOUSEMOVE: 'mousemove',
+  MOUSEENTER: 'mouseenter',
+  MOUSELEAVE: 'mouseleave',
+  WHEEL: 'wheel',
+  SCROLL: 'scroll',
+  RESIZE: 'resize',
+  TOUCHSTART: 'touchstart',
+  TOUCHMOVE: 'touchmove',
+  TOUCHEND: 'touchend',
+  POINTERDOWN: 'pointerdown',
+  POINTERMOVE: 'pointermove',
+  POINTERUP: 'pointerup',
+} as const;
+
+export type EventName = (typeof EVENT)[keyof typeof EVENT];

package/src/Helper/Function.ts

@@ -0,0 +1,5 @@
+export function functionIsType<TArgs extends unknown[] = unknown[], R = unknown>(
+  value: unknown
+): value is (...args: TArgs) => R {
+  return typeof value === 'function';
+}

package/src/Helper/Height.ts

@@ -0,0 +1,20 @@
+import { waitForTransitionEnd } from './Transition';
+
+export const expandHeight = async (el: HTMLElement, propertyName = 'height'): Promise<void> => {
+  el.style.height = '0px';
+  el.style.overflow = 'hidden';
+  void el.offsetHeight;
+  const targetHeight = el.scrollHeight;
+  el.style.height = `${targetHeight}px`;
+  await waitForTransitionEnd(el, propertyName);
+  el.style.height = '';
+  el.style.overflow = '';
+};
+
+export const collapseHeight = async (el: HTMLElement, propertyName = 'height'): Promise<void> => {
+  el.style.height = `${el.scrollHeight}px`;
+  el.style.overflow = 'hidden';
+  void el.offsetHeight;
+  el.style.height = '0px';
+  await waitForTransitionEnd(el, propertyName);
+};

package/src/Helper/Id.ts

@@ -0,0 +1,3 @@
+export function buildUniqueId(prefix: string = 'id'): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}