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

2.0 KiB

Raw Blame History

Plugin Dependencies

Overview

The Custom Resolver system provides a powerful dependency management system that allows plugins to depend on the resolved values of other properties. This enables complex resolution strategies where the value of one property can influence how another property is resolved.

Key Concepts

Dependency Declaration: Plugins declare their dependencies using the dependencies property
Type Safety: Dependencies are type-checked at compile time
Automatic Resolution: The system resolves dependencies in the correct order
Cycle Detection: Circular dependencies are detected and reported

How It Works

Dependency Graph: The system builds a directed acyclic graph (DAG) of plugin dependencies
Topological Sort: Plugins are processed in an order that respects their dependencies
Dependency Injection: Required dependencies are automatically injected into plugin methods
Lazy Resolution: Dependencies are only resolved when needed

Example

class TotalPricePlugin implements ResolverPlugin<TotalState, 'price' | 'tax'> {
  readonly dependencies = ['price', 'tax'] as const;
  
  initialize(): TotalState {
    return { total: 0 };
  }
  
  update(
    state: TotalState,
    _newValue: unknown,
    _delta: CollapsedDelta,
    deps: DependencyStates
  ): TotalState {
    const price = deps.price as number;
    const tax = deps.tax as number;
    return { total: price + tax };
  }
  
  resolve(state: TotalState): number {
    return state.total;
  }
}

Best Practices

Minimal Dependencies: Only declare dependencies that are actually needed
Acyclic Dependencies: Keep the dependency graph acyclic
Document Dependencies: Clearly document what each dependency is used for
Handle Missing Dependencies: Gracefully handle cases where dependencies might be undefined

Next Steps

Learn about Type-Safe Dependencies
Understand Dependency Resolution

2.0 KiB Raw Blame History