@mcpher/gas-fakes 1.2.19 → 1.2.21

package/src/services/formapp/fakeformresponse.js

@@ -0,0 +1,84 @@
+import { Proxies } from '../../support/proxies.js';
+import { newFakeItemResponse } from './fakeitemresponse.js';
+
+export const newFakeFormResponse = (...args) => {
+  return Proxies.guard(new FakeFormResponse(...args));
+};
+
+/**
+ * @class FakeFormResponse
+ * @see https://developers.google.com/apps-script/reference/forms/form-response
+ */
+export class FakeFormResponse {
+  /**
+   *
+   * @param {import('./fakeform.js').FakeForm} form the parent form
+   * @param {object} resource the response resource from the Forms API
+   */
+  constructor(form, resource) {
+    this.__form = form;
+    this.__resource = resource;
+  }
+
+  /**
+   * Gets the email address of the respondent.
+   * @returns {string} the respondent's email
+   */
+  getRespondentEmail() {
+    return this.__resource.respondentEmail || '';
+  }
+
+  /**
+   * Gets the unique ID for this form response.
+   * @returns {string} the unique ID
+   */
+  getId() {
+    return this.__resource.responseId;
+  }
+
+  /**
+   * Gets the date and time the response was submitted.
+   * @returns {Date} the submission timestamp
+   */
+  getTimestamp() {
+    return new Date(this.__resource.lastSubmittedTime);
+  }
+
+  /**
+   * Gets all item responses contained in the form response.
+   * @returns {import('./fakeitemresponse.js').FakeItemResponse[]} an array of item responses
+   */
+  getItemResponses() {
+    if (!this.__resource.answers) {
+      return [];
+    }
+
+    // Create a map to group answers by their parent form item. This is crucial for grid items,
+    // where each row is a separate answer in the API response but should be consolidated
+    // into a single ItemResponse in Apps Script.
+    const groupedAnswers = new Map();
+
+    for (const [questionId, answer] of Object.entries(this.__resource.answers)) {
+      const item = this.__form.getItemById(questionId);
+
+      if (item) {
+        const itemId = item.getId(); // Use the unique item ID as the key.
+        if (!groupedAnswers.has(itemId)) {
+          // Store the item itself along with an array for its answers.
+          groupedAnswers.set(itemId, { item, answers: [] });
+        }
+        // Add the raw answer object from the API response to the item's answer list.
+        // This correctly groups all row answers for a grid under the same parent item.
+        groupedAnswers.get(itemId).answers.push(answer);
+      }
+    }
+
+    // Now, create one FakeItemResponse for each grouped item.
+    const itemResponses = Array.from(groupedAnswers.values()).map(({ item, answers }) => {
+      return newFakeItemResponse(item, answers);
+    });
+
+    // Finally, sort the responses based on the item's index in the form.
+    return itemResponses.sort((a, b) => a.getItem().getIndex() - b.getItem().getIndex());
+  }
+}

package/src/services/formapp/fakegriditem.js

