mediamonks / isntnt

A collection of composable JavaScript runtime type predicates with TypeScript type guard declarations

Isntnt is a collection of composable JavaScript runtime type predicates with TypeScript type guard declarations. Supports generics including union and intersection types.

Generics

above

(floor: number) => (value: unknown) => value is number

const isAboveZero = above(0)

and

<T extends Array<Predicate<any>>>(...predicates: T) => (value: unknown) => value is Predicate<Intersect<Static<T[number]>>>

const isBetween0And21 = and(above(0), below(21))

const isUser = shape({ name: isString })
const hasEmailAddress = at('email', isString)

const isUserWithEmail = and(isUser, hasEmailAddress) // (value: unknown) => { name: string } & { email: string }

array

<T>(predicate: Predicate<T>) => (value: unknown) => value is Array<T>

const isAnyArray = array(isAny) // (value: unknown) => value is Array<any>

at

<T extends PropertyKey, U>(key: T, predicate: Predicate<U>) => (value: unknown) => value is { [P in T]: U }

const isAnyAtFoo = at('foo', isAny) // (value: unknown) => value is { foo: any }

below

(max: number) => (value: unknown) => value is number

const isBelow21 = below(21)

either

<T extends Array<Primitive>>(...literalValues: T) => (value: unknown) => value is T[number]

const isFooOrBar = either('foo', 'bar') // (value: unknown) => value is 'foo' | 'bar'

has

<T extends PropertyKey>(key: T) => (value: unknown) => value is { [P in T]: unknown }

const hasFoo = has('foo') // (value: unknown) => value is { 'foo': unknown }

instance

<T extends Constructor<any, any>>(constructor: T) => (value: unknown) => value is InstanceType<T>

const isInstanceofString = instance(String) // (value: unknown) => value is String

literal

<T extends Primitive>(literalValue: T) => (value: unknown) => value is T

const is42 = literal(42) // (value: unknown) => value is 42

max

<T extends number>(max: number) => (value: unknown) => value is number

const isMax255 = max(255)

maybe

<T>(predicate: Predicate<T>) => (value: unknown) => value is T | null | undefined

const isMaybeString = maybe(isString) // (value: unknown) => value is string | null | undefined

min

(min: number) => (value: unknown) => value is number

const isMin18 = min(18)

noneable

Aliases maybe

nullable

<T>(predicate: Predicate<T>) => (value: unknown) => value is T | null

const isNullableString = nullable(isString) // (value: unknown) => value is string | null

object

<T>(predicate: Predicate<T>) => (value: unknown) => value is Record<any, T>

const isEnum = object(isUint) // (value: unknown) => value is Record<any, number>

optional

<T>(predicate: Predicate<T>) => (value: unknown) => value is T | undefined

const isOptionalString = optional(isString) // (value: unknown) => value is string | undefined

or

<T extends Array<Predicate<any>>>(...predicates: T) => (value: unknown) => value is Static<T[number]>

const isStringOrNumber = or(isString, isNumber) // (value: unknown) => value is string | number

record

<T extends PropertyKey, U>(keyPredicate: Predicate<T>, valuePredicate: Predicate<U>) => (value: unknown) => value is Record<T, U>

const isDictionary = record(isString, isInt) // (value: unknown) => value is Record<string, number>

shape

<T extends Record<PropertyKey, Predicate<any>>>(predicates: T) => (value: unknown) => value is { [P in keyof T]: Static<T[P]> }

Note: Actual signature also considers optional members ({ name?: T }) in its Predicate type

const isCoordinate = shape({ x: isNumber, y: isNumber }) // (value: unknown) => value is { x: number, y: number }

test

(expression: RegExp) => (value: unknown) => value is string

const isSlug = test(/^[\w-]+$/)

tuple

<T extends Array<any>>(...predicates: { [K in keyof T]: Predicate<T[K]> }) => (value: unknown) => value is T

const isPoint = tuple(isNumber, isNumber) // (value: unknown) => value is [number, number]

Predicates

isAny

(value: unknown) => value is any

Always returns true.

isAny(value)

isArray

(value: unknown) => value is Array<unknown>

isArray(value)

isArrayLike

(value: unknown) => value is Record<number, unknown>

isArrayLike(value)

isBigInt

(value: unknown) => value is bigint

isBigInt(value)

isBoolean

(value: unknown) => value is boolean

isBoolean(value)

isDate

(value: unknown) => value is Date

isDate(value)

isDictionary

(value: unknown) => value is Record<any, string>

isDictionary(value)

isFalse

(value: unknown) => value is false

isFalse(value)

isFunction

(value: unknown) => value is Function

isFunction(value)

isInt

(value: unknown) => value is number

isInt(value)

isInt8

(value: unknown) => value is number

isInt8(value)

isInt16

(value: unknown) => value is number

isInt16(value)

isInt32

(value: unknown) => value is number

isInt32(value)

isLength

(value: unknown) => value is number

isLength(value)

isMap

