Merge pull request #24 from MaksymStoianov/max/next

Add comprehensive test suite, examples and new functions

Author: MaksymStoianov

README.md

@@ -0,0 +1,40 @@
+import { IllegalArgumentException } from "../../exception";
+import { isString, requireNonEmptyString } from "../../lang";
+import { parseA1Notation } from "./parseA1Notation";
+
+/**
+ * ## extractRangeFromA1Notation
+ *
+ * Extracts the **range part** from a full A1 notation string (e.g., `'Sheet1!A1:B2'` returns `'A1:B2'`).
+ *
+ * @param       {string} a1Notation - The A1 notation string (e.g., `'SheetName!A1:B2'`, `'A1:B2'`).
+ * @returns     {string|null} The extracted range string (e.g., `'A1:B2'`), or `null`.
+ * @throws      {Error}
+ * @throws      {IllegalArgumentException}
+ * @see         {@link parseA1Notation}
+ * @see         {@link GridRange}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Range|Range}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
+ * @see         [Class Range](https://developers.google.com/apps-script/reference/spreadsheet/range)
+ * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
+ * @since       1.6.0
+ * @version     1.0.0
+ * @environment `Google Apps Script`, `Browser`
+ * @author      Maksym Stoianov <stoianov.maksym@gmail.com>
+ * @license     Apache-2.0
+ */
+export function extractRangeFromA1Notation(a1Notation: string): string | null {
+  if (arguments.length === 0) {
+    throw new IllegalArgumentException();
+  }
+
+  const { a1Notation: range } = parseA1Notation(a1Notation);
+
+  if (!isString(range)) {
+    return null;
+  }
+
+  requireNonEmptyString(range);
+
+  return range;
+}

docs/assets/google-apps-script-utils-author-MaksymStoianov-artist-DarynaMikhailenko-2.jpg

@@ -0,0 +1,48 @@
+import { IllegalArgumentException } from "../../exception";
+import { isString } from "../../lang";
+import { isValidSheetName } from "./isValidSheetName";
+import { parseA1Notation } from "./parseA1Notation";
+
+/**
+ * ## extractSheetNameFromA1Notation
+ *
+ * Extracts the sheet name from an A1 notation string (e.g., `Sheet1!A1:B2`).
+ *
+ * This function returns the sheet name as a clean string, or `null` if the
+ * notation contains only the range part (e.g., `A1:B2`).
+ *
+ * @param       {string} a1Notation - The A1 notation string (e.g., `SheetName!A1`, `Sheet Name'!A:A`).
+ * @returns     {string|null} The extracted sheet name, or `null` if no sheet name is present in the notation.
+ * @throws      {Error}
+ * @throws      {IllegalArgumentException}
+ * @see         {@link parseA1Notation}
+ * @see         {@link GridRange}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Range|Range}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
+ * @see         [Class Range](https://developers.google.com/apps-script/reference/spreadsheet/range)
+ * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
+ * @since       1.6.0
+ * @version     1.0.0
+ * @environment `Google Apps Script`, `Browser`
+ * @author      Maksym Stoianov <stoianov.maksym@gmail.com>
+ * @license     Apache-2.0
+ */
+export function extractSheetNameFromA1Notation(
+  a1Notation: string
+): string | null {
+  if (arguments.length === 0) {
+    throw new IllegalArgumentException();
+  }
+
+  const { sheetName } = parseA1Notation(a1Notation);
+
+  if (!isString(sheetName)) {
+    return null;
+  }
+
+  if (!isValidSheetName(sheetName)) {
+    throw new Error("Expected a valid sheet name");
+  }
+
+  return sheetName;
+}

docs/assets/google-apps-script-utils-author-MaksymStoianov-artist-DarynaMikhailenko.jpg

@@ -47,6 +47,8 @@ export { appendRow } from "./appendRow";
 export { appendRows } from "./appendRows";
 export { convertRichTextToHtml } from "./convertRichTextToHtml";
 export { doGridRangesIntersect } from "./doGridRangesIntersect";
+export { extractRangeFromA1Notation } from "./extractRangeFromA1Notation";
+export { extractSheetNameFromA1Notation } from "./extractSheetNameFromA1Notation";
 export { getColumnIndexByLetter } from "./getColumnIndexByLetter";
 export { getColumnLetterByIndex } from "./getColumnLetterByIndex";
 export { getSheetById } from "./getSheetById";
