Overview
class-plus
is a simple class builder utility, which adds support for specifying class member variables as well as mix-ins. It does this by providing a custom API that augments an ES2015 class with custom features.
Why
Native JavaScript classes (introduced in ECMAScript 2015) are a welcome addition to the language, but two things bother me about them:
- You cannot declare properties inside the class (you have to do it in the constructor, which I do not like).
- Yes, there is a TC39 proposal for this, but it's not yet available to normal users.
- Classes can only inherit from one single parent class.
I wrote the class-plus module to provide these features to ES2015 classes using a simple API, while offering some additional niceties. The full set of features are:
- Provide an easy API to generate classes with additions.
- Support for adding properties right above the class definition (as close to inside it as we can get).
- Support for multiple mix-ins, will merge both properties and methods from multiple classes.
- Support for adding static properties.
- Optional easy way to mix-in the Node.js EventEmitter class.
- Optional hook system (async event emitters).
- Optional automatic conversion of callback methods to async ones.
- No dependencies
Usage
Use npm to install the module:
npm install class-plus
Then use require()
to load it in your code:
const Class = require('class-plus');
Then call Class()
to create classes. The function takes two arguments: an object with properties for the class, and the class definition itself (in native ES2015 format). Example:
const Animal = Class({
nickname: '',
color: ''
},
class Animal {
constructor(new_name, new_color) {
this.nickname = new_name;
this.color = new_color;
}
getInfo() {
return("Nickname: " + this.nickname + "\nColor: " + this.color);
}
});
This defines a class called Animal
, with two member variables, nickname
and color
, a constructor and a getInfo()
method which returns the nickname and color. Usage of this class is exactly what you would expect:
var dog = new Animal('Spot', 'Green');
console.log( dog.getInfo() );
Of course, you can also access the class member variables, as all members are public.
dog.nickname = 'Skippy';
dog.color = 'Blue';
console.log( dog.getInfo() );
Creating Subclasses
To create a subclass that inherits from a base class, use the built-in extends
keyword:
const Bear = Class({
wants: 'Honey'
},
class Bear extends Animal {
roar() {
console.log("Roar! Give me " + this.wants + "!");
}
});
This defines a Bear
class which inherits from the base Animal
class, including its constructor. What we did is extend the base class by introducing a new member variable wants
, and a new method roar()
. Everything else from the base class will be present in subclass instances.
var grizzly = new Bear('Fred', 'Brown');
console.log( grizzly.getInfo() );
grizzly.wants = 'blood';
grizzly.roar();
Calling Superclass methods
You can also explicitly invoke a superclass method using the built-in super
keyword:
const Bear = Class({
wants: 'Honey'
},
class Bear extends Animal {
roar() {
console.log("Roar! Give me " + this.wants + "!");
}
getInfo() {
var info = super.getInfo();
info += "\nWants: " + this.wants;
return info;
}
});
So here we are overriding the base class getInfo()
method, but the first thing we do is call the superclass method of the same name. This is done using the super
keyword, which points to the parent class.
Static Members
While the native built-in class system supports static methods it doesn't support non-function static members.
Using class-plus you can define static class members (variables or methods) by using the __static
property. These members do not become part of class instances, but instead live inside the class reference object, and must be accessed that way too. Example class definition:
const Beer = Class({
__static: {
types: ['Lager', 'Ale', 'Stout', 'Barleywine']
},
name: '',
type: ''
},
class Beer {
constructor(new_name, new_type) {
this.name = new_name;
if (Beer.types.indexOf(new_type) == -1) throw("Type not known: " + new_type);
this.type = new_type;
}
getInfo() {
return("Name: " + this.name + "\nType: " + this.type);
}
});
Here we define a Beer
class which has a static member defined in the __static
property. Anything placed there will not be propagated to class instances, and must be accessed using the class reference variable instead (e.g. Beer
in the above example). As you can see in the constructor, we are checking the new type against the types
array which is declared static, so we are getting to the list by using the syntax: Beer.types
rather than this.types
.
If you were to change Beer.types
later on, then all classes would see the changes instantly. The content is effectively shared.
Mix-ins
While achieving mix-ins (essentially multiple inheritance) is technically possible using ES2015 classes, the syntax leaves much to be desired.
Using class-plus you can simply merge in one or more "mix-in" classes using the __mixins
property. This will import all the variables, methods and static members from the specified classes, excluding constructors. Example:
const Liquid = Class({ flavor: "sweet" }, class Liquid {});
const Glass = Class({ size: 8 }, class Glass {});
const Soda = Class({
__mixins: [ Liquid, Glass ]
},
class Soda {
drink() {
console.log("Yum, " + this.size + " oz of " + this.flavor + " drink!");
}
});
In the above example we are importing all the variables and methods of the Liquid
and Glass
classes into our Soda
class. Then, they are accessible using the normal this
keyword, as if they were defined in the class.
I often use mix-ins to spread my larger classes across multiple source files, like this:
const Soda = Class({
__mixins: [ require('./liquid.js'), require('./glass.js') ]
},
... );
Note that mix-in properties and methods will only be imported if they aren't already defined in your class. Meaning, they will not clobber any existing class members.
If the mix-in classes you are importing have their own parent classes, those should be separately listed in the __mixins
array. Meaning, the prototype chain of the mix-ins is not automatically imported -- only the top-level methods and properties on the specified class are merged in. You'll need to specify parent classes if you want those merged in as well.
Event Emitters
I find myself frequently inheriting from Node's EventEmitter in my classes, so I added a shortcut for it in class-plus. Simply include a property named __events
and set it to true
, and your class will magically become an EventEmitter. Example:
const Party = Class({
__events: true
},
class Party {
start() {
console.log("Let's get this party started!");
this.emit('dance');
}
});
var birthday = new Party();
birthday.on('dance', function() {
console("I'm dancing!");
} );
birthday.start();
Setting the __events
property is equivalent to including Node's EventEmitter class in your mix-ins array:
const Party = Class({
__mixins: [ require('events').EventEmitter ]
},
... );
So __events
is really just a shortcut for that.
Hooks
Taking event listeners one step further, class-plus introduces an optional "hook" system for use in your classes, where custom events can be hooked, and you can run asynchronous operations in each listener. If multiple listeners are registered on a given hook, they are all fired in sequence. If any listener returns an error, the sequence is aborted, and the error passed to the original caller.
Your listeners can be either callback based, or native async functions. To enable hooks in your class, simply include a __hooks
property and set it to true
. Example:
const Party = Class({
__hooks: true
},
class Party {
start() { console.log("The party has finally started."); }
});
var birthday = new Party();
birthday.registerHook( 'prestart', function(item, callback) {
setTimeout( function() { callback(); }, 100 );
} );
birthday.fireHook( 'prestart', "Get ready!", function(err) {
birthday.start();
});
The idea here is similar with events, where one or more listeners can be registered, but in this case the hooks fire in an asynchronous manner, each with a callback to advance to the next listener, or to complete the hook sequence. In fact, the whole system can be used with native async functions (in Node 8+). Example:
const Party = Class({
__hooks: true
},
class Party {
start() { console.log("The party has finally started."); }
});
(async function() {
var birthday = new Party();
birthday.registerHook( 'prestart', async function(item) {
await myfunc();
} );
await birthday.fireHook( 'prestart', "Get ready!");
birthday.start();
})();
Async/Await Conversion
Node.js version 8 introduced native support for the async/await pattern. If your class has callback-based methods that you want to auto-convert into async/await, simply declare a __asyncify
property, and set it to true
:
var Sleeper = Class({
__asyncify: true
},
class Sleeper {
sleep(milliseconds, callback) {
setTimeout( function() { callback(); }, milliseconds );
}
});
This will automatically detect all your callback-based methods in the class, and then convert them to async using Node's util.promisify(), making them instantly ready for async/await. Example usage:
var snooze = new Sleeper();
async function main() {
await snooze.sleep( 1000 );
console.log("This happened 1 second later!");
};
main();
The automatic detection mechanism looks inside your method signatures for argument lists ending with the name callback
(or cb
). If you use any other variable name for the callback argument, this will skip over it. Also, class-plus will take care not asyncify a function that is already async.
If you only want some of your methods to be asyncified, set the __asyncify
property to an array containing all the method names. Example:
{
__asyncify: ["sleep"]
}
Alternatively, you can set __asyncify
to a regular expression, to match against all of your class method names. If the pattern matches, the function will be converted. Example:
{
__asyncify: /^(sleep|someOtherFunction)$/
}
Note that in order for your methods to be async-compatible, they must accept a callback as the final argument, and that callback must be called using the standard Node.js convention (i.e. (err)
or (err, result)
). The error must be the first argument sent to the callback (or false/undefined on success), and a result, if any, must be the second argument.
Async Return Values
If your callback is fired using the typical (err, result)
arguments, such as this:
const Soda = Class({
__asyncify: true
},
class Soda {
pour(callback) {
setTimeout( function() {
callback( null, "8oz" );
}, 250 );
}
});
Then you can access the result using async in this way:
let drink = new Soda();
try {
let result = await drink.pour();
console.log(result);
}
catch (err) {
throw err;
}
However, if your callback has multiple result arguments, like this:
const Soda = Class({
__asyncify: true
},
class Soda {
pour(callback) {
setTimeout( function() {
callback( null, 8, "oz" );
}, 250 );
}
});
They will be returned in an array which you can destruct like this:
let drink = new Soda();
try {
let [amount, units] = await drink.pour();
console.log(amount, units);
}
catch (err) {
throw err;
}
Finally, for ultimate control over the async conversion, you can pre-declare the names of your callback arguments in the __asyncify
property, by setting it to an object containing the function names as keys, and the argument names as array items. Then, the result can be awaited as a destructed object with named keys. Here is how to set this up in the class:
const Soda = Class({
__asyncify: {
pour: ['amount', 'units']
}
},
class Soda {
pour(callback) {
setTimeout( function() {
callback( null, 8, "oz" );
}, 250 );
}
});
And here is how to await it:
let drink = new Soda();
try {
let { amount, units } = await drink.pour();
console.log(amount, units);
}
catch (err) {
throw err;
}
The idea here is that the calling code can select which of the arguments it wants. For example, we can omit units
and only fetch amount
:
let { amount } = await drink.pour();
License
The MIT License
Copyright (c) 2019 - 2022 Joseph Huckaby
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.