Lettable operator examples are wrong

[OliverJAsh]

IxJS version: 2.3.4

Code to reproduce:

The README has the following example on how to use lettable operators:

import { IterableX as Iterable } from 'ix/iterable';
import { map, filter } from 'ix/iterable/pipe';

// CommonJS
const Iterable = require('ix/iterable').IterableX;
const { map, filter } = require('ix/iterable/pipe');

const results = of(1, 2, 3).pipe(
  filter(x => x % 2 === 0),
  map(x => x * x)
);

for (let item of results) {
  console.log(`Next: ${item}`);
}

A few issues here:

• Where does of come from?
• import { map, filter } from 'ix/iterable/pipe'; does not seem to work. Rather one has to do import { map } from 'ix/iterable/pipe/map'; etc.

[desnor]

I had a quick look through and to explain what's happening with your points respectively:

• The of operator comes from above Iterable object. So this example should really be Iterable.of
• The import { map, filter } from 'ix/iterable/pipe'; doesn't do what we expect here because import ... from 'ix/iterable/pipe' returns us the function pipe not the subdirectory which contains the pipe-able (lettable) functionality. In order to access the map and filter lettable functions we need to dig deeper and actually go into the 'pipe' subdirectory. So for ex. something like import { map, filter } from 'ix/iterable/pipe/'

Does that make sense? It's not ideal having these names clash. I'll make a pull request to the docs updating the above points and see if anyone has an opinion about a different way to get access to the lettable functions. Maybe a directory called lettable instead of pipe would be a good start?

[desnor]

Bit more info from doing this:

require.resolve('ix/iterable/pipe');
=> .../ix/node_modules/ix/iterable/pipe.js

whereas
require.resolve('ix/iterable/pipe/');
.../ix/node_modules/ix/iterable/pipe/index.js

[OliverJAsh]

@desnor That makes sense to me!

[Sawtaytoes]

Or better yet, why not match RxJS's import style? I would assume most users of IxJS would be RxJS folks not wanting to learn another transducer library. Is that assumption correct?

If so, wouldn't ixjs/operators make the most sense?

Also, I noticed this example was wrong as well:

// ES
import { AsyncIterableX as AsyncIterable } from 'ix/asynciterable';
import { filter, map } from 'ix/asynciterable/pipe';

// CommonJS
const AsyncIterable = require('ix/asynciterable').AsyncIterableX;
const { filter, map } = require('ix/asynciterable/pipe');

const source = async function* () {
  yield 1;
  yield 2;
  yield 3;
  yield 4;
};

const results = from(source()).pipe(
  filter(async x => x % 2 === 0),
  map(async x => x * x)
);

for await (let item of results) {
  console.log(`Next: ${item}`);
}

In this example, AsyncIterable is imported, but from is never imported directly. Should it be AsyncIterable.from instead? Or even better, from or fromPromise which doesn't require pulling values off an object.

In RxJS, you can use from for Array, Iterable, Promise (async), and Observable so I would imagine IxJS would be able to tell if it's dealing with Iterable vs AsyncIterable in the same way; although, I dunno if it would be as simple as it is with RxJS's from.

Either way, having a separate iterator method would help with tree-shaking and ensure more similarities to RxJS.