npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

tsguarder

v1.0.1

Published

A simple tool for creating TypeScript guards including assertions

Downloads

44

Readme

tsguarder

A quite simple tool for creating TypeScript guards including assertions with several built-in guards for runtime type checking. A type guard can be used to check the runtime type of a variable and narrow its type accordingly.

Read more about guards and assertions from the official TypeScript documentation.

Installation

npm install tsguarder

Usage

Create a type guard:

import { createTypeGuard, TypeGuard } from "tsguarder";

const isPositiveNumber: TypeGuard<number> = createTypeGuard(
  "must be a positive number", // optional
  (value: unknown): value is number => {
    return typeof value === "number" && value > 0;
  }
);

Use as a type guard:

function doSomething(value: number | string) {
  if (isPositiveNumber(value)) {
    // do something with a number
    const result = value.toFixed(2);
  }
  // do something with a number or a string
}

Use as an assertion:

function calculateFactorial(num: number) {
  // the second argument is optional
  isPositiveNumber.assert(num, "num argument");
}

calculateFactorial(100); // works
calculateFactorial("This is not a number"); // throws an error

console.log("This will not be printed");

If the type assertion fails, meaning the variable's type is not what was expected, TypeScript throws an error with the value name and the message provided in the guard.

TypeError: num argument: must be a positive number

An Explicit Type Annotation

⚠️ Note that we have used TypeGuard as the type annotation for the guard. This is because TypeScript requires an explicit type annotation to enable the use of type assertions. It concerns only assertions.

This does not work:

import { createTypeGuard } from "tsguarder";

const isString = createTypeGuard(
    (value): value is string =>  typeof value === "string";
);

// ⛔️ TypeScript error:
// Assertions require every name in the call target to be
// declared with an explicit type annotation.ts(2775)
isString.assert('Hello, World!')

Read more about assertions in the TypeScript documentation.

Built-in guards

The tool comes with several built-in guards:

isString

Equivalent to typeof value === "string"

isNumber

Equivalent to typeof value === "number"

isBoolean

Equivalent to typeof value === "boolean"

isSymbol

Equivalent to typeof value === "symbol"

isUndefined

Equivalent to typeof value === "undefined"

isNull

Equivalent to value === null

isBigInt

Equivalent to typeof value === "bigint"

isFunction

Equivalent to typeof value === "function"

isObject

Equivalent to typeof value === "object"

isArray

Equivalent to Array.isArray(value)

isRecord

Equivalent to typeof value === "object" && value !== null && !Array.isArray(value)

License

MIT