gas-types-detailed/google-apps-script.cache.d.ts

Enhanced Google Apps Script Type Definitions with detailed documentation. Includes type definitions plus code snippets, return values, required authorization scopes, and other details not found in @types/google-apps-script.

// Type definitions for Google Apps Script 2025-11-10
// Project: https://developers.google.com/apps-script/
// Definitions by: motemen <https://github.com/motemen/>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/// <reference path="google-apps-script.types.d.ts" />

declare namespace GoogleAppsScript {
  namespace Cache {
    /**
     * A reference to a particular cache.
     *
     * This class allows you to insert, retrieve, and remove items from a cache. This can be
     * particularly useful when you want frequent access to an expensive or slow resource. For example,
     * say you have an RSS feed at example.com that takes 20 seconds to fetch, but you want to speed up
     * access on an average request.
     *
     *     function getRssFeed() {
     *       const cache = CacheService.getScriptCache();
     *       const cached = cache.get('rss-feed-contents');
     *       if (cached != null) {
     *         return cached;
     *       }
     *       const result = UrlFetchApp.fetch(
     *           'http://example.com/my-slow-rss-feed.xml');  // takes 20 seconds
     *       const contents = result.getContentText();
     *       cache.put('rss-feed-contents', contents, 1500);  // cache for 25 minutes
     *       return contents;
     *     }
     */
    interface Cache {

      /**
       * Gets the cached value for the given key, or null if none is found.
       *
       *     // Gets the value from the cache for the key 'foo'.
       *     const value = CacheService.getScriptCache().get('foo');
       *
       * Return:
       * - String — the cached value, or null if none was found
       *
       * https://developers.google.com/apps-script/reference/cache/cache#get(String)
       * @param key the key to look up in the cache
       */
      get(key: string): string;

      /**
       * Returns a JavaScript Object containing all key/value pairs found in the cache for an array of keys.
       *
       *     // Gets a set of values from the cache
       *     const values = CacheService.getDocumentCache().getAll(['foo', 'x', 'missing']);
       *     // If there were values in the cache for 'foo' and 'x' but not 'missing', then
       *     // 'values' would be: {'foo': 'somevalue', 'x': 'othervalue'}
       *
       * Return:
       * - Object — a JavaScript Object containing the key/value pairs for all keys found in the cache
       *
       * https://developers.google.com/apps-script/reference/cache/cache#getAll(String)
       * @param keys the keys to lookup
       */
      getAll(keys: string[]): any;

      /**
       * Adds a key/value pair to the cache.
       * The maximum length of a key is 250 characters. The maximum amount of data that can be stored per key is 100KB. The value expires from the cache after 600 seconds (10 minutes).
       * The cap for cached items is 1,000. If more than 1,000 items are written, the cache stores the 900 items farthest from expiration. This limit might change.
       *
       *     const cache = CacheService.getScriptCache();
       *     // Puts the value 'bar' into the cache using the key 'foo'
       *     cache.put('foo', 'bar');
       *
       * https://developers.google.com/apps-script/reference/cache/cache#put(String,String)
       * @param key the key to store the value under
       * @param value the value to be cached
       */
      put(key: string, value: string): void;

      /**
       * Adds a key/value pair to the cache, with an expiration time (in seconds).
       * The maximum length of a key is 250 characters. The maximum amount of data that can be stored per key is 100KB. The specified expiration time is only a suggestion; cached data may be removed before this time if a lot of data is cached.
       * The cap for cached items is 1,000. If more than 1,000 items are written, the cache stores the 900 items farthest from expiration. This limit might change.
       *
       *     // Puts the value 'bar' into the cache using the key 'foo', but only for the
       *     // next 20 seconds.
       *     CacheService.getScriptCache().put('foo', 'bar', 20);
       *
       * https://developers.google.com/apps-script/reference/cache/cache#put(String,String,Integer)
       * @param key the key to store the value under
       * @param value the value to be cached
       * @param expirationInSeconds the maximum time the value remains in the cache, in seconds. The minimum is 1 second and the maximum is 21600 seconds (6 hours).
       */
      put(key: string, value: string, expirationInSeconds: Integer): void;

