@semaver/core v2.0.0

@semaver/core

Core interface/types and helper methods.

Introduction

The core package is a bundle of helper interfaces and classes to build the framework with type safety. The goal is to increase the readability and create some useful tools for other dependent projects.

Installation

$ yarn add @semaver/core --peer
$ npm install @semaver/core  

:warning: Important! Please, install the library as peer dependency if possible.

Table Of Contents

• Types

  • JS Types

    • JsFunction
    • JsObject

  • Utility Types

    • EmptyGeneric
    • Nullable
    • Throwable

  • Base Types

    • IClass
    • IFunction
    • IInterface
    • IType

  • Dictionaries

    • IStringKeyDictionary
    • INumberKeyDictionary
    • IDictionary

• Extensions

  • InterfaceSymbol
    • for
  • CoreObject
    • isEmpty
    • isPrimitive
    • isClass
    • classOf
    • haveSameClass
    • superClassOf
    • isNativeObjectClass
    • getSuperClassChain
  • CoreReflect
    • hasOwn
    • has
    • getOwner
    • getDescriptor
• Errors
  • CoreError
    • throwDefault
    • throwError

Types

JS Types

JsFunction

type JsFunction = Function

Type for default javascript function.

back

JsObject

JsObject = Object

Type for default javascript object.

back

Utility Types

EmptyGeneric

type EmptyGeneric<T> = {};

Type for empty generic object.

back

Nullable

type Nullable<T> = T | null | undefined;

Type for generic object that can be null or undefined.

back

Throwable

type Throwable<T> = T | never

Type for generic throwable object.

back

Base Types

Contains interfaces and mixed type to make objects strongly typed.

IClass

interface IClass<T> extends JsFunction, EmptyGeneric<T>

Generic class type with prototype property of type IPrototype<T>.

back

IFunction

type IFunction<TReturnType> = (...args: any[]) => TReturnType

Generic function type with any number of arguments and a returning type.

back

IInterface

interface IInterface<T>

Generic interface type with read only property uid of type symbol.

back

IType

type IType<T> = IClass<T> | IInterface<T>

Union type to mix IClass<T> and IInterface<T>.

back

Dictionaries

Key-value objects with understandable names.

IStringKeyDictionary

interface IStringKeyDictionary<TValueType>

Dictionary with string keys.

back

INumberKeyDictionary

interface INumberKeyDictionary<TValueType>

Dictionary with number keys.

back

IDictionary

type IDictionary<TValueType> = 
	IStringKeyDictionary<TValueType> | 
	INumberKeyDictionary<TValueType>

Union type for dictionary with string keys or number keys.

back

Extensions

InterfaceSymbol

class InterfaceSymbol<T> implements IInterface<T>

Helper to "materialize" interfaces. JS interfaces are just syntactic sugar, so can not be used as a type (e.g. send as a parameter in methods). InterfaceSymbol turns any interface into a symbol, so it can be used as a typical type anywhere, that at the same time is treated as IInterface by TS strong typization.

For

static for
<T>(uid: string | symbol): IInterface<T>

Static method to create a symbol for a given interface, that is used to "materialize" an interface.

Example:

export const ISomeInterface: IInterface<ISomeInterface> =
    InterfaceSymbol.for("ISomeInterface");

export interface ISomeInterface {
    ...
}

export class SomeInterfaceImpl implements ISomeInterface {
...
}

...
container.bind(ISomeInterface).toClass(SomeInterfaceImpl);

back

CoreObject

class CoreObject 

Helper class for working with objects.

back

isEmpty

static isEmpty<T>(obj: T): boolean

Checks if given object is null or undefined.

back

isPrimitive

static isPrimitive<T>(obj: T): boolean

Checks if given object is primitive.

back

isClass

static isClass<T extends object>(obj: T): boolean

Checks if given object is class.

back

classOf

static classOf<T extends object >(obj: IClass<T> | T): IClass<T>

Returns class from the given instance or from class itself.

back

haveSameClass

static haveSameClass<A extends object, B extends object>(instanceA: A, instanceB: B): boolean

Returns true if two instances are of the same class.

back

superClassOf

static superClassOf<S extends object, C extends S>(
  childClass: IClass<C>, 
  ignoreNativeObjectClass: boolean = false
): Nullable<IClass<S>>

Returns super class of a given class. If ignoreNativeObjectClass is true and superclass is native JavaScript Object, then returns undefined.

back

isNativeObjectClass

static isNativeObjectClass<T extends object>(targetClass: IClass<T>): boolean

Returns true if class is the native JavaScript Object class.

back

getSuperClassChain

static getSuperClassChain<S extends object, C extends S>(
    obj: C, 
    reversed: boolean = false, 
    excludeNativeObjectClass: boolean = true
): ReadonlyArray<IClass<S>>

Returns superclass chain of the object.

If reversed === false, then the chain starts from child classes:

ChildOfChildClass -> ChildClass -> ParentClass -> Object

If reversed === true, then the chain starts from parent class:

Object -> ParentClass -> ChildClass -> ChildOfChildClass

If excludeNativeObjectClass === true, then Object class is excluded from chain.

back

CoreReflect

class CoreReflect 

Helper class for object reflection.

back

hasOwn

static hasOwn<T extends object>(obj: T, property: PropertyKey): boolean

Checks if object (class or instance) has own property.

back

has

static has<T extends object>(obj: T, property: PropertyKey): boolean

Checks if object (class or instance) has own or inherited property.

back

getOwner

static getOwner<S extends object, C extends S>(obj: C, property: PropertyKey): Nullable<S>

Returns object (class or instance), that is the owner of the property.

back

getDescriptor

static getDescriptor<T extends object>(obj: T, property: PropertyKey): Nullable<PropertyDescriptor>

Returns a descriptor of the property. The property can be own or inherited.

back

Errors

CoreError

class CoreError extends Error

Base class for error handling.

back

throwDefault

static throwDefault<T>(target: T, error: string = "Error"): never

Throws default error, with minimal information.

back

throwError

static throwError<T extends Error>(error: T): never

Throws custom error.

back