# @helpers4/guard

> Tree-shakable TypeScript utility functions for the `guard` domain.
> Package: `@helpers4/guard` — Version: 3.0.1
> License: LGPL-3.0-or-later

## Installation

```sh
npm install @helpers4/guard
# or
pnpm add @helpers4/guard
```

## Usage

```typescript
import { isArray, isArrayBuffer, isArrayLike, ... } from '@helpers4/guard';
```

## Functions

| Function | Description |
|---|---|
| `isArray` | Checks if a value is an array. |
| `isArrayBuffer` | Checks if a value is an ArrayBuffer instance.  Useful for filtering or type-narrowing in a functiona |
| `isArrayLike` | Checks if a value is array-like: has a non-negative integer `length` property.  Returns `true` for a |
| `isAsyncFunction` | Checks if a value is an async function.  Returns `true` for any function declared with `async`. |
| `isAsyncGenerator` | Checks if a value is an async generator object (the result of calling an `async function*`).  Distin |
| `isAsyncGeneratorFunction` | Checks if a value is an async generator function (an `async function*` declaration or expression).   |
| `isAsyncIterable` | Checks if a value implements the async iterable protocol.  Returns `true` for any object that has a  |
| `isBigInt` | Checks if a value is a bigint. |
| `isBlob` | Checks if a value is a Blob instance.  Useful for filtering or type-narrowing in a functional pipeli |
| `isBoolean` | Checks if a value is a boolean. |
| `isCssColor` | Checks whether a value is a syntactically-safe, plain CSS color: a hex color (`#rgb`, `#rgba`, `#rrg |
| `isDate` | Checks if a value is a Date instance.  Note: this only checks the type, not whether the Date is vali |
| `isDefined` | Checks if a value is defined (not undefined nor null). This is the inverse of isNullish.  Use as a t |
| `isError` | Checks if a value is an Error instance. |
| `isFalsy` | Checks if a value is falsy (`false`, `null`, `undefined`, `0`, `""`, `NaN`). |
| `isFormData` | Checks if a value is a FormData instance.  Useful for filtering or type-narrowing in a functional pi |
| `isFunction` | Checks if a value is a function. |
| `isGenerator` | Checks if a value is a generator object (the result of calling a `function*`).  Distinct from isGene |
| `isGeneratorFunction` | Checks if a value is a generator function (a `function*` declaration or expression).  Distinct from  |
| `isIterable` | Checks if a value is iterable (has a `Symbol.iterator` method).  Returns `true` for strings, arrays, |
| `isMap` | Checks if a value is a Map instance. |
| `isNull` | Checks if a value is `null`. |
| `isNullish` | Checks if a value is null or undefined (nullish). |
| `isNumber` | Checks if a value is a number.  Returns `false` for `NaN`, which intentionally deviates from `typeof |
| `isPlainObject` | Checks if a value is a plain object.  A plain object is created by `{}`, `new Object()`, or `Object. |
| `isPrimitive` | Checks if a value is a JavaScript primitive.  Primitive types: `string`, `number`, `boolean`, `bigin |
| `isPromise` | Checks if a value is a Promise or a thenable.  Returns `true` for any object that has `.then()` and  |
| `isPromiseLike` | Checks if a value is a thenable (has a `.then()` method).  Looser than isPromise: accepts any object |
| `isPropertyKey` | Checks if a value is a valid property key: `string`, `number`, or `symbol`. |
| `isRegExp` | Checks if a value is a RegExp instance. |
| `isSet` | Checks if a value is a Set instance. |
| `isSpecialObject` | Determines if a value is a special object that should not have its properties compared deeply. Speci |
| `isString` | Checks if a value is a string. |
| `isSymbol` | Checks if a value is a symbol. |
| `isTemporalDuration` | Checks if a value is a `Temporal.Duration`.  Uses `instanceof` when `Temporal` is available globally |
| `isTemporalInstant` | Checks if a value is a `Temporal.Instant`.  Uses `instanceof` when `Temporal` is available globally, |
| `isTemporalPlainDate` | Checks if a value is a `Temporal.PlainDate`.  Uses `instanceof` when `Temporal` is available globall |
| `isTemporalPlainDateTime` | Checks if a value is a `Temporal.PlainDateTime`.  Uses `instanceof` when `Temporal` is available glo |
| `isTemporalPlainTime` | Checks if a value is a `Temporal.PlainTime`.  Uses `instanceof` when `Temporal` is available globall |
| `isTemporalZonedDateTime` | Checks if a value is a `Temporal.ZonedDateTime`.  Uses `instanceof` when `Temporal` is available glo |
| `isTimestamp` | Checks if a value is a valid timestamp (milliseconds or Unix seconds).  Supports: - JavaScript / Jav |
| `isTruthy` | Checks if a value is truthy (not `false`, `null`, `undefined`, `0`, `""`, or `NaN`).  This is the ty |
| `isUndefined` | Checks if a value is `undefined`. |
| `isValidRegex` | Checks if a string is a valid regex pattern. |
| `isWeakMap` | Checks if a value is a WeakMap instance. |
| `isWeakSet` | Checks if a value is a WeakSet instance. |

---

## API Reference

### `isArray`

Checks if a value is an array.

```typescript
import { isArray } from '@helpers4/guard';

isArray(value: unknown): value is unknown[]
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is unknown[]` — True if value is an array

**Examples:**

*isArray*

```typescript
```ts
isArray([1, 2, 3]) // => true
isArray('hello')   // => false
isArray({})        // => false
```
```

---

### `isArrayBuffer`

Checks if a value is an ArrayBuffer instance.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isArrayBuffer)`

```typescript
import { isArrayBuffer } from '@helpers4/guard';

