# isArray()

## `isArray()`

Checks if [`any`](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) value is of the type obtained from its [`object` class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString#using_tostring_to_detect_object_class) equal to `'array'` or an [`object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) type and passes the test [`Array.isArray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) method.

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

```typescript
const isArray = <Type = any, Payload extends object = object>(
  value: any,
  callback: ResultCallback<any, Payload> = resultCallback,
  payload?: Payload
): value is Array<Type> =>
  callback(
    (typeOf(value) === 'array' || typeof value === 'object') &&
      Array.isArray(value),
    value,
    payload
  );
```

{% endcode %}

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

### Generic type variables

#### <mark style="color:green;">**`Type`**</mark>**`=`**<mark style="color:green;">**`any`**</mark>

The `Type` generic type variable indicates the [`array`](https://www.typescriptlang.org/docs/handbook/basic-types.html#array) element type of the given [`value`](#value-any) via the [return type](#return-type), by default is [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any).

#### <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://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) of the supplied [`callback`](#callback-resultcallback-less-than-any-payload-greater-than) function and [`payload`](#payload-payload) optional parameter of the [`isArray()`](#isarray) 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 check.

#### `callback: ResultCallback<any, 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-object) 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.

#### `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://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) of the given [`callback`](#callback-resultcallback-less-than-any-payload-greater-than) function.

### Return type

#### `value is Array<Type>`

The **return type** is a [`boolean`](https://www.typescriptlang.org/docs/handbook/basic-types.html#boolean) because of used the `is` operator indicating the value is an [`array`](https://www.typescriptlang.org/docs/handbook/basic-types.html#array) that takes generic type variable [`Type`](#type-any) by default of value [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any) as the type of its elements.

### 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 [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array).

## Example usage

### Basic example

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

const ARRAY_NUMBER = [1, 2, 3];
const ARRAY_STRING = ['a', 'b', 'c'];

isArray(ARRAY_NUMBER); // Returns `true` as `value is any[]`
isArray<string>(ARRAY_STRING); // Returns `true` as `value is string[]`
```

### Fake `array`

```typescript
// Fake array example.
import { isArray } from '@angular-package/type'; 

const fakeArray = new String('');

Object.assign(fakeArray, {
  get [Symbol.toStringTag](): string {
    return 'array';
  }
});

isArray(fakeArray), // false
typeOf(fakeArray), // "array"
typeof fakeArray, // "object"
Array.isArray(fakeArray) // false
```

### Parameters `callback` and `payload`

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

isArray([1, 2, 3], (result, value, payload) => {
  if (result === true) {
    // Returns `(3) [1, 2, 3]`
    value

    if (payload) {
      // Returns `{ "1": "First", "2": "Second", "3": "Third" }`
      payload.transform;
    }
  }
  return result;
  // Returns `true` as `value is any[]`
}, { transform: { 1: 'First', 2: 'Second', 3: 'Third'} }); 
```