ReactiveX/rxjs
github.com/ReactiveX/rxjs ↗ · 1360 files · 10.6 MB
RxJS RxJS is a library for composing asynchronous and event-based programs with Observable values.
Overview
RxJS Next is the platform-based RxJS 9 prerelease foundation for developers composing asynchronous and event-driven programs. It preserves an existing realm Observable, supplies a conditional fallback, and installs reactive capabilities through imported Symbols, with explicit producer-per-subscription APIs where needed. The monorepo also contains virtual-time testing, bounded RxJS 7 migration tooling, release qualification infrastructure, and a separately maintained Angular documentation application.
System map
The runtime centers on the active realm's Observable rather than an RxJS-owned replacement constructor. Four versioned packages separate fallback acquisition, reactive extensions, testing, and migration. The documentation application remains on an older Angular/RxJS stack, while package distribution and publication follow an ESM and local-release model.
- The workspace uses pnpm 10.34.5, requires Node >=22.13.0 at the root, and includes packages/* plus apps/rxjs.dev.
- The architecture separates platform acquisition, Symbol extensions, and migration tooling; migration tooling is not a runtime dependency.
- The rxjs root imports the fallback initializer and exports core classes, subject factories, notifications, and errors without exporting the operator catalog.
- rxjs depends on @rxjs/observable-polyfill; @rxjs/test declares rxjs as a peer; @rxjs/migrate uses TypeScript and Zod for tooling.
- The fallback publishes one ESM implementation for browser, webpack, import, and require conditions; package builds use tshy followed by ESM finalization.
- apps/rxjs.dev uses Angular 13 and RxJS ^7.5.1, with Angular build/test, Dgeni documentation generation, marble generation, and a Firebase deployment script.
- Observed state owners include fallback WeakRef subscription state, Subject subscriber Sets, document caches, and a worker search index; these are in-memory structures.
- release:beta packs four packages in supporting-package-first order, performs publication dry runs, requires exact-version confirmation, then verifies registry integrity and tags.
Feature catalog
The inspected public surface covers Observable conversion and cancellation, Symbol operators, mutable producers, replay, and async consumption. Testing and migration are separate developer-facing products with explicit lifecycle choices. The legacy site provides documentation rendering, search, and lazy embedded components; this catalog is bounded rather than an exhaustive API enumeration.
- Observable.from accepts existing Observables, async iterables, sync iterables, and thenables in that precedence order, rejecting unsupported values.
- source[map](project) projects values with a subscription-local index; importing rxjs/map installs an exact Symbol property on Observable.prototype.
- source[switchMap](mapper, {concurrent}) defaults to one active inner and aborts the oldest active inner when capacity is reached.
- ColdObservable creates an independent producer for every direct subscribe; Subject exposes next/error/complete fanout and a read-only Observable view.
- replaySubject supports size and maxAge limits, replays buffered values to subscribers, and follows replay with stored completion or error.
- iterateBufferedValues provides lazy async iteration over accumulated value batches; generator closure aborts its observer, and accepted buffers precede terminal delivery.
- rxTest offers cold, hot, and platform marble sources, message/subscription assertions, scheduling, animation/idle plans, and manual virtual-time advancement.
- rxjs-migrate supports dry-run or explicit writes with cold/platform and framework options; rxjs-migrate-skill supports check/install/update/remove for Codex, Claude, and Cursor.
Data flow
Runtime values enter through producer callbacks or platform conversion and move through derived Subscribers. AbortSignals carry ownership upstream, while construction hooks preserve the selected lifecycle. Tooling transforms source into planned file outputs, and the documentation app moves generated JSON through caches, worker indexing, and DOM rendering.
- subscribe wraps the observer in SafeObserver, joins or creates the weakly referenced Subscriber, attaches cancellation, and invokes the producer only for a new activation.
- Subscriber.next snapshots observers for fanout; complete closes first, then notifies the snapshot; closure aborts its signal and runs teardowns in reverse order.
- map constructs through receiver[create]; createImpl selects the receiver's instance constructor or static constructor instead of hardcoding one output type.
- subscribeToSource forwards unspecified notifications, converts override exceptions into downstream errors, and combines inner cancellation with the downstream signal.
- Migration source passes through semantic rewriting, optional framework adaptation, provenance insertion, sorted diagnostics, and import deduplication into MigrationResult.
- planMigrationFiles reads canonical source paths, chooses output names, attaches repository/SHA/path provenance, and returns transformed files; applyMigrationPlan writes those exact code strings.
- DocumentService maps location.currentPath to cached document streams, fetches generated/docs/<id>.json into AsyncSubject, and deletes failed non-404 cache entries.
- Search initialization loads generated search JSON into a Lunr index and pageMap; query-index messages return query results correlated by message type and id.
Behavior traces
The source investigation followed initialization, operator execution, cancellation, and migration output end-to-end. Additional traces cover independent producers, virtual-time cleanup, document rendering, and worker search. These are source-derived execution orders, not recorded runtime executions.
- Initialization: importing rxjs reaches the fallback initializer → initializeObservablePolyfill checks globalThis.Observable → prepares fallback/abort properties only when absent → fills missing EventTarget.when → installs prepared properties.
- Projection: importing map loads create and subscription helpers → installs Observable.prototype[map] → mapOperator calls this[create] → subscription starts subscribeToSource → project(value,index++) feeds subscriber.next.
- Cancellation: observer AbortSignal invokes removeObserver → the final observer triggers closeSubscriber → the producer signal aborts → observer state clears → teardown callbacks run last-in-first-out.
- Independent producer: ColdObservable.subscribe creates ColdSubscriber → invokes its stored init; Symbol composition uses its [create] override, while string map wraps through #asPlatformObservable.
- Migration output: runCli parses/validates arguments → createMigrationCliReport plans files → migrateTestSource performs rewrites → any refused result prevents writes → otherwise applyMigrationPlan preflights and writes → CLI emits JSON and an exit code.
- Virtual test: rxTest queues behind a realm lock → executeRxTest verifies Observable and installs virtual time → runs callback until settled → checks expectations/open work → restores the realm → releases the queue.
- Documentation: currentPath → getDocument → fetchDocument/AsyncSubject → DocViewer doc setter → render → assign contents → prepare title/TOC → load contained elements → swapViews → docRendered.
- Search: initWorker races delay against first query → creates Worker/WebWorkerClient → sends load-index → worker XHR builds index → search waits on ready → query-index returns a correlated response inside NgZone.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted by this report. Evidence spans Vitest source tests, classified ported suites, Node package/tooling checks, browser contracts, and pinned WPT. The inspected coverage is bounded, and the legacy site's tests and native-mode fallback behavior require separate interpretation.
- Source tests use Vitest; inspected extension-kernel tests assert assignment descriptors, non-global public Symbols, preserved platform methods, and absence of RxJS string additions.
- The fast-check lifecycle property generates subscribe/abort/next/complete/error actions and checks fanout, activation/teardown accounting, and cleanup; RXJS_FUZZ_RUNS defaults to 200.
- @rxjs/test fixtures distinguish independent cold timelines, shared platform timelines, absolute hot timelines, construction policy, and virtualized timers/clocks.
- Migration file tests cover exact planned output, omitted lifecycle refusal, lexical traversal, escaping symlinks, duplicate canonical paths, and batch preflight behavior.
- Ported Vitest runs select cold or platform suites and disable file parallelism; native mode without a global Observable selects native-unavailable.spec.ts rather than exercising native behavior.
- Main CI runs package gates on Node 22.13.0 and 24, makes Node 26 advisory, and separately checks exact cold/polyfill audit baselines.
- Observable WPT pins revision 6a009d73f0d315941b90cac13a9523a2a08c631b and Chrome 150; CI verifies imports and runs lifecycle/kernel/conformance checks, with latest Chrome scheduled as advisory.
- Release readiness defines browser, Webpack, performance, packed adoption, Deno/Bun, and desktop/iOS Safari gates; the documentation app separately configures Jasmine/Karma with Chrome.
Risk map
These risks are source observations or explicitly labeled hypotheses, not confirmed vulnerabilities. The broadest runtime effects come from realm patching, construction policy, and unbounded buffering. Security-sensitive tooling includes file writes, npm publication, privileged rebasing, and documentation HTML ingestion; static inspection also found a stale scheduled test command.
- Fallback initialization replaces AbortController.prototype.abort to emulate abort algorithms before public events, so installation has realm-wide effects beyond Observable itself.
- Existing Observable values are preserved without conformance probing; public capability installation uses direct assignment with no common preflight or rollback, leaving hardened-realm initialization outside a transactional guarantee.
- Buffered async iteration is explicitly unbounded, and replaySubject defaults both size and maxAge to Infinity; consumers must choose retention limits where producer volume requires them.
- Hypothesis: migration application is vulnerable to partial output on an operational failure or filesystem change after preflight, because files are written sequentially without a batch rollback or atomic per-file replacement. (inferred)
- DocViewer assigns generated contents directly to innerHTML under an explicit documentation-author trust assumption; this is a content trust boundary, not evidence of exploitable injection.
- Publication executes npm against local tarballs and verifies integrity after publishing; guards reject CI, NPM_TOKEN/NODE_AUTH_TOKEN, and noninteractive terminals, but the architecture explicitly trusts the maintainer machine and npm account.
- The scheduled fuzz workflow still invokes removed release-policy test filenames, while the project log records removal of those scripts; its current command is stale despite retaining the lifecycle fuzz step.
- The rebase workflow grants contents:write for issue comments containing /rebase; separately, the documentation vulnerability backlog records time-limited exceptions, so automation authority and dependency exceptions need their own review.
Extension points
The central extension mechanism is an imported exact Symbol plus ambient TypeScript augmentation. A shared construction protocol supports subclasses and compatible duplicate installations, while connector factories customize stateful operators. Migration registries/adapters and the documentation element registry provide separate tooling and UI seams.
- A capability module exports a unique Symbol, augments Observable<T>, implements the operator, and assigns its function to Observable.prototype under that Symbol.
- The create protocol is registered as rxjs.kernel.create.v1, installed on constructor and prototype, accepts an existing callable slot, and rejects an occupied noncallable slot.
- Subclass construction is customized through an instance [create] override: ColdObservable returns ColdObservable, while Subject intentionally returns the selected platform base.
- share accepts a connector factory and independent error, completion, and zero-refcount reset rules, including Observable-valued reset notifiers.
- groupBy exposes key selection, element projection, duration Observables, and SubjectLike connector factories, with immutable key properties on group views.
- Migration capability mappings encode legacy/Symbol names, modules, argument adapters, arity, preconditions, status, and fixture evidence; semantic rewriting schema-checks the registry and engine version.
- Migration supports an optional frameworkAdapter after semantic rewriting and an OutputNamePolicy for planned filenames; these customize transformation and output without replacing batch planning.
- The documentation site registers lazy embedded components through selector/loadChildren entries, materializes a callback Map, and exposes it through an Angular InjectionToken.
Contributor handoff
Future work should start from the project charter and accepted decisions, then follow the smallest relevant runtime or tooling boundary. Tests and CI were inspected, not executed, and this bounded inventory does not prove exhaustive coverage or current gate success. The active plan, lifecycle distinctions, and source-pinned migration evidence are essential safeguards against reintroducing legacy assumptions.
- Read the charter, architecture, decisions, plan, and open questions in that order; read compatibility guidance for API or behavior changes.
- P6.10 remains NEXT pending actual beta publication/verification, package automation-token restrictions, and an immutable GitHub Release; inspected local preparation is not completion evidence for publication.
- Preserve an existing realm Observable and platform string methods; public RxJS capabilities use exact imported Symbols, with accepted internal registry keys documented separately.
- Do not port RxJS 7 assumptions mechanically: subscribe returns undefined, cancellation uses AbortSignal, producers register teardown explicitly, and platform teardown order is reversed insertion order.
- Use package scripts for later authorized verification: rxjs has source/ported Vitest, public types, installation/import checks, and migration freshness gates; polyfill has dedicated lifecycle and package checks.
- Treat test definitions and CI wiring as inspected evidence only: native-unavailable mode substitutes a sentinel suite, Node 26 is advisory, and unit success alone cannot establish WPT conformance.
- Update architecture documentation alongside changes to package boundaries, initialization, Symbol identity, lifecycle, realms, compatibility, exports, or test gates; record durable decisions and revise open questions.
- Keep apps/rxjs.dev outside the Next plan unless explicitly coordinated, and inspect migration preflight/refusal behavior before enabling project writes rather than treating dry-run output as automatic write authorization.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 771 | 72% |
| JavaScript | 249 | 23% |
| Markdown | 97 | docs/config |
| JSON | 77 | docs/config |
| Sass | 50 | 5% |
| HTML | 47 | docs/config |
| YAML | 18 | docs/config |
| Shell | 4 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (795 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/migrate/ | 108 |
packages/observable-polyfill/ | 78 |
packages/rxjs/ | 46 |
packages/test/ | 22 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 795 |
apps/ | 483 |
scripts/ | 21 |
.github/ | 17 |
docs/ | 14 |
.agents/ | 8 |
resources/ | 5 |
patches/ | 1 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.mddocs/RELEASE_PROCESS.mddocs/rxjs-next/ARCHITECTURE.mddocs/rxjs-next/COMPATIBILITY.mddocs/rxjs-next/DECISIONS.mddocs/rxjs-next/MIGRATION_SKILL_GUIDE.mddocs/rxjs-next/OPEN_QUESTIONS.mddocs/rxjs-next/PROJECT_CHARTER.md
Package
package.json — , 19 declared dependencies.
@nx/eslint-plugin@nx/js@playwright/test@typescript-eslint/eslint-plugin@typescript-eslint/parsercz-conventional-changelogesbuildeslintfast-checkhuskylint-stagednx
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/ci_ts_latest.yml— GitHub Actions workflow.github/workflows/codeql.yml— GitHub Actions workflow.github/workflows/dependency-review.yml— GitHub Actions workflow.github/workflows/rebase.yml— GitHub Actions workflow.github/workflows/observable-wpt.yml— GitHub Actions workflow.github/workflows/conventional-commit.yml— GitHub Actions workflow.github/workflows/release-readiness.yml— GitHub Actions workflow.github/workflows/ci_main.yml— GitHub Actions workflow
Structural health signals
Average score 8/10 across 96 analyzed source files; 11 hotspots surfaced.
packages/observable-polyfill/test/wpt/upstream/resources/idlharness.js— 2029 lines, score 5 (Large file, Deep nesting)packages/observable-polyfill/test/wpt/upstream/resources/webidl2/lib/webidl2.js— 2691 lines, score 5.5 (Large file, Deep nesting)packages/observable-polyfill/test/wpt/upstream/resources/testharness.js— 2007 lines, score 5.7 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
54796b38a57e2026-08-05 — docs: Update thisArg pattern documentationbe72ebf1a3b02026-08-05 — refactor: remove callback thisArg support11d931645c032026-08-04 — fix(release): simplify beta publishing87960a11a15f2026-08-04 — test(release): tolerate slow SafariDriver startup8b2c4367c3372026-08-04 — test(release): audit live staging controls