niklas-wortmann/rxjs-web

Observable based Api wrapping Web APIs

rxjs-web
^{_{Observables for the Browser API}}

This library aims to provide Observable based APIs, that wrap Web APIs.

---

⚠️ A word of warning:

Some of the Web APIs covered here are experimental, non-standard, and/or not well-supported. If necessary, polyfills need to be provided by the user of this library.

The public API surface of this library can be affected by breaking changes within the experimental API used.

Additionally, the implementation of this library makes use of globalThis which breaks ie <= 11! There is no plan to add support for IE 11 in this library.

📦 Install

rxjs-web is available via npm:

npm i rxjs-web

N.B.: This library relies on RxJS >= 6 and expects you already have it installed in your project.

🔧 API Reference

General hint: usually promise-based APIs are eager, while Observable-based APIs of this library are lazy (executed/started upon subscription). This design decision was made due to the general specification of RxJS Observables.

fromIntersectionObserver

📖 IntersectionObserver | 🔬 experimental

...

fromMutationObserver

📖 MutationObserver

...

fromPerformanceObserver

📖 PerformanceObserver | 🔬 experimental

...

fromResizeObserver

📖 ResizeObserver | 🔬 experimental

...

fromImport

📖 dynamic import

...

fromMediaListQuery

📖 matchMedia

...

fromNetwork

📖 Network Information API | 🔬 experimental

...

fromPermission

📖 Permission API | 🔬 experimental

...

fromPosition

📖 Geolocation API

...

fromSensor

📖 Sensor APIs | 🔬 experimental

...

speak (Text to Speech)

📖 SpeechSynthesis | 🔬 not well tested

speak provides handy interface for chaining and aborting synthesis.

Usage

import { speak } from 'rxjs-web';

speak('Hello!').subscribe();

Chained

import { speak } from 'rxjs-web';

concat(
    speak('Hello, mom!'),
    speak('How are you?'),
    speak('I miss you.'),
).subscribe();

Advanced usage

import { of, merge, concat, timer } from 'rxjs';
import { map, takeUntil } from 'rxjs/operators';
import { speak, SpeechSynthesisUtteranceConfig } from 'rxjs-web';

const a: string = 'Hello, mom!';

const b: SpeechSynthesisUtteranceConfig = {
  text: 'How are you?',
  lang: 'en-UK',
  pitch: 1,
  rate: 1,
  volume: 1,
};

const c = new SpeechSynthesisUtterance('I miss you');
c.rate = 1;
c.lang = 'en-US';
c.pitch = 1;
c.rate = 1;
c.volume = 1;

concat(speak(a), speak(b), speak(c)).subscribe((e: SpeechSynthesisEvent) => {
  console.log(e.name);
  console.log(e.type);
});

listen (Speech to Text)

📖 SpeechRecognition | 🔬 not well tested

Handy interface for continuous speech recognition.

simple example

import { listen } from 'rxjs-web';

listen({ lang: 'en' })
  .subscribe(e => {
    if (e.type == 'result') {
      console.log(e.results[0][0].transcript);
    }
  });

🛸 Not yet supported APIs

These APIs are not yet supported by this library, and might be included later:

Name / Link
Vibration API
Bluetooth API
File and Directory Entries API
Image Capture API
Push API
Broadcast Channel API

🤝 Want to contribute to this project?

That will be awesome!

Please create an issue before submitting a PR — we'll be able to discuss it first!

Thanks!

Credits

This project is build upon the typescript library starter. Kudos to @alexjoverm and every contributor of this amazing project!

Many thanks also goes to Sascha for creating this fantastic logo!

Enjoy 🙂

rxjs-web's Issues

Prettier README

May I suggest moving things around in the README to make things more appealing and API easier to navigate?

Here are some ideas:

