@TechUI/Utils Introduction

TechUI Utils (Utility Library) is the underlying lubricant of the TechUI ecosystem.

Unlike comprehensive general-purpose libraries such as Lodash or Underscore, @techui/utils is deeply customized to meet the internal requirements of TechUI components for high performance, lightweight footprint, and specific business logic. It encapsulates a series of atomic capabilities ranging from DOM operations to local storage and type detection.

One-sentence summary: A lightweight, pure, and tailor-made underlying toolkit for TechUI.

Positioning and Usage

⚠️ Please note: This is an "internal-first" utility library.

While this library is fully open-source and included in the NPM package, its primary design purpose is to support the operation of upper-level component libraries such as @techui/prime and @techui/admin. Therefore:

1. Internal-Specific Logic: Some modules (such as specific initialization methods for i18n and style) are deeply bound to the TechUI architecture. It is not recommended for developers to call these directly in business code to avoid breaking changes during framework upgrades.
2. Developer Convenience Tools: Other modules (such as tTimer for timer management, tType for data processing, and tStore for storage encapsulation) possess high versatility. We strongly recommend that developers use them in their projects to improve efficiency.

💡 Suggestion: When reading the subsequent module documentation, please choose what to use based on your actual needs.

Core Modules Overview

To maintain code organization, we have divided the utility library into the following seven functional modules:

• 🛠 Common: Includes device environment sniffing (deviceInfo), full-screen control, and miscellaneous general logic that cannot be categorized elsewhere.
• ⚡️ Monitor: A powerful event management system. It includes encapsulations for DOM dimensions (ResizeObserver) and node changes (MutationObserver), as well as high-performance event debounce and throttle tools.
• 💾 Store: Provides a unified encapsulation for LocalStorage, SessionStorage, Cookies, and IndexedDB, supporting automatic serialization and namespace management.
• 🏗 DOM Operations (DOM): DOM query and size calculation tools optimized for TechUI's adaptive system, solving coordinate conversion challenges in scaling scenarios.
• 🛡 Type and Data: Provides more accurate type detection than native typeof, along with deep processing for arrays, objects, numbers, and strings (such as deep cloning and merging).
• 🎨 Style: Provides CSS variable generation, dynamic style injection, and safe DOM class name manipulation methods.
• 🌍 Multi-language (i18n): Handles the underlying logic for system language detection, locking, and resource loading.

Design Philosophy

You might ask: "Why not directly use mature community libraries like Lodash or VueUse?"

Extreme Size Control

TechUI's core components (such as Base/Prime) are extremely sensitive to package size. Introducing a complete third-party general library (often 20KB+) is too heavy for scenarios requiring only a few functions. @techui/utils maintains a minimal footprint.

Business Logic Binding

We need to handle logic specific to TechUI that general libraries cannot provide. Examples include:

• Storage Prefixes: Preventing Key conflicts in micro-frontend environments.
• Adaptive Coordinates: Obtaining correct DOM coordinates within containers using transform: scale.
• Theme Registration Validation: Verifying that user-registered theme objects comply with the Schema.

Installation

Typically, @techui/utils is automatically installed as a dependency of Admin or Prime. If you need to reuse these capabilities in other independent projects:

npm install @techui/utils

On-Demand Import

We recommend importing specific modules on demand:

// ✅ Recommended: Import only the modules you need
import { tTimer, tType } from "@techui/utils";

// Using timer tools
await tTimer.w(1000); // Wait for 1 second

// Using type tools
if (tType(data) === 'array') {
  // ...
}