symbol-observable

symbol-observable is a minimal ponyfill for Symbol.observable, the well-known symbol that lets JavaScript objects declare themselves as Observables in a way multiple libraries can recognize consistently. Rather than mutating the global Symbol object unconditionally the way a polyfill would, it exports the correct symbol value directly for consumers to reference, falling back to a Symbol.for()-based or plain-string value when Symbol support is incomplete or absent entirely.

Originally written to standardize the interop point used by RxJS, xstream, and most.js, it has become the de facto shim that observable-producing and observable-consuming libraries depend on so they can recognize each other’s objects without agreeing on a shared class hierarchy.

What You Get

• Consistent Symbol.observable - A single shared value for Symbol.observable, exported as the module’s default export, so libraries agree on the same interop key.
• Safe ponyfill behavior - Never mutates global objects destructively; assigns Symbol.observable only when doing so won’t throw, and degrades gracefully when Symbol is frozen or absent.
• Environment fallbacks - Detects self, window, global, or module to find the correct root object, and falls back to the string '@@observable' when Symbol doesn’t exist at all.
• Bundled TypeScript typings - Ships index.d.ts and ponyfill.d.ts, including a global SymbolConstructor.observable declaration.
• Dual module builds - Provides both a CommonJS build (lib/, transpiled down to ES3) and an ES module build (es/) for bundlers that prefer tree-shakeable imports.

Common Use Cases

• Making a custom object observable - Assign a subscribe method under the imported symbol so libraries like RxJS can recognize your object as an Observable source.
• Building an Observable-compatible library - Library authors use the same symbol as their public interop point instead of inventing a proprietary marker.
• Interop between reactive libraries - Consuming code written against RxJS can accept observables produced by xstream or most.js because both key off the same symbol.
• Polyfilling in older JS engines - Provides a string-based fallback ('@@observable') so interop still functions in environments without native Symbol support.

Under The Hood

Architecture The package is deliberately two files deep: es/index.js performs environment/root detection (self → window → global → module → Function('return this')()) and hands the resolved root object to es/ponyfill.js, a single pure function (symbolObservablePonyfill) that contains all the actual logic for resolving or assigning Symbol.observable. The root-level index.js/ponyfill.js files are thin re-exports of the Babel-compiled lib/ output, and es/ ships the same logic as untouched ES modules for bundlers. There is no state, no classes, and no dependency injection — the entire library is one function call evaluated once at import time, so if ponyfill.js’s resolution logic changed, every consumer’s Symbol.observable reference would change simultaneously since it runs at module-load time. Tech Stack The published package has zero runtime dependencies; its devDependencies are entirely build/verification tooling — babel-cli with babel-preset-es2015/babel-preset-es3 transpile the ES module source in es/ down to ES3-safe CommonJS in lib/, check-es3-syntax-cli then verifies the build output contains no syntax newer engines wouldn’t need to worry about but ancient ones (targeted via a .travis.yml matrix down to Node 0.12) would choke on, and mocha/chai plus a standalone typescript compile step (ts-test/test.ts) cover runtime and type-level behavior respectively. package.json publishes both main (CJS) and module/jsnext:main (ESM) entry points alongside typings, so this is a pure library targeting npm distribution with no server or deployment component of its own. Code Quality Test coverage is proportionate to the package’s size: test/ponyfill.js unit-tests the core function across every branch (Symbol absent, Symbol.observable pre-set, Symbol.for present/absent, and a frozen Symbol object to confirm the try/catch doesn’t throw), and test/index.js adds an integration check against the real global Symbol. A separate ts-test/test.ts, compiled and executed as part of npm test, verifies the TypeScript typings resolve to the expected runtime value. CI was configured via Travis across seven Node versions (0.12 through 14); there’s no ESLint/Prettier config in the repo, and naming stays simple and consistent throughout the small codebase. No dedicated type-checking of the JS source itself (only the .d.ts files and a smoke-test consumer), which is a reasonable trade-off given the library’s tiny surface area. What Makes It Unique The library isn’t technically novel — it’s a standard ponyfill pattern (return the right value instead of mutating globals) applied to one specific well-known symbol. Its actual significance is social rather than algorithmic: it became the de facto shared interop point that RxJS, xstream, most.js, and other Observable implementations all independently adopted, so an object produced by one library is recognized as observable by consumers written against another, without any of them sharing a class hierarchy or importing each other directly.