# isInstance()

## `isInstance()`

Checks if [`any`](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) value is an instance of a given [`constructor`](#constructor-constructor-less-than-obj-greater-than).

{% code title="is-instance.func.ts" %}

```typescript
const isInstance = <Obj, Payload extends object>(
  value: any,
  constructor: Constructor<Obj>,
  callback: ResultCallback<
    any,
    { ctor: typeof constructor } & Payload
  > = resultCallback,
  payload?: Payload
): value is Obj =>
  callback(
    isObject(value) &&
      typeof constructor === 'function' &&
      constructor instanceof Function
      ? value instanceof constructor
      : false,
    value,
    { ...payload, ctor: constructor } as any
  );
```

{% endcode %}

{% embed url="<https://github.com/angular-package/type/blob/main/src/is/lib/is-instance.func.ts>" %}

### Generic type variables

#### <mark style="color:green;">`Obj`</mark>

A generic type variable `Obj`, by default captured from the provided [`constructor`](#constructor-constructor-less-than-obj-greater-than), indicates the type of generic type [`Constructor`](https://type.angular-package.dev/type-draft/type/constructor), and the type of [`value`](#value-any) parameter via the [return type](#return-type) `value is Obj`.

#### <mark style="color:green;">**`Payload`**</mark>**`extends`**<mark style="color:green;">**`object`**</mark>

The `Payload` generic type variable constrained by [`object`](https://www.typescriptlang.org/docs/handbook/basic-types.html#object) indicates the type of optional parameter [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) of the supplied [`callback`](#callback-resultcallback-less-than-any-ctor-typeof-constructor-and-payload-greater-than) function and [`payload`](#payload-payload) optional parameter of the [`isInstance()`](#isinstance) function from which it captures its value.

### Parameters

#### `value: any`

The value of [`any`](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) type to be an instance of a given [`constructor`](#constructor-constructor-less-than-obj-greater-than).

#### `constructor: Constructor<Obj>`

A [`class`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) or [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions) that specifies the type of [`Constructor`](https://type.angular-package.dev/type-draft/type/constructor).

#### `callback: ResultCallback<any, { ctor: typeof constructor } & Payload>`

A callback `function` of [`ResultCallback`](https://type.angular-package.dev/type-draft/type/resultcallback) type with parameters, the [`value`](#value-any) that has been checked, the [`result`](https://type.angular-package.dev/type-draft/type/resultcallback#result-boolean) of this check, and [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) of generic type variable [`Payload`](#payloadextendsobject) with optional properties from the provided [`payload`](#payload-payload), to handle them before the [`result`](https://type.angular-package.dev/type-draft/type/resultcallback#result-boolean) return. By default, it uses [`resultCallback()`](https://type.angular-package.dev/type-draft/helper/resultcallback) function.

{% hint style="info" %}
The [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) parameter of the [`callback`](https://type.angular-package.dev/type-draft/type/resultcallback) function consists of the [`ctor`](#constructor-constructor-less-than-obj-greater-than) property  given in the [`constructor`](#constructor-constructor-less-than-obj-greater-than) parameter of the core function, and it can't be overwritten by the given [`payload`](#payload-payload) parameter of the core function.
{% endhint %}

#### `payload?: Payload`

An optional [`object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) of the generic type variable [`Payload`](#payloadextendsobject) is assigned to the [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) of the given [`callback`](#callback-resultcallback-less-than-any-ctor-typeof-constructor-and-payload-greater-than) function.

### Return type

#### `value is Obj`

The **return type** is a [`boolean`](https://www.typescriptlang.org/docs/handbook/basic-types.html#boolean) as the result of its statement, indicating the [`value`](#value-any) is a generic type variable [`Obj`](#obj) by default of type captured from the supplied [`constructor`](#constructor-constructor-less-than-obj-greater-than).

### Returns

The **return value** is a [`boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) indicating whether the provided [`value`](#value-any) is an instance of a given [`constructor`](#constructor-constructor-less-than-obj-greater-than).

## Example usage

### Basic usage

```typescript
// Example usage.
import { isInstance } from '@angular-package/type';

// Classes.
class Some { x = 127; }
class Two { y = 'Lorem ipsum'; }

const SOME = new Some();
const TWO = new Two();

isInstance(TWO, Some); // false
isInstance(SOME, Some); // true
isInstance<Some, object>(TWO, Two); // true and type error

isInstance(new Array(), Array), // Returns `true` as `value is Array`
isInstance(new Boolean(), Boolean), // Returns `true` as `value is Boolean`
isInstance(new Date(), Date), // Returns `true` as `value is Date`
isInstance(new Error(), Error), // Returns `true` as `value is Error`
isInstance(new Function(), Function), // Returns `true` as `value is Function`
isInstance(new Map(), Map), // Returns `true` as `value is Map`
isInstance(new Number(), Number), // Returns `true` as `value is Number`
isInstance(new Object(), Object), // Returns `true` as `value is Object`
isInstance(new RegExp(/^[]/), RegExp), // Returns `true` as `value is RegExp`
isInstance(new Set(), Set), // Returns `true` as `value is Set`
isInstance(new String(), String), // Returns `true` as `value is String`
```

### Parameters `callback` and `payload`&#x20;

```typescript
// Example usage with callback and payload.
import { isInstance } from '@angular-package/type';

// Classes.
class Some { x = 127; }
class Two { y = 'Lorem ipsum'; }

const SOME = new Some();
const TWO = new Two();

isInstance(TWO, Some, (result, value, payload) => {
  value // Returns the provided `Two`
  if (payload) {
    payload.className // Returns `'Some'`
    payload.ctor // Returns the provided `Some`
  }
  return result;
}, { className: Some });
```

### Function constructor

```typescript
// Example usage with function constructor.
import { isInstance } from '@angular-package/type';

// Function constructor.
function functionConstructor(this: any, ...args: any[]): any {
  if (args) {
    args.forEach((arg, index: number) => this[index] = arg[index]);
  }
  return this;
}

const anyInstance: any = new (functionConstructor as any)('First name', 'Sur name', 27);
isInstance(anyInstance, functionConstructor as any); // true
```