@glimmer/util

  • Version 0.88.1
  • Published
  • 143 kB
  • 2 dependencies
  • MIT license

Install

npm i @glimmer/util
yarn add @glimmer/util
pnpm add @glimmer/util

Overview

Common utilities used in Glimmer

Index

Variables

variable assign

let assign: {
<T extends {}, U>(target: T, source: U): T & U;
<T_1 extends {}, U_1, V>(target: T_1, source1: U_1, source2: V): T_1 & U_1 & V;
<T_2 extends {}, U_2, V_1, W>(
target: T_2,
source1: U_2,
source2: V_1,
source3: W
): T_2 & U_2 & V_1 & W;
(target: object, ...sources: any[]): any;
};

    variable beginTestSteps

    let beginTestSteps: () => void;

      variable COMMENT_NODE

      const COMMENT_NODE: number;

        variable debugToString

        let debugToString: (value: unknown) => string;

          variable DOCUMENT_FRAGMENT_NODE

          const DOCUMENT_FRAGMENT_NODE: number;

            variable DOCUMENT_NODE

            const DOCUMENT_NODE: number;

              variable DOCUMENT_TYPE_NODE

              const DOCUMENT_TYPE_NODE: number;

                variable ELEMENT_NODE

                const ELEMENT_NODE: number;

                  variable EMPTY_ARRAY

                  const EMPTY_ARRAY: readonly unknown[];

                    variable EMPTY_NUMBER_ARRAY

                    const EMPTY_NUMBER_ARRAY: number[];

                      variable EMPTY_STRING_ARRAY

                      const EMPTY_STRING_ARRAY: string[];

                        variable endTestSteps

                        let endTestSteps: () => void;

                          variable INSERT_AFTER_BEGIN

                          const INSERT_AFTER_BEGIN: InsertPosition.afterbegin;

                            variable INSERT_AFTER_END

                            const INSERT_AFTER_END: InsertPosition.afterend;

                              variable INSERT_BEFORE_BEGIN

                              const INSERT_BEFORE_BEGIN: InsertPosition.beforebegin;

                                variable INSERT_BEFORE_END

                                const INSERT_BEFORE_END: InsertPosition.beforeend;

                                  variable LOCAL_LOGGER

                                  const LOCAL_LOGGER: Console;
                                  • This constant exists to make it easier to differentiate normal logs from errant console.logs. LOCAL_LOGGER should only be used inside a LOCAL_SHOULD_LOG check.

                                    It does not alleviate the need to check LOCAL_SHOULD_LOG, which is used for stripping.

                                  variable LOGGER

                                  const LOGGER: Console;
                                  • This constant exists to make it easier to differentiate normal logs from errant console.logs. LOGGER can be used outside of LOCAL_SHOULD_LOG checks, and is meant to be used in the rare situation where a console.* call is actually appropriate.

                                  variable logStep

                                  let logStep: (type: string, steps: unknown) => void;

                                    variable NS_HTML

                                    const NS_HTML: Namespace.HTML;

                                      variable NS_MATHML

                                      const NS_MATHML: Namespace.MathML;

                                        variable NS_SVG

                                        const NS_SVG: Namespace.SVG;
                                          const NS_XLINK: Namespace.XLink;

                                            variable NS_XML

                                            const NS_XML: Namespace.XML;

                                              variable NS_XMLNS

                                              const NS_XMLNS: Namespace.XMLNS;

                                                variable RAW_NODE

                                                const RAW_NODE: number;

                                                  variable SERIALIZATION_FIRST_NODE_STRING

                                                  const SERIALIZATION_FIRST_NODE_STRING: string;

                                                    variable TEXT_NODE

                                                    const TEXT_NODE: number;

                                                      variable verifySteps

                                                      let verifySteps: (
                                                      type: string,
                                                      steps: unknown[] | ((steps: unknown[]) => void),
                                                      message?: string
                                                      ) => void;

                                                        Functions

                                                        function arrayToOption

                                                        arrayToOption: <T>(list: T[]) => Nullable<PresentArray<T>>;

                                                          function asPresentArray

                                                          asPresentArray: <T>(list: T[], message?: string) => PresentArray<T>;

                                                            function assert

                                                            assert: (test: any, msg: string) => asserts test;

                                                              function assertNever

                                                              assertNever: (value: never, desc?: string) => never;

                                                                function assertPresent

                                                                assertPresent: {
                                                                <T extends string>(value: T): asserts value is Present<T>;
                                                                <T>(value: T, message: string): asserts value is Present<T>;
                                                                };

                                                                  function assertPresentArray

                                                                  assertPresentArray: <T>(
                                                                  list: T[],
                                                                  message?: string
                                                                  ) => asserts list is PresentArray<T>;

                                                                    function buildUntouchableThis

                                                                    buildUntouchableThis: (source: string) => null | object;

                                                                      function castToBrowser

                                                                      castToBrowser: {
                                                                      (doc: Document | SimpleDocument): Document;
                                                                      <S extends SugaryNodeCheck<keyof BrowserElementTags>>(
                                                                      node: any,
                                                                      check: S
                                                                      ): NodeForSugaryCheck<S>;
                                                                      <S extends SugaryNodeCheck<'NODE'>>(
                                                                      element: any,
                                                                      check: S
                                                                      ): NodeForSugaryCheck<S>;
                                                                      <K extends keyof HTMLElementTagNameMap>(
                                                                      element: any,
                                                                      check: K
                                                                      ): HTMLElementTagNameMap[K];
                                                                      };

                                                                        function castToSimple

                                                                        castToSimple: {
                                                                        (doc: Document | SimpleDocument): SimpleDocument;
                                                                        (elem: any): SimpleElement;
                                                                        (node: any): SimpleNode;
                                                                        };

                                                                          function checkNode

                                                                          checkNode: <S extends SugaryNodeCheck<keyof BrowserTags>>(
                                                                          node: Node | SimpleNode | null,
                                                                          check: S
                                                                          ) => NodeForSugaryCheck<S>;

                                                                            function clearElement

                                                                            clearElement: (parent: SimpleElement) => void;

                                                                              function constants

                                                                              constants: (...values: unknown[]) => unknown[];

                                                                                function decodeHandle

                                                                                decodeHandle: (num: number) => number;

                                                                                  function decodeImmediate

                                                                                  decodeImmediate: (num: number) => number;

                                                                                    function decodeNegative

                                                                                    decodeNegative: (num: number) => number;

                                                                                      function decodePositive

                                                                                      decodePositive: (num: number) => number;

                                                                                        function deprecate

                                                                                        deprecate: (desc: string) => void;

                                                                                          function dict

                                                                                          dict: <T = unknown>() => Dict<T>;

                                                                                            function emptyArray

                                                                                            emptyArray: <T>() => T[];

                                                                                              function encodeHandle

                                                                                              encodeHandle: (num: number) => number;

                                                                                                function encodeImmediate

                                                                                                encodeImmediate: (num: number) => number;

                                                                                                  function encodeNegative

                                                                                                  encodeNegative: (num: number) => number;

                                                                                                    function encodePositive

                                                                                                    encodePositive: (num: number) => number;

                                                                                                      function entries

                                                                                                      entries: <D extends object>(dict: D) => ObjectEntry<D>[];

                                                                                                        function enumerate

                                                                                                        enumerate: <T>(input: Iterable<T>) => IterableIterator<[number, T]>;

                                                                                                          function exhausted

                                                                                                          exhausted: (value: never) => never;

                                                                                                            function expect

                                                                                                            expect: <T>(val: T, message: string) => Present<T>;

                                                                                                              function extractHandle

                                                                                                              extractHandle: (handle: HandleResult) => number;

                                                                                                                function getFirst

                                                                                                                getFirst: { <T>(list: PresentArray<T>): T; <T>(list: T[]): T };

                                                                                                                  function getLast

                                                                                                                  getLast: { <T>(list: PresentArray<T>): T; <T>(list: T[]): T };

                                                                                                                    function ifPresent

                                                                                                                    ifPresent: <T, U, V>(
                                                                                                                    list: T[],
                                                                                                                    ifPresent: (input: PresentArray<T>) => U,
                                                                                                                    otherwise: () => V
                                                                                                                    ) => U | V;

                                                                                                                      function intern

                                                                                                                      intern: (str: string) => string;
                                                                                                                      • Strongly hint runtimes to intern the provided string.

                                                                                                                        When do I need to use this function?

                                                                                                                        For the most part, never. Pre-mature optimization is bad, and often the runtime does exactly what you need it to, and more often the trade-off isn't worth it.

                                                                                                                        Why?

                                                                                                                        Runtimes store strings in at least 2 different representations: Ropes and Symbols (interned strings). The Rope provides a memory efficient data-structure for strings created from concatenation or some other string manipulation like splitting.

                                                                                                                        Unfortunately checking equality of different ropes can be quite costly as runtimes must resort to clever string comparison algorithms. These algorithms typically cost in proportion to the length of the string. Luckily, this is where the Symbols (interned strings) shine. As Symbols are unique by their string content, equality checks can be done by pointer comparison.

                                                                                                                        How do I know if my string is a rope or symbol?

                                                                                                                        Typically (warning general sweeping statement, but truthy in runtimes at present) static strings created as part of the JS source are interned. Strings often used for comparisons can be interned at runtime if some criteria are met. One of these criteria can be the size of the entire rope. For example, in chrome 38 a rope longer then 12 characters will not intern, nor will segments of that rope.

                                                                                                                        Some numbers: http://jsperf.com/eval-vs-keys/8

                                                                                                                        Known Trick™

                                                                                                                        {String} interned version of the provided string

                                                                                                                      function isDict

                                                                                                                      isDict: <T>(u: T) => u is any;

                                                                                                                        function isElement

                                                                                                                        isElement: (node: Maybe<any>) => node is Element;

                                                                                                                          function isEmptyArray

                                                                                                                          isEmptyArray: (input: unknown[] | readonly unknown[]) => boolean;
                                                                                                                          • This function returns true if the input array is the special empty array sentinel, which is sometimes used for optimizations.

                                                                                                                          function isErrHandle

                                                                                                                          isErrHandle: (handle: HandleResult) => handle is ErrHandle;

                                                                                                                            function isHandle

                                                                                                                            isHandle: (value: number) => boolean;

                                                                                                                              function isNonPrimitiveHandle

                                                                                                                              isNonPrimitiveHandle: (value: number) => boolean;

                                                                                                                                function isObject

                                                                                                                                isObject: <T>(u: T) => u is object & T;

                                                                                                                                  function isOkHandle

                                                                                                                                  isOkHandle: (handle: HandleResult) => handle is OkHandle;

                                                                                                                                    function isPresent

                                                                                                                                    isPresent: <T>(value: T) => value is Present<T>;

                                                                                                                                      function isPresentArray

                                                                                                                                      isPresentArray: <T>(list: readonly T[]) => list is PresentArray<T>;

                                                                                                                                        function isSerializationFirstNode

                                                                                                                                        isSerializationFirstNode: (node: SimpleNode) => boolean;

                                                                                                                                          function isSimpleElement

                                                                                                                                          isSimpleElement: (node: Maybe<any>) => node is SimpleElement;

                                                                                                                                            function isSmallInt

                                                                                                                                            isSmallInt: (value: number) => boolean;

                                                                                                                                              function keys

                                                                                                                                              keys: <T extends object>(obj: T) => Array<keyof T>;

                                                                                                                                                function mapPresentArray

                                                                                                                                                mapPresentArray: {
                                                                                                                                                <T, U>(list: PresentArray<T>, mapper: (input: T) => U): PresentArray<U>;
                                                                                                                                                <T, U>(list: any, mapper: (input: T) => U): any;
                                                                                                                                                };

                                                                                                                                                  function reverse

                                                                                                                                                  reverse: <T>(input: T[]) => IterableIterator<T>;

                                                                                                                                                    function strip

                                                                                                                                                    strip: (strings: TemplateStringsArray, ...args: unknown[]) => string;

                                                                                                                                                      function tuple

                                                                                                                                                      tuple: <T extends Lit[]>(...args: T) => T;

                                                                                                                                                        function unreachable

                                                                                                                                                        unreachable: (message?: string) => Error;

                                                                                                                                                          function unwrap

                                                                                                                                                          unwrap: <T>(val: Maybe<T>) => T;

                                                                                                                                                            function unwrapHandle

                                                                                                                                                            unwrapHandle: (handle: HandleResult) => number;

                                                                                                                                                              function unwrapTemplate

                                                                                                                                                              unwrapTemplate: (template: Template) => TemplateOk;

                                                                                                                                                                function values

                                                                                                                                                                values: <T>(obj: { [s: string]: T }) => T[];

                                                                                                                                                                  Classes

                                                                                                                                                                  class Stack

                                                                                                                                                                  class StackImpl<T> implements Stack<T> {}

                                                                                                                                                                    constructor

                                                                                                                                                                    constructor(values?: T[]);

                                                                                                                                                                      property current

                                                                                                                                                                      current: Nullable<T>;

                                                                                                                                                                        property size

                                                                                                                                                                        readonly size: number;

                                                                                                                                                                          method isEmpty

                                                                                                                                                                          isEmpty: () => boolean;

                                                                                                                                                                            method nth

                                                                                                                                                                            nth: (from: number) => Nullable<T>;

                                                                                                                                                                              method pop

                                                                                                                                                                              pop: () => Nullable<T>;

                                                                                                                                                                                method push

                                                                                                                                                                                push: (item: T) => void;

                                                                                                                                                                                  method toArray

                                                                                                                                                                                  toArray: () => T[];

                                                                                                                                                                                    Enums

                                                                                                                                                                                    enum ImmediateConstants

                                                                                                                                                                                    enum ImmediateConstants {
                                                                                                                                                                                    MAX_SMI = 1073741823,
                                                                                                                                                                                    MIN_SMI = -1073741824,
                                                                                                                                                                                    SIGN_BIT = -536870913,
                                                                                                                                                                                    MAX_INT = 536870911,
                                                                                                                                                                                    MIN_INT = -536870912,
                                                                                                                                                                                    FALSE_HANDLE = 0,
                                                                                                                                                                                    TRUE_HANDLE = 1,
                                                                                                                                                                                    NULL_HANDLE = 2,
                                                                                                                                                                                    UNDEFINED_HANDLE = 3,
                                                                                                                                                                                    ENCODED_FALSE_HANDLE = 0,
                                                                                                                                                                                    ENCODED_TRUE_HANDLE = 1,
                                                                                                                                                                                    ENCODED_NULL_HANDLE = 2,
                                                                                                                                                                                    ENCODED_UNDEFINED_HANDLE = 3,
                                                                                                                                                                                    }

                                                                                                                                                                                      member ENCODED_FALSE_HANDLE

                                                                                                                                                                                      ENCODED_FALSE_HANDLE = 0

                                                                                                                                                                                        member ENCODED_NULL_HANDLE

                                                                                                                                                                                        ENCODED_NULL_HANDLE = 2

                                                                                                                                                                                          member ENCODED_TRUE_HANDLE

                                                                                                                                                                                          ENCODED_TRUE_HANDLE = 1

                                                                                                                                                                                            member ENCODED_UNDEFINED_HANDLE

                                                                                                                                                                                            ENCODED_UNDEFINED_HANDLE = 3

                                                                                                                                                                                              member FALSE_HANDLE

                                                                                                                                                                                              FALSE_HANDLE = 0

                                                                                                                                                                                                member MAX_INT

                                                                                                                                                                                                MAX_INT = 536870911

                                                                                                                                                                                                  member MAX_SMI

                                                                                                                                                                                                  MAX_SMI = 1073741823

                                                                                                                                                                                                    member MIN_INT

                                                                                                                                                                                                    MIN_INT = -536870912

                                                                                                                                                                                                      member MIN_SMI

                                                                                                                                                                                                      MIN_SMI = -1073741824

                                                                                                                                                                                                        member NULL_HANDLE

                                                                                                                                                                                                        NULL_HANDLE = 2

                                                                                                                                                                                                          member SIGN_BIT

                                                                                                                                                                                                          SIGN_BIT = -536870913

                                                                                                                                                                                                            member TRUE_HANDLE

                                                                                                                                                                                                            TRUE_HANDLE = 1

                                                                                                                                                                                                              member UNDEFINED_HANDLE

                                                                                                                                                                                                              UNDEFINED_HANDLE = 3

                                                                                                                                                                                                                Type Aliases

                                                                                                                                                                                                                type Factory

                                                                                                                                                                                                                type Factory<T> = new (...args: unknown[]) => T;

                                                                                                                                                                                                                  type FIXME

                                                                                                                                                                                                                  type FIXME<T, S extends string> = (T & S) | T;

                                                                                                                                                                                                                    type Lit

                                                                                                                                                                                                                    type Lit = string | number | boolean | undefined | null | void | {};

                                                                                                                                                                                                                      Package Files (1)

                                                                                                                                                                                                                      Dependencies (2)

                                                                                                                                                                                                                      Dev Dependencies (7)

                                                                                                                                                                                                                      Peer Dependencies (0)

                                                                                                                                                                                                                      No peer dependencies.

                                                                                                                                                                                                                      Badge

                                                                                                                                                                                                                      To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                                                                                                                                      You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@glimmer/util.

                                                                                                                                                                                                                      • Markdown
                                                                                                                                                                                                                        [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@glimmer/util)
                                                                                                                                                                                                                      • HTML
                                                                                                                                                                                                                        <a href="https://www.jsdocs.io/package/@glimmer/util"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>