KOS Developer's Portal

Creating Your First KOS Model

Introduction

A KOS Model is an entity with its own independent lifecycle that acts as a projection of one or more physical or software states that exist on a dispenser.

When creating a KOS model you will need to specify the model state to be managed as well as some metadata that the model framework will use to properly manage model relationships and lifecycles.

The KOS model framework makes use of annotations to specify type metadata.

A KOS Model is a Typescript class that has been decorated with the @kosModel decorator. The decorator takes a single parameter which is the unique model type identifier. This ID will uniquely identify the model specification as opposed the model instance.

As a best practice, there are three main pieces that make up a model; the Model Specification which is made up of the Model Options and Interface, the Model and the Model Factory.

Model Specification

The model specification is the interface that describes the model including its state as well as any additional services that might be passed in via the constructor.

Model Options

The options interface represents the part of the model that might be passed in the constructor. This can include pieces of the model state as well as services or other functions that allow for more modular IoC patterns.

It’s important to note that the options will only be applied during the construction of the model.

interface DemoOptions {
  name: string;
}

Model Interface

Typescript interface describing the public facing interface of the model that UI components and other models will interact with. As a best practice, try to avoid importing model implementations directly and prefer to work with interfaces. This will become especially important as application complexity increases and the number of projects start to grow.

import type { IKosDataModel } from "@coca-cola/kos-ui-core";

export interface IDemoModel extends IKosDataModel, DemoOptions {
  id: string;
}

KOS Model

The KOS Model is the implementation of the interface described above

import { kosModel } from "@coca-cola/kos-ui-core";
import type { IKosDataModel } from "@coca-cola/kos-ui-core";

import log from "loglevel";

@kosModel<IDemoModel, DemoOptions>(DEMO_TYPE)
export class DemoModel implements IDemoModel {
  id: string;
  name: string;

  constructor(modelId: string) {
    // assign the id from the passed in model id
    this.id = modelId;
    this.name = "foo";
  }

  async init(): Promise<void> {
    log.debug("initializing demo model");
  }

  async load(): Promise<void> {
    log.debug("Loading demo model");
  }
}

Model Factory

A Model Factory provides a generic, low-level mechanism for the KOS model framework to create new instances of models. The model factory should typically be placed into its own file in order to avoid needing to explicitly import and export the model implementations.

The SDK provides a helper function modelFactory that can be used to provide a simplified mechanism to create new instances of a model.

The Model Factory is a lower-level abstraction that is not commonly used directly in the application space. Generally, the factory is going to be used by the framework as there are higher level components, hooks and utilities that will used in the application space that make use of the Factory behind the scenes.

import { modelFactory } from "@coca-cola/kos-ui-core";

// define an ID to uniquely identify this model type.
export const DEMO_TYPE = "demo";
export const DemoFactory = modelFactory<IDemoModel, DemoOptions>(DEMO_TYPE);

It can be used in code to build a new instance of the model using the provided ID and options unless a model of the same type with the same ID already exists in the KOS Model cache in which case the already created instance will be returned.

In the case where the instance already exists the provided options will not be reapplied.

const modelId = "demo1";
const options: DemoOptions = {
  name: "demo_name",
};
const demo = DemoFactory.build(modelId, options);

In this case the build function will return a new instance of a Demo model with an ID of "demo1" and the name property set to "demo_name".

Creating Your First KOS Model

Introduction

Model Specification

Model Options

Model Interface

KOS Model

Model Factory

Reference

Next Steps

Creating Your First KOS Model

Introduction

Model Specification

Model Options

Model Interface

KOS Model

Model Factory

Reference

Next Steps

Send us your feedback!