@aedart/support/dist/types/reflections.d.ts

The Ion support package

/**
 * @aedart/support
 * 
 * BSD-3-Clause, Copyright (c) 2023-present Alin Eugen Deac <aedart@gmail.com>.
 */

import { ClassBlueprint } from '@aedart/contracts/support/reflections';
import { ConstructorLike } from '@aedart/contracts';

/**
 * Assert that given target object has a "prototype" property defined
 *
 * @see hasPrototypeProperty
 *
 * @param {object} target
 * @param {string} [message]
 *
 * @throws {TypeError} If target object does not have "prototype" property
 */
declare function assertHasPrototypeProperty(target: object, message?: string): void;

/**
 * Determine if target class look like given blueprint.
 *
 * @param {object} target
 * @param {ClassBlueprint} blueprint
 *
 * @throws {TypeError} If target object does not have "prototype" property. Or, if blueprint does not contain at least
 *                     one member or static member.
 */
declare function classLooksLike(target: object, blueprint: ClassBlueprint): boolean;

/**
 * Returns property keys that are defined target's prototype
 *
 * @param {ConstructorLike} target
 * @param {boolean} [recursive=false] If `true`, then target's parent prototypes are traversed and all
 *                                    property keys are returned.
 *
 * @returns {PropertyKey[]}
 *
 * @throws {TypeError} If target object does not have "prototype" property
 */
declare function classOwnKeys(target: ConstructorLike, recursive?: boolean): PropertyKey[];

/**
 * Returns all parent classes of given target
 *
 * @see {getParentOfClass}
 *
 * @param {ConstructorLike} target The target class.
 * @param {boolean} [includeTarget=false] If `true`, then given target is included in the output as the first element.
 *
 * @returns {ConstructorLike[]} List of parent classes, ordered by the top-most parent class first.
 *
 * @throws {TypeError}
 */
declare function getAllParentsOfClass(target: ConstructorLike, includeTarget?: boolean): ConstructorLike[];

/**
 * Returns a {@link PropertyDescriptor} object, from target's prototype that matches given property key
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getOwnPropertyDescriptor
 *
 * @param {ConstructorLike} target Class that contains property in its prototype
 * @param {PropertyKey} key Name of the property
 *
 * @return {PropertyDescriptor|undefined} Property descriptor or `undefined` if property does
 *                                        not exist in target's prototype.
 *
 * @throws {TypeError} If target is not an object or has no prototype
 */
declare function getClassPropertyDescriptor(target: ConstructorLike, key: PropertyKey): PropertyDescriptor | undefined;

/**
 * Returns all property descriptors that are defined target's prototype
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getOwnPropertyDescriptor
 *
 * @param {ConstructorLike} target The target class
 * @param {boolean} [recursive=false] If `true`, then target's parent prototypes are traversed.
 *                                    Descriptors are merged, such that the top-most class' descriptors
 *                                    are returned.
 *
 * @return {Record<PropertyKey, PropertyDescriptor>} Object with the property descriptors, or empty object of target has
 *                                                   properties defined.
 *
 * @throws {TypeError} If target is not an object or has no prototype property
 */
declare function getClassPropertyDescriptors(target: ConstructorLike, recursive?: boolean): Record<PropertyKey, PropertyDescriptor>;

/**
 * Returns target class' constructor name, if available
 *
 * @param {ConstructorLike} target
 * @param {string|null} [defaultValue=null] A default string value to return if target has no constructor name
 *
 * @return {string|null} Constructor name, or default value
 */
declare function getConstructorName(target: ConstructorLike, defaultValue?: string | null): string | null;

/**
 * Return target class' constructor name or default to target's description tag if a name is unavailable
 *
 * **Note**: _Method is a shortcut for the following:_
 * ```js
 * getConstructorName(target, descTag(target));
 * ```
 *
 * @see getConstructorName
 * @see descTag
 *
 * @param {ConstructorLike} target
 *
 * @return {string}
 */
declare function getNameOrDesc(target: ConstructorLike): string;

/**
 * Returns the parent class of given target class
 *
 * **Note**: _If target has a parent that matches
 * [FUNCTION_PROTOTYPE]{@link import('@aedart/contracts/support/reflections').FUNCTION_PROTOTYPE}, then `null` is returned!_
 *
 * @param {ConstructorLike} target The target class
 *
 * @returns {ConstructorLike | null} Parent class or `null`, if target has no parent class.
 *
 * @throws {TypeError}
 */
declare function getParentOfClass(target: ConstructorLike): ConstructorLike | null;

/**
 * Determine if given target object contains all given methods
 *
 * @param {object} target
 * @param {...PropertyKey} [methods]
 *
 * @return {boolean}
 */
