Skip to main content
The CacheBuilder class provides a fluent, chainable API for working with Google Apps Script’s CacheService. It supports script, user, and document caches with simple get/put/remove operations.

​
Constructor

const cache = new CacheBuilder(appsql)
​
appsql
APPSQL
Optional APPSQL instance for context

​
Cache Type Selection

Choose which type of cache to use. Default is script().

​
script()

Use script-level cache (shared across all users). 
cache.script()

​
user()

Use user-specific cache (isolated per user). 
cache.user()

​
document()

Use document-specific cache (shared by all users of a document). 
cache.document()

​
Cache Operations

​
Setting Values

​
key()

Specify a single cache key. 
cache.key(k)
​
k
string
required
The cache key

​
value()

Specify the value to store. 
cache.value(v)
​
v
any
required
Value to cache (will be converted to string)

​
ttl()

Set time-to-live in seconds. 
cache.ttl(seconds)
​
seconds
number
required
Number of seconds before the cache expires

​
put()

Store the value in cache. 
cache.put()
Example: 
const cache = new CacheBuilder();

// Cache a value for 5 minutes (300 seconds)
cache
  .script()
  .key("last_sync")
  .value(new Date().toISOString())
  .ttl(300)
  .put();

​
Batch Operations

​
map()

Specify multiple key-value pairs to store at once. 
cache.map(m)
​
m
object
required
Object with key-value pairs to cache
Example: 
const cache = new CacheBuilder();

// Store multiple values
cache
  .script()
  .map({
    "user:1": JSON.stringify({ id: 1, name: "John" }),
    "user:2": JSON.stringify({ id: 2, name: "Jane" }),
  })
  .ttl(600)
  .put();

​
keys()

Specify multiple keys to retrieve. 
cache.keys(arr)
​
arr
array
required
Array of cache keys to retrieve
Example: 
const users = cache
  .script()
  .keys(["user:1", "user:2"])
  .get();

// Returns: { "user:1": "...", "user:2": "..." }

​
Retrieving Values

​
get()

Retrieve value(s) from cache. 
cache.get()
Returns a single value if using key(), or an object of key-value pairs if using keys().
Example: 
// Get single value
const lastSync = cache
  .script()
  .key("last_sync")
  .get();

// Get multiple values
const users = cache
  .script()
  .keys(["user:1", "user:2"])
  .get();

​
Removing Values

​
remove()

Remove key(s) from cache. 
cache.remove()
Example: 
// Remove single key
cache
  .script()
  .key("last_sync")
  .remove();

// Remove multiple keys
cache
  .script()
  .keys(["user:1", "user:2"])
  .remove();

​
clearAll()

Remove multiple keys at once. 
cache.clearAll(keys)
​
keys
array
required
Array of cache keys to remove
Example: 
const cache = new CacheBuilder();
cache.script().clearAll(["key1", "key2", "key3"]);

​
Integration with Models

Cache frequently accessed queries for better performance: 
class Post extends Model {
  static _table = "Posts";

  static cachedLatest(limit = 10) {
    const cache = new CacheBuilder();
    const key = `posts:latest:${limit}`;

    // Try to get from cache
    const cached = cache.script().key(key).get();
    if (cached) {
      return new Collection(
        JSON.parse(cached).map(p => new Post(p))
      );
    }

    // Fetch from database
    const posts = this.query()
      .orderBy("created_at", "desc")
      .limit(limit)
      .get();

    // Store in cache for 60 seconds
    cache
      .script()
      .key(key)
      .value(JSON.stringify(posts.toArray()))
      .ttl(60)
      .put();

    return posts;
  }
}

Post.use(db);

// Usage
const latestPosts = Post.cachedLatest(10);

​
Complete Examples

​
User Session Cache

function cacheUserSession(userId, sessionData) {
  const cache = new CacheBuilder();
  
  cache
    .user() // User-specific cache
    .key(`session:${userId}`)
    .value(JSON.stringify(sessionData))
    .ttl(1800) // 30 minutes
    .put();
}

function getUserSession(userId) {
  const cache = new CacheBuilder();
  
  const cached = cache
    .user()
    .key(`session:${userId}`)
    .get();
  
  return cached ? JSON.parse(cached) : null;
}

​
Configuration Cache

function cacheAppConfig() {
  const cache = new CacheBuilder();
  
  // Check if config is cached
  const cached = cache.script().key("app:config").get();
  if (cached) {
    return JSON.parse(cached);
  }
  
  // Load config from sheet
  const config = loadConfigFromSheet();
  
  // Cache for 1 hour
  cache
    .script()
    .key("app:config")
    .value(JSON.stringify(config))
    .ttl(3600)
    .put();
  
  return config;
}

​
Temporary Feature Flags

function setFeatureFlag(flagName, enabled, durationSeconds = 3600) {
  const cache = new CacheBuilder();
  
  cache
    .script()
    .key(`feature:${flagName}`)
    .value(enabled ? "1" : "0")
    .ttl(durationSeconds)
    .put();
}

function isFeatureEnabled(flagName) {
  const cache = new CacheBuilder();
  const value = cache.script().key(`feature:${flagName}`).get();
  return value === "1";
}

​
Best Practices

DO: Serialize complex objects to JSON strings
cache
  .key("user:1")
  .value(JSON.stringify(user.toJSON()))
  .put();
DO: Use consistent key naming conventions
// Good: resource:id format
const key = `user:${userId}`;
const key = `post:${postId}:comments`;
DO: Set reasonable TTL values
// Short-lived data
cache.ttl(60);     // 1 minute

// Medium-lived data
cache.ttl(300);    // 5 minutes

// Long-lived data
cache.ttl(3600);   // 1 hour
DON’T: Call operations without required parameters
// ❌ Throws error: key required for get()
cache.script().get();

// ✅ Correct
cache.script().key("myKey").get();
DON’T: Store objects without serialization
// ❌ Objects are converted to string with toString()
cache.key("u").value({ id: 1 });

// ✅ Serialize first
cache.key("u").value(JSON.stringify({ id: 1 }));

​
Cache Types Comparison

TypeScopeUse Case
ScriptShared across all usersApp configuration, shared data
UserPer-user isolationUser sessions, preferences
DocumentPer-documentDocument-specific settings

​
Method Summary

CategoryMethods
Typescript(), user(), document()
Keyskey(), keys(), map()
Valuesvalue(), ttl()
Operationsget(), put(), remove(), clearAll()

Build docs developers (and LLMs) love

Get started for freeTalk to us