Advanced

Map observation

How rs-x observes Map mutations per key and emits key-scoped changes for reactive updates.

Detailed notes

MapObserverProxyPairFactory has priority 2 and applies to Map instances.
MapProxyFactory is keyed by the raw Map instance, so one observer/proxy pair is reused per map.
MapProxy intercepts clear, set, and delete while preserving normal method behavior for other members.
Each set/delete emits a change with chain context=index where index is the map key.
clear() emits key-by-key removals through deleteItem so downstream dependencies are updated per key.
Dispose unregisters the map from proxy registry.

Step 1: select the Map factory

Code links: MapObserverProxyPairFactory

Factory registration contract

Full implementation of the map observer/proxy pair factory.

@Injectable()
export class MapObserverProxyPairFactory
  extends AbstractObjectObserverProxyPairFactory<Map<unknown, unknown>>
{
  constructor(
    @Inject(RsXStateManagerInjectionTokens.IMapProxyFactory)
    private readonly _mapProxyFactory: IMapProxyFactory,
    @Inject(RsXCoreInjectionTokens.IErrorLog)
    errorLog: IErrorLog,
    @Inject(RsXCoreInjectionTokens.IMapKeyAccessor)
    mapKeyAccessor: IMapKeyAccessor,
    @Inject(
      RsXStateManagerInjectionTokens.IObjectPropertyObserverProxyPairManager,
    )
    objectPropertyObserverProxyPairManager: IObjectPropertyObserverProxyPairManager,
  ) {
    super(
      2,
      true,
      errorLog,
      mapKeyAccessor,
      objectPropertyObserverProxyPairManager,

Root observer creation

The root observer is the pair returned by MapProxyFactory.

protected override createRootObserver(
  data: IProxyTarget<Map<unknown, unknown>>,
): IMapObserverProxyPair {
  return this._mapProxyFactory.create({
    map: data.target,
  }).instance;
}

Step 2: create or reuse proxy by map id

Code links: MapProxyFactory

Keyed factory id

The map object itself is the key used for reuse.

public override getId(data: IMapProxifyData): Map<unknown, unknown> {
  return data.map;
}

protected override createId(data: IMapProxifyData): Map<unknown, unknown> {
  return data.map;
}

Create observer with release owner

Full implementation of MapProxyFactory.

@Injectable()
export class MapProxyFactory
  extends KeyedInstanceFactory<
    Map<unknown, unknown>,
    IMapProxifyData,
    IMapObserverProxyPair
  >
  implements IMapProxyFactory
{
  constructor(
    @Inject(RsXCoreInjectionTokens.IProxyRegistry)
    private readonly _proxyRegistry: IProxyRegistry,
  ) {
    super();
  }

  public override getId(data: IMapProxifyData): Map<unknown, unknown> {
    return data.map;
  }

  protected override createId(data: IMapProxifyData): Map<unknown, unknown> {
    return data.map;

Step 3: intercept Map mutations

Code links: MapProxy

Method switching in get trap

Mutating methods are wrapped, while get() and other methods keep normal behavior.

public get(
  originalMap: Map<unknown, unknown>,
  property: PropertyKey,
): unknown {
  if (this.isUpdateMapKey(property)) {
    return (...args: unknown[]) => {
      return this.updateMap[property](originalMap, ...args);
    };
  }

  if (property === 'get') {
    return (key: unknown) => originalMap.get(key);
  }

  const mapAny = originalMap as unknown as Record<PropertyKey, unknown>;
  return typeof mapAny[property] === 'function'
    ? (mapAny[property] as Function).bind(originalMap)
    : mapAny[property];
}

set/delete/clear behavior

set emits the new value for that key; clear emits delete for each existing key.

private setMap = (originalMap: Map<unknown, unknown>, ...args: unknown[]) => {
  const key = args[0];
  const value = args[1];
  originalMap.set(key, value);
  this.emitSet(originalMap, key, value);
  return this.target;
};

private clearMap = (originalMap: Map<unknown, unknown>) => {
  for (const key of originalMap.keys()) {
    this.deleteItem(originalMap, key);
  }
};

Step 4: emit key-scoped change payloads

Code links: MapProxy

Map change payload

The key is used as index in both chain and index fields.

private emitSet(
  originalMap: Map<unknown, unknown>,
  key: unknown,
  value?: unknown,
): void {
  this.emitChange({
    arguments: [],
    chain: [{ context: originalMap, index: key }],
    index: key,
    target: originalMap,
    newValue: value,
  });
}

Delete handling

delete emits undefined for removed keys and returns false when key was absent.

private deleteItem(
  originalMap: Map<unknown, unknown>,
  key: unknown,
): boolean {
  const item = originalMap.get(key);
  if (item === undefined) {
    return false;
  }

  originalMap.delete(key);
  this.emitSet(originalMap, key);
  return true;
}

Step 5: dispose map observer

Code links: MapProxyFactory

Unregister raw map

MapProxy dispose removes proxy registry mapping.

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

Factory release cleanup

Release path disposes the observer instance.

protected override releaseInstance(
  mapObserverWithProxy: IMapObserverProxyPair,
): void {
  mapObserverWithProxy.observer.dispose();
}