# isStringLength()

## `isStringLength()`

Checks if [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any) value is a [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) type or an instance of [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)(by using [`isString()`](https://type.angular-package.dev/type-draft/is/isstring)) of a specified length.

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

```typescript
const isStringLength = <
  Type extends AnyString = string,
  Length extends number = number,
  Payload extends object = object
>(
  value: any,
  length: Length,
  callback: ResultCallback<any, { length: Length } & Payload> = resultCallback,
  payload?: Payload
): value is StringOfLength<Length, Length, Type> =>
  callback(
    isString(value) && isNumberType(length) && length > 0
      ? value.valueOf().length === length
      : false,
    value,
    { ...payload, length } as any
  );
```

{% endcode %}

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

### Generic type variables

#### <mark style="color:green;">**`Type`**</mark>**`extends`**<mark style="color:green;">**`AnyString`**</mark>**`=`**<mark style="color:green;">**`string`**</mark>

A generic type variable `Type` constrained by [`AnyString`](https://type.angular-package.dev/type-draft/type/anystring) indicates the [`string`](https://www.typescriptlang.org/docs/handbook/basic-types.html#string) type of the given [`value`](#value-any) via the [return type](#return-type).

#### <mark style="color:green;">**`Length`**</mark>**`extends`**<mark style="color:green;">**`number`**</mark>

A generic type variable `Length` constrained by the [`number`](https://www.typescriptlang.org/docs/handbook/basic-types.html#number) type, by default of value captured from the supplied [`length`](#length-length) indicates the **length** of the provided [`value`](#value-any) via the [return type](#return-type) and the fixed shape of optional [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) parameter of the provided [`callback`](#callback-resultcallback-less-than-any-length-length-and-payload-greater-than) function.

#### <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-length-length-and-payload-greater-than) function and [`payload`](#payload-payload) optional parameter of the [`isStringLength()`](#isstringlength) 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.

#### `length: Length`

The **length** of generic type variable [`Length`](#lengthextendsnumber) of a given [`value`](#value-any).

#### `callback: ResultCallback<any, { length: Length } & 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.

{% hint style="info" %}
The [`payload`](https://type.angular-package.dev/type-draft/type/resultcallback#payload-payload) parameter of the [`callback`](#callback-resultcallback-less-than-any-length-length-and-payload-greater-than) function consists of the [`length`](#length-length) property given in 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-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-length-length-and-payload-greater-than) function.

### Return type

#### `value is StringOfLength<Length, Length, Type>`

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 [`StringOfLength`](https://type.angular-package.dev/type-draft/type/stringoflength) that takes generic type variables `Min` and `Max` from the generic type variable [`Length`](#lengthextendsnumber) as the **length** of the supplied [`value`](#value-any), and generic type variable [`Type`](#typeextendsanystring) as the type of the provided [`value`](#value-any).

### 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 a [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) type or an instance of [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) of the specified length.

## Example usage

### `string` type

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

const firstName = 'my first name';

// true; The return type `value is StringOfLength<13, 13, string>`
isStringLength(firstName, 13);
// false; The return type `value is StringOfLength<12, 12, string>`
isStringLength(firstName, 12);
// false; The return type `value is StringOfLength<14, 13, string>`
isStringLength(firstName, 14);
```

### `String` instance

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

const firstName = 'my first name';
const firstNameBox = new String(firstName);

// true; The return type `value is StringOfLength<0, 13, string>`
isStringLength(firstNameBox, 13);
// false; The return type `value is StringOfLength<14, 14, string>`
isStringLength(firstNameBox, 14);
// false; The return type `value is StringOfLength<12, 12, string>`
isStringLength(firstNameBox, 12);
```