@@ -64,5 +66,10 @@ export { highlightHtml } from "./highlightHtml";
 export { sortSheets } from "./sortSheets";
 
 export { parseA1Notation } from "./parseA1Notation";
+export {
+  parseA1Notations,
+  type A1NotationParseOptions
+} from "./parseA1Notations";
 
 export { toA1Notation } from "./toA1Notation";
+export { updateSheetNameInA1Notation } from "./updateSheetNameInA1Notation";

src/appsscript/sheet/extractRangeFromA1Notation.ts

@@ -1,4 +1,4 @@
-import { isEmpty, isString } from "../../lang";
+import { isString, nonEmpty } from "../../lang";
 
 /**
  * ## isValidSheetName
@@ -11,9 +11,9 @@ import { isEmpty, isString } from "../../lang";
  * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
  * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
  * @since       1.0.0
- * @version     1.0.0
+ * @version     1.0.1
  * @environment `Google Apps Script`, `Browser`
  */
 export function isValidSheetName(value: unknown): value is string {
-  return isString(value) && !isEmpty(value);
+  return isString(value) && nonEmpty(value);
 }

src/appsscript/sheet/extractSheetNameFromA1Notation.ts

@@ -33,16 +33,17 @@ import type { GridRange } from "./types";
  * parseA1Notation("'Sheet name'!A1:B2");
  * ```
  *
- * @param       a1Notation - The A1 notation string to parse.
- * @returns     An object representing the parsed grid range.
+ * @param       {string} a1Notation - The A1 notation string to parse.
+ * @returns     {GridRange} An object representing the parsed grid range.
  * @throws      {@link IllegalArgumentException}
+ * @see         {@link parseA1Notations}
  * @see         {@link GridRange}
  * @see         {@link GoogleAppsScript.Spreadsheet.Range|Range}
  * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
  * @see         [Class Range](https://developers.google.com/apps-script/reference/spreadsheet/range)
  * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
  * @since       1.0.0
- * @version     1.0.1
+ * @version     1.1.0
  * @environment `Google Apps Script`, `Browser`
  * @author      Maksym Stoianov <stoianov.maksym@gmail.com>
  * @license     Apache-2.0
@@ -52,7 +53,7 @@ export function parseA1Notation(a1Notation: string): GridRange {
     throw new IllegalArgumentException();
   }
 
-  const trimmedInput = requireNonEmptyString(a1Notation.trim());
+  const trimmedInput = requireNonEmptyString(a1Notation).trim();
 
   let sheetName: string | null = null;
   let rangeA1Part: string;
@@ -268,32 +269,12 @@ export function parseA1Notation(a1Notation: string): GridRange {
     throw new SyntaxError(`"${a1Notation}" is not a valid A1 notation.`);
   }
 
-  let fullCanonicalA1Notation = "";
-  if (sheetName !== null) {
-    const isSimpleSheetName = /^[A-Z_][A-Z0-9_]*$/i.test(sheetName);
-
-    if (!isSimpleSheetName) {
-      if (!sheetName.includes("'")) {
-        fullCanonicalA1Notation += `'${sheetName}'!`;
-      } else if (!sheetName.includes('"')) {
-        fullCanonicalA1Notation += `"${sheetName}"!`;
-      } else {
-        fullCanonicalA1Notation += `'${sheetName.replace(/'/g, "''")}'!`;
-      }
-    } else {
-      fullCanonicalA1Notation += `${sheetName}!`;
-    }
-  }
-  fullCanonicalA1Notation += canonicalA1Notation;
-
-  const result: GridRange = {
+  return {
     sheetName,
-    a1Notation: fullCanonicalA1Notation,
+    a1Notation: canonicalA1Notation,
     startRowIndex: currentStartRowIndex,
     endRowIndex: finalEndRowIndex,
     startColumnIndex: currentStartColumnIndex,
     endColumnIndex: finalEndColumnIndex
   };
-
-  return result;
 }

src/appsscript/sheet/index.ts

