Add is.optional and assert.optional

Fixes #111
This commit is contained in:
Sindre Sorhus 2025-09-13 02:27:50 +07:00
parent c68ad76062
commit 1f2440ae0d
3 changed files with 76 additions and 0 deletions

View file

@ -587,6 +587,21 @@ is.all(is.string, '🦄', [], 'unicorns');
//=> false
```
##### .optional(value, predicate)
Returns `true` if `value` is `undefined` or satisfies the given `predicate`.
```js
is.optional(undefined, is.string);
//=> true
is.optional('🦄', is.string);
//=> true
is.optional(123, is.string);
//=> false
```
##### .validDate(value)
Returns `true` if the value is a valid date.
@ -682,6 +697,23 @@ handleMovieRatingApiResponse({rating: 0.87, title: 'The Matrix'});
handleMovieRatingApiResponse({rating: '🦄'});
```
### Optional assertion
Asserts that `value` is `undefined` or satisfies the provided `assertion`.
```ts
import {assert} from '@sindresorhus/is';
assert.optional(undefined, assert.string);
// Passes without throwing
assert.optional('🦄', assert.string);
// Passes without throwing
assert.optional(123, assert.string);
// Throws: Expected value which is `string`, received value of type `number`
```
## Generic type parameters
The type guards and type assertions are aware of [generic type parameters](https://www.typescriptlang.org/docs/handbook/generics.html), such as `Promise<T>` and `Map<Key, Value>`. The default is `unknown` for most cases, since `is` cannot check them at runtime. If the generic type is known at compile-time, either implicitly (inferred) or explicitly (provided), `is` propagates the type so it can be used later.