@glimmer/util

@glimmer/util

Version 0.92.0
Published 7 days ago
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;

variable NS_XLINK

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)

dist/dev/index.d.ts

Dependencies (2)

Dev Dependencies (7)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto 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>

Updated 4 days ago.
Package analyzed in 4351 ms.
Missing or incorrect documentation? Open an issue for this package.