o-method-proxy v1.0.0

MethodProxy

Helper to create configurable Proxies.

What can I use a Proxy for?

Pretty much for anything you can possibly think of. Just try your best not to.

Here's a short list of topics where MethodProxy can be used:

• Transparent remote procedure calls
• Transparent lazy loading from a database, file or remote server
• Revertible object freezing
• Transparent persistency of objects to a database
• Transparent logging of an object method call
• Mock and stub objects
• Emulate traits and dynamically add behaviour to existing objects
• Implement dynamic public/private access to methods and properties
• Benchmark and trace method calls
• Transparent dynamic compilation or optimization of a method on its first call
• Implement syncronous Promises and Futures
• Transparent validation of methods parameters and object invariants

Take a look at the examples for some interesting uses of the MethodProxy.

On the other hand the use of Proxies may have a cost in performance, it difficults debugging quite a lot and care needs to be taken in aspects like the use of instaceof, typeof, chaining proxies, getOwnProperties , etc.

Installation

npm install o-method-proxy

Usage

Overriding an object method by the method name

Override a single method by its name.

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  proxy.on({
    method: 'setDescription', // override only the method 'setDescription'
    evaluate: function (proxy, target, methodName, args) {
      console.info(`setDescription was called on the object '${util.inspect(target)}' with arguments '${args}'`) // do something like logging the method call
      const targetMethod = targetObject[methodName]
      return Reflect.apply(targetMethod, proxy, args) // call the underlaying target method
    }
  })
}

// Get or create the target object
const targetObject = new Product()
// Wrap it with the proxy
const product = MethodProxy.on(targetObject, proxyDefinition)

// Then use the proxy as it if was the regular object
product.setDescription('A product')
product.getDescription()

Overriding many methods by name

Override many methods by name.

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  proxy.on({
    method: 'setDescription',
    evaluate: function (proxy, target, methodName, args) {
      console.info(`setDescription was called on the object '${util.inspect(target)}' with arguments '${args}'`)
      const targetMethod = targetObject[methodName]
      return Reflect.apply(targetMethod, proxy, args)
    }
  })
  proxy.on({
    method: 'setName',
    evaluate: function (proxy, target, methodName, args) {
      console.info(`setName was called on the object '${util.inspect(target)}' with arguments '${args}'`)
      const targetMethod = targetObject[methodName]
      return Reflect.apply(targetMethod, proxy, args)
    }
  })
}

// Get or create the target object
const targetObject = new Product()
const product = MethodProxy.on(targetObject, proxyDefinition)

// Then use the proxy as it if was the regular object
product.setDescription('A product')
product.getDescription()

Overriding many methods by name at once

Override many method by its name at once sharing the same override function.

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  proxy.on({
    methods: ['setDescription', 'setName']
    evaluate: function (proxy, target, methodName, args) {
      console.info(`${methodName} was called on the object '${util.inspect(target)}' with arguments '${args}'`)
      const targetMethod = targetObject[methodName]
      return Reflect.apply(targetMethod, proxy, args)
    }
  })
}

// Get or create the target object
const targetObject = new Product()
const product = MethodProxy.on(targetObject, proxyDefinition)

// Then use the proxy as it if was the regular object
product.setDescription('A product')
product.getDescription()

Overriding many methods matching a criteria

Override all the methods matching a criteria.

The matching block has the form

function(methodName, proxy, target) {
  return true|false
},

and it's expected to return true if the method should be overriden or false if not.

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  proxy.on({
    methodMatching: (methodName, proxy, target) => { return methodName.startsWith('set') },
    evaluate: function (proxy, target, methodName, args) {
      console.info(`${methodName} was called on the object '${util.inspect(target)}' with arguments '${args}'`)
      const targetMethod = targetObject[methodName]
      return Reflect.apply(targetMethod, proxy, args)
    }
  })
}

// Get or create the target object
const targetObject = new Product()
const product = MethodProxy.on(targetObject, proxyDefinition)

// Then use the proxy as it if was the regular object
product.setDescription('A product')
product.getDescription()

Overriding absent methods

Override only the methods that are not defined in the target object.

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  proxy.on({
    absentMethod: function (proxy, target, methodName, args) {
      throw new Error(`Target object '${util.inspect(target)}' does not implement the method ${methodName}`)
    }
  })
}

// Get or create the target object
const targetObject = new Product()
const product = MethodProxy.on(targetObject, proxyDefinition)

// Then use the proxy as it if was the regular object
product.setdescription('A product')
product.getDescription()

Overriding all methods

Override all the messages received by the target object, including both its absent and defined methods.

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  proxy.on({
    allMethods: function (proxy, target, methodName, args) {
      console.info(`${methodName} was called on the object '${util.inspect(target)}' with arguments '${args}'`)
      const targetMethod = targetObject[methodName]
      return Reflect.apply(targetMethod, proxy, args)
    }
  })
}

// Get or create the target object
const targetObject = new Product()
const product = MethodProxy.on(targetObject, proxyDefinition)

// Then use the proxy as it if was the regular object
product.setdescription('A product')
product.getDescription()

