Interfaces

context: Coding Style

Interfaces, Shapes, and Guards

We have a "patterns" system for defining and validating values, located in the store package as of December 2022.

Interfaces are implemented by classes or instances. InterfaceGuards consist of named MethodGuards. Aside from the special M.await(pattern) await guard, methodGuards use patterns to check their arguments and results. Values are tested against patterns/shapes, and either pass or fail.

InterfaceGuards are used in Exo objects and classes.

Naming conventions

const <Noun>I = M.interface('Noun', {
  <methodName>: M.call(<firstRequiredArgumentShape>, …).….returns(<returnShape>),
  …
});
const <Noun>Shape = M.<array|bag|map|record|remotable|…>(…);

// for multi-facet interfaces
const <ComplexNoun>IKit = {
  facet1: M.interface('Facet1', {
    <methodName1>: M.call().returns(M.remotable('returnThing')),
    <methodName2>: M.call(M.string()).returns(),
  }),
  facet2: M.interface('Facet2', { <methodName>: M.call(M.string()).returns() }),
};

Interfaces should be suffixed with "I", short for "Interface". We prefer this over <Noun>Guard, <Noun>Interface, or <Noun>InterfaceGuard. "Guard" by itself is less specific, as we also have method guards and await guards, although we rarely if even need to name these.

<Noun>Shape should only be used for patterns, not guards.

Resolving parameters

If parameters to a function might be passed as promises, but the function will need the resolution of the promise in order to proceed, the work can be made the responsibility of the guards and the function can be expressed without an await on the parameter or an E.when() surrounding the code.

   <methodName>: M.callWhen(M.await(<paramType>)).returns(),

Two things to notice about this:

• this can change the order of processing incoming messages. The deposit method on purses requires the caller to supply a resolved payment, and doesn't use callWhen() so that incoming deposit() calls will be totally ordered.
• typeGuards are often remote from the code, which means the fact that there's a callWhen may not be obvious when reading the code.