@@ -0,0 +1,105 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeFormItem } from './fakeformitem.js';
+import { registerFormItem } from './formitemregistry.js';
+import { signatureArgs } from '../../support/helpers.js';
+import { Utils } from '../../support/utils.js';
+import { ItemType } from '../enums/formsenums.js';
+
+export const newFakeGridItem = (...args) => {
+  return Proxies.guard(new FakeGridItem(...args));
+};
+
+/**
+ * @class FakeGridItem
+ * A fake for the GridItem class in Apps Script.
+ * @see https://developers.google.com/apps-script/reference/forms/grid-item
+ */
+export class FakeGridItem extends FakeFormItem {
+  constructor(form, itemId) {
+    super(form, itemId);
+  }
+
+  /**
+   * Gets the values for every column in the grid.
+   * @returns {string[]} an array of column values
+   */
+  getColumns() {
+    const choiceQuestion = this.__resource.questionGroupItem?.grid?.columns;
+    if (!choiceQuestion || !choiceQuestion.options) {
+      return [];
+    }
+    return choiceQuestion.options.map(option => option.value);
+  }
+
+  /**
+   * Gets the values for every row in the grid.
+   * @returns {string[]} an array of row values
+   */
+  getRows() {
+    const questions = this.__resource.questionGroupItem?.questions;
+    if (!questions) {
+      return [];
+    }
+    return questions.map(question => question.rowQuestion?.title || null).filter(f=>f);
+  }
+
+  /**
+   * Sets the columns of the grid based on an array of values.
+   * @param {string[]} columns an array of column values
+   * @returns {FakeGridItem} this item, for chaining
+   */
+  setColumns(columns) {
+    const { nargs, matchThrow } = signatureArgs(arguments, 'GridItem.setColumns');
+    if (nargs !== 1 || !Utils.is.array(columns) || !columns.every(Utils.is.string)) {
+      matchThrow('Invalid arguments: expected a string array.');
+    }
+    if (columns.length === 0) {
+      throw new Error('The array of columns cannot be empty.');
+    }
+
+    const updatedResource = JSON.parse(JSON.stringify(this.__resource));
+    updatedResource.questionGroupItem.grid.columns.options = columns.map(c => ({ value: c }));
+
+    const updateRequest = Forms.newRequest().setUpdateItem({
+      item: updatedResource,
+      location: { index: this.getIndex() },
+      updateMask: 'questionGroupItem.grid.columns.options',
+    });
+
+    return this.__update(updateRequest);
+  }
+
+  /**
+   * Sets the rows of the grid based on an array of values.
+   * @param {string[]} rows an array of row values
+   * @returns {FakeGridItem} this item, for chaining
+   */
+  setRows(rows) {
+    const { nargs, matchThrow } = signatureArgs(arguments, 'GridItem.setRows');
+    if (nargs !== 1 || !Utils.is.array(rows) || !rows.every(Utils.is.string)) {
+      matchThrow('Invalid arguments: expected a string array.');
+    }
+    if (rows.length === 0) {
+      throw new Error('The array of rows cannot be empty.');
+    }
+
+    const updatedResource = JSON.parse(JSON.stringify(this.__resource));
+    updatedResource.questionGroupItem.questions = rows.map(r => ({
+      rowQuestion: { title: r },
+    }));
+
+    const updateRequest = Forms.newRequest().setUpdateItem({
+      item: updatedResource,
+      location: { index: this.getIndex() },
+      updateMask: 'questionGroupItem.questions',
+    });
+
+    return this.__update(updateRequest);
+  }
+
+  toString() {
+    return 'GridItem';
+  }
+}
+
+registerFormItem(ItemType.GRID, newFakeGridItem);

package/src/services/formapp/fakeitemresponse.js

@@ -0,0 +1,56 @@
+import { Proxies } from '../../support/proxies.js';
+import { newFakeFormItem } from './fakeformitem.js';
+
+export const newFakeItemResponse = (...args) => {
+  return Proxies.guard(new FakeItemResponse(...args));
+};
+
+/**
+ * @class FakeItemResponse
+ * @see https://developers.google.com/apps-script/reference/forms/item-response
+ */
+export class FakeItemResponse {
+  /**
+   *
+   * @param {import('./fakeformitem.js').FakeFormItem} item the item this is a response to
+   * @param {object[]} answers an array of answer objects from the Forms API response
+   */
+  constructor(item, answers) {
+    this.__item = item;
+    this.__answers = answers; // This is now an array of answer objects
+  }
+
+  /**
+   * Gets the Item object for the question that this response answers.
+   */
+  getItem() {
+    return this.__item;
+  }
+
+  /**
+   * Gets the ID of the item this response is for. Note: This is a custom method for gas-fakes.
+   * @returns {string} the item's ID
+   */
+  getId() {
+    return this.__item.getId();
+  }
+
+  /**
+   * Gets the answer to the question as a string.
+   * @returns {string} the response
+   */
+  getResponse() {
+    // Flatten the 'textAnswers.answers' arrays from all answer objects.
+    // This correctly combines all row answers for a grid item.
+    const allTextAnswers = this.__answers.flatMap(
+      (answer) => answer?.textAnswers?.answers || []
+    );
+
+    if (allTextAnswers.length === 0) {
+      return '';
+    }
+
+    // For items like grids, there can be multiple answer values. The live script joins them with a comma.
+    return allTextAnswers.map(a => a.value).join(',');
+  }
+}

