Implement support for resources

[jnicklas]

A resource ties an execution context to an object. This allows an object to be passed around between contexts while retaining an associated context. This context is "kept alive" as long as the object's scope is alive. If the object is returned out of the current scope, the context is hoisted to the parent scope along with the object. This allows an escape hatch from contexts being local to where they were created and makes it possible to implement the RAII pattern.

[github-actions]

A preview package of this pull request has been published with the tag resources.
You can try it out by running the following command:

$ npm install effection@resources

or by updating your package.json to:

{
  "effection": "resources"
}

Generated by 🚫 dangerJS against 3f5581c

[jnicklas]

Just a note that this is definitely a breaking change, did find a few places in bigtest where this was breaking things in subtle ways. Mostly where we were returning a context for no real reason, which is now doing things when previously it was just useless.

[jnicklas]

@cowboyd marking this as ready for review :)

[cowboyd]

I'm still trying to understand the difference between creating a resource and returning a resource. Is my understanding correct here?

function* operation() {
  let resource = yield function* createResource() {
    let create = resource({}, constructoOperation); //<- an operation to create a thing
    let res = yield create; //<- actually creates a thing....
    return res; //<- links to parent context.
  }
  yield somethingElse();
  return resource; //-> links to parent context
}

My biggest questions are:

1. when should the create be considered done?
2. is binding the resource to the current context necessary when the only purpose is to return it to the parent context?

[cowboyd]

Is it worth adding in a check here to make sure that the new parent is higher in the tree than the old parent? It feels like it is not ok, to transfer ownership "down-tree", although we may want a way to do that explicitly in the future.

[jnicklas]

That was sort of what I was thinking, I think it makes sense to expose link as an operation, to essentially "move" a child somewhere, though there might be some weird implications to that which I haven't thought through, so I didn't add it in this PR. But we could definitively add such a check for now, until we're sure that it is actually safe to do this.

[cowboyd]

We should mark monitor as deprecated, maybe emit a console warning once.

[cowboyd]

See questions on bigtest repo, but looks good to me overall. Nice work!

[jnicklas]

1. when should the `create` be considered done?

A resource starts off in the context where it was created, and it effectively functions like a child of this context, so when the context is finalized the resource is halted.

The one exception to this is when the child resource is returned out of the context. Any child resource or child context which is returned from a context is not halted on finalization.*

Additionally, a resource can exit early, that is if the resource's context becomes completed. This is a trivial example:

yield resource({}, function*() { return });

The associated context here does nothing, so there is nothing keeping it alive. Compare to this:

yield resource({}, function*() { yield });

I've actually thought about whether a resource which finishes early should be considered an error, as this is probably never what you want, and it's actually already bitten me once or twice, but I felt that that's maybe a tad bit too opinionated 🤷‍♂️

2. is binding the resource to the current context necessary when the only purpose is to return it to the parent context?

Unfortunately not, since everything in Effection is synchronous, whatever happens up until the first yield point will run synchronously on creation of the resource. An error which occurs here will need to be handled by ... someone. So by creating the resource in the current context, and then moving it upwards, we ensure that there is someone there who can handle this error.

* (except, and here is where things get a bit weird: if the context that returns the resource is itself a resource context or it is the root context, some other weird rules apply, which feel like they make sense, but actually kinda don't 😂. But even though the implementation differs slightly here, functionally it feels like it behaves about the same)

[jnicklas]

One thing that I just realized is that we should consider a guard against returning a context or resource which is NOT a child of the current context, while this probably works just fine, it feels like it violates the "spirit" of this API, and shouldn't be allowed.