• reformat the header: add description & badges
• change the copy for the overview section (add links to some articles?)
• split the warnings into a separate section
• add install section
• prioritize API and examples
• deprioritize roadmap and move to the bottom (I'd actually moved the roadmap into a separate file)

Something like this:

---

rxjs-web
^{_{Observables for the Browser API}}

This library aims to provide an observable based API, that wraps the web APIapi. This also includes experimental, non-standard, and not well-supported APIs. Polyfills need to be provided by the user of this library if necessary.

📦 Install

npm i rxjs-web

This library uses the Observable implementation of rxjs >= 6 and expects you already have that installed in your project.

⚠️ A word of warning

The public API surface of this library can be affected by breaking changes within the experimental API used.

Additionally, the implementation of this library makes use of globalThis which breaks ie <= 11! There is no plan to add support for IE 11 in this library.

🔧 API Reference

General Hint: Usually Promises are eager. All the APIs provided by this library, that wraps native promise-based APIs, are lazy though. This design decision was made due to the general specification of Observables.

fromIntersectionObserver

⚠️ experimental ✅ tested

MDN link

description

const example = fromIntersectionObserver();
// ...

fromMutationObserver

⚠️ experimental 🔬 not well tested

MDN link

description

const example = fromMutationObserver();
// ...

Supported API Roadmap

API	Implemented	Tested	Experimental/not well supported
Bluetooth API			☑
Broadcast Channel API
dynamic import	☑
File and Directory Entries API			☑
Geolocation API	☑
Image Capture API			☑
IntersectionObserver	☑		☑
matchMedia	☑
MutationObserver	☑
Network Information API	☑		☑
PerformanceObserver	☑		☑
Push API			☑
Permission API	☑		☑
ResizeObserver	☑		☑
Sensor APIs	☑		☑
Vibration API			☑

Credits

This project is build upon the typescript library starter. Kudos to @alexjoverm and every contributor of this amazing project!

Many thanks also goes to Sascha Nuissl for creating this fantastic logo!

Typing problems with RxJS v7

No idea why this happens, but:

const o$ = fromResizeObserver(document.body);
const n$ = new Subject<number>().pipe();
const s$ = new Subject<string>().pipe();

combineLatest([n$, s$]).subscribe(([n, s]) => {})
// n = number
// s = string

combineLatest([o$, s$]).subscribe(([o, s]) => {})
// o = Observable[string] | Observable[ResizeNotification]
// s = undefined

Latest stable Typescript, latest stable RxJS. Any remedy? Thanks!

CI failing due to tests running on node < 12

The build is currently always failing on runners with NodeJS v < 12 due to globalThis usage (which is expected as only 12+ versions support it)

Related Travis CI config: https://github.com/niklas-wortmann/rxjs-web/blob/development/.travis.yml#L10-L11

IMO, one latest version should be enough since the lib is targeted on web platforms rather than NodeJS.

I suggest using only one runner: node 14 (latest LTS). This is a small fix that should make our builds green.

Distribute ES Modules (ESM) so we can benefit from tree shaking

Hi, this library looks really useful and we would like to use it at Unsplash!

However it seems that the npm module only provides CommonJS modules. Would it be possible to distribute ES Modules as well, so we can benefit from tree shaking which will help to reduce our bundle size?

interoperability with other reactive libraries

I would really like to get feedback if any other reactive community would be interested in something like this. Technically we could add some kind of interoperability with callbag or xstreams. I'm just mildly concerned about additional maintenance effort, but if it is a highly requested feature, I'd consider adding it.

Therefore I would really appreciate some kind of voting on this issue.

wraping fromNetwork in existing service function

I'm using angular http and can't get it to work in my component.

• service existing code:

search(criteria: string): Observable<OrgSearch[]> {
    return this.http
              .get<OrgSearch[]>(`api/info/search?q=${criteria}`, this.auth.getHttpAuthOpt())
              .pipe(catchError((error: Response) => observableThrowError(error)));
  }

• component existing code:

this.infoService
        .search(this.orgSearchCondition)
        .pipe(
          takeUntil(this.onDestroyComponent$),
          stopSpiner<OrgSearch[]>(() => this.isLoading = false),
          showError<OrgSearch[]>(() => {
            this.uiService.showErrorFlashMessage('prišlo je do napake pri iskanju članic!');
            return EMPTY;
          })
        )
        .subscribe(result => this.onSearchOk(result, this.orgSearchCondition));

• but when I wrap it, it's never triggered

search(criteria: string): Observable<OrgSearch[]> {
    return fromNetwork()
      .pipe(
        first(),
        switchMap(net => {
          console.log(`net=${net}`);
          return this.http
            .get<OrgSearch[]>(`api/info/search?q=${criteria}`, this.auth.getHttpAuthOpt())
            .pipe(catchError((error: Response) => observableThrowError(error)));
        })
      );
  }

• I'm doing something wrong?
• The idea of lib is great

Regards

Add support for Web Bluetooth

Hi, this is an amazing lib! I have done some work for the Web Bluetooth API in the context of Angular Web BLE module.

https://github.com/manekinekko/angular-web-bluetooth

I'm happy to help contribute some code 😊

Typed fromEvent for web

When we use fromEvent in web we can extract type of event from the map of event names that are present in TypeScript.

It is also often helpful to have currentTarget of that event to have the same type as the target we listen this event on so we do not have to typecast low level EventTarget when we work with it down the RxJS line.

currentTarget type is questionable because it changes. currentTarget only matches the element we listen event on directly in the callback. So this might not be a good idea but it's up for a debate :)

Here's a little proof of concept with events on Element, Window and Document with fallback to current fromEvent behavior where we just have generic:

https://stackblitz.com/edit/angular-typed-fromevent-delux

This could be a starting point for discussion/implementation.