package/src/services/formapp/fakelistitem.js

@@ -0,0 +1,124 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeFormItem } from './fakeformitem.js';
+import { newFakeChoice } from './fakechoice.js';
+import { registerFormItem } from './formitemregistry.js';
+import { ItemType } from '../enums/formsenums.js';
+
+export const newFakeListItem = (...args) => {
+  return Proxies.guard(new FakeListItem(...args));
+};
+
+/**
+ * @class FakeListItem
+ * @see https://developers.google.com/apps-script/reference/forms/list-item
+ */
+export class FakeListItem extends FakeFormItem {
+  constructor(...args) {
+    super(...args);
+  }
+
+  /**
+   * Creates a new choice for this item.
+   * @param {string} value The value for the new choice.
+   * @param {import('./pagebreakitem.js').FakePageBreakItem | import('../formapp.js').PageNavigationType} navigation The navigation action.
+   * @returns {import('./fakechoice.js').FakeChoice} The new choice.
+   */
+  createChoice(value, navigation) {
+    // In the real API, this creates a Choice object that is not yet attached.
+    // For the fake, we can create and return a representation of it.
+    if (navigation) {
+      let navType;
+      let pageId;
+      if (typeof navigation.getId === 'function') {
+        // It's a PageBreakItem object
+        navType = 'GO_TO_PAGE';
+        pageId = navigation.getId();
+      } else {
+        // It's a PageNavigationType enum value
+        navType = navigation.toString().toUpperCase();
+      }
+      return newFakeChoice(value, navType, pageId, this.__form, this.getType());
+    }
+
+    return newFakeChoice(value, null, null, this.__form, this.getType());
+  }
+
+  /**
+   * Gets the choices for this item.
+   * @returns {import('./fakechoice.js').FakeChoice[]} The choices.
+   */
+  getChoices() {
+    const options = this.__resource.questionItem?.question?.choiceQuestion?.options || [];
+    return options.map(option => {
+      let navType = null;
+      let pageId = null;
+
+      // Translate from API format back to Apps Script format.
+      if (option.goToSectionId) {
+        navType = 'GO_TO_PAGE';
+        pageId = option.goToSectionId;
+      } else if (option.goToAction) {
+        switch (option.goToAction) {
+          case 'NEXT_SECTION': navType = 'CONTINUE'; break;
+          case 'RESTART_FORM': navType = 'RESTART'; break;
+          case 'SUBMIT_FORM': navType = 'SUBMIT'; break;
+        }
+      }
+      return newFakeChoice(option.value, navType, pageId, this.__form, this.getType());
+    });
+  }
+  /**
+   * Sets the choices for the item.
+   * @param {import('./fakechoice.js').FakeChoice[]} choices The choices to set.
+   * @returns {FakeListItem} The item, for chaining.
+   */
+  setChoices(choices) {
+    // The Forms API expects an array of {value: string}, not FakeChoice objects.
+    // We need to map the array of FakeChoice objects to the correct format.
+    const options = choices.map(choice => {
+      const option = { value: choice.getValue() };
+      // The FakeChoice object stores these as internal properties.
+      // We need to translate from Apps Script enums to the Forms API enums.
+      if (choice.__navType) {
+        const navType = choice.__navType.toUpperCase();
+        switch (navType) {
+          case 'GO_TO_PAGE':
+            // For navigating to a specific page, you ONLY set the goToSectionId.
+            // The pageId is the itemId of the PageBreakItem.
+            option.goToSectionId = choice.__pageId;
+            break;
+          case 'CONTINUE':
+            option.goToAction = 'NEXT_SECTION';
+            break;
+          default:
+            option.goToAction = navType; // For RESTART_FORM, SUBMIT_FORM
+            break;
+        }
+      }
+      return option;
+    });
+    const updateRequest = {
+      updateItem: {
+        item: {
+          // The item payload should contain the questionItem directly,
+          // not nested within another 'question' object.
+          questionItem: { question: { choiceQuestion: { type: 'DROP_DOWN', options } } }
+        },
+        location: { index: this.getIndex() },
+        updateMask: 'questionItem.question.choiceQuestion',
+      },
+    };
+    return this.__update(updateRequest);
+  }
+
+  /**
+   * Returns the string "ListItem" to identify the class.
+   * @returns {string} The string "ListItem".
+   */
+  toString() {
+    return 'ListItem';
+  }
+}
+
+// Register the factory function for this item type.
+registerFormItem(ItemType.LIST, newFakeListItem);

