@solidgrounds/core/README.md

Dependency injection container

``# Table of Contents

- [Solidgrounds](#solidgrounds)
  - [Why should you use Solidgrounds](#why-should-you-use-solidgrounds)
    - [Typescript to the rescue](#typescript-to-the-rescue)
  - [Features](#features)
  - [Service registries](#service-registries)
  - [Setup](#setup)
  - [Service overrides & decorators](#service-overrides-&-decorators)
    - [Overriding a service](#overriding-a-service)
    - [Decorating a service](#decorating-a-service)
- [Existing solidgrounds features](#existing-solidgrounds-features)
- [Installation](#installation)
- [Facts](#facts)
- [Thanks](#thanks)
- [Reads](#reads)

![Licence](https://img.shields.io/npm/l/solidgrounds.svg) [![Build Status](https://travis-ci.org/epinxteren/solidgrounds.svg?branch=master)](https://travis-ci.org/epinxteren/solidgrounds) [![npm version](https://badge.fury.io/js/solidgrounds.svg)](https://badge.fury.io/js/solidgrounds) ![coverage](https://github.com/epinxteren/solidgrounds/raw/master/docs/coverage.svg?sanitize=true)

# Solidgrounds

Your application is full of useful objects: a "HttpClient"
object might help you send requests while another object might help you save things to some storage. Almost everything
that your application "does" is actually done by one of these objects.

In Solidgrounds, these useful objects are called services and each service lives inside a very special object called the
service container. The approach how a service is constructed and configured is the definition of the service or in short
the service definition. The container allows you to centralize the way objects are constructed. It makes your life
easier, promotes a strong architecture. It’s a design pattern aiming to make high-level code reusable.

## Why should you use Solidgrounds

Solidgrounds is inspired by the idea that non-trival issues should not take your precious time and **infect** your
application code. **Solidgrounds** highly aims to keep away from your application code. By separating the service
definition from usage. **No magic** injection with tokens and/or annotations whatsoever. It will use your application
code as a **strictly typed interface** to assure everything is connected properly.

> Parkinson's law of solidgrounds is C. Northcote Parkinson's 1957 argument that members of an organization give disproportionate weight to trivial issues. Parkinson provides the example of a fictional committee whose job was to approve the plans for a nuclear power plant spending the majority of its time on discussions about relatively minor but easy-to-grasp issues, such as what materials to use for the staff bike shed, while neglecting the proposed design of the plant itself, which is far more important and a far more difficult and complex task.

### Typescript to the rescue

Solidgrounds uses the full power of Typescript to ensure the ServiceContainer is connected properly before your
application code even has executed.

> It's not required to use Typescript when using Solidgrounds, but it's highly recommended.

# Class

## Features

Solidgrounds by its core is split into features. Each feature has his own services definitions so it can serve it's
unique and there separate logic. A feature is defined as a function.

```typescript
import { FF } from '@solidgrounds/core';
import { LoggerInterface } from './LoggerInterface';
import { ConsoleLogger } from './ConsoleLogger';

export interface LogServices {
  logger: LoggerInterface;
}

export const LogFeature: FF<LogServices> = () => ({
  logger: () => new ConsoleLogger(),
});
```

As you can see a feature return factory functions. The function name is the service name. The function implementation is
the service definition. Before we can use the service from the service container we need to build it:

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { LogFeature } from './LogFeature';

solidgrounds()
  .add(LogFeature)
  .build()
  .then(({ logger }) => {
    logger.info('Hallo word');
  });
```

Now we can fetch the 'logger' service from the service container and start using it. In the build step of the container,
function results will be memorized and can be threaded as a singleton based on the service factory arguments. For
example, create a service with a single service factory argument:

```typescript
import { LoggerInterface } from '../features/LoggerInterface';
import { PrefixedLogger } from './PrefixedLogger';
import { FF } from '@solidgrounds/core';
import { ConsoleLogger } from '../features/ConsoleLogger';

export const createPrefixedLogger =
  (logger: LoggerInterface) =>
  (prefix: string): LoggerInterface => {
    return new PrefixedLogger(logger, prefix);
  };

export interface LogFeatureInstance {
  logger: LoggerInterface;
  prefixedLogger: (name: string) => LoggerInterface;
}

export const LogFeature: FF<LogFeatureInstance> = ({ services }) => ({
  logger: () => new ConsoleLogger(),
  prefixedLogger: () => createPrefixedLogger(services('logger').logger()),
});
```

The logger service function and the 'prefixedLogger' functions will always return the same instance for the same
arguments.

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { LogFeature } from './LogFeature';

solidgrounds()
  .add(LogFeature)
  .build()
  .then((container) => {
    const johnLogger = container.prefixedLogger('John:');
    johnLogger.info('Hallo Jane!');
    const janeLogger = container.prefixedLogger('Jane:');
    janeLogger.info('Hi John!');
  });
```

```bash
./node_modules/.bin/ts-node example/singleton/LogFeatureContainer.ts
John: Hallo Jane!
Jane: Hi John!
```

---

The service container inherited the service types from all added features. This gives typescript the option to **
strictly type check** if everything is connected properly. And you the benefits of **code completion** and the option to
quickly traverse the service chain.

---

We can inject the Feature with a Container that has multiple Feature dependencies `Container<...Feature>`. Let's put
the type checking to the test, we create a nice feature that dependence on the 'LogFeature'.

```typescript
import { FF } from '@solidgrounds/core';
import { LoggerInterface } from '../features/LoggerInterface';
import { HalloService } from './HalloService';

export interface HalloFeatureServices {
  halloServiceFactory: (name: string) => HalloService;
}

export interface HalloFeatureDependencies {
  logger: LoggerInterface;
}

export const HalloFeature: FF<HalloFeatureServices, HalloFeatureDependencies> =
  ({ logger }) => ({
    halloServiceFactory: () => (name: string) =>
      new HalloService(logger(), name),
  });
```

Build the service container with missing 'LogFeature' dependency:

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { HalloFeature } from './HalloFeature';

solidgrounds()
  .add(HalloFeature)
  .build()
  .then((container) => {
    const service = container.halloService('John');
    service.speak();
  });
```

If you forget a feature you see a nice error of typescript in your IDE.

    Error:(6, 8) TS2345: Argument of type 'typeof HalloFeature' is not assignable to parameter of type 'FeatureConstructor<HalloFeature, {}>'.
      Types of parameters 'container' and 'container' are incompatible.
        Property 'logger' is missing in type '{}' but required in type 'Readonly<Pick<LogFeature, "logger">>'.

Let's fix the service container by adding the LogFeature:

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { LogFeature } from '../singleton/LogFeature';
import { HalloFeature } from './HalloFeature';

solidgrounds()
  .add(LogFeature)
  .add(HalloFeature)
  .build()
  .then((container) => {
    const service = container.halloServiceFactory('John');
    service.speak();
  });
```

```bash
./node_modules/.bin/ts-node example/featureDependency/HalloFeatureContainer.ts
Hallo John
```

## Service registries

For solidgrounds a service registry is a collection of services that share a common interface. Multiple Features can _
register_ services to the service registry without knowing anything about the other features.

For example let's create a service register for 'console commands' the services that are registered should match the
common interface 'ConsoleCommand':

```typescript
import { ConsoleInput } from './ConsoleInput';
import { ConsoleOutput } from './ConsoleOutput';

export interface ConsoleCommand {
  name(): string;

  execute(input: ConsoleInput, output: ConsoleOutput): void | Promise<void>;
}
```

For solidgrounds a service registry is defined as a function

```typescript
() => ConsoleCommand[];
```

To define a registry inside a feature it needs to implement the 'registries' function.

```typescript
import { FF, RegistryList } from '@solidgrounds/core';
import { ConsoleCommand } from './ConsoleCommand';

export interface ConsoleFeatureServices {
  consoleCommands: RegistryList<ConsoleCommand>;
}

export const ConsoleFeature: FF<ConsoleFeatureServices> = ({
  registerList,
}) => ({
  consoleCommands: registerList(),
});
```

The 'registries' returns an associative-map, the key represents the name of the registry and the value the service
registry.

It's possible to add a registry to multiple feature. In the next examples, both feature return one command service
inside the registry function.

```typescript
import { FF } from '@solidgrounds/core';
import { ConsoleFeatureServices } from '../ConsoleFeature';
import { HalloConsoleCommand } from './HalloConsoleCommand';

export const HalloConsoleFeature: FF<{}, ConsoleFeatureServices> = ({
  registers: { consoleCommands },
  construct,
}) => ({
  ...consoleCommands(construct(HalloConsoleCommand)),
});
```

```typescript
import { FF } from '@solidgrounds/core';
import { ConsoleCommand } from '../ConsoleCommand';
import { ByeConsoleCommand } from './ByeConsoleCommand';
import { ConsoleFeatureServices } from '../ConsoleFeature';

interface ByeConsoleServices {
  byeConsoleCommand: ConsoleCommand;
}

export const ByeConsoleFeature: FF<ByeConsoleServices, ConsoleFeatureServices> =
  ({ registers: { consoleCommands }, construct, service }) => ({
    ...consoleCommands(service('byeConsoleCommand')),
    byeConsoleCommand: construct(ByeConsoleCommand),
  });
```

Multiple feature can define the registry. The implementation needs to match between features otherwise typescript will
assist you with strict type checking errors. During the service container build phase, the registries will be combined,
so all registry functions will return the complete combined result.

```typescript
import { ConsoleService } from './ConsoleService';
import { FF, RegistryList } from '@solidgrounds/core';
import { ConsoleCommand } from './ConsoleCommand';

export interface ConsoleFeatureServices {
  consoleCommands: RegistryList<ConsoleCommand>;
  consoleService: ConsoleService;
}

export const ConsoleFeature: FF<ConsoleFeatureServices> = ({
  registerList,
}) => {
  const consoleCommands = registerList<ConsoleCommand>();
  return {
    consoleCommands,
    consoleService: () => new ConsoleService(consoleCommands().toArray()),
  };
};
```

Now we can combine the different command feature and build the service container.

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { ByeConsoleFeature } from './Command/ByeConsoleFeature';
import { HalloConsoleFeature } from './Command/HalloConsoleFeature';
import { ConsoleFeature } from './ConsoleFeature';

solidgrounds()
  .add(ConsoleFeature)
  .add(HalloConsoleFeature)
  .add(ByeConsoleFeature)
  .build()
  .then((container) => container.consoleService.handle());
```

```bash
./node_modules/.bin/ts-node example/registries/console.ts hallo john
Hallo john
```

```bash
./node_modules/.bin/ts-node example/registries/console.ts bye john
Bye john !!!
```

Registries can be fetched from the service container.

!["containerRegistries"](./example/registries/containerRegistries.png)

Typescript will verify if registers interface matches over multiple Features. You can add an extra verify by adding
response type to the feature registry function.

## Setup

The build step returns a single promise, Each feature can have its own specific setup task. The feature can check if
everything is configured properly or connect to external service like a database.

```typescript
import { FF, SetupFeatureServices } from '@solidgrounds/core';
import { Database } from './Database';

export interface DatabaseFeatureServices {
  database: Database;
}

export const DatabaseFeature: FF<
  DatabaseFeatureServices,
  SetupFeatureServices
> = ({ registers: { setupCallbacks }, services, construct }) => ({
  ...setupCallbacks(() => () => {
    if (!services('database').database().isConnected()) {
      throw new Error('Database is not connected!');
    }
  }),
  database: construct(Database),
});
```

Add a catch function to gracefully handle errors

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { DatabaseFeature } from './DatabaseFeature';

solidgrounds()
  .add(DatabaseFeature)
  .build()
  .then((container) => {
    container.database.someFancyQuery();
  })
  .catch((error) => {
    process.stdout.write(`${error}
`);
  });
```

```bash
./node_modules/.bin/ts-node example/setup/bootstrap.ts
Error: Database is not connected!
```

## Service overrides & decorators

If you use an external feature, maybe you want to override some services. For example, we start with the following
greetings feature:

```typescript
import { CasualGreetingService } from './services/CasualGreetingService';
import { GreetingsServiceInterface } from './services/GreetingsServiceInterface';
import { FF } from '@solidgrounds/core';

export interface GreetingsFeatureServices {
  greetingService: GreetingsServiceInterface;
}

export const GreetingsFeature: FF<GreetingsFeatureServices> = () => ({
  greetingService: () => new CasualGreetingService(),
});
```

When we run

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { GreetingsFeature } from './GreetingsFeature';
import { LogFeature } from '../features/LogFeature';

solidgrounds()
  .add(LogFeature)
  .add(GreetingsFeature)
  .build()
  .then(({ logger, greetingService }) => {
    logger.info(greetingService.greet('Solidgrounds'));
  });
```

We get:

```bash
./node_modules/.bin/ts-node example/overrides/bootstrapGreetingsFeature.ts
Hallo Solidgrounds
```

### Overriding a service

If we want to use a different way to greet we need to override the 'greetingService'

```typescript
import { FF } from '@solidgrounds/core';
import { FormalGreetingsService } from './services/FormalGreetingsService';
import { GreetingsServiceInterface } from './services/GreetingsServiceInterface';
import { GreetingsFeatureServices } from './GreetingsFeature';

interface FormalGreetingsFeatureServices {
  formalGreetingsService: GreetingsServiceInterface;
}

export const FormalGreetingsFeature: FF<
  FormalGreetingsFeatureServices,
  GreetingsFeatureServices
> = ({ override: { greetingService }, service, construct }) => ({
  ...greetingService(service('formalGreetingsService')),

  formalGreetingsService: construct(FormalGreetingsService),
});
```

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { GreetingsFeature } from './GreetingsFeature';
import { LogFeature } from '../features/LogFeature';
import { FormalGreetingsFeature } from './FormalGreetingsFeature';

solidgrounds()
  .add(LogFeature)
  .add(GreetingsFeature)
  .add(FormalGreetingsFeature)
  .build()
  .then(({ logger, greetingService }) => {
    logger.info(greetingService.greet('Solidgrounds'));
  });
```

Now the original 'greetingService' service is overridden for the hole application. If we now run the example we get the
following result:

```bash
./node_modules/.bin/ts-node example/overrides/bootstrapFormalGreetingsFeature.ts
Pleased to meet you Solidgrounds
```

### Decorating a service

If we still we to use the original service from the service container. We can fetch the original service from the '
serviceOverrides' container argument.

Let's be less formal by screaming the sentence:

```typescript
import { GreetingsServiceInterface } from './GreetingsServiceInterface';

export class ScreamGreetingsService implements GreetingsServiceInterface {
  constructor(private speakService: GreetingsServiceInterface) {}

  public greet(name: string): string {
    return `${this.speakService.greet(name).toUpperCase()}!!!!!!`;
  }
}
```

```typescript
import { FF } from '@solidgrounds/core';
import { GreetingsServiceInterface } from './services/GreetingsServiceInterface';
import { ScreamGreetingsService } from './services/ScreamGreetingsService';
import { GreetingsFeatureServices } from './GreetingsFeature';

function decorateWithScreams(
  greeter: GreetingsServiceInterface
): GreetingsServiceInterface {
  return new ScreamGreetingsService(greeter);
}

export const ScreamGreetingsFeature: FF<unknown, GreetingsFeatureServices> = ({
  override: { greetingService },
}) => ({
  ...greetingService((original) => decorateWithScreams(original())),
});
```

```typescript
import { solidgrounds } from '@solidgrounds/core';
import { GreetingsFeature } from './GreetingsFeature';
import { LogFeature } from '../features/LogFeature';
import { ScreamGreetingsFeature } from './ScreamGreetingsFeature';

solidgrounds()
  .add(LogFeature)
  .add(GreetingsFeature)
  .add(ScreamGreetingsFeature)
  .build()
  .then(({ logger, greetingService }) => {
    logger.info(greetingService.greet('Solidgrounds'));
  });
```

Now the original 'greetingService' service is overridden and we get:

```bash
./node_modules/.bin/ts-node example/overrides/bootstrapScreamGreetingsFeature.ts
HALLO SOLIDGROUNDS!!!!!!
```

# Existing solidgrounds features

- npm: [Commander as a Solidgrounds Definition](https://www.npmjs.com/package/@solidgrounds/commander)
- npm: [Typescript loggers with an interface that support composition](https://www.npmjs.com/package/@solidgrounds/logger)

# Installation

To install the stable version:

```
yarn add @solidgrounds/core
```

This assumes you are using [yarn](https://yarnpkg.com) as your package manager.

or

```
npm install @solidgrounds/core
```

# Facts

- Supported both for _Web_ and _Node_.
- Supported for [es5](https://caniuse.com/#search=es5)
- All definition functions (registers, service overrides, feature setups) can be asynchronous (Promises based).
- Support for Definition circular dependencies.

# Thanks

Special thanks to:

- Eric Pinxteren
- Wessel van der Linden

# Reads

Solidgrounds is inspired by [disco](https://github.com/bitExpert/disco) without the annotations.