# guardInstance()

## `guardInstance()`

Guards the value to be an instance of the given [`constructor`](#constructor-constructor-less-than-obj-greater-than).

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

```typescript
const guardInstance = <
  Obj extends object,
  Payload extends object = object
>(
  value: Obj,
  constructor: Constructor<Obj>,
  callback?: ResultCallback<Obj, { ctor: typeof constructor } & Payload>,
  payload?: Payload
): value is Obj => isInstance(value, constructor, callback, payload);
```

{% endcode %}

Code on [**GitHub**](https://github.com/angular-package/type/blob/5.0.x/src/guard/lib/guard-instance.func.ts).

### Generic type variables

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

A generic type variable `Obj` constrained by [`object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) indicates captured [`object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) type of the given [`value`](#value-obj) via the [return type](#return-type) and the [`value`](https://docs.angular-package.dev/type/type/resultcallback#value-value) parameter of the provided [`callback`](#callback-resultcallback-less-than-obj-ctor-typeof-constructor-and-payload-greater-than) function [`ResultCallback`](https://docs.angular-package.dev/type/type/resultcallback) type.

#### <mark style="color:green;">**`Payload`**</mark>**`extends`**<mark style="color:green;">**`object`**</mark>**`=`**<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://docs.angular-package.dev/type/type/resultcallback#payload-payload) of the supplied [`callback`](#callback-resultcallback-less-than-obj-ctor-typeof-constructor-and-payload-greater-than) function and [`payload`](#payload-payload) optional parameter of the [`guardInstance()`](#guardinstance) function from which it captures its value.

### Parameters

#### `value: Obj`

An [`object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) of a generic type variable [`Obj`](#typeextendsanyboolean) to guard and be compared with 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/Reference/Global_Objects/Function) that specifies the type of the [`Constructor`](https://docs.angular-package.dev/type/type/constructor).

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

The optional callback [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions) of [`ResultCallback`](https://docs.angular-package.dev/type/type/resultcallback) type with parameters, the [`value`](#value-obj) that has been checked, the [`result`](https://docs.angular-package.dev/type/type/resultcallback#result-boolean) of this check, and [`payload`](https://docs.angular-package.dev/type/type/resultcallback#payload-payload) of generic type variable [`Payload`](#payloadextendsobject-object) with optional properties from the provided [`payload`](#payload-payload), to handle them before the [`result`](https://docs.angular-package.dev/type/type/resultcallback#result-boolean) return. By default, it uses [`resultCallback()`](https://docs.angular-package.dev/type/helper/resultcallback) function.

{% hint style="info" %}
The [`payload`](https://docs.angular-package.dev/type/type/resultcallback#payload-payload) parameter of the [`callback`](#callback-resultcallback-less-than-obj-ctor-typeof-constructor-and-payload-greater-than) function consists of the **`ctor`** property under which is set given [`constructor`](#constructor-constructor-less-than-obj-greater-than), 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-object) is assigned to the [`payload`](https://docs.angular-package.dev/type/type/resultcallback#payload-payload) of the given [`callback`](#callback-resultcallback-less-than-obj-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-obj) is a generic type variable [`Obj`](#objextendsobject) by default of the type captured from the provided [`value`](#value-obj).

### Returns

The **return value** is a [`boolean`](https://www.typescriptlang.org/docs/handbook/basic-types.html#boolean) indicating whether the [`value`](#value-obj) is an instance of a given [`constructor`](#constructor-constructor-less-than-obj-greater-than).

## Example usage

```typescript
// Usage example.
import { guardInstance } from '@angular-package/type';

// Person interface.
interface Person {
  firstName?: string;
  surname?: string;
  age?: number;
  sex?: 'male' | 'female';
}

// Class constructor.
class Persons implements Person {
  firstName = '';
  surname = '';
  age = 15;
}

// Function person constructor.
function personFunctionConstructor(this: Person, ...args: any[]): Person {
  if (args) {
    this.firstName = args[0];
    this.surname = args[1];
    this.age = args[2];
    this.sex = args[3];
  }
  return this;
}

const personInstance: Person = new (personFunctionConstructor as any)('First name', 'Sur name', 27);
const personsInstance: Persons = new Persons();

guardInstance(personInstance, personFunctionConstructor as any); // true
guardInstance(personsInstance, Persons); // true
```