HowToCreateAService

How to create a service

This tutorial will demonstrate some more advanced topics related to the creation of services. We recommend reading the simpler How to use a service tutorial first.

Creating the service class

In this section, we will create a MathService in a new package.

First, create the directory src/packages/math with the following required package files (see also Package reference):

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({});

1
{
2
    "name": "math",
3
    "private": true
4
}

The service’s implementation is trivial. It provides a simple method to the users that multiplies two numbers:

1
export class MathServiceImpl {
2
    multiply(a: number, b: number): number {
3
        return a * b;
4
    }
5
}

We must export it from the services.ts (or .js) so it can be found by the framework later:

1
export { MathServiceImpl } from "./MathServiceImpl";

Note
The file name MathServiceImpl.ts is arbitrary. Only the export from the services.ts matters here.

Now, declare the service in your build.config.mjs. We provide the single interface "math.MathService":

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    services: {
5
        MathServiceImpl: {
6
            provides: "math.MathService"
7
        }
8
    }
9
});

Note
A service can provide many interfaces at the same time. See Service reference and Package reference.

Testing the service

We will create a simple unit test that calls the multiply method. The test framework Vitest (opens in a new tab) is preconfigured in this repository. It will automatically pick up all *.test.* files in all packages and execute their tests (see also How to write tests).

Before creating the test, add @open-pioneer/test-utils to your package’s devDependencies. The test-utils package contains helpers for testing service classes:

1
{
2
    "name": "math",
3
    "private": true,
4
    "devDependencies": {
5
        "@open-pioneer/test-utils": "catalog:"
6
    }
7
}

After that, execute pnpm install:

1
$ pnpm install

Now create the test file:

1
import { it, expect } from "vitest";
2
import { createService } from "@open-pioneer/test-utils/services";
3
import { MathServiceImpl } from "./MathServiceImpl";
4

5
it("multiplies two numbers", async () => {
6
    const service = await createService(MathServiceImpl);
7
    expect(service.multiply(3, 4)).toEqual(12);
8
});

The test creates a new service instance by calling the createService helper and then tests the result of multiply(...) by using Vitest’s expect API (opens in a new tab).

We can run pnpm test to execute all tests in this repository, which is Vitest’s default behavior. For this example, we will only execute tests in the math directory for the sake of simplicity:

1
$ pnpm test  src/packages/math
2
# > starter@ test <PROJECT_DIR>
3
# > vitest "src/packages/math"
4
#
5
#
6
#  DEV  v0.28.5 <PROJECT_DIR>/src
7
#
8
#  ✓ packages/math/MathServiceImpl.test.ts (1)
9
#
10
#  Test Files  1 passed (1)
11
#       Tests  1 passed (1)
12
#    Start at  12:15:10
13
#    Duration  1.98s (transform 1.33s, setup 0ms, collect 1.35s, tests 16ms)

Using the service

We will also add our first ‘real’ use of the service by editing the empty app.

First, add the packages math and @open-pioneer/chakra-snippets in the app’s package.json:

1
{
2
    "name": "empty",
3
    "private": true,
4
    "dependencies": {
5
        "@chakra-ui/react": "catalog:",
6
        "@open-pioneer/runtime": "catalog:",
7
        "sample-package": "workspace:*",
8
        "@open-pioneer/chakra-snippets": "catalog:",
9
        "math": "workspace:*"
10
    }
11
}

Then, run pnpm install to update the package’s node_modules directory.

In the build.config.mjs, add a reference from the UI to the interface "math.MathService":

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    ui: {
5
        references: ["math.MathService"]
6
    }
7
});

In the app’s UI, we call the service when a button is pressed by the user:

1
import { Button, Container, HStack, Text, VStack } from "@chakra-ui/react";
2
import { NumberInputRoot, NumberInputField } from "@open-pioneer/chakra-snippets/number-input";
3
import { useService } from "open-pioneer:react-hooks";
4
import { useState } from "react";
5

6
export function AppUI() {
7
    const [leftValue, setLeftValue] = useState("3");
8
    const [rightValue, setRightValue] = useState("4");
9
    const [result, setResult] = useState<number | undefined>();
10
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
11
    const service = useService("math.MathService") as any; // (1)
12
    const onMultiplyClicked = () => {
13
        setResult(service.multiply(leftValue, rightValue)); // (2)
14
    };
15

16
    return (
17
        <Container>
18
            <VStack>
19
                <Text>Multiply two numbers:</Text>
20
                <HStack>
21
                    <NumberInputRoot value={leftValue} onValueChange={(e) => setLeftValue(e.value)}>
22
                        <NumberInputField />
23
                    </NumberInputRoot>
24
                    <NumberInputRoot
25
                        value={rightValue}
26
                        onValueChange={(e) => setRightValue(e.value)}
27
                    >
28
                        <NumberInputField />
29
                    </NumberInputRoot>
30
                    <Button onClick={onMultiplyClicked}>Multiply!</Button>
31
                </HStack>
32
                <Text>The result is: {result}</Text>
33
            </VStack>
34
        </Container>
35
    );
36
}

