Typescript compatible fork of Justin Fagnani's Mixin library mixwith.js
npm install mixwith.tsA TypeScript fork of Justin Fagnani's excellent mixwith.js library that supports TypeScript type completions at design time.
mixwith differs from other mixin approaches because it does not copy properties from one object to another. Instead, mixwith works with "subclass factories" which create a new class that extends a superclass with the mixin.
my-mixin.ts:
``typescript`
const MyMixin = (s: Constructable) => class extends s {
// mixin methods here
}
my-class.ts
`typescript`
class MyClass extends mix(MySuperClass).with(MyMixin) {
// class methods here, go ahead, use super!
}Installation
Using npm
``
npm i mixwith.ts
Using deno
``
import {mix, Constructable } from "https://deno.land/x/mixwithts/mod.ts"
Classes use mixins in their extends clause. Classes that use mixins can define and override constructors and methods as usual. In conflicts, the right most Mixin wins.
`typescript
class MySuperClass {
// ...
}
const MyMixin =
foo() {}
}
class MyClass extends mix(MySuperClass).with(MyMixin) {
foo() {
super.foo() // calls MyMixin.foo()
}
}
`
To use contructors and make sure the base class constructors are called, mixins consume and pass along constructor arguments using a constructor with ...args: any. Mixins can optionally consume constructor arguments as well:
` typescript
class MySuperClass {
constructor(numArg : number, strArg: string) {
}
}
const MyMixin =
class Mix1 extends s {
constructor(...args: any[]) {
super(...args);
}
};
class MixedClass extends mix(MySuperClass).with(MyMixin) {
constructor(numArg : number, strArg: string) {
super(numArg, strArg);
}
}
const myInstance : MixedClass = new MixedClass(42, "hello world");
`
In this example, I model a 2D war game that has common functionality across units (shooters, spawners, etc.).
`typescript
// deno-lint-ignore-file no-unused-vars
import type { Constructable } from "./mod.ts";
import {mix } from "./mod.ts";
interface Position {
xPos: number;
yPos: number;
}
class AirForce implements Position {
xPos = 0;
yPos = 0;
}
class GroundForce implements Position {
xPos = 0;
yPos = 0;
}
const bomber =
bomb() { }
}
const shooter =
shoot() { }
}
//Notice that this takes a 'Position' type since
//it needs to refer back to its super class (which implements Position)
const spawner =
spawn() {
//spawn logic for things that spawn
this.yPos = Math.random() * 100;
this.xPos = Math.random() * 100;
}
}
//airplanes spawn, shoot, and bomb
class Airplane extends mix(AirForce).with(spawner, shooter, bomber) { }
//helicopters spawn and shoot
class Helicopter extends mix(AirForce).with(spawner, shooter) { }
//tanks spawn and shoot
class Tank extends mix(GroundForce).with(spawner, shooter) { }
//fortifications don't spawn in, but do shoot
class fortification extends mix(GroundForce).with(shooter) { }
// You can also skip the final class definition, but intent is less clear
const myJetFighter = new (mix(AirForce).with(spawner, shooter))
`
#### API & Functional changes
The builder MixinBuilder and its supporting method mix() were modified:
- MixinBuilder.with() accepts up to six mixins rather than an array. This change was made to enable design time TypeScript completions. The source code can be modified to support more mixins as needed.MixinBuilder.with()
- applies instanceOf support for mixins automatically
To resolve Mixins at design time, two types were defined.
`typescript `
export type Constructable
export type mixin
- Constructable defines a constructor function (can be called with new) that creates instances of objects of type T. mixin
- defines a function that takes a Constructable and returns a new type T.
TypeScript will infer both T and C implicitly. However, if you want to refer to a super's properties from a mixin without red squigglies, reference it.
`typescript
//open ended mixin. Use to add new functionality to any type
const openMix = (s: Constructable) => class extends s...
//closed mixin. Use to apply to a specific interface or class
const closedMix = (s: Constructable
`
The subclass factory pattern does not require a library. This library makes working with the pattern more powerful and easier to use.
* Determine if an object or class has had a particular mixin applied to it.
* Cache mixin applications so that a mixin repeatedly applied to the same superclass reuses its resulting subclass.
* De-duplicate mixin application so that including a mixin multiple times in a class hierarchy only applies it once to the prototype type chain.
* Add instanceof support to mixin functions. That is, the following test passes
`typescript
class MyClass extends mix(MySuperClass).with(MyMixin) {
// class methods here, go ahead, use super!
}
const foo = new MyClass();
assert(foo instanceof MySuperClass); //true
assert(foo instanceof MyMixin); //true
`
Subclass factory style mixins preserve the object-oriented inheritance properties that classes provide, like method overriding and super calls, while letting you compose classes out of mixins without being constrained to a single inheritance hierarchy, and without monkey-patching or copying.
#### Method overriding that just works
Methods in subclasses can naturally override methods in the mixin or superclass, and mixins override methods in the superclass. This means that precedence is preserved - the order is: _subclass_ -> _mixin__1_ -> ... -> _mixin__N_ -> _superclass_.
#### super works
Subclasses and mixins can use super normally, as defined in standard Javascript, and without needing the mixin library to do special chaining of functions.
#### Mixins can have constructors
Since super() works, mixins can define constructors. Combined with ES6 rest arguments and the spread operator, mixins can have generic constructors that work with any super constructor by passing along all arguments.
#### Prototypes and instances are not mutated
Typical JavaScript mixins usually used to either mutate each instance as created, which can be bad for performance and maintainability, or modify a prototype, which means every object inheriting from that prototype gets the mixin. Subclass factories don't mutate objects, they define new classes to subclass, leaving the original superclass intact.
• MixinBuilder: Class MixinBuilder
MixinBuilder helper class (returned by mix()).
#### Type parameters
| Name | Type |
| :------ | :------ |
| Base | extends Constructable |
#### Defined in
Method: with()
`ts`
with(
a,
b?,
c?,
d?,
e?,
f?): Base & A & B & C & D & E & F
Applies a chain of mixins to a base class. The method supports up to six mixins.
The mixins are applied in reverse sequence (e.g. the right most mixin is applied first, etc.)
| Parameter |
| :------ |
| A extends Constructable |B
| extends Constructable |C
| extends Constructable |D
| extends Constructable |E
| extends Constructable |F
| extends Constructable |
| Parameter | Type | Description |
| :------ | :------ | :------ |
| a | mixin\< Base, A \> | A mixin to apply. |b
| ? | mixin\< A, B \> | A mixin to apply (optional). |c
| ? | mixin\< B, C \> | A mixin to apply (optional). |d
| ? | mixin\< C, D \> | A mixin to apply (optional). |e
| ? | mixin\< D, E \> | A mixin to apply (optional). |f
| ? | mixin\< E, F \> | A mixin to apply (optional). |
Base & A & B & C & D & E & F
- A new class constructor that includes the functionalities
of all mixins and the base class.
▸ BareMixin<C, T\>(mixin): mixin
A basic mixin decorator that applies the mixin using the apply function so that it
can be used with isApplicationOf, hasMixin, and other mixin decorator functions.
#### Type parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| C | extends Constructable | The constructor type representing the original superclass. |T
| | T | The return type of the mixin function. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| mixin | mixin
#### Returns
mixin
- A new mixin function.
#### Defined in
___
▸ Cached<C, T\>(mixin): mixin
Decorates mixin so that it caches its applications. When applied multiplemixin
times to the same superclass, will only create one subclass, memoize
it and return it for each application.
Note: If mixin somehow stores properties its classes constructor (staticmixin
properties), or on its classes prototype, it will be shared across all
applications of to a super class. It's reccomended that mixin only
access instance state.
#### Type parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| C | extends Constructable | The type of the constructor of the mixin. |T
| | T | The type of the mixin instance. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| mixin | mixin
#### Returns
mixin
- Returns the cached mixin application.
#### Defined in
___
▸ DeDupe<C, T\>(mixin): mixin
Decorates mixin so that it only applies if it's not already on the
prototype chain.
#### Type parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| C | extends Constructable | The constructor type representing the original superclass. |T
| | T | The return type of the mixin function. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| mixin | mixin
#### Returns
mixin
- A deduplicated mixin that extends the original superclass if needed.
#### Defined in
___
▸ HasInstance<T\>(mixin): T
Adds a Symbol.hasInstance implementation to the provided mixin object to enable the use of the
instanceof operator with instances of classes that include the mixin.
#### Type parameters
| Name | Description |
| :------ | :------ |
| T | The type of the mixin object. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| mixin | T | The mixin object to be enhanced with the Symbol.hasInstance implementation. |
#### Returns
T
- The mixin object with the Symbol.hasInstance implementation.
#### Defined in
___
▸ Mixin<C, T\>(mixin): mixin
Decorates a mixin function to add deduplication, application caching, and instanceof support.
#### Type parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| C | extends Constructable | The constructor type representing the original superclass. |T
| | T | The return type of the mixin function. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| mixin | mixin
#### Returns
mixin
- A new mixin function.
#### Defined in
___
▸ apply<C, T\>(superclass, mixin): T
Applies mixin to superclass.
apply stores a reference from the mixin application to the unwrapped mixinisApplicationOf
to make and hasMixin work.
This function is useful for mixin wrappers that want to automatically enable
hasMixin support.
#### Type parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| C | extends Constructable | The constructor type of the superclass. |T
| | T | The resulting type of the mixin. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| superclass | C | The superclass to which the mixin will be applied. |mixin
| | mixin
#### Returns
T
- A new class with the mixin's behavior applied.
#### Defined in
___
▸ hasMixin<T\>(o, mixin): boolean
Checks if the provided mixin has been applied to the given prototype object.
#### Type parameters
| Name | Description |
| :------ | :------ |
| T | The type of the mixin. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| o | object | - |mixin
| | T | A mixin function used with apply. |
#### Returns
boolean
- Returns true if the mixin has been applied, otherwise false.
#### Defined in
___
▸ isApplicationOf<T\>(proto, mixin): boolean
Returns true iff proto is a prototype created by the application ofmixin to a superclass.
isApplicationOf works by checking that proto has a reference to mixinapply
as created by .
#### Type parameters
| Name | Description |
| :------ | :------ |
| T | The type of the mixin. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| proto | object | A prototype object created by apply. |mixin
| | T | A mixin function used with apply. |
#### Returns
boolean
whether proto is a prototype created by the application ofmixin to a superclass
#### Defined in
___
▸ mix<C\>(superclass?): MixinBuilder
A fluent interface to apply a list of mixins to a superclass.
`typescript`
class X extends mix(Object).with(A, B, C) {}
The mixins are applied in order to the superclass, so the prototype chain
will be: X->C'->B'->A'->Object.
This is purely a convenience function. The above example is equivalent to:
`typescript`
C = Mixin(C)
B = Mixin(B)
A = Mixin(A)
class X extends C(B(A(Object))) {}
Function
#### Type parameters
| Name | Type |
| :------ | :------ |
| C | extends Constructable |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| superclass? | C | The superclass to which the mixin will be applied. If not defined, it defaults to class {}. |
#### Returns
MixinBuilder
- A builder object to apply mixins to the superclass.
#### Defined in
___
▸ unwrap<T\>(wrapper): T
Unwraps the function wrapper to return the original function wrapped bywrap
one or more calls to . Returns wrapper if it's not a wrapped
function.
#### Type parameters
| Name | Description |
| :------ | :------ |
| T | The type of the wrapped mixin. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| wrapper | T | The wrapped mixin. |
#### Returns
T
- Returns the original mixin if available, otherwise the wrapper itself.
#### Defined in
___
▸ wrap<C, T\>(mixin, wrapper): mixin
Sets up the function mixin to be wrapped by the function wrapper, whilemixin
allowing properties on to be available via wrapper, and allowingwrapper to be unwrapped to get to the original function.
wrap does two things:mixin
1. Sets the prototype of to wrapper so that properties set onmixin
inherited by wrapper.mixin
2. Sets a special property on that points back to mixin so thatwrapper
it can be retreived from
Function
#### Type parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| C | extends Constructable | The type of the constructor of the mixin. |T
| | T | The type of the mixin instance. |
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| mixin | mixinwrapper` | mixin
|
#### Returns
mixin
- Returns the wrapper mixin.
#### Defined in