@t007/utils 0.0.13 → 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,
@@ -41,9 +44,14 @@ __export(index_exports, {
   isSameURL: () => isSameURL,
   isStr: () => isStr,
   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);
@@ -147,6 +155,49 @@ function isSameURL(src1, src2) {
   }
 }
 
+// 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, skipNestedOwn = true, nested = false) {
   let proto = owner;
@@ -284,8 +335,11 @@ if (isDef(window)) {
   VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
+  bindCleanupToSignal,
+  breath,
   clamp,
   createEl,
+  deepBreath,
   guardAllMethods,
   guardMethod,
   inBoolArrOpt,
@@ -302,8 +356,13 @@ if (isDef(window)) {
   isSameURL,
   isStr,
   isSym,
+  limited,
   loadResource,
+  mockAsync,
   onAllMethods,
   removeScrollAssist,
+  requestAnimationFrame,
+  setInterval,
+  setTimeout,
   uid
 });

package/dist/index.d.cts

@@ -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;
@@ -93,4 +113,4 @@ 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, isPOJO, isSameURL, isStr, 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

@@ -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;
@@ -93,4 +113,4 @@ 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, isPOJO, isSameURL, isStr, 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

@@ -97,6 +97,49 @@ function isSameURL(src1, src2) {
   }
 }
 
+// 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, skipNestedOwn = true, nested = false) {
   let proto = owner;
@@ -233,8 +276,11 @@ export {
   VIRTUAL_RESOURCE,
   assignEl,
   bindAllMethods,
+  bindCleanupToSignal,
+  breath,
   clamp,
   createEl,
+  deepBreath,
   guardAllMethods,
   guardMethod,
   inBoolArrOpt,
@@ -251,8 +297,13 @@ export {
   isSameURL,
   isStr,
   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.13",
+  "version": "0.0.14",
   "description": "High-performance, zero-dependency utility functions for the t007 ecosystem.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",