(1) Retrieves the reference to our math service. Note that we are currently casting to any here: this is because the interface name has not been associated with a type yet. We will do that later.

Do not use the actual class name (MathServiceImpl) here, since that is private to the package and may contain additional implementation details. When using a private service (e.g. inside the same package), using that class would be okay.
(2) Calls the multiply method on the service. This callback is triggered by the <Button> element. The result is stored into the component’s state via setResult() and will be displayed by the bottommost <Text> element.

Your UI should look like this:

Multiplication UI

Integrating with TypeScript

This section is optional when you’re mainly using JavaScript or if your service is private to your package. If you plan to have your service used by others, providing good TypeScript integration is highly recommended.

Back in the math package, we will define the public interface for "math.MathService". Pure interface descriptions are conventionally placed into a file called api.ts, but they should also be exported from the package’s main entry point (usually index.ts) for convenience.

Because we do not intend to export any classes, functions or constants, we’ll just make api.ts our main for now:

1
{
2
    "name": "math",
3
    "private": true,
4
    "main": "api.ts",
5
    "devDependencies": {
6
        "@open-pioneer/test-utils": "catalog:"
7
    }
8
}

The api.ts contains an interface definition and registers that interface with the interface name "math.MathService":

1
import { DeclaredService } from "@open-pioneer/runtime";
2

3
/**
4
 * Provides math operations.
5
 *
6
 * Use the interface `"math.MathService"` to inject an instance of this service.
7
 */
8
export interface MathService extends DeclaredService<"math.MathService"> {
9
    // (1)
10
    /**
11
     * Multiplies the two numbers and returns the result.
12
     */
13
    multiply(a: number, b: number): number;
14
}

(1)
This associates the type with the given interface name at compile time. Whenever one writes useService<MathService>("math.MathService"), the compiler will automatically check that one has not accidentally mistyped the string argument.

This means that we can now also remove the as any cast in AppUI.tsx:
```
1
const service = useService("math.MathService") as any;
2
const service = useService<MathService>("math.MathService");
```

Finally, now that we have an interface, we’ll also implement it in our service class:

1
import { MathService } from "./api";
2

3
export class MathServiceImpl implements MathService {
4
    multiply(a: number, b: number): number {
5
        return a * b;
6
    }
7
}

Referencing all services that provide a certain interface

Services have the powerful capability to gather all services that provide a certain interface name by specifying all: true in the build.config.mjs.

This can be used, for example, to implement an extension API: a user may add its own services into the inner workings of another service by providing an interface.

This section demonstrates how to do that by adding a simple extension API to the MathService: clients will be called whenever someone triggers a call to multiply.

This time, we will start with the TypeScript integration.

Creating the TypeScript API for the new interface

In your api.ts, add another interface:

1
// ...
2
/**
3
 * An extension to the math service.
4
 * Implementors are notified by the math service whenever a computation was triggered.
5
 *
6
 * Provide the interface `"math.MathServiceExtension"` to be called by the math service.
7
 */
8
export interface MathServiceExtension extends DeclaredService<"math.MathServiceExtension"> {
9
    /** Called when `multiply` was called on the math service. */
10
    onMultiply(a: number, b: number, result: number): void;
11
}

Gathering and using all services providing the interface

In the configuration file, we gather all services providing that extension interface:

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    services: {
5
        MathServiceImpl: {
6
            provides: "math.MathService",
7
            references: {
8
                // Injects all implementations of that interface as an `extensions` array
9
                extensions: {
10
                    name: "math.MathServiceExtension",
11
                    all: true
12
                }
13
            }
14
        }
15
    }
16
});

On the implementation side, we now use the constructor argument of type ServiceOptions. This argument is automatically created by the framework when the service is instantiated. options.references contains the array of extensions we’ve requested in the build.config.mjs:

1
import { ServiceOptions } from "@open-pioneer/runtime";
2
import { MathService, MathServiceExtension } from "./api";
3

4
interface References {
5
    extensions: MathServiceExtension[];
6
}
7

8
export class MathServiceImpl implements MathService {
9
    private extensions: MathServiceExtension[];
10

11
    constructor({ references }: ServiceOptions<References>) {
12
        this.extensions = references.extensions; // (1)
13
    }
14

15
    multiply(a: number, b: number): number {
16
        const result = a * b;
17
        for (const ext of this.extensions) {
18
            ext.onMultiply(a, b, result); // (2)
19
        }
20
        return result;
21
    }
22
}