declare function hasAllMethods(target: object, ...methods: PropertyKey[]): boolean;

/**
 * Determine if given target object contains method
 *
 * @param {object} target
 * @param {PropertyKey} method
 *
 * @return {boolean}
 */
declare function hasMethod(target: object, method: PropertyKey): boolean;

/**
 * Determine if target object has a prototype property defined
 *
 * **Warning**: _This method is NOT the same as checking if {@link Reflect.getPrototypeOf} of an object is `null`!_
 * _The method literally checks if a "prototype" property is defined in target, that it is not `null` or `undefined`,
 * and that its of the [type]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof} 'object'!_
 *
 * **Note**: _Method returns `false` if `null` given as argument!_
 *
 * @param {object} target
 *
 * @returns {boolean}
 */
declare function hasPrototypeProperty(target: object): boolean;

/**
 * Determine if given argument is callable, but is not a class constructor (es6 style)
 *
 * @see {isClassConstructor}
 * @see https://github.com/caitp/TC39-Proposals/blob/trunk/tc39-reflect-isconstructor-iscallable.md
 *
 * @param {unknown} value
 *
 * @return {boolean}
 */
declare function isCallable(value: unknown): boolean;

/**
 * Determine if given value is a class constructor (es6 style)
 *
 * @see https://github.com/caitp/TC39-Proposals/blob/trunk/tc39-reflect-isconstructor-iscallable.md
 *
 * @param {unknown} value
 *
 * @return {boolean}
 */
declare function isClassConstructor(value: unknown): boolean;

/**
 * Determine if value is a [Class Method Reference]{@link import('@aedart/constracts').ClassMethodReference}
 *
 * @param {unknown} value
 *
 * @return {boolean}
 */
declare function isClassMethodReference(value: unknown): boolean;

/**
 * Determine if given argument is a constructor
 *
 * @see https://github.com/caitp/TC39-Proposals/blob/trunk/tc39-reflect-isconstructor-iscallable.md
 *
 * @param {unknown} argument
 *
 * @return {boolean}
 */
declare function isConstructor(argument: unknown): boolean;

/**
 * Opposite of {@link isKeyUnsafe}
 *
 * @param {PropertyKey} key
 *
 * @returns {boolean}
 */
declare function isKeySafe(key: PropertyKey): boolean;

/**
 * Determine if property key is unsafe
 *
 * @see DANGEROUS_PROPERTIES
 *
 * @param {PropertyKey} key
 *
 * @returns {boolean}
 */
declare function isKeyUnsafe(key: PropertyKey): boolean;

/**
 * Determine if given property key is a method in target
 *
 * @param {object} target
 * @param {PropertyKey} property
 *
 * @return {boolean}
 */
declare function isMethod(target: object, property: PropertyKey): boolean;

/**
 * Determine if target class is a subclass (_child class_) of given superclass (_parent class_)
 *
 * **Note**: _Method determines if target is a child of given superclass, by checking if the `target.prototype`
 * is an instance of given superclass (`target.prototype instanceof superclass`)
 * However, if given target or superclass does not have a prototype property, then `false` is returned._
 *
 * @param {object} target
 * @param {ConstructorLike} superclass
 *
 * @returns {boolean} `true` if target is a subclass of given superclass, `false` otherwise.
 */
declare function isSubclass(target: object, superclass: ConstructorLike): boolean;

/**
 * Determine if target class is a subclass of given superclass, or if it looks like given blueprint
 *
 * **Note**: _Method is an alias for `isSubclass(target, superclass) || classLooksLike(target, blueprint)`._
 *
 * @see isSubclass
 * @see classLooksLike
 *
 * @param {object} target
 * @param {ConstructorLike} superclass
 * @param {ClassBlueprint} blueprint
 *
 * @throws {TypeError}
 */
declare function isSubclassOrLooksLike(target: object, superclass: ConstructorLike, blueprint: ClassBlueprint): boolean;

/**
 * Determine if object of a "weak" kind, e.g. `WeakRef`, `WeakMap` or `WeakSet`
 *
 * @param {object} value
 *
 * @return {boolean}
 */
declare function isWeakKind(value: object): boolean;

export { assertHasPrototypeProperty, classLooksLike, classOwnKeys, getAllParentsOfClass, getClassPropertyDescriptor, getClassPropertyDescriptors, getConstructorName, getNameOrDesc, getParentOfClass, hasAllMethods, hasMethod, hasPrototypeProperty, isCallable, isClassConstructor, isClassMethodReference, isConstructor, isKeySafe, isKeyUnsafe, isMethod, isSubclass, isSubclassOrLooksLike, isWeakKind };