Advanced

Array observation

How rs-x instruments arrays with a proxy that intercepts mutations and emits index-based changes.

Detailed notes

ArrayObserverProxyPairFactory has priority 5 and applies to Array targets.
ObjectObserverProxyPairFactoryProvider sorts factories by priority, so array handling is selected before promise/observable/map/set.
ArrayProxyFactory is keyed by the raw array instance, so repeated observation requests reuse one proxy+observer pair.
ArrayProxy intercepts push, splice, pop, shift, unshift, reverse, sort, fill, direct index writes, and length shrink.
Each changed slot emits an IPropertyChange with chain context=index for precise downstream updates.
Dispose unregisters the raw array from proxy registry and releases proxy references.

Step 1: select array object observer factory

Code links: ArrayObserverProxyPairFactory · ObjectObserverProxyPairFactoryProvider

Factory priority and applies

Full implementation of the array observer/proxy pair factory.

@Injectable()
export class ArrayObserverProxyPairFactory
  extends AbstractObjectObserverProxyPairFactory<unknown[]>
{
  constructor(
    @Inject(RsXStateManagerInjectionTokens.IArrayProxyFactory)
    private readonly _arrayProxyFactory: IArrayProxyFactory,
    @Inject(RsXCoreInjectionTokens.IErrorLog)
    errorLog: IErrorLog,
    @Inject(RsXCoreInjectionTokens.IArrayIndexAccessor)
    arrayIndexAccessor: IArrayIndexAccessor,
    @Inject(
      RsXStateManagerInjectionTokens.IObjectPropertyObserverProxyPairManager,
    )
    objectPropertyObserverProxyPairManager: IObjectPropertyObserverProxyPairManager,
  ) {
    super(
      5,
      true,
      errorLog,
      arrayIndexAccessor,
      objectPropertyObserverProxyPairManager,

Provider sorting

Factories are sorted descending by priority before matching.

this.factories = [...factories].sort((a, b) => b.priority - a.priority);

Step 2: create or reuse one proxy pair per array

Code links: ArrayProxyFactory

Root observer creation

ArrayObserverProxyPairFactory delegates root creation to ArrayProxyFactory.

protected override createRootObserver(
  data: IProxyTarget<unknown[]>,
): IArrayObserverProxyPair {
  return this._arrayProxyFactory.create({
    array: data.target,
  }).instance;
}

Factory id and lifecycle owner

Full implementation of ArrayProxyFactory.

@Injectable()
export class ArrayProxyFactory
  extends KeyedInstanceFactory<
    unknown[],
    IArrayProxyData,
    IArrayObserverProxyPair,
    IArrayProxyIdData
  >
  implements IArrayProxyFactory
{
  constructor(
    @Inject(RsXCoreInjectionTokens.IProxyRegistry)
    private readonly _proxyRegistry: IProxyRegistry,
  ) {
    super();
  }

  public override getId(data: IArrayProxyIdData): unknown[] {
    return data.array;
  }

  protected override createId(data: IArrayProxyIdData): unknown[] {

Step 3: intercept array mutation APIs

Code links: ArrayProxy

Method interception in get trap

Mutating methods are routed through internal handlers so rs-x can emit affected indexes.

public get(
  originalArray: unknown[],
  property: PropertyKey,
  receiver: unknown,
): unknown {
  if (this.isUpdateArrayKey(property)) {
    return (...args: unknown[]) => {
      return this.updateArray[property](originalArray, ...args);
    };
  }

  return Reflect.get(originalArray, property, receiver);
}

Direct index and length writes

The set trap handles numeric indexes and length shrink while avoiding recursive patch loops.

public set(
  originalArray: unknown[],
  property: PropertyKey,
  value: unknown,
  receiver: unknown,
): boolean {
  if (!this._patching) {
    if (property === 'length') {
      this.setLength(originalArray, value as number);
    } else if (Type.isPositiveInteger(property)) {
      const index = Number(property);
      originalArray[index] = value;
      this.emitSet(originalArray, index, value);
    } else {
      Reflect.set(originalArray, property, value, receiver);
    }
  }
  return true;
}

Step 4: emit index-level change payloads

Code links: ArrayProxy

Single index emission

Every changed slot emits a chain part pointing to that array index.

private emitSet(
  originaArray: unknown[],
  index: number,
  value?: unknown,
): void {
  this.emitChange({
    arguments: [],
    chain: [{ context: originaArray, index: index }],
    index: index,
    target: originaArray,
    newValue: value,
  });
}

Range emission helpers

Operations such as shift/unshift/reverse/sort/fill emit full affected ranges.

private emitSetForRange(
  originaArray: unknown[],
  startIndex: number,
  length: number,
): void {
  const endIndex = startIndex + length;
  for (let i = startIndex; i < endIndex; i++) {
    this.emitSet(originaArray, i, originaArray[i]);
  }
}

Step 5: release and unregister proxy

Code links: ArrayProxyFactory

ArrayProxy dispose path

Proxy registry mapping is removed and proxy reference is cleared.

protected override disposeInternal(): void {
  this._proxyRegistry.unregister(this.value);
  this.target = Type.cast(undefined);
}

Factory release path

When reference count reaches zero, the observer is disposed.

protected override releaseInstance(
  arrayObserverWithProxy: IArrayObserverProxyPair,
  id: unknown[],
): void {
  super.releaseInstance(arrayObserverWithProxy, id);
  arrayObserverWithProxy.observer.dispose();
}