Source: sobject.js

  1. /**
  2.  * @file Represents Salesforce SObject
  3.  * @author Shinichi Tomita <shinichi.tomita@gmail.com>
  4.  */
  6. 'use strict';
  8. var _      = require('lodash/core'),
  9.     Record = require('./record'),
  10.     Query  = require('./query'),
  11.     Cache  = require('./cache'),
  12.     QuickAction = require('./quick-action');
  14. /**
  15.  * A class for organizing all SObject access
  16.  *
  17.  * @constructor
  18.  */
  19. var SObject = module.exports = function(conn, type) {
  20.   this._conn = conn;
  21.   this.type = type;
  22.   var cacheOptions = { key: "describe." + this.type };
  23.   this.describe$ = conn.cache.makeCacheable(this.describe, this, cacheOptions);
  24.   this.describe = conn.cache.makeResponseCacheable(this.describe, this, cacheOptions);
  26.   cacheOptions = { key: "layouts." + this.type };
  27.   this.layouts$ = conn.cache.makeCacheable(this.layouts, this, cacheOptions);
  28.   this.layouts = conn.cache.makeResponseCacheable(this.layouts, this, cacheOptions);
  30.   cacheOptions = { key: "compactLayouts." + this.type };
  31.   this.compactLayouts$ = conn.cache.makeCacheable(this.compactLayouts, this, cacheOptions);
  32.   this.compactLayouts = conn.cache.makeResponseCacheable(this.compactLayouts, this, cacheOptions);
  34.   cacheOptions = { key: "approvalLayouts." + this.type };
  35.   this.approvalLayouts$ = conn.cache.makeCacheable(this.approvalLayouts, this, cacheOptions);
  36.   this.approvalLayouts = conn.cache.makeResponseCacheable(this.approvalLayouts, this, cacheOptions);
  37. };
  39. /**
  40.  * Synonym of SObject#create()
  41.  *
  42.  * @method SObject#insert
  43.  * @param {Record|Array.<Record>} records - A record or array of records to create
  44.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
  45.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  46.  */
  47. /**
  48.  * Create records
  49.  *
  50.  * @method SObject#create
  51.  * @param {Record|Array.<Record>} records - A record or array of records to create
  52.  * @param {Object} [options] - Options for rest api.
  53.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
  54.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  55.  */
  56. SObject.prototype.insert =
  57. SObject.prototype.create = function(records, options, callback) {
  58.   if (typeof options === 'function') {
  59.     callback = options;
  60.     options = {};
  61.   }
  62.   return this._conn.create(this.type, records, options, callback);
  63. };
  65. /**
  66.  * Retrieve specified records
  67.  *
  68.  * @param {String|Array.<String>} ids - A record ID or array of record IDs
  69.  * @param {Object} [options] - Options for rest api.
  70.  * @param {Callback.<Record|Array.<Record>>} [callback] - Callback function
  71.  * @returns {Promise.<Record|Array.<Record>>}
  72.  */
  73. SObject.prototype.retrieve = function(ids, options, callback) {
  74.   if (typeof options === 'function') {
  75.     callback = options;
  76.     options = {};
  77.   }
  78.   return this._conn.retrieve(this.type, ids, options, callback);
  79. };
  81. /**
  82.  * Update records
  83.  *
  84.  * @param {Record|Array.<Record>} records - A record or array of records to update
  85.  * @param {Object} [options] - Options for rest api.
  86.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
  87.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  88.  */
  89. SObject.prototype.update = function(records, options, callback) {
  90.   if (typeof options === 'function') {
  91.     callback = options;
  92.     options = {};
  93.   }
  94.   return this._conn.update(this.type, records, options, callback);
  95. };
  97. /**
  98.  * Upsert records
  99.  *
  100.  * @param {Record|Array.<Record>} records - Record or array of records to upsert
  101.  * @param {String} extIdField - External ID field name
  102.  * @param {Object} [options] - Options for rest api.
  103.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback
  104.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  105.  */
  106. SObject.prototype.upsert = function(records, extIdField, options, callback) {
  107.   if (typeof options === 'function') {
  108.     callback = options;
  109.     options = {};
  110.   }
  111.   return this._conn.upsert(this.type, records, extIdField, options, callback);
  112. };
  114. /**
  115.  * Synonym of SObject#destroy()
  116.  *
  117.  * @method SObject#delete
  118.  * @param {String|Array.<String>} ids - A ID or array of IDs to delete
  119.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
  120.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  121.  */
  122. /**
  123.  * Synonym of SObject#destroy()
  124.  *
  125.  * @method SObject#del
  126.  * @param {String|Array.<String>} ids - A ID or array of IDs to delete
  127.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
  128.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  129.  */
  130. /**
  131.  * Delete records
  132.  *
  133.  * @method SObject#destroy
  134.  * @param {String|Array.<String>} ids - A ID or array of IDs to delete
  135.  * @param {Object} [options] - Options for rest api.
  136.  * @param {Callback.<RecordResult|Array.<RecordResult>>} [callback] - Callback function
  137.  * @returns {Promise.<RecordResult|Array.<RecordResult>>}
  138.  */
  139. SObject.prototype["delete"] =
  140. SObject.prototype.del =
  141. SObject.prototype.destroy = function(ids, options, callback) {
  142.   if (typeof options === 'function') {
  143.     callback = options;
  144.     options = {};
  145.   }
  146.   return this._conn.destroy(this.type, ids, options, callback);
  147. };
  149. /**
  150.  * Describe SObject metadata
  151.  *
  152.  * @param {Callback.<DescribeSObjectResult>} [callback] - Callback function
  153.  * @returns {Promise.<DescribeSObjectResult>}
  154.  */
  155. SObject.prototype.describe = function(callback) {
  156.   return this._conn.describe(this.type, callback);
  157. };
  159. /**
  160.  * Get record representation instance by given id
  161.  *
  162.  * @param {String} id - A record ID
  163.  * @returns {RecordReference}
  164.  */
  165. SObject.prototype.record = function(id) {
  166.   return new Record(this._conn, this.type, id);
  167. };
  169. /**
  170.  * Find and fetch records which matches given conditions
  171.  *
  172.  * @param {Object|String} [conditions] - Conditions in JSON object (MongoDB-like), or raw SOQL WHERE clause string.
  173.  * @param {Object|Array.<String>|String} [fields] - Fields to fetch. Format can be in JSON object (MongoDB-like), array of field names, or comma-separated field names.
  174.  * @param {Object} [options] - Query options.
  175.  * @param {Number} [options.limit] - Maximum number of records the query will return.
  176.  * @param {Number} [options.offset] - Offset number where begins returning results.
  177.  * @param {Number} [options.skip] - Synonym of options.offset.
  178.  * @param {Callback.<Array.<Record>>} [callback] - Callback function
  179.  * @returns {Query.<Array.<Record>>}
  180.  */
  181. SObject.prototype.find = function(conditions, fields, options, callback) {
  182.   if (typeof conditions === 'function') {
  183.     callback = conditions;
  184.     conditions = {};
  185.     fields = null;
  186.     options = null;
  187.   } else if (typeof fields === 'function') {
  188.     callback = fields;
  189.     fields = null;
  190.     options = null;
  191.   } else if (typeof options === 'function') {
  192.     callback = options;
  193.     options = null;
  194.   }
  195.   options = options || {};
  196.   var config = {
  197.     fields: fields,
  198.     includes: options.includes,
  199.     table: this.type,
  200.     conditions: conditions,
  201.     limit: options.limit,
  202.     offset: options.offset || options.skip
  203.   };
  204.   var query = new Query(this._conn, config);
  205.   query.setResponseTarget(Query.ResponseTargets.Records);
  206.   if (callback) { query.run(callback); }
  207.   return query;
  208. };
  210. /**
  211.  * Fetch one record which matches given conditions
  212.  *
  213.  * @param {Object|String} [conditions] - Conditions in JSON object (MongoDB-like), or raw SOQL WHERE clause string.
  214.  * @param {Object|Array.<String>|String} [fields] - Fields to fetch. Format can be in JSON object (MongoDB-like), array of field names, or comma-separated field names.
  215.  * @param {Object} [options] - Query options.
  216.  * @param {Number} [options.limit] - Maximum number of records the query will return.
  217.  * @param {Number} [options.offset] - Offset number where begins returning results.
  218.  * @param {Number} [options.skip] - Synonym of options.offset.
  219.  * @param {Callback.<Record>} [callback] - Callback function
  220.  * @returns {Query.<Record>}
  221.  */
  222. SObject.prototype.findOne = function(conditions, fields, options, callback) {
  223.   if (typeof conditions === 'function') {
  224.     callback = conditions;
  225.     conditions = {};
  226.     fields = null;
  227.     options = null;
  228.   } else if (typeof fields === 'function') {
  229.     callback = fields;
  230.     fields = null;
  231.     options = null;
  232.   } else if (typeof options === 'function') {
  233.     callback = options;
  234.     options = null;
  235.   }
  236.   options = _.extend(options || {}, { limit: 1 });
  237.   var query = this.find(conditions, fields, options);
  238.   query.setResponseTarget(Query.ResponseTargets.SingleRecord);
  239.   if (callback) { query.run(callback); }
  240.   return query;
  241. };
  243. /**
  244.  * Find and fetch records only by specifying fields to fetch.
  245.  *
  246.  * @param {Object|Array.<String>|String} [fields] - Fields to fetch. Format can be in JSON object (MongoDB-like), array of field names, or comma-separated field names.
  247.  * @param {Callback.<Array.<Record>>} [callback] - Callback function
  248.  * @returns {Query.<Array.<Record>>}
  249.  */
  250. SObject.prototype.select = function(fields, callback) {
  251.   return this.find(null, fields, null, callback);
  252. };
  254. /**
  255.  * Count num of records which matches given conditions
  256.  *
  257.  * @param {Object|String} [conditions] - Conditions in JSON object (MongoDB-like), or raw SOQL WHERE clause string.
  258.  * @param {Callback.<Number>} [callback] - Callback function
  259.  * @returns {Query.<Number>}
  260.  */
  261. SObject.prototype.count = function(conditions, callback) {
  262.   if (typeof conditions === 'function') {
  263.     callback = conditions;
  264.     conditions = {};
  265.   }
  266.   var query = this.find(conditions, { "count()" : true });
  267.   query.setResponseTarget("Count");
  268.   if (callback) { query.run(callback); }
  269.   return query;
  270. };
  273. /**
  274.  * Call Bulk#load() to execute bulkload, returning batch object
  275.  *
  276.  * @param {String} operation - Bulk load operation ('insert', 'update', 'upsert', 'delete', or 'hardDelete')
  277.  * @param {Object} [options] - Options for bulk loading operation
  278.  * @param {String} [options.extIdField] - External ID field name (used when upsert operation).
  279.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulkload. Accepts array of records, CSv string, and CSV data input stream.
  280.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  281.  * @returns {Bulk~Batch}
  282.  */
  283. SObject.prototype.bulkload = function(operation, options, input, callback) {
  284.   return this._conn.bulk.load(this.type, operation, options, input, callback);
  285. };
  287. /**
  288.  * Synonym of SObject#createBulk()
  289.  *
  290.  * @method SObject#insertBulk
  291.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk insert. Accepts array of records, CSv string, and CSV data input stream.
  292.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  293.  * @returns {Bulk~Batch}
  294.  */
  295. /**
  296.  * Bulkly insert input data using bulk API
  297.  *
  298.  * @method SObject#createBulk
  299.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk insert. Accepts array of records, CSv string, and CSV data input stream.
  300.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  301.  * @returns {Bulk~Batch}
  302.  */
  303. SObject.prototype.insertBulk =
  304. SObject.prototype.createBulk = function(input, callback) {
  305.   return this.bulkload("insert", input, callback);
  306. };
  308. /**
  309.  * Bulkly update records by input data using bulk API
  310.  *
  311.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk update Accepts array of records, CSv string, and CSV data input stream.
  312.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  313.  * @returns {Bulk~Batch}
  314.  */
  315. SObject.prototype.updateBulk = function(input, callback) {
  316.   return this.bulkload("update", input, callback);
  317. };
  319. /**
  320.  * Bulkly upsert records by input data using bulk API
  321.  *
  322.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk upsert. Accepts array of records, CSv string, and CSV data input stream.
  323.  * @param {String} [options.extIdField] - External ID field name
  324.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  325.  * @returns {Bulk~Batch}
  326.  */
  327. SObject.prototype.upsertBulk = function(input, extIdField, callback) {
  328.   return this.bulkload("upsert", { extIdField: extIdField }, input, callback);
  329. };
  331. /**
  332.  * Synonym of SObject#destroyBulk()
  333.  *
  334.  * @method SObject#deleteBulk
  335.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk delete. Accepts array of records, CSv string, and CSV data input stream.
  336.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  337.  * @returns {Bulk~Batch}
  338.  */
  339. /**
  340.  * Bulkly delete records specified by input data using bulk API
  341.  *
  342.  * @method SObject#destroyBulk
  343.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk delete. Accepts array of records, CSv string, and CSV data input stream.
  344.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  345.  * @returns {Bulk~Batch}
  346.  */
  347. SObject.prototype.deleteBulk =
  348. SObject.prototype.destroyBulk = function(input, callback) {
  349.   return this.bulkload("delete", input, callback);
  350. };
  352. /**
  353.  * Synonym of SObject#destroyHardBulk()
  354.  *
  355.  * @method SObject#deleteHardBulk
  356.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk delete. Accepts array of records, CSv string, and CSV data input stream.
  357.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  358.  * @returns {Bulk~Batch}
  359.  */
  360. /**
  361.  * Bulkly hard delete records specified in input data using bulk API
  362.  *
  363.  * @method SObject#destroyHardBulk
  364.  * @param {Array.<Record>|stream.Stream|String} [input] - Input source for bulk delete. Accepts array of records, CSv string, and CSV data input stream.
  365.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  366.  * @returns {Bulk~Batch}
  367.  */
  368. SObject.prototype.deleteHardBulk =
  369. SObject.prototype.destroyHardBulk = function(input, callback) {
  370.   return this.bulkload("hardDelete", input, callback);
  371. };
  373. /**
  374.  * Retrieve recently accessed records
  375.  *
  376.  * @param {Callback.<Array.<RecordResult>>} [callback] - Callback function
  377.  * @returns {Promise.<Array.<RecordResult>>}
  378.  */
  379. SObject.prototype.recent = function (callback) {
  380.   return this._conn.recent(this.type, callback);
  381. };
  383. /**
  384.  * Retrieve the updated records
  385.  *
  386.  * @param {String|Date} start - start date or string representing the start of the interval
  387.  * @param {String|Date} end - start date or string representing the end of the interval, must be > start
  388.  * @param {Callback.<UpdatedRecordsInfo>} [callback] - Callback function
  389.  * @returns {Promise.<UpdatedRecordsInfo>}
  390.  */
  391. SObject.prototype.updated = function (start, end, callback) {
  392.   return this._conn.updated(this.type, start, end, callback);
  393. };
  395. /**
  396.  * Retrieve the deleted records
  397.  *
  398.  * @param {String|Date} start - start date or string representing the start of the interval
  399.  * @param {String|Date} end - start date or string representing the end of the interval, must be > start
  400.  * @param {Callback.<DeletedRecordsInfo>} [callback] - Callback function
  401.  * @returns {Promise.<DeletedRecordsInfo>}
  402.  */
  403. SObject.prototype.deleted = function (start, end, callback) {
  404.   return this._conn.deleted(this.type, start, end, callback);
  405. };
  407. /**
  408.  * @typedef {Object} LayoutInfo
  409.  * @prop {Array.<Object>} layouts - Array of layouts
  410.  * @prop {Array.<Object>} recordTypeMappings - Array of record type mappings
  411.  */
  412. /**
  413.  * Describe layout information for SObject
  414.  *
  415.  * @param {String} [layoutName] - Name of named layout. (e.g. UserAlt in User SObject)
  416.  * @param {Callback.<LayoutInfo>} [callback] - Callback function
  417.  * @returns {Promise.<LayoutInfo>}
  418.  */
  419. SObject.prototype.layouts = function(layoutName, callback) {
  420.   if (typeof layoutName === 'function') {
  421.     callback = layoutName;
  422.     layoutName = null;
  423.   }
  424.   var url = "/sobjects/" + this.type + "/describe/" + (layoutName ? "namedLayouts/"+layoutName : "layouts");
  425.   return this._conn.request(url, callback);
  426. };
  428. /**
  429.  * @typedef {Object} CompactLayoutInfo
  430.  * @prop {Array.<Object>} compactLayouts - Array of compact layouts
  431.  * @prop {String} defaultCompactLayoutId - ID of default compact layout
  432.  * @prop {Array.<Object>} recordTypeCompactLayoutMappings - Array of record type mappings
  433.  */
  434. /**
  435.  * Describe compact layout information defined for SObject
  436.  *
  437.  * @param {Callback.<CompactLayoutInfo>} [callback] - Callback function
  438.  * @returns {Promise.<CompactLayoutInfo>}
  439.  */
  440. SObject.prototype.compactLayouts = function(callback) {
  441.   var url = "/sobjects/" + this.type + "/describe/compactLayouts";
  442.   return this._conn.request(url, callback);
  443. };
  446. /**
  447.  * @typedef {Object} ApprovalLayoutInfo
  448.  * @prop {Array.<Object>} approvalLayouts - Array of approval layouts
  449.  */
  450. /**
  451.  * Describe compact layout information defined for SObject
  452.  *
  453.  * @param {Callback.<ApprovalLayoutInfo>} [callback] - Callback function
  454.  * @returns {Promise.<ApprovalLayoutInfo>}
  455.  */
  456. SObject.prototype.approvalLayouts = function(callback) {
  457.   var url = "/sobjects/" + this.type + "/describe/approvalLayouts";
  458.   return this._conn.request(url, callback);
  459. };
  461. /**
  462.  * Returns the list of list views for the SObject
  463.  *
  464.  * @param {Callback.<ListViewsInfo>} [callback] - Callback function
  465.  * @returns {Promise.<ListViewsInfo>}
  466.  */
  467. SObject.prototype.listviews = function(callback) {
  468.   var url = this._conn._baseUrl() + '/sobjects/' + this.type + '/listviews';
  469.   return this._conn.request(url, callback);
  470. };
  472. /**
  473.  * Returns the list view info in specifed view id
  474.  *
  475.  * @param {String} id - List view ID
  476.  * @returns {ListView}
  477.  */
  478. SObject.prototype.listview = function(id) {
  479.   return new ListView(this._conn, this.type, id);
  480. };
  482. /**
  483.  * Returns all registered quick actions for the SObject
  484.  *
  485.  * @param {Callback.<Array.<QuickAction~QuickActionInfo>>} [callback] - Callback function
  486.  * @returns {Promise.<Array.<QuickAction~QuickActionInfo>>}
  487.  */
  488. SObject.prototype.quickActions = function(callback) {
  489.   return this._conn.request("/sobjects/" + this.type + "/quickActions").thenCall(callback);
  490. };
  492. /**
  493.  * Get reference for specified quick aciton in the SObject
  494.  *
  495.  * @param {String} actionName - Name of the quick action
  496.  * @returns {QuickAction}
  497.  */
  498. SObject.prototype.quickAction = function(actionName) {
  499.   return new QuickAction(this._conn, "/sobjects/" + this.type + "/quickActions/" + actionName);
  500. };
  503. /**
  504.  * A class for organizing list view information
  505.  *
  506.  * @protected
  507.  * @class ListView
  508.  * @param {Connection} conn - Connection instance
  509.  * @param {SObject} type - SObject type
  510.  * @param {String} id - List view ID
  511.  */
  512. var ListView = function(conn, type, id) {
  513.   this._conn = conn;
  514.   this.type = type;
  515.   this.id = id;
  516. };
  518. /**
  519.  * Executes query for the list view and returns the resulting data and presentation information.
  520.  *
  521.  * @param {Callback.<ListViewResultInfo>} [callback] - Callback function
  522.  * @returns {Promise.<ListViewResultInfo>}
  523.  */
  524. ListView.prototype.results = function(callback) {
  525.   var url =  this._conn._baseUrl() + '/sobjects/' + this.type + '/listviews/' + this.id + '/results';
  526.   return this._conn.request(url, callback);
  527. };
  530. /**
  531.  * Returns detailed information about a list view
  532.  *
  533.  * @param {Callback.<ListViewDescribeInfo>} [callback] - Callback function
  534.  * @returns {Promise.<ListViewDescribeInfo>}
  535.  */
  536. ListView.prototype.describe = function(callback) {
  537.   var url =  this._conn._baseUrl() + '/sobjects/' + this.type + '/listviews/' + this.id + '/describe';
  538.   return this._conn.request(url, callback);
  539. };
  541. /**
  542.  * Explain plan for executing list view
  543.  *
  544.  * @param {Callback.<ExplainInfo>} [callback] - Callback function
  545.  * @returns {Promise.<ExplainInfo>}
  546.  */
  547. ListView.prototype.explain = function(callback) {
  548.   var url = "/query/?explain=" + this.id;
  549.   return this._conn.request(url, callback);
  550. };