Combining all the previous overrides

All the previous overrides can be combined in the same proxy.

The priority of the overrides is as follows:

1. method: and methods: methods has the higher priority
2. methodMatching:
3. absentMethod:
4. allMethods:

Take a look at the examples for some interesting uses of the MethodProxy.

Properties overrides

ProxyMethod can also override gets and sets of an object properties and/or the rest of the js Proxy handlers defined in the ECMAScript standard

The complete protocol of ProxyMethod is as follows

const MethodProxy = require('o-method-proxy')
const util = require('util')

const proxyDefinition = (proxy) => {
  /// Methods overrides

  proxy.on({
    method: 'setDescription',
    evaluate: function (proxy, target, methodName, args) {
      // ...
    }
  })

  proxy.on({
    methodMatching: (methodName, proxy, target) => { return methodName.startsWith('set') },
    evaluate: function (proxy, target, methodName, args) {
      // ...
    }
  })

  proxy.on({
    methodMatching: (methodName, proxy, target) => { return methodName.startsWith('set') },
    evaluate: function (proxy, target, methodName, args) {
      // ...
    }
  })

  proxy.on({
    absentMethod: function (proxy, target, methodName, args) {
      // ...
    }
  })

  proxy.on({
    allMethods: function (proxy, target, methodName, args) {
      // ...
    }
  })

  /// Properties overrides

  proxy.on({
    propertyGet: 'n',
    evaluate: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    propertiesGet: ['n', 'm'],
    evaluate: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    propertyGetMatching: function (propertyName) { return propertyName.startsWith('___') },
    evaluate: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    absentPropertyGet: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    allPropertiesGet: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    propertySet: 'n',
    evaluate: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    allPropertiesSet: function (proxy, target, propertyName, value) {
      // ...
    }
  })

  proxy.on({
    propertySet: 'n',
    evaluate: function (proxy, target, propertyName) {
      // ...
    }
  })

  proxy.on({
    absentPropertySet: function (proxy, target, propertyName, value) {
      // ...
    }
  })

  proxy.on({
    allPropertiesSet: function (proxy, target, propertyName, value) {
      // ...
    }
  })

  /// Handlers overrides

  proxy.on({
    getPrototypeOf: function (target) {
      // ...
    }
  })

  proxy.on({
    setPrototypeOf: function (target, objectPrototype) {
      // ...
    }
  })

  proxy.on({
    isExtensible: function (target) {
      // ...
    }
  })

  proxy.on({
    preventExtensions: function (target) {
      // ...
    }
  })

  proxy.on({
    getOwnPropertyDescriptor: function (target, property) {
      // ...
    }
  })

  proxy.on({
    defineProperty: function (target, property, descriptor) {
      // ...
    }
  })

  proxy.on({
    has: function (target, property) {
      // ...
    }
  })

  proxy.on({
    get: function (target, property, receiver) {
      // ...
    }
  })

  proxy.on({
    set: function (target, property, value) {
      // ...
    }
  })

  proxy.on({
    deleteProperty: function (target, property) {
      // ...
    }
  })

  proxy.on({
    ownKeys: function (target) {
      // ...
    }
  })

  proxy.on({
    apply: function (target, proxy, argumentsList) {
      // ...
    }
  })

  proxy.on({
    construct: function (target, argumentsList) {
      // ...
    }
  })
}

It is not necessary (or even advisable) to define each override. Define just the ones you need.

Proxy handler custom configuration

If for some reason you need the Proxy handler as its given to the Proxy constructor instead of calling MethodProxy.on() create the handler with MethodProxy.handler() and customize it or pass it along in your program

// Instead of creating the proxy object at once create the Proxy handler ...
const proxyHandler = MethodProxy.handler( (config) => {
  config.on({
    allMethods: function(proxy, target, methodName, args) {
      /// ...
    }
  })
})

// customize the handler to fit your needs ...
handler.set = function(...) { .... }
handler.getPrototypeOf = function(...) { .... }

// and create the proxy object with the customized handler
const proxy = new Proxy(target, handler)

Overriding apply

apply override only works on functions therefore the target object of the MethodProxy must be a function:

const proxyDefinition = (proxy) => {
  proxy.on({
    apply: function (target, proxy, argumentsList) {
      // ...
    }
  })
}
const targetObject = function () {} // <-- Function
const object = MethodProxy.on(targetObject, proxyDefinition)

Overriding both properties and methods

Overriding both properties and methods with a combination of allMethods|absentMethod and allPropertiesGet|allPropertiesSet|absentPropertyGet|absentPropertySet can be tricky because in js a method is a property of type function.

For example if you override both allMethods and allPropertiesGet it will only hook the allPropertiesGet because to call the method js first gets the object property and then it calls apply on it.

To make it work make sure that allPropertiesGet does not handle the methods you want to hook with allMethods, for example filtering the property by its name.

Recomendation

In this documentation and examples the behaviour of each proxy is inlined in the proxy definition.

That is to make the example more simple and concise but it's not a good practice.

It would be better to extract each MethodProxy definition to a class and I encourage you to do so.

You can use this example as a guide.