GlideRecord Helper Functions

var GlideRecordUtils = Class.create();
GlideRecordUtils.prototype = {

  /**
   * Safely get a record by sys_id with error handling
   *
   * @param {string} table - Table name
   * @param {string} sysId - sys_id of record
   * @returns {GlideRecord|null} GlideRecord if found, null otherwise
   */
  get: function(table, sysId) {
    if (!table || !sysId) {
      gs.warn('GlideRecordUtils.get: table and sysId are required');
      return null;
    }

    try {
      var gr = new GlideRecord(table);
      if (gr.get(sysId)) {
        return gr;
      }
    } catch (e) {
      gs.error('GlideRecordUtils.get error: ' + e.message);
    }

    return null;
  },

  /**
   * Query records with simplified syntax
   *
   * @param {string} table - Table name
   * @param {object} query - Query object {field: value}
   * @param {object} options - {orderBy, limit, fields}
   * @returns {Array} Array of record objects
   */
  query: function(table, query, options) {
    var results = [];
    options = options || {};

    try {
      var gr = new GlideRecord(table);

      // Apply query conditions
      for (var field in query) {
        gr.addQuery(field, query[field]);
      }

      // Apply options
      if (options.orderBy) {
        gr.orderBy(options.orderBy);
      }

      if (options.limit) {
        gr.setLimit(options.limit);
      }

      gr.query();

      // Convert to array of objects
      while (gr.next()) {
        var record = {};

        if (options.fields) {
          // Only include specified fields
          options.fields.forEach(function(field) {
            record[field] = gr.getValue(field);
          });
        } else {
          // Include all fields (be careful with this on large records)
          record.sys_id = gr.sys_id.toString();

          var elements = gr.getElements();
          for (var i = 0; i < elements.size(); i++) {
            var element = elements.get(i);
            var fieldName = element.getName();
            record[fieldName] = gr.getValue(fieldName);
          }
        }

        results.push(record);
      }
    } catch (e) {
      gs.error('GlideRecordUtils.query error: ' + e.message);
    }

    return results;
  },

  /**
   * Update multiple records matching query
   *
   * @param {string} table - Table name
   * @param {object} query - Query object {field: value}
   * @param {object} updates - Fields to update {field: value}
   * @returns {number} Number of records updated
   */
  updateMultiple: function(table, query, updates) {
    var count = 0;

    try {
      var gr = new GlideRecord(table);

      // Apply query
      for (var field in query) {
        gr.addQuery(field, query[field]);
      }

      gr.query();

      // Update each record
      while (gr.next()) {
        for (var updateField in updates) {
          gr.setValue(updateField, updates[updateField]);
        }
        gr.update();
        count++;
      }

      gs.info('GlideRecordUtils.updateMultiple: Updated ' + count + ' records in ' + table);
    } catch (e) {
      gs.error('GlideRecordUtils.updateMultiple error: ' + e.message);
    }

    return count;
  },

  /**
   * Delete multiple records matching query
   *
   * @param {string} table - Table name
   * @param {object} query - Query object {field: value}
   * @param {boolean} confirm - Safety confirmation (must be true)
   * @returns {number} Number of records deleted
   */
  deleteMultiple: function(table, query, confirm) {
    if (!confirm) {
      gs.warn('GlideRecordUtils.deleteMultiple: confirmation required');
      return 0;
    }

    var count = 0;

    try {
      var gr = new GlideRecord(table);

      // Apply query
      for (var field in query) {
        gr.addQuery(field, query[field]);
      }

      gr.query();

      // Delete each record
      while (gr.next()) {
        gr.deleteRecord();
        count++;
      }

      gs.info('GlideRecordUtils.deleteMultiple: Deleted ' + count + ' records from ' + table);
    } catch (e) {
      gs.error('GlideRecordUtils.deleteMultiple error: ' + e.message);
    }

    return count;
  },

  /**
   * Copy record to another table or same table
   *
   * @param {GlideRecord} sourceRecord - Source record to copy
   * @param {string} targetTable - Target table name
   * @param {Array} excludeFields - Fields to exclude from copy
   * @returns {string} sys_id of new record or empty string
   */
  copyRecord: function(sourceRecord, targetTable, excludeFields) {
    excludeFields = excludeFields || ['sys_id', 'sys_created_by', 'sys_created_on', 'sys_updated_by', 'sys_updated_on'];

    try {
      var grNew = new GlideRecord(targetTable);
      grNew.initialize();

      // Copy all fields except excluded ones
      var elements = sourceRecord.getElements();
      for (var i = 0; i < elements.size(); i++) {
        var element = elements.get(i);
        var fieldName = element.getName();

        if (excludeFields.indexOf(fieldName) === -1) {
          grNew.setValue(fieldName, sourceRecord.getValue(fieldName));
        }
      }

      var newId = grNew.insert();

      if (newId) {
        gs.info('GlideRecordUtils.copyRecord: Copied ' + sourceRecord.getTableName() +
                ' to ' + targetTable + ', new sys_id: ' + newId);
        return newId;
      }
    } catch (e) {
      gs.error('GlideRecordUtils.copyRecord error: ' + e.message);
    }

    return '';
  },

  /**
   * Count records matching query
   *
   * @param {string} table - Table name
   * @param {object} query - Query object {field: value}
   * @returns {number} Count of matching records
   */
  count: function(table, query) {
    try {
      var ga = new GlideAggregate(table);

      // Apply query
      for (var field in query) {
        ga.addQuery(field, query[field]);
      }

      ga.addAggregate('COUNT');
      ga.query();

      if (ga.next()) {
        return parseInt(ga.getAggregate('COUNT'));
      }
    } catch (e) {
      gs.error('GlideRecordUtils.count error: ' + e.message);
    }

    return 0;
  },

  /**
   * Check if record exists
   *
   * @param {string} table - Table name
   * @param {object} query - Query object {field: value}
   * @returns {boolean} True if at least one record exists
   */
  exists: function(table, query) {
    try {
      var gr = new GlideRecord(table);

      for (var field in query) {
        gr.addQuery(field, query[field]);
      }

      gr.setLimit(1);
      gr.query();

      return gr.hasNext();
    } catch (e) {
      gs.error('GlideRecordUtils.exists error: ' + e.message);
    }

    return false;
  },

  /**
   * Get related records (following reference field)
   *
   * @param {GlideRecord} record - Source record
   * @param {string} relationshipField - Field name that contains relationship
   * @param {object} options - {fields, limit, orderBy}
   * @returns {Array} Array of related records
   */
  getRelatedRecords: function(record, relationshipField, options) {
    options = options || {};
    var results = [];

    try {
      var relatedTable = record.getElement(relationshipField).getReferenceTable();
      var relatedId = record.getValue(relationshipField);

      if (!relatedTable || !relatedId) {
        return results;
      }

      var gr = new GlideRecord(relatedTable);
      if (!gr.get(relatedId)) {
        return results;
      }

      // Convert single record to result format
      var result = {};
      if (options.fields) {
        options.fields.forEach(function(field) {
          result[field] = gr.getValue(field);
        });
      } else {
        result.sys_id = gr.sys_id.toString();
        result.display_value = gr.getDisplayValue();
      }

      results.push(result);
    } catch (e) {
      gs.error('GlideRecordUtils.getRelatedRecords error: ' + e.message);
    }

    return results;
  },

  type: 'GlideRecordUtils'
};