wire.md

wire.js

wire.js is an Inversion of Control container that allows applications to be composed together at runtime based on a declarative configuration. A rest.js plugin is provided for wire.js that enables declarative configuration of rest.js clients, including chaning interceptors with their configuration.

Wire Plugin

rest/wire (src)

There are two aspects to the wire plugin the rest factory, and the client! reference resolver.

TIP: In each of these examples, { module: 'rest/wire' } is loaded as it provides the 'rest' factory to the wire.js spec. Without this module being loaded into the spec, the facilities below will silently fail.

'rest' Factory

The rest factory provides a declarative way to define a client with an interceptor chain that is nearly identical in capability to imperative JavaScript. The factory access two main config properties, a parent client, and an array of interceptors. Each entry in the interceptor array contains a reference to the interceptor module, and the configuration for that interceptor. The array of interceptors is chained off the client in order returning the resulting client as the wire.js component.

In it's basic form, the array of interceptors is processed in order, chaining off the parent client.

client: {
    rest: {
        parent: { $ref: 'baseClient' },
        interceptors: [
            { module: 'rest/interceptor/mime', config: { mime: 'application/json' } },
            { module: 'rest/interceptor/location' },
            { module: 'rest/interceptor/entity' },
            { module: 'rest/interceptor/hateoas', config: { target: '' } }
        ]
    }
},
baseClient: { module: 'rest' },
plugins: [{ module: 'rest/wire' }]

If parent is not defined, or is not a function, the default client is used as the parent. In that case, the interceptors array can replace the whole factory object

client: {
    rest: [
        { module: 'rest/interceptor/mime', config: { mime: 'application/json' } },
        { module: 'rest/interceptor/location' },
        { module: 'rest/interceptor/entity' },
        { module: 'rest/interceptor/hateoas', config: { target: '' } }
    ]
},
plugins: [{ module: 'rest/wire' }]

If a configuration element isn't needed, a string can be provided to represent the module

client: {
    rest: [
        { module: 'rest/interceptor/mime', config: { mime: 'application/json' } },
        'rest/interceptor/location',
        'rest/interceptor/entity',
        { module: 'rest/interceptor/hateoas', config: { target: '' } }
    ]
},
plugins: [{ module: 'rest/wire' }]

An individual interceptors array entry can use any facility available within wire.js, including $ref.

client: {
    rest: [
        { $ref: 'mime', config: { mime: 'application/json' } },
        'rest/interceptor/location',
        'rest/interceptor/entity',
        { $ref: 'hateoas', config: { target: '' } }
    ]
},
mime: { module: 'rest/interceptor/mime' },
hateoas: { module: 'rest/interceptor/hateoas' },
plugins: [{ module: 'rest/wire' }]

'client!' Reference Resolver

The client! reference resolver installs several commonly used interceptors, wrapping the default client. In order, the interceptors installed are the 'errorCode', 'mime', 'entity' and 'pathPrefix'. Basic options are configurable. It is intended as a quick and dirty way to get a functional client quickly. In most cases, the 'rest' factory will be more useful.

Property	Required?	Default	Description
client	optional	default client	client to wrap with the configured interceptors
errorCode	optional	400	response status code above which to make the response in error, provided a boolean false to block installing the errorCode interceptor
mime	optional	'application/x-www-form-urlencoded'	mime type for request entities, provided a boolean false to block installing the mime interceptor
accept	optional	mime value	accept header for the request
entity	optional	none	provided a boolean false to block installing the entity interceptor

The pathPrefix interceptor is not configured via a property, but the string after the '!'.

client: {
	{ $ref: 'client!' }
}

Is equivlent to:

client = rest.chain(errorCode, { code: 400 })
             .chain(mime, { mime: 'application/x-www-form-urlencoded' })
             .chain(entity)
             .chain(pathPrefix, { prefix: '' });

To disable interceptors, provide a boolean false for the config value

client: {
	{ $ref: 'client!', errorCode: false, mime: false, entity: false }
}

Is equivlent to:

client = rest.chain(pathPrefix, { prefix: '' });

A custom client can be used instead of the default client

client: {
	{ $ref: 'client!', client: { ref: 'someOtherClient' } }
}

Is equivlent to:

client = someOtherClient.chain(errorCode, { code: 400 })
                        .chain(mime, { mime: 'application/x-www-form-urlencoded' })
                        .chain(entity)
                        .chain(pathPrefix, { prefix: '' });

A Dojo Store variant of the client! reference resolver is available as resource! from rest/dojo/wire.