ericelliott / ogen

Write synchronous looking code & mix synchronous & asynchronous results using generators & observables.

Ogen

An observable version of async/await using regular generators. Short for (O)bservable (Gen)erator.

Write asynchronous code that looks synchronous, then tame your yielded values with observable methods like .map(), .filter(), .take(), .zip(), .skip(), etc...

Installing

npm install ogen --save

import / require

// ES6 Module import
import ogen from 'ogen';

// Node module import
const ogen = require('ogen');

Ogen uses generator functions to work its magic. If you don't know what they are, read: "7 Surprising Things I Learned Writing a Fibonacci Generator in JavaScript" and "The Hidden Power of ES6 Generators: Observable Async Flow Control", which describes the inner workings of Ogen in-depth.

When you yield a promise, Ogen intercepts it, waits for it to resolve, unwraps the resolved value, and passes the yielded value back into your function, assigning it to the left side variable:

const myFunc = function* (param1, param2, param3) {
  const result = yield fetchSomething(); // returns promise

  // waits for promise and uses promise result
  yield result + ' 2';
  yield param1;
  yield param2;
  yield param3;
};

Notice you can also yield any number of synchronous values, or any number of promises. All of your yield statements will yield observable values.

Pass your generator function into ogen() and get back an observable that lets you subscribe to all the yielded values:

const onNext = val => console.log(val);
const onError = err => console.log(err);
const onComplete = () => console.log('done.');

const asyncFunc = ogen(myFunc);

// Call the async function and pass params.
asyncFunc('a param', 'another param', 'more params!')
  .subscribe(onNext, onError, onComplete);
// future value
// future value 2
// a param
// another param
// more params!
// done.

Ogen returns a full Rx Observable instance, which means you can .map(), .filter() and .skip() to your heart’s content, among other things.

For a much more detailed description of how what Observables are all about, watch "Asynchronous Programming at Netflix".

Breaking Changes in 2.0.0

As of v2.0.0, Ogen returns an RxJS 5 Observable, meaning that it complies with the current ESNext Observable standard proposal. This is a breaking change.

For migration help, see rxjs/Migration.

Platform Notes

Obviously, this relies on generators. Works OK with Babel, Node v4+. Does not work in any IE without polyfills.

Should work in most other modern browsers.

Written for Learn JavaScript with Eric Elliott

An online course series for application developers. Ready to jump in? Learn more.