Advanced

Set observation

How rs-x tracks Set membership changes and emits updates keyed by the changed member value.

Detailed notes

SetObserverProxyPairFactory has priority 1 and applies to Set instances.
SetProxyFactory is keyed by the raw Set instance for one shared observer/proxy pair.
SetProxy intercepts add, delete, clear, and has; add/delete/clear produce change notifications.
Each emission uses the set member as the index key in the change chain.
Collection-item property observers can then subscribe to one member key and react when membership changes.
Dispose unregisters the set from proxy registry.

Step 1: choose Set factory and create root observer

Code links: SetObserverProxyPairFactory

Set factory match

Full implementation of the set observer/proxy pair factory.

@Injectable()
export class SetObserverProxyPairFactory
  extends AbstractObjectObserverProxyPairFactory<Set<unknown>>
{
  constructor(
    @Inject(RsXStateManagerInjectionTokens.ISetProxyFactory)
    private readonly _setProxyFactory: ISetProxyFactory,
    @Inject(RsXCoreInjectionTokens.IErrorLog)
    errorLog: IErrorLog,
    @Inject(RsXCoreInjectionTokens.ISetKeyAccessor)
    setKeyAccessor: ISetKeyAccessor,
    @Inject(
      RsXStateManagerInjectionTokens.IObjectPropertyObserverProxyPairManager,
    )
    objectPropertyObserverProxyPairManager: IObjectPropertyObserverProxyPairManager,
  ) {
    super(
      1,
      true,
      errorLog,
      setKeyAccessor,
      objectPropertyObserverProxyPairManager,

Root observer creation

The root observer/proxy pair is created by SetProxyFactory.

protected override createRootObserver(
  data: IProxyTarget<Set<unknown>>,
): ISetObserverProxyPair {
  return this._setProxyFactory.create({
    set: data.target,
  }).instance;
}

Step 2: create or reuse per Set instance

Code links: SetProxyFactory

Set id strategy

SetProxyFactory uses the set object as id.

public override getId(data: ISetProxifyIdData): Set<unknown> {
  return data.set;
}

protected override createId(data: ISetProxifyIdData): Set<unknown> {
  return data.set;
}

Owner release path

Full implementation of SetProxyFactory.

@Injectable()
export class SetProxyFactory
  extends KeyedInstanceFactory<
    Set<unknown>,
    ISetProxifyData,
    ISetObserverProxyPair,
    ISetProxifyIdData
  >
  implements ISetProxyFactory
{
  constructor(
    @Inject(RsXCoreInjectionTokens.IProxyRegistry)
    private readonly _proxyRegistry: IProxyRegistry,
  ) {
    super();
  }

  public override getId(data: ISetProxifyIdData): Set<unknown> {
    return data.set;
  }

  protected override createId(data: ISetProxifyIdData): Set<unknown> {

Step 3: intercept membership operations

Code links: SetProxy

get trap for Set APIs

SetProxy routes mutating methods through custom handlers and binds other methods to the original set.

public get(originalSet: Set<unknown>, property: PropertyKey): unknown {
  const target = originalSet as unknown as Record<PropertyKey, unknown>;

  if (property !== 'constructor' && property in this.updateSet) {
    return (...args: unknown[]) =>
      (this.updateSet as Record<PropertyKey, Function>)[property](
        originalSet,
        ...args,
      );
  }

  const value = target[property];
  return typeof value === 'function'
    ? (value as Function).bind(originalSet)
    : value;
}

add/delete/clear behavior

add emits new member value; delete emits undefined for that member; clear iterates all values.

private addSet = (originalSet: Set<unknown>, ...args: unknown[]) => {
  originalSet.add(args[0]);
  this.emitValueChange(originalSet, args[0], args[0]);
  return this.target;
};

private deleteSet = (originalSet: Set<unknown>, ...args: unknown[]) => {
  const result = originalSet.delete(args[0]);
  this.emitValueChange(originalSet, args[0], undefined);
  return result;
};

Step 4: emit Set member change payloads

Code links: SetProxy + CollectionItemObserverManager

Change payload shape

Set emissions use the member id as index in chain and index fields.

private emitValueChange(
  originalSet: Set<unknown>,
  id: unknown,
  value: unknown,
): void {
  this.emitChange({
    arguments: [],
    chain: [{ context: originalSet, index: id }],
    index: id,
    target: originalSet,
    newValue: value,
  });
}

Collection-level observers

CollectionItemObserverManager listens to these member-keyed events and forwards only matching indexes.

private onChanged = (change: IPropertyChange) => {
  if (change.index !== this.id) {
    return;
  }

  if (!this._indexValueAccessor.hasValue(this.target, this.id)) {
    this.value = undefined;
    this.emitChange(change);
    return;
  }

  if (!this._equalityService.isEqual(this.value, change.newValue)) {
    this.value = change.newValue;
    this.emitChange(change);
  }
};

Step 5: cleanup Set observer resources

Code links: PromiseProxyFactory

Proxy disposal

Dispose unregisters raw set/proxy mapping.

protected override disposeInternal(): void {
  this._proxyRegistry.unregister(this.value);
}

Factory release

Release path disposes the observer instance.

protected override releaseInstance(
  setObserverWithProxy: ISetObserverProxyPair,
): void {
  setObserverWithProxy.observer.dispose();
}