From 16456550feda6ad14dce2577920e1733b9230375 Mon Sep 17 00:00:00 2001 From: Closure Team Date: Mon, 16 Oct 2023 02:59:33 -0700 Subject: [PATCH] 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 | 21 ++++++++++++++++++--- closure/goog/html/safescript.js | 8 ++++++++ closure/goog/html/safestyle.js | 1 + closure/goog/html/safestylesheet.js | 8 ++++++++ closure/goog/html/safeurl.js | 2 ++ closure/goog/html/trustedresourceurl.js | 12 ++++++++++++ 6 files changed, 49 insertions(+), 3 deletions(-) diff --git a/closure/goog/html/safehtml.js b/closure/goog/html/safehtml.js index 89eb69d6de..2e085107e5 100644 --- a/closure/goog/html/safehtml.js +++ b/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)} 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
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 diff --git a/closure/goog/html/safescript.js b/closure/goog/html/safescript.js index 714dfb30f7..999c839fa8 100644 --- a/closure/goog/html/safescript.js +++ b/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 diff --git a/closure/goog/html/safestyle.js b/closure/goog/html/safestyle.js index 424c634593..e4c1d891d4 100644 --- a/closure/goog/html/safestyle.js +++ b/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_; diff --git a/closure/goog/html/safestylesheet.js b/closure/goog/html/safestylesheet.js index 478cbf0ade..6a654692d1 100644 --- a/closure/goog/html/safestylesheet.js +++ b/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)} * 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(''); diff --git a/closure/goog/html/safeurl.js b/closure/goog/html/safeurl.js index ec2f359354..f5968cc98e 100644 --- a/closure/goog/html/safeurl.js +++ b/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'; diff --git a/closure/goog/html/trustedresourceurl.js b/closure/goog/html/trustedresourceurl.js index 67f974f04d..266cf90683 100644 --- a/closure/goog/html/trustedresourceurl.js +++ b/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';