Naming Prosecution Mitigator

    ee-soa-request

    0.2.22 • Public • Published

    ee-soa-request

    Application internal, protocol independent request/response implementation.

    installation

    npm install ee-soa-request
    

    build status

    Build Status

    usage

    var Request = require('ee-soa-request');

    var myRequest = new Request();

    var myReadRequest = new Request.ReadRequest();

    api

    Some of the important methods the read request object provides (incomplete):

    Base Accessors

    // needs a callback to support asynchronous loading in the future
    request.getContent(callback)
    request.setContent(content)
    
    request.setContentType(type)
    request.getContentType()
    

    Type

    The type of the request is based on the action code (for crud/rest mapping, analogous to http methods).

    request.setAction(actionCode)
    request.getAction()
    
    request.isOfType(actionCode)
    
    request.isReadRequest()
    request.isCreateRequest()
    request.isUpdateRequest()
    request.isDeleteRequest()
    request.isWriteRequest()
    request.isInfoRequest()
    request.isOptionsRequest()
    

    Relations

    A request is often created to query specific relations/models.

    request.getCollection() :string
    // alias
    request.getController() :string
    request.setCollection(collection:string)
    request.queriesCollection() :boolean
    
    request.getResourceId()
    request.setResourceId(id:mixed)
    request.hasResourceId()
    
    request.hasRelatedTo()
    request.getRelatedTo() : {model:string, id: mixed}
    request.setRelatedTo(model, id)
    

    Accessors and Helpers

    request.getVersion()                    // api version
    request.setVersion(version)
    request.versionCompare(version)         // 0 if equal, -1 if request version is smaller, 1 if bigger
    
    request.addFormat(type, subtype)        // e.g. 'application' 'json'
    request.acceptsFormat(type, subtype)
    
    request.setLanguages(languageArray)
    request.getLanguages()
    request.acceptsLanguage(languageString)
    
    request.hasRange()
    request.setRange(from, to)
    request.getRange(): {from:mixed, to:mixed}  // Ranges (from, to) are set to null if not present
    
    // filters
    // projections
    // orderings
    // orderings
    

    Types and Dispatching

    The following request types are defined (based on the http verbs for rest interfaces), please use them and not the generic Request.

    • DeleteRequest DELETE
    • InfoRequest HEAD
    • CreateRequest PUT
    • OptionsRequest OPTIONS
    • ReadRequest GET
    • UpdateRequest PATCH
    • WriteRequest POST

    The different types of requests implement a dispatch method which takes a handler as its argument (the request performs a so called double-dispatch, this allows you to easily handle the request without knowing its type upfront). A handler is described by the following set of methods (to say it in terms of duck-typing)

    var handler = {
        handleCreateRequest: function(req, options){ ... }
        handleDeleteRequest: function(req, options){ ... }
        handleInfoRequest: function(req, options){ ... }
        handleOptionsRequest: function(req, options){ ... }
        handleReadRequest: function(req, options){ ... }
        handleUpdateRequest: function(req, options){ ... }
        handleWriteRequest: function(req, options){ ... }
    }
    

    You can use the options parameter to pass in additional data e.g. the request if you want to send the your data directly from your handler. See the following (rudimentary) example for a read request:

    var handler = {
        handleReadRequest: function(req, options){
            // list
            var   query = 'SELECT * FROM :collection:'
                , params = {collection: req.getCollection()};
    
            // listOne
            if(req.hasResourceId()){
                params['id'] = req.getResourceId();
                query += 'WHERE `id`= :id:';
            }
    
            var data = this.performQuery(query, params);
            options.response.send(options.response.OK, data);
        }
    };
    
    request.dispatch(handler, {response: response});
    

    Format

    Formats are the internal representation of the internet media types (currently not supporting parameters such as the encoding). All types of Request objects provide easy accessors to preserve you from dealing with the internal data format.

    addFormat(type, subtype)

    Add a format to the current format collection of the request (type and subtype are strings the asterisk represents the wildcard.

    acceptsFormat(type, subtype)

    This method can be used to to check if a request accepts a specific response format based on the internet media type (type, subtype). It returns the priority of the passed format to allow your service or controller to check which formats are accepted, and which should be delivered (the relation is covariant, so image/* accepts image/jpg but not the other way round). Lets consider an example for an simple image service:

    // The accepted formats are image/jpg, application/*
    // We can create jpgs and json
    var acceptsJPG  = request.acceptsFormat('image', 'jpg'),
        acceptsJSON = request.acceptsFormat('application', 'json');
    
    if(acceptsJPG === false && acceptsJSON === false){
        return this.sendUnsatisfiableResponse();
    }
    
    if(acceptsJPEG > acceptsJSON){
        return this.sendImageResponse();
    }
    
    return this.sendJSONResponse();
    

    One can immediately see, that we need the priority to be able to distinguish which response to send (because the request accepts both). More formats can easily be checked in a loop.

    Keywords

    Install

    npm i ee-soa-request

    DownloadsWeekly Downloads

    0

    Version

    0.2.22

    License

    MIT

    Unpacked Size

    56.3 kB

    Total Files

    26

    Last publish

    Collaborators

    • ee
    • rcky
    • tobiaskneubuehler