Advanced

Promise observation

How rs-x turns promise resolution into observable state changes using PromiseObserver and PromiseAccessor cache.

Detailed notes

PromiseObserverProxyPairFactory has priority 4 and applies to Promise values.
PromiseProxyFactory is keyed by Promise instance and reuses one PromiseObserver per promise.
No proxy object is created for Promise; observer pair returns proxy: undefined.
PromiseObserver attaches target.then(...) and emits once the promise resolves.
Resolved values are cached in PromiseAccessor through IResolvedValueCache (WeakMap-backed).
PromiseAccessor returns PENDING until resolution cache is available and clears cache on dispose.

Step 1: select Promise object observer factory

Code links: PromiseObserverProxyPairFactory

Factory match

Full implementation of PromiseObserverProxyPairFactory.

@Injectable()
export class PromiseObserverProxyPairFactory
  implements IObjectObserverProxyPairFactory<Promise<unknown>>
{
  public readonly priority = 4;

  constructor(
    @Inject(RsXStateManagerInjectionTokens.IPromiseProxyFactory)
    private readonly _promiseProxyFactory: IPromiseProxyFactory,
  ) {}

  public create(
    owner: IDisposableOwner,
    proxyTarget: IProxyTarget<Promise<unknown>>,
  ): IPromiseObserverProxyPair {
    return this._promiseProxyFactory.create({
      promise: proxyTarget.target,
      owner,
    }).instance;
  }

  public applies(object: unknown): boolean {

Factory id reuse

PromiseProxyFactory key is the promise object itself.

public override getId(data: IPromiseProxyData): Promise<unknown> {
  return data.promise;
}

protected override createId(data: IPromiseProxyData): Promise<unknown> {
  return data.promise;
}

Step 2: create PromiseObserver and attach then()

Code links: PromiseProxyFactory + PromiseObserver

Observer construction

Full implementation of PromiseObserver.

class PromiseObserver extends AbstractObserver<
  Promise<unknown>,
  undefined,
  undefined
> {
  constructor(
    owner: IDisposableOwner,
    target: Promise<unknown>,
    private readonly _promiseAccessor: IPromiseAccessor,
  ) {
    super(owner, target, undefined, new ReplaySubject<IPropertyChange>(1));
    target.then(this.onValueResolved);
  }

  protected override disposeInternal(): void {
    this._promiseAccessor.clearLastValue(this.target);
  }

  private onValueResolved = (newValue: unknown): void => {
    if (this.isDisposed) {
      return;
    }

Observer pair shape

Full implementation of PromiseProxyFactory.

@Injectable()
export class PromiseProxyFactory
  extends KeyedInstanceFactory<
    Promise<unknown>,
    IPromiseProxyData,
    IPromiseObserverProxyPair
  >
  implements IPromiseProxyFactory
{
  constructor(
    @Inject(RsXCoreInjectionTokens.IPromiseAccessor)
    private readonly _promiseAccessor: IPromiseAccessor,
  ) {
    super();
  }

  public override getId(data: IPromiseProxyData): Promise<unknown> {
    return data.promise;
  }

  protected override createId(data: IPromiseProxyData): Promise<unknown> {
    return data.promise;

Step 3: store resolved value and emit change

Code links: PromiseProxyFactory + PromiseObserver · PromiseAccessor

Resolution handler

Resolved value is cached and emitted as an observer change payload.

private onValueResolved = (newValue: unknown): void => {
  if (this.isDisposed) {
    return;
  }

  this._promiseAccessor.setLastValue(this.target, newValue);
  this.emitChange({
    arguments: [],
    chain: [],
    target: this.target,
    newValue,
  });
};

Resolved value cache

PromiseAccessor stores values in IResolvedValueCache (WeakMap-backed).

public setLastValue(promise: Promise<unknown>, value: unknown): void {
  this._resolvedValueCache.set(promise, value);
}

public getResolvedValue(context: unknown, index: string): unknown {
  const val = this.getIndexedValue(context, index);
  return this.isCacheable(val)
    ? (this._resolvedValueCache.get(val) ?? PENDING)
    : PENDING;
}

Step 4: PromiseAccessor read semantics

Code links: PromiseAccessor · ResolvedValueCache

hasValue behavior

hasValue returns true only when cached value exists and is not PENDING.

public hasValue(context: unknown, index: string): boolean {
  const val = this.getIndexedValue(context, index);
  return (
    this.isCacheable(val) && this._resolvedValueCache.get(val) !== PENDING
  );
}

setValue is blocked

PromiseAccessor does not allow direct writes.

public setValue(): void {
  throw new UnsupportedException('Cannot set value for a Promise');
}

Step 5: cleanup Promise observer resources

Code links: PromiseProxyFactory + PromiseObserver

Observer dispose

Disposing PromiseObserver clears cached last value.

protected override disposeInternal(): void {
  this._promiseAccessor.clearLastValue(this.target);
}

Factory release path

On final release the promise observer is disposed.

protected override releaseInstance(
  promiseObserverWithProxy: IPromiseObserverProxyPair,
): void {
  promiseObserverWithProxy.observer.dispose();
}