package/src/services/formapp/fakemultiplechoiceitem.js

@@ -0,0 +1,25 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeChoiceItem } from './fakechoiceitem.js';
+import { registerFormItem } from './formitemregistry.js';
+import { ItemType } from '../enums/formsenums.js';
+
+export const newFakeMultipleChoiceItem = (form, itemId) => {
+  return Proxies.guard(new FakeMultipleChoiceItem(form, itemId));
+};
+
+/**
+ * @class FakeMultipleChoiceItem
+ * A fake for the MultipleChoiceItem class in Apps Script.
+ * @see https://developers.google.com/apps-script/reference/forms/multiple-choice-item
+ */
+export class FakeMultipleChoiceItem extends FakeChoiceItem {
+  constructor(form, itemId) {
+    super(form, itemId);
+  }
+  toString() {
+    return 'MultipleChoiceItem';
+  }
+}
+
+// Register the factory function for this item type.
+registerFormItem(ItemType.MULTIPLE_CHOICE, newFakeMultipleChoiceItem);

package/src/services/formapp/fakepagebreakitem.js

@@ -0,0 +1,54 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeFormItem } from './fakeformitem.js';
+import { registerFormItem } from './formitemregistry.js';
+import { ItemType, PageNavigationType } from '../enums/formsenums.js';
+
+export const newFakePageBreakItem = (...args) => {
+  return Proxies.guard(new FakePageBreakItem(...args));
+};
+
+/**
+ * @class FakePageBreakItem
+ * @see https://developers.google.com/apps-script/reference/forms/page-break-item
+ */
+export class FakePageBreakItem extends FakeFormItem {
+  constructor(...args) {
+    super(...args);
+  }
+
+  /**
+   * Sets the page to navigate to when the user advances past this page.
+   * @param {FakePageBreakItem | import('../formapp.js').PageNavigationType} navigation The navigation action.
+   * @returns {FakePageBreakItem} The item, for chaining.
+   */
+  setGoToPage(navigation) {
+    // There is no public Forms API endpoint to set the navigation for a PageBreakItem.
+    // This method is therefore not implementable in the fake environment.
+    throw new Error('setGoToPage is not supported for PageBreakItems via the public Google Forms API.');
+  }
+
+  /**
+   * Gets the page-break item that this page break navigates to.
+   * @returns {FakePageBreakItem | null} The page-break item, or null if the page does not navigate to a specific page.
+   */
+  getGoToPage() {
+    // The API does not support setting a specific page destination for a page break.
+    return null;
+  }
+
+  getPageNavigationType() {
+    // Since navigation cannot be set via the API, the navigation type will always be the default.
+    return PageNavigationType.CONTINUE;
+  }
+
+  /**
+   * Returns the string "PageBreakItem" to identify the class.
+   * @returns {string} The string "PageBreakItem".
+   */
+  toString() {
+    return 'PageBreakItem';
+  }
+}
+
+// Register the factory function for this item type.
+registerFormItem(ItemType.PAGE_BREAK, newFakePageBreakItem);

package/src/services/formapp/fakescaleitem.js

