Forem: Darcy Rayner

Introducing Colib 🎉

Darcy Rayner — Mon, 15 Apr 2019 04:27:35 +0000

Hey all! I'm writing this post to announce the v1 release of Colib, (short for Command Library), to the wild. Colib is a set of patterns we've been using for years to help build games and interactive media, beginning with a C# Unity Version, and now a new Typescript/Web implementation.

What is Colib?

Colib makes it easy to build complex sequences of timed logic and animations, without ending up in callback hell. At it's core, Colib is a libary of Commands that take time, and a set of tools to schedule those Commands.

An introductory example

Before we define just exactly what a Command is, let's look at an example of what you can do with Colib.

import { globalScheduler, waitForTime, parallel, changeTo, coroutine } from 'colib';

const scheduler = globalScheduler();
const obj = { x: 10, y: 100 };
scheduler.add(
  waitForTime(4.0),
  parallel(
    changeTo(obj, { y: 200 }, 3.0, inOutQuad()),
    sequence(
      waitForTime(1.5), () => {
      console.log('Reached');
    })
  ),
  coroutine(aCoroutine)
);

function *aCoroutine() {
  console.log("Starting Coroutine");
  for (let i = 0; i < 3; ++i) {
    yield waitForTime(0.5);
  }
  console.log("Finished Coroutine");
}

Here we see a couple of Commands used, sequence, parallel, waitForTime, changeTo, and coroutine . Let's break down the whole thing step by step.

Breakdown

scheduler.add(
    //...
)

The global scheduler used here will run the commands. Commands don't do anything until something runs them.

waitForTime(4)

Waits 4 seconds, before execution continues onto the next Command.

parallel(
    //...
)

Executes all its child commands at the same time.

changeTo(obj, {y: 200}, 3.0, inOutQuad())

Tweens the value of obj.y to 200, over a duration of 3 seconds, using the inOutQuad() ease.

sequence(
    //...
)

Executes all its child commands one after the other. Because this sequence is nested inside a parallel command, the entire sequence is executing at the same time as the changeTo command.

waitForTime(1.5)

Waits 1.5 seconds, before execution continues onto the next command.

() => { console.log('Reached') }

A callback command that logs "Reached" to the console.

coroutine(aCoroutine)
//...
function *aCoroutine() {
  console.log("Starting Coroutine");
  for (let i = 0; i < 3; ++i) {
    yield waitForTime(0.5);
  }
  console.log("Finished Coroutine");
}

This launches a coroutine. Basically coroutines are ES6 generators, where you can yield any Command. That command will complete before execution of the function resumes. In this example, aCoroutine logs 'Started Coroutine', waits for 0.5 seconds three times in a row, then logs 'Finished Coroutine'.

Commands

So now we've seen a few commands in action, but what are they? Commands are functions that can consume time, and return whether they are completed or not. Take a look at the following (simplified) function signature of a command:

export type Command = (deltaTime: number) => { deltaTime: number; complete: boolean };

A command takes the maximum amount of time it's allowed to advance by, deltaTime, and returns any remaining unused time and whether it completed or not. Typically commands are implemented as closure functions so they track state internally. This means most commands are impure, (they have side effects).

So, the definition of a Command is simple, but it can used to build some incredibly cool and complex behaviours. As we saw in our example, parallel and sequence allow commands to easily be composed together in different ways. Other common commands worth checking out that can be used for composition include repeat, repeatForever, and chooseRandom.

Other Stuff

Colib is a super flexible set of tools. Check out the guides on different ways to schedule commands, available tweening utilities, and advanced coroutine patterns. There are also a lot of built in commands available.

Feedback Welcome

Feel free to raise bugs of the Github issues page, or suggest features.

Happy Sequencing!

Typescript Dependency Injection in 200 LOC

Darcy Rayner — Wed, 23 Jan 2019 02:00:53 +0000

One of the most common patterns in object oriented programming is dependency injection, and the inversion of control principle, (IOC). IOC containers are often feature packed, complex beasts that can stump even seasoned programmers. They take a collection of types with dependencies and when you need an instance of something they can automagically wire one up for you.

