# 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`](/type-draft/type/constructor.md), 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`](/type-draft/type/resultcallback.md#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`](/type-draft/type/constructor.md).

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

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

{% hint style="info" %}
The [`payload`](/type-draft/type/resultcallback.md#payload-payload) parameter of the [`callback`](/type-draft/type/resultcallback.md) 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`](/type-draft/type/resultcallback.md#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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://type.angular-package.dev/type-draft/is/isinstance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.