@@ -0,0 +1,121 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeFormItem } from './fakeformitem.js';
+import { registerFormItem } from './formitemregistry.js';
+import { ItemType } from '../enums/formsenums.js';
+import { signatureArgs } from '../../support/helpers.js';
+import { Utils } from '../../support/utils.js';
+const { is } = Utils;
+
+export const newFakeScaleItem = (...args) => {
+  return Proxies.guard(new FakeScaleItem(...args));
+};
+
+/**
+ * @class FakeScaleItem
+ * A fake for the ScaleItem class in Apps Script.
+ * @see https://developers.google.com/apps-script/reference/forms/scale-item
+ */
+export class FakeScaleItem extends FakeFormItem {
+  constructor(form, itemId) {
+    super(form, itemId);
+  }
+
+  /**
+   * Gets the lower bound of the scale.
+   * @returns {Integer} the lower bound
+   */
+  getLowerBound() {
+    return this.__resource.questionItem.question.scaleQuestion.low || 0;
+  }
+
+  /**
+   * Gets the upper bound of the scale.
+   * @returns {Integer} the upper bound
+   */
+  getUpperBound() {
+    return this.__resource.questionItem.question.scaleQuestion.high;
+  }
+
+  /**
+   * Gets the label for the scale's lower bound.
+   * @returns {string} the label for the lower bound
+   */
+  getLeftLabel() {
+    return this.__resource.questionItem.question.scaleQuestion.lowLabel || '';
+  }
+
+  /**
+   * Gets the label for the scale's upper bound.
+   * @returns {string} the label for the upper bound
+   */
+  getRightLabel() {
+    return this.__resource.questionItem.question.scaleQuestion.highLabel || '';
+  }
+
+  /**
+   * Sets the scale's bounds and, optionally, labels.
+   * @param {Integer} lower the lower bound
+   * @param {Integer} upper the upper bound
+   * @returns {FakeScaleItem} this item, for chaining
+   */
+  setBounds(lower, upper) {
+    const { nargs, matchThrow } = signatureArgs(arguments, 'ScaleItem.setBounds');
+    if (nargs !== 2 || !is.number(lower) || !is.number(upper)) {
+      matchThrow('Invalid arguments: expected two numbers.');
+    }
+
+    // Truncate decimals as per documentation.
+    const lowerInt = Math.trunc(lower);
+    const upperInt = Math.trunc(upper);
+
+    // Validate bounds as per documentation.
+    if (lowerInt !== 0 && lowerInt !== 1) {
+      throw new Error('The lower bound must be 0 or 1.');
+    }
+    if (upperInt < 3 || upperInt > 10) {
+      throw new Error('The upper bound must be between 3 and 10, inclusive.');
+    }
+    const updatedResource = JSON.parse(JSON.stringify(this.__resource));
+    updatedResource.questionItem.question.scaleQuestion.low = lowerInt;
+    updatedResource.questionItem.question.scaleQuestion.high = upperInt;
+
+    const updateRequest = Forms.newRequest().setUpdateItem({
+      item: updatedResource,
+      location: { index: this.getIndex() },
+      updateMask: 'questionItem.question.scaleQuestion',
+    });
+
+    return this.__update(updateRequest);
+  }
+
+  /**
+   * Sets the labels for the scale's lower and upper bounds.
+   * @param {string} lower the label for the lower bound
+   * @param {string} upper the label for the upper bound
+   * @returns {FakeScaleItem} this item, for chaining
+   */
+  setLabels(lower, upper) {
+    const { nargs, matchThrow } = signatureArgs(arguments, 'ScaleItem.setLabels');
+    if (nargs !== 2 || !is.string(lower) || !is.string(upper)) {
+      matchThrow('Invalid arguments: expected two strings.');
+    }
+
+    const updatedResource = JSON.parse(JSON.stringify(this.__resource));
+    updatedResource.questionItem.question.scaleQuestion.lowLabel = lower;
+    updatedResource.questionItem.question.scaleQuestion.highLabel = upper;
+
+    const updateRequest = Forms.newRequest().setUpdateItem({
+      item: updatedResource,
+      location: { index: this.getIndex() },
+      updateMask: 'questionItem.question.scaleQuestion',
+    });
+
+    return this.__update(updateRequest);
+  }
+
+  toString() {
+    return 'ScaleItem';
+  }
+}
+
+registerFormItem(ItemType.SCALE, newFakeScaleItem);

package/src/services/formapp/fakesectionheaderitem.js