(1) Saves the array of references in our service instance.
(2) Forwards the arguments and the result to each extension.

Updating the tests

If you left vitest running, you will have noticed that our original test is failing. This is because our test code does not provide the extensions array and therefore throws an error when attempting to iterate it in multiply().

We will update the test with an empty array and, while we’re at it, add a test for the new feature:

1
import { it, expect } from "vitest";
2
import { createService } from "@open-pioneer/test-utils/services";
3
import { MathServiceImpl } from "./MathServiceImpl";
4

5
it("multiplies two numbers", async () => {
6
    const service = await createService(MathServiceImpl, {
7
        references: {
8
            // (1)
9
            extensions: []
10
        }
11
    });
12
    expect(service.multiply(3, 4)).toEqual(12);
13
});
14

15
it("invokes the extensions when a multiplication is triggered", async () => {
16
    interface Event {
17
        from: string;
18
        a: number;
19
        b: number;
20
        result: number;
21
    }
22

23
    const events: Event[] = [];
24
    const service = await createService(MathServiceImpl, {
25
        references: {
26
            // (2)
27
            extensions: [
28
                {
29
                    onMultiply(a, b, result) {
30
                        events.push({
31
                            from: "first",
32
                            a,
33
                            b,
34
                            result
35
                        });
36
                    }
37
                },
38
                {
39
                    onMultiply(a, b, result) {
40
                        events.push({
41
                            from: "second",
42
                            a,
43
                            b,
44
                            result
45
                        });
46
                    }
47
                }
48
            ]
49
        }
50
    });
51

52
    // (3)
53
    service.multiply(4, 3);
54
    expect(events).toEqual([
55
        { from: "first", a: 4, b: 3, result: 12 },
56
        { from: "second", a: 4, b: 3, result: 12 }
57
    ]);
58
});

(1) Our original test now receives an empty array for extensions.
(2) Our new test contains two mocked extensions that simply write their arguments into a shared array.
(3) We call multiply and check that our extensions have been invoked by asserting the contents of the events array.

Implementing an actual service providing the interface

Now we will implement an extension class that simply logs all arguments to demonstrate that the system works as expected. Like before, we’ll use the empty app to do this.

In your app’s package.json, add a dependency to @open-pioneer/core. We want to use its logger implementation:

1
{
2
    "name": "empty",
3
    "private": true,
4
    "dependencies": {
5
        "@open-pioneer/core": "catalog:",
6
        "@chakra-ui/react": "catalog:",
7
        "@open-pioneer/runtime": "catalog:",
8
        "sample-package": "workspace:*",
9
        "@open-pioneer/chakra-snippets": "catalog:",
10
        "math": "workspace:*"
11
    }
12
}

Then, execute pnpm install to update your app’s dependencies.

In the build.config.mjs, declare a new service providing "math.MathServiceExtension":

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    i18n: ["en"],
5
    ui: {
6
        references: ["math.MathService"]
7
    },
8
    services: {
9
        LoggingMathExtension: {
10
            provides: ["math.MathServiceExtension"]
11
        }
12
    }
13
});

For this example, we’ll implement the class directly in the services.ts:

1
import { MathServiceExtension } from "math";
2
import { createLogger } from "@open-pioneer/core";
3
import { sourceId } from "open-pioneer:source-info";
4

5
const LOG = createLogger(sourceId);
6

7
export class LoggingMathExtension implements MathServiceExtension {
8
    onMultiply(a: number, b: number, result: number): void {
9
        LOG.info(`${a} * ${b} = ${result}`);
10
    }
11
}

Restart the empty app in your browser, open the console and click the “Multiply!” button. Your console should display a message just like this:

A note on service start behavior

By default, the framework will only start services that are actually required to run the app. It does so by starting the services required by the user interface (ui.references in each package’s build.config.mjs) or those required to implement the web component’s API (integration.ApiExtension), their dependencies, their dependencies and so on. An application may therefore contain services that are never required and thus never started (they might even be optimized out entirely in the future).

Service AutoStart

Some services should start as soon as their package is part of an application, for example to perform some side effect in the service’s constructor.

The preferred way to achieve this is to provide the runtime.AutoStart interface:

1
import { defineBuildConfig } from "@open-pioneer/build-support";
2

3
export default defineBuildConfig({
4
    services: {
5
        YourService: {
6
            provides: ["runtime.AutoStart"] // (1)
7
        }
8
    }
9
});

By providing the interface in (1), the framework will automatically instantiate your service. Of course, you can still provide any other interfaces just like usual.

NOTE: Services providing runtime.AutoStart are launched in arbitrary order. If you need to enforce starting order, add a dependency to the service(s) that must start before yours does.

If you’re curious: the framework still only starts referenced services. It just has an implicit dependency on all services implementing runtime.AutoStart, thus triggering their instantiation.