npm package: @basic-math/client
Description: Clean Architecture math library with dependency injection, configurable adapters, and monitoring
Author: Your Name
Latest version: 0.1.0

# Basic Math

A TypeScript library for basic mathematical operations (addition, subtraction, multiplication, division) built with Clean Architecture principles.

## Features

- Four basic mathematical operations: add, subtract, multiply, divide
- Type-safe TypeScript implementation
- Input validation and error handling
- Clean Architecture / Hexagonal Architecture design
- Fully tested with unit tests
- Zero dependencies

## Installation

```bash
bun install
```

## Usage

### Basic Usage

```typescript
import { Client } from './src/index';

// Create a client with default configuration (package adapters)
const math = new Client();

// Perform operations
const sum = math.add(5, 3);        // 8
const diff = math.subtract(10, 4);  // 6
const product = math.multiply(6, 7); // 42
const quotient = math.divide(15, 3); // 5
```

### Custom Configuration

```typescript
import { Client } from './src/index';

// 1. Use all native adapters
const math1 = new Client({
  add: 'native',
  subtract: 'native',
  multiply: 'native',
  divide: 'native'
});

// 2. Mix native and package adapters
const math2 = new Client({
  add: 'package',      // Use @basic-math/add
  subtract: 'native',   // Use native JS operations
  multiply: 'package',
  divide: 'native'
});

// 3. Custom function injection (Dependency Injection)
const math3 = new Client({
  add: (a, b) => a + b + 10,           // Custom add logic
  subtract: (a, b) => a - b - 1,       // Custom subtract logic
  multiply: 'package',
  divide: 'native'
});

console.log(math3.add(5, 3));      // 18 (5 + 3 + 10)
console.log(math3.subtract(10, 4)); // 5 (10 - 4 - 1)

// 4. Custom adapter injection
import { NativeAddAdapter } from './src/index';

const math4 = new Client({
  add: new NativeAddAdapter(),  // Direct adapter instance
  subtract: 'native'
});

// 5. Partial configuration (others use default)
const math5 = new Client({
  add: 'native'  // Only override add, others use default (package)
});

// 6. With monitoring (on/off)
import { MonitorService, ConsoleOperationRepository } from '@basic-math/monitor';

const repository = new ConsoleOperationRepository();
const monitor = new MonitorService(repository);

const math6 = new Client({
  monitoring: true,        // Enable monitoring
  monitorService: monitor  // Provide monitor service
});

math6.add(5, 3);  // Automatically logged and recorded!

// Query operation history
const stats = await monitor.getStatistics();
const operations = await monitor.getAllOperations();
```

## API Reference

### `Client`

Main class for performing mathematical operations.

#### Constructor

```typescript
new Client(config?: ClientConfig)
```

**Parameters:**
- `config` (optional): Configuration object for adapter selection

**Config Options:**

**Operation Adapters:**
Each operation (`add`, `subtract`, `multiply`, `divide`) can be configured as:
- `'native'`: Use native JavaScript operations
- `'package'`: Use @basic-math/* packages (default)
- `Function`: Custom function `(a: number, b: number) => number`
- `Adapter`: Custom adapter instance implementing the respective Port interface

**Monitoring:**
- `monitoring` (boolean): Enable/disable operation monitoring (default: false)
- `monitorService`: MonitorService instance from @basic-math/monitor (required if monitoring is true)

#### Methods

##### `add(a: number, b: number): number`
Returns the sum of two numbers.

##### `subtract(a: number, b: number): number`
Returns the difference between two numbers.

##### `multiply(a: number, b: number): number`
Returns the product of two numbers.

##### `divide(a: number, b: number): number`
Returns the quotient of two numbers.

**Note**: All methods validate inputs and throw errors for invalid values (NaN, Infinity, -Infinity). Division by zero also throws an error.

## Architecture

This library follows Clean Architecture / Hexagonal Architecture principles:

```
src/
├── domains/              # Domain Layer
│   ├── ports/           # Interface definitions
│   ├── value-object/    # Domain value objects
│   └── validators/      # Input validation
├── applications/        # Application Layer
│   └── use-cases/      # Business logic use cases
├── infrastructures/     # Infrastructure Layer
│   ├── Native*Adapter.ts    # Native JavaScript implementations
│   └── Package*Adapter.ts   # @basic-math/* package implementations
└── config.ts            # Adapter configuration
```

### Layers

- **Domain Layer**: Core business rules and entities
  - Ports: Interfaces for mathematical operations
  - Value Objects: `NumberValue` encapsulates number validation
  - Validators: Input validation logic

- **Application Layer**: Use cases that orchestrate domain logic
  - Each operation has a dedicated use case (AddUseCase, SubtractUseCase, etc.)

- **Infrastructure Layer**: External implementations
  - **NativeAdapter**: Direct JavaScript operations (`+`, `-`, `*`, `/`)
  - **PackageAdapter**: Uses @basic-math/* packages with SafeNumber validation

### Monitoring Operations

Enable automatic operation monitoring with simple on/off configuration:

```typescript
import { Client } from './src/index';
import { MonitorService, ConsoleOperationRepository } from '@basic-math/monitor';

// Setup monitoring
const repository = new ConsoleOperationRepository();
const monitor = new MonitorService(repository);

// Create client with monitoring enabled
const math = new Client({
  monitoring: true,
  monitorService: monitor
});

// All operations are automatically recorded
math.add(5, 3);      // Logged: "📊 Operation: add, 5 + 3 = 8"
math.subtract(10, 4); // Logged: "📊 Operation: subtract, 10 - 4 = 6"

// Query operation history
const stats = await monitor.getStatistics();
console.log(`Total operations: ${stats.total}`);

const operations = await monitor.getAllOperations();
operations.forEach(op => {
  console.log(`${op.operation}: ${op.operandA} → ${op.result}`);
});
```

**Monitoring Features:**
- **On/Off Control**: Simple `monitoring: true/false` flag
- **Automatic Recording**: All operations automatically logged when enabled
- **No Code Changes**: Each package handles monitoring internally
- **Zero Overhead**: No performance impact when monitoring is disabled
- **Flexible Storage**: Use built-in ConsoleRepository or implement custom storage

## Testing

Run tests:

```bash
bun test
```

The library includes comprehensive unit tests for:
- Use cases
- Value objects
- Validators

## Development

Built with:
- [Bun](https://bun.com) - Fast all-in-one JavaScript runtime
- TypeScript 5+

## License

Private package (not published to npm)