isArrayBuffer(value: unknown): value is ArrayBuffer
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is ArrayBuffer` — True if value is an ArrayBuffer

**Examples:**

*Detect an ArrayBuffer*

Returns true only for ArrayBuffer instances, not TypedArray views.

```typescript
isArrayBuffer(new ArrayBuffer(8)) // => true
isArrayBuffer(new Uint8Array(8))  // => false
isArrayBuffer('hello')            // => false
```

*Filter ArrayBuffers from a mixed array*

Use as a predicate in .filter() to extract ArrayBuffer values.

```typescript
const values = [new ArrayBuffer(4), 'text', new ArrayBuffer(8), 42];
values.filter(isArrayBuffer)
// => [ArrayBuffer(4), ArrayBuffer(8)]
```

---

### `isArrayLike`

Checks if a value is array-like: has a non-negative integer `length` property.

Returns `true` for arrays, strings, `arguments` objects, `NodeList`, typed
arrays, and any object with a valid `length`. Functions are excluded even though
they have a `length` (arity), as they are not considered array-like in practice.

```typescript
import { isArrayLike } from '@helpers4/guard';

isArrayLike(value: unknown): value is ArrayLike<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is ArrayLike<unknown>` — `true` if value is array-like

**Examples:**

*Detect array-like values*

Arrays, strings, and objects with a non-negative integer length are array-like.

```typescript
isArrayLike([1, 2, 3])       // => true
isArrayLike('hello')         // => true
isArrayLike({ length: 3 })   // => true
isArrayLike({ length: -1 })  // => false
isArrayLike(() => {})        // => false  (functions excluded)
isArrayLike(null)            // => false
```

*Convert an array-like value to an array*

Use as a guard before Array.from().

```typescript
function toArray(value: unknown): unknown[] {
  if (isArrayLike(value)) return Array.from(value);
  return [value];
}
toArray([1, 2])       // => [1, 2]
toArray('abc')        // => ['a', 'b', 'c']
toArray(42)           // => [42]
```

---

### `isAsyncFunction`

Checks if a value is an async function.

Returns `true` for any function declared with `async`.

```typescript
import { isAsyncFunction } from '@helpers4/guard';

isAsyncFunction(value: unknown): value is function
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is function` — True if value is an async function

**Examples:**

*isAsyncFunction*

```typescript
```ts
isAsyncFunction(async () => {})      // => true
isAsyncFunction(async function() {}) // => true
isAsyncFunction(() => {})            // => false
isAsyncFunction(42)                  // => false
```
```

---

### `isAsyncGenerator`

Checks if a value is an async generator object (the result of calling an `async function*`).

Distinct from isAsyncGeneratorFunction: this predicate targets the
*instance* produced by calling an async generator function, not the function itself.

```typescript
import { isAsyncGenerator } from '@helpers4/guard';

isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unknown, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is AsyncGenerator<unknown, unknown, unknown>` — `true` if value is an AsyncGenerator instance

**Examples:**

*Detect an async generator instance*

Returns true only for the object produced by calling an async function*.

```typescript
async function* gen() { yield 1; }
isAsyncGenerator(gen())  // => true   (instance)
isAsyncGenerator(gen)    // => false  (function)
isAsyncGenerator([])     // => false
```

*Distinguish async from sync generators*

isAsyncGenerator is false for sync generator instances.

```typescript
function* sync() { yield 1; }
async function* async_() { yield 1; }
isAsyncGenerator(sync())   // => false
isAsyncGenerator(async_()) // => true
```

---

### `isAsyncGeneratorFunction`

Checks if a value is an async generator function (an `async function*` declaration or expression).

Distinct from isAsyncGenerator: this predicate targets the *function* itself,
not the async iterator it produces when called.

```typescript
import { isAsyncGeneratorFunction } from '@helpers4/guard';

