README
custom-ability
generate the ability which can be added to any class directly. It makes custom ability more easy.
Sometimes, we still feel that the class is a little big, and too many features in it. We just need some of the features(methods) inside. So as a class developer can consider these functions to extract, as a kind of ability to the user.
Usage
Suppose we wanna add the RefCount ability to any class directly.
the RefCount
ability will add the following members to your class.
and you should implement the destroy
method which will be called
by release
/free
.
- properties:
RefCount
(integer): the reference count.
- methods:
release()
/free()
: Decrements reference count for this instance. If it is becoming less than 0, the object would be (self) destroyed.addRef()
: Increments the reference count for this instance and returns the new reference count.
Note: The same name of the methods will be replaced via the ability. These old methods will be lost. So, you must confirm whether there are the same methods in your class before you apply the new ability.
# ability.coffee
customAbility = require 'custom-ability'
class RefCountable
# define the instance methods here:
release: ->
result = --@RefCount
@destroy() unless result >= 0
result
free: @::release
addRef: ->
if not isUndefined @RefCount
++@RefCount
else
@RefCount = 1
# the class methods if any:
@someClassMethod: ->
# We set the `addRef` method as the core methods.
# The Core methods are the ability MUST have.
# they're used to check the same ability whether the ability already added.
module.exports = customAbility RefCountable, 'addRef'
Do not forget to add the "ability"
keyword to your package.json which means
the ability power with it.
// package.json
"keywords": [
"ability",
...
],
Do not forget to add the "ability.js"
file on your package root folder too.
now user use this ability like this:
refable = require 'ref-object/ability'
class MyClass
refable MyClass, exclude: '@someClassMethod' #someClassMethod would not be added to the class
destroy: ->console.log 'destroy'
my = new MyClass
my.addRef()
my.free() # nothing
my.free() # print the 'destroy' here.
More complicated example, you can see the events-ex/src/eventable.coffee.
additional $abilities
In order to make certain ability to work, you need to modify some methods of the class which could call the old(original) method. this time we need the "additional abilities" now. eg, the event-able ability to AbstractObject. We need to send a notification event when the state of the object changes(life cycle). So the event-able of AbstractObject should be:
eventable = require 'events-ex/eventable'
eventableOptions = require './eventable-options'
module.exports = (aClass, aOptions)->
eventable aClass, eventableOptions(aOptions)
# eventable-options.coffee
module.exports = (aOptions)->
aOptions = {} unless aOptions
aOptions.methods = {} unless aOptions.methods
extend aOptions.methods,
# override methods: (btw: classMethods to override the class methods)
setObjectState: (value, emitted = true)->
self= @self
@super.call(self, value)
self.emit value, self if emitted
return
...
return aOptions
# more detail on [AbstractObject/src/eventable-options.coffee](https://github.com/snowyu/abstract-object)
TODO: need to more explain:
The original eventable('events-ex/eventable')
is no useful for AbstractObject.
But we wanna the original eventable('events-ex/eventable')
knows the changes
and use it automatically.
eventable = require 'events-ex/eventable'
class MyClass
inherits MyClass, AbstractObject
eventable MyClass
you just do this on the AbstractObject:
AbstractObject = require('./lib/abstract-object')
AbstractObject.$abilities =
# "Eventable" is the AbilityClass name
Eventable: require('./lib/eventable-options')
module.exports = AbstractObject
API
just one function:
var customAbility = require('custom-ability')
customAbility(abilityClass[, coreMethod[, isGetClassFunction]])
arguments
- abilityClass (function): the class will become to abilitiable.
- coreMethod (string|arrayOf string): optional must have coreMethod(s).
- note:
@
prefix means class/static method.
- note:
- isGetClassFunction (boolean): the
AbilityClass
is afunction(aClass, aOptions)
to return the realAbility Class
if true. defaults to false.
return
- (function): a function which can inject the ability to any class directly.
This custom ability injection function has two arguments: function(class[, options])
class
: the class to be injected the ability.options
(object): optional optionsinclude
(array|string): only these methods will be added to the class- note:
@
prefix means class/static method.
- note:
exclude
(array|string): these methods would not be added to the class- note: the
coreMethod
could not be excluded. It's always added to the class. - note:
@
prefix means class/static method.
- note: the
methods
(object): injected/hooked methods to the class- key: the method name to hook.
- value: the new method function, if original method is exists or not in replacedMethods:
- use
this.super()
to call the original method. this.self
is the originalthis
object.
- use
classMethods
(object): hooked class methods to the class, it's the same usage as themethods
.replacedMethods
(array): the method name in the array will be replaced the original method directly.
Specification
V1.6.2
fix: use replace instead inject method if there is no such method on the target
const makeAbility = require('custom-ability') class Feature { $init() { const Super = this.super const that = this.self || this if (Super) { if (Super.apply(that, arguments) === 'ok') return } that._init.apply(that, arguments) } _init() {console.log('feature init')} } Feature.prototype.init = function() {this._init.apply(this, arguments)} const addFeatureTo = makeAbility(Feature) class My { } addFeatureTo(My) expect(My.prototype.init).toStrictEqual(Feature.prototype.init)
fix(1.6.1): the injectMethods(AOP) starting with "