Add assertion type guards #97
Conversation
|
Due to typescript's syntax changes/additions in v3.7 (such as |
|
Awaiting #101; should be rebased on top of |
Uses the typescript v3.7 feature `asserts value is T` to create `assert` variants of the `is` type guards. The assertions are used to narrow types at compile time, and to throw `TypeError` at runtime for values which are not of the correct type.
```typescript
import {assert} from '@sindresorhus/is';
assert.string(foo);
```
- Each method in `is` is wrapped and mirrored in `assert`.
- Tests for `is` are duplicated for `assert`.
Notes
- The explicit typing in `interface Assert` is required for typescript to acknowledge the assertions.
- Due to the assertions requiring explicit typing, using ` property for is.assert.string()` (and so on) would require using `namespace is`, which was removed in #78. This also means that `assert` needs to be exported separately.
- Custom descriptions are used to enhance some assertion error messages. The value is not included in the error message.
- Could perhaps use Node.js' fitting `AssertionError` on the server-side, but it would require an `import`.
Fixes #91.
See
- #91
- https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
- microsoft/TypeScript#32695
I think it would be useful to include the value. Maybe something like: ? |
readme.md
Outdated
| @@ -37,6 +38,15 @@ is.number(6); | |||
| //=> true | |||
| ``` | |||
|
|
|||
| Assertions perform the same type checks, but throw errors if the type does not match. | |||
There was a problem hiding this comment.
| Assertions perform the same type checks, but throw errors if the type does not match. | |
| [Assertions](#type-assertions) perform the same type checks, but throw errors if the type does not match. |
readme.md
Outdated
| const {assert} = require('@sindresorhus/is'); | ||
|
|
||
| assert.string(foo); | ||
| //=> foo is known to be a string |
There was a problem hiding this comment.
//=> is usually used to show output, so I think the text should just be a normal comment above.
| regExp: (value: unknown) => asserts value is RegExp; | ||
| date: (value: unknown) => asserts value is Date; | ||
| error: (value: unknown) => asserts value is Error; | ||
| map: <TKey = unknown, TValue = unknown>(value: unknown) => asserts value is Map<TKey, TValue>; |
There was a problem hiding this comment.
| map: <TKey = unknown, TValue = unknown>(value: unknown) => asserts value is Map<TKey, TValue>; | |
| map: <Key = unknown, Value = unknown>(value: unknown) => asserts value is Map<Key, Value>; |
There was a problem hiding this comment.
What do you think about adding generic type parameters to some of the is methods too?
There was a problem hiding this comment.
Would be nice to propagate some more typings for the cases when typescript already knows about them. Separate pull request, right?
There was a problem hiding this comment.
Separate pull request, right?
Yes, would be great :)
source/index.ts
Outdated
| truthy: (value: unknown) => asserts value is unknown; | ||
| falsy: (value: unknown) => asserts value is unknown; | ||
| nan: (value: unknown) => asserts value is unknown; | ||
| primitive: (value: unknown) => asserts value is unknown; |
There was a problem hiding this comment.
| primitive: (value: unknown) => asserts value is unknown; | |
| primitive: (value: unknown) => asserts value is Primitive; |
?
Useful, yes. Mostly avoided because outputting arbitrary (and in this case provably unexpected) input is scary. Can be seen as a security and information leakage issue. Could add something like |
|
Force-pushed to remove code from #101 already in |
👍 |
|
This looks good to me. Thank you 🙌 |
Uses the typescript v3.7 feature
asserts value is Tto createassertvariants of theistype guards. The assertions are used to narrow types at compile time, and to throwTypeErrorat runtime for values which are not of the correct type.isis wrapped and mirrored inassert.isare duplicated forassert.Notes
interface Assertis required for typescript to acknowledge the assertions.property for is.assert.string()(and so on) would require usingnamespace is, which was removed in Stop using TypeScriptnamespace#78. This also means thatassertneeds to be exported separately.AssertionErroron the server-side, but it would require animport.Fixes #91.
See