[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 Yahoo! Inc. All rights reserved.
   4  Licensed under the BSD License.
   5  http://yuilibrary.com/license/
   6  */
   7  
   8  YUI.add('dataschema-json', function (Y, NAME) {
   9  
  10  /**
  11  Provides a DataSchema implementation which can be used to work with JSON data.
  12  
  13  @module dataschema
  14  @submodule dataschema-json
  15  **/
  16  
  17  /**
  18  Provides a DataSchema implementation which can be used to work with JSON data.
  19  
  20  See the `apply` method for usage.
  21  
  22  @class DataSchema.JSON
  23  @extends DataSchema.Base
  24  @static
  25  **/
  26  var LANG = Y.Lang,
  27      isFunction = LANG.isFunction,
  28      isObject   = LANG.isObject,
  29      isArray    = LANG.isArray,
  30      // TODO: I don't think the calls to Base.* need to be done via Base since
  31      // Base is mixed into SchemaJSON.  Investigate for later.
  32      Base       = Y.DataSchema.Base,
  33  
  34      SchemaJSON;
  35  
  36  SchemaJSON = {
  37  
  38  /////////////////////////////////////////////////////////////////////////////
  39  //
  40  // DataSchema.JSON static methods
  41  //
  42  /////////////////////////////////////////////////////////////////////////////
  43      /**
  44       * Utility function converts JSON locator strings into walkable paths
  45       *
  46       * @method getPath
  47       * @param locator {String} JSON value locator.
  48       * @return {String[]} Walkable path to data value.
  49       * @static
  50       */
  51      getPath: function(locator) {
  52          var path = null,
  53              keys = [],
  54              i = 0;
  55  
  56          if (locator) {
  57              // Strip the ["string keys"] and [1] array indexes
  58              // TODO: the first two steps can probably be reduced to one with
  59              // /\[\s*(['"])?(.*?)\1\s*\]/g, but the array indices would be
  60              // stored as strings.  This is not likely an issue.
  61              locator = locator.
  62                  replace(/\[\s*(['"])(.*?)\1\s*\]/g,
  63                  function (x,$1,$2) {keys[i]=$2;return '.@'+(i++);}).
  64                  replace(/\[(\d+)\]/g,
  65                  function (x,$1) {keys[i]=parseInt($1,10)|0;return '.@'+(i++);}).
  66                  replace(/^\./,''); // remove leading dot
  67  
  68              // Validate against problematic characters.
  69              // commented out because the path isn't sent to eval, so it
  70              // should be safe. I'm not sure what makes a locator invalid.
  71              //if (!/[^\w\.\$@]/.test(locator)) {
  72              path = locator.split('.');
  73              for (i=path.length-1; i >= 0; --i) {
  74                  if (path[i].charAt(0) === '@') {
  75                      path[i] = keys[parseInt(path[i].substr(1),10)];
  76                  }
  77              }
  78              /*}
  79              else {
  80              }
  81              */
  82          }
  83          return path;
  84      },
  85  
  86      /**
  87       * Utility function to walk a path and return the value located there.
  88       *
  89       * @method getLocationValue
  90       * @param path {String[]} Locator path.
  91       * @param data {String} Data to traverse.
  92       * @return {Object} Data value at location.
  93       * @static
  94       */
  95      getLocationValue: function (path, data) {
  96          var i = 0,
  97              len = path.length;
  98          for (;i<len;i++) {
  99              if (isObject(data) && (path[i] in data)) {
 100                  data = data[path[i]];
 101              } else {
 102                  data = undefined;
 103                  break;
 104              }
 105          }
 106          return data;
 107      },
 108  
 109      /**
 110      Applies a schema to an array of data located in a JSON structure, returning
 111      a normalized object with results in the `results` property. Additional
 112      information can be parsed out of the JSON for inclusion in the `meta`
 113      property of the response object.  If an error is encountered during
 114      processing, an `error` property will be added.
 115  
 116      The input _data_ is expected to be an object or array.  If it is a string,
 117      it will be passed through `Y.JSON.parse()`.
 118  
 119      If _data_ contains an array of data records to normalize, specify the
 120      _schema.resultListLocator_ as a dot separated path string just as you would
 121      reference it in JavaScript.  So if your _data_ object has a record array at
 122      _data.response.results_, use _schema.resultListLocator_ =
 123      "response.results". Bracket notation can also be used for array indices or
 124      object properties (e.g. "response['results']");  This is called a "path
 125      locator"
 126  
 127      Field data in the result list is extracted with field identifiers in
 128      _schema.resultFields_.  Field identifiers are objects with the following
 129      properties:
 130  
 131        * `key`   : <strong>(required)</strong> The path locator (String)
 132        * `parser`: A function or the name of a function on `Y.Parsers` used
 133              to convert the input value into a normalized type.  Parser
 134              functions are passed the value as input and are expected to
 135              return a value.
 136  
 137      If no value parsing is needed, you can use path locators (strings)
 138      instead of field identifiers (objects) -- see example below.
 139  
 140      If no processing of the result list array is needed, _schema.resultFields_
 141      can be omitted; the `response.results` will point directly to the array.
 142  
 143      If the result list contains arrays, `response.results` will contain an
 144      array of objects with key:value pairs assuming the fields in
 145      _schema.resultFields_ are ordered in accordance with the data array
 146      values.
 147  
 148      If the result list contains objects, the identified _schema.resultFields_
 149      will be used to extract a value from those objects for the output result.
 150  
 151      To extract additional information from the JSON, include an array of
 152      path locators in _schema.metaFields_.  The collected values will be
 153      stored in `response.meta`.
 154  
 155  
 156      @example
 157          // Process array of arrays
 158          var schema = {
 159                  resultListLocator: 'produce.fruit',
 160                  resultFields: [ 'name', 'color' ]
 161              },
 162              data = {
 163                  produce: {
 164                      fruit: [
 165                          [ 'Banana', 'yellow' ],
 166                          [ 'Orange', 'orange' ],
 167                          [ 'Eggplant', 'purple' ]
 168                      ]
 169                  }
 170              };
 171  
 172          var response = Y.DataSchema.JSON.apply(schema, data);
 173  
 174          // response.results[0] is { name: "Banana", color: "yellow" }
 175  
 176  
 177          // Process array of objects + some metadata
 178          schema.metaFields = [ 'lastInventory' ];
 179  
 180          data = {
 181              produce: {
 182                  fruit: [
 183                      { name: 'Banana', color: 'yellow', price: '1.96' },
 184                      { name: 'Orange', color: 'orange', price: '2.04' },
 185                      { name: 'Eggplant', color: 'purple', price: '4.31' }
 186                  ]
 187              },
 188              lastInventory: '2011-07-19'
 189          };
 190  
 191          response = Y.DataSchema.JSON.apply(schema, data);
 192  
 193          // response.results[0] is { name: "Banana", color: "yellow" }
 194          // response.meta.lastInventory is '2001-07-19'
 195  
 196  
 197          // Use parsers
 198          schema.resultFields = [
 199              {
 200                  key: 'name',
 201                  parser: function (val) { return val.toUpperCase(); }
 202              },
 203              {
 204                  key: 'price',
 205                  parser: 'number' // Uses Y.Parsers.number
 206              }
 207          ];
 208  
 209          response = Y.DataSchema.JSON.apply(schema, data);
 210  
 211          // Note price was converted from a numeric string to a number
 212          // response.results[0] looks like { fruit: "BANANA", price: 1.96 }
 213  
 214      @method apply
 215      @param {Object} [schema] Schema to apply.  Supported configuration
 216          properties are:
 217        @param {String} [schema.resultListLocator] Path locator for the
 218            location of the array of records to flatten into `response.results`
 219        @param {Array} [schema.resultFields] Field identifiers to
 220            locate/assign values in the response records. See above for
 221            details.
 222        @param {Array} [schema.metaFields] Path locators to extract extra
 223            non-record related information from the data object.
 224      @param {Object|Array|String} data JSON data or its string serialization.
 225      @return {Object} An Object with properties `results` and `meta`
 226      @static
 227      **/
 228      apply: function(schema, data) {
 229          var data_in = data,
 230              data_out = { results: [], meta: {} };
 231  
 232          // Convert incoming JSON strings
 233          if (!isObject(data)) {
 234              try {
 235                  data_in = Y.JSON.parse(data);
 236              }
 237              catch(e) {
 238                  data_out.error = e;
 239                  return data_out;
 240              }
 241          }
 242  
 243          if (isObject(data_in) && schema) {
 244              // Parse results data
 245              data_out = SchemaJSON._parseResults.call(this, schema, data_in, data_out);
 246  
 247              // Parse meta data
 248              if (schema.metaFields !== undefined) {
 249                  data_out = SchemaJSON._parseMeta(schema.metaFields, data_in, data_out);
 250              }
 251          }
 252          else {
 253              data_out.error = new Error("JSON schema parse failure");
 254          }
 255  
 256          return data_out;
 257      },
 258  
 259      /**
 260       * Schema-parsed list of results from full data
 261       *
 262       * @method _parseResults
 263       * @param schema {Object} Schema to parse against.
 264       * @param json_in {Object} JSON to parse.
 265       * @param data_out {Object} In-progress parsed data to update.
 266       * @return {Object} Parsed data object.
 267       * @static
 268       * @protected
 269       */
 270      _parseResults: function(schema, json_in, data_out) {
 271          var getPath  = SchemaJSON.getPath,
 272              getValue = SchemaJSON.getLocationValue,
 273              path     = getPath(schema.resultListLocator),
 274              results  = path ?
 275                          (getValue(path, json_in) ||
 276                           // Fall back to treat resultListLocator as a simple key
 277                              json_in[schema.resultListLocator]) :
 278                          // Or if no resultListLocator is supplied, use the input
 279                          json_in;
 280  
 281          if (isArray(results)) {
 282              // if no result fields are passed in, then just take
 283              // the results array whole-hog Sometimes you're getting
 284              // an array of strings, or want the whole object, so
 285              // resultFields don't make sense.
 286              if (isArray(schema.resultFields)) {
 287                  data_out = SchemaJSON._getFieldValues.call(this, schema.resultFields, results, data_out);
 288              } else {
 289                  data_out.results = results;
 290              }
 291          } else if (schema.resultListLocator) {
 292              data_out.results = [];
 293              data_out.error = new Error("JSON results retrieval failure");
 294          }
 295  
 296          return data_out;
 297      },
 298  
 299      /**
 300       * Get field data values out of list of full results
 301       *
 302       * @method _getFieldValues
 303       * @param fields {Array} Fields to find.
 304       * @param array_in {Array} Results to parse.
 305       * @param data_out {Object} In-progress parsed data to update.
 306       * @return {Object} Parsed data object.
 307       * @static
 308       * @protected
 309       */
 310      _getFieldValues: function(fields, array_in, data_out) {
 311          var results = [],
 312              len = fields.length,
 313              i, j,
 314              field, key, locator, path, parser, val,
 315              simplePaths = [], complexPaths = [], fieldParsers = [],
 316              result, record;
 317  
 318          // First collect hashes of simple paths, complex paths, and parsers
 319          for (i=0; i<len; i++) {
 320              field = fields[i]; // A field can be a simple string or a hash
 321              key = field.key || field; // Find the key
 322              locator = field.locator || key; // Find the locator
 323  
 324              // Validate and store locators for later
 325              path = SchemaJSON.getPath(locator);
 326              if (path) {
 327                  if (path.length === 1) {
 328                      simplePaths.push({
 329                          key : key,
 330                          path: path[0]
 331                      });
 332                  } else {
 333                      complexPaths.push({
 334                          key    : key,
 335                          path   : path,
 336                          locator: locator
 337                      });
 338                  }
 339              } else {
 340              }
 341  
 342              // Validate and store parsers for later
 343              //TODO: use Y.DataSchema.parse?
 344              parser = (isFunction(field.parser)) ?
 345                          field.parser :
 346                          Y.Parsers[field.parser + ''];
 347  
 348              if (parser) {
 349                  fieldParsers.push({
 350                      key   : key,
 351                      parser: parser
 352                  });
 353              }
 354          }
 355  
 356          // Traverse list of array_in, creating records of simple fields,
 357          // complex fields, and applying parsers as necessary
 358          for (i=array_in.length-1; i>=0; --i) {
 359              record = {};
 360              result = array_in[i];
 361              if(result) {
 362                  // Cycle through complexLocators
 363                  for (j=complexPaths.length - 1; j>=0; --j) {
 364                      path = complexPaths[j];
 365                      val = SchemaJSON.getLocationValue(path.path, result);
 366                      if (val === undefined) {
 367                          val = SchemaJSON.getLocationValue([path.locator], result);
 368                          // Fail over keys like "foo.bar" from nested parsing
 369                          // to single token parsing if a value is found in
 370                          // results["foo.bar"]
 371                          if (val !== undefined) {
 372                              simplePaths.push({
 373                                  key:  path.key,
 374                                  path: path.locator
 375                              });
 376                              // Don't try to process the path as complex
 377                              // for further results
 378                              complexPaths.splice(i,1);
 379                              continue;
 380                          }
 381                      }
 382  
 383                      record[path.key] = Base.parse.call(this,
 384                          (SchemaJSON.getLocationValue(path.path, result)), path);
 385                  }
 386  
 387                  // Cycle through simpleLocators
 388                  for (j = simplePaths.length - 1; j >= 0; --j) {
 389                      path = simplePaths[j];
 390                      // Bug 1777850: The result might be an array instead of object
 391                      record[path.key] = Base.parse.call(this,
 392                              ((result[path.path] === undefined) ?
 393                              result[j] : result[path.path]), path);
 394                  }
 395  
 396                  // Cycle through fieldParsers
 397                  for (j=fieldParsers.length-1; j>=0; --j) {
 398                      key = fieldParsers[j].key;
 399                      record[key] = fieldParsers[j].parser.call(this, record[key]);
 400                      // Safety net
 401                      if (record[key] === undefined) {
 402                          record[key] = null;
 403                      }
 404                  }
 405                  results[i] = record;
 406              }
 407          }
 408          data_out.results = results;
 409          return data_out;
 410      },
 411  
 412      /**
 413       * Parses results data according to schema
 414       *
 415       * @method _parseMeta
 416       * @param metaFields {Object} Metafields definitions.
 417       * @param json_in {Object} JSON to parse.
 418       * @param data_out {Object} In-progress parsed data to update.
 419       * @return {Object} Schema-parsed meta data.
 420       * @static
 421       * @protected
 422       */
 423      _parseMeta: function(metaFields, json_in, data_out) {
 424          if (isObject(metaFields)) {
 425              var key, path;
 426              for(key in metaFields) {
 427                  if (metaFields.hasOwnProperty(key)) {
 428                      path = SchemaJSON.getPath(metaFields[key]);
 429                      if (path && json_in) {
 430                          data_out.meta[key] = SchemaJSON.getLocationValue(path, json_in);
 431                      }
 432                  }
 433              }
 434          }
 435          else {
 436              data_out.error = new Error("JSON meta data retrieval failure");
 437          }
 438          return data_out;
 439      }
 440  };
 441  
 442  // TODO: Y.Object + mix() might be better here
 443  Y.DataSchema.JSON = Y.mix(SchemaJSON, Base);
 444  
 445  
 446  }, '3.17.2', {"requires": ["dataschema-base", "json"]});