isAsyncGeneratorFunction(value: unknown): value is AsyncGeneratorFunction
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is AsyncGeneratorFunction` — `true` if value is an AsyncGeneratorFunction

**Examples:**

*Detect an async generator function*

Returns true for async function* declarations and expressions.

```typescript
async function* gen() { yield 1; }
isAsyncGeneratorFunction(gen)         // => true
isAsyncGeneratorFunction(gen())       // => false  (instance)
isAsyncGeneratorFunction(async () => {}) // => false
```

*Distinguish async generator functions from sync generator functions*

isAsyncGeneratorFunction is false for sync function*.

```typescript
function* sync() { yield 1; }
async function* async_() { yield 1; }
isAsyncGeneratorFunction(sync)   // => false
isAsyncGeneratorFunction(async_) // => true
```

---

### `isAsyncIterable`

Checks if a value implements the async iterable protocol.

Returns `true` for any object that has a `[Symbol.asyncIterator]()` method,
including async generators. Note that regular iterables (arrays, strings, etc.)
are **not** async iterables.

```typescript
import { isAsyncIterable } from '@helpers4/guard';

isAsyncIterable(value: unknown): value is AsyncIterable<unknown, any, any>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is AsyncIterable<unknown, any, any>` — `true` if value is async iterable

**Examples:**

*Detect an async generator*

Async generators implement the async iterable protocol.

```typescript
async function* stream() { yield 1; yield 2; }
isAsyncIterable(stream())   // => true
isAsyncIterable([1, 2, 3])  // => false  (Iterable, not AsyncIterable)
isAsyncIterable('hello')    // => false
```

*Guard before for-await-of*

Use to type-narrow before consuming a value with for-await-of.

```typescript
async function consume(source: unknown) {
  if (isAsyncIterable(source)) {
    for await (const item of source) {
      console.log(item);
    }
  }
}
```

---

### `isBigInt`

Checks if a value is a bigint.

```typescript
import { isBigInt } from '@helpers4/guard';

isBigInt(value: unknown): value is bigint
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is bigint` — True if value is a bigint

**Examples:**

*isBigInt*

```typescript
```ts
isBigInt(42n)  // => true
isBigInt(42)   // => false
isBigInt('42') // => false
```
```

---

### `isBlob`

Checks if a value is a Blob instance.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isBlob)`

```typescript
import { isBlob } from '@helpers4/guard';

isBlob(value: unknown): value is Blob
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Blob` — True if value is a Blob

**Examples:**

*Detect a Blob*

Returns true only for Blob instances.

```typescript
isBlob(new Blob(['hello'])) // => true
isBlob(new Blob([], { type: 'application/json' })) // => true
isBlob('hello')             // => false
```

*Filter Blobs from a mixed array*

Use as a predicate in .filter() to extract Blob values.

```typescript
const values = [new Blob(['a']), 'text', new Blob(['b']), 42];
values.filter(isBlob)
// => [Blob, Blob]
```

---

### `isBoolean`

Checks if a value is a boolean.

```typescript
import { isBoolean } from '@helpers4/guard';

isBoolean(value: unknown): value is boolean
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is boolean` — True if value is a boolean

**Examples:**

*isBoolean*

```typescript
```ts
isBoolean(true)  // => true
isBoolean(false) // => true
isBoolean(1)     // => false
```
```

---

### `isCssColor`

Checks whether a value is a syntactically-safe, plain CSS color: a hex color
(`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`), a functional notation (`rgb()`,
`rgba()`, `hsl()`, `hsla()`), or a single-word named color (`red`,
`rebeccapurple`).

Intended to sanitize a color value before interpolating it into inline
`style`/`cssText` — it does not implement the full CSS color grammar or
validate named colors against the real keyword list, it only rejects
characters (`{`, `}`, `;`, ``) or shapes that could smuggle extra CSS
declarations into the surrounding rule.

