The behavior of stream seems somewhat odd; perhaps it shouldn't be Operation<X>

[iplaylf2]

The documentation at Effection Collections mentions that Stream corresponds to AsyncIterable, but in practice, AsyncIterable -> AsyncIterator does not require await during usage:

const delay = (x: number) => new Promise(r => setTimeout(r, x));

(async () => {
    const stream: AsyncIterable<number> = (async function* () {
        await delay(100)
        yield 1
        await delay(100)
        yield 2
        await delay(100)
        yield 3
    })();

    const subcription1 = stream[Symbol.asyncIterator]() // No `await` on the stream itself
    // const subcription2 = ...

    console.log(await subcription1.next())
    // ....
})()

typescript playground

The example in the Effection documentation is also confusing:

    let subscription1 = yield* channel;
    let subscription2 = yield* channel;

There are two different subscriptions created here, and it feels like merely using yield* to wait for an Operation<X> creates a new task, whereas await waiting for a Promise<X> does not.

Nowadays, for the same functionality, I think the following expression in Effection is better:

import { main, createChannel } from 'effection';

await main(function*() {
  let channel = createChannel();

  // the channel has no subscribers yet!
  yield* channel.send('too early');

  let subscription1 = channel.subscribe();
  let subscription2 = channel.subscribe();

  yield* channel.send('hello');
  yield* channel.send('world');

  console.log(yield* subscription1.next());
  //=> { done: false, value: "hello" }
  console.log(yield* subscription1.next());
  //=> { done: false, value: "world" }
  console.log(yield* subscription2.next());
  //=> { done: false, value: "hello" }
  console.log(yield* subscription2.next());
  //=> { done: false, value: "world" }
});

Hmm, what about Stream? Maybe the signature of Stream should be Stream<T> = () => Subscription<T>. This way, it would be analogous to AsyncIterable and AsyncIterator.

[cowboyd]

@iplaylf2 I think I see where you're coming from. There definitely are some differences between the Async/Await primitives and their Effection analogues, and that they can seem confusing and/or unnecessary when you are new to Effection. However, it is precisely in these differences that you will find the key to the guarantees that Effection provides you that Async/Await does not. Specifically:

It is impossible in Effection to create any effect whatsoever that is not bound to a scope.

This may seem restrictive at first, but it is actually a superpower.

Take for example the delay function you defined:

const delay = (x: number) => new Promise(r => setTimeout(r, x));

This eagerly creates the timeout effect every time it is called, and it can be called anywhere at any time:

const delay = (x: number) => new Promise(r => setTimeout(r, x));

delay(500);

(() => { delay(1000}; delay(400); })();

for (let i = 0; i < 1000; i++) {
  delay(i);
}

This will create over 1000 calls to setTimeout(), and there is no way to tell where they came from. By contrast, the Effection analogue of the Promise constructor is action() and it does not eagerly create context-free effects. The previous example using action would look like this:

const delay = (x: number) => action(r => { 
  let timeoutId = setTimout(r,x}; 
  return () => clearTimeout(timeoutId);
});

delay(500);

(() => { delay(1000}; delay(400); })();

for (let i =0; i < 1000; i++) {
  delay(i);
}

Which causes setTimeout() to be called exactly zero times. That's because unlike the Promise constructor which actively does a thing, an action is only a recipe for how to do the thing. And, the only way you can actually cause it to be invoked is by evaluating the action with yield*. When you do, that call to setTimeout is implicitly associated with the scope in which the action was evaluated, and so if that scope goes away for any reason whatsoever(return, error, or cancellation), the setTimeout effect will be uninstalled.

The same principle applies to subscriptions. Usually, whether it is a file handle, a web socket, a bucket storage download, or whatever, there is some "hot" state associated with a subscription. AsyncIterable will usually create that hot state eagerly in a context-free fashion, just like the Promise constructor.

 const subcription1 = stream[Symbol.asyncIterator]() // No `await` on the stream itself

In that code, it is unknown what state [Symbol.asyncIterator]() could allocate. It might open a TCP connection for example to start reading chunks, it might open a file. But there is no "owner" of that state. It is effectively global, and could very easily be leaked. In the same way as action(), activating an effect must be associated with a scope, so the subscription itself must have an owner, as well as each operation that is evaluated to get the next item.

I hope that helps explain why the differences are necessary. While there are analogues for Async/Await constructs in Effection, they are only that: analogues. They must be different it very distinct ways so that we can experience the guarantees that structured concurrency provides which Async/Await doesn't.

I'll leave one final difference which I think is important to grasp. In Effection, yield* is the analogue to await. However, yield* is much more than just a mechanism to await the settlement of a Task (although it is that). While await is limited strictly to resuming the current async function when a promise settles, yield* is a universal evaluator of any effect. In other words, while await can evaluate a single type of effect (promise settlement), yield* can evaluate an infinite number of effect types. An example of this is the context api. which has nothing to do with asynchrony (and is, in fact, synchronous).

[iplaylf2]

My previous understanding of Operation was fundamentally incorrect. If I had properly understood how generator functions can be used to represent () => Operation, I wouldn't have maintained this misunderstanding for so long.

When a generator function is directly called, it doesn't execute the code in its body immediately. Instead, it requires obtaining an Iterator and invoking the next() method to start executing the code. This is precisely how yield/yield* works - when you yield* an Iterable instance, it actually executes the code in the generator function that created it. Each yield* operation essentially creates a new Iterator and performs a complete iteration through it.

Effection uses the same syntax to handle Operations. The principle remains identical: every time you yield* an Operation instance, it means executing the code in the generator function that created that Operation instance.

Regarding the context aspect - I can't articulate it clearly yet, but I intuitively perceive yield* Operation as synchronously executing code within a scope. This scope represents exactly what I expect: a transparent and controlled "coroutine code block"... I'll reach out again if I encounter unresolved issues in this area.

In any case, thank you for helping me identify the root issue. The Stream concept is starting to make sense to me.

[cowboyd]

Great!

I intuitively perceive yield* Operation as synchronously executing code within a scope.

You're pretty much spot on, and you've hit on a very important point. Effection is fundamentally synchronous in nature, so if operations can resolve synchronously, they do. Among other things, this means that Effection streams are appropriate for handling DOM events, whereas async iterables are not.