Stack TypeScript Node

After designing the project, the next step is to implement it. You can find helpful information on preparing your IDE in development tools. This also includes the installation and setup of the Solution CLI which provides several features related to local development as well as testing service projects.

ℹ️note

This part will be done in the IDE of your choice.

Introduction

The implementation of a Domain Service Project is focused on the usage of commands, services, events and operations. These are the main elements to add functional behavior to the project.

While working on a REST API you will implement mostly operations and maybe call domain services to process the incoming request. Depending on your project's design you may need to gather additional data from an integration service that will then be processed and enriched with other data by using a domain service.

⚠warning

Whenever you are querying external services, you should make sure, that all communication to such services are encrypted and all TLS-encrypted protocols including HTTPS use version 1.2+. The connection to the target service should be authenticated (certificate validation should be enabled)!

There is also the option to create, edit and persist data or load data from the datastore by using factory commands or instance commands. This domain service could also publish an event whenever a request has been processed or data has been created/persisted.

To make proper use of these elements you need to understand when and how to use which of them to implement the desired behavior. Below is a description of each element, its intended use and scope of other elements it can call.

Getting Started

At this point, it is assumed that the initial setup and the mandatory commands of the Solution CLI have been performed and executed as described.

Prerequisites

Be sure you have set up and installed all prerequisites and development tools.

Create a new project workspace

After you have created a project in Solution Designer and modelled it according to Domain Driven Design principles, create a folder for your workspace. Then, open a terminal and navigate to your development workspace folder.

Example:

cd /my/workspace/

Clone project to local workspace

Inside Solution Designer, open the project and click on Solution CLI in the task bar located at the bottom of the page.

There you will find instructions on how to set up the CLI and connect it with your k5-project. The section Implementation provides the necessary information for the k5 clone command to clone the project to your local workspace.

ℹ️note

You will be prompted for your username and password for this k5-project. A folder in your workspace will be created for the cloned project, where the folder name will be the project acronym.

Example:

/my/workspace/SOL

Open project

Open your project folder using a code editor, e.g. Microsoft VS Code or similar.

Project structure

The project is structured into several source folders and some configuration files inside the workspace folder:

- .vscode: holds settings for Microsoft VS Code
- dist/src-impl: holds the JavaScript files and the source maps for each of the TypeScript files
  - api
    - one folder per API Namespace
      - middleware
      - operations
  - domain
    - one folder per Domain namespace
      - services
      - aggregates
        - factory
        - instance
      - agents
  - integration
    - one folder per Integration namespace
      - services
  - util
- node_modules: contains all node module folders
- src-impl: contains the TypeScript implementation code
  - api
    - one folder per API Namespace
      - middleware
      - operations
  - domain
    - one folder per Domain namespace
      - services
      - aggregates
        - factory
        - instance
      - agents
  - integration
    - one folder per Integration namespace
      - services
  - util

The folder named src-impl is the main implementation folder that holds all other folders for each of the modelled elements. Depending on your design model there will be one or more of the following folders inside:

API

This folder consists of a folder for each of the modelled API Namespaces. These folders are named by their respective namespace's prefix and each of these folders contains two additional folders:

• Middleware: This folder holds the implementation and the test file for the ErrorMiddleware
• Operations: In this folder you will find an implementation file and a test file for each Operation you modelled

Domain

This folder contains a folder for each domain namespace you have created. These folders are named by their respective namespace's prefix. Depending on your design model you will see one or more of the following folders inside the namespace folders:

• Aggregates: For each root entity you modelled you will find a folder that contains the following folders depending on your model:
  • Factory: If you modelled factory commands you can find the implementation and the test files for each command here
  • Instance: If you modelled instance commands* you can find the implementation and the test files for each command here
• Agents: For each agent you modelled you will find an implementation file and a test file here
• Services: This folder holds an implementation file and a test file for each service you modelled

Integration

This folder consists of a folder for each of the modelled Integration Namespaces. These folders are named by their respective namespace's prefix and each of these folders contains an additional folder:

• Services: Inside this folder you can find an implementation file and a test file for each REST service you have modelled

util

This folder contains the mapper.ts file. See mapper utility for further details.

Functional overview

Factory command

• Creates an instance of a root entity and persists it in the data-store
• Inside a factory command, events can be published.
• Inside a factory command's implementation, there is a function called available(). This is used to check the necessary pre-conditions of the command. If the function returns true then the command will be executed, otherwise, the command will not be executed at all.

Instance command

• Manipulates the values of one or more properties of an already existing instance of an entity
• Inside an instance command, events can be published
• Inside an instance command's implementation, there is a function called available(). This is used to check the necessary pre-conditions of the command. If the function returns true then the command will be executed, otherwise, the command will not be executed at all.

Domain service

• can perform operations throughout different Domain Namespaces
• inside a domain service, you can call factory commands, instance commands, domain services, and events

Events

• they are published to indicate that some state has changed
• an event that is successfully published will automatically execute the script of the agent that is bound to this event

Agents

• when an event is triggered, then agents are automatically executed as consequence of the action that triggered the event
• inside agents, you can call factory commands, instance commands, domain services and trigger events

Operations

• Can perform operations throughout different Domain Namespaces
• Inside operations, you can call factory commands, instance commands and domain services

Scope overview

	Factory command	Instance command	Domain service	Events	Agents	Operation
Factory command				o
Instance command				o
Domain service	o	o	o	o
Events					o
Agents	o	o	o	o
Operation	o	o	o

Related links to our learning center

Course Implement API Operations