need-some-basic.js


_need-some_ is a collection of small yet useful functions.
The basic package provides core functionality that can be used in many javascript and typescript applications.

Installation

Simply install as dependency

npm install @need-some/basic --save

stdmethods

Methods for compatibility, but not defined as polyfill

$3

Adjust number, so it fits into the given borders. If the given number is lower than the lower bound (or greater than the upper bound), the bound is returned.
If a bound is undefined, this side is not adjusted. If the lower bound is greater than the upper bound, the result is kind of unexpected, and always one of the bounds.

adjust (n: number, lower: number|undefined, upper: number|undefined): number

$3

Truncate fractional part of number. Returns the signed integer part

trunc (n: number): number

$3

Pad a string to have at least n characters. The c characters are appended in front (left) of the string

padLeft (s: string, c: string, n: number): string

$3

Pad a string to have at least n characters. The c characters are appended at the end (right) of the string

padRight (s: string, c: string, n: number): string

$3

Pad a number with leading zeros to have at least n characters.
If the number is negative, the numbers absolute value is padded to one character less and a leading minus sign is added.
If the number string is already longer than the given length, it is returned without change.

padNumber (s: number, n: number): string

$3

Check whether a string starts with another string.

startsWith (str: string, start: string): boolean

$3

Check whether a string ends with another string

endsWith (str: string, start: string): boolean

$3

Split string on delimiter. A delimiter can be delimited by backslash '\'

splitSimple (s: string, delim: string): string[]

$3

Split well-formed string into parts with brakets.
Within the enclosed strings, the brakets will not be considered.
* E.g. 'a+(b+(c+d))+(e+f)' will be split into 'a+', 'b+(c+d))', '+', '(e+f)'

The resulting array will always start with an unenclosed part and have one unenclosed part between the enclosed ones.
These parts may be empty strings to provide a strict structure
* E.g. '(b+(c+d))' will be split into '', 'b+(c+d))'
* and '(b+(c+d))(e+f)' will be split into '', 'b+(c+d))', '', 'e+f'

Alternative start delimiters can be used to mask end delimiter within the enclosed parts
* E.g. 'a${b:{c}}' with start '${' and end '}' needs alternative start '{' so the outmost closing bracket is found

splitBracket(s: string, dstart: string, dend: string, altdstarts?: string[]): string[]

$3

Return the nested child of an object.

lookup(object: any, key: (string | number) | ((string | number)[])): any

$3

Set the value of a nested child of an object.

overwrite(object: any, key: (string | number) | ((string | number)[]), value: any): void

Converters

Interfaces for converters of string (or similar serialized form) to an object and vice versa are defined here.

The main interfaces are
Marshaller to serialize objects with its method marshal(object: T): S and Unmarshaller to deserialize with unmarshal(serialized: S): T
S is the type of the serialization (e.g. string) and T is the deserialized object type.

There are some convenience methods to use converters

$3

Create an instance to marshal with the given function

marshal(fun: (object: T) => S): Marshaller

$3

Create an instance to unmarshal with the given function

unmarshal(fun: (serialized: S) => T): Unmarshaller

$3

Create an instance to marshal with the given function

convert(marshalFunction: (object: T) => S, unmarshalFunction: (serialized: S) => T): Converter

$3

Construct a new converter instance that simple returns the given instance

identity(): Converter {

$3

Construct a new converter instance that calls the given converter for each array item.

map(converter: Converter): Converter

$3

Construct a new string converter instance which allows null. If null is unmarshalled, an empty string is returned.

nullsafestring(converter: Converter): Converter

$3

Construct a new converter instance which allows null.

nullsafe(converter: Converter): Converter

$3

Construct a new converter instance which allows undefined.

undefinedsafe(converter: Converter): Converter

Types

$3

Color is a class that parses and holds the color values.

$3

Convenience converter to convert between a color object and a hex string.