npm package: @formwire/core
Description: Core form engine with service injection architecture
Author: FormWire Team
Latest version: 0.1.0

# @formwire/core

Core form engine with service injection architecture for FormWire.

## Features

- **Service Injection Architecture** - Modular, testable, and extensible
- **Zero Dependencies** - No external dependencies
- **High Performance** - Optimized with WeakMap caching and microtask batching
- **TypeScript Ready** - Full type support
- **Memory Efficient** - Automatic cleanup with WeakMap

## Installation

```bash
npm install @formwire/core
```

## Usage

### Basic Usage

```javascript
import { FormEngine, ValidationService, CacheService, EventService, BatchService } from '@formwire/core';

// Create services
const validationService = new ValidationService({
  debounceDelay: 300,
  validateOnChange: true,
});

const cacheService = new CacheService({
  enableValueCache: true,
  maxCacheSize: 1000,
});

const eventService = new EventService({
  enableContextTracking: true,
  enableErrorHandling: true,
});

const batchService = new BatchService({
  enableBatching: true,
  batchDelay: 100,
});

// Create engine with custom services
const engine = new FormEngine({
  validationService,
  cacheService,
  eventService,
  batchService,
});

// Initialize form
engine.init({ email: '', name: '' }, { validateOnBlur: true });
```

### Service Management

```javascript
// Replace services at runtime
engine.setValidationService(new CustomValidationService());
engine.setCacheService(new CustomCacheService());

// Get service statistics
const stats = engine.getServiceStats();
console.log(stats);
```

### Form Operations

```javascript
// Data operations
engine.set('email', 'user@example.com');
const email = engine.get('email');

// Validation
engine.registerValidator('email', (value) => {
  if (!value) return 'Email is required';
  if (!value.includes('@')) return 'Invalid email';
  return undefined;
});

engine.validateAll();

// State management
engine.touch('email');
engine.focus('email');
engine.blur();

// Events
engine.on('change', (data) => {
  console.log('Form changed:', data);
});

// Submission
engine.submit((values) => {
  console.log('Form submitted:', values);
});
```

## API Reference

### FormEngine

The main form engine class that coordinates all services.

#### Constructor

```javascript
new FormEngine(services)
```

- `services` (object): Service configuration
  - `validationService` (ValidationService): Validation service instance
  - `cacheService` (CacheService): Cache service instance
  - `eventService` (EventService): Event service instance
  - `batchService` (BatchService): Batch service instance

#### Methods

- `init(initialValues, config)` - Initialize form with initial values and configuration
- `reset()` - Reset form to initial state
- `get(path)` - Get value by path
- `set(path, value)` - Set value by path
- `setMany(updates)` - Bulk update multiple values
- `registerValidator(path, validator)` - Register validator for field
- `validateAll()` - Validate all fields
- `hasValidator(path)` - Check if validator exists for field
- `touch(path)` - Mark field as touched
- `focus(path)` - Focus on field
- `blur()` - Remove focus
- `on(event, callback)` - Subscribe to events
- `submit(onSubmit)` - Submit form
- `setValidationService(service)` - Replace validation service
- `setCacheService(service)` - Replace cache service
- `setEventService(service)` - Replace event service
- `setBatchService(service)` - Replace batch service
- `getServiceStats()` - Get all services statistics

### Services

#### ValidationService

Handles field validation with debouncing support.

```javascript
const service = new ValidationService({
  debounceDelay: 300,
  validateOnChange: false,
  validateOnBlur: true
});
```

#### CacheService

High-performance caching with automatic memory cleanup.

```javascript
const service = new CacheService({
  enableValueCache: true,
  maxCacheSize: 1000
});
```

#### EventService

Event system with automatic cleanup and context tracking.

```javascript
const service = new EventService({
  enableContextTracking: true,
  enableErrorHandling: true
});
```

#### BatchService

Efficient operation batching for performance optimization.

```javascript
const service = new BatchService({
  enableBatching: true,
  batchDelay: 100
});
```

## License

MIT