Skip to main content

Wraplet and WrapletApi

What defines a wraplet is the implementation of the Wraplet interface that consists only of a wraplet property that implements the WrapletApi interface.

WrapletApi makes it possible to tie together lifecycles of multiple wraplets, allowing complex components to emerge.

interface Wraplet {
  wraplet: WrapletApi;
}
interface WrapletApi {
  [WrapletApiSymbol]: true;

  status: Status;

  destroy(): Promise<void>;

  initialize(): Promise<void>;

  addDestroyListener(callback: DestroyListener): void;
}

WrapletAPI's properties​

status​

interface Status {
  readonly isInitialized: boolean;
  readonly isGettingInitialized: boolean;
  readonly isDestroyed: boolean;
  readonly isGettingDestroyed: boolean;
}

The status property is a read-only object that contains information about the wraplet's lifecycle.

destroy​

destroy is an asynchronous method that's responsible for destroying a wraplet.

initialize​

initialize is an asynchronous method that's responsible for initializing a wraplet.

addDestroyListener​

addDestroyListener is a method that allows you to add a listener to the wraplet that will be executed during wraplet's destruction.

type DestroyListener<W extends Wraplet = Wraplet> = (
  wraplet: W,
) => Promise<void>;

Helper functions​

createWrapletApi​

createWrapletApi is a simple function that creates a new WrapletApi instance. You inject your callbacks into it to run your custom code on the Wraplet's lifecycle events.

function createWrapletApi(
  args: WrapletApiFactoryArgs,
): WrapletApi & WrapletApiDebug;
type WrapletApiFactoryArgs<N extends Node = Node> = {
  node?: N;
  wraplet: Wraplet;
  destroyCallback?: WrapletApiFactoryBasicCallback;
  initializeCallback?: WrapletApiFactoryBasicCallback;
}

composeWrapletApi​

composeWrapletApi function allows managing wirings of your objects with Wraplet API through declarative composition. Basically, features shared by multiple wraplets can provide their own wirings, so if their wiring changes, it changes only in a single place (and if they are external dependencies, you might not need to change your code at all).

function composeWrapletApi(
  node: Node,
  wraplet: Wraplet,
  wirings: Wiring[],
): WrapletApi & WrapletApiDebug;

The Wiring type is similar to object that you pass to the createWrapletApi function, but it contains callbacks only:

type Wiring = Omit<WrapletApiFactoryArgs, "wraplet" | "node">;

composeWrapletApi merges multiple wirings into a single object passed into the createWrapletApi function. Initialization callbacks are then executed in the order of the wirings, but destruction callbacks are executed in reverse order.

Examples​

A non-dependent wraplet​

In this example we'll create a simple custom class implementing the Wraplet interface without extending any other class.

Implementing WrapletApi with composeWrapletApi​

Thanks to the composeWrapletApi helper, you can easily wire up additional features of your wraplet with Wraplet API, if they have a lifecycle to share.