```typescript
import { isCssColor } from '@helpers4/guard';

isCssColor(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — `true` if value is a string that looks like a safe, plain CSS color

**Examples:**

*Validate a color before writing it to inline style*

Accepts hex, functional (rgb/rgba/hsl/hsla), and named colors.

```typescript
isCssColor('#ff0000')            // => true
isCssColor('rgba(0, 0, 0, 0.5)') // => true
isCssColor('rebeccapurple')      // => true
isCssColor(42)                   // => false
```

*Reject values that could inject extra CSS declarations*

Guards against untrusted data smuggling a second declaration into a style attribute.

```typescript
isCssColor('red; background: url(evil)') // => false
isCssColor('red}body{color:blue')        // => false
```

---

### `isDate`

Checks if a value is a Date instance.

Note: this only checks the type, not whether the Date is valid.
Use `date/isValid` to also validate that the Date is not `Invalid Date`.

```typescript
import { isDate } from '@helpers4/guard';

isDate(value: unknown): value is Date
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Date` — True if value is a Date instance

**Examples:**

*isDate*

```typescript
```ts
isDate(new Date())          // => true
isDate(new Date('invalid')) // => true (still a Date instance)
isDate('2023-01-01')       // => false
isDate(1609459200000)      // => false
```
```

---

### `isDefined`

Checks if a value is defined (not undefined nor null).
This is the inverse of isNullish.

Use as a type-safe filter callback to remove `null`/`undefined` from arrays.

```typescript
import { isDefined } from '@helpers4/guard';

isDefined<T>(value: Maybe<T>): value is T
```

**Parameters:**

- `value: Maybe<T>` — The value to check

**Returns:** `value is T` — True if value is not undefined nor null

**Examples:**

*isDefined*

```typescript
```ts
isDefined(42)        // => true
isDefined('')        // => true (empty string is defined)
isDefined(null)      // => false
isDefined(undefined) // => false
```
```

*isDefined*

```typescript
```ts
// Type-safe alternative to filter out null/undefined
const items: (string | null | undefined)[] = ['a', null, 'b', undefined];
const result = items.filter(isDefined);
// => ['a', 'b'] with type string[]
```
```

---

### `isError`

Checks if a value is an Error instance.

```typescript
import { isError } from '@helpers4/guard';

isError(value: unknown): value is Error
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Error` — True if value is an Error (or subclass like TypeError, RangeError, etc.)

**Examples:**

*isError*

```typescript
```ts
isError(new Error('oops'))     // => true
isError(new TypeError('bad'))  // => true
isError({ message: 'fake' })  // => false
```
```

---

### `isFalsy`

Checks if a value is falsy (`false`, `null`, `undefined`, `0`, `""`, `NaN`).

```typescript
import { isFalsy } from '@helpers4/guard';

isFalsy(value: unknown): value is Falsy
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Falsy` — True if the value is falsy

**Examples:**

*Check falsy values*

Returns true for all falsy values: false, null, undefined, 0, "", NaN.

```typescript
isFalsy(0)         // => true
isFalsy('')        // => true
isFalsy(null)      // => true
isFalsy('hello')   // => false
```

---

### `isFormData`

Checks if a value is a FormData instance.

Useful for filtering or type-narrowing in a functional pipeline:
`values.filter(isFormData)`

```typescript
import { isFormData } from '@helpers4/guard';

isFormData(value: unknown): value is FormData
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is FormData` — True if value is a FormData

**Examples:**

*Detect a FormData*

Returns true only for FormData instances.

```typescript
isFormData(new FormData()) // => true
isFormData({})             // => false
isFormData(null)           // => false
```

*Filter FormData from a mixed array*

Use as a predicate in .filter() to extract FormData values.

```typescript
const fd = new FormData();
fd.append('name', 'Alice');
const values = [fd, {}, new FormData(), 'text'];
values.filter(isFormData)
// => [FormData, FormData]
```

---

### `isFunction`

Checks if a value is a function.

```typescript
import { isFunction } from '@helpers4/guard';

isFunction(value: unknown): value is Function
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Function` — True if value is a function

**Examples:**

*isFunction*

```typescript
```ts
isFunction(() => {})       // => true
isFunction(function() {})  // => true
isFunction('function')     // => false
```
```

---

### `isGenerator`

Checks if a value is a generator object (the result of calling a `function*`).

Distinct from isGeneratorFunction: this predicate targets the
*instance* produced by calling a generator function, not the function itself.

```typescript
import { isGenerator } from '@helpers4/guard';

