Google Apps Script: Преобразование объекта в строку

/**
 * Преобразует объект JavaScript в строку JSON.
 *
 * @param {any} value Значение для преобразования.
 * @param {(key: string, value: any) => any | (string | number)[]} [replacer] Функция-заменитель или массив строк/чисел для фильтрации свойств.
 * @param {string | number} [space] Строка или число для добавления отступов (форматирования) в вывод.
 * @return {string} Строка JSON.
 */
JSON.stringify(value[, replacer[, space]])

/**
 * Пример преобразования простого объекта конфигурации в JSON.
 */
function simpleObjectToString() {
  const config = {
    apiKey: 'XYZ123',
    isEnabled: true,
    retryCount: 3
  };

  // Преобразование в компактную JSON-строку
  const jsonString = JSON.stringify(config);
  Logger.log(jsonString); // Вывод: "{"apiKey":"XYZ123","isEnabled":true,"retryCount":3}"

  // Преобразование в форматированную JSON-строку с отступом в 2 пробела
  const formattedJsonString = JSON.stringify(config, null, 2);
  Logger.log(formattedJsonString);
  /* Вывод:
  {
    "apiKey": "XYZ123",
    "isEnabled": true,
    "retryCount": 3
  }
  */
}

/**
 * Пример преобразования сложного объекта с массивами и вложенностью.
 */
function complexObjectToString() {
  const campaignData = {
    id: 'CMP-001',
    name: 'Summer Sale Campaign',
    startDate: new Date(2023, 5, 1), // Июнь 1, 2023
    targets: [
      { region: ' EMEA', budget: 5000 },
      { region: 'NA', budget: 10000 }
    ],
    metadata: {
      owner: 'marketing@example.com',
      lastUpdated: new Date()
    }
  };

  // Используем replacer для форматирования дат в ISO строку (хотя JSON.stringify делает это по умолчанию)
  const replacer = (key, value) => {
    if (value instanceof Date) {
      return value.toISOString();
    }
    return value;
  };

  const jsonString = JSON.stringify(campaignData, replacer, 2);
  Logger.log(jsonString);
  /* Примерный вывод:
  {
    "id": "CMP-001",
    "name": "Summer Sale Campaign",
    "startDate": "2023-06-01T00:00:00.000Z", // Зависит от часового пояса сервера GAS
    "targets": [
      {
        "region": " EMEA",
        "budget": 5000
      },
      {
        "region": "NA",
        "budget": 10000
      }
    ],
    "metadata": {
      "owner": "marketing@example.com",
      "lastUpdated": "2023-10-27T10:30:00.000Z" // Текущая дата/время в ISO
    }
  }
  */
}

/**
 * Демонстрация обработки функций и циклических ссылок.
 */
function handleSpecialCases() {
  const obj = {
    name: 'Test Object',
    data: { value: 1 },
    run: function() { console.log('Running...'); },
    nothing: undefined
  };
  obj.self = obj; // Создаем циклическую ссылку

  // Попытка прямой сериализации вызовет ошибку
  try {
    JSON.stringify(obj);
  } catch (e) {
    Logger.log(`Ошибка при прямой сериализации: ${e}`); // TypeError: Converting circular structure to JSON
  }

  // Использование replacer для удаления циклических ссылок и функций
  const getCircularReplacer = () => {
    const seen = new WeakSet();
    return (key, value) => {
      if (typeof value === 'object' && value !== null) {
        if (seen.has(value)) {
          return '[Circular]'; // Заменяем циклическую ссылку
        }
        seen.add(value);
      }
      if (typeof value === 'function') {
        return '[Function]'; // Заменяем функцию
      }
      if (typeof value === 'undefined') {
        return '[Undefined]'; // Явно указываем undefined
      }
      return value;
    };
  };

  const safeJsonString = JSON.stringify(obj, getCircularReplacer(), 2);
  Logger.log(safeJsonString);
  /* Вывод:
  {
    "name": "Test Object",
    "data": {
      "value": 1
    },
    "run": "[Function]",
    "nothing": "[Undefined]",
    "self": "[Circular]"
  }
  */
}

/**
 * Использование шаблонных литералов для простого строкового представления.
 */
function templateLiteralExample() {
  const userData = {
    name: 'Alice',
    email: 'alice@example.com',
    lastLogin: new Date()
  };

  const userString = `User: ${userData.name}, Email: ${userData.email}, Last Login: ${userData.lastLogin.toLocaleString()}`;
  Logger.log(userString);
  // Вывод: User: Alice, Email: alice@example.com, Last Login: 10/27/2023, 11:00:00 AM (формат зависит от локали)
}

/**
 * Пример ручной конкатенации (не рекомендуется).
 */
function manualConcatenation() {
  const item = { id: 101, status: 'active' };
  const itemString = 'ID: ' + item.id + '; Status: ' + item.status;
  Logger.log(itemString); // Вывод: ID: 101; Status: active
}

/**
 * Пример использования Utilities.jsonStringify.
 */
function utilitiesJsonStringifyExample() {
  const data = { a: 1, b: [2, 3] };
  const jsonString = Utilities.jsonStringify(data);
  Logger.log(jsonString); // Вывод: "{"a":1,"b":[2,3]}"
}

/**
 * Пример извлечения данных из объекта Range перед сериализацией.
 */
