Get started

rs-x is a reactive expression library for TypeScript. You write a plain string expression — such as 'price * quantity - discount' — bind it to a model object, and get back an IExpression<T> that always holds the current computed value. Whenever any tracked dependency on the model changes, the expression re-evaluates and fires a changed event.

Dependencies are tracked automatically — you do not declare them up front. rs-x wraps values in observer proxies and detects mutations as they happen, whether those mutations come from a direct property assignment, an array push, a resolved Promise, or an RxJS Observable emission.

Expressions are composable: an expression value can itself be a model field, a collection item, a function return value, or another expression. The whole dependency graph updates incrementally — only the nodes affected by a mutation are re-evaluated.

rs-x works with any JavaScript framework. Official integration guides are available for:

• React — bind expressions to component state and re-render on changed using a custom hook.
• Angular — integrate with Angular's change detection by triggering ChangeDetectorRef.markForCheck inside a changed subscription.

1. Install: add @rs-x/core, @rs-x/state-manager, @rs-x/expression-parser, and rxjs.
2. Bootstrap once: load RsXExpressionParserModule into InjectionContainer at app startup.
3. Bind + observe: create with rsx(...)(model), read value, subscribe to changed.
4. Clean up: call expression.dispose() when the expression is no longer needed.

rs-x is split into three focused packages so you can take only what you need:

• @rs-x/core — foundational contracts, the Inversify-based InjectionContainer, utility types, and helpers such as WaitForEvent and printValue. Every other rs-x package depends on core.
• @rs-x/state-manager — tracks mutations on plain objects, arrays, Maps, Sets, Dates, Promises, and Observables by wrapping values in transparent observer proxies. The StateManager service stores the current value for each watched (context, index) pair and emits IStateChange events. Used internally by the expression parser.
• @rs-x/expression-parser — parses expression strings into an AST, resolves identifiers against the model via StateManager, and produces live IExpression<T> instances. The entrypoint is rsx(); the module is RsXExpressionParserModule.
• rxjs — peer dependency. Observable values in expressions are resolved using RxJS Observable. The changed stream on every expression is also an RxJS Observable.

# npm
npm install @rs-x/core @rs-x/state-manager @rs-x/expression-parser rxjs

# pnpm
pnpm add @rs-x/core @rs-x/state-manager @rs-x/expression-parser rxjs

# yarn
yarn add @rs-x/core @rs-x/state-manager @rs-x/expression-parser rxjs

# bun
bun add @rs-x/core @rs-x/state-manager @rs-x/expression-parser rxjs

{
  "name": "my-rsx-app",
  "private": true,
  "type": "module",
  "dependencies": {
    "@rs-x/core": "latest",
    "@rs-x/state-manager": "latest",
    "@rs-x/expression-parser": "latest",
    "rxjs": "^7.8.2"
  }
}

import { InjectionContainer } from '@rs-x/core';
import { RsXExpressionParserModule } from '@rs-x/expression-parser';

// App startup: load once
await InjectionContainer.load(RsXExpressionParserModule);

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true
  }
}

Every expression goes through three phases:

• Create — rsx<T>('expr')(model) parses the expression string, resolves each identifier against the model, registers watchers with StateManager, and returns an IExpression<T>. The value property is populated immediately — no need to wait for a change event.
• Observe — subscribe to expression.changed (an RxJS Observable) to react to re-evaluations. The callback fires synchronously for plain property mutations and asynchronously for Promises and Observables. Always read the latest value from expression.value inside the handler — the change event itself does not carry the new value.
• Clean up — call expression.dispose() when the expression is no longer needed. This releases all StateManager watchers and RxJS subscriptions. Forgetting to dispose is the most common source of memory leaks.

// 1. Create — parse the expression and bind it to the model.
//    expression.value is available immediately.
const expression = rsx<number>('a * b')(model);

// 2. Observe — subscribe to the changed stream.
//    Fires synchronously for plain-property mutations,
//    asynchronously for Promises and Observables.
const subscription = expression.changed.subscribe(() => {
  console.log(expression.value);
});

// 3. Clean up — call dispose() to release all watchers.
//    Always dispose expressions you no longer need to
//    prevent memory leaks.
expression.dispose();