isGenerator(value: unknown): value is Generator<unknown, unknown, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Generator<unknown, unknown, unknown>` — `true` if value is a Generator instance

**Examples:**

*Distinguish a generator instance from its function*

isGenerator targets the object returned by calling a function*, not the function itself.

```typescript
function* counter() { yield 1; yield 2; }
isGenerator(counter())  // => true   (instance)
isGenerator(counter)    // => false  (function)
isGenerator([1, 2])     // => false
```

*Type-narrow to safely call .next()*

Narrows the type to Generator so you can call .next() and .return().

```typescript
function* gen() { yield 1; yield 2; }
const value: unknown = gen();
if (isGenerator(value)) {
  const { value: v, done } = value.next();
  // v: unknown, done: boolean | undefined
}
```

---

### `isGeneratorFunction`

Checks if a value is a generator function (a `function*` declaration or expression).

Distinct from isGenerator: this predicate targets the *function* itself,
not the iterator it produces when called.

```typescript
import { isGeneratorFunction } from '@helpers4/guard';

isGeneratorFunction(value: unknown): value is GeneratorFunction
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is GeneratorFunction` — `true` if value is a GeneratorFunction

**Examples:**

*Detect a generator function*

Returns true for function* declarations and expressions.

```typescript
function* gen() { yield 1; }
isGeneratorFunction(gen)      // => true
isGeneratorFunction(gen())    // => false  (instance, not function)
isGeneratorFunction(() => {}) // => false
```

*Filter generator factories from a mixed array*

Use as a predicate to select only generator functions.

```typescript
const fns = [() => {}, function* () { yield 1; }, async () => {}];
fns.filter(isGeneratorFunction)
// => [function* () { yield 1; }]
```

---

### `isIterable`

Checks if a value is iterable (has a `Symbol.iterator` method).

Returns `true` for strings, arrays, Maps, Sets, generators, and any object
implementing the iterable protocol.

```typescript
import { isIterable } from '@helpers4/guard';

isIterable(value: unknown): value is Iterable<unknown, any, any>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Iterable<unknown, any, any>` — True if value is iterable

**Examples:**

*isIterable*

```typescript
```ts
isIterable([1, 2, 3])      // => true
isIterable('hello')        // => true
isIterable(new Map())      // => true
isIterable(new Set())      // => true
isIterable({})             // => false
isIterable(42)             // => false
```
```

---

### `isMap`

Checks if a value is a Map instance.

```typescript
import { isMap } from '@helpers4/guard';

isMap(value: unknown): value is Map<unknown, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Map<unknown, unknown>` — True if value is a Map

**Examples:**

*isMap*

```typescript
```ts
isMap(new Map())           // => true
isMap(new Map([['a', 1]])) // => true
isMap({})                  // => false
```
```

---

### `isNull`

Checks if a value is `null`.

```typescript
import { isNull } from '@helpers4/guard';

isNull(value: unknown): value is null
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is null` — True if value is null

**Examples:**

*isNull*

```typescript
```ts
isNull(null)      // => true
isNull(undefined) // => false
isNull(0)         // => false
```
```

---

### `isNullish`

Checks if a value is null or undefined (nullish).

```typescript
import { isNullish } from '@helpers4/guard';

isNullish(value: unknown): value is null | undefined
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is null | undefined` — True if value is null or undefined

**Examples:**

*Check for null or undefined*

Returns true only for null and undefined, not other falsy values.

```typescript
isNullish(null)      // => true
isNullish(undefined) // => true
isNullish(0)         // => false
isNullish('')        // => false
```

*Guard before accessing properties*

Use as a type guard to safely narrow types.

```typescript
function greet(name: string | null | undefined): string {
  if (isNullish(name)) return 'Hello, stranger!';
  return `Hello, ${name}!`;
}
greet(null) // => 'Hello, stranger!'
```

---

### `isNumber`

Checks if a value is a number.

Returns `false` for `NaN`, which intentionally deviates from `typeof` behavior
to increase user-friendliness.

```typescript
import { isNumber } from '@helpers4/guard';

