isguard-ts

A powerful typescript library that helps you build type guards quickly while maintaining type safety.

isguard-ts utilizes the typescript compiler to ensure that its type guards are aligned with the guarded type.

For example, when making a change to your type, isguard-ts will inform you to update your type guard as well.

Installation

``
npm install isguard-ts
`

Table of Contents

+ TypeGuard

+ isType
+ isOptional
+ isMaybe
+ isArray
+ isLiteral
+ isUnion
+ isIntersection
+ isRecord
+ isPartialRecord
+ isIndexRecord
+ isLazy
+ isTuple
+ isEnum
+ isSet
+ isMap
+ isInstanceof
+ isRefine

+ utility type guards
+ generic types
+ recursive types

+ zod

Basic Usage

$3

The most basic type - represents a type guard of T
`typescript
type TypeGuard = (value: unknown) => value is T;
`

$3

Helps you create type guards for types and interfaces

`typescript
type Person = {
name: string;
age: number;
};

const isPerson = isType({
name: isString,
age: isNumber,
});

isPerson({ name: "Hello", age: 6 }); // true
`

> Best Practice
>
> Pass the generic type argument into isType

> Otherwise optional fields might have an unexpected behavior

$3

Helps you create type guards for optional (potentially undefined) types
`typescript
isOptional(isNumber); // or isNumber.optional();
`

$3

Helps you create type guards for nullable (potentially null) types
`typescript
isMaybe(isNumber); // or isNumber.maybe();
`

$3

Helps you create type guards for arrays
`typescript
isArray(isBoolean); // or isBoolean.array();
`

$3

Helps you create type guards for literals
`typescript
const isHello = isLiteral("Hello");
const is12 = isLiteral(12);
`

isLiteral can receive multiple values

`typescript
const directions = ["up", "down", "left", "right"] as const;
type Direction = (typeof directions)[number];

const isDirection = isLiteral(...directions) satisfies TypeGuard;
`

> Best Practice
>
> Use the satisfies keyword on the result of isLiteral when passing multiple values

> This ensures the result is of the expected type

$3

Helps you create type guards for unions

`typescript
type A = { a: number };
type B = { b: string };
type C = A | B;

const isA = isType({ a: isNumber });
const isB = isType({ b: isString });

isUnion(isA, isB) satisfies TypeGuard; // or isA.or(isB);
`

> Best Practice
>
> Use the satisfies keyword on the result of isUnion

> This ensures the result is of the expected type

$3

Helps you create type guards for intersections

`typescript
type A = { a: number };
type B = { b: string };
type C = A & B;

const isA = isType({ a: isNumber });
const isB = isType({ b: isString });

isIntersection(isA, isB) satisfies TypeGuard; // or isA.and(isB);
`

> Best Practice
>
> Use the satisfies keyword on the result of isIntersection

> This ensures the result is of the expected type

$3

Helps you create type guards for records
`typescript
const timeUnits = ["second", "minute", "hour"] as const;
type TimeUnit = (typeof timeUnits)[number];

isRecord(timeUnits, isNumber);
// Record
`

$3

Works just like isRecord but allows for undefined values
`typescript
const timeUnits = ["second", "minute", "hour"] as const;
type TimeUnit = (typeof timeUnits)[number];

isPartialRecord(timeUnits, isNumber);
// Partial>
`

$3

Works just like isRecord but checks only the values and not the keys
`typescript
isIndexRecord(isNumber); // or isNumber.indexRecord();
// Record
`

$3

Helps you lazy load a type guard.
Useful for:
+ Resolving undefined errors due to circular imports
+ Creating type guards for recursive types

`typescript
import { isPerson } from "./some-module";

const isPeople = isLazy(() => isPerson).array();
`

In the example above isPerson, imported from ./some-module, might be undefined when isPeople is being created, due to circular imports. So isPerson.array() would throw an error. isLazy solves this issue by accessing isPerson only when needed.

$3

Helps you create type guards for tuples

`typescript
type Row = [number, string?];

const isRow = isTuple([isNumber, isString.optional()]);

isRow([6, "Hello"]); // true
isRow([6]); // true
isRow(["Hello", "Bye"]); // false
`

> Best Practice
>
> Pass the generic type argument into isTuple

> Otherwise optional fields might have an unexpected behavior

$3

Helps you create type guards for enums
`typescript
enum Direction {
up = 0,
down = 1,
left = 2,
right = 3,
}

const isDirection = isEnum(Direction);

isDirection(Direction.up); // true
isDirection(2); // true
isDirection("hello"); // false
`

$3

Helps you create type guards for sets
`typescript
isSet(isNumber); // or isNumber.set();
// Set
`

$3

Helps you create type guards for maps
`typescript
isMap(isString, isBoolean);
// Map
`

$3

Helps you create type guards for classes
`typescript
abstract class Animal { }
class Dog extends Animal { }

const isAnimal = isInstanceof(Animal);
const isDog = isInstanceof(Dog);
`

$3

Helps you refine existing type guards. Can be used for:
+ Branded types (like Email, PositiveNumber and more)
+ Template literals (like \Bye ${string}\)

`typescript
type Farewell = Bye ${string};

const isFarewell = isRefine(isString, (value: string): value is Farewell => {
return value.startsWith("Bye ");
});
`

> Warning
>
> using isRefine can be unsafe because it let's you implement potentially false logic

> Use at your own risk.

$3

`typescript
const isNumber: TypeGuard;
const isBigint: TypeGuard;
const isString: TypeGuard;
const isBoolean: TypeGuard;
const isSymbol: TypeGuard;
const isFunction: TypeGuard;
const isPropertyKey: TypeGuard;

const isDate: TypeGuard;
const isRegExp: TypeGuard;
const isObject: TypeGuard