# guardSymbol()

## `guardSymbol()`

Guards the value to be a [`symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol).

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

```typescript
const guardSymbol = <Payload extends object>(
  value: symbol,
  callback?: ResultCallback<symbol, Payload>,
  payload?: Payload
): value is symbol => isSymbol(value, callback, payload);
```

{% endcode %}

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

### Generic type variables

#### <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-null-payload-greater-than) function and [`payload`](#payload-payload) optional parameter of the [`guardSymbol()`](#guardsymbol) function from which it captures its value.

### Parameters

#### `value: symbol`

A [`symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) type value to guard.

#### `callback?: ResultCallback<null, Payload>`

The optional callback [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions) of [`ResultCallback`](https://type.angular-package.dev/type-draft/type/resultcallback) type with parameters, the [`value`](#value-symbol) that has been checked, the `result` of this check, and `payload` of generic type variable [`Payload`](#payloadextendsobject) with optional properties from the provided `payload`, to handle them before the `result` 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) is assigned to the [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) of the given [`callback`](#callback-resultcallback-less-than-null-payload-greater-than) function.

### Return type

#### `value is`<mark style="color:green;">`symbol`</mark>

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

### Returns

The **return value** is a [`boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) indicating whether the [`value`](#value-symbol) is a [`symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol).

## Example usage

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

const SYMBOL_NUMBER: unique symbol = Symbol(27);
const SYMBOL_STRING: unique symbol = Symbol('Twenty seven');

guardSymbol(SYMBOL_NUMBER); // true; return type `value is symbol`
guardSymbol(SYMBOL_STRING); // true; return type `value is symbol`
```