function serializeSheetData() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getActiveSheet();
  const range = sheet.getRange('A1:B2');

  // Прямая сериализация объекта Range бесполезна
  // Logger.log(JSON.stringify(range)); // Выведет {} или что-то неинформативное

  // Извлекаем нужные данные
  const data = {
    values: range.getValues(),
    formulas: range.getFormulas(),
    sheetName: sheet.getName(),
    rangeA1Notation: range.getA1Notation()
  };

  const jsonString = JSON.stringify(data, null, 2);
  Logger.log(jsonString);
  /* Примерный вывод:
  {
    "values": [
      ["Header 1", "Header 2"],
      ["Data A", "Data B"]
    ],
    "formulas": [
      ["", ""],
      ["", ""]
    ],
    "sheetName": "Sheet1",
    "rangeA1Notation": "A1:B2"
  }
  */
}

/**
 * Обработка потенциальной ошибки при сериализации.
 *
 * @param {any} dataToSerialize Данные для сериализации.
 * @return {string | null} Строка JSON или null в случае ошибки.
 */
function safeStringify(dataToSerialize) {
  try {
    // Используем replacer для предотвращения циклических ссылок
    const getCircularReplacer = () => {
      const seen = new WeakSet();
      return (key, value) => {
        if (typeof value === 'object' && value !== null) {
          if (seen.has(value)) {
            return '[Circular Reference]';
          }
          seen.add(value);
        }
        return value;
      };
    };
    return JSON.stringify(dataToSerialize, getCircularReplacer());
  } catch (error) {
    Logger.log(`Ошибка сериализации: ${error.message}`);
    // Можно добавить более детальное логирование или обработку
    console.error('Не удалось сериализовать объект:', error);
    return null; // Возвращаем null или другое индикативное значение
  }
}

/**
 * Логирование структурированных данных в Cloud Logging.
 */
function logToCloud() {
  const eventData = {
    timestamp: new Date().toISOString(),
    source: 'DataProcessingTrigger',
    payload: { userId: 123, action: 'update', success: true },
    executionTimeMs: 150
  };

  // Cloud Logging автоматически обработает объект, но явное использование
  // console.log с объектом или строкой JSON гарантирует читаемость.
  console.log({ message: 'Processing event', event: eventData });

  // Можно также сначала преобразовать в строку, если нужно логгировать именно JSON
  const eventString = JSON.stringify(eventData);
  console.log(`Raw event JSON: ${eventString}`);
}

/**
 * Сохранение конфигурации в ячейку Google Sheets.
 */
function saveConfigToSheet() {
  const config = {
    sheetId: 'abc123xyz',
    syncEnabled: true,
    lastSync: new Date().toISOString()
  };
  const configString = JSON.stringify(config);

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const configSheet = ss.getSheetByName('Configuration') || ss.insertSheet('Configuration');
  configSheet.getRange('A1').setValue(configString);
  Logger.log('Конфигурация сохранена в ячейку A1.');
}

/**
 * Загрузка конфигурации из Google Sheets.
 *
 * @return {object | null} Разобранный объект конфигурации или null.
 */
function loadConfigFromSheet() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const configSheet = ss.getSheetByName('Configuration');
  if (!configSheet) return null;

  const configString = configSheet.getRange('A1').getValue();
  if (!configString) return null;

  try {
    const config = JSON.parse(configString);
    // Опционально: преобразовать строки дат обратно в объекты Date
    if (config.lastSync) {
      config.lastSync = new Date(config.lastSync);
    }
    return config;
  } catch (e) {
    Logger.log(`Ошибка парсинга конфигурации: ${e}`);
    return null;
  }
}

/**
 * Отправка данных о событии на внешний API.
 */
function sendDataToApi() {
  const eventPayload = {
    event: 'user_signup',
    user_id: 'usr_789',
    timestamp: new Date().toISOString(),
    details: { source: 'webapp', referrer: 'google' }
  };

  const options = {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(eventPayload), // Сериализуем объект в JSON
    muteHttpExceptions: true // Чтобы обработать ошибки вручную
  };

  const url = 'https://api.example.com/events';
  const response = UrlFetchApp.fetch(url, options);

  Logger.log(`API Response Code: ${response.getResponseCode()}`);
  Logger.log(`API Response Body: ${response.getContentText()}`);
}

/**
 * Сохранение пользовательских настроек в PropertiesService.
 */
function saveUserSettings() {
  const userSettings = {
    theme: 'dark',
    notifications: { email: true, push: false },
    language: 'ru'
  };

  const settingsString = JSON.stringify(userSettings);
  PropertiesService.getUserProperties().setProperty('userSettings', settingsString);
  Logger.log('Настройки пользователя сохранены.');
}

/**
 * Загрузка пользовательских настроек из PropertiesService.
 *
 * @return {object} Объект настроек пользователя.
 */
function loadUserSettings() {
  const settingsString = PropertiesService.getUserProperties().getProperty('userSettings');
  if (settingsString) {
    try {
      return JSON.parse(settingsString);
    } catch (e) {
      Logger.log(`Ошибка парсинга настроек: ${e}`);
      // Возвращаем настройки по умолчанию
      return { theme: 'light', notifications: { email: true, push: true }, language: 'en' };
    }
  } else {
    // Настройки не найдены, возвращаем по умолчанию
    return { theme: 'light', notifications: { email: true, push: true }, language: 'en' };
  }
}