You might have seen Typescript containers in frameworks like Angular, and NestJs with their module systems. Or maybe you are using a stand alone container like Inversify.

One of the best ways to demystify programming concepts is to go out and build it yourself, so this article will build a minimal toy container step by step. But first…

A quick history lesson

Back yonder during the framework wars of 2014, some Google engineers had run into a problem. They had been working on Angular 2 when they realised the language they were building it in, Typescript, had a fatal flaw. It was kind of a deal breaker, so they did what Google engineers do in these kinds of situations. They invented a new language. It was called AtScript.

I'm not here to rehash the history of AtScript. Anders Hejlsberg,(creator of Typescript), gives his short version of it here. Like Anders mentions in his talk, Typescript at the time was missing two crucial features which AtScript was meant to address; Decorators and Reflection. And they were the secret sauce that made makes IOC in Typescript possible.

Decorators

If you've used a Typescript container before, you've probably seen something like this:

@Injectable()
class SomeService {
    constructor(private anotherService: AnotherService) {}
}

At the top there we have the Injectable decorator. The decorator is saying this class can have its dependencies automatically injected.

A decorator is a function which wraps a class, function or method and adds behaviour to it. This is useful for defining metadata associated with an object. It also ties into the way reflection works in Typescript.

Reflection

In order to know which things to wire up, we need to be able to inspect types at runtime. Let's look at how Javascript does things before getting to Typescript.

const a = "hello there";
const b = 0b1;
console.log(typeof a); // "string";
console.log(typeof b); // "number";

While it isn't perfect, Javascript does support a degree of basic runtime reflection. Besides the primitive types of the language, (num, boolean, object, string, array etc), classes also carry runtime information:

class Alpha {}
const a = new Alpha();
a instanceof Alpha; // true

We can also inspect the class's prototype to get a list of methods. But that's where we start to hit some limits. There is no easy way to extract the names of class properties or method parameters. Traditional pure javascript containers would use hacks like casting the function or class to a string and manually parsing that string to get the names of each parameter/property. That name would then be used by the container to lookup the correct dependency. Of course, this would fail if you ran a minifier over your code, because all those parameter names would change. This was a common issue with Angular 1, and the work arounds involved a lot of redundancy.

So, vanilla Javascript doesn't help us much in the reflection department. To combat this, Typescript uses a library called reflect-metadata to store additional type information. For instance, Typescript types assigned to parameters and properties are made available at runtime. It is enabled with the 'emitDecoratorMetadata' compiler option.

@SomeDecorator()
function someFunc(a: number, b: string){}
Reflect.getMetadata('design:types', someFunc); // Number, String

There are two catches though:

Classes/functions must have a decorator for them to save metadata.
Only classes/enums/primitive types can be recorded. Interfaces and union types come through as 'Object'. That's because these types disappear entirely after compilation, whereas classes hang around.

Anyway, that's enough background for now. If Typescript decorators/reflect-metadata are still confusing you, go check out the official tutorial.

The Code

Our container is going to use two main concepts. Tokens and Providers. Tokens are an identifier for something that our container needs to know how to create, and providers describe how to create them. With that in mind, a minimal public interface for the Container class looks like this.

export class Container {
    addProvider<T>(provider: Provider<T>) {} // TODO
    inject<T>(type: Token<T>): T {} // TODO
}

Now let's define our Token. Tokens can either refer to a class or, in cases where the parameter type doesn't give enough context about what to inject, a constant attached to a parameter with a decorator.

const API_URL_TOKEN = new InjectionToken('some-identifier');
const TWITTER_TOKEN = new InjectionToken('another-identifier');
class SomeClass {
    // Both AService, API_URL_TOKEN, and TWITTER_URL_TOKEN are all tokens.
    // We will define the Inject decorator later.    
    constructor(b: AService, @Inject(API_URL_TOKEN) apiURL: string, @Inject(TWITTER_URL_TOKEN) twitterUrl: string) {}
}

