A small library to allow you to safely add 'dynamic properties' to objects, with the help of Symbols. This is useful (among other things) for 'monkey patching' native JavaScript types to give them new capabilities (seemetho-number,metho-set,metho-function,metho-array,andmetho-string).
Some examples of what is possible:
import*asMethofrom'metho'
constasHex=Metho.add(
Number.prototype,
function(){returnthis.toString(16)}
)
console.log(65534[asHex])// fffe
constupper=Metho.add(
String.prototype,
function(){returnthis.toUpperCase()}
)
constchunk=Metho.add(
String.prototype,
function(length){
returnthis.match(newRegExp('.{1,'+length+'}','g'))
}
)
console.log("Hello World!"[upper][chunk(2)])// ['HE', 'LL', 'O ', 'WO', 'RL', 'D!']
Metho is fairly simple, and offers 4 basic functions for adding these 'dynamic properties' to your target object(s). All functions will return either a Symbol, or a function that returns a Symbol. These Symbols are the property 'names'.
This is probably the function you'll need most often. It will use eitheraddWithParams
oraddSimple
based on the number of arguments the passed function expects - 0 will causeaddSimple
to be used, anything else will causeaddWithParams
oraddProperty
to be used - based upon the state of theouterSyntax
option. When added withouterSyntax
set totrue
- the syntax for your property will be that of a more regular function call:
// options.outerSyntax = false
object[property(x)]
// options.outerSyntax = true
object[property](x)
There is a slight performance hit when not usingouterSyntax
- hence the reason for the switch. To specify more than one target for the function, you should pass an array of targets.
Important note- it has been pointed out that functions with a default argument(s) that start from the first argument do not seem to work correctly with theadd
method. Whilst they doseemto behave oddly, they are actually behaving correctly as they do not actuallyexpectany arguments (for a clearer explanation, see the information aboutfunction.length
on MDN). If you want to add such methods you should use theaddWithParams
method directly.
Adds a 'dynamic property` that can accept parameters. If you wish to passnoparameters when calling it, you can simply omit the parentheses - this is particularly useful in the case of functions where all parameters have defaults or are entirely optional.
console.log(object[property(param1,param2)]// call the dynamic property and pass parameters
console.log(object[propertyWithDefaultParams])// equivalent to object[propertyWithDefaultParams()]
Adds a 'dynamic property` that has no parameters
console.log(object[property])
Adds a regular property to the target(s) (will not be automatically called if it is a function)
console.log(object[property])
Most, if not all of the below were added to facilitate the ability to have Metho 'methods' that can be shared between different targets in different libraries (e.g. the 'method' would acquire more capabilities when a second library is imported that uses it). For an example of this in action, please refer to themetho-stringandmetho-arraylibraries - where this functionality is used to create shared 'methods' such asreverse
andchunk
.
This is used to give a name to the generated Symbol (i.e. when it is created withnew Symbol(symbolName
)
Used to internally register the created/usedSymbol
(or function) in an internal registry within Metho - used in conjunctionsymbolName
which will become the 'key' in the registry
This allows an existing Symbol to be used instead of a new one being created. This is available only foraddProperty
andaddSimple
- meaning that it can also be passed toadd
This is a symbol created by Metho for the intended purpose of being a key to store arbitary 'data' on a target object
myTarget[Metho.data]="Arbitrary value"
This will return the Symbol or function stored in the registry with the given name as key
A convenience function to assist when adding new 'methods' to new targets, where the 'method' may already be in existence. This is best understood in conjunction withmetho-string
andmetho-array
mentioned above