Shared Utilities¶

The src/notFeatures/ directory holds cross-cutting infrastructure that is deliberately not a product feature: logging, spreadsheet and tab access, row-entry reading and writing, cell formatting, type helpers, and self-documenting source-code labels. Nothing here is user-facing; everything is called by the feature modules and by the legacy v3Legacy JavaScript. src/errorsAndExceptions.ts standardizes error reporting.

errorsAndExceptions.ts¶

A small module standardizing how the add-on reports failures: a consistent alert dialog with a title, message, and traceable short error id (e.g. [id 7b63e0]), plus paired logging.

Function	Description
`showUiError(msg, title?, errorId?, isLogging?)`	Logs the error (optionally) and shows a `SpreadsheetApp.getUi().alert` with title, message, and error id. If no UI is available (running from the script editor), the exception is swallowed via `ignoreException`.
`showUiErrorAndThrow(msg, title?, errorId?, args?)`	Shows the alert and then throws. Return type `never`, so it can be used in `??` fallbacks.
`throwError(msg, id?, args?)`	Logs and throws an `EqualEntryLogicError` with the id prefixed onto the message.
`ignoreException(msg, error)`	Records a deliberately swallowed exception as a warning.

logging.ts¶

Replaces the global console with an adapter so all legacy console.log calls route through the same versioned, stack-annotated loggers. Every log line is prefixed with the app patch version and suffixed with a condensed 10-frame call stack.

Function	Description
`logDebug(...args)`	Debug-level logging; suppressed when debug logging is off.
`logWarn(...args)` / `logError(...args)`	Warning and error logging; always emitted.
`logDebugToggle(isON = true)`	Turns debug logging on or off at runtime; runnable from the Apps Script editor.

sheetAndTabs.ts¶

Function	Description
`findTab(name, sheetId)`	Returns the tab or null.
`getTabOrThrow(name, sheetId, userErrorMsg?)`	Returns the tab, or shows a "Tab NOT FOUND" alert (optionally with a hint) and throws.
`createTab(name, sheetId, afterTab?)`	Inserts a new tab, positioned after `afterTab` when provided.
`getSheetId(s?)` / `getParentSheetId(tab)` / `getSheet(id)` / `getSheetName(sheetId)`	Spreadsheet id and lookup helpers.
`getCurrentOrFallbackSheetId(fallback)`	The active spreadsheet id, or a fallback with a warning; lets features run from the script editor against a fixed example spreadsheet.

tabEntriesEditing.ts¶

Provides the RowEntry abstraction: a row read as a {headerName: displayValue} object, together with its column ordering and its source cell, so code can manipulate rows by column name rather than index.

Function	Description
`readRowEntries<T>(tab, headerRow?, leftMostColumn?)`	Reads the whole data block in one call and returns typed `RowEntry` objects. Warns about duplicate column names.
`writeRowEntry(entry, tab, startCell?)`	Writes an entry's values back as one row.
`clearDataRows(tab, headerRow?, leftMostColumn?)`	Clears content and data validations from the header row down.
`getSrcCellByKey(e, key)`	The `Cell` for a named column in an entry's row; throws on an unknown key.
`readCellValue(cell, tab)` / `writeCellValue(value, cell, tab)`	Single-cell read and write.
`activateCells(cells, tab)`	Selects a list of cells (used to draw attention to problem or changed cells).

Deprecated variants also exist: readRowEntriesDeprecated, writeRowEntryDeprecated, writeRowEntryDeprecated2, activateCellsA1.

formatting.ts¶

Row-height, column-width, and wrap helpers plus two formatting utilities.

Function	Description
`setWordWrap(range, isWrapped)` / `setWordWrapToRows(startRow, tab)`	Toggle wrapping.
`setColumnWidths(width, columns, tab)` / `setRowHeights(height, startRow, tab)` / `changeRowHeightsBy(diff, tab, startRow, rowCount?)`	Size setters.
`normalizeRowHeightsForMultiline(startRow, tab)`	Forces auto-sized rows into a readable multi-line height.
`resetSizesFromRow(startRow, tab)`	Collapses rows and columns to defaults before re-applying a layout.
`formatTimeInNYC(time)`	The standard log-row timestamp, formatted in America/New_York.
`getSheetUrlFormula(sheetId, tabId, sheetName)` / `getUrlFormula(url, urlText)`	`=HYPERLINK(...)` formula builders.

Cell.ts¶

Member	Description
`Cell.new(row, column)`	Static factory for an immutable cell coordinate.
`cell.setTo(value, targetTab)` / `cell.getFrom(sourceTab)`	Write and read this coordinate on a tab.

Other helpers¶

Function	File	Description
`getUserAtKeyboardEmail()`	`session.ts`	Email of the user currently operating the spreadsheet; used to attribute AI-review decisions.
`logDebugArray(data, name, ...indices)`	`logArrayInfo.ts`	Logs a compact sample of a possibly 2D array (dimensions plus first, middle, and last elements) instead of dumping large datasets.
`getEndIndexAfterRangeCheck(...)` / `getStartIndexOfOpenRangeAfterLogging(...)`	`batchApiIndexConsistency.ts`	Log and sanity-check batch Sheets API index ranges; the strict variant shows a UI error instead of sending a malformed request.
`nullOf<T>()`, `getObjectKeys<T>(obj)`, `isBlankArray(a)`, `isBlankString(s)`	`tsUtils.ts`	Small typed utility functions.
`doNothing(...args)`	`utils.js`	Explicit no-op, used for label-only menu items (the "about: v..." entry) and test mocks.
`isObjectPathExist(obj, path)`	`utils.js`	Safely checks whether a nested dotted path exists on an object.

sourceCodeLabels.ts¶

Three no-op tagged-template functions used as in-scope documentation markers. They have no runtime effect; their value is that IDE "find all references" works across them.

Function	Description
`doc`	Marks in-scope documentation (an alternative to JSDoc that stays attached to the code it describes).
`protocol`	Marks constraints that must not be violated by future edits.
`todo`	Marks TODOs and links to external trackers so they are findable via references.

Type declarations¶

EqualEntry.d.ts contains ambient type declarations only: branded nominal types (TabName, SheetId, ErrorId, A1Expression, Url, Email, and so on), the ResultsTabEntry / ParsedResultsTab shapes returned by the results parser, and short aliases for Apps Script classes.