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.

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>I = {
  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.