Our definition for Tokens looks like this:

// We use this to refer to classes.
export interface Type<T> extends Function {
    // Has a constructor which takes any number of arguments. 
    // Can be an implicit constructor.   
    new (...args: any[]): T; 
}

export class InjectionToken {
    constructor(public injectionIdentifier: string) {}
}

// Our combined Token type
Token<T> = Type<T> | InjectionToken;

Next, let's define the Providers. There are three different Provider types we will implement. One for providing an existing value as a singleton, one for providing via a factory function, and one for providing just the class name to use.

// Every provider maps to a token.
export interface BaseProvider<T> {
    provide: Token<T>;
}

export interface ClassProvider<T> extends BaseProvider<T> {
    useClass: Type<T>;
}

export interface ValueProvider<T> extends BaseProvider<T> {
    useValue: T;
}

// To keep things simple, a factory is just a function which creates the type.
export type Factory<T> = () => T;

export interface FactoryProvider<T> extends BaseProvider<T> {
    useFactory: Factory<T>;
}

export type Provider<T> = ClassProvider<T> | ValueProvider<T> | FactoryProvider<T>;

For convenience let's throw in some type guards as well.

export function isClassProvider<T>(provider: BaseProvider<T>): provider is ClassProvider<T> {
    return (provider as any).useClass !== undefined;
}
export function isValueProvider<T>(provider: BaseProvider<T>): provider is ValueProvider<T> {
    return (provider as any).useValue !== undefined;
}
export function isFactoryProvider<T>(provider: BaseProvider<T>): provider is FactoryProvider<T> {
    return (provider as any).useFactory !== undefined;
}

This is pretty good for our base API. We just need to define two decorators before we are ready to implement the container.

// This class decorator adds a boolean property to the class
// metadata, marking it as 'injectable'. 
// It uses the reflect-metadata API.
const INJECTABLE_METADATA_KEY = Symbol('INJECTABLE_KEY');
export function Injectable() {
    return function(target: any) {
        // target in this case is the class being decorated.    
        Reflect.defineMetadata(INJECTABLE_METADATA_KEY, true, target);
        return target;
    };
}
// We also provide an easy way to query whether a class is
// injectable. Our container will reject classes which aren't
// marked as injectable.
export function isInjectable<T>(target: Type<T>) {
    return Reflect.getMetadata(INJECTABLE_METADATA_KEY, target) === true;
}

And we define the Inject decorator, which maps a parameter to another Token.

const INJECT_METADATA_KEY = Symbol('INJECT_KEY');
// This is a parameter decorator, it takes a token to map the parameter to.
export function Inject(token: Token<any>) {
    return function(target: any, _: string | symbol, index: number) {
        Reflect.defineMetadata(INJECT_METADATA_KEY, token, target, `index-${index}`);
        return target;
    };
}
export function getInjectionToken(target: any, index: number) {
    return Reflect.getMetadata(INJECT_METADATA_KEY, target, `index-${index}`) as Token<any> | undefined;
}

The Container

The implementation for adding providers is fairly simple. You can see it is just a simple key value store. The providers map uses any types, but we know the Token and Provider will always match because the only way to insert into that map is with the addProvider method.

class Container {
    private providers = new Map<Token<any>, Provider<any>>();

    addProvider<T>(provider: Provider<T>) {
        this.assertInjectableIfClassProvider(provider);
        this.providers.set(provider.provide, provider);
    }
    // ...
}

We use the assertInjectableIfClassProvider method to make sure all the classes which are provided to the container have been marked as Injectable, and therefore have metadata. This isn't strictly necessary, but it will help us catch issues at configuration time.

class Container {
    // ...
    private assertInjectableIfClassProvider<T>(provider: Provider<T>) {
        if (isClassProvider(provider) && !isInjectable(provider.useClass)) {
            throw new Error(
            `Cannot provide ${this.getTokenName(provider.provide)} using class ${this.getTokenName(
                provider.useClass
            )}, ${this.getTokenName(provider.useClass)} isn't injectable`
            );
        }
    }

