Services

What is a service?

Sodacore treats services as a way to encapsulate a "thing", i.e. a http server, a websocket server, etc. A service is usually some kind of server or long running process that's main aim is to listen and dispatch events to the application, like a HTTP server.

• What is a service?
• Events
• Dispatching
• Creating a service
• Decorators.
• Using the service.
• Conclusion

Events

A service has built-in events that the framework will automatically dispatch, you should aim to listen to these and react to them accordingly.

Event	Description
init	Called as the framework is being initialised, you should use this to define configs and maybe even initialise your service.
start	Called when the server actually "starts" this is when you should actually start the service, i.e. telling the http server to listen.
stop	Called when the server is being stopped, this is where you should stop the service, i.e. telling the http server to close.

The above are the default events/methods the framework will look for, all of them are async and should return a promise.

Dispatching

Now you might assume, that the framework will deal with dispatching a service to a controller for you, this is not the case unfortunately, but for a good reason. When it comes to services, we understand that a "router" will NOT be able to cater for EVERY type of use case, for example the way slash commands in Discord dispatch events compared to a HTTP server are very different with different parameters, and we don't want to restrict your ability like that.

So how do we do it then? Simple, decorators and metadata.

If you are building a service maybe as a plugin for the framework or a feature for your own project, then the actual implementation is up to you, but we have libraries for making working with decorators easier, to see some examples, feel free to look at the HTTP & Discord plugin's decorators and service for examples.

• HTTP Plugin Decorators
• HTTP Plugin Service
• Discord Plugin Decorators
• Discord Plugin Service
• Discord Plugin Router

As you can see, for the Discord plugin, we actually made a separate router, mostly because there is a lot of different types of events that can come through, and we wanted to make it easier to read and handle, you can of course do the same.

Also make sure you extend the BaseService, this will help with the methods you need to override.

Creating a service

Regardless, let's create a service, this service is going to be stupid simple, it's going to create a timer that runs every 60 seconds, when it does, it will dispatch an event to the framework.

import { Service, BaseService } from '@sodacore/core';

@Service()
export default class TimerService extends BaseService {
	private timer: number | null = null;
	private controllers: any[] = []; // We expect you to type this yourself of course.

	public async init() {

		// Collect all of the registry modules.
		const modules = Registry.all();
		for (const module of modules) {

			// Get the type and services array for the module.
			const type = Utils.getMeta('type', 'autowire')(module.constructor);
			const services = Utils.getMeta<string[]>('services', 'controller')(module.constructor, undefined, []);

			// Check for valid type and service it is for.
			if (!type || !services.includes('timer')) continue;

			// If a controller type.
			if (type === 'controller') {
				this.controllers.push(module);
				continue;
			}
		}
	}

	public async start() {
		this.timer = setInterval(() => {
			this.dispatch();
		}, 60_000);
	}

	public async stop() {
		clearInterval(this.timer!);
	}

	private async dispatch() {
		for (const controller of this.controllers) {
			if (controller.onTimer) {
				controller.onTimer.bind(controller)();
			}
		}
	}
}

So let's understand we have done here:

1. We import the Service and BaseService from the @sodacore/core package.
2. We create a new class called TimerService.
3. We use the @Service decorator to tell the framework that this is a service.
4. We create a private property called timer and set it to null.
5. We create an init method that will collect all of the modules from the registry and then filter out the controllers, and then store them in the controllers array.
6. We create a start method that will start a timer that will dispatch an event every 60 seconds.
7. We create a stop method that will stop the timer.
8. We create a dispatch method that will loop through all of the controllers and call the onTimer method if it exists.

For context, the autowire will automatically register everything within the src folder, that has the correct autowire type applied to it, so in this case, we simply are just looking for the controllers that relate to our service specifically, it will automatically initialise them as well, so remember you have to look at the constructor for the decorators.

Decorators.

Now we have a controller, we need to create a decorator that we can assign to a controller, let's do that.

import { Utils } from '@sodacore/di';

export default function Timer() {
	return (target: any) => {
		Utils.setMeta('type', 'autowire')(target, 'controller');
		const services = Utils.getMeta<string[]>('services', 'controller')(target, undefined, []);
		services.push('timer');
		Utils.setMeta('services', 'controller')(target, services);
	};
}

And that's it, voila. We have a decorator that we (or another user) can apply to a controller so they can receive the event from the service.

Using the service.

Simple.

import { Timer } from '../decorators/timer';

@Timer()
export class SomeController {
	public async onTimer() {
		console.log('Timer has run!');
	}
}

Conclusion

And that's it, you have a service that will dispatch an event to a controller every 60 seconds, we could make this better, by using more decorators to help tell the framework what method to look for, so it doesn't have to assume one, or even creating an interface for the user/or yourself to enforce the required method.

Of course this is a very simple use case, but I am hoping you understand the basis of how services work and how you can use them in your application if you need to, or if you intend to write a library around something else, then 1. thank you, and 2. I hope this guide has helped you understand how to structure your service.