isNumber(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — True if value is a number (excludes NaN)

**Examples:**

*isNumber*

```typescript
```ts
isNumber(42)    // => true
isNumber(0)     // => true
isNumber(NaN)   // => false
isNumber('123') // => false
```
```

---

### `isPlainObject`

Checks if a value is a plain object.

A plain object is created by `{}`, `new Object()`, or `Object.create(null)`.
Returns `false` for arrays, Date, Map, Set, RegExp, class instances, etc.

```typescript
import { isPlainObject } from '@helpers4/guard';

isPlainObject(value: unknown): value is Record<string, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Record<string, unknown>` — True if value is a plain object

**Examples:**

*isPlainObject*

```typescript
```ts
isPlainObject({})           // => true
isPlainObject({ a: 1 })    // => true
isPlainObject(new Date())  // => false
isPlainObject([])          // => false
isPlainObject(null)        // => false
```
```

---

### `isPrimitive`

Checks if a value is a JavaScript primitive.

Primitive types: `string`, `number`, `boolean`, `bigint`, `symbol`, `null`, `undefined`.

```typescript
import { isPrimitive } from '@helpers4/guard';

isPrimitive(value: unknown): value is Primitive
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Primitive` — True if value is a primitive

**Examples:**

*isPrimitive*

```typescript
```ts
isPrimitive('hello')  // => true
isPrimitive(42)       // => true
isPrimitive(null)     // => true
isPrimitive({})       // => false
isPrimitive([])       // => false
```
```

---

### `isPromise`

Checks if a value is a Promise or a thenable.

Returns `true` for any object that has `.then()` and `.catch()` methods,
including native Promises and userland implementations.

```typescript
import { isPromise } from '@helpers4/guard';

isPromise(value: unknown): value is PromiseLike<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PromiseLike<unknown>` — True if value is a Promise-like object

**Examples:**

*isPromise*

```typescript
```ts
isPromise(Promise.resolve(42))     // => true
isPromise(new Promise(() => {}))   // => true
isPromise({ then: () => {} })      // => false (no .catch)
isPromise(42)                      // => false
```
```

---

### `isPromiseLike`

Checks if a value is a thenable (has a `.then()` method).

Looser than isPromise: accepts any object or function with a `then`
method, including non-standard Promise implementations without `.catch()`.
Follows the Promise/A+ specification for thenables.

```typescript
import { isPromiseLike } from '@helpers4/guard';

isPromiseLike(value: unknown): value is PromiseLike<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PromiseLike<unknown>` — `true` if value is a PromiseLike (thenable)

**Examples:**

*Detect any thenable*

Returns true for native Promises and any object with a .then() method.

```typescript
isPromiseLike(Promise.resolve(1))    // => true
isPromiseLike({ then: () => {} })    // => true   (thenable)
isPromiseLike(42)                    // => false
isPromiseLike(null)                  // => false
isPromiseLike({ then: 'not-a-fn' }) // => false
```

*Handle both Promises and thenables in a utility*

Use isPromiseLike to accept any thenable, not just native Promises.

```typescript
function toPromise<T>(value: T | PromiseLike<T>): Promise<T> {
  if (isPromiseLike(value)) return Promise.resolve(value);
  return Promise.resolve(value);
}
```

---

### `isPropertyKey`

Checks if a value is a valid property key: `string`, `number`, or `symbol`.

```typescript
import { isPropertyKey } from '@helpers4/guard';

isPropertyKey(value: unknown): value is PropertyKey
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PropertyKey` — `true` if value can be used as an object property key

**Examples:**

*Detect valid property keys*

Strings, numbers, and symbols are valid property keys.

```typescript
isPropertyKey('name')        // => true
isPropertyKey(42)            // => true
isPropertyKey(Symbol('id'))  // => true
isPropertyKey(null)          // => false
isPropertyKey(true)          // => false
```

*Safe dynamic property access*

Use as a guard before indexing an object with an unknown key.

```typescript
function get(obj: Record<PropertyKey, unknown>, key: unknown): unknown {
  if (isPropertyKey(key)) return obj[key];
  return undefined;
}
get({ a: 1 }, 'a')    // => 1
get({ a: 1 }, null)   // => undefined
```

---

### `isRegExp`

Checks if a value is a RegExp instance.

```typescript
import { isRegExp } from '@helpers4/guard';

isRegExp(value: unknown): value is RegExp
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is RegExp` — True if value is a RegExp

**Examples:**

*isRegExp*

```typescript
```ts
isRegExp(/abc/)          // => true
isRegExp(new RegExp('a')) // => true
isRegExp('abc')          // => false
```
```

---

### `isSet`

Checks if a value is a Set instance.

```typescript
import { isSet } from '@helpers4/guard';

isSet(value: unknown): value is Set<unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Set<unknown>` — True if value is a Set

**Examples:**

*Check whether a value is a Set*

Returns true only for real Set instances.

```typescript
isSet(new Set([1, 2, 3])) // => true
isSet([1, 2, 3])          // => false
```

*Type-safe narrowing in a conditional*

Inside the `if` branch, the value is narrowed to Set<unknown>.

```typescript
const value: unknown = new Set(['a', 'b']);
if (isSet(value)) {
  value.size // => 2, type-safe access
}
```

---

### `isSpecialObject`

Determines if a value is a special object that should not have its properties compared deeply.
Special objects include: Date, Function, Promise, Observable, RegExp, Error, Map, Set, WeakMap, WeakSet, etc.

```typescript
import { isSpecialObject } from '@helpers4/guard';

isSpecialObject(value: unknown): boolean
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `boolean` — `true` if the value is a special object, `false` otherwise

**Examples:**

*Detect special objects*

Returns true for built-in objects like Date, Map, Set, RegExp, etc.

```typescript
isSpecialObject(new Date())     // => true
isSpecialObject(new Map())      // => true
isSpecialObject(/regex/)        // => true
```

*Plain objects are not special*

Returns false for plain objects and arrays.

```typescript
isSpecialObject({ a: 1 })  // => false
isSpecialObject([1, 2])    // => false
```

---

### `isString`

Checks if a value is a string.

```typescript
import { isString } from '@helpers4/guard';

isString(value: unknown): value is string
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is string` — True if value is a string

**Examples:**

*isString*

```typescript
```ts
isString('hello') // => true
isString(123)     // => false
```
```

---

### `isSymbol`

Checks if a value is a symbol.

```typescript
import { isSymbol } from '@helpers4/guard';

isSymbol(value: unknown): value is symbol
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is symbol` — True if value is a symbol

**Examples:**

*isSymbol*

```typescript
```ts
isSymbol(Symbol('test')) // => true
isSymbol(Symbol.iterator) // => true
isSymbol('symbol')       // => false
```
```

---

### `isTemporalDuration`

Checks if a value is a `Temporal.Duration`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalDuration } from '@helpers4/guard';

isTemporalDuration(value: unknown): value is Duration
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Duration` — True if value is a `Temporal.Duration`

**Examples:**

*isTemporalDuration*

```typescript
```ts
isTemporalDuration(Temporal.Duration.from({ hours: 1 }))  // => true
isTemporalDuration(Temporal.Now.instant())                 // => false
isTemporalDuration(1000)                                   // => false
```
```

---

### `isTemporalInstant`

Checks if a value is a `Temporal.Instant`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalInstant } from '@helpers4/guard';