@@ -0,0 +1,72 @@
+import { IllegalArgumentException } from "../../exception";
+import { isObject, requireNonEmptyString } from "../../lang";
+import { parseA1Notation } from "./parseA1Notation";
+import { GridRange } from "./types";
+
+export interface A1NotationParseOptions {
+  includeSheetNames?: boolean;
+}
+
+/**
+ * ## parseA1Notations
+ *
+ * Parses a comma-separated string of A1 notations into an array of {@link GridRange} objects.
+ * Validates the format and sheet name requirements based on the provided options.
+ *
+ * @param       {string} value - The input string to be parsed.
+ * @param       {A1NotationParseOptions} options - An object with options for parsing.
+ * @returns     {GridRange[]} An array of {@link GridRange} objects.
+ * @throws      {@link Error}
+ * @throws      {@link IllegalArgumentException}
+ * @see         {@link parseA1Notation}
+ * @see         {@link GridRange}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Range|Range}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
+ * @see         [Class Range](https://developers.google.com/apps-script/reference/spreadsheet/range)
+ * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
+ * @since       1.6.0
+ * @version     1.0.0
+ * @environment `Google Apps Script`, `Browser`
+ * @author      Maksym Stoianov <stoianov.maksym@gmail.com>
+ * @license     Apache-2.0
+ */
+export function parseA1Notations(
+  value: string,
+  { includeSheetNames }: A1NotationParseOptions
+): GridRange[] {
+  if (arguments.length === 0) {
+    throw new IllegalArgumentException();
+  }
+
+  const trimmedInput = requireNonEmptyString(value).trim();
+
+  if (trimmedInput === "") {
+    return [];
+  }
+
+  const ranges = trimmedInput
+    .split(",")
+    .map(item => item.trim())
+    .filter(Boolean)
+    .map(parseA1Notation);
+
+  if (!ranges.every(isObject)) {
+    throw new Error("One or more values are not valid ranges.");
+  }
+
+  for (const range of ranges) {
+    if (includeSheetNames === true && !range.sheetName) {
+      throw new Error(
+        `Missing sheet name in "${range.a1Notation}". Ranges must include a sheet name.`
+      );
+    }
+
+    if (includeSheetNames === false && range.sheetName) {
+      throw new Error(
+        `Sheet names are not allowed. Found a sheet name in "${range.a1Notation}".`
+      );
+    }
+  }
+
+  return ranges;
+}

src/appsscript/sheet/isValidSheetName.ts

@@ -0,0 +1,60 @@
+import { IllegalArgumentException } from "../../exception";
+import { requireNonEmptyString } from "../../lang";
+import { isValidSheetName } from "./isValidSheetName";
+import { parseA1Notation } from "./parseA1Notation";
+
+/**
+ * ## updateSheetNameInA1Notation
+ *
+ * Updates or sets the sheet name within an A1 notation string, while preserving the range information (e.g., `A1:B2`).
+ *
+ * @param       {string} a1Notation - The source A1 notation, which may or may not include a sheet name (e.g., `'Sheet Name'!A1:B2` or `A1:B2`).
+ * @param       {string|null} [sheetName] - The new sheet name to set.
+ * Pass `null` or `undefined` to remove any existing sheet name and return only the range.
+ * @returns     {string} The new A1 notation string with the updated sheet name (e.g., `'New Sheet'!A1:B2` or just `A1:B2`).
+ * @throws      {@link IllegalArgumentException}
+ * @throws      {@link EmptyStringException}
+ * @see         {@link parseA1Notation}
+ * @see         {@link GridRange}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Range|Range}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
+ * @see         [Class Range](https://developers.google.com/apps-script/reference/spreadsheet/range)
+ * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
+ * @since       1.6.0
+ * @version     1.0.0
+ * @environment `Google Apps Script`, `Browser`
+ * @author      Maksym Stoianov <stoianov.maksym@gmail.com>
+ * @license     Apache-2.0
+ */
+export function updateSheetNameInA1Notation(
+  a1Notation: string,
+  sheetName?: string | null
+): string {
+  if (arguments.length === 0) {
+    throw new IllegalArgumentException();
+  }
+
+  const gridRange = parseA1Notation(a1Notation);
+
+  const range = requireNonEmptyString(gridRange.a1Notation);
+
+  if (!isValidSheetName(sheetName)) {
+    return range;
+  }
+
+  const isSimpleSheetName = /^[A-Z_][A-Z0-9_]*$/i.test(sheetName);
+
+  if (isSimpleSheetName) {
+    return `${sheetName}!${range}`;
+  }
+
+  if (!sheetName.includes("'")) {
+    return `'${sheetName}'!${range}`;
+  }
+
+  if (!sheetName.includes('"')) {
+    return `"${sheetName}"!${range}`;
+  }
+
+  return `'${sheetName.replace(/'/g, "''")}'!${range}`;
+}