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

bun install

Usage

Basic Usage

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

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

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:

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:

bun test

The library includes comprehensive unit tests for:

• Use cases
• Value objects
• Validators

Development

Built with:

• Bun - Fast all-in-one JavaScript runtime
• TypeScript 5+

License

Private package (not published to npm)