@semaver/core

Core interfaces, types, and helper methods for object manipulation and reflection.

Introduction

The core package is a collection of helper interfaces and classes designed to build frameworks with type safety. Its goal is to enhance readability and provide useful tools for other dependent projects.

Installation

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

Warning: Please install the library as a peer dependency if possible.

Table of Contents

• Types
  • JS Types
    • JsFunction
    • JsObject
  • Utility Types
    • EmptyGeneric
    • Nullable
    • Undefined
    • Empty
    • Throwable
  • Base Types
    • IClass
    • IFunction
    • IInterface
    • IType
• Extensions
  • InterfaceSymbol
    • For
  • CoreObject
    • isObjectEmpty
    • isObjectPrimitive
    • isObjectClass
    • classOfObject
    • haveObjectsSameClass
    • superClassOfObject
    • isNativeObjectClass
    • getObjectSuperClassChain
  • CoreReflect
    • hasOwnProperty
    • hasProperty
    • getPropertyOwner
    • getPropertyDescriptor
• Errors
  • ExtendedError
    • throwDefault
    • throwError

---

Types

JS Types

JsFunction

type JsFunction = Function;

Represents the default JavaScript function type.

Back to top

JsObject

type JsObject = Object;

Represents the default JavaScript object type.

Back to top

Utility Types

EmptyGeneric

interface EmptyGeneric<T> {};

Represents an empty generic object type.

Back to top

Nullable

type Nullable<T> = T | null;

Represents a generic object that can be null.

Back to top

Undefined

type Undefined<T> = T | undefined;

Represents a generic object that can be undefined.

Empty

type Undefined<T> = Nullable<T> | Undefined<T>;

Represents a generic object that can be null or undefined.

Back to top

Throwable

type Throwable<T> = T | never;

Represents a generic throwable object.

Back to top

Base Types

Contains interfaces and types to ensure strong typing of objects.

IClass

interface IClass<T> extends JsFunction, EmptyGeneric<T> {};

A generic class type with a prototype property of type IPrototype<T>.

Back to top

IFunction

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

A generic function type that accepts any number of arguments and returns a specified type.

Back to top

IInterface

interface IInterface<T> extends EmptyGeneric<T> {
  readonly uid: symbol;
}

A generic interface type with a uid property of type symbol.

Back to top

IType

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

A union type combining IClass<T> and IInterface<T>.

Back to top

---

Extensions

InterfaceSymbol

class InterfaceSymbol<T> implements IInterface<T> {}

Helper class to "materialize" interfaces. Since JavaScript interfaces are just syntactic sugar, they cannot be used as types (e.g., passed as parameters). InterfaceSymbol turns any interface into a symbol that can be used as a typical type while maintaining TypeScript's strong typing.

For

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

A static method to create a symbol for a given interface, effectively "materializing" it.

Example:

// To avoid TypeScript error: "refers to a type, but is being used as a value here."
export const ISomeInterface: IInterface<ISomeInterface> = InterfaceSymbol.for("ISomeInterface");

export interface ISomeInterface {
    // Interface definition
}

export class SomeInterfaceImpl implements ISomeInterface {
    // Implementation
}

// Usage in a container
container.bind(ISomeInterface).toClass(SomeInterfaceImpl);

Back to top

CoreObject

A collection of helper functions for working with objects.

Back to top

isObjectEmpty

function isObjectEmpty(obj: unknown): boolean;

Checks if a given object is null or undefined.

Back to top

isObjectPrimitive

function isObjectPrimitive(obj: unknown): boolean;

Checks if a given object is a primitive type.

Back to top

isObjectClass

function isObjectClass(obj: Nullable<object & { call?: JsFunction, apply?: JsFunction }>): boolean;

Checks if a given object is a class.

Back to top

classOfObject

function classOfObject<T extends object>(obj: IClass<T> | T): IClass<T>;

Returns the class of a given instance or the class itself.

Back to top

haveObjectsSameClass

function haveObjectsSameClass<A extends object, B extends object>(
  instanceA: Nullable<A>,
  instanceB: Nullable<B>
): boolean;

Returns true if two instances belong to the same class.

Back to top

superClassOfObject

function superClassOfObject<S extends object, C extends S>(
  childClass: Nullable<IClass<C>>,
  ignoreNativeObjectClass: boolean = false
): Nullable<IClass<S>>;

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

Back to top

isNativeObjectClass

function isNativeObjectClass<T extends object>(targetClass: Nullable<IClass<T>>): boolean;

Returns true if the class is the native JavaScript Object class.

Back to top

getObjectSuperClassChain

function getObjectSuperClassChain(
  obj: Nullable<object>,
  reversed: boolean = false,
  excludeNativeObjectClass: boolean = true
): readonly IClass<object>[];

Returns the superclass chain of the object.

• If reversed is false, the chain starts from the child classes:
  • ChildOfChildClass -> ChildClass -> ParentClass -> Object
• If reversed is true, the chain starts from the parent class:
  • Object -> ParentClass -> ChildClass -> ChildOfChildClass
• If excludeNativeObjectClass is true, the Object class is excluded from the chain.

Back to top

CoreReflect

A collection of helper functions for working with object reflection.

Back to top

hasOwnProperty

function hasOwnProperty(obj: Nullable<object>, property: PropertyKey): boolean;

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

Back to top

hasProperty

function hasProperty(obj: Nullable<object>, property: PropertyKey): boolean;

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

Back to top

getPropertyOwner

function getPropertyOwner<S extends object, C extends S>(
  obj: Nullable<C>,
  property: PropertyKey
): Nullable<S>;

Returns the object (class or instance) that owns the property.

Back to top

getPropertyDescriptor

function getPropertyDescriptor(
  obj: Nullable<object>,
  property: PropertyKey
): Nullable<PropertyDescriptor>;

Returns the descriptor of a property, whether own or inherited.

Back to top

---

Errors

ExtendedError

class ExtendedError extends Error {}

A base class for error handling.

Back to top

throwDefault

function throwDefault(target: object, error: string = "Error"): never;

Throws a default error with minimal information.

Back to top

throwError

function throwError(error: Error): never;

Throws a custom error.

Back to top