iso-global
This module lets you require and asynchronously access global objects that exist within an isolated browser context (specifically, an iframe). You could use it to conditionally load standalone modules without polluting the global namespace.
** The tests should pass in all browsers, even IE 6 and friends! **
Install
$ npm install iso-global
Usage
Example
Suppose you wanted to generate some SHA-1 hashes. Most modern browsers support crypto.subtle.digest
but for those that don’t you’d like to provide a fallback. Ideally, a capable browser shouldn’t be forced to download and parse a non-native implementation they’ll never execute, so you could do something like this:
var iso = var supports =
For more comprehensive but less “real world” usage examples, check out test/index.js
.
API
:accessor
< iso-global(…)
required script-src:string
is any URL that resolves to a javascript file.
optional object-name:string
is the name of a global object that script-src
exposes. If omitted, the basename of script-src
will be used instead.
optional object-properties:array
is a list of properties, belonging to the global object, that you would like to access. These will be exposed as properties of the returned accessor(…)
object, and are themselves accessor(…)
objects.
optional object-functions-are-asynchronous:boolean
defaults to false
but should be set to true
if the global object or its function properties pass values into callback functions rather than returning them to the caller.
note: optional arguments for can be specified in any order.
:void < accessor(…)
optional args:arguments
are any number of values that need to be passed to the global object, assuming the object is a function.
required callback:function
is a function that will eventually be passed the accessed value or values.
optional object-function-is-asynchronous:boolean
allows you to override the object-functions-are-asynchronous
boolean for this specific global object property.
iso-global/recontext(…)
A few words about Because iso-global
runs scripts in an separate context from the main application, a weird edge case exists where if the isolated code performs instanceof
checks against arguments passed from the main context, those checks will always fail. The reason for this can perhaps best be demonstrated through code:
var ContextA = windowvar ContextB = iframecontentWindowvar array = array instanceof ContextAArray> truearray instanceof ContextBArray> false
If this is a problem for you, you can likely get around it by requiring iso-global/recontext
, which will automagically recontextualise arguments before passing them to the isolated script. It’s a total hack, so that’s why it’s provided as an optional augmentation.
Page weight
require('iso-global')
compression | size |
---|---|
iso-global.js | 4.62 kB |
iso-global.min.js | 2.05 kB |
iso-global.min.js.gz | 1.04 kB |
require('iso-global/recontext')
compression | size |
---|---|
recontext.js | 5.43 kB |
recontext.min.js | 2.47 kB |
recontext.min.js.gz | 1.22 kB |
Running the tests
Until testling comes back (or is replaced by something elegant) you can run the tests yourself in any browser:
$ git clone git@github.com:michaelrhodes/iso-global$ cd iso-global$ npm install$ npm test