@wexample/js-helpers 0.0.26 → 0.0.35

package/src/Helper/KeyCode.ts

@@ -0,0 +1,5 @@
+export const KEY_CODE = {
+  ESCAPE: 'Escape',
+} as const;
+
+export type KeyCode = (typeof KEY_CODE)[keyof typeof KEY_CODE];

package/src/Helper/Location.ts

@@ -0,0 +1,65 @@
+let locationParamsHash: URLSearchParams | null = null;
+
+export function locationParamReload(): URLSearchParams {
+  locationParamsHash = new URLSearchParams(window.location.hash.slice(1));
+  return locationParamsHash;
+}
+
+export function locationHashParamGet(name: string, defaultValue = ''): string {
+  const params = locationParamReload();
+  const value = params.get(name);
+  return value !== null ? value : defaultValue;
+}
+
+export function locationHashParamSet(name: string, value: string, ignoreHistory = false): void {
+  const params = locationParamReload();
+  params.set(name, value);
+
+  const { pathname, search } = window.location;
+  locationUpdate(`${pathname}${search}#${params.toString()}`, ignoreHistory);
+}
+
+export function locationUpdate(href: string, ignoreHistory = false): void {
+  let nextHref = href;
+
+  if (nextHref.endsWith('#')) {
+    nextHref = nextHref.slice(0, -1);
+  }
+
+  const method: 'pushState' | 'replaceState' = ignoreHistory ? 'replaceState' : 'pushState';
+  window.history[method]({ manualState: true }, document.title, nextHref);
+}
+
+export function locationDetectLanguageAndRedirect(
+  config: Record<string, string> & { _default: string }
+): void {
+  const userLanguage = (
+    navigator.language ||
+    (navigator as unknown as { userLanguage?: string })?.userLanguage ||
+    ''
+  ).toLowerCase();
+  const currentPath = window.location.pathname;
+
+  const redirectUrls = Object.values(config);
+  const escaped = redirectUrls.map((url) => url.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const redirectPattern = new RegExp(`^(${escaped.join('|')})`);
+
+  if (redirectPattern.test(currentPath)) {
+    return;
+  }
+
+  let redirectUrl = config._default;
+
+  for (const [lang, url] of Object.entries(config)) {
+    if (lang === '_default') {
+      continue;
+    }
+    if (userLanguage.startsWith(lang.toLowerCase())) {
+      redirectUrl = url;
+      break;
+    }
+  }
+
+  const restOfPath = currentPath.replace(/^\//, '');
+  window.location.href = `${redirectUrl}${restOfPath}`;
+}

package/src/Helper/Log.ts

@@ -0,0 +1,41 @@
+export const COLORS = {
+  blue: '34',
+  cyan: '36',
+  gray: '90',
+  green: '32',
+  magenta: '35',
+  yellow: '33',
+  red: '31',
+} as const;
+
+type ColorValue = keyof typeof COLORS | string;
+
+export function logColor(text: string, colorCode: ColorValue = COLORS.gray): string {
+  const resolved =
+    typeof colorCode === 'string' && colorCode in COLORS
+      ? COLORS[colorCode as keyof typeof COLORS]
+      : colorCode || COLORS.gray;
+
+  return `\x1b[${resolved}m${text}\x1b[0m`;
+}
+
+export function logTitle(title: string, colorCode: ColorValue = COLORS.cyan): void {
+  console.log('');
+  console.log(logColor(`# ${String(title).toUpperCase()}`, colorCode));
+}
+
+export function logPath(
+  label: string,
+  value: string,
+  labelColor: ColorValue = COLORS.gray,
+  valueColor: ColorValue = COLORS.yellow
+): void {
+  console.log(`${logColor(label, labelColor)} ${logColor(value, valueColor)}`);
+}
+
+export function logEntry(action: string, entry: { output: string; source: string }): void {
+  console.log(
+    `${logColor('•', COLORS.green)} ${logColor(action, COLORS.blue)} ${logColor(entry.output, COLORS.yellow)}`
+  );
+  console.log(`    ${logColor('from', COLORS.gray)} ${logColor(entry.source, COLORS.gray)}`);
+}

package/src/Helper/Mixin.ts

@@ -0,0 +1,33 @@
+type Constructor<T = any> = abstract new (...args: any[]) => T;
+
+/**
+ * Apply mixin classes to a target class (TypeScript-compatible).
+ * Copy prototype properties (except constructor) and static props.
+ */
+export function mixinApply(targetCtor: Constructor, mixins: Constructor[]): void {
+  mixins.forEach((mixinCtor) => {
+    // Copy instance members (prototype).
+    Object.getOwnPropertyNames(mixinCtor.prototype).forEach((name) => {
+      if (name === 'constructor') {
+        return;
+      }
+
+      const descriptor = Object.getOwnPropertyDescriptor(mixinCtor.prototype, name);
+      if (descriptor) {
+        Object.defineProperty(targetCtor.prototype, name, descriptor);
+      }
+    });
+
+    // Copy static members if any (excluding length/name/prototype).
+    Object.getOwnPropertyNames(mixinCtor).forEach((name) => {
+      if (['length', 'name', 'prototype'].includes(name)) {
+        return;
+      }
+
+      const descriptor = Object.getOwnPropertyDescriptor(mixinCtor, name);
+      if (descriptor) {
+        Object.defineProperty(targetCtor, name, descriptor);
+      }
+    });
+  });
+}

package/src/Helper/NodeEnv.ts

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function nodeEnvReadVarFromDotEnvFiles(
+  variableName: string,
+  envFiles: string[] = ['.env.local', '.env.build', '.env']
+): string | null {
+  for (const envFile of envFiles) {
+    const envPath = path.resolve(process.cwd(), envFile);
+    if (!fs.existsSync(envPath)) {
+      continue;
+    }
+
+    const lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+    for (const line of lines) {
+      const value = nodeEnvParseDotEnvLine(line, variableName);
+      if (value !== null) {
+        return value;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function nodeEnvParseDotEnvLine(line: string, variableName: string): string | null {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return null;
+  }
+
+  const match = trimmed.match(new RegExp(`^(?:export\\s+)?${variableName}\\s*=\\s*(.*)$`));
+  if (!match) {
+    return null;
+  }
+
+  let value = match[1].trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1);
+  }
+
+  return value;
+}

package/src/Helper/NodeFs.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function nodeFsListFilesRecursively(
+  rootPath: string,
+  ignoredDirectoryNames: string[] = ['.git', 'node_modules']
+): string[] {
+  const files: string[] = [];
+  const directories = [rootPath];
+
+  while (directories.length) {
+    const currentPath = directories.pop();
+    if (!currentPath) {
+      continue;
+    }
+
+    const entries = fs.readdirSync(currentPath, { withFileTypes: true });
+
+    entries.forEach((entry) => {
+      if (ignoredDirectoryNames.includes(entry.name)) {
+        return;
+      }
+
+      const absolutePath = path.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        directories.push(absolutePath);
+        return;
+      }
+
+      if (entry.isFile()) {
+        files.push(absolutePath);
+      }
+    });
+  }
+
+  return files;
+}

package/src/Helper/NodePath.ts

@@ -0,0 +1,23 @@
+import path from 'node:path';
+
+export function nodePathNormalizeToAbsolute(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed.length) {
+    return null;
+  }
+
+  return path.resolve(trimmed);
+}
+
+export function nodePathToPosix(filePath: string): string {
+  return filePath.split(path.sep).join('/');
+}
+
+export function nodePathStripExtension(filePath: string): string {
+  const extension = path.extname(filePath);
+  return filePath.slice(0, -extension.length);
+}

package/src/Helper/Object.ts

@@ -0,0 +1,124 @@
+export function objectMergeDeep<T extends Record<string, any>, U extends Record<string, any>>(
+  target: T = {} as T,
+  source: U = {} as U
+): T & U {
+  const output: Record<string, any> = { ...target };
+
+  Object.entries(source || {}).forEach(([key, value]) => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      output[key] = objectMergeDeep(
+        typeof output[key] === 'object' && output[key] !== null ? output[key] : {},
+        value as Record<string, any>
+      );
+    } else {
+      output[key] = value;
+    }
+  });
+
+  return output as T & U;
+}
+
+export function objectToType(value: unknown): string {
+  return {}.toString.call(value).match(/([a-z]+)(:?\])/i)?.[1] ?? typeof value;
+}
+
+export function objectIsPlainObject(value: unknown): value is Record<PropertyKey, unknown> {
+  return objectToType(value) === 'Object';
+}
+
+export function objectDeepAssignWithOptions(options: {
+  nonEnum?: boolean;
+  symbols?: boolean;
+  descriptors?: boolean;
+  proto?: boolean;
+}) {
+  const mergedOptions = {
+    nonEnum: true,
+    symbols: true,
+    descriptors: true,
+    proto: true,
+    ...options,
+  };
+
+  return (target: any, ...sources: any[]) => {
+    sources.forEach((source) => {
+      if (!objectIsPlainObject(source) || !objectIsPlainObject(target)) return;
+
+      const copyProperty = (property: string | symbol) => {
+        const descriptor = Object.getOwnPropertyDescriptor(source, property);
+        if (!descriptor) return;
+
+        if (descriptor.enumerable || mergedOptions.nonEnum) {
+          if (objectIsPlainObject(source[property]) && objectIsPlainObject(target[property])) {
+            descriptor.value = objectDeepAssignWithOptions(mergedOptions)(
+              target[property],
+              source[property]
+            );
+          }
+
+          if (mergedOptions.descriptors) {
+            Object.defineProperty(target, property, descriptor);
+          } else {
+            target[property] = descriptor.value;
+          }
+        }
+      };
+
+      Object.getOwnPropertyNames(source).forEach(copyProperty);
+
+      if (mergedOptions.symbols) {
+        Object.getOwnPropertySymbols(source).forEach(copyProperty);
+      }
+
+      if (mergedOptions.proto) {
+        const targetProto = Object.getPrototypeOf(target);
+        const sourceProto = Object.getPrototypeOf(source);
+        if (targetProto && sourceProto) {
+          objectDeepAssignWithOptions({ ...mergedOptions, proto: false })(targetProto, sourceProto);
+        }
+      }
+    });
+    return target;
+  };
+}
+
+export function objectDeepAssign(...args: any[]): any {
+  return objectDeepAssignWithOptions({
+    nonEnum: true,
+    symbols: true,
+    descriptors: true,
+    proto: true,
+  }).apply(undefined, args as [any, ...any[]]);
+}
+
+export function objectCallPrototypeMethodIfExists<T extends object, R>(
+  self: T,
+  methodName: string,
+  args: unknown[] = []
+): R | undefined {
+  const method = Object.getPrototypeOf(self)?.[methodName];
+  if (typeof method === 'function') {
+    return method.apply(self, args);
+  }
+  return undefined;
+}
+
+export function objectGetItemByPath(
+  data: any,
+  key: string | string[],
+  defaultValue: any = null,
+  separator = '.'
+): any {
+  const keys = Array.isArray(key) ? key : key.split(separator);
+  let cursor: any = data;
+
+  for (const k of keys) {
+    if (cursor !== null && typeof cursor === 'object' && k in cursor) {
+      cursor = cursor[k];
+    } else {
+      return defaultValue;
+    }
+  }
+
+  return cursor;
+}

