script_builders.d.ts 2.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455
  1. /**
  2. * @license
  3. * SPDX-License-Identifier: Apache-2.0
  4. */
  5. import '../environment/dev';
  6. import { SafeScript } from '../internals/script_impl';
  7. declare type Primitive = number | string | boolean | null;
  8. declare type Serializable = Primitive | readonly Serializable[] | {
  9. readonly [key: string]: Serializable;
  10. };
  11. /**
  12. * Creates a SafeScript object from a template literal (without any embedded
  13. * expressions).
  14. *
  15. * This function is a template literal tag function. It should be called with
  16. * a template literal that does not contain any expressions. For example,
  17. * safeScript`foo`;
  18. *
  19. * @param templateObj This contains the literal part of the template literal.
  20. */
  21. export declare function safeScript(templateObj: TemplateStringsArray): SafeScript;
  22. /** Creates a `SafeScript` value by concatenating multiple `SafeScript`s. */
  23. export declare function concatScripts(scripts: readonly SafeScript[]): SafeScript;
  24. /**
  25. * Converts a serializable value into JSON that is safe to interpolate into a
  26. * script context. In particular it escapes < characters so that a value of
  27. * "</script>" doesn't break out of the context.
  28. * @param value The value to serialize.
  29. */
  30. export declare function scriptFromJson(value: Serializable): SafeScript;
  31. /**
  32. * Creates a `SafeScript` object from a template literal (without any embedded
  33. * expressions) along with additional arguments that the script should have
  34. * access to. These arguments will be JSON-encoded and passed to the script as
  35. * a function call.
  36. * @example
  37. * ```ts
  38. * safeScriptWithArgs`function (name, props) {
  39. * console.log(name + ' is ' + props.age);
  40. * }`('Bob', { 'age': 42 })
  41. * ```
  42. * would return a `SafeScript` that represents the following code:
  43. * ```js
  44. * (function (name, props) {
  45. * console.log(name + ' is ' + props.age);
  46. * })("Bob",{"age":42})
  47. * ```
  48. * @note Be careful when passing objects as arguments, as unquoted property
  49. * names may be changed during compilation.
  50. * @param templateObj This contains the literal part of the template literal.
  51. * @param emptyArgs Expressions that evaluate to the empty string to enable
  52. * inline comments.
  53. */
  54. export declare function safeScriptWithArgs(templateObj: TemplateStringsArray, ...emptyArgs: ReadonlyArray<''>): (...argValues: Serializable[]) => SafeScript;
  55. export {};