@t007/utils 0.0.12 → 0.0.14

package/dist/index.cjs

@@ -23,8 +23,11 @@ __export(index_exports, {
   VIRTUAL_RESOURCE: () => VIRTUAL_RESOURCE,
   assignEl: () => assignEl,
   bindAllMethods: () => bindAllMethods,
+  bindCleanupToSignal: () => bindCleanupToSignal,
+  breath: () => breath,
   clamp: () => clamp,
   createEl: () => createEl,
+  deepBreath: () => deepBreath,
   guardAllMethods: () => guardAllMethods,
   guardMethod: () => guardMethod,
   inBoolArrOpt: () => inBoolArrOpt,
@@ -37,13 +40,18 @@ __export(index_exports, {
   isIter: () => isIter,
   isNum: () => isNum,
   isObj: () => isObj,
+  isPOJO: () => isPOJO,
   isSameURL: () => isSameURL,
   isStr: () => isStr,
-  isStrictObj: () => isStrictObj,
   isSym: () => isSym,
+  limited: () => limited,
   loadResource: () => loadResource,
+  mockAsync: () => mockAsync,
   onAllMethods: () => onAllMethods,
   removeScrollAssist: () => removeScrollAssist,
+  requestAnimationFrame: () => requestAnimationFrame2,
+  setInterval: () => setInterval,
+  setTimeout: () => setTimeout2,
   uid: () => uid
 });
 module.exports = __toCommonJS(index_exports);
@@ -70,7 +78,7 @@ function isArr(obj) {
 function isObj(obj, arraycheck = true) {
   return "object" === typeof obj && obj !== null && (arraycheck ? !Array.isArray(obj) : true);
 }
-function isStrictObj(obj, crossRealms = false, typecheck = true) {
+function isPOJO(obj, crossRealms = false, typecheck = true) {
   return (typecheck ? isObj(obj, false) : true) && (crossRealms ? Object.prototype.toString.call(obj) === "[object Object]" : obj.constructor === Object);
 }
 function isIter(obj) {
@@ -83,20 +91,6 @@ function inBoolArrOpt(opt, str) {
   return opt?.includes?.(str) ?? opt;
 }
 
-// src/core/str.ts
-function uid(prefix = "") {
-  return prefix + Date.now().toString(36) + "_" + performance.now().toString(36).replace(".", "") + "_" + Math.random().toString(36).slice(2);
-}
-function isSameURL(src1, src2) {
-  if (!isStr(src1) || !isStr(src2) || !src1 || !src2) return false;
-  try {
-    const u1 = new URL(src1, window.location.href), u2 = new URL(src2, window.location.href);
-    return decodeURIComponent(u1.origin + u1.pathname) === decodeURIComponent(u2.origin + u2.pathname);
-  } catch {
-    return src1.replace(/\\/g, "/").split("?")[0].trim() === src2.replace(/\\/g, "/").split("?")[0].trim();
-  }
-}
-
 // src/core/dom.ts
 function createEl(tag, props, dataset, styles, el = tag ? document?.createElement(tag) : null) {
   return assignEl(el, props, dataset, styles), el;
@@ -147,15 +141,73 @@ function clamp(min = 0, val, max = Infinity) {
   return Math.min(Math.max(val, min), max);
 }
 
+// src/core/str.ts
+function uid(prefix = "") {
+  return prefix + Date.now().toString(36) + "_" + performance.now().toString(36).replace(".", "") + "_" + Math.random().toString(36).slice(2);
+}
+function isSameURL(src1, src2) {
+  if (!isStr(src1) || !isStr(src2) || !src1 || !src2) return false;
+  try {
+    const u1 = new URL(src1, window.location.href), u2 = new URL(src2, window.location.href);
+    return decodeURIComponent(u1.origin + u1.pathname) === decodeURIComponent(u2.origin + u2.pathname);
+  } catch {
+    return src1.replace(/\\/g, "/").split("?")[0].trim() === src2.replace(/\\/g, "/").split("?")[0].trim();
+  }
+}
+
+// src/core/fn.ts
+function setTimeout2(handler, timeout, ...args) {
+  const sig = args[0] instanceof AbortSignal ? args.shift() : void 0;
+  if (sig?.aborted) return -1;
+  const w = args[0] instanceof Window ? args.shift() : window;
+  if (!sig) return w.setTimeout(handler, timeout, ...args);
+  const id = w.setTimeout(() => (sig.removeEventListener("abort", kill), isStr(handler) ? new Function(handler) : handler(...args)), timeout), kill = () => w.clearTimeout(id);
+  return sig.addEventListener("abort", kill, { once: true }), id;
+}
+function setInterval(handler, timeout, ...args) {
+  const sig = args[0] instanceof AbortSignal ? args.shift() : void 0;
+  if (sig?.aborted) return -1;
+  const w = args[0] instanceof Window ? args.shift() : window, id = w.setInterval(handler, timeout, ...args);
+  return sig?.addEventListener("abort", () => w.clearInterval(id), { once: true }), id;
+}
+function requestAnimationFrame2(callback, sig, w = window) {
+  if (sig?.aborted) return -1;
+  if (!sig) return w.requestAnimationFrame(callback);
+  const id = w.requestAnimationFrame((t) => (sig.removeEventListener("abort", kill), callback(t))), kill = () => w.cancelAnimationFrame(id);
+  return sig.addEventListener("abort", kill, { once: true }), id;
+}
+function limited(FN_KEY, fn, opts = {}) {
+  let count = 0, { key, maxTimes: max = 1 } = isStr(opts) ? { key: opts } : opts;
+  const getReg = () => JSON.parse(localStorage.getItem(FN_KEY) || "{}"), setReg = (r) => localStorage.setItem(FN_KEY, JSON.stringify(r));
+  const handle = (...args) => {
+    if (!key) return count++ < max ? fn(...args) : void 0;
+    const r = getReg(), c = r[key] || 0;
+    return c < max ? (r[key] = c + 1, setReg(r), fn(...args)) : void 0;
+  };
+  handle.left = max - (handle.count = count);
+  handle.reset = () => (count = 0, key && ((r) => (delete r[key], setReg(r)))(getReg()));
+  handle.block = () => (count = max, key && ((r) => (r[key] = max, setReg(r)))(getReg()));
+  return handle;
+}
+var mockAsync = (timeout = 250) => new Promise((resolve) => setTimeout2(resolve, timeout));
+var breath = (w = window) => new Promise((res) => w.requestAnimationFrame(res));
+var deepBreath = (w = window) => new Promise((res) => w.requestAnimationFrame(() => w.requestAnimationFrame(res)));
+function bindCleanupToSignal(cleanup, signal) {
+  signal?.aborted ? cleanup() : signal?.addEventListener("abort", cleanup, { once: true });
+  if (signal && !signal.aborted) cleanup = (() => (signal.removeEventListener("abort", cleanup), cleanup()));
+  return cleanup;
+}
+
 // src/mixins/methodist.ts
-function onAllMethods(owner, callback) {
+function onAllMethods(owner, callback, skipNestedOwn = true, nested = false) {
   let proto = owner;
   while (proto && proto !== Object.prototype) {
     for (const method of Object.getOwnPropertyNames(proto)) {
       if (method === "constructor") continue;
+      if (nested && skipNestedOwn && Object.prototype.hasOwnProperty.call(owner, method)) continue;
       if (isFunc(Object.getOwnPropertyDescriptor(proto, method)?.value)) callback(method, owner);
     }
-    proto = Object.getPrototypeOf(proto);
+    proto = Object.getPrototypeOf(proto), nested = true;
   }
 }
 function bindAllMethods(owner) {
@@ -283,8 +335,11 @@ if (isDef(window)) {
   VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
+  bindCleanupToSignal,
+  breath,
   clamp,
   createEl,
+  deepBreath,
   guardAllMethods,
   guardMethod,
   inBoolArrOpt,
@@ -297,12 +352,17 @@ if (isDef(window)) {
   isIter,
   isNum,
   isObj,
+  isPOJO,
   isSameURL,
   isStr,
-  isStrictObj,
   isSym,
+  limited,
   loadResource,
+  mockAsync,
   onAllMethods,
   removeScrollAssist,
+  requestAnimationFrame,
+  setInterval,
+  setTimeout,
   uid
 });

package/dist/index.d.cts

@@ -57,7 +57,7 @@ declare function isNum<T extends number = number>(val: any): val is T;
 declare function isStr<T extends string = string>(val: any): val is T;
 declare function isArr<T = unknown>(obj: any): obj is T[];
 declare function isObj<T extends object = object>(obj: any, arraycheck?: boolean): obj is T;
-declare function isStrictObj<T extends object = object>(obj: any, crossRealms?: boolean, typecheck?: boolean): obj is T;
+declare function isPOJO<T extends object = object>(obj: any, crossRealms?: boolean, typecheck?: boolean): obj is T;
 declare function isIter<T = unknown>(obj: any): obj is Iterable<T>;
 declare function isFunc<T extends Function = Function>(val: any): val is T;
 declare function inBoolArrOpt(opt: any, str: string): boolean;
@@ -67,6 +67,26 @@ declare function clamp(min: number | undefined, val: number, max?: number): numb
 declare function uid(prefix?: string): string;
 declare function isSameURL(src1: unknown, src2: unknown): boolean;
 
+declare function setTimeout(handler: TimerHandler, timeout?: number, ...args: any[]): number;
+declare function setInterval(handler: TimerHandler, timeout?: number, ...args: any[]): number;
+declare function requestAnimationFrame(callback: FrameRequestCallback, sig?: AbortSignal, w?: Window & typeof globalThis): number;
+interface LimitedOptions {
+    key?: string /** Key for localStorage persistence (if omitted, uses session-only) */;
+    maxTimes?: number /** Max times to call (default: 1) */;
+}
+interface LimitedHandle<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): ReturnType<T> | void;
+    count: number;
+    left: number;
+    reset: () => void;
+    block: () => void;
+}
+declare function limited<T extends (...args: any[]) => any>(FN_KEY: string, fn: T, opts?: LimitedOptions | string): LimitedHandle<T>;
+declare const mockAsync: (timeout?: number) => Promise<void>;
+declare const breath: (w?: Window & typeof globalThis) => Promise<unknown>;
+declare const deepBreath: (w?: Window & typeof globalThis) => Promise<unknown>;
+declare function bindCleanupToSignal<Cb extends () => any>(cleanup: Cb, signal?: AbortSignal): Cb;
+
 type Dataset = Record<string, string | number>;
 type Style = Partial<CSSStyleDeclaration>;
 type ResourceType = "style" | "script" | string;
@@ -88,9 +108,9 @@ declare function assignEl(el?: HTMLElement | null, props?: Partial<HTMLElement>,
 declare const VIRTUAL_RESOURCE: unique symbol;
 declare function loadResource(req: string | symbol, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, w?: Window & typeof globalThis): Promise<HTMLElement | void>;
 
-declare function onAllMethods(owner: any, callback: (method: string, owner: any) => void): void;
+declare function onAllMethods(owner: any, callback: (method: string, owner: any) => void, skipNestedOwn?: boolean, nested?: boolean): void;
 declare function bindAllMethods(owner: any): void;
 declare function guardAllMethods(owner: any, guardFn?: (fn: Function) => Function, bound?: boolean): void;
 declare function guardMethod<T extends Function>(fn: T, onError?: (e: any) => void): T;
 
-export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, VIRTUAL_RESOURCE, assignEl, bindAllMethods, clamp, createEl, guardAllMethods, guardMethod, inBoolArrOpt, initScrollAssist, initVScrollerator, isArr, isBool, isDef, isFunc, isIter, isNum, isObj, isSameURL, isStr, isStrictObj, isSym, loadResource, onAllMethods, removeScrollAssist, uid };
+export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, VIRTUAL_RESOURCE, assignEl, bindAllMethods, bindCleanupToSignal, breath, clamp, createEl, deepBreath, guardAllMethods, guardMethod, inBoolArrOpt, initScrollAssist, initVScrollerator, isArr, isBool, isDef, isFunc, isIter, isNum, isObj, isPOJO, isSameURL, isStr, isSym, limited, loadResource, mockAsync, onAllMethods, removeScrollAssist, requestAnimationFrame, setInterval, setTimeout, uid };

package/dist/index.d.ts

@@ -57,7 +57,7 @@ declare function isNum<T extends number = number>(val: any): val is T;
 declare function isStr<T extends string = string>(val: any): val is T;
 declare function isArr<T = unknown>(obj: any): obj is T[];
 declare function isObj<T extends object = object>(obj: any, arraycheck?: boolean): obj is T;
-declare function isStrictObj<T extends object = object>(obj: any, crossRealms?: boolean, typecheck?: boolean): obj is T;
+declare function isPOJO<T extends object = object>(obj: any, crossRealms?: boolean, typecheck?: boolean): obj is T;
 declare function isIter<T = unknown>(obj: any): obj is Iterable<T>;
 declare function isFunc<T extends Function = Function>(val: any): val is T;
 declare function inBoolArrOpt(opt: any, str: string): boolean;
@@ -67,6 +67,26 @@ declare function clamp(min: number | undefined, val: number, max?: number): numb
 declare function uid(prefix?: string): string;
 declare function isSameURL(src1: unknown, src2: unknown): boolean;
 
+declare function setTimeout(handler: TimerHandler, timeout?: number, ...args: any[]): number;
+declare function setInterval(handler: TimerHandler, timeout?: number, ...args: any[]): number;
+declare function requestAnimationFrame(callback: FrameRequestCallback, sig?: AbortSignal, w?: Window & typeof globalThis): number;
+interface LimitedOptions {
+    key?: string /** Key for localStorage persistence (if omitted, uses session-only) */;
+    maxTimes?: number /** Max times to call (default: 1) */;
+}
+interface LimitedHandle<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): ReturnType<T> | void;
+    count: number;
+    left: number;
+    reset: () => void;
+    block: () => void;
+}
+declare function limited<T extends (...args: any[]) => any>(FN_KEY: string, fn: T, opts?: LimitedOptions | string): LimitedHandle<T>;
+declare const mockAsync: (timeout?: number) => Promise<void>;
+declare const breath: (w?: Window & typeof globalThis) => Promise<unknown>;
+declare const deepBreath: (w?: Window & typeof globalThis) => Promise<unknown>;
+declare function bindCleanupToSignal<Cb extends () => any>(cleanup: Cb, signal?: AbortSignal): Cb;
+
 type Dataset = Record<string, string | number>;
 type Style = Partial<CSSStyleDeclaration>;
 type ResourceType = "style" | "script" | string;
@@ -88,9 +108,9 @@ declare function assignEl(el?: HTMLElement | null, props?: Partial<HTMLElement>,
 declare const VIRTUAL_RESOURCE: unique symbol;
 declare function loadResource(req: string | symbol, type?: ResourceType, { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts, retryKey }?: LoadResourceOptions, w?: Window & typeof globalThis): Promise<HTMLElement | void>;
 
-declare function onAllMethods(owner: any, callback: (method: string, owner: any) => void): void;
+declare function onAllMethods(owner: any, callback: (method: string, owner: any) => void, skipNestedOwn?: boolean, nested?: boolean): void;
 declare function bindAllMethods(owner: any): void;
 declare function guardAllMethods(owner: any, guardFn?: (fn: Function) => Function, bound?: boolean): void;
 declare function guardMethod<T extends Function>(fn: T, onError?: (e: any) => void): T;
 
-export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, VIRTUAL_RESOURCE, assignEl, bindAllMethods, clamp, createEl, guardAllMethods, guardMethod, inBoolArrOpt, initScrollAssist, initVScrollerator, isArr, isBool, isDef, isFunc, isIter, isNum, isObj, isSameURL, isStr, isStrictObj, isSym, loadResource, onAllMethods, removeScrollAssist, uid };
+export { type Dataset, type LoadResourceOptions, type ResourceType, type ScrollAssistControl, type Style, VIRTUAL_RESOURCE, assignEl, bindAllMethods, bindCleanupToSignal, breath, clamp, createEl, deepBreath, guardAllMethods, guardMethod, inBoolArrOpt, initScrollAssist, initVScrollerator, isArr, isBool, isDef, isFunc, isIter, isNum, isObj, isPOJO, isSameURL, isStr, isSym, limited, loadResource, mockAsync, onAllMethods, removeScrollAssist, requestAnimationFrame, setInterval, setTimeout, uid };

package/dist/index.js

@@ -20,7 +20,7 @@ function isArr(obj) {
 function isObj(obj, arraycheck = true) {
   return "object" === typeof obj && obj !== null && (arraycheck ? !Array.isArray(obj) : true);
 }
-function isStrictObj(obj, crossRealms = false, typecheck = true) {
+function isPOJO(obj, crossRealms = false, typecheck = true) {
   return (typecheck ? isObj(obj, false) : true) && (crossRealms ? Object.prototype.toString.call(obj) === "[object Object]" : obj.constructor === Object);
 }
 function isIter(obj) {
@@ -33,20 +33,6 @@ function inBoolArrOpt(opt, str) {
   return opt?.includes?.(str) ?? opt;
 }
 
-// src/core/str.ts
-function uid(prefix = "") {
-  return prefix + Date.now().toString(36) + "_" + performance.now().toString(36).replace(".", "") + "_" + Math.random().toString(36).slice(2);
-}
-function isSameURL(src1, src2) {
-  if (!isStr(src1) || !isStr(src2) || !src1 || !src2) return false;
-  try {
-    const u1 = new URL(src1, window.location.href), u2 = new URL(src2, window.location.href);
-    return decodeURIComponent(u1.origin + u1.pathname) === decodeURIComponent(u2.origin + u2.pathname);
-  } catch {
-    return src1.replace(/\\/g, "/").split("?")[0].trim() === src2.replace(/\\/g, "/").split("?")[0].trim();
-  }
-}
-
 // src/core/dom.ts
 function createEl(tag, props, dataset, styles, el = tag ? document?.createElement(tag) : null) {
   return assignEl(el, props, dataset, styles), el;
@@ -97,15 +83,73 @@ function clamp(min = 0, val, max = Infinity) {
   return Math.min(Math.max(val, min), max);
 }
 
+// src/core/str.ts
+function uid(prefix = "") {
+  return prefix + Date.now().toString(36) + "_" + performance.now().toString(36).replace(".", "") + "_" + Math.random().toString(36).slice(2);
+}
+function isSameURL(src1, src2) {
+  if (!isStr(src1) || !isStr(src2) || !src1 || !src2) return false;
+  try {
+    const u1 = new URL(src1, window.location.href), u2 = new URL(src2, window.location.href);
+    return decodeURIComponent(u1.origin + u1.pathname) === decodeURIComponent(u2.origin + u2.pathname);
+  } catch {
+    return src1.replace(/\\/g, "/").split("?")[0].trim() === src2.replace(/\\/g, "/").split("?")[0].trim();
+  }
+}
+
+// src/core/fn.ts
+function setTimeout2(handler, timeout, ...args) {
+  const sig = args[0] instanceof AbortSignal ? args.shift() : void 0;
+  if (sig?.aborted) return -1;
+  const w = args[0] instanceof Window ? args.shift() : window;
+  if (!sig) return w.setTimeout(handler, timeout, ...args);
+  const id = w.setTimeout(() => (sig.removeEventListener("abort", kill), isStr(handler) ? new Function(handler) : handler(...args)), timeout), kill = () => w.clearTimeout(id);
+  return sig.addEventListener("abort", kill, { once: true }), id;
+}
+function setInterval(handler, timeout, ...args) {
+  const sig = args[0] instanceof AbortSignal ? args.shift() : void 0;
+  if (sig?.aborted) return -1;
+  const w = args[0] instanceof Window ? args.shift() : window, id = w.setInterval(handler, timeout, ...args);
+  return sig?.addEventListener("abort", () => w.clearInterval(id), { once: true }), id;
+}
+function requestAnimationFrame2(callback, sig, w = window) {
+  if (sig?.aborted) return -1;
+  if (!sig) return w.requestAnimationFrame(callback);
+  const id = w.requestAnimationFrame((t) => (sig.removeEventListener("abort", kill), callback(t))), kill = () => w.cancelAnimationFrame(id);
+  return sig.addEventListener("abort", kill, { once: true }), id;
+}
+function limited(FN_KEY, fn, opts = {}) {
+  let count = 0, { key, maxTimes: max = 1 } = isStr(opts) ? { key: opts } : opts;
+  const getReg = () => JSON.parse(localStorage.getItem(FN_KEY) || "{}"), setReg = (r) => localStorage.setItem(FN_KEY, JSON.stringify(r));
+  const handle = (...args) => {
+    if (!key) return count++ < max ? fn(...args) : void 0;
+    const r = getReg(), c = r[key] || 0;
+    return c < max ? (r[key] = c + 1, setReg(r), fn(...args)) : void 0;
+  };
+  handle.left = max - (handle.count = count);
+  handle.reset = () => (count = 0, key && ((r) => (delete r[key], setReg(r)))(getReg()));
+  handle.block = () => (count = max, key && ((r) => (r[key] = max, setReg(r)))(getReg()));
+  return handle;
+}
+var mockAsync = (timeout = 250) => new Promise((resolve) => setTimeout2(resolve, timeout));
+var breath = (w = window) => new Promise((res) => w.requestAnimationFrame(res));
+var deepBreath = (w = window) => new Promise((res) => w.requestAnimationFrame(() => w.requestAnimationFrame(res)));
+function bindCleanupToSignal(cleanup, signal) {
+  signal?.aborted ? cleanup() : signal?.addEventListener("abort", cleanup, { once: true });
+  if (signal && !signal.aborted) cleanup = (() => (signal.removeEventListener("abort", cleanup), cleanup()));
+  return cleanup;
+}
+
 // src/mixins/methodist.ts
-function onAllMethods(owner, callback) {
+function onAllMethods(owner, callback, skipNestedOwn = true, nested = false) {
   let proto = owner;
   while (proto && proto !== Object.prototype) {
     for (const method of Object.getOwnPropertyNames(proto)) {
       if (method === "constructor") continue;
+      if (nested && skipNestedOwn && Object.prototype.hasOwnProperty.call(owner, method)) continue;
       if (isFunc(Object.getOwnPropertyDescriptor(proto, method)?.value)) callback(method, owner);
     }
-    proto = Object.getPrototypeOf(proto);
+    proto = Object.getPrototypeOf(proto), nested = true;
   }
 }
 function bindAllMethods(owner) {
@@ -232,8 +276,11 @@ export {
   VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
+  bindCleanupToSignal,
+  breath,
   clamp,
   createEl,
+  deepBreath,
   guardAllMethods,
   guardMethod,
   inBoolArrOpt,
@@ -246,12 +293,17 @@ export {
   isIter,
   isNum,
   isObj,
+  isPOJO,
   isSameURL,
   isStr,
-  isStrictObj,
   isSym,
+  limited,
   loadResource,
+  mockAsync,
   onAllMethods,
   removeScrollAssist,
+  requestAnimationFrame2 as requestAnimationFrame,
+  setInterval,
+  setTimeout2 as setTimeout,
   uid
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t007/utils",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "High-performance, zero-dependency utility functions for the t007 ecosystem.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",