package/src/Helper/Pointer.ts

@@ -0,0 +1,3 @@
+export const POINTER = {
+  CLICK_DURATION: 500,
+} as const;

package/src/Helper/Queue.ts

@@ -0,0 +1,112 @@
+export type QueueWorker<TItem, TResult = unknown> = (item: TItem) => Promise<TResult> | TResult;
+
+export type QueueCallbacks<TItem, TResult = unknown> = {
+  onItemStart?: (item: TItem) => void;
+  onItemSuccess?: (item: TItem, result: TResult) => void;
+  onItemError?: (item: TItem, error: unknown) => void;
+  onItemDone?: (item: TItem) => void;
+  onDrain?: () => void;
+};
+
+export type QueueOptions<TItem, TResult = unknown> = QueueCallbacks<TItem, TResult> & {
+  worker: QueueWorker<TItem, TResult>;
+  concurrency?: number;
+  autoStart?: boolean;
+};
+
+export default class Queue<TItem, TResult = unknown> {
+  private queue: TItem[] = [];
+  private activeCount = 0;
+  private paused = false;
+  private readonly worker: QueueWorker<TItem, TResult>;
+  private readonly concurrency: number;
+  private readonly autoStart: boolean;
+  private readonly callbacks: QueueCallbacks<TItem, TResult>;
+
+  constructor(options: QueueOptions<TItem, TResult>) {
+    this.worker = options.worker;
+    this.concurrency = Math.max(1, options.concurrency ?? 1);
+    this.autoStart = options.autoStart ?? true;
+    this.callbacks = {
+      onItemStart: options.onItemStart,
+      onItemSuccess: options.onItemSuccess,
+      onItemError: options.onItemError,
+      onItemDone: options.onItemDone,
+      onDrain: options.onDrain,
+    };
+  }
+
+  enqueue(item: TItem): void {
+    this.queue.push(item);
+    if (this.autoStart) {
+      this.pump();
+    }
+  }
+
+  enqueueMany(items: TItem[]): void {
+    this.queue.push(...items);
+    if (this.autoStart) {
+      this.pump();
+    }
+  }
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    if (!this.paused) {
+      return;
+    }
+
+    this.paused = false;
+    this.pump();
+  }
+
+  clear(): void {
+    this.queue = [];
+  }
+
+  size(): number {
+    return this.queue.length;
+  }
+
+  active(): number {
+    return this.activeCount;
+  }
+
+  isIdle(): boolean {
+    return this.queue.length === 0 && this.activeCount === 0;
+  }
+
+  private pump(): void {
+    if (this.paused) {
+      return;
+    }
+
+    while (this.activeCount < this.concurrency && this.queue.length > 0) {
+      const item = this.queue.shift() as TItem;
+      this.runItem(item);
+    }
+
+    if (this.isIdle()) {
+      this.callbacks.onDrain?.();
+    }
+  }
+
+  private async runItem(item: TItem): Promise<void> {
+    this.activeCount += 1;
+    this.callbacks.onItemStart?.(item);
+
+    try {
+      const result = await this.worker(item);
+      this.callbacks.onItemSuccess?.(item, result);
+    } catch (error) {
+      this.callbacks.onItemError?.(item, error);
+    } finally {
+      this.callbacks.onItemDone?.(item);
+      this.activeCount -= 1;
+      this.pump();
+    }
+  }
+}