(value: unknown) => value is Map<any, unknown>

isMap(value)

isNegative

(value: unknown) => value is number

isNegative(value)

isNever

(value: unknown) => value is never

Always returns false;

isNever(value)

isNone

(value: unknown) => value is null | undefined

isNone(value)

isNull

(value: unknown) => value is null

isNull(value)

isNumber

(value: unknown) => value is number

isNumber(value)

isObject

(value: unknown) => value is object

isObject(value)

isObjectLike

(value: unknown) => value is ObjectLike

isObjectLike(value)

isPlainObject

(value: unknown) => value is {}

isPlainObject(value)

isPositive

(value: unknown) => value is number

isPositive(value)

isPrimitive

(value: unknown) => value is Primitive

isPrimitive(value)

isRegExp

(value: unknown) => value is RegExp

isRegExp(value)

isSerializable

(value: unknown) => value is Serializable

isSerializable(value)

isSerializableArray

(value: unknown) => value is Array<Serializable>

isSerializableArray(value)

isSerializableNumber

(value: unknown) => value is number

isSerializableNumber(value)

isSerializableObject

(value: unknown) => value is Record<string, Serializable>

isSerializableObject(value)

isSerializablePrimitive

(value: unknown) => value is SerializablePrimitive

isSerializablePrimitive(value)

isSet

(value: unknown) => value is Set<unknown>

isSet(value)

isSome

(value: unknown) => value is Some

isSome(value)

isString

(value: unknown) => value is string

isString(value)

isSymbol

(value: unknown) => value is symbol

isSymbol(value)

isTrue

(value: unknown) => value is true

isTrue(value)

isUint

(value: unknown) => value is number

isUint(value)

isUint8

(value: unknown) => value is number

isUint8(value)

isUint16

(value: unknown) => value is number

isUint16(value)

isUint32

(value: unknown) => value is number

isUint32(value)

isUndefined

(value: unknown) => value is undefined

isUndefined(value)

isWeakMap

(value: unknown) => value is WeakMap<any, unknown>

isWeakMap(value)

isWithLength

(value: unknown) => value is { length: number }

isWithLength(value)

Types

Intersect

Intersect<A | B> // A & B

Maybe

Maybe<T> // T | null | undefined

type MaybeString = Maybe<string> // string | null | undefined

None

None // null | undefined

Nullable

Nullable<T> // T | null

type NullableString = Nullable<string> // string | null

Optional

Optional<T> // T | undefined

type OptionalString = Optional<string> // string | undefined

Predicate

Predicate<T> // (value: unknown, ...rest: Array<unknown>) => value is T

Primitive

Primitive // null | undefined | boolean | number | string | symbol | bigint

Serializable

Serializable // SerializableArray | SerializableObject | SerializablePrimitive

SerializableArray

SerializableArray // Array<Serializable>

SerializableObject

SerializableObject // Partial<{ [key: string]: Serializable }>

SerializablePrimitive

SerializablePrimitive // null | boolean | number | string

Some

Some // Function | boolean | bigint | number | string | symbol | object
Some<T> // Exclude<T, undefined | null>

// Make sure `T` is not `null` or `undefined`
type Option<T extends Some, E extends Error> = T | E

// Remove `null` or `undefined` from a type
type MaybeString = Optional<string> // string | null | undefined
type SomeString = Some<MaybeString> // string

Static

Static<Predicate<T>> // T

type True = Static<typeof isTrue> // true

isntnt's Issues

Add install guide on readme

As the title suggest might be a good idea to add the classic npm install -D isntn in the main readme file.

Tree shaking isn't working correctly

The package now supports esm but tree shaking doesn't work yet when used in webpack. A single import of a predicate will import everything from the package.

I didn't understand why so I started searching and found this: https://webpack.js.org/guides/tree-shaking/
I also looked at a package like lodash-es and found that they have sideEffects: false in their package.json as stated in the guide. The lodash package does proper treeshaking as far as I could see because of that sideEffects property. As a test I added the property to this package as well and it seemed to work the included size went from 13kb to 1kb in my case. I don't know the complete package to know if there are actual side effects. If not then it's just a case of adding that property to the package.json.

Consider making predicate values generic

Currently the value argument for predicates is hardcoded to be unknown.
This is fine for simple use cases like using predicates in if statements example ⬇️

const foo: null | number = null;
if(isSome(foo)) {
   foo; // now it's only of type 'number'
}

However, using predicates in methods and functions which use generics, TS can't correctly infer the type from the predicate.

const foo = [null, 1, null, 2, null]; // (number | null)[]

const cleanFoo = foo.filter(isSome); // still (number | null)[]

From what I can gather, making the value argument a generic fixes the above

function isSome<T>(value: T): value is Some<T> {
return value != null && value === value;
}

const foo = [null, 1, null, 2, null]; // (number | null)[]

const cleanFoo = foo.filter(isSome); // now correctly typed as number[]

TS playground

This example is only for isSome, but I imagine that this improvement could be added to most if not all predicates.