Skip to main content

Bold Penguin SDK Contracts

What is a contract​

Contracts allow you to validate disjointed communication between two consumers of a given service. Contracts are commonly used to allow servers and consumers of an API to validate and handle changes to that API. This technique has been adapted for TypeScript consumers of the Bold Penguin SDK to handle communication of changes between our internal elements to your external elements.

While the consumption of contracts is optional, we highly encourage it to make your components more resilient to any changes to our internal structure.

Contracts with the Bold Penguin SDK​

We export general and component contracts from the @boldpenguin/sdk package. These Typescript types define all the properties and types we use on our components as inputs.

Example usage​

import { IDateInputComponent } from '@boldpenguin/sdk';

  class BpSdkExternalDateInput implements IDateInputComponent {
  }

Validating attributes​

Notably, these contracts only allow you to track properties. With a bit more work you can start tracking attributes as well, making your external components resilient to our internal component changes. When registering web components, there is a defined observedAttributes property you can use to look at all the attributes a component consumes. You can validate the attributes match by comparing the external and internal components.

Jest example​

expect(customElements.get('bp-sdk-date-input').observedAttributes.sort()).toEqual(customElements.get('bp-sdk-external-date-input').observedAttributes.sort());

Dynamic example​

  isValidComponent(tag: string, external: string): boolean {
  return customElements.get(tag).observedAttributes.sort() === customElements.get(external).observedAttributes.sort();
  }