Advanced

Modular expression implementation

rs-x is a highly extendable framework: you can add support for custom data types without rewriting the runtime core. Modular expression support was added in exactly that way, by introducing a focused plugin set for the Expression value type.

Detailed notes

rs-x was built to be extended and adaptable. It has extension points for value access, value metadata, observer factories, and deep-clone value handling, so we can add a new value type without changing the runtime core.
First, ExpressionMetadata tells the runtime that AbstractExpression is a supported value type and that it should be handled as async/proxy-aware.
Next, ExpressionIndexAccessor defines how expression members are read (`expression.value`) and intentionally blocks direct `setValue` writes.
Then, ExpressionObserverFactory provides one reusable observer per expression and forwards `expression.changed` events into state-manager change events.
After that, ExpressionObserverProxyPairFactory connects expression objects to the observer pipeline by handling values that are `AbstractExpression` instances and delegating observer creation to `IExpressionObserverFactory`.
Finally, DeepCloneExceptWithExpressionSupport makes clone/evaluation paths unwrap `expression.value` (or `PENDING` when unresolved), so modular expressions compose correctly with other values.
Result: modular expressions behave like a native runtime value type and participate fully in tracking, observation, and evaluation flows.

Step 1: ExpressionMetadata

Plugin implementation

@Injectable()
export class ExpressionMetadata implements IValueMetadata {
  public readonly priority = 300;

  public isAsync(): boolean {
    return true;
  }

  public needsProxy(): boolean {
    return true;
  }

  public applies(value: unknown): boolean {
    return value instanceof AbstractExpression;
  }
}

Module registration

overrideMultiInjectServices(
  options,
  RsXCoreInjectionTokens.IValueMetadataList,
  [
    {
      target: ExpressionMetadata,
      token: RsXExpressionParserInjectionTokens.ExpressiomMetadata,
    },
    ...defaultValueMetadataList,
  ],
);

Step 2: ExpressionIndexAccessor

Plugin implementation

@Injectable()
export class ExpressionIndexAccessor implements IExpressionIndexAccessor {
  public readonly priority!: 300;

  public getResolvedValue(context: unknown, index: string): unknown {
    return Type.cast<IExpression>((Type.toObject(context) ?? {})[index])?.value;
  }

  public hasValue(context: unknown, index: string): boolean {
    return Type.cast<IExpression>((Type.toObject(context) ?? {})[index])?.value !== undefined;
  }

  public getValue(context: unknown, index: string): unknown {
    return (Type.toObject(context) ?? {})[index];
  }

  public setValue(): void {
    throw new UnsupportedException(
      'Cannot set the value of an expression directly. To update it, modify the relevant properties in the expression context.',
    );
  }

Module registration

overrideMultiInjectServices(
  options,
  RsXCoreInjectionTokens.IIndexValueAccessorList,
  [
    {
      target: ExpressionIndexAccessor,
      token: RsXExpressionParserInjectionTokens.IExpressionIndexAccessor,
    },
    ...defaultIndexValueAccessorList,
  ],
);

Step 3: IExpressionObserverFactory

Factory contract

export interface IExpressionObserverData {
  owner?: IDisposableOwner;
  expression: AbstractExpression;
}

export type IExpressionObserverFactory = IKeyedInstanceFactory<
  AbstractExpression,
  IExpressionObserverData,
  IObserver
>;

Implementation details

@Injectable()
export class ExpressionObserverFactory
  extends KeyedInstanceFactory<
    AbstractExpression,
    IExpressionObserverData,
    IObserver
  >
  implements IExpressionObserverFactory
{
  public override getId(data: IExpressionObserverData): AbstractExpression {
    return data.expression;
  }

  protected override createId(data: IExpressionObserverData): AbstractExpression {
    return data.expression;
  }

  protected override createInstance(
    data: IExpressionObserverData,
    id: AbstractExpression,
  ): IObserver {
    return new ExpressionObserver(

ExpressionObserver implementation

class ExpressionObserver extends AbstractObserver<
  AbstractExpression,
  undefined,
  undefined
> {
  private readonly _changedSubsctiption: Subscription;

  constructor(owner: IDisposableOwner, target: AbstractExpression) {
    super(owner, target, undefined, new ReplaySubject<IPropertyChange>(1));
    this._changedSubsctiption = target.changed.subscribe(
      this.onExpressionChanged,
    );
  }

  protected override disposeInternal(): void {
    this._changedSubsctiption.unsubscribe();
  }

  private onExpressionChanged = (expression: IExpression): void => {
    this.emitChange({
      arguments: [],
      chain: [],

DI registration

options
  .bind<IExpressionObserverFactory>(
    RsXExpressionParserInjectionTokens.IExpressionObserverFactory,
  )
  .to(ExpressionObserverFactory)
  .inSingletonScope();

Step 4: ExpressionObserverProxyPairFactory

Factory contract

export type IExpressionObserverProxyPairFactory =
  IObjectObserverProxyPairFactory<AbstractExpression>;

Plugin implementation

@Injectable()
export class ExpressionObserverProxyPairFactory implements IExpressionObserverProxyPairFactory {
  public readonly priority = 100;

  constructor(
    @Inject(RsXExpressionParserInjectionTokens.IExpressionObserverFactory)
    private readonly _expressionObserverFactory: IExpressionObserverFactory,
  ) {}

  public create(
    owner: IDisposableOwner,
    proxyTarget: IProxyTarget<AbstractExpression>,
  ): IExpressionObserverProxyPair {
    return {
      observer: this._expressionObserverFactory.create({
        owner,
        expression: proxyTarget.target,
      }).instance,
    };
  }

  public applies(object: unknown): boolean {

Module registration

overrideMultiInjectServices(
  options,
  RsXStateManagerInjectionTokens.IObjectObserverProxyPairFactoryList,
  [
    {
      target: ExpressionObserverProxyPairFactory,
      token:
        RsXExpressionParserInjectionTokens.IExpressionObserverProxyPairFactory,
    },
    ...defaultObjectObserverProxyPairFactoryList,
  ],
);

Step 5: deep-clone support

Deep clone plugin implementation

@Injectable()
export class DeepCloneExceptWithExpressionSupport implements IDeepCloneExcept {
  constructor(
    @Inject(RsXCoreInjectionTokens.IDeepCloneExcept)
    private readonly _defaultDeepCloneValueGetter: IDeepCloneExcept,
  ) {}

  public except(source: unknown): unknown {
    if (source instanceof AbstractExpression) {
      return source.value === undefined ? PENDING : source.value;
    }

    return this._defaultDeepCloneValueGetter.except(source);
  }
}

Deep clone module wiring

options.unbind(RsXCoreInjectionTokens.DefaultDeepCloneExcept);
options
  .bind<IDeepCloneExcept>(RsXCoreInjectionTokens.DefaultDeepCloneExcept)
  .to(DeepCloneExceptWithExpressionSupport)
  .inSingletonScope();