@glimmer/util

  • Version 0.84.3
  • Published
  • 462 kB
  • 3 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, U>(target: T, source: U): T & U;
<T_1, U_1, V>(target: T_1, source1: U_1, source2: V): T_1 & U_1 & V;
<T_2, 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 debugToString

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

        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 HAS_NATIVE_PROXY

                const HAS_NATIVE_PROXY: boolean;

                  variable HAS_NATIVE_SYMBOL

                  const HAS_NATIVE_SYMBOL: boolean;

                    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 SERIALIZATION_FIRST_NODE_STRING

                      const SERIALIZATION_FIRST_NODE_STRING: string;

                        variable symbol

                        const symbol: (key: string) => any;

                          variable verifySteps

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

                            Functions

                            function assert

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

                              function assertNever

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

                                function assertPresent

                                assertPresent: <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 | 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 extends unknown>() => 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 enumerableSymbol

                                                                    enumerableSymbol: (key: string) => any;

                                                                      function exhausted

                                                                      exhausted: (value: never) => never;

                                                                        function expect

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

                                                                          function extractHandle

                                                                          extractHandle: (handle: HandleResult) => number;

                                                                            function fillNulls

                                                                            fillNulls: <T>(count: number) => 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 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>(list: readonly T[]) => list is PresentArray<T>;

                                                                                              function isSerializationFirstNode

                                                                                              isSerializationFirstNode: (node: SimpleNode) => boolean;

                                                                                                function isSmallInt

                                                                                                isSmallInt: (value: number) => boolean;

                                                                                                  function keys

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

                                                                                                    function mapPresent

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

                                                                                                      function strip

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

                                                                                                        function toPresentOption

                                                                                                        toPresentOption: <T>(list: T[]) => Option<PresentArray<T>>;

                                                                                                          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: Option<T>;

                                                                                                                            property size

                                                                                                                            readonly size: number;

                                                                                                                              method isEmpty

                                                                                                                              isEmpty: () => boolean;

                                                                                                                                method nth

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

                                                                                                                                  method pop

                                                                                                                                  pop: () => Option<T>;

                                                                                                                                    method push

                                                                                                                                    push: (item: T) => void;

                                                                                                                                      method toArray

                                                                                                                                      toArray: () => T[];

                                                                                                                                        Enums

                                                                                                                                        enum ImmediateConstants

                                                                                                                                        const 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 (17)

                                                                                                                                                                          Dependencies (3)

                                                                                                                                                                          Dev Dependencies (3)

                                                                                                                                                                          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>