Class: BookArtisan¶

Advanced Google Spreadsheet (Book) management with caching and logging.

BookArtisan provides efficient spreadsheet operations with built-in caching via JunkPocket and comprehensive logging via AfterGlow. It helps avoid repeated calls to SpreadsheetApp.openById() by maintaining an internal cache that returns cached instances on subsequent requests.

Remarks¶

All spreadsheet objects are cached by ID for performance
Supports both spreadsheet IDs and Google Spreadsheet URLs
Logs all operations for debugging and auditing
Thread-safe for use in Google Apps Script environment

Examples¶

Basic usage:

TypeScript

const artisan = new BookArtisan({ name: "DataProcessor" });
const book = artisan.open("SPREADSHEET_ID");
if (book) {
  console.log("Spreadsheet:", book.getName());
}

Demonstrate caching efficiency:

TypeScript

const artisan = new BookArtisan();
const id = "1ABC...XYZ";

// First call - fetches from Google API
const book1 = artisan.open(id);

// Second call - returns from cache (no API call)
const book2 = artisan.open(id);
console.log("Same instance:", book1 === book2); // true

Configure logging:

TypeScript

const artisan = new BookArtisan({
  name: "SpreadsheetManager",
  logLevel: "debug"
});

const logger = artisan.getAfterGlow();
const logs = logger.toMap();

Since¶

0.13.0

Constructors¶

Constructor¶

new BookArtisan(options?): BookArtisan

Parameters¶

options?¶

BookArtisanOptions = {}

Returns¶

BookArtisan

Gaslets¶

getAfterGlow()¶

getAfterGlow(): AfterGlow

Get the internal AfterGlow logger instance for advanced usage.

Use this to access all logged operations or configure logging behavior.

Returns¶

AfterGlow

AfterGlow logger instance

Example¶

TypeScript

const artisan = new BookArtisan();
const logger = artisan.getAfterGlow();
const logs = logger.toMap();

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

getJunkPocket()¶

getJunkPocket(): JunkPocket\<Spreadsheet>

Get the internal JunkPocket cache for advanced usage.

Returns the underlying cache instance for direct cache management if needed.

Returns¶

JunkPocket\<Spreadsheet>

JunkPocket cache instance containing cached Spreadsheet objects

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

getFromCache()¶

getFromCache(id): Spreadsheet | undefined

Retrieve a cached Spreadsheet by ID without opening it.

Returns the spreadsheet from cache if it exists, or undefined if not cached yet.

Parameters¶

id¶

string

Spreadsheet ID to retrieve

Returns¶

Spreadsheet | undefined

Cached Spreadsheet object, or undefined if not found in cache

Example¶

TypeScript

const artisan = new BookArtisan();
const book = artisan.getFromCache("SPREADSHEET_ID");
if (book) {
  console.log("Found:", book.getName());
}

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

addToCache()¶

addToCache(book): void

Cache a Spreadsheet object by its ID.

The spreadsheet ID is automatically extracted using getId(). If already cached, the existing entry will be overwritten.

Parameters¶

book¶

Spreadsheet

Spreadsheet object to add to cache

Returns¶

void

Example¶

TypeScript

const artisan = new BookArtisan();
const book = SpreadsheetApp.getActiveSpreadsheet();
artisan.addToCache(book);

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

clear()¶

clear(id): void

Remove a specific spreadsheet from cache by ID.

Parameters¶

id¶

string

Spreadsheet ID to remove

Returns¶

void

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

clearAll()¶

clearAll(): void

Remove all spreadsheets from cache.

Returns¶

void

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

openById()¶

openById(id): Spreadsheet | null

Open a Spreadsheet by ID with automatic caching.

Checks cache first, then fetches from Google API if not cached. All opened spreadsheets are automatically cached for future use.

Parameters¶

id¶

string

Spreadsheet ID to open

Returns¶

Spreadsheet | null

Spreadsheet object, or null if the operation failed

Example¶

TypeScript

const artisan = new BookArtisan();
const book = artisan.openById("1ABC...XYZ");
if (book) {
  console.log("Sheet count:", book.getSheets().length);
}

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

openByUrl()¶

openByUrl(url): Spreadsheet | null

Open a Spreadsheet by URL with automatic caching.

Extracts the spreadsheet ID from the URL and opens it. The result is automatically cached for future use.

Parameters¶

url¶

string

Google Spreadsheet URL to open

Returns¶

Spreadsheet | null

Spreadsheet object, or null if the operation failed

Example¶

TypeScript

const artisan = new BookArtisan();
const url = "https://docs.google.com/spreadsheets/d/1ABC...XYZ/edit";
const book = artisan.openByUrl(url);
if (book) {
  console.log("Opened:", book.getName());
}

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

open()¶

open(idOrUrl): Spreadsheet | null

Open a Spreadsheet by ID or URL with automatic caching.

Automatically detects whether the input is a spreadsheet ID or URL and uses the appropriate method. All opened spreadsheets are cached.

Parameters¶

idOrUrl¶

string

Spreadsheet ID or Google Spreadsheet URL

Returns¶

Spreadsheet | null

Spreadsheet object, or null if the operation failed

Example¶

TypeScript

const artisan = new BookArtisan();

// Using ID
const book1 = artisan.open("1ABC...XYZ");

// Using URL
const book2 = artisan.open("https://docs.google.com/spreadsheets/d/1ABC...XYZ/edit");

if (book1) console.log("Opened:", book1.getName());
if (book2) console.log("Opened:", book2.getName());

Deprecated¶

Will be deprecated in a future version.

Since¶

0.13.0

Other¶

defaultName¶

readonly static defaultName: "BookArtisan" = "BookArtisan"