Advanced

Plain object property observation

How rs-x tracks plain object fields with descriptor patching, nested value proxying, and lifecycle-safe teardown.

Detailed notes

NonIterableObjectPropertyObserverProxyPairFactory is selected for non-collection, non-Date, non-method string properties.
This factory extends IndexObserverProxyPairFactory, so it can observe the property value itself and also rebind nested observers when the value changes.
Descriptor patching is done by ObjectPropertyObserverManager through PropertObserver, with different behavior for fields, methods, and writable accessors.
Readonly accessor-only properties are rejected and throw InvalidOperationException.
Emitted changes include chain + setValue so state can propagate and rebind cleanly.
On dispose, the original descriptor is restored and proxied values are unwrapped back to raw targets.

Step 1: choose the plain-object property factory

Code links: NonIterableObjectPropertyObserverProxyPairFactory · RsXStateManagerModule

Factory registration

The factory is part of the property observer factory list used by state-manager.

export const defaultPropertyObserverProxyPairFactoryList = [
  {
    target: NonIterableObjectPropertyObserverProxyPairFactory,
    token:
      RsXStateManagerInjectionTokens.NonIterableObjectPropertyObserverProxyPairFactory,
  },
  {
    target: CollectionItemObserverProxyPairFactory,
    token:
      RsXStateManagerInjectionTokens.ICollectionItemObserverProxyPairFactory,
  },
  {
    target: DatePropertyObserverProxyPairFactory,
    token:
      RsXStateManagerInjectionTokens.IDatePropertyObserverProxyPairFactory,
  },
];

Selection rule

Full implementation of the plain-object property observer factory.

@Injectable()
export class NonIterableObjectPropertyObserverProxyPairFactory extends IndexObserverProxyPairFactory<
  object,
  string
> {
  constructor(
    @Inject(RsXStateManagerInjectionTokens.IObjectObserverProxyPairManager)
    objectObserveryManager: IObjectObserverProxyPairManager,
    @Inject(RsXStateManagerInjectionTokens.IObjectPropertyObserverManager)
    objectPropertyObserverManager: IObjectPropertyObserverManager,
    @Inject(RsXCoreInjectionTokens.IErrorLog)
    errorLog: IErrorLog,
    @Inject(RsXCoreInjectionTokens.IGuidFactory)
    guidFactory: IGuidFactory,
    @Inject(RsXCoreInjectionTokens.IIndexValueAccessor)
    indexValueAccessor: IIndexValueAccessor,
    @Inject(RsXCoreInjectionTokens.IProxyRegistry)
    proxyRegister: IProxyRegistry,
    @Inject(RsXCoreInjectionTokens.IValueMetadata)
    valueMetadata: IValueMetadata,
  ) {
    super(

Step 2: create observer group for one property

Code links: IndexObserverProxyPairFactory

IndexObserverProxyPairFactory pipeline

The base factory checks if the property value needs nested observation (async or watched index), then creates a group observer for the property.

const valueAtIndex = this._indexValueAccessor.getValue(object, index);
const needProxy =
  this._valueMetadata.isAsync(valueAtIndex) ||
  propertyInfo.indexWatchRule?.test?.(index, object);

const indexValueObserverProxyPair = needProxy
  ? this.createIndexValueProxy(
      propertyInfo,
      object,
      index,
      valueAtIndex,
      propertyInfo.indexWatchRule,
    )
  : undefined;

Nested value proxying

If a nested proxy is created, rs-x writes the proxy back into the property so later reads stay reactive.

const observerProxyPair = this._objectObserveryManager.create({
  target,
  indexWatchRule,
  initializeManually,
}).instance;

if (observerProxyPair.proxy !== undefined) {
  setValue(observerProxyPair.proxy);
}

Step 3: patch property descriptor and emit changes

Code links: ObjectPropertyObserverManager

Patch behavior by descriptor type

PropertObserver patches the property once and chooses function/field/writable-accessor behavior.

if (descriptorWithTarget.type === PropertyDescriptorType.Function) {
  newDescriptor =
    this.createFunctionPropertyDescriptor(descriptorWithTarget);
} else if (!descriptor.get && !descriptor.set) {
  newDescriptor = this.createFieldPropertyDescriptor(descriptorWithTarget);
} else if (descriptor.set) {
  newDescriptor =
    this.createWritablePropertyDescriptor(descriptorWithTarget);
} else {
  throw new InvalidOperationException(
    `Property '${propertyName}' can not be watched because it is readonly`,
  );
}

Emit payload structure

Each property change includes chain, index, and setValue so downstream handlers can rebind nested state.

super.emitChange({
  arguments: [],
  ...change,
  chain: [{ context: this.target, index: this.id }],
  target: this.target,
  index: id,
  setValue: this.setValue,
});

Step 4: rebind nested observers when value changes

Code links: IndexObserverProxyPairFactory

Handle index update

When the property value changes, rs-x decides whether to emit immediately and whether a new nested observer chain is needed.

const isAsync = this._valueMetadata.isAsync(change.newValue);
const emitValue = Type.isNullOrUndefined(change.newValue) || !isAsync;

if (emitValue) {
  observerGroup.emitValue(change.newValue);
}

const observers = this.getNestedObservers(change, isAsync, indexWatchRule);
observerGroup.replaceObservers(observers);

Nested observer trigger

Nested observer creation is re-run when the new value is async or when the watch rule says the index must stay observed.

if (
  isAsync ||
  (indexWatchRule && indexWatchRule.test(change.index, change.target))
) {
  const observerProxyPair = this.proxifyIndexValue(
    change.newValue,
    indexWatchRule as IIndexWatchRule,
    true,
    change.setValue ??
      ((value: unknown) => {
        const obj = Type.toObject(change.target);
        if (obj) {
          obj[change.index as string] = value;
        }
      }),
  );
}

Step 5: teardown and descriptor restore

Code links: ObjectPropertyObserverManager

Restore original descriptor

On final release, the patched descriptor is removed and the original descriptor is restored.

delete object[propertyName];
Object.defineProperty(
  this.target,
  propertyName,
  Type.cast(this._propertyDescriptorWithTarget?.descriptor),
);

Unwrap proxied field values

For non-function properties, rs-x writes back the raw value from proxy registry before completing dispose.

if (
  this._propertyDescriptorWithTarget?.type !==
  PropertyDescriptorType.Function
) {
  object[propertyName] = this._proxyRegister.getProxyTarget(value) ?? value;
}