# @dooboostore/core

[![NPM version](https://img.shields.io/npm/v/@dooboostore/core.svg?color=cb3837&style=flat-square)](https://www.npmjs.com/package/@dooboostore/core)
[![Build and Test](https://github.com/dooboostore-develop/packages/actions/workflows/main.yaml/badge.svg?branch=main)](https://github.com/dooboostore-develop/packages/actions/workflows/main.yaml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)


A comprehensive TypeScript utility library providing 35+ modules with 200+ utilities for enterprise-grade application development. From reactive messaging to advanced async patterns, geometry operations to form validation—`@dooboostore/core` is the foundational toolkit for the @dooboostore ecosystem.

---

## ✨ Key Features

-   **🎯 RxJS-Like Reactive System**: 30+ operators with `Observable`, `Subject`, `BehaviorSubject`, and more—without the RxJS dependency
-   **⚡ Advanced Async Utilities**: Promise coordination, `AbortablePromise`, recurring loops, sleep/settle, and transaction management
-   **📋 Enterprise Validation Framework**: 30+ validators with composition, type guards, and form validation patterns
-   **📐 2D/3D Geometry Engine**: Point, Polygon, Rect, Ellipse, Vector operations with collision detection
-   **🌐 Flexible HTTP Client**: Extensible fetcher framework with plugin hooks and multiple output formats
-   **📦 Comprehensive Data Utilities**: Arrays, Objects, Strings, Dates, Math, Convert, Reflect, and more
-   **⏰ Cron Scheduling**: Schedule-based task execution with standard cron format
-   **🛡️ Transaction Management**: Coordinated error handling and resource cleanup across multiple operations
-   **🎨 Type-Safe**: Full TypeScript support with powerful utility types and strict typing
-   **🪶 Zero Dependencies**: ~200 utilities with NO external dependencies; tree-shaking friendly

## Installation

Install `@dooboostore/core` using your favorite package manager:

```bash
# pnpm
pnpm add @dooboostore/core

# npm
npm install @dooboostore/core

# yarn
yarn add @dooboostore/core
```

---

## 📚 Module Organization

`@dooboostore/core` is organized into **35+ modules** across 4 tiers:

### **Tier 1: Foundation (Data & Async)**
Core utilities for data manipulation and async operations.

| Module | Description | Key Exports |
|--------|-------------|------------|
| **message** | RxJS-like reactive system | `Observable`, `Subject`, `BehaviorSubject`, `ReplaySubject` |
| **promise** | Advanced async utilities | `Promises`, `AbortablePromise` |
| **valid** | Type guards & validation | `ValidUtils` (~20 type guards) |
| **array** | Array manipulation | `ArrayUtils` (chunk, flatten, compact, etc.) |
| **object** | Object introspection | `ObjectUtils` (keys, values, pick, merge, etc.) |
| **string** | String utilities | `StringUtils` (kebab, camel, pascal, trim, etc.) |
| **date** | Date/time operations | `DateUtils` (format, parse, diff, add, etc.) |
| **math** | Mathematical operations | `MathUtil` (Bezier, Pythagorean, angle calc) |
| **convert** | Type conversion | `ConvertUtils` (Map ↔ JSON, RGB, URL params) |
| **random** | Randomization | `RandomUtils` (randomInt, randomString, uuid) |

### **Tier 2: Data Structures & Network**
Specialized tools for validation, HTTP, and geometry.

| Module | Description | Key Exports |
|--------|-------------|------------|
| **validators** | Form validation framework | `Validator`, `FormValidator`, 30+ validator implementations |
| **fetch** | HTTP client framework | `HttpFetcher`, `HttpJsonFetcher`, extensible plugin system |
| **entity** | 2D/3D geometry | `Point2D`, `Point3D`, `Polygon`, `Rect`, `Ellipse`, `Vector` |
| **runs** | Runnable pattern | `Runnable<T, R>` interface and implementations |

### **Tier 3: Coordination & Async Patterns**
Advanced patterns for coordinating async operations.

| Module | Description | Key Exports |
|--------|-------------|------------|
| **transaction** | Transaction management | `TransactionManager` (coordinated error/cleanup) |
| **schedule** | Cron-based scheduling | `ScheduleBase` (standard cron format support) |
| **store** | Store loader pattern | `StoreLoader` (dynamic store initialization) |

### **Tier 4: Utilities & Helpers**
General-purpose helpers and specialized tools.

| Module | Description | Key Features |
|--------|-------------|------------|
| **url** | URL utilities | `UrlUtils` (parse, build, getPath, getPort, getQuery) |
| **parser** | Parsing utilities | `CssParser`, `ObjectPathParser` |
| **logger** | Structured logging | Configurable log levels (DEBUG, INFO, WARN, ERROR) |
| **storage** | Storage abstraction | `Storage`, `MemoryStorage`, `LocalStorageAdapter` |
| **reflect** | Metadata reflection | `ReflectUtils` (getPropertyNames, getConstructorParams) |
| **function** | Function utilities | Dynamic function execution, function composition |
| **optional** | Optional/Maybe monad | `Optional<T>` (Haskell-like optional type) |
| **iterators** | Range iterators | `Range` (numeric and character ranges) |
| **queues** | Async queues | `AsyncBlockingQueue<T>` (FIFO async queue) |
| **advice** | AOP exception handling | `Advice` (exception handling patterns) |
| **code** | Code constants | ISO3166-1 country codes and classifications |
| **image** | Image utilities | Image manipulation and analysis |
| **expression** | Expression evaluation | Dynamic expression parsing and execution |

---

## 🎯 Core Modules Deep Dive

### 1️⃣ **Message & Reactive System** (Observable, Subject)

The reactive messaging system provides an RxJS-like API **without the RxJS dependency**.

#### Core Classes

```typescript
// Base observable
Observable<T, E>
  .pipe(...operators): Observable
  .subscribe(observer | callbacks): Subscription
  .toPromise(): Promise<T | undefined>

// Subject variants
Subject<T, E>              // Multicast observable
BehaviorSubject<T, E>      // With initial value
ReplaySubject<T, E>        // Replays historical values
AsyncSubject<T, E>         // Emits last value on complete
```

#### 30+ Operators

**Transformation:**
```typescript
.map(fn)              // Transform each value
.switchMap(fn)        // Or switch to inner observable
.mergeMap(fn)         // Or merge inner observables
.concatMap(fn)        // Or concat inner observables
.reduce(fn, initial)  // Accumulate values
.scan(fn, initial)    // Running accumulation (like reduce but emits each step)
```

**Filtering:**
```typescript
.filter(predicate)      // Keep only matching values
.distinct()             // Skip duplicate consecutive values
.skipWhile(predicate)   // Skip while predicate is true
.takeWhile(predicate)   // Take while predicate is true
.first()                // Take only first value
.last()                 // Take only last value
```

**Time-based:**
```typescript
.debounceTime(ms)       // Delay after last emission
.throttle(ms)           // Allow one emission per interval
.delay(ms)              // Delay all emissions
.bufferTime(ms)         // Buffer values for interval
.timeout(ms)            // Error if no emission in time
```

**Error Handling:**
```typescript
.catchError(handler)    // Handle errors
.retry(count)           // Retry on error
```

**Combining:**
```typescript
.merge(other)           // Combine with another observable
.concat(other)          // Concatenate sequentially
```

#### Example: Reactive Form Validation

```typescript
import { Subject } from '@dooboostore/core/message';
import { debounceTime, map, switchMap } from '@dooboostore/core/message/operators';

// Create input change subject
const emailInput$ = new Subject<string>();

// Validation pipeline
const isValid$ = emailInput$.pipe(
  debounceTime(300),                    // Wait 300ms after user stops typing
  map(email => email.trim()),           // Normalize input
  switchMap(email => validateEmail(email))  // Check with server
);

// Subscribe to results
isValid$.subscribe({
  next: (valid) => console.log('Valid:', valid),
  error: (err) => console.error('Error:', err),
  complete: () => console.log('Done')
});

// Emit values
emailInput$.next('user@example.com');
```

---

### 2️⃣ **Promise Utilities** (Advanced Async)

Advanced patterns for Promise coordination and async control flow.

#### Key Functions

```typescript
// Delay execution
Promises.sleep(ms: number): Promise<void>
Promises.sleepReject(ms: number): Promise<never>  // Always rejects
Promises.delayExecute<T>(value: T, ms: number): Promise<T>

// Settlement & composition
Promises.settle<T>(promise: Promise<T>): Promise<SettledResult<T>>
  // Returns { status: 'fulfilled' | 'rejected', value?, reason? }
Promises.settles<T>(...promises): Promise<SettledResult<T>[]>
  // Settle multiple promises at once

// Recurring loops
Promises.loop(config: LoopConfig<T, R>): ObservableLoop<T, R>
  // Executes promise repeatedly with delay/max attempts

// Error filtering
Promises.filterCatch<T>(promise, errorType): Promise<Error | undefined>
  // Catches specific error type, rethrows others

// Abortable promises
Promises.abortable<T>(executor, signal?: AbortSignal): AbortablePromise<T>
  // Promise that can be aborted via AbortSignal
```

#### Example: Polling with Max Retries

```typescript
import { Promises } from '@dooboostore/core/promise';

const loop = Promises.loop({
  task: async () => {
    const response = await fetch('/api/status');
    if (!response.ok) throw new Error('Not ready');
    return response.json();
  },
  delay: 2000,        // Wait 2 seconds between attempts
  maxAttempts: 5,     // Max 5 attempts
  onSuccess: (result) => console.log('Success:', result),
  onError: (err) => console.error('Failed:', err)
});

// Manually check or cancel
console.log('Running:', loop.isRunning());
// loop.cancel();
```

#### Example: Coordinated Settlement

```typescript
import { Promises } from '@dooboostore/core/promise';

const results = await Promises.settles(
  fetch('/api/users'),
  fetch('/api/posts'),
  fetch('/api/comments')
);

results.forEach((result, index) => {
  if (result.status === 'fulfilled') {
    console.log(`Request ${index} succeeded:`, result.value);
  } else {
    console.log(`Request ${index} failed:`, result.reason);
  }
});
```

---

### 3️⃣ **Validation Framework** (30+ Validators)

Enterprise-grade form validation with composable validators.

#### Core Classes

```typescript
// Base validator
abstract class Validator<T> {
  abstract validate(value: T): Promise<ValidationResult>;
}

// Form validator (combines multiple validators)
class FormValidator {
  addValidator(field: string, validator: Validator): void
  async validate(formData: Record<string, any>): Promise<ValidationErrors>
}

// Validation result
interface ValidationResult {
  valid: boolean;
  error?: string;
}
```

#### 30+ Built-in Validators

**Text Validators:**
```typescript
new EmailValidator()              // RFC 5322 email format
new PhoneValidator()              // Phone numbers
new UrlValidator()                // URL format
new PatternValidator(/regex/)     // Custom regex pattern
new StringLengthValidator(1, 100) // Min/max length
new AlphanumericValidator()       // Only letters & numbers
new CreditCardValidator()         // Credit card format
```

**Number Validators:**
```typescript
new NumberRangeValidator(0, 100)  // Min/max bounds
new IntegerValidator()            // Whole numbers only
new PercentValidator()            // 0-100 range
new PositiveValidator()           // > 0
```

**Collection Validators:**
```typescript
new ArrayLengthValidator(1, 10)   // Array size bounds
new ArrayItemValidator(itemValidator) // Each item
new RequiredValidator()           // Not null/empty
new UniqueValidator()             // No duplicates
```

**Date/Time:**
```typescript
new DateValidator()               // Valid date format
new DateRangeValidator(from, to) // Between dates
new FutureValidator()             // Date in future
new PastValidator()               // Date in past
```

**Logic:**
```typescript
new CompositeValidator([v1, v2])  // All must pass (AND)
new AlternativeValidator([v1, v2])// Any must pass (OR)
new CustomValidator((val) => {...}) // Custom function
```

#### Example: Form Validation

```typescript
import { FormValidator, EmailValidator, StringLengthValidator } from '@dooboostore/core/validators';

const validator = new FormValidator();
validator.addValidator('email', new EmailValidator());
validator.addValidator('password', new StringLengthValidator(8, 100));
validator.addValidator('username', new AlphanumericValidator());

const errors = await validator.validate({
  email: 'user@example.com',
  password: 'secretpass123',
  username: 'john_doe'
});

if (Object.keys(errors).length > 0) {
  console.log('Validation errors:', errors);
} else {
  console.log('Form is valid!');
}
```

---

### 4️⃣ **Geometry & Entity** (2D/3D Operations)

Complete 2D/3D geometry system with collision detection.

#### Core Classes

```typescript
// 2D Points
Point2D { x: number, y: number }
  .distance(other: Point2D): number
  .angle(other: Point2D): number
  .rotate(angle: number, origin?: Point2D): Point2D

// 3D Points
Point3D { x: number, y: number, z: number }
  .distance(other: Point3D): number
  .cross(other: Point3D): Point3D
  .dot(other: Point3D): number

// Polygons
Polygon { points: Point2D[] }
  .contains(point: Point2D): boolean
  .intersects(other: Polygon): boolean
  .area(): number
  .perimeter(): number

// Rectangles
Rect { x: number, y: number, width: number, height: number }
  .contains(point: Point2D): boolean
  .intersects(other: Rect): boolean
  .overlaps(other: Rect): Rect | null

// Other shapes
Ellipse { centerX, centerY, radiusX, radiusY }
Vector { x, y }
Scalar { value }
```

#### Example: Collision Detection

```typescript
import { Rect, Point2D } from '@dooboostore/core/entity';

const playerRect = new Rect(100, 100, 50, 50);
const enemyRect = new Rect(130, 120, 40, 40);
const projectile = new Point2D(140, 110);

// Check collisions
if (playerRect.intersects(enemyRect)) {
  console.log('Player hit enemy!');
}

if (enemyRect.contains(projectile)) {
  console.log('Projectile hit enemy!');
}

// Get overlap area
const overlap = playerRect.overlaps(enemyRect);
console.log('Overlap:', overlap);
```

---

### 5️⃣ **HTTP Fetcher** (Extensible Framework)

Flexible HTTP client with plugin architecture.

#### Core Classes

```typescript
// Base fetcher
class HttpFetcher<T> {
  fetch(url: string, options?: FetchOptions): Promise<T>
  post(url: string, data: any, options?): Promise<T>
  get(url: string, options?): Promise<T>
  put(url: string, data: any, options?): Promise<T>
  delete(url: string, options?): Promise<T>
  patch(url: string, data: any, options?): Promise<T>
}

// JSON-specific
class HttpJsonFetcher extends HttpFetcher<any> {
  // Automatic JSON parsing/serializing
}
```

#### Plugin Hooks

```typescript
interface FetcherOptions {
  beforeRequest?: (request: Request) => Request | Promise<Request>
  afterResponse?: (response: Response) => Response | Promise<Response>
  onError?: (error: Error) => void
  timeout?: number
  retries?: number
  headers?: Record<string, string>
}
```

#### Example: API Client with Interceptors

```typescript
import { HttpJsonFetcher } from '@dooboostore/core/fetch';

class ApiClient extends HttpJsonFetcher {
  async beforeRequest(request: Request) {
    // Add authorization token
    request.headers.set('Authorization', `Bearer ${getToken()}`);
    return request;
  }

  async afterResponse(response: Response) {
    // Handle 401 - refresh token
    if (response.status === 401) {
      await refreshToken();
      // Retry request...
    }
    return response;
  }

  async onError(error: Error) {
    console.error('API Error:', error);
    // Report to error tracking service
  }
}

const client = new ApiClient({ timeout: 5000, retries: 3 });
const users = await client.get<User[]>('/api/users');
```

---

### 6️⃣ **Transaction Management**

Coordinated async operations with centralized error/cleanup handling.

#### Core Classes

```typescript
interface Transaction<I, T, C, F> {
  try(data: I): Promise<T>
  catch(error: any): Promise<C>
  finally(): Promise<F>
}

class TransactionManager {
  setTransaction(key: string, transaction: Transaction): void
  getTransaction(key: string): Transaction | undefined
  hasTransaction(key: string): boolean
  deleteTransaction(key: string): void
  async try(data?: any): Promise<void>        // Run all try()
  async catch(error: any): Promise<void>      // Cascade to all catch()
  async finally(): Promise<void>              // Run all finally() for cleanup
}
```

#### Example: Multi-Step Operation with Rollback

```typescript
import { TransactionManager } from '@dooboostore/core/transaction';

class OrderTransaction {
  try(order: Order) {
    // Step 1: Create order in DB
    // Step 2: Process payment
    // Step 3: Send confirmation email
  }
  
  catch(error: any) {
    // Rollback: Refund payment, delete order
  }
  
  finally() {
    // Cleanup: Close connections, release locks
  }
}

const manager = new TransactionManager();
manager.setTransaction('order', new OrderTransaction());
manager.setTransaction('inventory', new InventoryTransaction());

try {
  await manager.try({ orderData: {...} });
} catch (error) {
  await manager.catch(error);  // Cascades to all transactions
} finally {
  await manager.finally();     // Cleanup for all transactions
}
```

---

### 7️⃣ **Scheduling** (Cron Format)

Schedule recurring tasks using standard cron format.

#### Cron Format Reference

```
  *    *    *    *    *    *
  ┬    ┬    ┬    ┬    ┬    ┬
  │    │    │    │    │    └─ day of week (0-7, Sun-Sat)
  │    │    │    │    └────── month (1-12)
  │    │    │    └─────────── day (1-31)
  │    │    └──────────────── hour (0-23)
  │    └───────────────────── minute (0-59)
  └────────────────────────── second (0-59, optional)

Examples:
  "0 0 * * *"         → Daily at midnight
  "0 9 * * 1"         → Every Monday at 9:00 AM
  "*/15 * * * *"      → Every 15 minutes
  "0 0 1 * *"         → First day of every month
  "0 0 * * 0"         → Every Sunday
  "0 18 * * 1-5"      → Weekdays at 6:00 PM
```

#### Example: Scheduled Tasks

```typescript
import { ScheduleBase } from '@dooboostore/core/schedule';

class BackupSchedule extends ScheduleBase<null, BackupResult> {
  spec = "0 2 * * *";  // 2 AM daily
  name = "Daily Database Backup";

  async execute(): Promise<BackupResult> {
    const backup = await performBackup();
    return {
      timestamp: new Date(),
      filesBackedUp: backup.fileCount,
      success: true
    };
  }
}

const schedule = new BackupSchedule();
await schedule.execute();  // Run manually
```

---

### 8️⃣ **Data Utilities**

Common helpers for array, object, string, date operations.

#### ArrayUtils

```typescript
ArrayUtils.chunk(arr, size)           // Split into chunks
ArrayUtils.flatten(arr)               // Flatten nested arrays
ArrayUtils.compact(arr)               // Remove falsy values
ArrayUtils.uniq(arr)                  // Remove duplicates
ArrayUtils.shuffle(arr)               // Randomize order
ArrayUtils.group(arr, keyFn)          // Group by key function
ArrayUtils.range(start, end)          // Create range array
ArrayUtils.zip(...arrays)             // Combine arrays
ArrayUtils.transpose(matrix)          // Transpose 2D array
```

#### ObjectUtils

```typescript
ObjectUtils.keys(obj)                 // Get all keys
ObjectUtils.values(obj)               // Get all values
ObjectUtils.entries(obj)              // Get key-value pairs
ObjectUtils.pick(obj, keys)           // Select specific keys
ObjectUtils.omit(obj, keys)           // Remove specific keys
ObjectUtils.merge(...objects)         // Deep merge objects
ObjectUtils.clone(obj)                // Deep clone
ObjectUtils.assign(target, source)    // Like Object.assign
ObjectUtils.freeze(obj)               // Recursively freeze
```

#### StringUtils

```typescript
StringUtils.camelCase(str)            // camelCase
StringUtils.kebabCase(str)            // kebab-case
StringUtils.pascalCase(str)           // PascalCase
StringUtils.snakeCase(str)            // snake_case
StringUtils.trim(str)                 // Remove whitespace
StringUtils.capitalize(str)           // Capitalize first letter
StringUtils.reverse(str)              // Reverse string
StringUtils.truncate(str, length)     // Truncate with ellipsis
StringUtils.repeat(str, count)        // Repeat string
StringUtils.padStart(str, length, pad) // Pad start
```

#### DateUtils

```typescript
DateUtils.format(date, format)        // Format date string
DateUtils.parse(dateStr)              // Parse date string
DateUtils.add(date, amount, unit)     // Add time
DateUtils.diff(date1, date2, unit)    // Get difference
DateUtils.startOf(date, unit)         // Start of period
DateUtils.endOf(date, unit)           // End of period
DateUtils.isLeapYear(year)            // Check leap year
DateUtils.getDaysInMonth(date)        // Days in month
DateUtils.isBefore(date1, date2)      // Date comparison
```

#### MathUtil

```typescript
MathUtil.distance(p1, p2)             // Euclidean distance
MathUtil.angle(p1, p2)                // Angle between points
MathUtil.lerp(a, b, t)                // Linear interpolation
MathUtil.clamp(value, min, max)       // Clamp to range
MathUtil.normalize(value, min, max)   // 0-1 normalization
MathUtil.degToRad(degrees)            // Convert degrees to radians
MathUtil.radToDeg(radians)            // Convert radians to degrees
MathUtil.bezier(t, ...points)         // Bezier curve calculation
```

---

## 📖 Usage Examples

### Example 1: Real-time Search with Debounce

```typescript
import { Subject } from '@dooboostore/core/message';
import { debounceTime, map, switchMap } from '@dooboostore/core/message/operators';
import { HttpJsonFetcher } from '@dooboostore/core/fetch';

const searchInput$ = new Subject<string>();
const fetcher = new HttpJsonFetcher();

searchInput$.pipe(
  debounceTime(300),
  map(query => query.trim()),
  filter(query => query.length > 0),
  switchMap(query => fetcher.get(`/api/search?q=${query}`))
).subscribe(
  results => displayResults(results),
  error => showError(error)
);

// Emit searches
searchInput$.next('typescript');
searchInput$.next('utilities');
```

### Example 2: Form Validation Pipeline

```typescript
import { FormValidator, EmailValidator, StringLengthValidator } from '@dooboostore/core/validators';
import { Subject } from '@dooboostore/core/message';
import { debounceTime, switchMap } from '@dooboostore/core/message/operators';

const formData$ = new Subject<FormData>();
const validator = new FormValidator();

validator.addValidator('email', new EmailValidator());
validator.addValidator('password', new StringLengthValidator(8, 128));

formData$.pipe(
  debounceTime(500),
  switchMap(data => validator.validate(data))
).subscribe(
  errors => {
    if (Object.keys(errors).length === 0) {
      enableSubmitButton();
    } else {
      showValidationErrors(errors);
    }
  }
);
```

### Example 3: Coordinated Async Operations

```typescript
import { Promises } from '@dooboostore/core/promise';
import { HttpJsonFetcher } from '@dooboostore/core/fetch';

const fetcher = new HttpJsonFetcher({ timeout: 5000 });

const [users, posts, comments] = await Promise.all([
  fetcher.get('/api/users'),
  fetcher.get('/api/posts'),
  fetcher.get('/api/comments')
]);

// Or with error handling
const results = await Promises.settles(
  fetcher.get('/api/users'),
  fetcher.get('/api/posts'),
  fetcher.get('/api/comments')
);

results.forEach((result, idx) => {
  if (result.status === 'fulfilled') {
    console.log(`Request ${idx}:`, result.value);
  } else {
    console.log(`Request ${idx} failed:`, result.reason);
  }
});
```

### Example 4: Geometry & Collision

```typescript
import { Rect, Point2D, Polygon } from '@dooboostore/core/entity';

// Create game objects
const player = new Rect(100, 100, 50, 50);
const enemy = new Rect(200, 140, 40, 40);
const powerUp = new Point2D(150, 180);

// Check collisions
if (player.intersects(enemy)) {
  console.log('Game Over!');
}

if (player.contains(powerUp)) {
  console.log('Power Up Activated!');
}

// Complex shapes
const walls = new Polygon([
  new Point2D(0, 0),
  new Point2D(500, 0),
  new Point2D(500, 500),
  new Point2D(0, 500)
]);

if (walls.contains(player)) {
  console.log('Player is inside walls');
}
```

### Example 5: Transaction with Rollback

```typescript
import { TransactionManager } from '@dooboostore/core/transaction';

class PaymentTransaction {
  async try(order: Order) {
    // Charge the customer
    await chargeCard(order.payment);
  }
  
  async catch(error: any) {
    // Refund if something fails
    console.log('Refunding due to:', error.message);
    await refundCard(order.payment);
  }
  
  async finally() {
    // Cleanup
    await closePaymentConnection();
  }
}

class InventoryTransaction {
  async try(order: Order) {
    await reduceInventory(order.items);
  }
  
  async catch(error: any) {
    await restoreInventory(order.items);
  }
  
  async finally() {
    await closeDatabase();
  }
}

const manager = new TransactionManager();
manager.setTransaction('payment', new PaymentTransaction());
manager.setTransaction('inventory', new InventoryTransaction());

try {
  await manager.try(order);
  console.log('Order processed successfully');
} catch (error) {
  await manager.catch(error);  // All transactions rollback
  console.log('Order failed and rolled back');
} finally {
  await manager.finally();     // All cleanup
}
```

---

## 🔗 Type Guard Utilities

Comprehensive type checking functions:

```typescript
import { ValidUtils } from '@dooboostore/core/valid';

ValidUtils.isString(value)            // Check if string
ValidUtils.isNumber(value)            // Check if number
ValidUtils.isBoolean(value)           // Check if boolean
ValidUtils.isArray(value)             // Check if array
ValidUtils.isObject(value)            // Check if object (not null/array)
ValidUtils.isNull(value)              // Check if null
ValidUtils.isUndefined(value)         // Check if undefined
ValidUtils.isFunction(value)          // Check if function
ValidUtils.isDate(value)              // Check if Date
ValidUtils.isRegExp(value)            // Check if RegExp
ValidUtils.isEmpty(value)             // Check if empty
ValidUtils.isAsync(value)             // Check if Promise
ValidUtils.isIterable(value)          // Check if iterable
ValidUtils.hasProperty(obj, prop)     // Check if has property
ValidUtils.isPrimitive(value)         // Check if primitive type
```

---

## 🏗️ Architecture Overview

```
┌─────────────────────────────────────────────┐
│       @dooboostore/core Modules             │
├─────────────────────────────────────────────┤
│                                              │
│  ┌─ TIER 1: Utilities ────────────────┐    │
│  │ • strings, arrays, objects         │    │
│  │ • dates, math, convert             │    │
│  │ • random, valid (type guards)      │    │
│  └────────────────────────────────────┘    │
│           ↓                                  │
│  ┌─ TIER 1: Async Core ──────────────┐    │
│  │ • Observable/Subject (30+ ops)     │    │
│  │ • Promises (sleep, settle, loop)   │    │
│  └────────────────────────────────────┘    │
│           ↓                                  │
│  ┌─ TIER 2: Domain-Specific ────────┐     │
│  │ • Validators (30+ validators)      │    │
│  │ • HttpFetcher (HTTP client)        │    │
│  │ • Entity (2D/3D geometry)          │    │
│  │ • Runs (Runnable pattern)          │    │
│  └────────────────────────────────────┘    │
│           ↓                                  │
│  ┌─ TIER 3: Async Patterns ─────────┐     │
│  │ • Transaction (coordinated async)  │    │
│  │ • Schedule (cron scheduling)       │    │
│  │ • Store (dynamic loading)          │    │
│  └────────────────────────────────────┘    │
│           ↓                                  │
│  ┌─ TIER 4: Specialized Utils ──────┐     │
│  │ • URL parsing, CSS parsing         │    │
│  │ • Logger, Storage abstraction      │    │
│  │ • Reflect, Function utilities      │    │
│  │ • Optional monad, Iterators        │    │
│  └────────────────────────────────────┘    │
│                                              │
└─────────────────────────────────────────────┘
```

---

## 📊 Performance Characteristics

| Aspect | Characteristic |
|--------|---|
| **Dependencies** | 0 external dependencies |
| **Bundle Size** | ~50KB gzipped (full library) |
| **Tree-Shaking** | ✅ Fully supported |
| **Module Format** | ESM, CJS, UMD |
| **TypeScript** | Full native support |
| **Runtime** | Node.js 12+, Browsers |
| **Observable Performance** | Similar to RxJS for typical workloads |
| **Validation Speed** | ~1ms for complex forms (100+ fields) |
| **HTTP Client** | Native fetch-based, no extra overhead |

---

## 🎓 Best Practices

### 1. **Use Type Guards for Runtime Safety**
```typescript
import { ValidUtils } from '@dooboostore/core/valid';

function processData(data: unknown) {
  if (ValidUtils.isObject(data) && ValidUtils.hasProperty(data, 'id')) {
    // Safe to access data.id
  }
}
```

### 2. **Compose Validators for Complex Forms**
```typescript
import { CompositeValidator } from '@dooboostore/core/validators';

const passwordValidator = new CompositeValidator([
  new StringLengthValidator(8, 128),
  new PatternValidator(/[A-Z]/),    // At least one uppercase
  new PatternValidator(/[0-9]/)     // At least one digit
]);
```

### 3. **Use Debounce for UI Events**
```typescript
searchInput$.pipe(
  debounceTime(500),  // Wait for user to finish typing
  switchMap(query => searchApi(query))
).subscribe(results => updateUI(results));
```

### 4. **Manage Subscriptions Correctly**
```typescript
const subscription = observable.subscribe(...);
// Clean up when done
subscription.unsubscribe();
```

### 5. **Use Transactions for Multi-Step Operations**
```typescript
// Ensures all-or-nothing semantics
const manager = new TransactionManager();
manager.setTransaction('db', dbTransaction);
manager.setTransaction('api', apiTransaction);
// If any fails, all rollback
```

---

## 🚀 Advanced Topics

### Reactive Composition
```typescript
const user$ = userIdInput$.pipe(
  debounceTime(300),
  switchMap(id => fetchUser(id)),
  catchError(err => {
    console.error('Failed to fetch user:', err);
    return of(null);
  })
);
```

### Error Boundaries with Transactions
```typescript
const manager = new TransactionManager();
// Add multiple transactions
// try() → catch() → finally() flows automatically
```

### Custom Validators
```typescript
class UniqueUsernameValidator extends Validator<string> {
  async validate(username: string) {
    const exists = await checkUsernameExists(username);
    return {
      valid: !exists,
      error: exists ? 'Username already taken' : undefined
    };
  }
}
```

---

## 📚 Learn More

The detailed API documentation, including all modules and usage examples, is available on our documentation website.


## License

This package is licensed under the [MIT License](https://opensource.org/licenses/MIT).