isTemporalInstant(value: unknown): value is Instant
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is Instant` — True if value is a `Temporal.Instant`

**Examples:**

*isTemporalInstant*

```typescript
```ts
isTemporalInstant(Temporal.Now.instant())      // => true
isTemporalInstant(Temporal.Now.plainDateISO())  // => false
isTemporalInstant(new Date())                   // => false
```
```

---

### `isTemporalPlainDate`

Checks if a value is a `Temporal.PlainDate`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalPlainDate } from '@helpers4/guard';

isTemporalPlainDate(value: unknown): value is PlainDate
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PlainDate` — True if value is a `Temporal.PlainDate`

**Examples:**

*isTemporalPlainDate*

```typescript
```ts
isTemporalPlainDate(Temporal.PlainDate.from('2025-01-19'))  // => true
isTemporalPlainDate(Temporal.Now.instant())                 // => false
isTemporalPlainDate(new Date())                             // => false
```
```

---

### `isTemporalPlainDateTime`

Checks if a value is a `Temporal.PlainDateTime`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalPlainDateTime } from '@helpers4/guard';

isTemporalPlainDateTime(value: unknown): value is PlainDateTime
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PlainDateTime` — True if value is a `Temporal.PlainDateTime`

**Examples:**

*isTemporalPlainDateTime*

```typescript
```ts
isTemporalPlainDateTime(Temporal.PlainDateTime.from('2025-01-19T12:00'))  // => true
isTemporalPlainDateTime(Temporal.Now.instant())                           // => false
isTemporalPlainDateTime(new Date())                                       // => false
```
```

---

### `isTemporalPlainTime`

Checks if a value is a `Temporal.PlainTime`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalPlainTime } from '@helpers4/guard';

isTemporalPlainTime(value: unknown): value is PlainTime
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is PlainTime` — True if value is a `Temporal.PlainTime`

**Examples:**

*isTemporalPlainTime*

```typescript
```ts
isTemporalPlainTime(Temporal.PlainTime.from('12:30:00'))  // => true
isTemporalPlainTime(Temporal.Now.instant())               // => false
isTemporalPlainTime(new Date())                           // => false
```
```

---

### `isTemporalZonedDateTime`

Checks if a value is a `Temporal.ZonedDateTime`.

Uses `instanceof` when `Temporal` is available globally, and falls back
to `Symbol.toStringTag` for environments without Temporal (e.g. browsers).

```typescript
import { isTemporalZonedDateTime } from '@helpers4/guard';

isTemporalZonedDateTime(value: unknown): value is ZonedDateTime
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is ZonedDateTime` — True if value is a `Temporal.ZonedDateTime`

