gas-types-detailed/google-apps-script.lock.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 Lock {
    /**
     * A representation of a mutual-exclusion lock.
     *
     * This class lets scripts make sure that only one instance of the script executes a given
     * section of code at a time. This is particularly useful for callbacks and triggers, where a user
     * action might cause changes to a shared resource and you want to ensure that there aren't
     * collisions.
     *
     * The following example shows how to use a lock in a form submit handler.
     *
     *     // Generates a unique ticket number for every form submission.
     *     function onFormSubmit(e) {
     *       const targetCell = e.range.offset(0, e.range.getNumColumns(), 1, 1);
     *
     *       // Gets a script lock before modifying a shared resource.
     *       const lock = LockService.getScriptLock();
     *       // Waits for up to 30 seconds for other processes to finish.
     *       lock.waitLock(30000);
     *
     *       const scriptProperties = PropertiesService.getScriptProperties();
     *
     *       const ticketNumber =
     *           Number(scriptProperties.getProperty('lastTicketNumber')) + 1;
     *       scriptProperties.setProperty('lastTicketNumber', ticketNumber);
     *
     *       // Releases the lock so that other processes can continue.
     *       lock.releaseLock();
     *
     *       targetCell.setValue(ticketNumber);
     *     }
     *
     * lastTicketNumber
     * ScriptProperties
     */
    interface Lock {

      /**
       * Returns true if the lock was acquired. This method will return false if tryLock(timeoutInMillis) or waitLock(timeoutInMillis) were never called, timed out before the lock could be retrieved, or if releaseLock() was called.
       *
       *     const lock = LockService.getScriptLock();
       *     lock.tryLock(10000);
       *     if (!lock.hasLock()) {
       *       Logger.log('Could not obtain lock after 10 seconds.');
       *     }
       *
       * Return:
       * - Boolean — true if the lock was acquired, false otherwise
       *
       * https://developers.google.com/apps-script/reference/lock/lock#hasLock()
       */
      hasLock(): boolean;

      /**
       * Releases the lock, allowing other processes waiting on the lock to continue. The lock is automatically released when the script terminates, but for efficiency it is best to release it as soon as you no longer need exclusive access to a section of code. This method has no effect if the lock has not been acquired.
       * Note that if you are working with a spreadsheet, you should call SpreadsheetApp.flush() prior to releasing the lock, to commit all pending changes to the spreadsheet while you still have exclusive access to it.
       *
       *     const lock = LockService.getScriptLock();
       *     lock.waitLock(10000);
       *     // Do some work on a shared resource.
       *     lock.releaseLock();
       *
       * https://developers.google.com/apps-script/reference/lock/lock#releaseLock()
       */
      releaseLock(): void;

      /**
       * Attempts to acquire the lock, timing out after the provided number of milliseconds. This method has no effect if the lock has already been acquired.
       *
       *     const lock = LockService.getScriptLock();
       *     const success = lock.tryLock(10000);
       *     if (!success) {
       *       Logger.log('Could not obtain lock after 10 seconds.');
       *     }
       *
       * Return:
       * - Boolean — true if the lock was acquired, false otherwise
       *
       * https://developers.google.com/apps-script/reference/lock/lock#tryLock(Integer)
       * @param timeoutInMillis how long to wait to acquire the lock, in milliseconds
       */
      tryLock(timeoutInMillis: Integer): boolean;

      /**
       * Attempts to acquire the lock, timing out with an exception after the provided number of milliseconds. This method is the same as tryLock(timeoutInMillis) except that it throws an exception when the lock could not be acquired instead of returning false.
       *
       *     const lock = LockService.getScriptLock();
       *     try {
       *       lock.waitLock(10000);
       *     } catch (e) {
       *       Logger.log('Could not obtain lock after 10 seconds.');
       *     }
       *
       * Throws:
       * - Error — if the method timed out before the lock was acquired
       *
       * https://developers.google.com/apps-script/reference/lock/lock#waitLock(Integer)
       * @param timeoutInMillis how long to wait to acquire the lock, in milliseconds
       */
      waitLock(timeoutInMillis: Integer): void;
    }
    /**
     * Prevents concurrent access to sections of code. This can be useful when you have multiple users
     * or processes modifying a shared resource and want to prevent collisions.
     */
    interface LockService {

      /**
       * Gets a lock that prevents any user of the current document from concurrently running a section of code. A code section guarded by a document lock can be executed simultaneously by script instances running in the context of different documents, but by no more than one execution for any given document. Note that the lock is not actually acquired until Lock.tryLock(timeoutInMillis) or Lock.waitLock(timeoutInMillis) is called. If this method is called outside of the context of a containing document (such as from a standalone script or webapp), null is returned.
       *
       * Return:
       * - Lock — a lock scoped to the script and current document, or null if called from a standalone script or webapp
       *
       * https://developers.google.com/apps-script/reference/lock/lock-service#getDocumentLock()
       */
      getDocumentLock(): Lock;

      /**
       * Gets a lock that prevents any user from concurrently running a section of code. A code section guarded by a script lock cannot be executed simultaneously regardless of the identity of the user. Note that the lock is not actually acquired until Lock.tryLock(timeoutInMillis) or Lock.waitLock(timeoutInMillis) is called.
       *
       * Return:
       * - Lock — a lock scoped to the script
       *
       * https://developers.google.com/apps-script/reference/lock/lock-service#getScriptLock()
       */
      getScriptLock(): Lock;

      /**
       * Gets a lock that prevents the current user from concurrently running a section of code. A code section guarded by a user lock can be executed simultaneously by different users, but by no more than one execution for any given user. The lock is "private" to the user. Note that the lock is not actually acquired until Lock.tryLock(timeoutInMillis) or Lock.waitLock(timeoutInMillis) is called.
       *
       * Return:
       * - Lock — a lock scoped to the script and current user
       *
       * https://developers.google.com/apps-script/reference/lock/lock-service#getUserLock()
       */
      getUserLock(): Lock;
    }
  }
}

declare var LockService: GoogleAppsScript.Lock.LockService;