rhizome-node/docs/custom-resolvers/api/custom-resolver-class.md

CustomResolver Class

Overview

The CustomResolver class is the main entry point for the Custom Resolver system. It manages the resolution of entity properties using the configured plugins and handles dependency resolution between them.

Class Definition

class CustomResolver {
  /**
   * Creates a new CustomResolver instance
   * @param view The lossless view to resolve
   * @param config Plugin configuration
   */
  constructor(
    private readonly view: LosslessView,
    private readonly config: ResolverConfig
  );

  /**
   * Processes all entities in the view and returns the resolved values
   */
  resolve(): CustomResolverResult;

  /**
   * Processes a single entity and returns its resolved values
   * @param entityId ID of the entity to resolve
   */
  resolveEntity(entityId: string): EntityResult | undefined;

  /**
   * Gets the current processing order of properties
   */
  getProcessingOrder(): string[];

  /**
   * Gets the dependency graph
   */
  getDependencyGraph(): Map<string, Set<string>>;
}

Constructor

new CustomResolver(view, config)

Creates a new instance of the CustomResolver.

Parameters:

• view: LosslessView - The lossless view containing the data to resolve
• config: ResolverConfig - Configuration object mapping property IDs to their resolver plugins

Example:

const resolver = new CustomResolver(view, {
  price: new LastWriteWinsPlugin(),
  discount: new LastWriteWinsPlugin(),
  total: new TotalPricePlugin()
});

Methods

resolve(): CustomResolverResult

Processes all entities in the view and returns the resolved values.

Returns: CustomResolverResult - Object mapping entity IDs to their resolved properties

Example:

const results = resolver.resolve();
console.log(results);
// {
//   'entity1': {
//     id: 'entity1',
//     properties: { price: 100, discount: 10, total: 90 }
//   },
//   // ...
// }

resolveEntity(entityId: string): EntityResult | undefined

Processes a single entity and returns its resolved values.

Parameters:

• entityId: string - ID of the entity to resolve

Returns: EntityResult | undefined - Resolved entity or undefined if not found

Example:

const result = resolver.resolveEntity('order-123');
if (result) {
  console.log(`Order total: ${result.properties.total}`);
}

getProcessingOrder(): string[]

Gets the current processing order of properties based on their dependencies.

Returns: string[] - Array of property IDs in processing order

Example:

const order = resolver.getProcessingOrder();
console.log('Processing order:', order);
// ['price', 'discount', 'total']

getDependencyGraph(): Map<string, Set<string>>

Gets the dependency graph used for resolution.

Returns: Map<string, Set<string>> - Map where keys are property IDs and values are sets of their dependencies

Example:

const graph = resolver.getDependencyGraph();
for (const [prop, deps] of graph.entries()) {
  console.log(`${prop} depends on:`, [...deps]);
}

Configuration

The resolver is configured with an object mapping property IDs to their resolver plugins:

interface ResolverConfig {
  [propertyId: string]: ResolverPlugin<any, string>;
}

Error Handling

The resolver may throw the following errors:

• Error - For invalid configurations or dependency cycles
• TypeError - For type mismatches or invalid plugin implementations

Example: Complete Usage

import { CustomResolver, LastWriteWinsPlugin } from './resolver';
import { LosslessView } from '../lossless-view';

// Create a lossless view with some data
const view = new LosslessView();
// ... add data to the view ...

// Configure the resolver
const resolver = new CustomResolver(view, {
  // Simple plugins
  productId: new LastWriteWinsPlugin(),
  quantity: new LastWriteWinsPlugin(),
  
  // Plugin with dependencies
  unitPrice: new LastWriteWinsPlugin(),
  discount: new LastWriteWinsPlugin(),
  taxRate: new LastWriteWinsPlugin(),
  
  // Complex plugin with multiple dependencies
  subtotal: new class implements ResolverPlugin<SubtotalState, 'unitPrice' | 'quantity'> {
    readonly name = 'subtotal' as const;
    readonly dependencies = ['unitPrice', 'quantity'] as const;
    
    initialize() { return { value: 0 }; }
    
    update(_state, _value, _delta, deps) {
      const unitPrice = deps.unitPrice as number;
      const quantity = deps.quantity as number;
      return { value: unitPrice * quantity };
    }
    
    resolve(state) { return state.value; }
  }(),
  
  // More plugins...
});

// Resolve all entities
const results = resolver.resolve();
console.log(results);

// Or resolve a single entity
const order = resolver.resolveEntity('order-123');
console.log(order);

Best Practices

1. Reuse Instances: Create a single resolver instance and reuse it
2. Minimize Dependencies: Keep the dependency graph simple and acyclic
3. Error Handling: Always handle potential errors in plugin implementations
4. Performance: Be mindful of plugin complexity in hot code paths

Related

• ResolverPlugin Interface
• Creating Custom Plugins
• Dependency Resolution