@@ -0,0 +1,25 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeFormItem } from './fakeformitem.js';
+import { registerFormItem } from './formitemregistry.js';
+import { ItemType } from '../enums/formsenums.js';
+
+export const newFakeSectionHeaderItem = (...args) => {
+  return Proxies.guard(new FakeSectionHeaderItem(...args));
+};
+
+/**
+ * @class FakeSectionHeaderItem
+ * A fake for the SectionHeaderItem class in Apps Script.
+ * @see https://developers.google.com/apps-script/reference/forms/section-header-item
+ */
+export class FakeSectionHeaderItem extends FakeFormItem {
+  constructor(form, itemId) {
+    super(form, itemId);
+  }
+
+  toString() {
+    return 'SectionHeaderItem';
+  }
+}
+
+registerFormItem(ItemType.SECTION_HEADER, newFakeSectionHeaderItem);

package/src/services/formapp/faketextitem.js

@@ -0,0 +1,20 @@
+import { Proxies } from '../../support/proxies.js';
+import { FakeFormItem } from './fakeformitem.js';
+
+export const newFakeTextItem = (...args) => {
+  return Proxies.guard(new FakeTextItem(...args));
+};
+
+/**
+ * @class FakeTextItem
+ * @see https://developers.google.com/apps-script/reference/forms/text-item
+ */
+export class FakeTextItem extends FakeFormItem {
+  constructor(...args) {
+    super(...args);
+  }
+
+  toString() {
+    return 'TextItem';
+  }
+}

package/src/services/formapp/formitems.js

@@ -2,5 +2,10 @@
 // with the formitemRegistry. By importing them here, we trigger their
 // registration code.
 
-import './fakecheckboxitem.js';
+import './fakecheckboxitem.js'
+import './fakegriditem.js';
+import './fakecheckboxgriditem.js';
+import './fakescaleitem.js';
+import './fakepagebreakitem.js';
+import './fakelistitem.js';
 // Add other item types here as they are implemented (e.g., './faketextitem.js')

package/src/support/sxforms.js

@@ -12,7 +12,7 @@ import { getFormsApiClient } from '../services/advforms/formsapis.js';
 
 const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 
-export const sxForms = async (Auth, { prop, method, params, options = {} }) => {
+export const sxForms = async (Auth, { prop, subProp, method, params, options = {} }) => {
 
   const apiClient = getFormsApiClient();
 
@@ -24,7 +24,11 @@ export const sxForms = async (Auth, { prop, method, params, options = {} }) => {
     let error;
 
     try {
-      const callish = apiClient[prop];
+      // Access the base property (e.g., 'forms'), then the sub-property if it exists (e.g., 'responses').
+      let callish = apiClient[prop];
+      if (subProp) {
+        callish = callish[subProp];
+      }
       response = await callish[method](params, options);
     } catch (err) {
       error = err;
@@ -35,14 +39,14 @@ export const sxForms = async (Auth, { prop, method, params, options = {} }) => {
 
     if (isRetryable && i < maxRetries - 1) {
       const jitter = Math.floor(Math.random() * 1000);
-      syncWarn(`Retryable error on Forms API call ${prop}.${method} (status: ${response?.status}). Retrying in ${delay + jitter}ms...`);
+      syncWarn(`Retryable error on Forms API call ${prop}${subProp ? '.' + subProp : ''}.${method} (status: ${response?.status}). Retrying in ${delay + jitter}ms...`);
       await sleep(delay + jitter);
       delay *= 2;
       continue;
     }
 
     if (error || isRetryable) {
-      syncError(`Failed in sxForms for ${prop}.${method}`, error);
+      syncError(`Failed in sxForms for ${prop}${subProp ? '.' + subProp : ''}.${method}`, error);
       return { data: null, response: responseSyncify(response) };
     }
     return { data: response.data, response: responseSyncify(response) };

package/src/support/syncit.js

@@ -151,8 +151,8 @@ const fxGeneric = ({
   if (method === "get") {
     return register(resourceId, cacher, result, false, otherParams);
   }
-
-  if (resourceId) {
+  
+  else if (resourceId) {
     cacher.clear(resourceId);
   }
   return result;