@aitianyu.cn/types 0.1.2 → 0.1.3

package/doc/en/README.md

@@ -0,0 +1,372 @@
+# @aitianyu.cn/types — English Documentation
+
+> Common modules (types, functions, classes) for the aitianyu ecosystem.
+> Supports both Node.js and browser environments.
+
+---
+
+## Table of Contents
+
+- [Project Description](#project-description)
+- [Project Structure](#project-structure)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Core Utilities](#core-utilities)
+  - [Object Helpers](#object-helpers)
+  - [Security](#security)
+  - [Type Definitions](#type-definitions)
+- [Build & Test](#build--test)
+
+---
+
+## Project Description
+
+`@aitianyu.cn/types` is the foundational utility package of the aitianyu Node.js ecosystem. It provides:
+
+- **Strongly-typed base types** — interfaces, enums, and generic helpers used across all aitianyu packages.
+- **Core runtime utilities** — structured logging, environment detection, type conversion, and custom exceptions.
+- **Object manipulation helpers** — deep clone, deep compare, string formatting, byte operations, and JSON utilities.
+- **Security utilities** — TOTP (RFC 6238), Base32 encoding, UUID/GUID generation, SHA hashing, RSA encryption, and QR code generation.
+- **Path processing** — cross-platform file/directory path parsing and validation.
+
+The library is published as CommonJS and ships full TypeScript declaration files, so it can be used directly in TypeScript or JavaScript projects.
+
+---
+
+## Project Structure
+
+```
+tianyu-types/
+├── src/                        # TypeScript source files
+│   ├── index.ts                # Main export entry point
+│   ├── coding/                 # Path encoding and error types
+│   │   ├── Error.ts            # Path-related exceptions
+│   │   └── Path.ts             # Path class and PathTargetType enum
+│   ├── core/                   # Core runtime utilities
+│   │   ├── Environment.ts      # Runtime environment detection (node / browser)
+│   │   ├── Errors.ts           # Custom exception classes
+│   │   ├── Language.ts         # Area code / locale helpers
+│   │   ├── Log.ts              # Structured logging and performance tracking
+│   │   ├── TypeConvertion.ts   # Type conversion helpers (e.g. getBoolean)
+│   │   ├── interface/
+│   │   │   ├── ITJSON.ts       # JSON type interface
+│   │   │   └── ITianyuType.ts  # Base aitianyu type interface
+│   │   ├── object/             # Object / data-structure helpers
+│   │   │   ├── ArrayHelper.ts  # Array utilities
+│   │   │   ├── Bytes.ts        # Random byte buffer generation
+│   │   │   ├── Calculater.ts   # Mathematical calculations
+│   │   │   ├── DataView.ts     # Binary DataView utilities
+│   │   │   ├── Integer.ts      # Bitwise / random integer helpers
+│   │   │   ├── Json.ts         # JSON processing utilities
+│   │   │   ├── ObjectHelper.ts # Deep clone, compare, validate
+│   │   │   └── StringHelper.ts # String formatting and stringify
+│   │   └── type/               # Typed wrapper classes
+│   │       ├── TArray.ts
+│   │       ├── TBoolean.ts
+│   │       ├── TJSON.ts
+│   │       ├── TNumber.ts
+│   │       ├── TObject.ts
+│   │       └── TString.ts
+│   ├── security/               # Security and cryptography utilities
+│   │   ├── Base32.ts           # Base32 encode / decode (RFC3548, RFC4648, Crockford)
+│   │   ├── Guid.ts             # UUID v4 generation
+│   │   ├── Hash.ts             # Generic hash operations
+│   │   ├── QRCode.ts           # QR code image generation (base64)
+│   │   ├── RSA.ts              # RSA encryption / decryption
+│   │   ├── SHA.ts              # SHA hash functions
+│   │   └── TOTP.ts             # Time-based One-Time Password (RFC 6238)
+│   └── types/                  # Pure type definitions and interfaces
+│       ├── AreaCode.ts         # International area code enum (200+ locales)
+│       ├── Exception.ts        # Base Exception class
+│       ├── Logs.ts             # LogLevel enum and logging interfaces
+│       ├── Object.ts           # Object diff tracking types
+│       ├── PathBase.ts         # Abstract path base class
+│       ├── Security.ts         # EncryptOption enum and ICipher interface
+│       ├── TMap.ts             # Generic TMap data structure
+│       ├── Types.ts            # Common generic types and interfaces
+│       └── index.ts            # Type barrel export
+├── test/                       # Jest test suites (mirrors src/ structure)
+├── dist/                       # Compiled output (generated, not committed)
+│   ├── lib/                    # CommonJS JavaScript files
+│   └── types/                  # TypeScript declaration files
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+└── eslint.config.ts
+```
+
+---
+
+## Installation
+
+```bash
+npm install @aitianyu.cn/types
+```
+
+Requirements: Node.js ≥ 14 or a modern browser environment.
+
+---
+
+## Usage
+
+### Core Utilities
+
+#### Logging
+
+```typescript
+import { Log, Performance } from "@aitianyu.cn/types";
+
+Log.info("Server started on port 3000");
+Log.warn("Deprecated API called");
+Log.error("Unhandled exception", err);
+Log.debug("Config loaded", config);
+
+// Performance tracking
+const perf = Performance.startPerf("db-query");
+// ... do work ...
+Performance.endPerf(perf);
+```
+
+Available log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `FATAL`, `LOG`
+
+#### Environment Detection
+
+```typescript
+import { Environment } from "@aitianyu.cn/types";
+
+const env = Environment.runtimeEnv(); // "node" | "browser"
+```
+
+#### Type Conversion
+
+```typescript
+import { getBoolean } from "@aitianyu.cn/types";
+
+getBoolean(1);        // true
+getBoolean("false");  // false
+getBoolean(null);     // false
+```
+
+#### Custom Exceptions
+
+```typescript
+import { ArgumentNullOrEmptyException, Exception } from "@aitianyu.cn/types";
+
+throw new ArgumentNullOrEmptyException("userId");
+```
+
+Available exceptions:
+- `ArgumentNullOrEmptyException`
+- `ObjectCloneFunctionNotSupportException`
+- `ObjectMergeStatusCheckFailedException`
+- `ObjectDiffApplyInvalidStatusException`
+- `ObjectDiffMergeFailedException`
+- `PathProcessorSourceLostException`
+- `PathDirectoryValidationFailException`
+
+---
+
+### Object Helpers
+
+#### String Formatting
+
+```typescript
+import { StringHelper } from "@aitianyu.cn/types";
+
+// Positional placeholders (like C# String.Format)
+StringHelper.format("Hello, {0}! You have {1} messages.", "Alice", 5);
+// => "Hello, Alice! You have 5 messages."
+
+// Safe stringify (returns "" on circular reference)
+StringHelper.stringifySafe(someObject);
+```
+
+#### Deep Object Operations
+
+```typescript
+import { ObjectHelper } from "@aitianyu.cn/types";
+
+// Deep clone
+const copy = ObjectHelper.clone(original);
+
+// Deep equality check across multiple objects
+const equal = ObjectHelper.compareObjects(obj1, obj2, obj3);
+
+// Check primitive types
+ObjectHelper.isSimpleDataType(42);      // true
+ObjectHelper.isSimpleDataType({});      // false
+
+// Validate JSON-serialisability
+ObjectHelper.validateSerializable(data);
+```
+
+#### Integer & Byte Utilities
+
+```typescript
+import { Integer, Bytes } from "@aitianyu.cn/types";
+
+const n = Integer.random(0, 100);       // random int in [0, 100]
+const buf = Bytes.random(16);           // 16-byte random Buffer
+
+// Bitwise helpers
+Integer.left(value, bits);
+Integer.right(value, bits);
+Integer.xor(a, b);
+```
+
+#### Array Helpers
+
+```typescript
+import { ArrayHelper } from "@aitianyu.cn/types";
+
+// Utility methods for array manipulation
+```
+
+---
+
+### Security
+
+#### UUID / GUID Generation
+
+```typescript
+import { guid } from "@aitianyu.cn/types";
+
+guid();            // "550e8400-e29b-41d4-a716-446655440000"
+guid("no-dash");   // "550e8400e29b41d4a716446655440000"
+```
+
+#### TOTP (Time-based One-Time Password)
+
+```typescript
+import { TOTP } from "@aitianyu.cn/types";
+
+// Generate a new TOTP secret key
+const secret = TOTP.generate();
+
+// Get a 6-digit code for the current 30-second window
+const code = TOTP.code(secret);
+
+// Build an otpauth:// URI (for use with authenticator apps / QR codes)
+const uri = TOTP.getUrl("MyApp", "user@example.com", secret);
+```
+
+#### Base32 Encoding
+
+```typescript
+import { Base32 } from "@aitianyu.cn/types";
+
+const encoded = Base32.encode(buffer);                   // RFC4648 by default
+const decoded = Base32.decode(encoded);
+const rand    = Base32.random(16);                       // 16-char random Base32 string
+
+// Supported types: "RFC3548" | "RFC4648" | "RFC4648-HEX" | "Crockford"
+Base32.encode(buffer, "Crockford");
+```
+
+#### SHA Hashing
+
+```typescript
+import { SHA } from "@aitianyu.cn/types";
+
+SHA.sha256("input data");
+SHA.hmac("secret", "message");
+```
+
+#### RSA Encryption
+
+```typescript
+import { RSA } from "@aitianyu.cn/types";
+
+const { publicKey, privateKey } = RSA.generateKeyPair();
+const encrypted = RSA.encrypt(publicKey, "secret text");
+const decrypted = RSA.decrypt(privateKey, encrypted);
+```
+
+#### QR Code Generation
+
+```typescript
+import { QRCode } from "@aitianyu.cn/types";
+
+// Returns a base64-encoded PNG data URL
+const dataUrl = await QRCode.getURL("https://example.com");
+```
+
+---
+
+### Type Definitions
+
+#### Common Generic Types
+
+```typescript
+import {
+    MapOfString,
+    MapOfStrings,
+    MapOfBoolean,
+    MapOfType,
+    KeyValuePair,
+    CallbackAction,
+    CallbackActionT,
+    IComparable,
+} from "@aitianyu.cn/types";
+
+const map: MapOfString   = { key: "value" };
+const flags: MapOfBoolean = { enabled: true };
+
+const pair: KeyValuePair<string, number> = { key: "age", value: 30 };
+
+const cb: CallbackActionT<string> = (value) => console.log(value);
+```
+
+#### Area Codes
+
+```typescript
+import { AreaCode, parseAreaCode, parseAreaString } from "@aitianyu.cn/types";
+
+const code = AreaCode.zh_CN;              // Chinese Simplified
+const str  = parseAreaString(AreaCode.en_US); // "en-US"
+```
+
+#### Path Utilities
+
+```typescript
+import { Path, PathTargetType } from "@aitianyu.cn/types";
+
+const p = new Path("/usr/local/bin/node", PathTargetType.File);
+p.directory;   // "/usr/local/bin"
+p.fileName;    // "node"
+```
+
+#### TMap
+
+```typescript
+import { TMap } from "@aitianyu.cn/types";
+
+const map = new TMap<string, number>();
+map.set("a", 1);
+map.get("a");   // 1
+```
+
+---
+
+## Build & Test
+
+```bash
+# Install dependencies
+npm install
+
+# Compile TypeScript and produce dist/
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test-all
+
+# Lint
+npm run eslint
+```
+
+Build output is placed in `dist/`:
+- `dist/lib/` — CommonJS JavaScript
+- `dist/types/` — TypeScript declaration files (`.d.ts`)