AI-generated Key Takeaways

outlined_flag

• Libraries are script projects that allow functions to be reused in other scripts, although this can slightly decrease execution speed.

• To use a library, you need at least view-level access and the library's script ID to add it to your project.

• Libraries are used like default services, with the identifier you set acting as the reference to the library's methods.

• When creating a library, consider best practices like choosing a meaningful name, using underscores for private methods, and including JSDoc documentation.

• Libraries have both shared resources, accessible by both the library and including script, and not-shared resources, which require explicit functions to be accessed by the including script.

A library is a script project whose functions can be reused in other scripts.

Gain access to a library

To include a library in your project you must have at least view-level access to it. If you aren't the author of the library that you want to include, contact the author and request access.

You need the script ID of the library you want to include. When you have access to the library, you can find the script ID on theProject Settingssettings page.

Add a library to your script project

1. At the left of the Apps Script editor, next to "Libraries," click Add alibraryadd.
2. In the "Script ID" field, paste in the script ID of the library.
3. ClickLook up.If you encounter an error, make sure that youhave at least view-level access to the project that you're trying toinclude.
4. Click theVersion dropdown and select the version of the libraryto use.
5. Check to see if the default "Identifier" name is the one that you want touse with this library. This is the name that your script uses torefer to the library. For example, if you set it toTest then you cancall a method of that library as follows:Test.libraryMethod().If you use an identifier name that matches the name ofan already existing service, such asMailApp, or a previouslyadded library, then the library you have added most recently overrides theexisting service or library.
6. ClickAdd.

Use a library

Use your included library as you would use a default service. Forexample, ifTest is the identifier for your library, typeTest immediately followed by a period to see the list of methods in the library.

The reference documentation for an included library can be opened by followingthese steps:

At the left of the script editor, next to the library name, click Moremore_vert> Open in a new tab.

Remove a library

At the left of the script editor, next to the library name, click Moremore_vert> Remove > Remove library.

1. Create a versioned deploymentof your script.
2. Share at least view-level access with all potential users of the library.
3. Give those users the script ID, which can be found on theProjectsettingssettings page.

Best practices

Here are some guidelines to follow when writing a library:

1. Choose a meaningful name for your project since it's used as thedefault identifier when your library is included by others.
2. If you want one or more methods of your script to not be visible (norusable) to your library users, you can end the name of the method with anunderscore. For example,myPrivateMethod_().
3. Only enumerable global properties are visible to library users. This includes functiondeclarations, variables created outside a function withvar, and properties explicitly seton the global object. For example,Object.defineProperty() withenumerable set tofalsecreates a symbol you can use in your library, but this symbol isn't accessible by your users.

4. If you want your library users to make use of the script editor autocomplete andthe automatically generated documentation, you must have JSDoc-styledocumentation for all your functions. Here's an example:

   /***Raisesanumbertothegivenpower,andreturnstheresult.**@param{number}basethenumberwe'reraisingtoapower*@param{number}exptheexponentwe'reraisingthebaseto*@return{number}theresultoftheexponentialcalculation*/functionpower(base, exp){...}

Resource scoping

There are two types of resources when you are working with libraries: sharedand not-shared. A shared resource means that both the library and the includingscript have a built-in access to the same instance of the resource. Thefollowing diagram illustrates a shared resource using the example ofUser Properties:

A not-shared resource means that both library and the including script havebuilt-in access only to their instance of the resource. However, a library canprovide access to its not-shared resources by having explicit functions thatoperate on them. Here is an example of a function that you would include inyour library to expose its Script Properties:

functiongetLibraryProperty(key){constscriptProperties=PropertiesService.getScriptProperties();returnscriptProperties.getProperty(key);}

The following diagram illustrates a not-shared resource using the example ofScript Properties:

This table lists the shared and not-shared resources for your reference:

Resource	Shared*	Not-Shared**	Notes
Lock			The same instance is visible to all including scripts when created in the library.
Script Properties			The same instance is visible to all including scripts when created in the library.
Cache			The same instance is visible to all including scripts when created in the library.
Triggers			Simple triggers created in library are not triggered by the including script.
ScriptApp
UiApp
User Properties
Logger and execution transcript
Sites, Sheets and other containers			A call togetActive() returns the container of the including script.
MailApp and GmailApp
* This means that the library does not have its own instance of the feature/resource and instead is using the one created by the script that invoked it. ** This means that library has its own instance of the resource/feature and that all scripts that use the library share and have access to that same instance.

Test a library

To test your library, use the head deployment. Anyone who has editor-levelaccess to the script can use the head deployment.