    // Returns a printable name for the token.
    private getTokenName<T>(token: Token<T>) {
        return token instanceof InjectionToken ? token.injectionIdentifier : token.name;
    }
    // ...
}

Next we have our injection function. This first method looks up the provider, and the second method determines which type of provider it is, then handles each case separately.

class Container {
    // ...
    inject<T>(type: Token<T>): T {
        let provider = this.providers.get(type);
        return this.injectWithProvider(type, provider);
    }

    private injectWithProvider<T>(type: Token<T>, provider?: Provider<T>): T {
        if (provider === undefined) {
            throw new Error(`No provider for type ${this.getTokenName(type)}`);
        }
        if (isClassProvider(provider)) {
            return this.injectClass(provider as ClassProvider<T>);
        } else if (isValueProvider(provider)) {
            return this.injectValue(provider as ValueProvider<T>);
        } else {
            // Factory provider by process of elimination
            return this.injectFactory(provider as FactoryProvider<T>);
        }
    }
    // ...
}

The value and factory providers are pretty straight forward. One is a method call, one just returns a value. The class provider is a little more complex, it needs to construct the items in the parameter list for the constructor, and then invokes the constructor using the class reference.

class Container {
    // ...
    private injectValue<T>(valueProvider: ValueProvider<T>): T {
        return valueProvider.useValue;
    }

    private injectFactory<T>(valueProvider: FactoryProvider<T>): T {
        return valueProvider.useFactory();
    }

    private injectClass<T>(classProvider: ClassProvider<T>): T {
        const target = classProvider.useClass;
        const params = this.getInjectedParams(target);
        return Reflect.construct(target, params);
    }
    // ...
}

The implementation for building the parameter list is where things get tricky. We invoke the reflect-metadata API in order to get a list of types for each parameter of the constructor. For each of those parameters, we find the relevant token, and then construct is recursively.

public class Container {
    // ...
    private getInjectedParams<T>(target: Type<T>) {
        const argTypes = Reflect.getMetadata(REFLECT_PARAMS, target) as (InjectableParam | undefined)[];
        if (argTypes === undefined) {
            return [];
        }
        return argTypes.map((argType, index) => {
            // The reflect-metadata API fails on circular dependencies,
            // and will return undefined for the argument instead.
            // We could handle this better, but for now let's just throw an error.
            if (argType === undefined) {
                throw new Error(
                    `Injection error. Recursive dependency detected in constructor for type ${
                    target.name
                    } with parameter at index ${index}`
                );
            }
            // Check if a 'Inject(INJECTION_TOKEN)' was added to the parameter.
            // This always takes priority over the parameter type.
            const overrideToken = getInjectionToken(target, index);
            const actualToken = overrideToken === undefined ? argType : overrideToken;
            let provider = this.providers.get(actualToken);
            return this.injectWithProvider(actualToken, provider);
        });
    }
}

Using it

That's it for the implementation. Here's what it looks like using our new container.


const API_TOKEN = new InjectionToken('api-token');

@Injectable()
class SomeService {
    constructor(@Inject(API_TOKEN)) {}
}

@Injectable()
class InjectableClass {
    constructor(public someService: SomeService) {}
}

const container = new Container();

container.addProvider({ provide: API_TOKEN, useValue: 'https://some-url.com' });
container.addProvider({ provide: SomeService, useClass: SomeService });
container.addProvider({ provide: InjectableClass, useClass: InjectableClass });

const instance = container.inject(InjectableClass);

Conclusion

While the toy container we built here was fairly simple, it's also powerful. You can already see the bones of how other more advanced containers are built. A working demo repository with tests and documentation can be found here. If you are up for a challenge, fork it and see if you can extend it with the following features:

Early detection of circular references, (when you add your providers).
Nested containers, add the ability to provide types from child containers, (similar to Angular/NestJs modules).
Factories with injected parameters.
Specifiy scope of instance lifecycle in providers, (eg. singleton).