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