attribute.js

'use strict';
// TODO consider refactoring this file so that the geoApi object is passed in along with the
//      esriBundle, then reference the shared module from it.  See layer.js as example.
const shared = require('./shared.js');
/*
Structure and naming:
this is the Bundle. it is the topmost object in the structure.
it packages up attributes for an entire layer object (i.e. FeatureLayer, DynamicLayer)
{
    layerId: <layerId for layer>,
    indexes: ["6", "7"],
    "6": {
        <instance of a layer package, see below>
    },
    "7": {
        <instance of a layer package, see below>
    }
}
this is a layer Package.  it contains information about a single server-side layer.
note this is not always 1-to-1 with client side. a client side DynamicLayer can have
many server-side sublayers, each with their own attribute sets
DO NOT access the ._attribData property directly, as it will not exist until the first
request for attributes.  use the function .getAttribs(), as it will properly handle the
initial request, or return the previously loaded result (always as a promise)
{
    "layerId": "<layerid>",
    "featureIdx": 3,
    "getAttribs": getAttribs(),
    "_attribData": Promise(
        <instance of a attribute data object, see below>
    ),
    "layerData":  Promise(
        <instance of a layer data object, see below>
    )
}
this is an attribute data object.  it resides in a promise (as the data needs to be downloaded)
it contains the attribute data as an array, and an index mapping object id to array position
{
    "features": [
        {
            "attributes": {
                "objectid": 23,
                "name": "Bruce",
                "age": 27
            }
        },
        ...
    ],
        "oidIndex": {
        "23": 0,
        ...
    }
}
this is a layer data object.  it contains information describing the server-side layer
{
    "fields: [
        {
            "name": "objectid",
            "type": "esriFieldTypeOID",
            "alias": "OBJECTID"
        },
        ...
    ],
    "oidField": "objectid",
    "renderer": {...},
    "geometryType": "esriGeometryPoint",
    "minScale": 0,
    "maxScale": 0
}
*/
/**
* Will generate an empty object structure to store a bundle of attributes for a full layer
* @private
* @return {Object} empty layer bundle object
*/
function newLayerBundle(layerId) {
    const bundle = {
        layerId, // for easy access to know what layer the results belong to
        indexes: [], // for easy iteration over all indexes in the set
        registerData
    };
    function registerData(layerPackage) {
        layerPackage.layerId = bundle.layerId; // layerPackage is unaware of layerId. assign it during registration
        bundle[layerPackage.featureIdx.toString()] = layerPackage;
        bundle.indexes.push(layerPackage.featureIdx.toString());
    }
    return bundle;
}
/**
* Will generate an empty object structure to store attributes for a single layer of features
* @private
* @param  {Integer} featureIdx server index of the layer
* @param  {Object} esriBundle bundle of API classes
* @return {Object} empty layer package object
*/
function newLayerPackage(featureIdx, esriBundle) {
    // only reason this is in a function is to tack on the lazy-load
    // attribute function. all object properties are added elsewhere
    const layerPackage = {
        featureIdx,
        getAttribs
    };
    /**
    * Return promise of attribute data object. First request triggers load
    * @private
    * @return {Promise} promise of attribute data object
    */
    function getAttribs() {
        if (layerPackage._attribData) {
            // attributes have already been downloaded.
            return layerPackage._attribData;
        }
        // first request for data. create the promise
        layerPackage._attribData = new Promise((resolve, reject) => {
            // first wait for the layer specific data to finish loading
            // NOTE: by the time the application has access to getAttribs(), the .layerData
            //       property will have been created.
            layerPackage.layerData.then(layerData => {
                // FIXME switch to native Promise
                const defFinished = new esriBundle.Deferred();
                const params = {
                    maxId: -1,
                    batchSize: -1,
                    layerUrl: layerData.load.layerUrl,
                    oidField: layerData.oidField,
                    attribs: layerData.load.attribs,
                    supportsLimit: layerData.load.supportsLimit,
                    esriBundle
                };
                // begin the loading process
                loadDataBatch(params, defFinished);
                // after all data has been loaded
                defFinished.promise.then(features => {
                    delete layerData.load; // no longer need this info
                    // resolve the promise with the attribute set
                    resolve(createAttribSet(layerData.oidField, features));
                }, error => {
                    console.warn('error getting attribute data for ' + layerData.load.layerUrl);
                    // attrib data deleted so the first check for attribData doesn't return a rejected promise
                    delete layerPackage._attribData;
                    reject(error);
                });
            });
        });
        return layerPackage._attribData;
    }
    return layerPackage;
}
/**
* Will generate attribute package with object id indexes
* @private
* @param  {String} oidField field containing object id
* @param  {Array} featureData feature objects to index and return
* @return {Object} object containing features and an index by object id
*/
function createAttribSet(oidField, featureData) {
    // add new data to layer data's array
    const res = {
        features: featureData,
        oidIndex: {}
    };
    // make index on object id
    featureData.forEach((elem, idx) => {
        // map object id to index of object in feature array
        // use toString, as objectid is integer and will act funny using array notation.
        res.oidIndex[elem.attributes[oidField].toString()] = idx;
    });
    return res;
}
// skim the last number off the Url
// TODO apply more edge case tests to this function
function getLayerIndex(layerUrl) {
    const re = /\/(\d+)\/?$/;
    const matches = layerUrl.match(re);
    if (matches) {
        return parseInt(matches[1]);
    }
    throw new Error('Cannot extract layer index from url ' + layerUrl);
}
/**
* Recursive function to load a full set of attributes, regardless of the maximum output size of the service.
* Passes result back on the provided Deferred object.
*
* @private
* @param  {Object} opts options object that consists of these properties
*         - maxId: integer, largest object id that has already been downloaded.
*         - supportsLimit: boolean, indicates if server result will notify us if our request surpassed the record limit.
*         - batchSize: integer, maximum number of results the service will return. if -1, means currently unknown. only required if supportsLimit is false.
*         - layerUrl: string, URL to feature layer endpoint.
*         - oidField: string, name of attribute containing the object id for the layer.
*         - attribs: string, a comma separated list of attributes to download. '*' will download all.
*         - esriBundle: object, standard set of ESRI API objects.
* @param  {Object} callerDef deferred object that resolves when current data has been downloaded
*/
function loadDataBatch(opts, callerDef) {
    //  fetch attributes from feature layer. where specifies records with id's higher than stuff already
    //  downloaded. no geometry.
    // FIXME replace esriRequest with a library that handles proxies better
    const defData = opts.esriBundle.esriRequest({
        url: opts.layerUrl + '/query',
        content: {
            where: opts.oidField + '>' + opts.maxId,
            outFields: opts.attribs,
            returnGeometry: 'false',
            f: 'json',
        },
        callbackParamName: 'callback',
        handleAs: 'json'
    });
    defData.then(dataResult => {
        if (dataResult.features) {
            const len = dataResult.features.length;
            if (len > 0) {
                // figure out if we hit the end of the data. different logic for newer vs older servers.
                let moreData;
                if (opts.supportsLimit) {
                    moreData = dataResult.exceededTransferLimit;
                } else {
                    if (opts.batchSize === -1) {
                        // this is our first batch. set the max batch size to this batch size
                        opts.batchSize = len;
                    }
                    moreData = (len >= opts.batchSize);
                }
                if (moreData) {
                    // stash the result and call the service again for the next batch of data.
                    // max id becomes last object id in the current batch
                    const thisDef = new opts.esriBundle.Deferred();
                    opts.maxId = dataResult.features[len - 1].attributes[opts.oidField];
                    loadDataBatch(opts, thisDef);
                    thisDef.then(dataArray => {
                        // chain the next result to our current result, then pass back to caller
                        callerDef.resolve(dataResult.features.concat(dataArray));
                    },
                    error => {
                        callerDef.reject(error);
                    });
                } else {
                    // done thanks
                    callerDef.resolve(dataResult.features);
                }
            } else {
                // no more data.  we are done
                callerDef.resolve([]);
            }
        } else {
            // it is possible to have an error, but it comes back on the "success" channel.
            callerDef.reject(dataResult.error);
        }
    },
    error => {
        callerDef.reject(error);
    });
}
/**
* fetch attributes from an ESRI ArcGIS Server Feature Layer Service endpoint
* @param {String} layerUrl an arcgis feature layer service endpoint
* @param {Integer} featureIdx index of where the endpoint is. used for legend output
* @param {String} attribs a comma separated list of attributes to download. '*' will download all
* @param  {Object} esriBundle bundle of API classes
* @return {Object} attributes in a packaged format for asynch access
*/
function loadFeatureAttribs(layerUrl, featureIdx, attribs, esriBundle, geoApi) {
    const layerPackage = newLayerPackage(getLayerIndex(layerUrl), esriBundle);
    // get information about this layer, asynch
    layerPackage.layerData = new Promise((resolve, reject) => {
        const layerData = {};
        // extract info for this service
        const defService = esriBundle.esriRequest({
            url: layerUrl,
            content: { f: 'json' },
            callbackParamName: 'callback',
            handleAs: 'json',
        });
        defService.then(serviceResult => {
            if (serviceResult && (typeof serviceResult.error === 'undefined')) {
                // properties for all endpoints
                layerData.layerType = serviceResult.type;
                layerData.geometryType = serviceResult.geometryType;
                layerData.minScale = serviceResult.minScale;
                layerData.maxScale = serviceResult.maxScale;
                layerData.supportsFeatures = false; // saves us from having to keep comparing type to 'Feature Layer' on the client
                if (serviceResult.type === 'Feature Layer') {
                    layerData.supportsFeatures = true;
                    layerData.fields = serviceResult.fields;
                    // find object id field
                    // NOTE cannot use arrow functions here due to bug
                    serviceResult.fields.every(function (elem) {
                        if (elem.type === 'esriFieldTypeOID') {
                            layerData.oidField = elem.name;
                            return false; // break the loop
                        }
                        return true; // keep looping
                    });
                    // ensure our attribute list contains the object id
                    if (attribs !== '*') {
                        if (attribs.split(',').indexOf(layerData.oidField) === -1) {
                            attribs += (',' + layerData.oidField);
                        }
                    }
                    // add renderer and legend
                    layerData.renderer = serviceResult.drawingInfo.renderer;
                    layerData.legend = geoApi.symbology.rendererToLegend(layerData.renderer, featureIdx);
                    geoApi.symbology.enhanceRenderer(layerData.renderer, layerData.legend);
                    // temporarily store things for delayed attributes
                    layerData.load = {
                        // version number is only provided on 10.0 SP1 servers and up.
                        // servers 10.1 and higher support the query limit flag
                        supportsLimit: (serviceResult.currentVersion || 1) >= 10.1,
                        layerUrl,
                        attribs
                    };
                }
                // return the layer data promise result
                resolve(layerData);
            } else {
                // case where error happened but service request was successful
                console.warn('Service metadata load error');
                if (serviceResult && serviceResult.error) {
                    // reject with error
                    reject(serviceResult.error);
                } else {
                    reject(new Error('Unknown error loading service metadata'));
                }
            }
        }, error => {
            // failed to load service info. reject with error
            console.warn('Service metadata load error : ' + error);
            reject(error);
        });
    });
    return layerPackage;
}
// extract the options (including defaults) for a layer index
function pluckOptions(featureIdx, options = {}) {
    // handle missing layer
    const opt = options[featureIdx] || {};
    return {
        skip: opt.skip || false,
        attribs: opt.attribs || '*'
    };
}
/**
* Ochestrate the attribute extraction of a feature layer object.
* @private
* @param  {Object} layer an ESRI API Feature layer object
* @param  {Object} options information on layer and attribute skipping
* @param  {Object} esriBundle bundle of API classes
* @return {Object} attributes in layer bundle format (see newLayerBundle)
*/
function processFeatureLayer(layer, options, esriBundle, geoApi) {
    // logic is in separate function to passify the cyclomatic complexity check.
    // TODO we may want to support the option of a layer that points to a server based JSON file containing attributes
    const result = newLayerBundle(layer.id);
    if (layer.url) {
        const idx = getLayerIndex(layer.url);
        const opts = pluckOptions(idx, options);
        // check for skip flag
        if (!opts.skip) {
            // call loadFeatureAttribs with options if present
            result.registerData(loadFeatureAttribs(layer.url, idx, opts.attribs, esriBundle, geoApi));
        }
    } else {
        // feature layer was loaded from a file.
        // this approach is inefficient (duplicates attributes in layer and in attribute store),
        // but provides a consistent approach to attributes regardless of where the layer came from
        const layerPackage = newLayerPackage(0, esriBundle); // files have no index (no server), so we use value 0
        // it's local, no need to lazy-load
        layerPackage._attribData = Promise.resolve(createAttribSet(layer.objectIdField, layer.graphics.map(elem => {
            return { attributes: elem.attributes };
        })));
        const renderer = layer.renderer.toJson();
        const legend = geoApi.symbology.rendererToLegend(renderer, 0);
        geoApi.symbology.enhanceRenderer(renderer, legend);
        // TODO revisit the geometry type. ideally, fix our GeoJSON to Feature to populate the property
        layerPackage.layerData = Promise.resolve({
            oidField: layer.objectIdField,
            fields: layer.fields,
            geometryType: layer.geometryType || JSON.parse(layer._json).layerDefinition.drawingInfo.geometryType,
            minScale: layer.minScale,
            maxScale: layer.maxScale,
            renderer,
            legend
        });
        result.registerData(layerPackage);
    }
    return result;
}
/**
* Ochestrate the attribute extraction of a dynamic map service layer object.
* @private
* @param  {Object} layer an ESRI API Dynamic Map Service layer object
* @param  {Object} options information on layer and attribute skipping
* @param  {Object} esriBundle bundle of API classes
* @return {Object} attributes in layer bundle format (see newLayerBundle)
*/
function processDynamicLayer(layer, options, esriBundle, geoApi) {
    // logic is in separate function to passify the cyclomatic complexity check.
    // TODO we may want to support the option of a layer that points to a server based JSON file containing attributes
    let idx = 0;
    let opts;
    const result = newLayerBundle(layer.id);
    const lInfo = layer.layerInfos;
    // for each layer leaf.  we use a custom loop as we need to skip sections
    while (idx < lInfo.length) {
        opts = pluckOptions(idx, options);
        //  check if leaf node or group node
        if (lInfo[idx].subLayerIds) {
            // group node
            if (opts.skip) {
                // skip past all child indexes (thus avoiding processing all children).
                // group indexes have property .subLayerIds that lists indexes of all immediate child layers
                // child layers can be group layers as well.
                // example: to skip Group A (index 0), we crawl to Leaf X (index 4), then add 1 to get to sibling layer Leaf W (index 5)
                //  [0] Group A
                //      [1] Leaf Z
                //      [2] Group B
                //          [3] Leaf Y
                //          [4] Leaf X
                //  [5] Leaf W
                let lastIdx = idx;
                while (lInfo[lastIdx].subLayerIds) {
                    // find last child index of this group. the last child may be a group itself so we keep processing the while loop
                    lastIdx = lInfo[lastIdx].subLayerIds[
                        lInfo[lastIdx].subLayerIds.length - 1];
                }
                // lastIdx has made it to the very last child in the original group node.
                // advance by 1 to get the next sibling index to the group
                idx = lastIdx + 1;
            } else {
                // advance to the first child layer
                idx += 1;
            }
        } else {
            // leaf node
            if (!opts.skip) {
                // load the features, store promise in array
                result.registerData(loadFeatureAttribs(layer.url + '/' + idx.toString(), idx,
                    opts.attribs, esriBundle, geoApi));
            }
            // advance the loop
            idx += 1;
        }
    }
    return result;
}
function loadLayerAttribsBuilder(esriBundle, geoApi) {
    /**
    * Fetch attributes from a server-based Layer
    * @param {Object} layer an ESRI API layer object
    * @param {Object} options settings to determine if sub layers or certain attributes should be skipped.
    * @return {Object} attributes bundle for given layer
    */
    return (layer, options) => {
        /*
        format of the options object
        all parts are optional.  default values are skip: false and attribs: "*"
        {
            "<layerindex a>": {
                "skip": true
            },
             "<layerindex b>": {
                "skip": false,
                "attribs": "field3,field8,field11"
            },
            "<layerindex d>": {
            }
        }
        */
        const shr = shared(esriBundle);
        const lType = shr.getLayerType(layer);
        switch (lType) {
            case 'FeatureLayer':
                return processFeatureLayer(layer, options, esriBundle, geoApi);
            case 'ArcGISDynamicMapServiceLayer':
                return processDynamicLayer(layer, options, esriBundle, geoApi);
            // case 'WmsLayer':
            // case 'ArcGISTiledMapServiceLayer':
            default:
                throw new Error('no support for loading attributes from layer type ' + lType);
        }
    };
}
//  Attribute Loader related functions
// TODO consider re-writing all the asynch stuff with the ECMA-7 style of asynch keywords
module.exports = (esriBundle, geoApi) => {
    return {
        loadLayerAttribs: loadLayerAttribsBuilder(esriBundle, geoApi),
        getLayerIndex
    };
};