refactor(resolver): overhaul plugin system and dependency handling

Core Changes:
- Completely rewrote CustomResolver reducer with dependency-ordered processing
- Enhanced plugin initialization with proper dependency injection
- Improved delta processing and property value tracking
- Added robust error handling for duplicate property IDs

Resolver Improvements:
- Updated to use new accumulator structure
- Implemented execution order processing for plugins
- Enhanced debug logging and error reporting
- Simplified TimestampResolver by removing unused initializer

Configuration Updates:
- Added TypeScript path aliases for test helpers
- Improved module resolution paths

Key Benefits:
- More robust plugin dependency management
- More efficient state updates
- Enhanced type safety
- Better error messages and debugging
- More consistent plugin initialization

This refactoring focuses on improving the robustness of the resolver,
especially around plugin lifecycle management and dependency handling.
The changes ensure better separation of concerns and more predictable
behavior when dealing with complex plugin dependencies.

2025-06-25 06:10:34 -05:00

3.0 KiB

Raw Blame History

Creating Custom Plugins

Overview

Custom plugins allow you to implement custom resolution logic for your specific use case. This guide walks through creating a new plugin from scratch.

Basic Plugin Structure

A minimal plugin must implement the ResolverPlugin interface:

import { ResolverPlugin } from '../resolver';

class MyPlugin implements ResolverPlugin<MyState> {
  
  initialize(): MyState {
    // Return initial state
    return { /* ... */ };
  }
  
  update(
    currentState: MyState,
    newValue: unknown,
    delta: CollapsedDelta,
    dependencies: {}
  ): MyState {
    // Update state based on new value
    return { /* updated state */ };
  }
  
  resolve(state: MyState): unknown {
    // Return the resolved value
    return /* resolved value */;
  }
}

Adding Dependencies

To depend on other properties, specify the dependency types:

class DiscountedPricePlugin implements ResolverPlugin<DiscountState, 'basePrice' | 'discount'> {
  readonly dependencies = ['basePrice', 'discount'] as const;
  
  initialize(): DiscountState {
    return { finalPrice: 0 };
  }
  
  update(
    state: DiscountState,
    _newValue: unknown,
    _delta: CollapsedDelta,
    deps: DependencyStates
  ): DiscountState {
    const basePrice = deps.basePrice as number;
    const discount = deps.discount as number;
    return { finalPrice: basePrice * (1 - discount) };
  }
  
  resolve(state: DiscountState): number {
    return state.finalPrice;
  }
}

Best Practices

Immutable State: Always return new state objects instead of mutating
Pure Functions: Keep update and resolve methods pure and side-effect free
Error Handling: Handle unexpected input gracefully
Type Safety: Use TypeScript types to catch errors early
Documentation: Document your plugin's behavior and requirements

Testing Your Plugin

Create tests to verify your plugin's behavior:

describe('DiscountedPricePlugin', () => {
  let view: LosslessView;
  let resolver: CustomResolver;
  
  beforeEach(() => {
    view = new LosslessView();
    resolver = new CustomResolver(view, {
      basePrice: new LastWriteWinsPlugin(),
      discount: new LastWriteWinsPlugin(),
      finalPrice: new DiscountedPricePlugin()
    });
  });
  
  test('applies discount to base price', () => {
    // Test your plugin's behavior
  });
});

Advanced Topics

Handling Complex Dependencies

For plugins with complex dependency requirements, you can use the dependencies array to declare all required properties and access them in a type-safe way through the dependencies parameter.

Performance Considerations

Keep state updates minimal and efficient
Avoid expensive computations in the update method
Consider memoization for expensive resolve operations

Debugging

Add logging to track state changes and resolution:

update(currentState: MyState, newValue: unknown): MyState {
  debug('Updating with:', { currentState, newValue });
  // ...
}

3.0 KiB Raw Blame History