README
A simple lightweight JavaScript library for adding abstract methods to types which, when called, report a useful error indicating that they have not been implemented/overridden on the child type.
Install
Install using the package manager for your desired environment(s):
$ npm install --save pollock
# OR:
$ bower install --save pollock
If you want to simply download the file to be used in the browser you can find them below:
- Development Version (4.6kb - Source Map)
- Production Version (723b - Source Map)
API
The API couldn't be simpler and consists of a single function, pollock
:
pollock(type, methodName[, options])
The most common use case is to add an abstract instance method to a type (i.e. it's prototype) which, when called, throws an error:
class GraphicObject {
constructor(x, y) {
this.x = x;
this.y = y;
}
moveTo(newX, newY) {
// ...
}
}
pollock(GraphicObject, 'draw');
pollock(GraphicObject, 'resize');
class Circle extends GraphicObject {
draw() {
// ...
}
resize() {
// ...
}
}
class Rectangle extends GraphicObject {
draw() {
// ...
}
}
By declaring the abstract methods draw
and resize
, it will make it much easier/quicker to discover cases where
children of that type have not implemented those methods, but it's important to note it's only reported if/when the
method is called.
const circle = new Circle(0, 0);
circle.draw();
circle.resize();
const rect = new Rectangle(50, 50);
rect.draw();
rect.resize();
//=> Error(GraphicObject#resize abstract method is not implemented)
The examples in this document are all using ECMAScript 2015 classes, which your code may not be. Don't worry though, pollock works with ECMAScript Version 5 as well. ECMAScript 2015 classes were used mainly because they better demonstrate the inheritance without the noise of different type extension mechanisms.
Static Methods
While pollock creates instance methods by default, enabling the static
option will result in the abstract method being
assigned directly to the type instead, effectively making it static.
class GraphicObject {
// ...
}
pollock(GraphicObject, 'getEdges', { static: true });
class Circle extends GraphicObject {
static getEdges() {
return 1;
}
// ...
}
class Rectangle extends GraphicObject {
// ...
}
This behaves exactly as you'd expect it to and the only difference is in the error message; the character separating the type and method names is different. This is to help differentiate such cases while debugging as, in theory, a single type could have two abstract methods with the same name; one instance and one static.
Circle.getEdges();
//=> 1
Rectangle.getEdges();
//=> Error(GraphicObject.getEdges abstract method is not implemented)
Asynchronous Methods
In most cases, throwing an error as soon as the abstract method is called is best, regardless of whether the method is intended to be synchronous or asynchronous in nature. However, pollock is flexible and allows you to easily support two of the most common asynchronous patterns should you wish: callbacks and promises.
Callback
In order to have the abstract method invoke a callback function with the error instead of it being thrown, you just need
to specify the index of the callback argument via the callback
option.
class UserService {
getUserCount(callback) {
this.getUsers((error, users) => {
if (error) {
callback(error);
} else {
callback(null, users.length);
}
});
}
}
pollock(UserService, 'getUser', { callback: 1 });
pollock(UserService, 'getUsers', { callback: 0 });
class UserServiceImpl extends UserService {
getUsers(callback) {
// ...
}
}
Now the error will be passed to the specified callback function argument when invoked.
const userService = new UserServiceImpl();
userService.getUser(123, (error) => {
//=> Error(UserService#getUser abstract method is not implemented)
});
If the value of the callback
option is negative (i.e. less than zero), then it will be applied to the end of argument
list passed to the abstract method. For example; to always treat the last argument as the callback function argument,
pass -1
.
If the specified index is invalid or does not match an argument that is a function, then the abstract method will fall back on throwing the error instead.
Promise
For the abstract method to return a ECMAScript 2015 Promise
that has been rejected with the error instead of it being
thrown, simply enable the promise
option.
class UserService {
getUserCount() {
return this.getUsers()
.then((users) => users.length);
}
}
pollock(UserService, 'getUser', { promise: true });
pollock(UserService, 'getUsers', { promise: true });
class UserServiceImpl extends UserService {
getUser(id) {
// ...
}
}
Done!
const userService = new UserServiceImpl();
userService.getUsers()
.catch((error) => {
//=> Error(UserService#getUsers abstract method is not implemented)
});
If the current environment does not support ECMAScript 2015's Promise
, which is tested by detecting whether it's in
the global scope, then the abstract method will fall back on throwing the error instead.
Custom Type Name
The type name that is reported in the error message can be controlled using the typeName
option. The type name
resolution occurs in the following order:
typeName
option, if specifiedtype.name
property value, if available"<anonymous>"
otherwise
This can be useful for cases where your code is minified and you don't want errors like "p#lock abstract method is not implemented" or you're using a library/framework that creates the constructor function for you and results in the assigned name being lost/distorted.
const GraphicObject = Nevis.extend({
// ...
});
pollock(GraphicObject, 'draw', { typeName: 'GraphicObject' });
pollock(GraphicObject, 'resize', { typeName: 'GraphicObject' });
Bugs
If you have any problems with pollock or would like to see changes currently in development you can do so here.
Contributors
If you want to contribute, you're a legend! Information on how you can do so can be found in CONTRIBUTING.md. We want your suggestions and pull requests!
A list of pollock contributors can be found in AUTHORS.md.
License
Copyright © 2018 Alasdair Mercer
See LICENSE.md for more information on our MIT license.