A very small TypeScript library that provides tolerable Mixin functionality.
npm install ts-mixerts-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.
ts-mixerinstanceof-like replacement (with caveats [4, 5]).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.ts-mixer does not support instanceof for mixins, but it does offer a replacement. See the hasMixin function for more details.@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.
$ npm install ts-mixer
or if you prefer Yarn:
$ yarn add ts-mixer
$3
typescript
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
$3
Frustratingly, it is _impossible_ for generic parameters to be referenced in base class expressions. No matter what, you will eventually run into The way to get around this is to leverage declaration merging, and a slightly different mixing function from ts-mixer:
. 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:`typescript
import { mix } from 'ts-mixer';class Foo {
public fooMethod(input: T): T {
return input;
}
}
class Bar {
public barMethod(input: T): T {
return input;
}
}
interface FooBar extends Foo, Bar { }
@mix(Foo, Bar)
class FooBar {
public fooBarMethod(input1: T1, input2: T2) {
return [this.fooMethod(input1), this.barMethod(input2)];
}
}
`Key takeaways from this example:
*
makes sure FooBar has the typing we want, thanks to declaration merging
* @mix(Foo, Bar) wires things up "on the JavaScript side", since the interface declaration has nothing to do with runtime behavior.
* The reason we have to use the mix decorator is that the typing produced by Mixin(Foo, Bar) would conflict with the typing of the interface. mix has no effect "on the TypeScript side," thus avoiding type conflicts.$3
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:`typescript
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);
});
`$3
As mentioned in the caveats section, ES6 disallowed calling constructor functions without . 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:`typescript
import { Mixin, settings } from 'ts-mixer';settings.initFunction = 'init';
class Person {
public static allPeople: Set = new Set();
protected init() {
Person.allPeople.add(this);
}
}
type PartyAffiliation = 'democrat' | 'republican';
class PoliticalParticipant {
public static democrats: Set = new Set();
public static republicans: Set = 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
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
$3
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:`typescript
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
` will work anywhere that instance instanceof mixinClass works. Additionally, like instanceof, you get the same type narrowing benefits:`typescript
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 from ts-mixer. For example:`typescript
import { settings, Mixin } from 'ts-mixer';settings.prototypeStrategy = 'proxy';
// then use
Mixin as normal...
`$3
* Determines how ts-mixer will mix class prototypes together
* Possible values:
- (default) - Copies all methods from the classes being mixed into a new prototype object. (This will include all methods up the prototype chains as well.) This is the default for ES5 compatibility, but it has the downside of stale references. For example, if you mix Foo and Bar to make FooBar, then redefine a method on Foo, FooBar will not have the latest methods from Foo. If this is not a concern for you, 'copy' is the best value for this setting.
- 'proxy' - Uses an ES6 Proxy to "soft mix" prototypes. Unlike 'copy', updates to the base classes _will_ be reflected in the mixed class, which may be desirable. The downside is that method access is not as performant, nor is it ES5 compatible.$3
* Determines how static properties are inherited
* Possible values:
- 'copy' (default) - Simply copies all properties (minus prototype) from the base classes/constructor functions onto the mixed class. Like settings.prototypeStrategy = 'copy', this strategy also suffers from stale references, but shouldn't be a concern if you don't redefine static methods after mixing.
- 'proxy' - Similar to settings.prototypeStrategy, proxy's static method access to base classes. Has the same benefits/downsides.$3
* If set, ts-mixer will automatically call the function with this name upon construction
* Possible values:
- null (default) - disables the behavior
- a string - function name to call upon construction
* Read more about why you would want this in dealing with constructors$3
* Determines how decorators are inherited from classes passed to Mixin(...)
* Possible values:
- (default) - Deeply inherits decorators from all given classes and their ancestors
- 'direct' - Only inherits decorators defined directly on the given classes
- 'none'` - Skips decorator inheritance