a2bei4-utils 1.0.0

package/types/index.d.ts

@@ -0,0 +1,499 @@
+/**
+ * 基于 `setTimeout` 的“间隔循环”定时器。
+ * 每次任务执行完成后才计算下一次间隔，避免任务堆积。
+ */
+declare class IntervalTimer {
+    /**
+     * 创建定时器实例。
+     * @param {() => void} fn - 每次间隔要执行的业务函数
+     * @param {number} [ms=1000] - 间隔时间（毫秒）
+     * @throws {TypeError} 当 `fn` 不是函数时抛出
+     */
+    constructor(fn: () => void, ms?: number);
+    _fn: () => void;
+    _ms: number;
+    _timerId: number | null;
+    /**
+     * 启动定时器；若已启动则先停止再重新启动。
+     * 首次执行会立即触发。
+     */
+    start(): void;
+    /**
+     * 停止定时器。
+     */
+    stop(): void;
+    /**
+     * 查询定时器是否正在运行。
+     * @returns {boolean}
+     */
+    isRunning(): boolean;
+}
+
+/**
+ * 使用 Fisher-Yates 算法对数组 **原地** 随机乱序。
+ * @template T
+ * @param {T[]} arr - 要乱序的数组
+ * @returns {T[]} 返回传入的同一数组实例（已乱序）
+ */
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ * 将数组中的元素从 `fromIndex` 移动到 `toIndex`，**原地** 修改并返回该数组。
+ * @template T
+ * @param {T[]} arr - 要操作的数组
+ * @param {number} fromIndex - 原始下标
+ * @param {number} toIndex - 目标下标
+ * @returns {T[]} 返回传入的同一数组实例
+ */
+declare function moveItem<T>(arr: T[], fromIndex: number, toIndex: number): T[];
+
+/**
+ * 视口尺寸对象。
+ * @typedef {Object} ViewportDimensions
+ * @property {number} w 视口宽度，单位像素。
+ * @property {number} h 视口高度，单位像素。
+ */
+/**
+ * 获取当前视口（viewport）的宽高。
+ *
+ * 兼容策略：
+ * 1. 优先使用 `window.innerWidth/innerHeight`（现代浏览器）。
+ * 2. 降级到 `document.documentElement.clientWidth/clientHeight`（IE9+ 及怪异模式）。
+ * 3. 最后降级到 `document.body.clientWidth/clientHeight`（IE6-8 怪异模式）。
+ *
+ * @returns {ViewportDimensions} 包含 `w`（宽度）和 `h`（高度）的对象，单位为像素。
+ *
+ * @example
+ * const { w, h } = getViewportSize();
+ * console.log(`视口尺寸：${w} × ${h}`);
+ */
+declare function getViewportSize(): ViewportDimensions;
+/**
+ * 将当前页面 URL 的 query 部分解析成键值对对象。
+ *
+ * @returns {Record<string, string>} 所有查询参数组成的平凡对象
+ *                                   （同名 key 仅保留最后一项）
+ */
+declare function getAllSearchParams(): Record<string, string>;
+/**
+ * 根据 key 获取当前页面 URL 中的单个查询参数。
+ *
+ * @param {string} key - 要提取的参数名
+ * @returns {string | undefined} 对应参数值；不存在时返回 `undefined`
+ */
+declare function getSearchParam(key: string): string | undefined;
+/**
+ * 视口尺寸对象。
+ */
+type ViewportDimensions = {
+    /**
+     * 视口宽度，单位像素。
+     */
+    w: number;
+    /**
+     * 视口高度，单位像素。
+     */
+    h: number;
+};
+
+/**
+ * 返回任意值的运行时类型字符串（小写形式）。
+ *
+ * @param {*} obj 待检测的值
+ * @returns {keyof globalThis|"blob"|"file"|"formdata"|string} 小写类型名
+ */
+declare function getDataType(obj: any): ("undefined" | "globalThis" | "eval" | "parseInt" | "parseFloat" | "isNaN" | "isFinite" | "decodeURI" | "decodeURIComponent" | "encodeURI" | "encodeURIComponent" | "escape" | "unescape" | "NaN" | "Infinity" | "Symbol" | "Object" | "Function" | "String" | "Boolean" | "Number" | "Math" | "Date" | "RegExp" | "Error" | "EvalError" | "RangeError" | "ReferenceError" | "SyntaxError" | "TypeError" | "URIError" | "JSON" | "Array" | "Promise" | "ArrayBuffer" | "DataView" | "Int8Array" | "Uint8Array" | "Uint8ClampedArray" | "Int16Array" | "Uint16Array" | "Int32Array" | "Uint32Array" | "Float32Array" | "Float64Array" | "Intl" | "alert" | "blur" | "cancelIdleCallback" | "captureEvents" | "close" | "confirm" | "focus" | "getComputedStyle" | "getSelection" | "matchMedia" | "moveBy" | "moveTo" | "open" | "postMessage" | "print" | "prompt" | "releaseEvents" | "requestIdleCallback" | "resizeBy" | "resizeTo" | "scroll" | "scrollBy" | "scrollTo" | "stop" | "toString" | "dispatchEvent" | "cancelAnimationFrame" | "requestAnimationFrame" | "atob" | "btoa" | "clearInterval" | "clearTimeout" | "createImageBitmap" | "fetch" | "queueMicrotask" | "reportError" | "setInterval" | "setTimeout" | "structuredClone" | "addEventListener" | "removeEventListener" | "NodeFilter" | "AbortController" | "AbortSignal" | "AbstractRange" | "AnalyserNode" | "Animation" | "AnimationEffect" | "AnimationEvent" | "AnimationPlaybackEvent" | "AnimationTimeline" | "Attr" | "AudioBuffer" | "AudioBufferSourceNode" | "AudioContext" | "AudioData" | "AudioDecoder" | "AudioDestinationNode" | "AudioEncoder" | "AudioListener" | "AudioNode" | "AudioParam" | "AudioParamMap" | "AudioProcessingEvent" | "AudioScheduledSourceNode" | "AudioWorklet" | "AudioWorkletNode" | "AuthenticatorAssertionResponse" | "AuthenticatorAttestationResponse" | "AuthenticatorResponse" | "BarProp" | "BaseAudioContext" | "BeforeUnloadEvent" | "BiquadFilterNode" | "Blob" | "BlobEvent" | "BroadcastChannel" | "ByteLengthQueuingStrategy" | "CDATASection" | "CSPViolationReportBody" | "CSSAnimation" | "CSSConditionRule" | "CSSContainerRule" | "CSSCounterStyleRule" | "CSSFontFaceRule" | "CSSFontFeatureValuesRule" | "CSSFontPaletteValuesRule" | "CSSGroupingRule" | "CSSImageValue" | "CSSImportRule" | "CSSKeyframeRule" | "CSSKeyframesRule" | "CSSKeywordValue" | "CSSLayerBlockRule" | "CSSLayerStatementRule" | "CSSMathClamp" | "CSSMathInvert" | "CSSMathMax" | "CSSMathMin" | "CSSMathNegate" | "CSSMathProduct" | "CSSMathSum" | "CSSMathValue" | "CSSMatrixComponent" | "CSSMediaRule" | "CSSNamespaceRule" | "CSSNestedDeclarations" | "CSSNumericArray" | "CSSNumericValue" | "CSSPageRule" | "CSSPerspective" | "CSSPropertyRule" | "CSSRotate" | "CSSRule" | "CSSRuleList" | "CSSScale" | "CSSScopeRule" | "CSSSkew" | "CSSSkewX" | "CSSSkewY" | "CSSStartingStyleRule" | "CSSStyleDeclaration" | "CSSStyleRule" | "CSSStyleSheet" | "CSSStyleValue" | "CSSSupportsRule" | "CSSTransformComponent" | "CSSTransformValue" | "CSSTransition" | "CSSTranslate" | "CSSUnitValue" | "CSSUnparsedValue" | "CSSVariableReferenceValue" | "CSSViewTransitionRule" | "Cache" | "CacheStorage" | "CanvasCaptureMediaStreamTrack" | "CanvasGradient" | "CanvasPattern" | "CanvasRenderingContext2D" | "CaretPosition" | "ChannelMergerNode" | "ChannelSplitterNode" | "CharacterData" | "Clipboard" | "ClipboardEvent" | "ClipboardItem" | "CloseEvent" | "Comment" | "CompositionEvent" | "CompressionStream" | "ConstantSourceNode" | "ContentVisibilityAutoStateChangeEvent" | "ConvolverNode" | "CookieChangeEvent" | "CookieStore" | "CookieStoreManager" | "CountQueuingStrategy" | "Credential" | "CredentialsContainer" | "Crypto" | "CryptoKey" | "CustomElementRegistry" | "CustomEvent" | "CustomStateSet" | "DOMException" | "DOMImplementation" | "DOMMatrix" | "SVGMatrix" | "WebKitCSSMatrix" | "DOMMatrixReadOnly" | "DOMParser" | "DOMPoint" | "SVGPoint" | "DOMPointReadOnly" | "DOMQuad" | "DOMRect" | "SVGRect" | "DOMRectList" | "DOMRectReadOnly" | "DOMStringList" | "DOMStringMap" | "DOMTokenList" | "DataTransfer" | "DataTransferItem" | "DataTransferItemList" | "DecompressionStream" | "DelayNode" | "DeviceMotionEvent" | "DeviceOrientationEvent" | "Document" | "DocumentFragment" | "DocumentTimeline" | "DocumentType" | "DragEvent" | "DynamicsCompressorNode" | "Element" | "ElementInternals" | "EncodedAudioChunk" | "EncodedVideoChunk" | "ErrorEvent" | "Event" | "EventCounts" | "EventSource" | "EventTarget" | "External" | "File" | "FileList" | "FileReader" | "FileSystem" | "FileSystemDirectoryEntry" | "FileSystemDirectoryHandle" | "FileSystemDirectoryReader" | "FileSystemEntry" | "FileSystemFileEntry" | "FileSystemFileHandle" | "FileSystemHandle" | "FileSystemWritableFileStream" | "FocusEvent" | "FontFace" | "FontFaceSet" | "FontFaceSetLoadEvent" | "FormData" | "FormDataEvent" | "FragmentDirective" | "GainNode" | "Gamepad" | "GamepadButton" | "GamepadEvent" | "GamepadHapticActuator" | "Geolocation" | "GeolocationCoordinates" | "GeolocationPosition" | "GeolocationPositionError" | "HTMLAllCollection" | "HTMLAnchorElement" | "HTMLAreaElement" | "HTMLAudioElement" | "HTMLBRElement" | "HTMLBaseElement" | "HTMLBodyElement" | "HTMLButtonElement" | "HTMLCanvasElement" | "HTMLCollection" | "HTMLDListElement" | "HTMLDataElement" | "HTMLDataListElement" | "HTMLDetailsElement" | "HTMLDialogElement" | "HTMLDirectoryElement" | "HTMLDivElement" | "HTMLDocument" | "HTMLElement" | "HTMLEmbedElement" | "HTMLFieldSetElement" | "HTMLFontElement" | "HTMLFormControlsCollection" | "HTMLFormElement" | "HTMLFrameElement" | "HTMLFrameSetElement" | "HTMLHRElement" | "HTMLHeadElement" | "HTMLHeadingElement" | "HTMLHtmlElement" | "HTMLIFrameElement" | "HTMLImageElement" | "HTMLInputElement" | "HTMLLIElement" | "HTMLLabelElement" | "HTMLLegendElement" | "HTMLLinkElement" | "HTMLMapElement" | "HTMLMarqueeElement" | "HTMLMediaElement" | "HTMLMenuElement" | "HTMLMetaElement" | "HTMLMeterElement" | "HTMLModElement" | "HTMLOListElement" | "HTMLObjectElement" | "HTMLOptGroupElement" | "HTMLOptionElement" | "HTMLOptionsCollection" | "HTMLOutputElement" | "HTMLParagraphElement" | "HTMLParamElement" | "HTMLPictureElement" | "HTMLPreElement" | "HTMLProgressElement" | "HTMLQuoteElement" | "HTMLScriptElement" | "HTMLSelectElement" | "HTMLSlotElement" | "HTMLSourceElement" | "HTMLSpanElement" | "HTMLStyleElement" | "HTMLTableCaptionElement" | "HTMLTableCellElement" | "HTMLTableColElement" | "HTMLTableElement" | "HTMLTableRowElement" | "HTMLTableSectionElement" | "HTMLTemplateElement" | "HTMLTextAreaElement" | "HTMLTimeElement" | "HTMLTitleElement" | "HTMLTrackElement" | "HTMLUListElement" | "HTMLUnknownElement" | "HTMLVideoElement" | "HashChangeEvent" | "Headers" | "Highlight" | "HighlightRegistry" | "History" | "IDBCursor" | "IDBCursorWithValue" | "IDBDatabase" | "IDBFactory" | "IDBIndex" | "IDBKeyRange" | "IDBObjectStore" | "IDBOpenDBRequest" | "IDBRequest" | "IDBTransaction" | "IDBVersionChangeEvent" | "IIRFilterNode" | "IdleDeadline" | "ImageBitmap" | "ImageBitmapRenderingContext" | "ImageCapture" | "ImageData" | "ImageDecoder" | "ImageTrack" | "ImageTrackList" | "InputDeviceInfo" | "InputEvent" | "IntersectionObserver" | "IntersectionObserverEntry" | "KeyboardEvent" | "KeyframeEffect" | "LargestContentfulPaint" | "Location" | "Lock" | "LockManager" | "MIDIAccess" | "MIDIConnectionEvent" | "MIDIInput" | "MIDIInputMap" | "MIDIMessageEvent" | "MIDIOutput" | "MIDIOutputMap" | "MIDIPort" | "MathMLElement" | "MediaCapabilities" | "MediaDeviceInfo" | "MediaDevices" | "MediaElementAudioSourceNode" | "MediaEncryptedEvent" | "MediaError" | "MediaKeyMessageEvent" | "MediaKeySession" | "MediaKeyStatusMap" | "MediaKeySystemAccess" | "MediaKeys" | "MediaList" | "MediaMetadata" | "MediaQueryList" | "MediaQueryListEvent" | "MediaRecorder" | "MediaSession" | "MediaSource" | "MediaSourceHandle" | "MediaStream" | "MediaStreamAudioDestinationNode" | "MediaStreamAudioSourceNode" | "MediaStreamTrack" | "MediaStreamTrackEvent" | "MessageChannel" | "MessageEvent" | "MessagePort" | "MimeType" | "MimeTypeArray" | "MouseEvent" | "MutationObserver" | "MutationRecord" | "NamedNodeMap" | "NavigationActivation" | "NavigationHistoryEntry" | "NavigationPreloadManager" | "Navigator" | "NavigatorLogin" | "Node" | "NodeIterator" | "NodeList" | "Notification" | "OfflineAudioCompletionEvent" | "OfflineAudioContext" | "OffscreenCanvas" | "OffscreenCanvasRenderingContext2D" | "OscillatorNode" | "OverconstrainedError" | "PageRevealEvent" | "PageSwapEvent" | "PageTransitionEvent" | "PannerNode" | "Path2D" | "PaymentAddress" | "PaymentMethodChangeEvent" | "PaymentRequest" | "PaymentRequestUpdateEvent" | "PaymentResponse" | "Performance" | "PerformanceEntry" | "PerformanceEventTiming" | "PerformanceMark" | "PerformanceMeasure" | "PerformanceNavigation" | "PerformanceNavigationTiming" | "PerformanceObserver" | "PerformanceObserverEntryList" | "PerformancePaintTiming" | "PerformanceResourceTiming" | "PerformanceServerTiming" | "PerformanceTiming" | "PeriodicWave" | "PermissionStatus" | "Permissions" | "PictureInPictureEvent" | "PictureInPictureWindow" | "Plugin" | "PluginArray" | "PointerEvent" | "PopStateEvent" | "ProcessingInstruction" | "ProgressEvent" | "PromiseRejectionEvent" | "PublicKeyCredential" | "PushManager" | "PushSubscription" | "PushSubscriptionOptions" | "RTCCertificate" | "RTCDTMFSender" | "RTCDTMFToneChangeEvent" | "RTCDataChannel" | "RTCDataChannelEvent" | "RTCDtlsTransport" | "RTCEncodedAudioFrame" | "RTCEncodedVideoFrame" | "RTCError" | "RTCErrorEvent" | "RTCIceCandidate" | "RTCIceTransport" | "RTCPeerConnection" | "RTCPeerConnectionIceErrorEvent" | "RTCPeerConnectionIceEvent" | "RTCRtpReceiver" | "RTCRtpScriptTransform" | "RTCRtpSender" | "RTCRtpTransceiver" | "RTCSctpTransport" | "RTCSessionDescription" | "RTCStatsReport" | "RTCTrackEvent" | "RadioNodeList" | "Range" | "ReadableByteStreamController" | "ReadableStream" | "ReadableStreamBYOBReader" | "ReadableStreamBYOBRequest" | "ReadableStreamDefaultController" | "ReadableStreamDefaultReader" | "RemotePlayback" | "Report" | "ReportBody" | "ReportingObserver" | "Request" | "ResizeObserver" | "ResizeObserverEntry" | "ResizeObserverSize" | "Response" | "SVGAElement" | "SVGAngle" | "SVGAnimateElement" | "SVGAnimateMotionElement" | "SVGAnimateTransformElement" | "SVGAnimatedAngle" | "SVGAnimatedBoolean" | "SVGAnimatedEnumeration" | "SVGAnimatedInteger" | "SVGAnimatedLength" | "SVGAnimatedLengthList" | "SVGAnimatedNumber" | "SVGAnimatedNumberList" | "SVGAnimatedPreserveAspectRatio" | "SVGAnimatedRect" | "SVGAnimatedString" | "SVGAnimatedTransformList" | "SVGAnimationElement" | "SVGCircleElement" | "SVGClipPathElement" | "SVGComponentTransferFunctionElement" | "SVGDefsElement" | "SVGDescElement" | "SVGElement" | "SVGEllipseElement" | "SVGFEBlendElement" | "SVGFEColorMatrixElement" | "SVGFEComponentTransferElement" | "SVGFECompositeElement" | "SVGFEConvolveMatrixElement" | "SVGFEDiffuseLightingElement" | "SVGFEDisplacementMapElement" | "SVGFEDistantLightElement" | "SVGFEDropShadowElement" | "SVGFEFloodElement" | "SVGFEFuncAElement" | "SVGFEFuncBElement" | "SVGFEFuncGElement" | "SVGFEFuncRElement" | "SVGFEGaussianBlurElement" | "SVGFEImageElement" | "SVGFEMergeElement" | "SVGFEMergeNodeElement" | "SVGFEMorphologyElement" | "SVGFEOffsetElement" | "SVGFEPointLightElement" | "SVGFESpecularLightingElement" | "SVGFESpotLightElement" | "SVGFETileElement" | "SVGFETurbulenceElement" | "SVGFilterElement" | "SVGForeignObjectElement" | "SVGGElement" | "SVGGeometryElement" | "SVGGradientElement" | "SVGGraphicsElement" | "SVGImageElement" | "SVGLength" | "SVGLengthList" | "SVGLineElement" | "SVGLinearGradientElement" | "SVGMPathElement" | "SVGMarkerElement" | "SVGMaskElement" | "SVGMetadataElement" | "SVGNumber" | "SVGNumberList" | "SVGPathElement" | "SVGPatternElement" | "SVGPointList" | "SVGPolygonElement" | "SVGPolylineElement" | "SVGPreserveAspectRatio" | "SVGRadialGradientElement" | "SVGRectElement" | "SVGSVGElement" | "SVGScriptElement" | "SVGSetElement" | "SVGStopElement" | "SVGStringList" | "SVGStyleElement" | "SVGSwitchElement" | "SVGSymbolElement" | "SVGTSpanElement" | "SVGTextContentElement" | "SVGTextElement" | "SVGTextPathElement" | "SVGTextPositioningElement" | "SVGTitleElement" | "SVGTransform" | "SVGTransformList" | "SVGUnitTypes" | "SVGUseElement" | "SVGViewElement" | "Screen" | "ScreenOrientation" | "ScriptProcessorNode" | "SecurityPolicyViolationEvent" | "Selection" | "ServiceWorker" | "ServiceWorkerContainer" | "ServiceWorkerRegistration" | "ShadowRoot" | "SharedWorker" | "SourceBuffer" | "SourceBufferList" | "SpeechRecognitionAlternative" | "SpeechRecognitionResult" | "SpeechRecognitionResultList" | "SpeechSynthesis" | "SpeechSynthesisErrorEvent" | "SpeechSynthesisEvent" | "SpeechSynthesisUtterance" | "SpeechSynthesisVoice" | "StaticRange" | "StereoPannerNode" | "Storage" | "StorageEvent" | "StorageManager" | "StylePropertyMap" | "StylePropertyMapReadOnly" | "StyleSheet" | "StyleSheetList" | "SubmitEvent" | "SubtleCrypto" | "Text" | "TextDecoder" | "TextDecoderStream" | "TextEncoder" | "TextEncoderStream" | "TextEvent" | "TextMetrics" | "TextTrack" | "TextTrackCue" | "TextTrackCueList" | "TextTrackList" | "TimeRanges" | "ToggleEvent" | "Touch" | "TouchEvent" | "TouchList" | "TrackEvent" | "TransformStream" | "TransformStreamDefaultController" | "TransitionEvent" | "TreeWalker" | "UIEvent" | "URL" | "webkitURL" | "URLSearchParams" | "UserActivation" | "VTTCue" | "VTTRegion" | "ValidityState" | "VideoColorSpace" | "VideoDecoder" | "VideoEncoder" | "VideoFrame" | "VideoPlaybackQuality" | "ViewTransition" | "ViewTransitionTypeSet" | "VisualViewport" | "WakeLock" | "WakeLockSentinel" | "WaveShaperNode" | "WebGL2RenderingContext" | "WebGLActiveInfo" | "WebGLBuffer" | "WebGLContextEvent" | "WebGLFramebuffer" | "WebGLProgram" | "WebGLQuery" | "WebGLRenderbuffer" | "WebGLRenderingContext" | "WebGLSampler" | "WebGLShader" | "WebGLShaderPrecisionFormat" | "WebGLSync" | "WebGLTexture" | "WebGLTransformFeedback" | "WebGLUniformLocation" | "WebGLVertexArrayObject" | "WebSocket" | "WebTransport" | "WebTransportBidirectionalStream" | "WebTransportDatagramDuplexStream" | "WebTransportError" | "WheelEvent" | "Window" | "Worker" | "Worklet" | "WritableStream" | "WritableStreamDefaultController" | "WritableStreamDefaultWriter" | "XMLDocument" | "XMLHttpRequest" | "XMLHttpRequestEventTarget" | "XMLHttpRequestUpload" | "XMLSerializer" | "XPathEvaluator" | "XPathExpression" | "XPathResult" | "XSLTProcessor" | "CSS" | "WebAssembly" | "console" | "Audio" | "Image" | "Option" | "clientInformation" | "closed" | "cookieStore" | "customElements" | "devicePixelRatio" | "document" | "event" | "external" | "frameElement" | "frames" | "history" | "innerHeight" | "innerWidth" | "length" | "location" | "locationbar" | "menubar" | "navigator" | "ondevicemotion" | "ondeviceorientation" | "ondeviceorientationabsolute" | "onorientationchange" | "opener" | "orientation" | "originAgentCluster" | "outerHeight" | "outerWidth" | "pageXOffset" | "pageYOffset" | "parent" | "personalbar" | "screen" | "screenLeft" | "screenTop" | "screenX" | "screenY" | "scrollX" | "scrollY" | "scrollbars" | "self" | "speechSynthesis" | "status" | "statusbar" | "toolbar" | "top" | "visualViewport" | "window" | "onabort" | "onanimationcancel" | "onanimationend" | "onanimationiteration" | "onanimationstart" | "onauxclick" | "onbeforeinput" | "onbeforematch" | "onbeforetoggle" | "onblur" | "oncancel" | "oncanplay" | "oncanplaythrough" | "onchange" | "onclick" | "onclose" | "oncontextlost" | "oncontextmenu" | "oncontextrestored" | "oncopy" | "oncuechange" | "oncut" | "ondblclick" | "ondrag" | "ondragend" | "ondragenter" | "ondragleave" | "ondragover" | "ondragstart" | "ondrop" | "ondurationchange" | "onemptied" | "onended" | "onerror" | "onfocus" | "onformdata" | "ongotpointercapture" | "oninput" | "oninvalid" | "onkeydown" | "onkeypress" | "onkeyup" | "onload" | "onloadeddata" | "onloadedmetadata" | "onloadstart" | "onlostpointercapture" | "onmousedown" | "onmouseenter" | "onmouseleave" | "onmousemove" | "onmouseout" | "onmouseover" | "onmouseup" | "onpaste" | "onpause" | "onplay" | "onplaying" | "onpointercancel" | "onpointerdown" | "onpointerenter" | "onpointerleave" | "onpointermove" | "onpointerout" | "onpointerover" | "onpointerrawupdate" | "onpointerup" | "onprogress" | "onratechange" | "onreset" | "onresize" | "onscroll" | "onscrollend" | "onsecuritypolicyviolation" | "onseeked" | "onseeking" | "onselect" | "onselectionchange" | "onselectstart" | "onslotchange" | "onstalled" | "onsubmit" | "onsuspend" | "ontimeupdate" | "ontoggle" | "ontouchcancel" | "ontouchend" | "ontouchmove" | "ontouchstart" | "ontransitioncancel" | "ontransitionend" | "ontransitionrun" | "ontransitionstart" | "onvolumechange" | "onwaiting" | "onwebkitanimationend" | "onwebkitanimationiteration" | "onwebkitanimationstart" | "onwebkittransitionend" | "onwheel" | "onafterprint" | "onbeforeprint" | "onbeforeunload" | "ongamepadconnected" | "ongamepaddisconnected" | "onhashchange" | "onlanguagechange" | "onmessage" | "onmessageerror" | "onoffline" | "ononline" | "onpagehide" | "onpagereveal" | "onpageshow" | "onpageswap" | "onpopstate" | "onrejectionhandled" | "onstorage" | "onunhandledrejection" | "onunload" | "localStorage" | "caches" | "crossOriginIsolated" | "crypto" | "indexedDB" | "isSecureContext" | "origin" | "performance" | "sessionStorage" | "importScripts" | "ActiveXObject" | "WScript" | "WSH" | "Enumerator" | "VBArray" | "Map" | "WeakMap" | "Set" | "WeakSet" | "Iterator" | "Proxy" | "Reflect" | "SharedArrayBuffer" | "Atomics" | "BigInt" | "BigInt64Array" | "BigUint64Array" | "AggregateError" | "WeakRef" | "FinalizationRegistry" | "SuppressedError" | "DisposableStack" | "AsyncDisposableStack" | "Float16Array") | "blob" | "file" | "formdata" | string;
+/**
+ * 判断值是否为原生 Blob（含 File）。
+ *
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Blob}
+ */
+declare function isBlob(obj: any): obj is Blob;
+/**
+ * 判断值是否为**纯粹**的 Object（即 `{}` 或 `new Object()`，不含数组、null、自定义类等）。
+ *
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Record<PropertyKey, any>}
+ */
+declare function isPlainObject(obj: any): obj is Record<PropertyKey, any>;
+/**
+ * 判断值是否为 Promise（含 Promise 子类）。
+ *
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Promise<any>}
+ */
+declare function isPromise(obj: any): obj is Promise<any>;
+/**
+ * 判断值是否为合法 Date 对象（含 Invalid Date 返回 false）。
+ *
+ * @param {*} t - 待检测值
+ * @returns {t is Date}
+ */
+declare function isDate(t: any): t is Date;
+/**
+ * 判断值是否为函数（含异步函数、生成器函数、类）。
+ *
+ * @param {*} obj - 待检测的值
+ * @returns {obj is Function}
+ */
+declare function isFunction(obj: any): obj is Function;
+/**
+ * 判断值是否为**非空**字符串。
+ *
+ * @param {*} obj - 待检测的值
+ * @returns {obj is string}
+ */
+declare function isNonEmptyString(obj: any): obj is string;
+/**
+ * 在闭区间 [min, max] 内生成一个均匀分布的随机整数。
+ * 若 min > max 则自动交换。
+ *
+ * @param {number} min - 整数下界（包含）
+ * @param {number} max - 整数上界（包含）
+ * @returns {number}
+ * @throws {TypeError} 当 min 或 max 不是整数时抛出
+ */
+declare function randomIntInRange(min: number, max: number): number;
+/**
+ * 随机生成一个汉字（可控制范围）。
+ *
+ * @param {boolean} [base=true]  - 是否启用基本区（0x4E00-0x9FA5）
+ * @param {boolean} [extA=false] - 是否启用扩展 A 区（0x3400-0x4DBF）
+ * @param {boolean} [extBH=false] - 是否启用扩展 B~H 区（0x20000-0x2EBEF，代理对）
+ * @returns {string} 单个汉字字符
+ * @throws {RangeError} 未启用任何区段时抛出
+ */
+declare function randomHan(base?: boolean, extA?: boolean, extBH?: boolean): string;
+/**
+ * 随机生成一个英文字母。
+ *
+ * @param {'lower'|'upper'} [type] - 指定大小写；留空则随机
+ * @returns {string} 单个字母
+ */
+declare function randomEnLetter(type?: "lower" | "upper"): string;
+/**
+ * 生成指定长度的随机“中英混合”字符串。
+ *
+ * @param {number} [len=1] - 目标长度（≥1，自动取整）
+ * @param {number} [zhProb=0.5] - 每个位置选择汉字的概率，默认 0.5
+ * @returns {string}
+ */
+declare function randomHanOrEn(len?: number, zhProb?: number): string;
+/**
+ * 创建 debounced（防抖）函数。
+ * - 默认 trailing 触发；当 `leading=true` 时，首次调用或超过等待间隔会立即执行。
+ * - 支持手动取消。
+ *
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn - 要防抖的原始函数
+ * @param {number} wait - 防抖等待时间（毫秒）
+ * @param {boolean} [leading=false] - 是否启用立即执行（leading edge）
+ * @returns {T & { cancel(): void }} 返回经过防抖包装的函数，并附带 `cancel` 方法
+ * @throws {TypeError} 当 `fn` 不是函数时抛出
+ */
+declare function debounce<T extends (...args: any[]) => any>(fn: T, wait: number, leading?: boolean): T & {
+    cancel(): void;
+};
+/**
+ * 创建 throttled（节流）函数。
+ * 支持 leading/trailing 边缘触发，可手动取消。
+ *
+ * @template {(...args: any[]) => any} T
+ * @param {T} fn - 要节流的原始函数
+ * @param {number} wait - 节流间隔（毫秒）
+ * @param {object} [options] - 配置项
+ * @param {boolean} [options.leading=true] - 是否在 leading 边缘执行
+ * @param {boolean} [options.trailing=true] - 是否在 trailing 边缘执行
+ * @returns {T & { cancel(): void }} 返回经过节流包装的函数，并附带 `cancel` 方法
+ * @throws {TypeError} 当 `fn` 不是函数时抛出
+ */
+declare function throttle<T extends (...args: any[]) => any>(fn: T, wait: number, { leading, trailing }?: {
+    leading?: boolean | undefined;
+    trailing?: boolean | undefined;
+}): T & {
+    cancel(): void;
+};
+/**
+ * 利用 JSON 序列化/反序列化实现**深拷贝**。
+ * 注意：会丢失 `undefined`、函数、循环引用、特殊包装对象等。
+ *
+ * @template T
+ * @param {T} obj - 待拷贝的 JSON 兼容值
+ * @returns {T} 深拷贝后的值
+ */
+declare function deepCloneByJSON<T>(obj: T): T;
+/**
+ * **安全**地将源对象中**已存在**的属性赋值到目标对象。
+ * 不会新增键，也不会复制原型链上的属性。
+ *
+ * @template {Record<PropertyKey, any>} T
+ * @param {T} target - 目标对象（将被就地修改）
+ * @param {...Partial<T>} sources - 一个或多个源对象
+ * @returns {T} 修改后的目标对象（即第一个参数本身）
+ *
+ * @example
+ * const defaults = { a: 1, b: 2 };
+ * assignExisting(defaults, { a: 9, c: 99 }); // defaults 变为 { a: 9, b: 2 }
+ */
+declare function assignExisting<T extends Record<PropertyKey, any>>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * 提取任意函数（含箭头函数、普通函数、async、class 构造器）的形参名称列表。
+ * 通过源码正则解析，不支持解构参数、默认参数、剩余参数等复杂语法；
+ * 若出现上述场景将返回空数组或部分名称。
+ *
+ * @param {Function} fn - 目标函数
+ * @returns {string[]} 按声明顺序排列的参数名数组；解析失败时返回空数组
+ *
+ * @example
+ * getFunctionArgNames(function (a, b) {})        // ["a", "b"]
+ * getFunctionArgNames((foo, bar) => {})          // ["foo", "bar"]
+ * getFunctionArgNames(async function x({a} = {}) {}) // [] （解构无法识别）
+ */
+declare function getFunctionArgNames(fn: Function): string[];
+/**
+ * 将 Blob（或 File）读取为文本，并可选择自动执行 `JSON.parse`。
+ * 当 `isParse=true` 且内容非法 JSON 时，会回退为返回原始文本。
+ *
+ * @param {Blob} blob - 待读取的 Blob/File 对象
+ * @param {boolean} [isParse=true] - 是否尝试将结果按 JSON 解析
+ * @returns {Promise<string | any>} 解析后的 JSON 对象或原始文本
+ *
+ * @example
+ * const json = await readBlobAsText(blob);        // 自动 JSON.parse
+ * const text = await readBlobAsText(blob, false); // 仅返回文本
+ */
+declare function readBlobAsText(blob: Blob, isParse?: boolean): Promise<string | any>;
+
+/**
+ * 将任意值安全转换为 Date 对象。
+ * - 数字／数字字符串：视为时间戳
+ * - 字符串：尝试按 ISO/RFC 格式解析
+ * - 对象：优先 valueOf()，再 toString()
+ * - null / undefined / 无效值：返回 null
+ *
+ * @param {*} val - 待转换值
+ * @returns {Date | null} 有效 Date 或 null
+ */
+declare function toDate(val: any): Date | null;
+/**
+ * 在闭区间 [date1, date2] 内随机生成一个日期（含首尾）。
+ * 若顺序相反则自动交换。
+ *
+ * @param {Date} date1 - 起始日期
+ * @param {Date} date2 - 结束日期
+ * @returns {Date} 随机日期
+ */
+declare function randomDateInRange(date1: Date, date2: Date): Date;
+/**
+ * 计算两个时间之间的剩余/已过时长（天-时-分-秒），返回带补零的展示对象。
+ *
+ * @param {string|number|Date} originalTime - 原始时间（可转 Date 的任意值）
+ * @param {Date} [currentTime=new Date()] - 基准时间，默认当前
+ * @returns {{days:number,hours:string,minutes:string,seconds:string}}
+ */
+declare function calcTimeDifference(originalTime: string | number | Date, currentTime?: Date): {
+    days: number;
+    hours: string;
+    minutes: string;
+    seconds: string;
+};
+/**
+ * 将总秒数格式化成人类可读的时间段文本。
+ * 固定进制：1 年=365 天，1 月=30 天。
+ *
+ * @param {number} totalSeconds - 非负总秒数
+ * @param {object} [options] - 格式化选项
+ * @param {Partial<{year:string,month:string,day:string,hour:string,minute:string,second:string}>} [options.labels] - 各单位的自定义文本
+ * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.maxUnit] - 最大输出单位
+ * @param {('year'|'month'|'day'|'hour'|'minute'|'second')} [options.minUnit] - 最小输出单位
+ * @param {boolean} [options.showZero] - 是否强制显示 0 秒
+ * @returns {string} 拼接后的时长文本，如“1天 02小时 30分钟”
+ * @throws {TypeError} 当 totalSeconds 为非数字或负数时抛出
+ */
+declare function formatDuration(totalSeconds: number, options?: {
+    labels?: Partial<{
+        year: string;
+        month: string;
+        day: string;
+        hour: string;
+        minute: string;
+        second: string;
+    }> | undefined;
+    maxUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
+    minUnit?: "year" | "month" | "day" | "hour" | "minute" | "second" | undefined;
+    showZero?: boolean | undefined;
+}): string;
+/**
+ * 快捷调用 {@link formatDuration}，最大单位到“天”。
+ *
+ * @param {number} totalSeconds
+ * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
+ * @returns {string}
+ */
+declare function formatDurationMaxDay(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+/**
+ * 快捷调用 {@link formatDuration}，最大单位到“小时”。
+ *
+ * @param {number} totalSeconds
+ * @param {Omit<Parameters<typeof formatDuration>[1],'maxUnit'>} [options]
+ * @returns {string}
+ */
+declare function formatDurationMaxHour(totalSeconds: number, options?: Omit<Parameters<typeof formatDuration>[1], "maxUnit">): string;
+
+/**
+ * 通过动态创建 `<a>` 标签触发浏览器下载。
+ *
+ * @param {string} url - 任意可下载地址（同源或允许跨域）
+ * @param {string} [fileName] - 保存到本地的文件名；不传时使用时间戳
+ */
+declare function downloadByUrl(url: string, fileName?: string): void;
+/**
+ * 把 Blob 转成临时 URL 并触发下载，下载完成后立即释放内存。
+ *
+ * @param {Blob} blob - 待下载的 Blob（含 File）
+ * @param {string} [fileName] - 保存到本地的文件名
+ */
+declare function downloadByBlob(blob: Blob, fileName?: string): void;
+/**
+ * 将任意数据包装成 Blob 并下载。
+ *
+ * @param {string | ArrayBufferView | ArrayBuffer | Blob} data - 要写入文件的数据
+ * @param {string} [fileName] - 保存到本地的文件名
+ * @param {string} [mimeType] - MIME 类型；默认 `application/octet-stream`
+ */
+declare function downloadByData(data: string | ArrayBufferView | ArrayBuffer | Blob, fileName?: string, mimeType?: string): void;
+/**
+ * 快捷下载 Excel 文件（MIME 已固定）。
+ *
+ * @param {string | ArrayBufferView | ArrayBuffer | Blob} data - Excel 二进制或字符串内容
+ * @param {string} [fileName] - 保存到本地的文件名
+ */
+declare function downloadExcel(data: string | ArrayBufferView | ArrayBuffer | Blob, fileName?: string): void;
+/**
+ * 快捷下载 JSON 文件（MIME 已固定）。
+ * 若传入非字符串数据，会自行 `JSON.stringify`。
+ *
+ * @param {any} data - 要序列化的 JSON 数据
+ * @param {string} [fileName] - 保存到本地的文件名
+ */
+declare function downloadJSON(data: any, fileName?: string): void;
+
+/**
+ * 简单、高性能的通用事件总线。
+ * - 支持命名空间事件
+ * - 支持一次性监听器
+ * - 返回唯一 flag，用于精确卸载
+ * - emit 时可选自定义 this 指向
+ */
+declare class MyEvent {
+    evtPool: Map<any, any>;
+    /**
+     * 注册事件监听器。
+     * @param {string} name - 事件名
+     * @param {Function} fn - 回调函数
+     * @returns {string} flag - 唯一标识，用于 off
+     */
+    on(name: string, fn: Function): string;
+    /**
+     * 注册一次性监听器，触发后自动移除。
+     * @param {string} name - 事件名
+     * @param {Function} fn - 回调函数
+     * @returns {string} flag - 唯一标识
+     */
+    once(name: string, fn: Function): string;
+    /**
+     * 移除指定事件监听器。
+     * @param {string} name - 事件名
+     * @param {Function|string} fnOrFlag - 回调函数或 flag
+     */
+    off(name: string, fnOrFlag: Function | string): void;
+    /**
+     * 触发事件（同步执行）。
+     * @param {string} name - 事件名
+     * @param {*} [data] - 任意载荷
+     * @param {*} [fnThis] - 回调内部 this 指向，默认 undefined
+     */
+    emit(name: string, data?: any, fnThis?: any): void;
+}
+declare namespace MyEvent_CrossPagePlugin {
+    /**
+     * 为指定 MyEvent 实例安装跨页插件。
+     * @param {MyEvent} bus - 事件总线实例
+     * @param {Options} [opts] - 配置项
+     */
+    function install(bus: MyEvent, opts?: Options): void;
+    /**
+     * 卸载插件，恢复原始 emit 并停止监听。
+     * @param {MyEvent} bus - 事件总线实例
+     */
+    function uninstall(bus: MyEvent): void;
+}
+
+/**
+ * 生成 RFC4122 版本 4 的 GUID/UUID。
+ * 收集来源：《基于mvc的javascript web富应用开发》 书中介绍是Robert Kieffer写的，还留了网址 http://goo.gl/0b0hu ，但实际访问不了。
+ * 格式：`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
+ *
+ * @returns {string} 36 位大写 GUID
+ *
+ * @example
+ * // A2E0F340-6C3B-4D7F-B8C1-1E4F6A8B9C0D
+ * console.log(getGUID())
+ */
+declare function getGUID(): string;
+/**
+ * 分布式短 ID 生成器。
+ * 格式：`${timestamp}${flag}${serial}`，其中：
+ * - timestamp：毫秒级时间戳
+ * - flag：客户端标识串（自定义）
+ * - serial：同一毫秒内的序号，左补零到固定长度
+ */
+declare class MyId {
+    /**
+     * @param {object} [option]
+     * @param {string} [option.flag] - 客户端标识，默认空串
+     * @param {number} [option.len=5] - 序号位长度（位数），安全范围 ≥0
+     */
+    constructor(option?: {
+        flag?: string | undefined;
+        len?: number | undefined;
+    });
+    /**
+     * 生成下一个全局唯一字符串 ID。
+     * 同一毫秒序号自动递增；序号溢出时会在控制台警告。
+     * @returns {string}
+     */
+    nextId(): string;
+    #private;
+}
+
+/**
+ * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} data - 嵌套树森林
+ * @param {string} [idKey='id'] - 主键字段
+ * @param {string} [childrenKey='children'] - 子节点字段
+ * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表
+ */
+declare function nestedTree2IdMap<T>(data: T[], idKey?: string, childrenKey?: string): Record<string, T & { [k in typeof childrenKey]: null; }>;
+/**
+ * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）
+ * @param {number | string} [parentId=0] - 根节点标识值
+ * @param {Object} [opts] - 字段映射配置
+ * @param {string} [opts.idKey='id'] - 节点主键
+ * @param {string} [opts.parentKey='parentId'] - 父节点外键
+ * @param {string} [opts.childrenKey='children'] - 存放子节点的字段
+ * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林
+ */
+declare function flatCompleteTree2NestedTree<T>(nodes: T[], parentId?: number | string, { idKey, parentKey, childrenKey }?: {
+    idKey?: string | undefined;
+    parentKey?: string | undefined;
+    childrenKey?: string | undefined;
+}): (T & { [k in typeof childrenKey]: T[]; })[];
+declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
+
+export { IntervalTimer, MyEvent, MyEvent_CrossPagePlugin, MyId, assignExisting, calcTimeDifference, debounce, deepCloneByJSON, downloadByBlob, downloadByData, downloadByUrl, downloadExcel, downloadJSON, findObjAttrValueById, flatCompleteTree2NestedTree, formatDuration, formatDurationMaxDay, formatDurationMaxHour, getAllSearchParams, getDataType, getFunctionArgNames, getGUID, getSearchParam, getViewportSize, isBlob, isDate, isFunction, isNonEmptyString, isPlainObject, isPromise, moveItem, nestedTree2IdMap, randomDateInRange, randomEnLetter, randomHan, randomHanOrEn, randomIntInRange, readBlobAsText, shuffle, throttle, toDate };

package/types/timer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 基于 `setTimeout` 的“间隔循环”定时器。
+ * 每次任务执行完成后才计算下一次间隔，避免任务堆积。
+ */
+declare class IntervalTimer {
+    /**
+     * 创建定时器实例。
+     * @param {() => void} fn - 每次间隔要执行的业务函数
+     * @param {number} [ms=1000] - 间隔时间（毫秒）
+     * @throws {TypeError} 当 `fn` 不是函数时抛出
+     */
+    constructor(fn: () => void, ms?: number);
+    _fn: () => void;
+    _ms: number;
+    _timerId: number | null;
+    /**
+     * 启动定时器；若已启动则先停止再重新启动。
+     * 首次执行会立即触发。
+     */
+    start(): void;
+    /**
+     * 停止定时器。
+     */
+    stop(): void;
+    /**
+     * 查询定时器是否正在运行。
+     * @returns {boolean}
+     */
+    isRunning(): boolean;
+}
+
+export { IntervalTimer };

package/types/tree.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 把嵌套树拍平成 `{ [id]: node }` 映射，同时把原 `children` 置为 `null`。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} data - 嵌套树森林
+ * @param {string} [idKey='id'] - 主键字段
+ * @param {string} [childrenKey='children'] - 子节点字段
+ * @returns {Record<string, T & { [k in typeof childrenKey]: null }>} id→节点的映射表
+ */
+declare function nestedTree2IdMap<T>(data: T[], idKey?: string, childrenKey?: string): Record<string, T & { [k in typeof childrenKey]: null; }>;
+/**
+ * 把**已包含完整父子关系**的扁平节点列表还原成嵌套树（森林）。
+ *
+ * @template T extends Record<PropertyKey, any>
+ * @param {T[]} nodes - 扁平节点列表（必须包含 id / parentId）
+ * @param {number | string} [parentId=0] - 根节点标识值
+ * @param {Object} [opts] - 字段映射配置
+ * @param {string} [opts.idKey='id'] - 节点主键
+ * @param {string} [opts.parentKey='parentId'] - 父节点外键
+ * @param {string} [opts.childrenKey='children'] - 存放子节点的字段
+ * @returns {(T & { [k in typeof childrenKey]: T[] })[]} 嵌套树森林
+ */
+declare function flatCompleteTree2NestedTree<T>(nodes: T[], parentId?: number | string, { idKey, parentKey, childrenKey }?: {
+    idKey?: string | undefined;
+    parentKey?: string | undefined;
+    childrenKey?: string | undefined;
+}): (T & { [k in typeof childrenKey]: T[]; })[];
+declare function findObjAttrValueById<T>(id: string | number, arr: T[], resultKey?: string, idKey?: string, childrenKey?: string): any;
+
+export { findObjAttrValueById, flatCompleteTree2NestedTree, nestedTree2IdMap };