``# Table of Contents

• Solidgrounds
  • Why should you use Solidgrounds
    • Typescript to the rescue
  • Features
  • Service registries
  • Setup
  • Service overrides & decorators
    • Overriding a service
    • Decorating a service
• Existing solidgrounds features
• Installation
• Facts
• Thanks
• Reads

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.

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:

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:

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.

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!');
  });

./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'.

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:

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:

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();
  });

./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':

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

() => ConsoleCommand[];

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

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.

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

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

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.

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.

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());

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

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

Registries can be fetched from the service container.

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.

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

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

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

./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:

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

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:

./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'

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),
});

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:

./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:

import { GreetingsServiceInterface } from './GreetingsServiceInterface';

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

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

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())),
});

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:

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

Existing solidgrounds features

• npm: Commander as a Solidgrounds Definition
• npm: Typescript loggers with an interface that support composition

Installation

To install the stable version:

yarn add @solidgrounds/core

This assumes you are using yarn as your package manager.

or

npm install @solidgrounds/core

Facts

• Supported both for Web and Node.
• Supported for 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 without the annotations.