@kensio/smartass

TypeScript-first test assertion functions with precise type narrowing via assertion signatures.

Installation

npm install @kensio/smartass

Type narrowing with assertion signatures

See TypeScript assertion functions / assertion signatures

The fluent expect().toBe() interface in Jest and Vitest is readable, but is unable to provide type information to TypeScript and IntelliSense.

This library provides assertion functions with assertion signatures so that you can benefit from the extra type information.

import { assertNonNullable } from "@kensio/smartass";

const user: { name: string } | undefined = getUser();
assertNonNullable(user);
// TypeScript now knows user is neither null nor undefined,
// so no need for ? or ! operators.
const userName = user.name;

import { assertOneOf } from "@kensio/smartass";

const status = getStatus();
assertOneOf(status, ["pending", "active", "completed"]);
// TypeScript now knows status is of type 'pending' | 'active' | 'completed'

Composable type narrowing matchers

As well as the standalone assertion functions, you can also use type narrowing matcher functions to compose an object structure.

import {
  assertObjectMatches,
  arrayIncluding,
  oneOf,
  stringOfLength,
} from "@kensio/smartass";

const user = getUser();

assertObjectMatches(user, {
  role: oneOf(["admin", "editor", "viewer"]),
  tags: arrayIncluding("beta"),
  id: stringOfLength(8),
});

// TypeScript knows:
//   user.role is 'admin' | 'editor' | 'viewer'
//   user.tags is an array with at least one string element
//   user.id is a string of length 8 with safe indexing

This applies the same type narrowing effect as the assertion functions but in a composable object structure.

Assertion functions

• assertArrayEquals
• assertArrayIncludesAll
• assertArrayIncludes
• assertArrayLength
• assertArrayMinLength
• assertArrayNotEmpty
• assertBufferEqual
• assertFalse
• assertIdentical
• assertInstanceOf
• assertMapSize
• assertNonNullable
• assertNumberBetween
• assertNumberToNearest
• assertObjectEquals
• assertObjectHasProperty
• assertObjectMatches
• assertOneOf
• assertSetSize
• assertStringEndsWith
• assertStringIncludes
• assertStringLength
• assertStringNotIncludes
• assertStringStartsWith
• assertThrowsErrorAsync
• assertThrowsErrorLike
• assertThrowsError
• assertTrue
• assertTypeBigInt
• assertTypeBoolean
• assertTypeFunction
• assertTypeNumber
• assertTypeNumeric
• assertTypeObject
• assertTypeString
• assertTypeSymbol
• assertTypeTypedArray
• assertUndefined
• assertUuidV4

Matcher functions

• arrayIncludingAll
• arrayIncluding
• arrayOfLength
• arrayOfMinLength
• nonEmptyArray
• bufferEqualTo
• instanceOf
• mapOfSize
• nonNullable
• numberBetween
• numberToNearest
• objectWithProperty
• oneOf
• setOfSize
• stringEndingWith
• stringIncluding
• stringOfLength
• stringNotIncluding
• stringStartingWith
• typeBigInt
• typeBoolean
• typeFunction
• typeNumber
• typeNumeric
• typeObject
• typeString
• typeSymbol
• typeTypedArray
• uuidV4