feat(far): new package @agoric/far

[michaelfig]

closes: #3833

Description

Create a new package @agoric/far, as described in the README.md, to cover the common cases of clients of the Agoric distributed objects system.

After this toehold, a follow-on PR can convert many of our redundant:

import { E } from '@agoric/eventual-send';
import { Far, getInterfaceOf, passStyleOf } from '@agoric/marshal';

to just:

import { E, Far, getInterfaceOf, passStyleOf } from '@agoric/far';

The eventual goal is to reduce the dependencies required to implement this package.

Security Considerations

Documentation Considerations

I'd like to get @dckc's involvement to see if it helps simplify example code in https://github.com/Agoric/documentation.

Testing Considerations

Tests were lifted from @agoric/eventual-send and @agoric/marshal, and pruned to test only the features exported by this package.

[dckc]

Hmmm... In #3833 the suggested name was far. It's shorter.

Perhaps we could even lose the @agoric/ qualifier in due course...
https://www.npmjs.com/package/far was last published 10 years ago, though it still has about 150 downloads per week. I wonder if the maintainer would cede to us.

This is clearly a user-visible feature, not just a chore.

[michaelfig]

Hmmm... In #3833 the suggested name was far. It's shorter.

👍

Perhaps we could even lose the @agoric/ qualifier in due course... https://www.npmjs.com/package/far was last published 10 years ago, though it still has about 150 downloads per week. I wonder if the maintainer would cede to us.

For branding and logical grouping of packages, I'd like to see this pushed down into @endo/far or even @jessie.js/far. I don't think it makes sense to try to publish non-namespaced packages.

This is clearly a user-visible feature, not just a chore.

Thanks, adjusted.

[dckc]

exports seem to differ between index.js and the README

[dckc]

Documentation Considerations

I'd like to get @dckc's involvement to see if it helps simplify example code in https://github.com/Agoric/documentation.

yes, quite likely.

In fact, I considered consolidating the eventual-send.md and far.md sections. Keeping them separate seems ok for now.

[dckc]

good stuff.

I'm curious how much of the new package boilerplate you had to do from memory. I don't see anything about it in https://github.com/Agoric/agoric-sdk/blob/master/CONTRIBUTING.md

[dckc]

EOnly<T> is sort of new to me; I'm used to ERef<T>. hm.

[michaelfig]

I added comments, and good catch: this package should export ERef<T> as well.

[michaelfig]

Oops, too late to beat the automerge. I'll do a follow-on.