package/src/Helper/Reconnect.ts

@@ -0,0 +1,170 @@
+import { timeSleep } from './Time';
+
+export type ReconnectBackoffOptions = {
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  factor?: number;
+  jitterRatio?: number;
+  maxAttempts?: number;
+  random?: () => number;
+};
+
+export type ReconnectBackoffResolvedOptions = {
+  initialDelayMs: number;
+  maxDelayMs: number;
+  factor: number;
+  jitterRatio: number;
+  maxAttempts: number;
+  random: () => number;
+};
+
+export type ReconnectAttemptContext = {
+  attempt: number;
+  delayMs: number;
+  error: unknown;
+};
+
+export type ReconnectAttemptCallbacks = {
+  onRetry?: (context: ReconnectAttemptContext) => void | Promise<void>;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+
+const DEFAULT_RECONNECT_BACKOFF_OPTIONS: ReconnectBackoffResolvedOptions = {
+  initialDelayMs: 1000,
+  maxDelayMs: 30000,
+  factor: 2,
+  jitterRatio: 0.2,
+  maxAttempts: Number.POSITIVE_INFINITY,
+  random: Math.random,
+};
+
+export function reconnectBackoffResolveOptions(
+  options: ReconnectBackoffOptions = {}
+): ReconnectBackoffResolvedOptions {
+  const resolved: ReconnectBackoffResolvedOptions = {
+    ...DEFAULT_RECONNECT_BACKOFF_OPTIONS,
+    ...options,
+  };
+
+  if (resolved.initialDelayMs < 0) {
+    throw new Error('initialDelayMs must be >= 0.');
+  }
+
+  if (resolved.maxDelayMs < 0) {
+    throw new Error('maxDelayMs must be >= 0.');
+  }
+
+  if (resolved.factor < 1) {
+    throw new Error('factor must be >= 1.');
+  }
+
+  if (resolved.jitterRatio < 0 || resolved.jitterRatio > 1) {
+    throw new Error('jitterRatio must be between 0 and 1.');
+  }
+
+  if (resolved.maxAttempts < 1 && Number.isFinite(resolved.maxAttempts)) {
+    throw new Error('maxAttempts must be >= 1.');
+  }
+
+  return resolved;
+}
+
+export function reconnectBackoffBaseDelay(
+  attempt: number,
+  options: ReconnectBackoffOptions = {}
+): number {
+  const resolved = reconnectBackoffResolveOptions(options);
+  const safeAttempt = Math.max(1, attempt);
+  const baseDelay = resolved.initialDelayMs * resolved.factor ** (safeAttempt - 1);
+
+  return Math.min(resolved.maxDelayMs, baseDelay);
+}
+
+export function reconnectBackoffApplyJitter(
+  delayMs: number,
+  options: ReconnectBackoffOptions = {}
+): number {
+  const resolved = reconnectBackoffResolveOptions(options);
+  if (delayMs <= 0 || resolved.jitterRatio === 0) {
+    return Math.max(0, delayMs);
+  }
+
+  const amplitude = delayMs * resolved.jitterRatio;
+  const offset = (resolved.random() * 2 - 1) * amplitude;
+  const jitteredDelay = delayMs + offset;
+
+  return Math.max(0, Math.min(resolved.maxDelayMs, jitteredDelay));
+}
+
+export function reconnectBackoffDelay(
+  attempt: number,
+  options: ReconnectBackoffOptions = {}
+): number {
+  const baseDelay = reconnectBackoffBaseDelay(attempt, options);
+  return reconnectBackoffApplyJitter(baseDelay, options);
+}
+
+export type ReconnectBackoffController = {
+  getAttempt: () => number;
+  nextDelay: () => number;
+  canRetry: () => boolean;
+  reset: () => void;
+};
+
+export function reconnectBackoffCreateController(
+  options: ReconnectBackoffOptions = {}
+): ReconnectBackoffController {
+  const resolved = reconnectBackoffResolveOptions(options);
+  let attempt = 0;
+
+  return {
+    getAttempt: () => attempt,
+
+    canRetry: () => {
+      if (!Number.isFinite(resolved.maxAttempts)) {
+        return true;
+      }
+
+      return attempt < resolved.maxAttempts;
+    },
+
+    nextDelay: () => {
+      attempt += 1;
+      return reconnectBackoffDelay(attempt, resolved);
+    },
+
+    reset: () => {
+      attempt = 0;
+    },
+  };
+}
+
+export async function reconnectBackoffAttempt<T>(
+  operation: () => Promise<T> | T,
+  options: ReconnectBackoffOptions = {},
+  callbacks: ReconnectAttemptCallbacks = {}
+): Promise<T> {
+  const controller = reconnectBackoffCreateController(options);
+
+  while (true) {
+    try {
+      const result = await operation();
+      controller.reset();
+      return result;
+    } catch (error) {
+      const nextAttempt = controller.getAttempt() + 1;
+      const shouldRetry = callbacks.shouldRetry?.(error, nextAttempt) ?? true;
+      if (!shouldRetry || !controller.canRetry()) {
+        throw error;
+      }
+
+      const delayMs = controller.nextDelay();
+      await callbacks.onRetry?.({
+        attempt: controller.getAttempt(),
+        delayMs,
+        error,
+      });
+      await timeSleep(delayMs);
+    }
+  }
+}