**Examples:**

*isTemporalZonedDateTime*

```typescript
```ts
isTemporalZonedDateTime(Temporal.Now.zonedDateTimeISO())  // => true
isTemporalZonedDateTime(Temporal.Now.instant())           // => false
isTemporalZonedDateTime(new Date())                       // => false
```
```

---

### `isTimestamp`

Checks if a value is a valid timestamp (milliseconds or Unix seconds).

Supports:
- JavaScript / Java timestamps (milliseconds since epoch)
- Unix timestamps (seconds since epoch)

The function uses a heuristic to distinguish between the two:
numbers ≤ ~7.26 billion are treated as seconds, larger as milliseconds.

```typescript
import { isTimestamp } from '@helpers4/guard';

isTimestamp(value: unknown): value is number
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is number` — True if value is a number that represents a valid timestamp

**Examples:**

*isTimestamp*

```typescript
```ts
isTimestamp(1609459200000) // => true (JS ms — 2021-01-01)
isTimestamp(1609459200)    // => true (Unix seconds — 2021-01-01)
isTimestamp(Date.now())    // => true
isTimestamp(NaN)           // => false
isTimestamp('1609459200')  // => false (not a number)
```
```

---

### `isTruthy`

Checks if a value is truthy (not `false`, `null`, `undefined`, `0`, `""`, or `NaN`).

This is the type-safe alternative to `Boolean()` as a filter callback.
Unlike `filter(Boolean)`, using `filter(isTruthy)` correctly narrows the
resulting array type by excluding falsy values.

```typescript
import { isTruthy } from '@helpers4/guard';

isTruthy<T>(value: Falsy | T): value is T
```

**Parameters:**

- `value: Falsy | T` — The value to check

**Returns:** `value is T` — True if the value is truthy

**Examples:**

*Check truthy values*

Returns true for all truthy values, false for falsy ones.

```typescript
isTruthy(1)         // => true
isTruthy('hello')   // => true
isTruthy(0)         // => false
isTruthy(null)      // => false
```

*Type-safe filter alternative to Boolean*

Use isTruthy with Array.filter to get correct TypeScript narrowing.

```typescript
const items = ['a', '', null, 'b', undefined];
const result = items.filter(isTruthy);
// => ['a', 'b'] with type string[]
```

---

### `isUndefined`

Checks if a value is `undefined`.

```typescript
import { isUndefined } from '@helpers4/guard';

isUndefined(value: unknown): value is undefined
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is undefined` — True if value is undefined

**Examples:**

*isUndefined*

```typescript
```ts
isUndefined(undefined) // => true
isUndefined(null)      // => false
isUndefined(0)         // => false
```
```

---

### `isValidRegex`

Checks if a string is a valid regex pattern.

```typescript
import { isValidRegex } from '@helpers4/guard';

isValidRegex(value: string): boolean
```

**Parameters:**

- `value: string` — The string to check

**Returns:** `boolean` — True if the string is a valid regex pattern

**Examples:**

*isValidRegex*

```typescript
```ts
isValidRegex('[a-z]+') // => true
isValidRegex('.*')     // => true
isValidRegex('[')      // => false
```
```

---

### `isWeakMap`

Checks if a value is a WeakMap instance.

```typescript
import { isWeakMap } from '@helpers4/guard';

isWeakMap(value: unknown): value is WeakMap<object, unknown>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is WeakMap<object, unknown>` — True if value is a WeakMap

**Examples:**

*Check whether a value is a WeakMap*

Distinguishes WeakMap from the regular (iterable) Map.

```typescript
isWeakMap(new WeakMap()) // => true
isWeakMap(new Map())     // => false
```

*Plain objects are not WeakMaps*

Only real WeakMap instances pass, not objects that merely look like one.

```typescript
isWeakMap({ get: () => undefined, set: () => {} })
// => false
```

---

### `isWeakSet`

Checks if a value is a WeakSet instance.

```typescript
import { isWeakSet } from '@helpers4/guard';

isWeakSet(value: unknown): value is WeakSet<object>
```

**Parameters:**

- `value: unknown` — The value to check

**Returns:** `value is WeakSet<object>` — True if value is a WeakSet

**Examples:**

*Check whether a value is a WeakSet*

Distinguishes WeakSet from the regular (iterable) Set.

```typescript
isWeakSet(new WeakSet()) // => true
isWeakSet(new Set())     // => false
```

*Arrays are not WeakSets*

Only real WeakSet instances pass.

```typescript
isWeakSet([1, 2, 3])
// => false
```

---
