Adds deprecation notices on safe type functions.

RELNOTES: Adds deprecation notices on safe type functions.

PiperOrigin-RevId: 573755249
Change-Id: I893ee619d37f166bf8209eb83a52968918c2305d

closure/goog/html/safehtml.js

@@ -129,6 +129,7 @@ class SafeHtml {
    * @return {string}
    * @see SafeHtml.unwrap
    * @override
+   * @deprecated Use the native `toString` or the `String` constructor instead.
    */
   getTypedStringValue() {
     return this.privateDoNotAccessOrElseSafeHtmlWrappedValue_.toString();
@@ -157,6 +158,7 @@ class SafeHtml {
    *     run-time type check fails. In that case, `unwrap` returns an innocuous
    *     string, or, if assertions are enabled, throws
    *     `asserts.AssertionError`.
+   * @deprecated Use `safevalues.unwrapHtml` combined with `toString()` instead.
    */
   static unwrap(safeHtml) {
     return SafeHtml.unwrapTrustedHTML(safeHtml).toString();
@@ -168,6 +170,7 @@ class SafeHtml {
    * @param {!SafeHtml} safeHtml
    * @return {!TrustedHTML|string}
    * @see SafeHtml.unwrap
+   * @deprecated Use `safevalues.unwrapHtml` instead.
    */
   static unwrapTrustedHTML(safeHtml) {
     // Perform additional run-time type-checking to ensure that safeHtml is
@@ -193,6 +196,7 @@ class SafeHtml {
    *     the parameter is of type SafeHtml it is returned directly (no escaping
    *     is done).
    * @return {!SafeHtml} The escaped text, wrapped as a SafeHtml.
+   * @deprecated Use `safevalues.htmlEscape` instead.
    */
   static htmlEscape(textOrHtml) {
     if (textOrHtml instanceof SafeHtml) {
@@ -219,6 +223,7 @@ class SafeHtml {
    *     the parameter is of type SafeHtml it is returned directly (no escaping
    *     is done).
    * @return {!SafeHtml} The escaped text, wrapped as a SafeHtml.
+   * @deprecated Use `safevalues.htmlEscape` instead.
    */
   static htmlEscapePreservingNewlines(textOrHtml) {
     if (textOrHtml instanceof SafeHtml) {
@@ -238,6 +243,7 @@ class SafeHtml {
    *     the parameter is of type SafeHtml it is returned directly (no escaping
    *     is done).
    * @return {!SafeHtml} The escaped text, wrapped as a SafeHtml.
+   * @deprecated Use `safevalues.htmlEscape` instead.
    */
   static htmlEscapePreservingNewlinesAndSpaces(textOrHtml) {
     if (textOrHtml instanceof SafeHtml) {
@@ -314,8 +320,10 @@ class SafeHtml {
    * @throws {!Error} If invalid tag name, attribute name, or attribute value is
    *     provided.
    * @throws {!asserts.AssertionError} If content for void tag is provided.
-   * @deprecated Use a recommended templating system like Lit instead.
-   *     More information: go/goog.html-readme // LINE-INTERNAL
+   * @deprecated Use a recommended templating system like Lit instead. If this
+   *     is not possible, use `safevalues.createHtml`.
+   * More information:
+   *     go/goog.html-readme // LINE-INTERNAL
    */
   static create(tagName, attributes = undefined, content = undefined) {
     SafeHtml.verifyTagName(String(tagName));
@@ -478,6 +486,7 @@ class SafeHtml {
    * @throws {!Error} If invalid attribute name or value is provided. If
    *     attributes  contains the
    * src attribute.
+   * @deprecated Use `safevalues.scriptUrlToHtml` instead.
    */
   static createScriptSrc(src, attributes = undefined) {
     // TODO(mlourenco): The charset attribute should probably be blocked. If
@@ -511,7 +520,7 @@ class SafeHtml {
    * @throws {!Error} If invalid attribute name or attribute value is provided.
    *     If attributes  contains the
    *     language, src or text attribute.
-   * @deprecated Use safevalues.scriptToHtml instead.
+   * @deprecated Use `safevalues.scriptToHtml` instead.
    */
   static createScript(script, attributes = undefined) {
     for (let attr in attributes) {
@@ -627,6 +636,7 @@ class SafeHtml {
    *     contains an array then each member of this array is also joined with
    * the separator.
    * @return {!SafeHtml}
+   * @deprecated Use `safevalues.joinHtmls` instead.
    */
   static join(separator, parts) {
     const separatorHtml = SafeHtml.htmlEscape(separator);
@@ -656,6 +666,7 @@ class SafeHtml {
    * @param {...(!SafeHtml.TextOrHtml_|
    *     !Array<!SafeHtml.TextOrHtml_>)} var_args Values to concatenate.
    * @return {!SafeHtml}
+   * @deprecated Use `safevalues.concatHtmls` instead.
    */
   static concat(var_args) {
     return SafeHtml.join(SafeHtml.EMPTY, Array.prototype.slice.call(arguments));
@@ -821,6 +832,7 @@ SafeHtml.SUPPORT_STYLE_ATTRIBUTE =
  * or might already be SafeHtml (as SafeHtml is a TypedString).
  * @private
  * @typedef {string|number|boolean|!TypedString}
+ * @deprecated Use an explicit type instead.
  */
 SafeHtml.TextOrHtml_;
 
@@ -872,6 +884,7 @@ const NOT_ALLOWED_TAG_NAMES = googObject.createSet(
 /**
  * @typedef {string|number|!TypedString|
  *     !SafeStyle.PropertyMap|undefined|null}
+ * @deprecated Use an explicit type instead.
  */
 SafeHtml.AttributeValue;
 
@@ -979,6 +992,7 @@ SafeHtml.DOCTYPE_HTML = /** @type {!SafeHtml} */ ({
 /**
  * A SafeHtml instance corresponding to the empty string.
  * @const {!SafeHtml}
+ * @deprecated Use `safevalues.EMPTY_HTML` instead.
  */
 SafeHtml.EMPTY = new SafeHtml(
     (goog.global.trustedTypes && goog.global.trustedTypes.emptyHTML) || '',
@@ -987,6 +1001,7 @@ SafeHtml.EMPTY = new SafeHtml(
 /**
  * A SafeHtml instance corresponding to the <br> tag.
  * @const {!SafeHtml}
+ * @deprecated Use `safevalues.createHtml('br')` instead.
  */
 SafeHtml.BR = /** @type {!SafeHtml} */ ({
   // NOTE: this compiles to nothing, but hides the possible side effect of

closure/goog/html/safescript.js

@@ -111,6 +111,8 @@ class SafeScript {
    * @param {!Const} script A compile-time-constant string from which to create
    *     a SafeScript.
    * @return {!SafeScript} A SafeScript object initialized to `script`.
+   * @deprecated Use the `safevalues.safeScript` template literal builder
+   *     instead.
    */
   static fromConstant(script) {
     const scriptString = Const.unwrap(script);
@@ -126,6 +128,7 @@ class SafeScript {
    * to JSON.stringify.
    * @param {*} val
    * @return {!SafeScript}
+   * @deprecated Use `safevalues.valueAsScript` instead.
    */
   static fromJson(val) {
     return SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse(
@@ -152,6 +155,7 @@ class SafeScript {
    *
    * @see SafeScript#unwrap
    * @override
+   * @deprecated Use `toString()` or the String constructor instead.
    */
   getTypedStringValue() {
     return this.privateDoNotAccessOrElseSafeScriptWrappedValue_.toString();
@@ -166,6 +170,8 @@ class SafeScript {
    *     the run-time type check fails. In that case, `unwrap` returns an
    *     innocuous string, or, if assertions are enabled, throws
    *     `asserts.AssertionError`.
+   * @deprecated Use `safevalues.unwrapScript` combined with `.toString()`
+   *     instead.
    */
   static unwrap(safeScript) {
     return SafeScript.unwrapTrustedScript(safeScript).toString();
@@ -176,6 +182,7 @@ class SafeScript {
    * @param {!SafeScript} safeScript
    * @return {!TrustedScript|string}
    * @see SafeScript.unwrap
+   * @deprecated Use `safevalues.unwrapScript` instead.
    */
   static unwrapTrustedScript(safeScript) {
     // Perform additional Run-time type-checking to ensure that
@@ -230,6 +237,7 @@ class SafeScript {
 /**
  * A SafeScript instance corresponding to the empty string.
  * @const {!SafeScript}
+ * @deprecated Use `safevalues.EMPTY_SCRIPT` instead.
  */
 SafeScript.EMPTY = /** @type {!SafeScript} */ ({
   // NOTE: this compiles to nothing, but hides the possible side effect of

closure/goog/html/safestyle.js

@@ -196,6 +196,7 @@ class SafeStyle {
    * @return {string}
    * @see SafeStyle#unwrap
    * @override
+   * @deprecated Use `toString()` or the String constructor instead.
    */
   getTypedStringValue() {
     return this.privateDoNotAccessOrElseSafeStyleWrappedValue_;

closure/goog/html/safestylesheet.js

@@ -117,6 +117,8 @@ class SafeStyleSheet {
    *     definition associated with the selector.
    * @return {!SafeStyleSheet}
    * @throws {!Error} If invalid selector is provided.
+   * @deprecated Use `safevalues.safeStyleSheet` or `safevalues.safeStyleRule`
+   *     instead.
    */
   static createRule(selector, style) {
     if (contains(selector, '<')) {
@@ -176,6 +178,7 @@ class SafeStyleSheet {
    * @param {...(!SafeStyleSheet|!Array<!SafeStyleSheet>)}
    *     var_args Values to concatenate.
    * @return {!SafeStyleSheet}
+   * @deprecated Use `safevalues.concatStyleSheets` instead.
    */
   static concat(var_args) {
     let result = '';
@@ -207,6 +210,7 @@ class SafeStyleSheet {
    *     which to create a SafeStyleSheet.
    * @return {!SafeStyleSheet} A SafeStyleSheet object initialized to
    *     `styleSheet`.
+   * @deprecated Use `safevalues.safeStyleSheet` instead.
    */
   static fromConstant(styleSheet) {
     const styleSheetString = Const.unwrap(styleSheet);
@@ -242,6 +246,7 @@ class SafeStyleSheet {
    *
    * @see SafeStyleSheet#unwrap
    * @override
+   * @deprecated Use `toString()` or the String constructor instead.
    */
   getTypedStringValue() {
     return this.privateDoNotAccessOrElseSafeStyleSheetWrappedValue_;
@@ -256,6 +261,8 @@ class SafeStyleSheet {
    *     the run-time type check fails. In that case, `unwrap` returns an
    *     innocuous string, or, if assertions are enabled, throws
    *     `asserts.AssertionError`.
+   * @deprecated Use `safevalues.unwrapStyleSheet` combined with `toString()`
+   *     instead.
    */
   static unwrap(safeStyleSheet) {
     // Perform additional Run-time type-checking to ensure that
@@ -292,6 +299,7 @@ class SafeStyleSheet {
 /**
  * A SafeStyleSheet instance corresponding to the empty string.
  * @const {!SafeStyleSheet}
+ * @deprecated Use `safevalues.safeStyleSheet` instead.
  */
 SafeStyleSheet.EMPTY =
     SafeStyleSheet.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse('');

closure/goog/html/safeurl.js

@@ -142,6 +142,7 @@ goog.html.SafeUrl.prototype.implementsGoogStringTypedString = true;
  *
  * @see goog.html.SafeUrl#unwrap
  * @override
+ * @deprecated Use `toString()` or the String constructor instead.
  */
 goog.html.SafeUrl.prototype.getTypedStringValue = function() {
   'use strict';
@@ -273,6 +274,7 @@ goog.html.SafeUrl.fromBlob = function(blob) {
  * Revokes an object URL created for a safe URL created {@link fromBlob()}.
  * @param {!goog.html.SafeUrl} safeUrl SafeUrl wrapping a blob object.
  * @return {void}
+ * @deprecated Use `URL.revokeObjectURL` instead.
  */
 goog.html.SafeUrl.revokeObjectUrl = function(safeUrl) {
   'use strict';

closure/goog/html/trustedresourceurl.js

@@ -114,6 +114,7 @@ goog.html.TrustedResourceUrl.prototype.implementsGoogStringTypedString = true;
  *
  * @see goog.html.TrustedResourceUrl#unwrap
  * @override
+ * @deprecated Use `toString()` or the String constructor instead.
  */
 goog.html.TrustedResourceUrl.prototype.getTypedStringValue = function() {
   'use strict';
@@ -133,6 +134,8 @@ goog.html.TrustedResourceUrl.prototype.getTypedStringValue = function() {
  *     to URL. See goog.html.TrustedResourceUrl.stringifyParams_ for exact
  *     format definition.
  * @return {!goog.html.TrustedResourceUrl} New TrustedResourceUrl with params.
+ * @deprecated Use `safevalues.appendParams` and `safevalues.replaceFragment`
+ *     instead.
  */
 goog.html.TrustedResourceUrl.prototype.cloneWithParams = function(
     searchParams, opt_hashParams) {
@@ -162,6 +165,7 @@ goog.html.TrustedResourceUrl.prototype.cloneWithParams = function(
  *     the run-time type check fails. In that case, `unwrap` returns an
  *     innocuous string, or, if assertions are enabled, throws
  *     `goog.asserts.AssertionError`.
+ * @deprecated Use `safevalues.unwrapResourceUrl` and `toString()` instead
  */
 goog.html.TrustedResourceUrl.unwrap = function(trustedResourceUrl) {
   'use strict';
@@ -175,6 +179,7 @@ goog.html.TrustedResourceUrl.unwrap = function(trustedResourceUrl) {
  * @param {!goog.html.TrustedResourceUrl} trustedResourceUrl
  * @return {!TrustedScriptURL|string}
  * @see goog.html.TrustedResourceUrl.unwrap
+ * @deprecated Use `safevalues.unwrapResourceUrl` instead.
  */
 goog.html.TrustedResourceUrl.unwrapTrustedScriptURL = function(
     trustedResourceUrl) {
@@ -236,6 +241,8 @@ goog.html.TrustedResourceUrl.unwrapTrustedScriptURL = function(
  * @return {!goog.html.TrustedResourceUrl}
  * @throws {!Error} On an invalid format string or if a label used in the
  *     the format string is not present in args.
+ * @deprecated Use the `safevalues.trustedResourceUrl` template string literal
+ *     builder instead.
  */
 goog.html.TrustedResourceUrl.format = function(format, args) {
   'use strict';
@@ -342,6 +349,8 @@ goog.html.TrustedResourceUrl.URL_PARAM_PARSER_ =
  * @return {!goog.html.TrustedResourceUrl}
  * @throws {!Error} On an invalid format string or if a label used in the
  *     the format string is not present in args.
+ * @deprecated Use `safevalues.trustedResourceUrl` and `safevalues.appendParams`
+ *     instead.
  */
 goog.html.TrustedResourceUrl.formatWithParams = function(
     format, args, searchParams, opt_hashParams) {
@@ -361,6 +370,7 @@ goog.html.TrustedResourceUrl.formatWithParams = function(
  *     create a TrustedResourceUrl.
  * @return {!goog.html.TrustedResourceUrl} A TrustedResourceUrl object
  *     initialized to `url`.
+ * @deprecated Use `safevalues.trustedResourceUrl` instead.
  */
 goog.html.TrustedResourceUrl.fromConstant = function(url) {
   'use strict';
@@ -380,6 +390,7 @@ goog.html.TrustedResourceUrl.fromConstant = function(url) {
  *     which to create a TrustedResourceUrl.
  * @return {!goog.html.TrustedResourceUrl} A TrustedResourceUrl object
  *     initialized to concatenation of `parts`.
+ * @deprecated Use `safevalues.trustedResourceUrl` instead.
  */
 goog.html.TrustedResourceUrl.fromConstants = function(parts) {
   'use strict';
@@ -406,6 +417,7 @@ goog.html.TrustedResourceUrl.fromConstants = function(parts) {
  *     TrustedResourceUrl.
  * @return {!goog.html.TrustedResourceUrl} A TrustedResourceUrl object
  *     initialized to a new blob URL.
+ * @deprecated Use `safevalues.objectUrlFromScript` instead.
  */
 goog.html.TrustedResourceUrl.fromSafeScript = function(safeScript) {
   'use strict';