search

tannerntannern / ts-mixer

A small TypeScript library that provides tolerable Mixin functionality.
MIT License
379 stars 27 forks source link
mixins typescript

readme

ts-mixer

npm version TS Versions Node.js Versions Minified Size Conventional Commits

Overview

ts-mixer brings mixins to TypeScript. "Mixins" to ts-mixer are just classes, so you already know how to write them, and you can probably mix classes from your favorite library without trouble.

The mixin problem is more nuanced than it appears. I've seen countless code snippets that work for certain situations, but fail in others. ts-mixer tries to take the best from all these solutions while accounting for the situations you might not have considered.

Quick start guide

Features

Caveats

  1. Mixing generic classes requires a more cumbersome notation, but it's still possible. See mixing generic classes below.
  2. Using decorators in mixed classes also requires a more cumbersome notation. See mixing with decorators below.
  3. ES6 made it impossible to use .apply(...) on class constructors (or any means of calling them without new), which makes it impossible for ts-mixer to pass the proper this to your constructors. This may or may not be an issue for your code, but there are options to work around it. See dealing with constructors below.
  4. ts-mixer does not support instanceof for mixins, but it does offer a replacement. See the hasMixin function for more details.
  5. Certain features (specifically, @decorator and hasMixin) make use of ES6 Maps, which means you must either use ES6+ or polyfill Map to use them. If you don't need these features, you should be fine without.

Quick Start

Installation

$ npm install ts-mixer

or if you prefer Yarn:

$ yarn add ts-mixer

Basic Example

import { Mixin } from 'ts-mixer';

class Foo {
    protected makeFoo() {
        return 'foo';
    }
}

class Bar {
    protected makeBar() {
        return 'bar';
    }
}

class FooBar extends Mixin(Foo, Bar) {
    public makeFooBar() {
        return this.makeFoo() + this.makeBar();
    }
}

const fooBar = new FooBar();

console.log(fooBar.makeFooBar());  // "foobar"

Special Cases

Mixing Generic Classes

Frustratingly, it is impossible for generic parameters to be referenced in base class expressions. No matter what, you will eventually run into Base class expressions cannot reference class type parameters.

The way to get around this is to leverage declaration merging, and a slightly different mixing function from ts-mixer: mix. It works exactly like Mixin, except it's a decorator, which means it doesn't affect the type information of the class being decorated. See it in action below:

import { mix } from 'ts-mixer';

class Foo<T> {
    public fooMethod(input: T): T {
        return input;
    }
}

class Bar<T> {
    public barMethod(input: T): T {
        return input;
    }
}

interface FooBar<T1, T2> extends Foo<T1>, Bar<T2> { }
@mix(Foo, Bar)
class FooBar<T1, T2> {
    public fooBarMethod(input1: T1, input2: T2) {
        return [this.fooMethod(input1), this.barMethod(input2)];
    }
}

Key takeaways from this example:

Mixing with Decorators

Popular libraries such as class-validator and TypeORM use decorators to add functionality. Unfortunately, ts-mixer has no way of knowing what these libraries do with the decorators behind the scenes. So if you want these decorators to be "inherited" with classes you plan to mix, you first have to wrap them with a special decorate function exported by ts-mixer. Here's an example using class-validator:

import { IsBoolean, IsIn, validate } from 'class-validator';
import { Mixin, decorate } from 'ts-mixer';

class Disposable {
    @decorate(IsBoolean())  // instead of @IsBoolean()
    isDisposed: boolean = false;
}

class Statusable {
    @decorate(IsIn(['red', 'green']))  // instead of @IsIn(['red', 'green'])
    status: string = 'green';
}

class ExtendedObject extends Mixin(Disposable, Statusable) {}

const extendedObject = new ExtendedObject();
extendedObject.status = 'blue';

validate(extendedObject).then(errors => {
    console.log(errors);
});

Dealing with Constructors

As mentioned in the caveats section, ES6 disallowed calling constructor functions without new. This means that the only way for ts-mixer to mix instance properties is to instantiate each base class separately, then copy the instance properties into a common object. The consequence of this is that constructors mixed by ts-mixer will not receive the proper this.

This very well may not be an issue for you! It only means that your constructors need to be "mostly pure" in terms of how they handle this. Specifically, your constructors cannot produce side effects involving this, other than adding properties to this (the most common side effect in JavaScript constructors).

If you simply cannot eliminate this side effects from your constructor, there is a workaround available: ts-mixer will automatically forward constructor parameters to a predesignated init function (settings.initFunction) if it's present on the class. Unlike constructors, functions can be called with an arbitrary this, so this predesignated init function will have the proper this. Here's a basic example:

import { Mixin, settings } from 'ts-mixer';

settings.initFunction = 'init';

class Person {
    public static allPeople: Set<Person> = new Set();

    protected init() {
        Person.allPeople.add(this);
    }
}

type PartyAffiliation = 'democrat' | 'republican';

class PoliticalParticipant {
    public static democrats: Set<PoliticalParticipant> = new Set();
    public static republicans: Set<PoliticalParticipant> = new Set();

    public party: PartyAffiliation;

    // note that these same args will also be passed to init function
    public constructor(party: PartyAffiliation) {
        this.party = party;
    }

    protected init(party: PartyAffiliation) {
        if (party === 'democrat')
            PoliticalParticipant.democrats.add(this);
        else
            PoliticalParticipant.republicans.add(this);
    }
}

class Voter extends Mixin(Person, PoliticalParticipant) {}

const v1 = new Voter('democrat');
const v2 = new Voter('democrat');
const v3 = new Voter('republican');
const v4 = new Voter('republican');

Note the above .add(this) statements. These would not work as expected if they were placed in the constructor instead, since this is not the same between the constructor and init, as explained above.

Other Features

hasMixin

As mentioned above, ts-mixer does not support instanceof for mixins. While it is possible to implement custom instanceof behavior, this library does not do so because it would require modifying the source classes, which is deliberately avoided.

You can fill this missing functionality with hasMixin(instance, mixinClass) instead. See the below example:

import { Mixin, hasMixin } from 'ts-mixer';

class Foo {}
class Bar {}
class FooBar extends Mixin(Foo, Bar) {}

const instance = new FooBar();

// doesn't work with instanceof...
console.log(instance instanceof FooBar)  // true
console.log(instance instanceof Foo)     // false
console.log(instance instanceof Bar)     // false

// but everything works nicely with hasMixin!
console.log(hasMixin(instance, FooBar))  // true
console.log(hasMixin(instance, Foo))     // true
console.log(hasMixin(instance, Bar))     // true

hasMixin(instance, mixinClass) will work anywhere that instance instanceof mixinClass works. Additionally, like instanceof, you get the same type narrowing benefits:

if (hasMixin(instance, Foo)) {
    // inferred type of instance is "Foo"
}

if (hasMixin(instance, Bar)) {
    // inferred type of instance of "Bar"
}

Settings

ts-mixer has multiple strategies for mixing classes which can be configured by modifying settings from ts-mixer. For example:

import { settings, Mixin } from 'ts-mixer';

settings.prototypeStrategy = 'proxy';

// then use `Mixin` as normal...

settings.prototypeStrategy

settings.staticsStrategy

settings.initFunction

settings.decoratorInheritance

Author

Tanner Nielsen tannerntannern@gmail.com