@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

npm install @formwire/core

Usage

Basic Usage

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

// Replace services at runtime
engine.setValidationService(new CustomValidationService());
engine.setCacheService(new CustomCacheService());

// Get service statistics
const stats = engine.getServiceStats();
console.log(stats);

Form Operations

// Data operations
engine.set('email', '[email protected]');
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

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.

const service = new ValidationService({
  debounceDelay: 300,
  validateOnChange: false,
  validateOnBlur: true
});

CacheService

High-performance caching with automatic memory cleanup.

const service = new CacheService({
  enableValueCache: true,
  maxCacheSize: 1000
});

EventService

Event system with automatic cleanup and context tracking.

const service = new EventService({
  enableContextTracking: true,
  enableErrorHandling: true
});

BatchService

Efficient operation batching for performance optimization.

const service = new BatchService({
  enableBatching: true,
  batchDelay: 100
});

License

MIT