      /**
       * Adds a set of key/value pairs to the cache.
       * Similar to repeated calls to "put", but more efficient as it only makes one call to the memcache server to set all values. The maximum length of a key is 250 characters. The maximum amount of data that can be stored per key is 100KB. The values will expire from the cache after 600 seconds (10 minutes).
       * The cap for cached items is 1,000. If more than 1,000 items are written, the cache stores the 900 items farthest from expiration. This limit might change.
       *
       *     // Puts a set of values into the cache with the keys 'foo', 'x', and 'key'.
       *     const values = {
       *       foo: 'bar',
       *       x: 'y',
       *       key: 'value',
       *     };
       *     CacheService.getUserCache().putAll(values);
       *
       * https://developers.google.com/apps-script/reference/cache/cache#putAll(Object)
       * @param values a JavaScript Object containing string keys and values
       */
      putAll(values: any): void;

      /**
       * Adds a set of key/value pairs to the cache, with an expiration time (in seconds).
       * Similar to repeated calls to "put", but more efficient as it only makes one call to the memcache server to set all values. The maximum length of a key is 250 characters. The maximum amount of data that can be stored per key is 100KB. The specified expiration time is only a suggestion; cached data may be removed before this time if a lot of data is cached.
       * The cap for cached items is 1,000. If more than 1,000 items are written, the cache stores the 900 items farthest from expiration. This limit might change.
       *
       *     // Puts a set of values into the cache with the keys 'foo', 'x', and 'key'.
       *     const values = {
       *       foo: 'bar',
       *       x: 'y',
       *       key: 'value',
       *     };
       *     CacheService.getUserCache().putAll(values, 20);
       *
       * https://developers.google.com/apps-script/reference/cache/cache#putAll(Object,Integer)
       * @param values A JavaScript Object containing string keys and values
       * @param expirationInSeconds The maximum time the value remains in the cache, in seconds The minimum allowed expiration is 1 second, and the maximum allowed expiration is 21600 seconds (6 hours). The default expiration is 600 seconds (10 minutes).
       */
      putAll(values: any, expirationInSeconds: Integer): void;

      /**
       * Removes an entry from the cache using the given key.
       *
       *     // Removes any cache entries for 'foo'
       *     CacheService.getUserCache().remove('foo');
       *
       * https://developers.google.com/apps-script/reference/cache/cache#remove(String)
       * @param key the key to remove from the cache
       */
      remove(key: string): void;

      /**
       * Removes a set of entries from the cache.
       *
       *     // Removes entries from the cache with keys 'foo' and 'x'
       *     CacheService.getDocumentCache().removeAll(['foo', 'x']);
       *
       * https://developers.google.com/apps-script/reference/cache/cache#removeAll(String)
       * @param keys the array of keys to remove
       */
      removeAll(keys: string[]): void;
    }
    /**
     * CacheService allows you to access a cache for short term storage of data.
     *
     * This class lets you get a specific cache instance. Public caches are for things that are not
     * dependent on which user is accessing your script. Private caches are for things which are
     * user-specific, like settings or recent activity.
     *
     * The data you write to the cache is not guaranteed to persist until its expiration time. You
     * must be prepared to get back null from all reads.
     */
    interface CacheService {

      /**
       * Gets the cache instance scoped to the current document and script. Document caches are specific to the current document which contains the script. Use these to store script information that is specific to the current document. If this method is called outside of the context of a containing document (such as from a standalone script or web app), this method returns null.
       *
       *     // Gets a cache that is specific to the current document containing the script
       *     const cache = CacheService.getDocumentCache();
       *
       * Return:
       * - Cache — a document cache instance, or null if there is no containing document
       *
       * https://developers.google.com/apps-script/reference/cache/cache-service#getDocumentCache()
       */
      getDocumentCache(): Cache;

      /**
       * Gets the cache instance scoped to the script. Script caches are common to all users of the script. Use these to store information that is not specific to the current user.
       *
       *     // Gets a cache that is common to all users of the script
       *     const cache = CacheService.getScriptCache();
       *
       * Return:
       * - Cache — a script cache instance
       *
       * https://developers.google.com/apps-script/reference/cache/cache-service#getScriptCache()
       */
      getScriptCache(): Cache;

      /**
       * Gets the cache instance scoped to the current user and script. User caches are specific to the current user of the script. Use these to store script information that is specific to the current user.
       *
       *     // Gets a cache that is specific to the current user of the script
       *     const cache = CacheService.getUserCache();
       *
       * Return:
       * - Cache — a user cache instance
       *
       * https://developers.google.com/apps-script/reference/cache/cache-service#getUserCache()
       */
      getUserCache(): Cache;
    }
  }
}

declare var CacheService: GoogleAppsScript.Cache.CacheService;