DI-Proxy

Dependency Injection UMD Module using the Built-in Proxy.

Installation

$ npm i --save di-proxy

How to include in...

ES6 import (with babel):

import { inject, wrap } from 'di-proxy'

CommonJS:

const { inject, wrap } = require('di-proxy')

Browser:

<script src="https://unpkg.com/di-proxy"></script>
<script>
  const { inject, wrap } = window.diProxy
</script> 

inject(resolver, [memoize]) ⇒ Proxy

Creates an optionally memoized proxy that invokes the resolver from trapped property accesses.

Kind: global function
Returns: Proxy - proxy - A proxy with a get trap that invokes the resolver.

Param	Type	Default	Description
resolver	resolver		A function invoked within the get trap of returned proxy.
[memoize]	boolean	true	Shadow properties with result from first invocation of resolver.

wrap(resolver, callback) ⇒ injector

Kind: global function
Returns: injector - injector - A function that passes arguments after the proxy in callback when invoked.

Param	Type	Description
resolver	resolver	A function invoked within the get trap of first argument to callback.
callback	callback	A function that accepts a proxy as the first argument.

resolver ⇒ *

Kind: global typedef
Returns: * - result - Synchronously resolved object referenced by key.
See: inject()

Param	Type	Description
key	string	A reference to some sort of dependency or query.

callback ⇒ *

Kind: global typedef
See: wrap()

Param	Type	Description
proxy	Proxy	Bound parameter which is the result of inject(resolver, true).
...rest	*	Arguments passed when invoking injector.

injector ⇒ *

Kind: global typedef
Returns: * - result - Result of invoking callback.
See: wrap()

Param	Type	Description
...args	*	Passed as rest parameter to callback.

Usage

const { http, express, 'socket.io': sio } = inject(require)
 
const app = express()
const server = http.Server(app)
const io = sio(server)
// ...

Other examples

jQuery:

const {
  'input#file-input': $file,
  'ul#preview-names': $previewNames 
} = diProxy.inject(jQuery)
 
$file.change(() => {
  $previewNames.empty()
 
  const files = $file.prop('files')
 
  for (const file of files) {
    $previewNames.append($('<li/>').text(file.name))
  }
})

document.querySelector:

const qs = diProxy.wrap(
  document.querySelector.bind(document),
  ({ input: { id, name, type, value }, pre }) => {
    const json = JSON.stringify({ id, name, type, value })
 
    pre.appendChild(document.createTextNode(json))
  }
)
 
qs()

sessionStorage.getItem:

const ssdi = diProxy.inject(sessionStorage.getItem.bind(sessionStorage))
 
sessionStorage.setItem('test', 'value')
sessionStorage.setItem('another', 'thing')
 
// get some session properties
let { test, another } = ssdi
 
const formattedText = `test: ${test}, another: ${another}`
document.getElementById('out').textContent = formattedText

Dependencies and Supported Environments

This assumes that the environment has a working implementation for Proxy.

All modern browsers including Microsoft Edge, and Node.js >=6.0.0 are supported, according to caniuse.com and kangax/compat-table.

Some Notes on Performance

Internally this dependency injection uses Proxy. However, any performance implications have been mitigated by optionally memoizing each property accessor by default:

const string = diProxy.inject((prop) => {
  console.log('get trap invoked!')
  return prop
})
 
const value = string.somePropertyName // 'get trap invoked!'
console.log(value) // 'somePropertyName'
string.somePropertyName // nothing will be printed here
delete string.somePropertyName
string.somePropertyName // 'get trap invoked!'

You should be careful when using the default behavior in coordination with a query function for live data (like jQuery, for example), as it will memoize the resolver with the result of the first call for each property name unless you delete it from the proxy object before each subsequent call, or set the optional memoize parameter to false when calling inject().

This library allows you to re-use a created proxy or injector without taking a performance hit from the overhead of a naive proxy implementation.

License

Available under the MIT License (c) 2017 Patrick Roberts