https://github.com/sha1n/fungus
An experimental library for starting and stopping multi-service environments correctly and efficiently based on declared dependencies between them
https://github.com/sha1n/fungus
bfs-algorithm dependencies dfs-algorithm directed-acyclic-graph nodejs testing-tool topological-sort typescript
Last synced: 2 months ago
JSON representation
An experimental library for starting and stopping multi-service environments correctly and efficiently based on declared dependencies between them
- Host: GitHub
- URL: https://github.com/sha1n/fungus
- Owner: sha1n
- License: mit
- Created: 2021-10-09T22:03:50.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-11-21T17:24:10.000Z (7 months ago)
- Last Synced: 2025-04-12T04:52:16.204Z (2 months ago)
- Topics: bfs-algorithm, dependencies, dfs-algorithm, directed-acyclic-graph, nodejs, testing-tool, topological-sort, typescript
- Language: TypeScript
- Homepage:
- Size: 8.38 MB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/sha1n/fungus/actions/workflows/ci.yml)
[](https://github.com/sha1n/fungus/actions/workflows/coverage.yml)
```
.-'~~~-.
.'o oOOOo`.
:~~~-.oOo o`.
`. \ ~-. oOOo.
`.; / ~. OO:
.' ;-- `.o.'
,' ; ~~--'~
; ;
_______\|/__________\\;_\\//___\|/________
```
# Fungus 🍄
Designed to harness backend integration testing environments, `Fungus` is a simple controller for starting and stopping multiple stateful services of virtually any kind, as long as they have `start` and `stop` semantics. A `Fungus` environment allows you to declare dependencies between services, so they can start up in the correct order and shut down in the correct order. It uses graph algorithms to minimize startup time and ensure clean shutdown.
- [Fungus 🍄](#fungus-)
- [Features](#features)
- [Usage](#usage)
- [Docker Services Demo](#docker-services-demo)
- [In-Memory Services Demo](#in-memory-services-demo)
- [Install](#install)
## Features
- Simple and lean API surface. Very easy to adopt or experiment with. The [`Service`](./lib/types.ts) interface is all you really have to implement.
- Easy to extend. The [`Docker`](./examples/docker/docker.ts) example shows how easy it is to create a generic docker based service and use it to control containers.
- A `RuntimeContext` API gives you access to metadata that is provided by any service in your environment. This is handy when you need to configure a service based on its dependencies. For example, you use a random database port and you want your app to get it before it starts up. The same context object is passed to all the services on startup and returned by the environment start method, so you can use it from the application or test.
## Usage
Here is a simple examples of how you create an environment and interact with it. For full working examples, see the demos [here](./examples).
```ts
// create services (implement the Service interface)
const storageService = createConfigService('my-config-service-id');
const mqService = ...;
const configService = ...;
const authService = ...;
const appService = ...;
// create an environment from a list of services and dependencies between them
const env = createEnvironment(
[
{
service: configService,
dependsOn: [storageService, mqService]
},
{
service: appService,
dependsOn: [configService, authService]
},
{
service: authService,
dependsOn: [configService]
}
],
{ name: 'my-env' }
);
// start all the services. Services start according to their level in the dependency graph and in parallel where possible (topological)
const context = await env.start();
// query the context for metadata returned by your services
const yourConfigServiceMetadata = context.catalog.get('my-config-service-id') as YourConfigServiceMetadata;
const configServiceUrl = yourConfigServiceMetadata.url;
...
// finally - stop all service in reverse order
await env.stop();
```
### Docker Services Demo
- A demo that uses Docker based services can be found [here](examples/docker/index.ts). This implementation relies on your shell environment and requires a Docker client and an available Docker daemon.
```
yarn install && yarn run docker-demo
```
### In-Memory Services Demo
- An in-memory services demo code can be found [here](examples/in-memory/index.ts).
```
yarn install && yarn run simple-demo
```
## Install
```
yarn add @sha1n/fungus
```
or
```
npm i @sha1n/fungus
```